StyledStrings

Note

StyledStrings ve AnnotatedStrings için API deneysel olarak kabul edilmektedir ve Julia sürümleri arasında değişiklik göstermesi muhtemeldir.

Styling

Dizelerle çalışırken, biçimlendirme ve stil genellikle ikincil bir endişe olarak ortaya çıkar.

Örneğin, bir terminale yazdırırken ANSI escape sequences çıktısında serpiştirmek isteyebilirsiniz, HTML stil yapıları (<span style="..."> vb.) benzer bir amaca hizmet eder ve devam eder. İçerikle birlikte ham stil yapıları dizeye basitçe eklemek mümkündür, ancak bu, en temel kullanım durumları dışında iyi bir şekilde uygun olmadığını hızla ortaya çıkarır. Tüm terminaller aynı ANSI kodlarını desteklemez, stil yapıları, zaten stillendirilmiş içeriğin genişliğini hesaplarken titizlikle kaldırılmalıdır ve bu, birden fazla çıktı formatını ele almaya başlamadan önceki durumdur.

Bunu aşağı akışta yaygın olarak deneyimlenmesi için bırakmak yerine, özel bir dize türünün (AnnotatedString) tanıtımıyla doğrudan ele alınmaktadır. Bu dize türü, herhangi bir AbstractString türünü sarar ve biçimlendirme bilgilerini bölgelere uygulamaya olanak tanır (örneğin, 1'den 7'ye kadar olan karakterler kalın ve kırmızıdır).

Bir dize bölgeleri, onlara Face (düşünün "yazı tipi") uygulayarak stillendirilir — stil bilgilerini tutan bir yapı. Kolaylık olması açısından, küresel yüzler sözlüğündeki yüzler (örneğin shadow) doğrudan 4d61726b646f776e2e436f64652822222c2022466163652229_40726566205374796c6564537472696e67732e46616365 vermek yerine sadece adlandırılabilir.

Bu yeteneklerin yanı sıra, AnnotatedString oluşturmak için de kullanışlı bir yol sağlıyoruz, bu da Styled String Literals içinde detaylandırılmıştır.

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

Annotated Strings

Bazen bir dize ile ilgili bölgeleri tutmak için meta verileri saklamak faydalı olabilir. Bir AnnotatedString, başka bir dizeyi sarar ve bunun bölgelerinin etiketli değerlerle (:label => value) anotasyon yapılmasına olanak tanır. Tüm genel dize işlemleri, temel dizeye uygulanır. Ancak, mümkün olduğunda stil bilgileri korunur. Bu, bir 4d61726b646f776e2e436f64652822222c2022416e6e6f7461746564537472696e672229_4072656620426173652e416e6e6f7461746564537472696e67 üzerinde alt dizeler alabileceğiniz, bunları doldurabileceğiniz, diğer dizelerle birleştirebileceğiniz anlamına gelir ve meta veri anotasyonları "yolda gelir".

Bu dize türü, stil bilgilerini tutmak için :face etiketli notlar kullanan StyledStrings stdlib için temeldir.

AnnotatedString ile birleştirirken, dize açıklamalarını korumak istiyorsanız annotatedstring kullanmaya dikkat edin, string yerine.

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 anotasyonları annotations ve annotate! fonksiyonları aracılığıyla erişilebilir ve değiştirilebilir.

Styling via AnnotatedStrings

Faces

The Face type

Bir Face, metinlerin ayarlanabileceği bir yazı tipinin ayrıntılarını belirtir. Farklı formatlar arasında iyi bir şekilde genelleştirilebilen temel özellikler kümesini kapsar, yani:

  • yazı tipi
  • yükseklik
  • ağırlık
  • eğim
  • ön plan
  • arka plan
  • altı çizili
  • üstü çizili
  • ters
  • miras almak

Belirli niteliklerin bu biçimlerinin ayrıntıları için Face docstring'ine bakın, ancak özellikle ilginç olan inherit'dir çünkü diğer 4d61726b646f776e2e436f64652822222c2022466163652229_40726566205374796c6564537472696e67732e46616365'lerden nitelikleri devralmanıza olanak tanır.

The global faces dictionary

Belirli stillere atıfta bulunmayı daha uygun hale getirmek için, Dict{Symbol, Face} adlı küresel bir yapı vardır. Bu yapı, Face'leri sadece isimle anılmasını sağlar. Paketler, bu sözlüğe yüzler eklemek için addface! fonksiyonunu kullanabilir ve yüklenen yüzler kolayca customized olarak kullanılabilir.

Appropriate face naming

Herhangi bir paket yeni yüzler kaydediyorsa, bunların paket adıyla ön eklenmiş olduğundan emin olmalıdır, yani mypackage_myface formatını takip etmelidir. Bu, öngörülebilirlik açısından önemlidir ve isim çakışmalarını önlemek için gereklidir.

Ayrıca, paketlerin doğrudan renkler ve stiller (örneğin cyan) yerine anlamsal yüzleri (örneğin code) kullanmaya (ve tanıtmaya) özen göstermesi gerekir. Bu, kullanım amacını daha belirgin hale getirmek, bileşenlerin birleştirilmesine yardımcı olmak ve kullanıcı özelleştirmesini daha sezgisel hale getirmek gibi birçok açıdan faydalıdır.

Paket ön ek kuralına iki tür muafiyet vardır:

  • varsayılan değer olan yüzler sözlüğünün bir parçası olan temel yüzlerin kümesi
  • Julia'nın kendi standart kütüphanesi tarafından tanıtılan yüzler, yani JuliaSyntaxHighlighting

Basic faces

Temel yüzler, yaygın olarak uygulanabilir genel bir fikri temsil etmek amacıyla tasarlanmıştır.

Belirli bir niteliğe sahip metin ayarlamak için bold, light, italic, underline, strikethrough ve inverse yüzlerini kullanıyoruz.

16 terminal renkleri için ayrıca adlandırılmış yüzler de vardır: siyah, kırmızı, yeşil, sarı, mavi, macenta, cyan, beyaz, parlak_siyah/gri, parlak_kırmızı, parlak_yeşil, parlak_mavi, parlak_macenta, parlak_cyan ve parlak_beyaz.

Gölgelendirilmiş metin için (yani, soluk ama orada) shadow yüzü vardır. Seçili bir bölgeyi belirtmek için region yüzü vardır. Benzer şekilde, vurgulama ve öne çıkarma için emphasis ve highlight yüzleri tanımlanmıştır. Ayrıca, kod benzeri metinler için code de vardır.

Mesajların ciddiyetini görsel olarak belirtmek için hata, uyarı, başarı, bilgi, not ve ipuçları yüzleri tanımlanmıştır.

Customisation of faces (Faces.toml)

Küresel yüz sözlüğündeki isim yüzlerinin özelleştirilebilir olması iyidir. Temalar ve estetikler hoş, ayrıca erişilebilirlik nedenleriyle de önemlidir. Bir TOML dosyası, yüz sözlüğündeki mevcut girişle birleştirilen Face spesifikasyonları listesine ayrıştırılabilir.

Bir Face TOML formatında şu şekilde temsil edilir:

[facename]
attribute = "value"
...

[package.facename]
attribute = "value"

Örneğin, eğer gölge yüzü okunması çok zor ise, şöyle daha parlak hale getirilebilir:

[shadow]
foreground = "white"

Başlatıldığında, ilk Julia depo altında bulunan config/faces.toml dosyası (genellikle ~/.julia) yüklenir.

Applying faces to a AnnotatedString

Gelenek gereği, AnnotatedString'nin :face nitelikleri, şu anda geçerli olan Face'ler hakkında bilgi tutar. Bu, global yüz sözlüğündeki bir Symbol ile adlandırılan bir 4d61726b646f776e2e436f64652822222c2022466163652229_40726566205374796c6564537472696e67732e46616365, bir 4d61726b646f776e2e436f64652822222c2022466163652229_40726566205374796c6564537472696e67732e46616365 veya bunların bir vektörü şeklinde birden fazla biçimde verilebilir.

show(::IO, ::MIME"text/plain", ::AnnotatedString) ve show(::IO, ::MIME"text/html", ::AnnotatedString) yöntemleri, genel stil belirlenirken :face niteliklerine bakar ve hepsini bir araya getirir.

AnnotatedString oluşturulurken :face niteliklerini sağlayabilir, bunları sonrasında özellikler listesine ekleyebilir veya kullanışlı Styled String literals'i kullanabilirsiniz.

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 ile Face'lerin uygulanmasıyla, styled"..." stilinde bir dize literal'i, içeriğin ve niteliklerin özel bir dil bilgisi aracılığıyla kolayca ifade edilmesine olanak tanır.

styled"..." literal içinde, süslü parantezler normal kullanımda özel karakterler olarak kabul edilir ve kaçış karakteri ile kullanılmalıdır (\{, \}). Bu, (iç içe) {annotations...:text} yapıları ile notasyonları ifade etmek için kullanılmalarına olanak tanır.

annotations... bileşeni, üç tür anotasyonun virgülle ayrılmış bir listesidir.

  • Yüz isimleri
  • Satır içi Yüz ifadeleri (anahtar=değer,...)
  • ana=değer çiftleri

İnterpolasyon, yalnızca satır içi yüz anahtarları için mümkün değildir.

Daha fazla bilgi için, styled"..." docstring'inin genişletilmiş yardımına bakın.

Örnek olarak, yukarıda bahsedilen yerleşik yüzlerin listesini şu şekilde gösterebiliriz:

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

StyledStrings.StyledMarkup.@styled_strMacro
@styled_str -> AnnotatedString

Biçimlendirilmiş bir dize oluşturun. Dize içinde, {<specs>:<content>} yapıları <content>'e biçimlendirme uygular ve bu, virgülle ayrılmış <specs> spesifikasyonları listesini takip eder. Her bir spesifikasyon, bir yüz adı, bir satır içi yüz spesifikasyonu veya bir key=value çifti biçiminde olabilir. Değer, ,=:{} karakterlerinden herhangi birini içeriyorsa {...} ile sarılmalıdır.

Dize interpolasyonu $ ile, normal dizelerle aynı şekilde çalışır, ancak tırnak işaretleri kaçırılmalıdır. Yüzler, anahtarlar ve değerler de $ ile interpolasyon yapılabilir.

Örnek

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

Genişletilmiş yardım

Bu makro aşağıdaki EBNF grameri ile tanımlanabilir:

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' } ; (* boşluk *)

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 = [^${},:], [^,:]* ;

Yukarıdaki gramerde kodlanmamış bir ek şart, plain'in unescape_string için geçerli bir girdi olmasıdır ve specialchar korunmalıdır.

inlineface için yukarıdaki gramer basitleştirilmiştir, çünkü gerçek uygulama biraz daha karmaşıktır. Tam davranış aşağıda verilmiştir.

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 ;
source
StyledStrings.StyledMarkup.styledFunction
styled(content::AbstractString) -> AnnotatedString

Biçimlendirilmiş bir dize oluşturur. Dize içinde, {<specs>:<content>} yapıları <content>'e biçimlendirme uygular; bu, virgülle ayrılmış <specs> spesifikasyonları listesinin gerekliliklerine göre yapılır. Her bir spesifikasyon, bir yüz adı, bir satır içi yüz spesifikasyonu veya bir key=value çifti biçiminde olabilir. Değer, ,=:{} karakterlerinden herhangi birini içeriyorsa {...} ile sarılmalıdır.

Bu, @styled_str makrosunun işlevsel bir eşdeğeridir; sadece interpolasyon yetenekleri olmadan.

source
StyledStrings.FaceType

Bir Face, metin görüntülemek için grafiksel özelliklerin bir koleksiyonudur. Yüzler, metnin terminalde ve muhtemelen diğer yerlerde nasıl görüntüleneceğini kontrol eder.

Çoğu zaman, bir Face, yüz adı Symbol ile benzersiz bir ilişki olarak global yüzler sözlüklerinde saklanır ve genellikle bu isimle anılır, Face nesnesinin kendisi yerine.

Özellikler

Tüm özellikler anahtar kelime yapıcı aracılığıyla ayarlanabilir ve varsayılan olarak nothing değerini alır.

  • height (bir Int veya Float64): Yükseklik, bir Int olduğunda desi-pt cinsinden veya bir Float64 olduğunda temel boyutun bir faktörü olarak.

  • weight (bir Symbol): :thin, :extralight, :light, :semilight, :normal, :medium, :semibold, :bold, :extrabold veya :black sembollerinden biri (en hafiften en yoğun olana). Terminallerde, :normaldan daha büyük herhangi bir ağırlık kalın olarak görüntülenir ve değişken parlaklık metnini destekleyen terminallerde, :normaldan daha düşük herhangi bir ağırlık soluk olarak görüntülenir.

  • slant (bir Symbol): :italic, :oblique veya :normal sembollerinden biri.

  • foreground (bir SimpleColor): Metin ön plan rengi.

  • background (bir SimpleColor): Metin arka plan rengi.

  • underline, metin altı çizgisi, aşağıdaki formlardan birini alır:

    • bir Bool: Metnin altı çizili olup olmayacağı.
    • bir SimpleColor: Metin bu renkle altı çizili olmalıdır.
    • bir Tuple{Nothing, Symbol}: Metin, :straight, :double, :curly, :dotted veya :dashed sembolüyle belirlenen stil kullanılarak altı çizili olmalıdır.
    • bir Tuple{SimpleColor, Symbol}: Metin belirtilen SimpleColor ile altı çizili olmalı ve daha önce belirtilen sembol tarafından belirlenen stil kullanılmalıdır.
  • strikethrough (bir Bool): Metnin üstü çizili olup olmayacağı.

  • inverse (bir Bool): Ön plan ve arka plan renklerinin tersine çevrilip çevrilmeyeceği.

  • inherit (bir Vector{Symbol}): Öncelik sırasına göre miras alınacak yüzlerin isimleri. Tüm yüzler :default yüzünden miras alır.

source
StyledStrings.addface!Function
addface!(name::Symbol => default::Face)

name ile yeni bir yüz oluşturun. Bu isimle zaten bir yüz mevcut değilse, default hem FACES.default'a hem de (bir kopyası) FACES.current'a eklenir ve mevcut değer döndürülür.

Eğer name yüzü zaten mevcutsa, nothing döndürülür.

Örnekler

julia> addface!(:mypkg_myface => Face(slant=:italic, underline=true))
Face (örnek)
         slant: italic
     underline: true
source
StyledStrings.withfacesFunction
withfaces(f, kv::Pair...)
withfaces(f, kvpair_itr)

f'yi FACES.current'ı sıfır veya daha fazla :name => val argümanı kv veya kv-form değerleri üreten kvpair_itr ile geçici olarak değiştirilmiş olarak çalıştırır.

withfaces genellikle withfaces(kv...) do ... end sözdizimi aracılığıyla kullanılır. nothing değeri, bir yüz geçici olarak sıfırlamak için kullanılabilir (eğer ayarlanmışsa). withfaces döndüğünde, orijinal FACES.current geri yüklenmiştir.

Örnekler

julia> withfaces(:yellow => Face(foreground=:red), :green => :blue) do
           println(styled"{yellow:red} ve {green:blue} karışımı {magenta:purple} yapar")
       end
kırmızı ve mavi karışımı mor yapar
source
StyledStrings.SimpleColorType
struct SimpleColor

Bir rengin temel bir temsilidir, dize stilizasyonu amaçları için tasarlanmıştır. Ya bir adlandırılmış rengi (örneğin :red) ya da 8 bit derinliğinde r, g, b rengini belirten bir NamedTuple olan RGBTuple içerebilir.

Yapıcılar

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

Ayrıca tryparse(SimpleColor, rgb::String)'e de bakın.

source
Base.parseMethod
parse(::Type{SimpleColor}, rgb::String)

tryparse(SimpleColor, rgb::String) (buna bakınız) ile benzer bir işlevdir; nothing döndürmek yerine bir hata yükseltir.

source
Base.tryparseMethod
tryparse(::Type{SimpleColor}, rgb::String)

rgb'yi bir SimpleColor olarak ayrıştırmayı deneyin. Eğer rgb # ile başlıyorsa ve uzunluğu 7 ise, RGBTuple destekli bir SimpleColor'a dönüştürülür. Eğer rgb a-z ile başlıyorsa, rgb bir renk adı olarak yorumlanır ve Symbol destekli bir SimpleColor'a dönüştürülür.

Aksi takdirde, nothing döndürülür.

Örnekler

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

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

julia> tryparse(SimpleColor, "#nocolor")
source
Base.mergeMethod
merge(initial::Face, others::Face...)

initial yüzünün ve diğerlerinin özelliklerini birleştirir, daha sonraki yüzler önceliğe sahiptir.

source