StyledStrings

Форматирование

При работе со строками форматирование и стилизация часто являются вторичными проблемами.

Например, при выводе в терминал вы можете добавить последовательности ANSI в вывод, при выводе HTML-конструктов стилей (<span style="...">, и т.д.) преследуется аналогичная цель. Можно просто вставить необработанные конструкции форматирования в строку рядом с самим содержимым, но быстро становится ясно, что это подходит только для самых простых случаев. Не все терминалы поддерживают одни и те же коды ANSI, конструкции стилей необходимо тщательно удалять при вычислении ширины уже отформатированного содержимого, и это еще до того, как вы начнете обрабатывать несколько форматов вывода.

Вместо того, чтобы оставлять эту головную боль для широкого распространения в последующих этапах, она решается сразу введением специального типа строки (AnnotatedString). Этот тип строки оборачивает любой другой тип AbstractString и позволяет применять информацию о форматировании к регионам (например, символы с 1 по 7 выделены жирным шрифтом красным цветом).

Регионы строки стилизуются путем применения Face (подумайте о «типе шрифта») к ним — структура, содержащая информацию о стилизации. Для удобства лица в глобальном словаре лиц (например, shadow) могут просто называться, вместо указания Face непосредственно.

Наряду с этими возможностями, мы также предоставляем удобный способ создания AnnotatedString, подробно описанный в разделе Литералы стилизованных строк.

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

Аннотированные строки

Иногда бывает полезно иметь возможность хранить метаданные, относящиеся к регионам строки. AnnotatedString оборачивает другую строку и позволяет аннотировать ее области с помощью маркированных значений (:label => value). Все общие операции со строками применяются к базовой строке. Однако, когда это возможно, информация о стилизации сохраняется. Это означает, что вы можете манипулировать AnnotatedString — извлекая подстроки, дополняя их, конкатенируя их с другими строками — и аннотации метаданных будут «идти вместе с ними».

Этот тип строки является основой для модуля StyledStrings, который использует аннотации с метками :face для хранения информации о стилизации.

При конкатенации AnnotatedString следует использовать annotatedstring вместо string, если вы хотите сохранить аннотации строк.

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

К аннотациям AnnotatedString можно получить доступ и изменить их с помощью функций annotations и annotate!.

Стилизация с помощью AnnotatedString

Лица

Тип Face

Face определяет детали шрифта, которым может быть установлен текст. Он охватывает набор основных атрибутов, которые хорошо обобщаются в разных форматах, а именно:

• font
• height
• weight
• slant
• foreground
• background
• underline
• strikethrough
• inverse
• inherit

Подробности о конкретных формах этих атрибутов см. в строке документации Face, но особенно интересен inherit, так как он позволяет вам унаследовать атрибуты от других Face.

Глобальный словарь лиц

Для упрощения ссылки на определенные стили существует глобальный Dict{Symbol, Face}, который позволяет ссылаться на Face просто по имени. Пакеты могут добавлять лица в этот словарь с помощью функции addface!, и загруженные лица можно легко настроить.

Существует два исключения из правила префикса пакета:

• набор основных лиц, которые являются частью значения по умолчанию словаря лиц
• лица, введенные собственной стандартной библиотекой Julia, а именно JuliaSyntaxHighlighting

Основные лица

Основные лица предназначены для представления общего понятия, широко применимого.

Для задания некоторого текста с определенным атрибутом у нас есть лица bold, light, italic, underline, strikethrough, и inverse.

Также существуют именованные лица для 16 цветовых схем терминала: black, red, green, yellow, blue, magenta, cyan, white, bright_black/grey/gray, bright_red, bright_green, bright_blue, bright_magenta, bright_cyan, и bright_white.

Для затемненного текста (т. е. тусклого, но присутствующего) есть лицо shadow. Для обозначения выделенного региона есть лицо region. Аналогично, для выделения и подсветки определены лица emphasis и highlight. Также есть code для кода-подобного текста.

Для визуального обозначения серьезности сообщений определены лица error, warning, success, info, note, и tip.

Настройка лиц (Faces.toml)

Хорошо, если имена лиц в глобальном словаре лиц можно настроить. Тематика и эстетика приятны, и это важно и по соображениям доступности. Файл TOML можно разобрать в список спецификаций Face, которые объединяются с существующей записью в словаре лиц.

Face представляется в TOML так:

[facename]
attribute = "value"
...

[package.facename]
attribute = "value"

Например, если лицо shadow слишком трудно читать, его можно сделать ярче так:

[shadow]
foreground = "white"

При инициализации загружается файл config/faces.toml в первом репозитории Julia (обычно ~/.julia).

Применение лиц к AnnotatedString

По соглашению, атрибуты :face AnnotatedString содержат информацию о Face, которые в настоящее время применяются. Это может быть представлено в нескольких формах, как одно Symbol, указывающее на Face в глобальном словаре лиц, само Face, или вектор любого из них.

Методы show(::IO, ::MIME"text/plain", ::AnnotatedString) и show(::IO, ::MIME"text/html", ::AnnotatedString) оба обращаются к атрибутам :face и объединяют их все вместе при определении общего стиля.

Мы можем предоставить атрибуты :face к AnnotatedString во время создания, добавить их в список свойств позже или использовать удобные литералы стилизованных строк.

julia> str1 = AnnotatedString("blue text", [(1:9, :face, :blue)])"blue text"julia> str2 = styled"{blue:blue text}""blue text"julia> str1 == str2truejulia> 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>"

Литералы стилизованных строк

Для упрощения создания AnnotatedString с примененными Face, литерал стилизованной строки styled"..." позволяет легко выразить содержимое и атрибуты вместе с помощью специальной грамматики.

Внутри литерала styled"..." фигурные скобки считаются специальными символами и должны быть экранированы в обычном использовании (\{, \}). Это позволяет использовать их для выражения аннотаций с помощью (вложенных) {annotations...:text} конструкций.

Компонент annotations... представляет собой список, разделенный запятыми, трех типов аннотаций.

• Имена лиц
• Встроенные выражения Face (key=val,...)
• Пары key=value

Интерполяция возможна везде, кроме встроенных ключей лиц.

Дополнительную информацию о грамматике см. в расширенной справке по строке документации styled"...".

В качестве примера, мы можем продемонстрировать список встроенных шрифтов, упомянутых выше, следующим образом:

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

Стилеобработка и Шрифты

StyledStrings.StyledMarkup.@styled_strМакрос

@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' } ; (* whitespace *)

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 ;

StyledStrings.StyledMarkup.styledФункция

styled(content::AbstractString) -> AnnotatedString

StyledStrings.FaceТип

StyledStrings.addface!Функция

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

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

StyledStrings.withfacesФункция

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

StyledStrings.SimpleColorТип

struct SimpleColor

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

Base.parseМетод

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

Base.tryparseМетод

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

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

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

julia> tryparse(SimpleColor, "#nocolor")

Base.mergeМетод

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