Fix type piracy using the Typst wrapper

jakobjpeters · May 20, 2024 · e49247e · e49247e
1 parent 3f607c9
commit e49247e
Show file tree

Hide file tree

Showing 6 changed files with 75 additions and 49 deletions.
diff --git a/docs/make.jl b/docs/make.jl
@@ -2,7 +2,7 @@
 using Documenter: HTML, DocMeta.setdocmeta!, deploydocs, makedocs
 using Luxor: Drawing, finish, julia_blue, julia_green, julia_purple, julia_red, rect, sethue
 using Typstry
-using Typstry: enclose, examples, join_with, preamble, typst_mime
+using Typstry: Typst, enclose, examples, join_with, preamble, typst_mime
 
 const assets = joinpath(@__DIR__, "src", "assets")
 const strings = joinpath(assets, "strings")
@@ -62,7 +62,7 @@ open(strings * ".typ"; truncate = true) do file
         print(file, ", `", t, "`,", is_vector || is_matrix ? "\n        " : " ")
         join_with(file, modes, ", ") do file, mode
             enclose((file, v) ->
-                show(IOContext(file, :mode => mode, :depth => 2), typst_mime, v),
+                show(IOContext(file, :mode => mode, :depth => 2), typst_mime, Typst(v)),
             file, v, (
                 if mode == math; ("\$",)
                 else ("[" * (mode == code ? "#" : ""), "]")

diff --git a/docs/src/getting_started.md b/docs/src/getting_started.md
@@ -4,7 +4,7 @@
 ## Examples
 
 This Typst source file and corresponding document were generated from Julia using \
-[`show(::IO, ::MIME"text/typst", ::Any)`](@ref) to print Julia values
+[`show(::IO, ::MIME"text/typst", ::Union{Typst, TypstString})`](@ref) to print Julia values
 to Typst format and a [`TypstCommand`](@ref) to render it.
 
 A [`Mode`](@ref) specifies the current Typst context.

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -26,7 +26,7 @@ julia> using Typstry
 julia> show_typst(IOContext(stdout, :mode => code), 'a')
 "'a'"
 
-julia> show(stdout, "text/typst", [true 1; 1.0 [Any[true 1; 1.0 nothing]]])
+julia> show(stdout, "text/typst", Typst([true 1; 1.0 [Any[true 1; 1.0 nothing]]]))
 $ mat(
     "true", 1;
     1.0, mat(
@@ -52,22 +52,22 @@ typst`compile input.typ output.pdf`
 
 ### Strings
 
-- Convert Julia values to Typst format using `show(::IO, ::MIME"text/typst", ::Any)`
-    - Specify Julia settings and Typst parameters in the `IOContext`
-    - Implement `show_typst` for custom types
-- Create and manipulate `TypstString`s
-    - Interpolate formatted values using `@typst_str`
+- Convert Julia values to Typst format
+    - Specify Julia settings and Typst parameters
+    - Implement formatting for custom types
+- Create and manipulate Typst formatted strings
+    - Interpolate formatted values
     - Render in Pluto.jl notebooks
 
 ### Commands
 
-- Construct `TypstCommand`s with a `Vector{String}` or using `@typst_cmd`
+- Construct Typst commands
 - Render documents using the Typst compiler
     - Use the [JuliaMono](https://github.com/cormullion/juliamono) typeface
 
 ### Planned
 
-- Implement `show_typst` for more types
+- Implement Typst formatting for more types
     - `Base`
     - Standard Library
     - Package extensions

diff --git a/docs/src/manual/strings.md b/docs/src/manual/strings.md
@@ -5,6 +5,7 @@
 
 ```@docs
 Mode
+Typst
 TypstString
 @typst_str
 show_typst
@@ -22,6 +23,6 @@ ncodeunits
 pointer
 repr
 show(::IO, ::TypstString)
-show(::IO, ::MIME"text/typst", ::Any)
+show(::IO, ::MIME"text/typst", ::Union{Typst, TypstString})
 show(::IO, ::Union{MIME"application/pdf", MIME"image/png", MIME"image/svg+xml"}, ::TypstString)
 ```
diff --git a/src/Typstry.jl b/src/Typstry.jl
@@ -18,7 +18,7 @@ export TypstCommand, TypstError, @typst_cmd
 
 include("strings.jl")
 
-export Mode, TypstString, @typst_str, julia_mono, code, markup, math, show_typst, typst_text
+export Mode, Typst, TypstString, @typst_str, julia_mono, code, markup, math, show_typst, typst_text
 
 @compile_workload for (x, _) in examples
     typst"\(x)"

diff --git a/src/strings.jl b/src/strings.jl
@@ -17,15 +17,34 @@ math = 2
 """
 @enum Mode code markup math
 
+"""
+    Typst{T}
+    Typst(::T)
+
+A wrapper used to pass values to
+[`show(::IO,\u00A0::MIME"text/typst",\u00A0::Union{Typst,\u00A0TypstString})`](@ref).
+
+```jldoctest
+julia> Typst(1)
+Typst{Int64}(1)
+
+julia> Typst("a")
+Typst{String}("a")
+```
+"""
+struct Typst{T}
+    value::T
+end
+
 """
     TypstString <: AbstractString
-    TypstString(::Any; kwargs...)
+    TypstString(::Any; context...)
 
 Convert the value to a Typst formatted string.
 
 Optional Julia settings and Typst parameters are passed to
-[`show(::IO,\u00A0::MIME"text/typst",\u00A0::Any)`](@ref) in an `IOContext`.
-See also [`show_typst`](@ref) for a list of supported types.
+[`show(::IO,\u00A0::MIME"text/typst",\u00A0::Union{Typst,\u00A0TypstString})`](@ref)
+in an `IOContext`. See also [`show_typst`](@ref) for a list of supported types.
 
 !!! info
     This type implements the `String` interface.
@@ -43,14 +62,8 @@ typst"\\\"\\\\\\"a\\\\\\"\\\""
 struct TypstString <: AbstractString
     text::String
 
-    TypstString(x::T; settings...) where T = new(
-        if T <: Union{TypstString, TypstText} x.text
-        else
-            buffer = IOBuffer()
-            show(IOContext(buffer, settings...), typst_mime, x)
-            String(take!(buffer))
-        end
-    )
+    TypstString(x::T; context...) where T = new(T <: Union{TypstString, TypstText} ?
+        x.text : sprint(show, typst_mime, Typst(x); context = (context...,)))
 end
 
 """
@@ -66,7 +79,8 @@ Values may be interpolated by calling the `TypstString` constructor,
 except using a backslash instead of the type name.
 
 !!! tip
-    Use [`show(::IO,\u00A0::MIME"text/typst",\u00A0::Any)`](@ref) to print directly to an `IO`.
+    Pring directly to an `IO` using
+    [`show(::IO,\u00A0::MIME"text/typst",\u00A0::Union{Typst,\u00A0TypstString})`](@ref).
 
     See also the performance tip to [Avoid string interpolation for I/O]
     (https://docs.julialang.org/en/v1/manual/performance-tips/#Avoid-string-interpolation-for-I/O).
@@ -113,8 +127,8 @@ end
 """
     TypstText(::Any)
 
-A wrapper used by [`typst_text`](@ref) to construct a [`TypstString`](@ref) with
-`print` instead of [`show(::IO,\u00A0::MIME"text/typst",\u00A0::Any)`](@ref).
+A wrapper used by [`typst_text`](@ref) to construct a [`TypstString`](@ref) with `print` instead
+of [`show(::IO,\u00A0::MIME"text/typst",\u00A0::Union{Typst,\u00A0TypstString})`](@ref).
 
 # Examples
 ```jldoctest
@@ -135,7 +149,7 @@ end
     examples
 
 A constant `Vector` of Julia values and their corresponding `Type`s implemented for
-[`show(::IO,\u00A0::MIME"text/plain",\u00A0::Any)`](@ref).
+[`show(::IO,\u00A0::MIME"text/plain",\u00A0::Union{Typst,\u00A0TypstString})`](@ref).
 """
 const examples = [
     'a' => AbstractChar,
@@ -160,7 +174,7 @@ const examples = [
     preamble
 
 A constant used at the beginning of Typst source files generated by
-[`show(::IO,\u00A0::Union{MIME"image/png",\u00A0MIME"image/svg+xml"},\u00A0::TypstString)`](@ref).
+[`show(::IO,\u00A0::Union{MIME"application/pdf",\u00A0MIME"image/png",\u00A0MIME"image/svg+xml"},\u00A0::TypstString)`](@ref).
 
 # Examples
 ```jldoctest
@@ -177,8 +191,8 @@ const preamble = """
 """
     settings
 
-A constant `NamedTuple` containing the default `IOContext` settings
-for [`show(::IO,\u00A0::MIME"text/typst",\u00A0::Any)`](@ref).
+A constant `NamedTuple` containing the default `IOContext` settings used in
+[`show(::IO,\u00A0::MIME"text/typst",\u00A0::Union{Typst,\u00A0TypstString})`](@ref).
 
 # Examples
 ```jldoctest
@@ -419,15 +433,14 @@ Settings are used in Julia to format the [`TypstString`](@ref) and can be any ty
 Parameters are passed to a function in the Typst source file and must be a `String`
 with the same name as in Typst, except that dashes are replaced with underscores.
 
-For additiona information on parameters and settings,
-see also [`show(::IO,\u00A0::MIME"text/typst",\u00A0::Any)`](@ref)
-and the [Typst Documentation](https://typst.app/docs/),
-respectively.
+For additional information on parameters and settings, see also
+[`show(::IO,\u00A0::MIME"text/typst",\u00A0::Union{Typst,\u00A0TypstString})`](@ref)
+and the [Typst Documentation](https://typst.app/docs/), respectively.
 
 For additional information on printing and rendering, see also [Examples](@ref).
 
 !!! tip
-    Implement this function for new types to specify their Typst formatting.
+    Implement this function for custom types to specify their Typst formatting.
 
 !!! warning
     This function's methods are incomplete.
@@ -450,6 +463,7 @@ For additional information on printing and rendering, see also [Examples](@ref).
 | `Signed`                                                  |                                         |                                                         |
 | `StepRangeLen{<:Integer,\u00A0<:Integer,\u00A0<:Integer}` | `:mode`                                 |                                                         |
 | `Text`                                                    | `:mode`                                 |                                                         |
+| `Typst`                                                   | ...                                     | ...                                                     |
 | `TypstString`                                             |                                         |                                                         |
 
 # Examples
@@ -530,6 +544,7 @@ function show_typst(io, x::Text)
     code_mode(io)
     print_quoted(io, repr(x)) # TODO: remove string allocation
 end
+show_typst(io, x::Typst) = show_typst(io, x.value)
 show_typst(io, x::Union{AbstractFloat, Signed, TypstString}) = print(io, x)
 function show_typst(io, x::Union{
     OrdinalRange{<:Integer, <:Integer},
@@ -556,11 +571,7 @@ Unsigned
     typst_text(::Any)
 
 Construct a [`TypstString`](@ref) using `print` instead of
-[`show(::IO,\u00A0::MIME"text/typst",\u00A0::Any)`](@ref).
-
-!!! tip
-    Use `typst_text` to print text to a `TypstString`.
-    Use `Text` to render the text in a Typst document.
+[`show(::IO,\u00A0::MIME"text/typst",\u00A0::Union{Typst,\u00A0TypstString})`](@ref).
 
 !!! warning
     Unescaped control characters in `TypstString`s may
@@ -691,13 +702,17 @@ function show(io::IO, ts::TypstString)
 end
 
 """
-    show(::IO, ::MIME"text/typst", ::Any)
+    show(::IO, ::MIME"text/typst", ::Union{Typst, TypstString})
 
 Print to Typst format.
 
 Provides default settings for [`show_typst`](@ref)
 which may be specified in an `IOContext`.
-Custom default settings may be provided by implementing methods for new types.
+
+See also [`Typst`](@ref) and [`TypstString`](@ref).
+
+!!! tip
+    Implement this function for custom types to specify their default settings and parameters.
 
 | Setting   | Default                  | Type           | Description                                                                                                                                                             |
 |:----------|:-------------------------|:---------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
@@ -708,15 +723,18 @@ Custom default settings may be provided by implementing methods for new types.
 
 # Examples
 ```jldoctest
-julia> show(stdout, "text/typst", "a")
+julia> show(stdout, "text/typst", typst"a")
+a
+
+julia> show(stdout, "text/typst", Typst("a"))
 "a"
 
-julia> show(IOContext(stdout, :mode => code), "text/typst", "a")
+julia> show(IOContext(stdout, :mode => code), "text/typst", Typst("a"))
 "\\\"a\\\""
 ```
 """
-show(io::IO, ::MIME"text/typst", x) =
-    show_typst(IOContext(io, map(key -> key => get(io, key, settings[key]), keys(settings))...), x)
+show(io::IO, ::MIME"text/typst", t::Union{Typst, TypstString}) =
+    show_typst(IOContext(io, map(key -> key => get(io, key, settings[key]), keys(settings))...), t)
 
 """
     show(::IO, ::Union{
@@ -726,8 +744,15 @@ show(io::IO, ::MIME"text/typst", x) =
 Print to Portable Document Format (PDF),
 Portable Network Graphics (PNG), or Scalable Vector Graphics (SVG) format.
 
-Environments such as Pluto.jl notebooks use this
-function to render [`TypstString`](@ref)s to a document.
+The corresponding Typst source file begins with this preamble:
+
+```typst
+$preamble
+```
+
+!!! note
+    Environments such as Pluto.jl notebooks use this
+    function to render [`TypstString`](@ref)s to a document.
 """
 function show(io::IO, m::Union{
     MIME"application/pdf", MIME"image/png", MIME"image/svg+xml"