StyledStrings

Styling

文字列を扱う際、フォーマットやスタイルはしばしば二次的な関心事として現れます。

例えば、ターミナルに印刷する際には、出力に ANSI escape sequences を散りばめたい場合があります。HTMLスタイリング構造（<span style="..."> など）を出力することも同様の目的を果たします。このように、コンテンツ自体の隣に生のスタイリング構造を単純に挿入することは可能ですが、これは最も基本的なユースケースにしか適していないことがすぐに明らかになります。すべてのターミナルが同じANSIコードをサポートしているわけではなく、スタイリング構造は、すでにスタイルが適用されたコンテンツの幅を計算する際に手間をかけて取り除く必要があります。そして、複数の出力形式を扱う前に、これが必要になります。

Instead of leaving this headache to be widely experienced downstream, it is tackled head-on by the introduction of a special string type (AnnotatedString). This string type wraps any other AbstractString type and allows for formatting information to be applied to regions (e.g. characters 1 through to 7 are bold and red).

文字列の領域は、Face（「フォント」と考えてください）を適用することでスタイルが設定されます。これはスタイリング情報を保持する構造です。便利なことに、グローバルフォント辞書内のフォント（例：shadow）は、4d61726b646f776e2e436f64652822222c2022466163652229_40726566205374796c6564537472696e67732e46616365を直接指定する代わりに名前を付けることができます。

これらの機能に加えて、AnnotatedStringを構築するための便利な方法も提供しています。詳細はStyled String Literalsに記載されています。

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

Annotated Strings

文字列の領域に関連するメタデータを保持することができると、時には便利です。AnnotatedStringは別の文字列をラップし、その一部にラベル付きの値（:label => value）で注釈を付けることを可能にします。すべての一般的な文字列操作は、基になる文字列に適用されます。ただし、可能な場合はスタイリング情報が保持されます。これは、4d61726b646f776e2e436f64652822222c2022416e6e6f7461746564537472696e672229_4072656620426173652e416e6e6f7461746564537472696e67を操作することができることを意味します—部分文字列を取り出したり、パディングを施したり、他の文字列と連結したりしても、メタデータの注釈は「一緒に付いてくる」のです。

この文字列タイプは、スタイリング情報を保持するために :face ラベル付きの注釈を使用する StyledStrings stdlib にとって基本的です。

When concatenating a AnnotatedString, take care to use annotatedstring instead of string if you want to keep the string annotations.

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! 関数を介してアクセスおよび変更できます。

Styling via AnnotatedStrings

Faces

The Face type

Face は、テキストを設定できるフォントの詳細を指定します。これは、さまざまなフォーマットにわたって一般化される基本的な属性のセットをカバーしています。具体的には：

• フォント
• 高さ
• 体重
• スラント
• 前景
• 背景
• 下線
• 打ち消し線
• 逆
• 継承

特定の属性がどのような形を取るかの詳細については、Face ドキュメントストリングを参照してくださいが、特に興味深いのは inherit です。これは他の 4d61726b646f776e2e436f64652822222c2022466163652229_40726566205374796c6564537472696e67732e46616365 から属性を 継承 することを可能にします。

The global faces dictionary

特定のスタイルを参照するために便利にするために、グローバルな Dict{Symbol, Face} があり、これにより Face を単に名前で参照することができます。パッケージは addface! 関数を介してこの辞書にフェイスを追加でき、ロードされたフェイスは簡単に customized できます。

パッケージプレフィックスルールには2つの免除があります：

• デフォルト値のフェイス辞書に含まれる基本的なフェイスのセット
• Juliaの標準ライブラリであるJuliaSyntaxHighlightingによって導入された顔。

Basic faces

基本的な顔は、広く適用可能な一般的なアイデアを表すことを意図しています。

特定の属性を持つテキストを設定するために、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 のフェイスが定義されています。

Customisation of faces (Faces.toml)

グローバルフェイス辞書の名前の顔がカスタマイズ可能であることは良いことです。テーマや美学は素晴らしく、アクセシビリティの理由からも重要です。TOMLファイルは、フェイス辞書の既存のエントリとマージされるFace仕様のリストに解析できます。

A Face は、次のようにTOMLで表現されます：

[facename]
attribute = "value"
...

[package.facename]
attribute = "value"

例えば、shadow フェイスが読みづらい場合は、次のように明るくすることができます：

[shadow]
foreground = "white"

初期化時に、最初のJuliaデポ（通常は~/.julia）の下にあるconfig/faces.tomlファイルが読み込まれます。

Applying faces to a AnnotatedString

慣例として、AnnotatedStringの:face属性は、現在適用されているFaceに関する情報を保持します。これは、グローバルフェイス辞書内の4d61726b646f776e2e436f64652822222c2022466163652229_40726566205374796c6564537472696e67732e46616365を名前付ける単一のSymbol、4d61726b646f776e2e436f64652822222c2022466163652229_40726566205374796c6564537472696e67732e46616365自体、またはそのいずれかのベクトルの形で提供できます。

show(::IO, ::MIME"text/plain", ::AnnotatedString) および show(::IO, ::MIME"text/html", ::AnnotatedString) メソッドはどちらも :face 属性を確認し、全体のスタイリングを決定する際にそれらをすべて統合します。

AnnotatedStringの構築時に:face属性を供給することができ、その後プロパティリストに追加するか、便利な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

AnnotatedStringの構築を容易にするために、Faceが適用され、styled"..."スタイルの文字列リテラルは、コンテンツと属性をカスタム文法を介して簡単に表現できるようにします。

styled"..." リテラル内では、波括弧は特別な文字と見なされ、通常の使用ではエスケープする必要があります（\{、\}）。これにより、（ネスト可能な）{annotations...:text} 構文を使用して注釈を表現することができます。

annotations... コンポーネントは、3種類のアノテーションのカンマ区切りリストです。

• 顔の名前
• インライン 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 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' } ; (* 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 ;

styled(content::AbstractString) -> AnnotatedString

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

julia> addface!(:mypkg_myface => Face(slant=:italic, underline=true))
Face (sample)
         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)  # 例: :red
SimpleColor(rgb::RGBTuple) # 例: (r=1, b=2, g=3)
SimpleColor(r::Integer, b::Integer, b::Integer)
SimpleColor(rgb::UInt32)   # 例: 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...)