Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Adopt Base's annotated types/functions as API #81

Merged
merged 1 commit into from
Oct 1, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 5 additions & 5 deletions docs/src/examples.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ A styled string can be constructed manually, but the [`styled"..."`](@ref
```@repl examples
using StyledStrings
str = styled"{yellow:hello} {blue:there}"
(String(str), Base.annotations(str))
(String(str), annotations(str))
```

```@setup example
Expand Down Expand Up @@ -181,25 +181,25 @@ Sometimes it's useful to compose a string incrementally, or interoperate with
other `IO`-based code. For these use-cases, the [`AnnotatedIOBuffer`](@ref Base.AnnotatedIOBuffer) is very handy, as you can [`read`](@ref Base.read) an [`AnnotatedString`](@ref Base.AnnotatedString) from it.

```@repl examples
aio = Base.AnnotatedIOBuffer()
aio = AnnotatedIOBuffer()
typ = Int
print(aio, typ)
while typ != Any # We'll pretend that `supertypes` doesn't exist.
typ = supertype(typ)
print(aio, styled" {bright_red:<:} $typ")
end
read(seekstart(aio), Base.AnnotatedString)
read(seekstart(aio), AnnotatedString)
```

StyledStrings adds a specialised [`printstyled`](@ref) method `printstyled(::AnnotatedIOBuffer, ...)` that means that you can pass an `AnnotatedIOBuffer` as IO to "legacy" code written to use `printstyled`, and extract all the styling as though it had used [`styled"..."`](@ref @styled_str) macros.

```@repl
aio = Base.AnnotatedIOBuffer()
aio = AnnotatedIOBuffer()
printstyled(aio, 'c', color=:red)
printstyled(aio, 'o', color=:yellow)
printstyled(aio, 'l', color=:green)
printstyled(aio, 'o', color=:blue)
printstyled(aio, 'r', color=:magenta)
read(seekstart(aio), Base.AnnotatedString)
read(seekstart(aio), AnnotatedString)
read(seekstart(aio), String)
```
64 changes: 60 additions & 4 deletions docs/src/index.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,12 @@
# [StyledStrings](@id stdlib-styledstrings)

```@meta
CurrentModule = StyledStrings
DocTestSetup = quote
using StyledStrings
end
```

!!! note
The API for StyledStrings and AnnotatedStrings is considered experimental and is subject to change between
Julia versions.
Expand Down Expand Up @@ -41,6 +48,52 @@ using StyledStrings
styled"{yellow:hello} {blue:there}"
```

## [Annotated Strings](@id man-annotated-strings)

It is sometimes useful to be able to hold metadata relating to regions of a
string. A [`AnnotatedString`](@ref Base.AnnotatedString) wraps another string and
allows for regions of it to be annotated with labelled values (`:label => value`).
All generic string operations are applied to the underlying string. However,
when possible, styling information is preserved. This means you can manipulate a
[`AnnotatedString`](@ref Base.AnnotatedString) —taking substrings, padding them,
concatenating them with other strings— and the metadata annotations will "come
along for the ride".

This string type is fundamental to the [StyledStrings stdlib](@ref
stdlib-styledstrings), which uses `:face`-labelled annotations to hold styling
information.

When concatenating a [`AnnotatedString`](@ref Base.AnnotatedString), take care to use
[`annotatedstring`](@ref StyledStrings.annotatedstring) instead of [`string`](@ref) if you want
to keep the string annotations.

```jldoctest
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
```

The annotations of a [`AnnotatedString`](@ref Base.AnnotatedString) can be accessed
and modified via the [`annotations`](@ref StyledStrings.annotations) and
[`annotate!`](@ref StyledStrings.annotate!) functions.

## Styling via [`AnnotatedString`](@ref Base.AnnotatedString)s

## [Faces](@id stdlib-styledstrings-faces)
Expand Down Expand Up @@ -153,7 +206,7 @@ them to the properties list afterwards, or use the convenient [Styled String
literals](@ref stdlib-styledstring-literals).

```@repl demo
str1 = Base.AnnotatedString("blue text", [(1:9, :face => :blue)])
str1 = AnnotatedString("blue text", [(1:9, :face => :blue)])
str2 = styled"{blue:blue text}"
str1 == str2
sprint(print, str1, context = :color => true)
Expand Down Expand Up @@ -275,14 +328,17 @@ arbitrarily nest and overlap, \colorbox[HTML]{3a3a3a}{\color[HTML]{33d079}like

## [API reference](@id stdlib-styledstrings-api)


### Styling and Faces

```@docs
StyledStrings.@styled_str
StyledStrings.styled
StyledStrings.Face
StyledStrings.addface!
StyledStrings.withfaces
StyledStrings.SimpleColor
Base.parse(::Type{StyledStrings.SimpleColor}, ::String)
Base.tryparse(::Type{StyledStrings.SimpleColor}, ::String)
Base.merge(::StyledStrings.Face, ::StyledStrings.Face)
StyledStrings.parse(::Type{StyledStrings.SimpleColor}, ::String)
StyledStrings.tryparse(::Type{StyledStrings.SimpleColor}, ::String)
StyledStrings.merge(::StyledStrings.Face, ::StyledStrings.Face)
```
5 changes: 4 additions & 1 deletion src/StyledStrings.jl
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,12 @@

module StyledStrings

using Base: AnnotatedString, AnnotatedChar, annotations, annotate!, annotatedstring
using Base: AnnotatedString, AnnotatedChar, AnnotatedIOBuffer, annotations, annotate!, annotatedstring
using Base.ScopedValues: ScopedValue, with, @with

# While these are imported from Base, we claim them as part of the `StyledStrings` API.
export AnnotatedString, AnnotatedChar, AnnotatedIOBuffer, annotations, annotate!, annotatedstring

export @styled_str
public Face, addface!, withfaces, styled, SimpleColor

Expand Down
4 changes: 2 additions & 2 deletions src/io.jl
Original file line number Diff line number Diff line change
Expand Up @@ -263,7 +263,7 @@ Base.print(io::IO, s::Union{<:AnnotatedString, SubString{<:AnnotatedString}}) =

# We need to make sure that printing to an `AnnotatedIOBuffer` calls `write` not `print`
# so we get the specialised handling that `_ansi_writer` doesn't provide.
Base.print(io::Base.AnnotatedIOBuffer, s::Union{<:AnnotatedString, SubString{<:AnnotatedString}}) =
Base.print(io::AnnotatedIOBuffer, s::Union{<:AnnotatedString, SubString{<:AnnotatedString}}) =
(write(io, s); nothing)

Base.escape_string(io::IO, s::Union{<:AnnotatedString, SubString{<:AnnotatedString}},
Expand Down Expand Up @@ -293,7 +293,7 @@ function Base.show(io::IO, c::AnnotatedChar)
end
end

function Base.write(io::IO, aio::Base.AnnotatedIOBuffer)
function Base.write(io::IO, aio::AnnotatedIOBuffer)
if get(io, :color, false) == true
# This does introduce an overhead that technically
# could be avoided, but I'm not sure that it's currently
Expand Down
6 changes: 3 additions & 3 deletions src/legacy.jl
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@

module Legacy

using ..StyledStrings: SimpleColor, Face, loadface!, face!
using ..StyledStrings: SimpleColor, Face, loadface!, face!, AnnotatedIOBuffer, annotatedstring

"""
legacy_color(color::Union{String, Symbol, Int})
Expand Down Expand Up @@ -123,11 +123,11 @@ function load_env_colors!()
end
end

function Base.printstyled(io::Base.AnnotatedIOBuffer, msg...;
function Base.printstyled(io::AnnotatedIOBuffer, msg...;
bold::Bool=false, italic::Bool=false, underline::Bool=false,
blink::Bool=false, reverse::Bool=false, hidden::Bool=false,
color::Union{Symbol, Int}=:normal)
str = Base.annotatedstring(msg...)
str = annotatedstring(msg...)
bold && face!(str, :bold)
italic && face!(str, :italic)
underline && face!(str, :underline)
Expand Down
2 changes: 1 addition & 1 deletion src/regioniterator.jl
Original file line number Diff line number Diff line change
Expand Up @@ -28,7 +28,7 @@ an iterator which provides each substring and the applicable annotations as a
# Examples

```jldoctest
julia> collect(StyledStrings.eachregion(Base.AnnotatedString(
julia> collect(StyledStrings.eachregion(AnnotatedString(
"hey there", [(1:3, :face => :bold), (5:9, :face => :italic)])))
3-element Vector{Tuple{SubString{String}, Vector{Pair{Symbol, Any}}}}:
("hey", [:face => :bold])
Expand Down
4 changes: 2 additions & 2 deletions test/runtests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -3,9 +3,9 @@
using Test

using StyledStrings: StyledStrings, Legacy, SimpleColor, FACES, Face,
@styled_str, styled, StyledMarkup, eachregion, getface, addface!, loadface!, resetfaces!
@styled_str, styled, StyledMarkup, eachregion, getface, addface!, loadface!, resetfaces!,
AnnotatedString, AnnotatedChar, AnnotatedIOBuffer, annotations
using .StyledMarkup: MalformedStylingMacro
using Base: AnnotatedString, AnnotatedChar, AnnotatedIOBuffer, annotations

const NON_STDLIB_TESTS = Main == @__MODULE__
if NON_STDLIB_TESTS
Expand Down
Loading