wunderbar

Wunderbar: простые приложения HTML5

Wunderbar позволяет легко создавать корректные HTML5, правильно сформированные XHTML, Unicode (utf-8), читаемые приложения с постоянными отступами.

Wunderbar был вдохновлен Builder Джима Вейриха и предоставляет синтаксис идентификатора элемента и идентификатора класса и основан на реализации Markaby.

Поддержка JSON в Wunderbar основана на jbuilder Дэвида Хайнемайера Ханссона.

Учебник находится в разработке.

Дополнительный функционал обеспечивается расширениями.

Обзор

Идея Wunderbar заключается в том, что выходные данные различных типов обычно формируются путем добавления либо серии пар ключ/значение, либо простых значений, и эти операции должны быть оптимизированы. Добавление пары ключ/значение осуществляется с помощью:

 _key value

... и добавление простого значения выполняется следующим образом:

 _ value

В HTML ключ/значение используется для узлов элементов, а простые значения используются для текстовых узлов. В JSON ключ/значение используется для хешей, а простые значения — для массивов. Для текста простые значения выводятся через puts, а пары ключ/значение не используются.

Вложение осуществляется с помощью блоков.

Метод подчеркивания, если ему не переданы аргументы, возвращает объект, который можно использовать для выполнения ряда специальных функций. Некоторые из этих функций уникальны для метода вывода. Другие методы, такие как методы ведения журнала, распространены.

Метод подчеркивания при передаче нескольких аргументов или комбинации аргументов и блока может выполнять другие общие функции, в зависимости от типов переданных аргументов.

Вопросительный знак, восклицательный знак и суффиксы подчеркивания в имени метода могут изменить результаты.

Быстрый старт (HTML)

Простой элемент:

 _br

Вложенные элементы:

 _div do
  _hr
end

Элемент с текстом:

 _h1 "My weblog"

Элемент с атрибутами:

 _img src: '/img/logo.jpg', alt: 'site logo'

Элемент с текстом и атрибутами:

 _a 'search', href: 'http://google.com'

Элемент с логическими атрибутами:

 _input 'Cheese', type: 'checkbox', name: 'cheese', checked: true

Элемент с логическими атрибутами (альтернативная форма):

 _input 'Cheese', :checked, type: 'checkbox', name: 'cheese'

Элемент с необязательными (опущенными) атрибутами:

 _tr class: nil

Текст (символы разметки экранированы):

 _ "<3"

Текст (может содержать разметку):

 _{"<em>hello</em>!!!"}

Импорт HTML/XML:

 _[Nokogiri::XML "<em>hello</em>"]

Смешанное содержимое (с автоматическим интервалом):

 _p do
  _ 'It is a'
  _em 'very'
  _ 'nice day.'
end

Смешанный контент (контролируется пространством):

 _p! do
  _ 'Source is on '
  _a 'github', href: 'https://github.com/'
  _ '.'
end

Вставьте пустые строки между строками в полученном HTML:

 _tbody do
  _tr_ do
    _td 1
  end
  _tr_ do
    _td 2
  end
  _tr_ do
    _td 3
  end
end

Захват исключений:

 _body? do
  raise NotImplementedError.new('page')
end

Ярлык атрибута класса (эквивалент class="front"):

 _div.front do
end

Ярлык атрибутов идентификатора (эквивалент id="search"):

 _div.search! do
end

Полные списки/строки можно определить с помощью массивов:

 _ul %w(apple orange pear)
_ol %w(apple orange pear)
_table do
  _tr %w(apple orange pear)
end

Произвольная итерация может быть выполнена над Enumerables:

 _dl.colors red: '#F00', green: '#0F0', blue: '#00F' do |color, hex|
  _dt color.to_s
  _dd hex
end

Базовый интерфейс

Типичная основная программа выдает один или несколько выходных данных в формате HTML, JSON или простого текста. Это достигается путем предоставления одного или нескольких из следующих действий:

 _html do
  code
end

_xhtml do
  code
end

_json do
  code
end

_text do
  code
end

_websocket do
  code
end

В каждом может быть размещен произвольный код Ruby. Параметры формы доступны как переменные экземпляра (например, @name ). Значения среды хоста (CGI, Rack, Sinatra) доступны как методы объекта _ : например, _.headers (CGI), _.set_cookie (Rack), _.redirect (Sinatra).

Чтобы добавить к полученному выводу, используйте методы _ , описанные ниже. Примеры приложений приведены в руководстве.

Методы, предоставляемые Wunderbar.html

Вызов методов, которые начинаются с символа нижней строки Юникода ("_"), создаст HTML-тег. Как и в случае с конструктором, на котором основана эта библиотека, эти теги могут иметь текстовое содержимое и атрибуты. Теги также могут быть вложенными. Логику можно свободно смешивать.

Wunderbar знает, какие HTML-теги необходимо явно закрывать отдельными закрывающими тегами (пример: textarea ), а какие никогда не следует закрывать отдельными закрывающими тегами (пример: br ). Он также заботится о цитировании HTML и экранировании аргументов и текста.

Суффиксы после имени тега изменят обработку.

• ! : отключает всю специальную обработку, включая отступы.
• ? : добавляет код для устранения исключений и создания обратных трассировок.
• _ : добавляет дополнительные пустые строки между этим тегом и братьями и сестрами.

Метод « _ » служит нескольким целям. Вызов его с одним аргументом вставляет разметку с соблюдением отступов. Вставка разметки без учета отступов осуществляется с помощью « _ << text ». Определен ряд других удобных методов:

• _ : вставить текст с отступом, соответствующим текущему выводу
• _! : вставить текст без отступов
• _.post? -- это было вызвано через HTTP POST?
• _.system — вызывает команду оболочки, захватывает stdin, stdout и stderr.
• _.submit — запускает команду (или блок) как процесс демона
• _.xhtml? -- вывод в формате XHTML?

Метод _.system принимает необязательный хеш в качестве последнего параметра. Это можно использовать для предоставления настроек базовому методу Process.spawn. Например: ._system('pwd',{ system_opts: { chdir: dir } , system_env: { 'FOO' => 'BAR' } }) Обратите внимание, что имена переменных среды должны быть представлены в виде строк, а не символов. Дополнительные параметры, которые можно использовать с _.system включают:

• :tag — HTML-тег, который будет использоваться для ввода/вывода; по умолчанию pre
• :bundlelines — обрабатывать ли все строки для данного типа вывода (stderr, stdout и т. д.) как часть одного тега. Если не указано, по умолчанию используется значение true для тегов pre и false в противном случае. Если false , каждая строка вывода обрабатывается отдельно.

Таким способом можно получить доступ ко всем методам, определенным сборщиком (обычно они заканчиваются восклицательным знаком), а также ко всем методам модуля Wunderbar. Примеры:

• _.tag! :foo : вставить элементы, имя которых может быть динамическим.
• _.comment! "text" : добавить комментарий
• _.error 'Log message' : запись сообщения в журнал сервера

Подчеркивания в именах элементов и атрибутов преобразуются в тире. Чтобы отключить это поведение, выразите имена атрибутов в виде строк и используйте _.tag! метод для имен элементов.

XHTML отличается от HTML экранированием встроенных стилей и элементов сценария. XHTML также вернется к выводу HTML, если пользовательский агент не укажет, что он поддерживает XHTML через заголовок HTTP Accept.

Помимо стандартной обработки элементов, текста и атрибутов, Wunderdar определяет дополнительную обработку для следующего:

• _head : вставить мета-кодировку utf-8
• _svg : вставить пространство имен SVG.
• _math : вставить математическое пространство имен
• _coffeescript : преобразовать Coffeescript в JS и вставить тег сценария.

Обратите внимание, что добавление восклицательного знака в конец имени тега отключает такое поведение.

Если одним из атрибутов, переданных в объявлении _html , является :_width , будет предпринята попытка перекомпоновать текст, чтобы не превысить эту ширину строки. Этого не будет сделано, если это повлияет на то, что на самом деле отображается.

Если ни один из дочерних элементов элемента html не является ни head , ни body , то эти теги будут созданы для вас, а соответствующие дочерние элементы будут перемещены в соответствующий раздел. Если тело содержит элемент h1 , а head не содержит title , элемент заголовка будет создан на основе текста, предоставленного первому элементу h1 .

Методы, предоставляемые Wunderbar.json

Обычными операциями являются возврат хэша или массива значений. Хэши — это серия пар имя/значение, а массивы — это серия значений.

 Wunderbar . json do
  _content format_content ( @message . content )
  _ @message , :created_at , :updated_at 

  _author do
    _name @message . creator . name . familiar
    _email_address @message . creator . email_address_with_name
    _url url_for ( @message . creator , format : :json )
  end

  if current_user . admin?
    _visitors calculate_visitors ( @message )
  end

  _comments @message . comments , :content , :created_at
  
  _attachments @message . attachments do | attachment |
    _filename attachment . filename
    _url url_for ( attachment )
  end
end

Вызов методов, которые начинаются с символа нижней строки Юникода ("_"), добавит к этому хешу пару ключ/значение. Хэши также могут быть вложенными. Логику можно свободно смешивать.

Метод « _ » служит нескольким целям.

• вызов его с несколькими аргументами приведет к тому, что первый аргумент будет рассматриваться как объект, а оставшаяся часть — как извлекаемые атрибуты.

  • Пример: _ File.stat('foo'), :mtime, :size, :mode

• вызов его с одним объектом Enumerable и блоком приведет к возврату массива на основе сопоставления каждого возражения из перечисления с блоком

  • Пример: _([1,2,3]) {|n| n*n}

• массивы также можно создавать с помощью метода _ :

    _ 1
    _ 2
  

Метод _ возвращает прокси создаваемого объекта. Это часто бывает удобно при вызове без аргументов. Примеры:

    _.sort!
    _['foo'] = 'bar'

Методы, предоставляемые Wunderbar.text

Добавление к выходному потоку выполняется с помощью метода _ , который эквивалентен методу puts . Метод _ возвращает объект, который проксирует выходной поток и обеспечивает доступ к другим полезным методам, например:

    _.print 'foo'
    _.printf "Hello %s!n", 'world'

Методы, предоставляемые Wunderbar.websocket

Для поддержки WebSocket необходимо установить em-websocket .

Веб-сокет — это двунаправленный канал. _.send или _.push можно использовать для отправки произвольных строк. Чаще всего можно использовать все методы массива JSON, описанные выше, важное отличие состоит в том, что отдельные записи отправляются индивидуально и по мере их создания.

_.recv или _.pop можно использовать для получения произвольных строк. Чаще всего _.subscribe используется для регистрации блока, который используется в качестве обратного вызова.

_.system выполнит произвольную команду. Строки вывода передаются через веб-сокет по мере их получения в виде хэшей в формате JSON с двумя значениями: type — одно из stdin , stdout или stderr ; и line , содержащая саму строку. Если команда представляет собой массив, элементы массива будут экранированы как аргументы команды оболочки. Вложенные массивы можно использовать, чтобы скрыть элементы от вывода команды на стандартный ввод. Нулевые значения опускаются.

Параметры _websocket предоставляются в виде хеша:

• :port выберет номер порта, по умолчанию вам будет выбран доступный порт.
• Для :sync установлено значение false , что приведет к запуску сервера WebSocket как процесса демона. По умолчанию это значение true при запуске из командной строки и значение false при запуске как CGI.
• buffer_limit ограничит количество записей, сохраняемых и отправляемых новым клиентам по открытым запросам. По умолчанию — 1 . Значение 0 отключит буферизацию. Значение nil приведет к неограниченной буферизации. Примечание. Буферизация фактически не ограничена до тех пор, пока не подключится первый клиент.

Безопасно по умолчанию

Wunderbar корректно экранирует весь вывод HTML и JSON, устраняя проблемы внедрения HTML или JavaScript. Сюда входят вызовы _ для прямой вставки текста. Если ранее не требовалось nokogiri (см. дополнительные зависимости ниже), вызовы вставки разметки ( _{...} ) будут экранировать разметку.

Глобальные значения предоставлены

• $USER — идентификатор пользователя хоста
• $PASSWORD — пароль хоста (если переданы CGI и HTTP_AUTHORIZATION)
• $HOME — Домашний каталог
• $SERVER — Имя сервера
• $HOME — домашний каталог пользователя.
• $HOST — хост сервера

Кроме того, установлены следующие переменные среды, если они еще не установлены:

• HOME
• HTTP_HOST
• LANG
• REMOTE_USER

Наконец, по умолчанию для внешней и внутренней кодировки установлено значение UTF-8.

Ведение журнала

• _.debug : сообщения отладки
• _.info : информационные сообщения
• _.warn : предупреждающие сообщения
• _.error : сообщения об ошибках
• _.fatal : сообщения о фатальных ошибках.
• _.log_level =: установить уровень ведения журнала (по умолчанию: :warn )
• _.default_log_level =: установить, но не переопределять уровень журнала
• _.logger : вернуть экземпляр Logger

Параметры командной строки

При запуске из командной строки можно указать пары имя=значение CGI. Кроме того, поддерживаются следующие параметры:

• --get : ожидается вывод HTML (HTTP GET)
• --post : ожидается вывод HTML (HTTP POST)
• --json : ожидается вывод JSON (XML HTTP-запрос)
• --html : принудительно вывести HTML
• --prompt или --offline : запросить пары ключ/значение с помощью стандартного ввода
• --debug , --info , --warn , --error , --fatal : установить уровень журнала
• --install= путь: создать сценарий-оболочку, вызываемый suexec
• --rescue или --backtrace заставляют скрипт-оболочку фиксировать ошибки

Дополнительные зависимости

Следующие драгоценные камни необходимы в зависимости от того, какие функции вы используете:

• em-websocket требуется для wunderbar/websocket
• kramdown требуется для wunderbar/markdown
• ruby2js добавляет поддержку скриптов, написанных в виде блоков.
• Для wunderbar/opal требуется sourcify

Следующие драгоценные камни необходимы для одноимённых расширений:

• coderay — подсветка синтаксиса
• opal — компилятор Ruby в JavaScript
• rack — интерфейс веб-сервера
• sinatra — DSL для создания веб-приложений

Следующие драгоценные камни, если они установлены, будут давать более чистый и красивый результат:

• nokogiri очищает фрагменты HTML, вставленные с помощью << и _{} .
• nokogumbo также очищает фрагменты HTML, вставленные с помощью << и _{} . Если этот драгоценный камень доступен, он будет предпочтительнее прямого использования nokogiri .
• escape более красивого цитирования system команд

Связанные усилия

• Строитель
• JBuilder
• Маркабы
• Нокогири::HTML::Builder
• Тагз