wunderbar
1.0.0
Wunderbar facilita la producción de aplicaciones HTML5 válidas, XHTML bien formadas, Unicode (utf-8), con sangría consistente y legibles.
Wunderbar se inspiró en el Builder de Jim Weirich y proporciona la sintaxis de identificación de elemento y de identificación de clase y se basa en la implementación de Markaby.
El soporte JSON de Wunderbar está inspirado en el jbuilder de David Heinemeier Hansson.
Se está desarrollando un tutorial.
Las extensiones proporcionan funcionalidad adicional.
La premisa de Wunderbar es que la salida de varios tipos generalmente se forma agregando una serie de pares clave/valor o valores simples, y esas operaciones deben optimizarse. Agregar un par clave/valor se realiza mediante:
_key value
... y añadiendo un valor simple se hace así:
_ value
Para HTML, la clave/valor se usa para los nodos de elementos y los valores simples se usan para los nodos de texto. Para JSON, la clave/valor se usa para Hashes y los valores simples se usan para matrices. Para el texto, los valores simples se generan mediante opciones de venta y no se utilizan pares clave/valor.
El anidamiento se realiza mediante bloques.
El método de guión bajo, cuando no se le pasan argumentos, devuelve un objeto que puede usarse para realizar una serie de funciones especiales. Algunas de esas funciones son exclusivas del método de salida. Otros, como los métodos de registro, son comunes.
El método de guión bajo, cuando se pasan múltiples argumentos o una combinación de argumentos y un bloque, puede realizar otras funciones comunes, dependiendo de los tipos de argumentos pasados.
Los sufijos de signos de interrogación, exclamación y guiones bajos en el nombre del método pueden modificar los resultados.
Elemento sencillo:
_br
Elementos anidados:
_div do
_hr
end
Elemento con texto:
_h1 "My weblog"
Elemento con atributos:
_img src: '/img/logo.jpg', alt: 'site logo'
Elemento con texto y atributos:
_a 'search', href: 'http://google.com'
Elemento con atributos booleanos:
_input 'Cheese', type: 'checkbox', name: 'cheese', checked: true
Elemento con atributos booleanos (forma alternativa):
_input 'Cheese', :checked, type: 'checkbox', name: 'cheese'
Elemento con atributos opcionales (omitidos):
_tr class: nil
Texto (los caracteres de marcado están en formato de escape):
_ "<3"
Texto (puede contener marcas):
_{"<em>hello</em>!!!"}
Importación de HTML/XML:
_[Nokogiri::XML "<em>hello</em>"]
Contenido mixto (espaciado automáticamente):
_p do
_ 'It is a'
_em 'very'
_ 'nice day.'
end
Contenido mixto (espacio controlado):
_p! do
_ 'Source is on '
_a 'github', href: 'https://github.com/'
_ '.'
end
Inserte líneas en blanco entre filas en el HTML producido:
_tbody do
_tr_ do
_td 1
end
_tr_ do
_td 2
end
_tr_ do
_td 3
end
end
Excepciones de captura:
_body? do
raise NotImplementedError.new('page')
end
Atajo de atributo de clase (equivalente a class="front"):
_div.front do
end
Acceso directo a atributos de ID (equivalente a id="buscar"):
_div.search! do
end
Se pueden definir listas/filas completas utilizando matrices:
_ul %w(apple orange pear)
_ol %w(apple orange pear)
_table do
_tr %w(apple orange pear)
end
Se puede realizar iteración arbitraria sobre Enumerables:
_dl.colors red: '#F00', green: '#0F0', blue: '#00F' do |color, hex|
_dt color.to_s
_dd hex
end
Un programa principal típico produce uno o más resultados HTML, JSON o texto sin formato. Esto se logra proporcionando uno o más de los siguientes:
_html do
code
end
_xhtml do
code
end
_json do
code
end
_text do
code
end
_websocket do
code
end
Se puede colocar código Ruby arbitrario en cada uno. Los parámetros del formulario están disponibles como variables de instancia (por ejemplo, @name ). Se puede acceder a los valores del entorno host (CGI, Rack, Sinatra) como métodos del objeto _ : por ejemplo _.headers (CGI), _.set_cookie (Rack), _.redirect (Sinatra).
Para agregar al resultado producido, utilice los métodos _ que se describen a continuación. Las aplicaciones de ejemplo están en el tutorial.
La invocación de métodos que comienzan con un carácter de línea baja Unicode ("_") generará una etiqueta HTML. Al igual que con el constructor, en el que se basa esta biblioteca, estas etiquetas pueden tener atributos y contenido de texto. Las etiquetas también se pueden anidar. La lógica se puede mezclar libremente.
Wunderbar sabe qué etiquetas HTML deben cerrarse explícitamente con etiquetas finales separadas (ejemplo: textarea ) y cuáles nunca deben cerrarse con etiquetas finales separadas (ejemplo: br ). También se encarga de citar HTML y escapar de argumentos y texto.
Los sufijos después del nombre de la etiqueta modificarán el procesamiento.
! : desactiva todo el procesamiento especial, incluida la sangría? : agrega código para rescatar excepciones y producir rastreos_ : agrega líneas en blanco adicionales entre esta etiqueta y los hermanos El método " _ " sirve para varios propósitos. Llamarlo con un solo argumento inserta marcado, respetando la sangría. La inserción de marcas sin tener en cuenta la sangría se realiza utilizando " _ << text ". Se definen otros métodos de conveniencia:
_ : inserta texto con sangría que coincida con la salida actual_! : insertar texto sin sangría_.post? - ¿Se invocó esto a través de HTTP POST?_.system : invoca un comando de shell, captura stdin, stdout y stderr._.submit : ejecuta un comando (o un bloque) como un proceso demoníaco._.xhtml? - salida como XHTML? El método _.system toma un hash opcional como último parámetro. Esto se puede utilizar para proporcionar configuraciones para el método Process.spawn subyacente. Por ejemplo: ._system('pwd',{ system_opts: { chdir: dir } , system_env: { 'FOO' => 'BAR' } }) Tenga en cuenta que los nombres de las variables de entorno deben proporcionarse como cadenas, no como símbolos. Las opciones adicionales que se pueden utilizar con _.system incluyen:
:tag : la etiqueta HTML que se utilizará para la entrada/salida; por defecto es pre:bundlelines : si se procesan todas las líneas para un tipo de salida determinado (stderr, stdout, etc.) como parte de una sola etiqueta. Si no se especifica, el valor predeterminado es true para las etiquetas pre y false en caso contrario. Si es false , cada línea de salida se procesa por separado.De esta manera se puede acceder a todos los métodos definidos por el constructor (normalmente terminan en un signo de exclamación) y a todos los métodos del módulo Wunderbar. Ejemplos:
_.tag! :foo : inserta elementos donde el nombre puede ser dinámico_.comment! "text" : añade un comentario_.error 'Log message' : escribe un mensaje en el registro del servidor Los guiones bajos en los nombres de elementos y atributos se convierten en guiones. Para deshabilitar este comportamiento, exprese los nombres de los atributos como cadenas y use _.tag! método para nombres de elementos.
XHTML se diferencia de HTML en el escape de elementos de script y estilo en línea. XHTML también recurrirá a la salida HTML a menos que el agente de usuario indique que admite XHTML a través del encabezado HTTP Accept.
Además del procesamiento predeterminado de elementos, texto y atributos, Wunderdar define un procesamiento adicional para lo siguiente:
_head : insertar meta juego de caracteres utf-8_svg : insertar espacio de nombres svg_math : inserta un espacio de nombres matemático_coffeescript : convierte coffeescript a JS e inserta la etiqueta scriptTenga en cuenta que agregar un signo de exclamación al final del nombre de la etiqueta desactiva este comportamiento.
Si uno de los atributos pasados en la declaración _html es :_width , se intentará redistribuir el texto para no exceder este ancho de línea. Esto no se hará si afecta lo que realmente se muestra.
Si ninguno de los elementos secundarios del elemento html es head o body , estas etiquetas se crearán automáticamente y los elementos secundarios relevantes se moverán a la sección correspondiente. Si el cuerpo contiene un elemento h1 y el head no contiene un title , se creará un elemento de título basado en el texto proporcionado al primer elemento h1 .
Las operaciones comunes son devolver un Hash o una matriz de valores. Los hashes son una serie de pares de nombre/valor y las matrices son una serie de valores.
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
endLa invocación de métodos que comienzan con un carácter de línea baja Unicode ("_") agregará un par clave/valor a ese hash. Los hashes también se pueden anidar. La lógica se puede mezclar libremente.
El método " _ " sirve para varios propósitos.
llamarlo con múltiples argumentos hará que el primer argumento se trate como el objeto y el resto como los atributos que se extraerán.
_ File.stat('foo'), :mtime, :size, :modellamarlo con un único objeto Enumerable y un bloque hará que se devuelva una matriz basada en el mapeo de cada objeción de la enumeración contra el bloque
_([1,2,3]) {|n| n*n} Las matrices también se pueden construir usando el método _ :
_ 1
_ 2
El método _ devuelve un proxy al objeto que se está construyendo. Esto suele ser útil cuando se llama sin argumentos. Ejemplos:
_.sort!
_['foo'] = 'bar'
La adición al flujo de salida se realiza mediante el método _ , que equivale a puts . El método _ devuelve un objeto que representa el flujo de salida, lo que proporciona acceso a otros métodos útiles, por ejemplo:
_.print 'foo'
_.printf "Hello %s!n", 'world'
La compatibilidad con WebSocket requiere la instalación de em-websocket .
Un web socket es un canal bidireccional. _.send o _.push se pueden utilizar para enviar cadenas arbitrarias. Más comúnmente, se pueden usar todos los métodos de matriz JSON descritos anteriormente, la diferencia importante es que las entradas individuales se envían individualmente y a medida que se producen.
_.recv o _.pop se pueden utilizar para recibir cadenas arbitrarias. Más comúnmente, _.subscribe se usa para registrar un bloque que se usa como devolución de llamada.
_.system ejecutará un comando arbitrario. Las líneas de salida se envían a través del websocket a medida que se reciben como hashes codificados en JSON con dos valores: type es uno de stdin , stdout o stderr ; y line que contiene la línea misma. Si el comando es una matriz, los elementos de la matriz se escaparán como argumentos del comando Shell. Se pueden usar matrices anidadas para ocultar elementos del eco del comando en la entrada estándar. Se omiten los valores nulos.
Las opciones para _websocket se proporcionan como hash:
:port elegirá un número de puerto, siendo el valor predeterminado que se elija uno disponible para usted.:sync establecido en false hará que el servidor WebSocket se ejecute como un proceso demonio. El valor predeterminado es true cuando se ejecuta desde la línea de comando y false cuando se ejecuta como CGI.buffer_limit limitará la cantidad de entradas retenidas y enviadas a nuevos clientes en solicitudes abiertas. El valor predeterminado es 1 . Un valor de cero deshabilitará el almacenamiento en búfer. Un valor de nil dará como resultado un almacenamiento en búfer ilimitado. Nota: el almacenamiento en búfer es efectivamente ilimitado hasta que se conecte el primer cliente. Wunderbar escapará correctamente de toda la salida HTML y JSON, eliminando los problemas de inyección de HTML o JavaScript. Esto incluye llamadas a _ para insertar texto directamente. A menos que previamente se requiriera nokogiri (consulte las dependencias opcionales a continuación), las llamadas para insertar marcado ( _{...} ) escaparán del marcado.
$USER - ID de usuario del host$PASSWORD - Contraseña del host (si se pasa CGI y HTTP_AUTHORIZATION)$HOME - Directorio de inicio$SERVER - Nombre del servidor$HOME - directorio de inicio del usuario$HOST - host del servidorAdemás, se establecen las siguientes variables de entorno si aún no lo están:
HOMEHTTP_HOSTLANGREMOTE_USERFinalmente, las codificaciones externas e internas predeterminadas están configuradas en UTF-8.
_.debug : mensajes de depuración_.info : mensajes informativos_.warn : mensajes de advertencia_.error : mensajes de error_.fatal : mensajes de error fatales_.log_level =: establecer el nivel de registro (predeterminado: :warn )_.default_log_level =: establece, pero no anula, el nivel de registro_.logger : devuelve la instancia de Logger Cuando se ejecuta desde la línea de comando, se pueden especificar pares de nombre=valor CGI. Además, se admiten las siguientes opciones:
--get : Se espera salida HTML (HTTP GET)--post : Se espera salida HTML (HTTP POST)--json : se espera salida JSON (solicitud HTTP XML)--html : fuerza la salida HTML--prompt o --offline : solicita pares clave/valor usando stdin--debug , --info , --warn , --error , --fatal : establecer nivel de registro--install= ruta: produce un script contenedor invocable por suexec--rescue o --backtrace hacen que el script contenedor capture errores Se necesitan las siguientes gemas según las funciones que utilice:
wunderbar/websocket requiere em-websocketkramdown es requerido por wunderbar/markdownruby2js agrega soporte para scripts escritos como bloqueswunderbar/opal requiere sourcifyLas siguientes gemas son requeridas por extensiones del mismo nombre:
coderay - resaltado de sintaxisopal - compilador de ruby a javascriptrack - interfaz de servidor websinatra - DSL para crear aplicaciones webLas siguientes gemas, si se instalan, producirán resultados más limpios y bonitos:
nokogiri limpia los fragmentos HTML insertados mediante << y _{} .nokogumbo también limpia los fragmentos HTML insertados mediante << y _{} . Si esta gema está disponible, se preferirá al uso directo de nokogiri .escape las citas más bonitas de los comandos system 
