Adopt Base's annotated types/functions as API

This opens the door to shuffling parts currently implemented in Base
into this stdlib without breaking any public APIs.

It would be nice to actually show the relevant Annotated* docstrings,
but unfortunately due to
JuliaDocs/Documenter.jl#1781 it's a bit
difficult to actually do so. We should re-visit this later.

docs/src/examples.md

@@ -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
@@ -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 StyledStrings.AnnotatedIOBuffer) is very handy, as you can [`read`](@ref Base.read) an [`AnnotatedString`](@ref StyledStrings.AnnotatedString) from it.
 
 ```@repl examples
-aio = StyledStrings.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), StyledStrings.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 = StyledStrings.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), StyledStrings.AnnotatedString)
+read(seekstart(aio), AnnotatedString)
 read(seekstart(aio), String)
 ```

docs/src/index.md

@@ -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.
@@ -41,7 +48,53 @@ using StyledStrings
 styled"{yellow:hello} {blue:there}"
 ```
 
-## Styling via [`AnnotatedString`](@ref StyledStrings.AnnotatedString)s
+## [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) added in Julia 1.11, 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)
 
@@ -153,7 +206,7 @@ them to the properties list afterwards, or use the convenient [Styled String
 literals](@ref stdlib-styledstring-literals).
 
 ```@repl demo
-str1 = StyledStrings.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)
@@ -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)
 ```

src/StyledStrings.jl

@@ -2,6 +2,8 @@
 
 module StyledStrings
 
+# 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
 
@@ -13,8 +15,7 @@ const ncodeunits = Compat.ncodeunits
 include("strings/strings.jl")
 include("terminfo.jl")
 
-using .AnnotatedStrings: AnnotatedString, AnnotatedChar, annotations,
-    annotate!, annotatedstring, AnnotatedIOBuffer
+using .AnnotatedStrings: AnnotatedString, AnnotatedChar, AnnotatedIOBuffer, annotations, annotate!, annotatedstring,
 
 include("faces.jl")
 include("regioniterator.jl")

src/regioniterator.jl

@@ -28,7 +28,7 @@ an iterator which provides each substring and the applicable annotations as a
 # Examples
 
 ```jldoctest
-julia> collect(StyledStrings.eachregion(StyledStrings.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])

test/runtests.jl

@@ -3,7 +3,8 @@
 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
 import StyledStrings.AnnotatedStrings: AnnotatedString, AnnotatedChar,
     AnnotatedIOBuffer, annotations