StyledStrings

Styling

Cuando se trabaja con cadenas, el formato y el estilo a menudo aparecen como una preocupación secundaria.

Por ejemplo, al imprimir en un terminal, es posible que desees esparcir ANSI escape sequences en la salida. Al generar construcciones de estilo HTML (<span style="...">, etc.), se cumple un propósito similar, y así sucesivamente. Es posible simplemente insertar las construcciones de estilo en bruto en la cadena junto al contenido mismo, pero rápidamente se hace evidente que esto no es adecuado para nada más que los casos de uso más básicos. No todos los terminales admiten los mismos códigos ANSI, las construcciones de estilo deben ser meticulosamente eliminadas al calcular el ancho del contenido ya estilizado, y eso es antes de que incluso comiences a manejar múltiples formatos de salida.

En lugar de dejar que este dolor de cabeza sea ampliamente experimentado en la parte inferior, se aborda de manera directa mediante la introducción de un tipo de cadena especial (AnnotatedString). Este tipo de cadena envuelve cualquier otro tipo AbstractString y permite que se apliquen información de formato a regiones (por ejemplo, los caracteres del 1 al 7 son negrita y rojos).

Las regiones de una cadena se estilizan aplicando Face (piensa en "tipografía") a ellas: una estructura que contiene información de estilo. Como conveniencia, las tipografías en el diccionario global de tipografías (por ejemplo, shadow) pueden ser nombradas en lugar de dar el 4d61726b646f776e2e436f64652822222c2022466163652229_40726566205374796c6564537472696e67732e46616365 directamente.

Junto con estas capacidades, también proporcionamos una forma conveniente de construir AnnotatedString, detallado en Styled String Literals.

julia> using StyledStrings
julia> styled"{yellow:hello} {blue:there}""hello there"

Annotated Strings

A veces es útil poder mantener metadatos relacionados con regiones de una cadena. Un AnnotatedString envuelve otra cadena y permite que las regiones de esta sean anotadas con valores etiquetados (:label => value). Todas las operaciones de cadena genéricas se aplican a la cadena subyacente. Sin embargo, cuando es posible, se preserva la información de estilo. Esto significa que puedes manipular un 4d61726b646f776e2e436f64652822222c2022416e6e6f7461746564537472696e672229_4072656620426173652e416e6e6f7461746564537472696e67 —tomando subcadenas, rellenándolas, concatenándolas con otras cadenas— y las anotaciones de metadatos "vendrán junto con el viaje".

Este tipo de cadena es fundamental para el StyledStrings stdlib, que utiliza anotaciones etiquetadas con :face para mantener información de estilo.

Al concatenar un AnnotatedString, asegúrate de usar annotatedstring en lugar de string si deseas mantener las anotaciones de cadena.

julia> str = AnnotatedString("hello there", [(1:5, :word, :greeting), (7:11, :label, 1)])
"hello there"

julia> length(str)
11

julia> lpad(str, 14)
"   hello there"

julia> typeof(lpad(str, 7))
AnnotatedString{String}

julia> str2 = AnnotatedString(" julia", [(2:6, :face, :magenta)])
" julia"

julia> annotatedstring(str, str2)
"hello there julia"

julia> str * str2 == annotatedstring(str, str2) # *-concatenation works
true

Las anotaciones de un AnnotatedString se pueden acceder y modificar a través de las funciones annotations y annotate!.

Styling via AnnotatedStrings

Faces

The Face type

Un Face especifica detalles de una tipografía en la que se puede establecer texto. Cubre un conjunto de atributos básicos que se generalizan bien en diferentes formatos, a saber:

• fuente
• altura
• peso
• inclinación
• primer plano
• fondo
• subrayar
• tachado
• inverso
• heredar

Para obtener detalles sobre las formas particulares que toman estos atributos, consulta el Face docstring, pero de particular interés es inherit, ya que te permite heredar atributos de otros 4d61726b646f776e2e436f64652822222c2022466163652229_40726566205374796c6564537472696e67732e46616365s.

The global faces dictionary

Para hacer que la referencia a estilos particulares sea más conveniente, hay un Dict{Symbol, Face} global que permite que los Face se refieran simplemente por nombre. Los paquetes pueden agregar caras a este diccionario a través de la función addface!, y las caras cargadas pueden ser fácilmente customized.

Hay dos conjuntos de exenciones a la regla del prefijo del paquete:

• el conjunto de caras básicas que son parte del valor predeterminado del diccionario de caras
• caras introducidas por la propia biblioteca estándar de Julia, a saber, JuliaSyntaxHighlighting

Basic faces

Las caras básicas están destinadas a representar una idea general que es ampliamente aplicable.

Para establecer un texto con un cierto atributo, tenemos las caras negrita, ligera, cursiva, subrayado, tachado e inversa.

También hay nombres para los 16 colores terminales: negro, rojo, verde, amarillo, azul, magenta, cian, blanco, negro_brillante/gris, rojo_brillante, verde_brillante, azul_brillante, magenta_brillante, cian_brillante y blanco_brillante.

Para el texto sombreado (es decir, tenue pero presente) existe la cara shadow. Para indicar una región seleccionada, está la cara region. De manera similar, para énfasis y resaltado se definen las caras emphasis y highlight. También hay code para texto similar al código.

Para indicar visualmente la gravedad de los mensajes, se definen las caras de error, warning, success, info, note y tip.

Customisation of faces (Faces.toml)

Es bueno que los nombres de las caras en el diccionario global de caras sean personalizables. La tematización y la estética son agradables, y también es importante por razones de accesibilidad. Un archivo TOML se puede analizar en una lista de Face especificaciones que se fusionan con la entrada preexistente en el diccionario de caras.

Un Face se representa en TOML de la siguiente manera:

[facename]
attribute = "value"
...

[package.facename]
attribute = "value"

Por ejemplo, si la cara shadow es demasiado difícil de leer, se puede hacer más brillante así:

[shadow]
foreground = "white"

Al iniciar, se carga el archivo config/faces.toml en el primer depósito de Julia (generalmente ~/.julia).

Applying faces to a AnnotatedString

Por convención, los atributos :face de un AnnotatedString contienen información sobre los Face que actualmente se aplican. Esto se puede dar en múltiples formas, como un único Symbol que nombra un 4d61726b646f776e2e436f64652822222c2022466163652229_40726566205374796c6564537472696e67732e46616365 en el diccionario de caras global, un 4d61726b646f776e2e436f64652822222c2022466163652229_40726566205374796c6564537472696e67732e46616365 en sí, o un vector de cualquiera de ellos.

Los métodos show(::IO, ::MIME"text/plain", ::AnnotatedString) y show(::IO, ::MIME"text/html", ::AnnotatedString) ambos examinan los atributos :face y los combinan todos al determinar el estilo general.

Podemos suministrar atributos :face a un AnnotatedString durante la construcción, agregarlos a la lista de propiedades después, o usar el conveniente Styled String literals.

julia> str1 = AnnotatedString("blue text", [(1:9, :face, :blue)])"blue text"
julia> str2 = styled"{blue:blue text}""blue text"
julia> str1 == str2true
julia> sprint(print, str1, context = :color => true)"\e[34mblue text\e[39m"
julia> sprint(show, MIME("text/html"), str1, context = :color => true)"<span style=\"color: #195eb3\">blue text</span>"

Styled String Literals

Para facilitar la construcción de AnnotatedStrings con Faces aplicados, el literal de cadena estilizado styled"..." permite que el contenido y los atributos se expresen fácilmente juntos a través de una gramática personalizada.

Dentro de un literal styled"...", las llaves se consideran caracteres especiales y deben ser escapadas en el uso normal (\{, \}). Esto permite que se utilicen para expresar anotaciones con construcciones {anotaciones...:texto} (anidables).

El componente annotations... es una lista separada por comas de tres tipos de anotaciones.

• Nombres de cara
• Expresiones Face en línea (clave=valor,...)
• clave=valor pares

La interpolación es posible en todas partes excepto para las claves de cara en línea.

Para más información sobre la gramática, consulte la ayuda extendida del docstring styled"...".

Como ejemplo, podemos demostrar la lista de caras integradas mencionadas anteriormente de la siguiente manera:

julia> println(styled"
The basic font-style attributes are {bold:bold}, {light:light}, {italic:italic},
{underline:underline}, and {strikethrough:strikethrough}.

In terms of color, we have named faces for the 16 standard terminal colors:
 {black:■} {red:■} {green:■} {yellow:■} {blue:■} {magenta:■} {cyan:■} {white:■}
 {bright_black:■} {bright_red:■} {bright_green:■} {bright_yellow:■} {bright_blue:■} {bright_magenta:■} {bright_cyan:■} {bright_white:■}

Since {code:bright_black} is effectively grey, we define two aliases for it:
{code:grey} and {code:gray} to allow for regional spelling differences.

To flip the foreground and background colors of some text, you can use the
{code:inverse} face, for example: {magenta:some {inverse:inverse} text}.

The intent-based basic faces are {shadow:shadow} (for dim but visible text),
{region:region} for selections, {emphasis:emphasis}, and {highlight:highlight}.
As above, {code:code} is used for code-like text.

Lastly, we have the 'message severity' faces: {error:error}, {warning:warning},
{success:success}, {info:info}, {note:note}, and {tip:tip}.

Remember that all these faces (and any user or package-defined ones) can
arbitrarily nest and overlap, {region,tip:like {bold,italic:so}}.")

 The basic font-style attributes are bold, light, italic,
 underline, and strikethrough.

 In terms of color, we have named faces for the 16 standard terminal colors:
  ■ ■ ■ ■ ■ ■ ■ ■
  ■ ■ ■ ■ ■ ■ ■ ■

 Since bright_black is effectively grey, we define two aliases for it:
 grey and gray to allow for regional spelling differences.

 To flip the foreground and background colors of some text, you can use the
 inverse face, for example: some inverse text.

 The intent-based basic faces are shadow (for dim but visible text),
 region for selections, emphasis, and highlight.
 As above, code is used for code-like text.

 Lastly, we have the 'message severity' faces: error, warning,
 success, info, note, and tip.

 Remember that all these faces (and any user or package-defined ones) can
 arbitrarily nest and overlap, like so.

API reference

Styling and Faces

@styled_str -> AnnotatedString

styled"The {bold:{italic:quick} {(foreground=#cd853f):brown} fox} jumped over the {link={https://en.wikipedia.org/wiki/Laziness}:lazy} dog"

styledstring = { styled | interpolated | escaped | plain } ;

specialchar = '{' | '}' | '$' | '\"' ;
anychar = [\u0-\u1fffff] ;
plain = { anychar - specialchar } ;
escaped = '\\', specialchar ;

interpolated = '$', ? expr ? | '$(', ? expr ?, ')' ;

styled = '{', ws, annotations, ':', content, '}' ;
content = { interpolated | plain | escaped | styled } ;
annotations = annotation | annotations, ws, ',', ws, annotation ;
annotation = face | inlineface | keyvalue ;
ws = { ' ' | '\t' | '\n' } ; (* espacio en blanco *)

face = facename | interpolated ;
facename = [A-Za-z0-9_]+ ;

inlineface = '(', ws, [ faceprop ], { ws, ',', faceprop }, ws, ')' ;
faceprop = [a-z]+, ws, '=', ws, ( [^,)]+ | interpolated) ;

keyvalue = key, ws, '=', ws, value ;
key = ( [^\0${}=,:], [^\0=,:]* ) | interpolated ;
value = simplevalue | curlybraced | interpolated ;
curlybraced = '{' { escaped | plain } '}' ;
simplevalue = [^${},:], [^,:]* ;

faceprop = ( 'face', ws, '=', ws, ( ? string ? | interpolated ) ) |
           ( 'height', ws, '=', ws, ( ? number ? | interpolated ) ) |
           ( 'weight', ws, '=', ws, ( symbol | interpolated ) ) |
           ( 'slant', ws, '=', ws, ( symbol | interpolated ) ) |
           ( ( 'foreground' | 'fg' | 'background' | 'bg' ),
               ws, '=', ws, ( simplecolor | interpolated ) ) |
           ( 'underline', ws, '=', ws, ( underline | interpolated ) ) |
           ( 'strikethrough', ws, '=', ws, ( bool | interpolated ) ) |
           ( 'inverse', ws, '=', ws, ( bool | interpolated ) ) |
           ( 'inherit', ws, '=', ws, ( inherit | interpolated ) ) ;

nothing = 'nothing' ;
bool = 'true' | 'false' ;
symbol = [^ ,)]+ ;
hexcolor = ('#' | '0x'), [0-9a-f]{6} ;
simplecolor = hexcolor | symbol | nothing ;

underline = nothing | bool | simplecolor | underlinestyled;
underlinestyled = '(', ws, ('' | nothing | simplecolor | interpolated), ws,
                  ',', ws, ( symbol | interpolated ), ws ')' ;

inherit = ( '[', inheritval, { ',', inheritval }, ']' ) | inheritval;
inheritval = ws, ':'?, symbol ;

styled(content::AbstractString) -> AnnotatedString

addface!(name::Symbol => default::Face)

julia> addface!(:mypkg_myface => Face(slant=:italic, underline=true))
Face (muestra)
         slant: italic
     underline: true

withfaces(f, kv::Pair...)
withfaces(f, kvpair_itr)

julia> withfaces(:yellow => Face(foreground=:red), :green => :blue) do
           println(styled"{yellow:red} and {green:blue} mixed make {magenta:purple}")
       end
red and blue mixed make purple

struct SimpleColor

SimpleColor(name::Symbol)  # p. ej. :red
SimpleColor(rgb::RGBTuple) # p. ej. (r=1, b=2, g=3)
SimpleColor(r::Integer, b::Integer, b::Integer)
SimpleColor(rgb::UInt32)   # p. ej. 0x123456

parse(::Type{SimpleColor}, rgb::String)

tryparse(::Type{SimpleColor}, rgb::String)

julia> tryparse(SimpleColor, "blue")
SimpleColor(blue)

julia> tryparse(SimpleColor, "#9558b2")
SimpleColor(#9558b2)

julia> tryparse(SimpleColor, "#nocolor")

merge(initial::Face, others::Face...)