Reference

GlossarEntry

An abstract type representing a term in a glossary.

Glossary{T} <: GlossarEntry

Fields

• terms::Dict{Symbol, T} : A dictionary mapping term names (as symbols) to terms of type T.

A glossary containing entries of type T where T is a subtype of GlossarEntry. As Glossary is a subtype of GlossarEntry, glossaries can be nested within other glossaries.

Constructor

Glossary(terms = Dict{Symbol, GlossarEntry}())

Creates a new (empty) Glossary instance.

@Glossary

A macro to introduce a glossary in the current Module as well as access functions current_glossary and current_glossary!, such that one can easily work with the current active glossary in a thread-safe manner.

Term{P} <: GlossarEntry

A concrete implementation of a term in a Glossary.

Fields

• properties::Dict{Symbol, P}: A dictionary of properties associated with the term

These properties can be

• Strings
• a function (args...; kwargs...) -> String
• other further (nested)) GlossarEntrys

Constructors

Term(properties = Dict{Symbol, Union{GlossarEntry, String, <:Function}}())

Create a new empty Term with the given name.

Term(name::String)

Create a new empty Term and directly set its :name.

getindex(glossary::Glossary, key::Symbol)
glossary[key::Symbol]

Access the entry at key in the given Glossary glossary.

getindex(term::Term, key::Symbol)
term[key::Symbol]

Access the property key in the given Term term.

add!(term::Term{P}, name::Symbol, value::Q) where {P, Q<:P}

Add a property name with value value for the given Term term.

define!(glossary::Glossary, key::Symbol, name::String)
define!(glossary::Glossary, key::Symbol, term::T) where {T <: GlossarEntry}
define!(wm::Module, key::Symbol, name::String)
define!(wm::Module, key::Symbol, term::T) where {T <: GlossarEntry}

Define a new Term in the Glossary glossary at key or a new Term(name) if just providing a string.

If a Module wm is given, the term is added to the current active glossary

define!(glossary::Glossary, key::Symbol, name::String)
define!(glossary::Glossary, key::Symbol, term::T) where {T <: GlossarEntry}
define!(wm::Module, key::Symbol, name::String)
define!(wm::Module, key::Symbol, term::T) where {T <: GlossarEntry}

Define a new Term in the Glossary glossary at key or a new Term(name) if just providing a string.

If a Module wm is given, the term is added to the current active glossary

define!(wm::Module, entry::Symbol, property::Symbol, args...)
define!(glossary::Glossary, entry::Symbol, property::Symbol, args...)

Define a property property with value args... for the Term at the key in Glossary glossary. If the term does not exist yet, it is created as an empty Term().

If a Module wm is given, the term is added to the current active glossary of that module.

define!(wm::Module, glossary::Glossary)

Set the current active glossary in the given module wm to glossary. Soo also current_glossary!.

define!(wm::Module, entry::Symbol, property::Symbol, args...)
define!(glossary::Glossary, entry::Symbol, property::Symbol, args...)

Define a property property with value args... for the Term at the key in Glossary glossary. If the term does not exist yet, it is created as an empty Term().

If a Module wm is given, the term is added to the current active glossary of that module.

define!(glossary::Glossary, key::Symbol, name::String)
define!(glossary::Glossary, key::Symbol, term::T) where {T <: GlossarEntry}
define!(wm::Module, key::Symbol, name::String)
define!(wm::Module, key::Symbol, term::T) where {T <: GlossarEntry}

Define a new Term in the Glossary glossary at key or a new Term(name) if just providing a string.

If a Module wm is given, the term is added to the current active glossary

define!(glossary::Glossary, key::Symbol, name::String)
define!(glossary::Glossary, key::Symbol, term::T) where {T <: GlossarEntry}
define!(wm::Module, key::Symbol, name::String)
define!(wm::Module, key::Symbol, term::T) where {T <: GlossarEntry}

Define a new Term in the Glossary glossary at key or a new Term(name) if just providing a string.

If a Module wm is given, the term is added to the current active glossary

@define!(entry::Symbol, name::String)
@define!(entry::Symbol, term::T) where {T <: GlossarEntry}
@define!(entry::Symbol, property::Symbol, args...)

A macro to define a new Term in the current_glossary of the current module or a property of a Term. If given a String name is provided, a new Term(name) is created and added to the current glossary.

Since this requires to call @__MODULE__, this is wrapped in a macro for convenience.

(glossary::Glossary)(query)

Given a Glossary instance, this allows to search for a query string in all its terms/entries by calling glossary(query).

Glossaries.Glossary(Dict{Symbol,Glossaries.GlossarEntry}([
    :title => Glossaries.Term("A simple Glossary Test"),
    :names => Glossaries.Glossary(Dict{Symbol,Glossaries.Term}([
        :Anton => Glossaries.Term("Anton Test"),
        :Egon => Glossaries.Term("Egon Est"),
        ])),
    ]))

search_in(entry::Term, query::AbstractString)

A small internal function to search in a term. To match the glossary search interface, this method returns a vector of length one containing the pair (nothing, term) if there is a match, otherwise an empty vector.

search_in(glossary::Glossary{T}, query) where {T}

Search for a query string in all terms/entries of a Glossary. Internally, this function calls occursin, so the query can be any needle that function accepts.

This returns an array of Pairs where the first element is the Symbol or vector of Symbols where to find the corresponding term, and the second element is the term itself.

Argument <: TermFormatter

A format representing a function argument.

Given a Term, this formatter expects the following properties to be set:

• :name: the name of the argument
• :type: the type of the argument (optional)
• :description: the description of the argument

This formatter prints

- `name::type`: description

Note that both the name and the type are set in code formatting.

This format additionally accepts two keyword arguments, that are hence are hence not passed to the underlying term:

• name::String="": if given, this name is used instead of the term's :name property.
• add_properties::Vector{Symbol}=Symbol[]: a vector of additional properties to add to the output after the description.

All arguments and keyword arguments other than these are passed to the underlying property formatting,

Fields

• show_type::Bool: whether to show the type of the argument

Constructor

Argument(show_type::Bool = true)
@Argument(show_type::Bool = true)

Create a new Argument formatter, where the macro variant takes the current modules glossary as default, see the different forms to call a formatter at TermFormatter.

Field <: TermFormatter

A format representing a struct field.

Given a Term, this formatter expects the following properties to be set:

• :name: the name of the field
• :type: the type of the field (optional)
• :description: the description of the field

This formatter prints

- `name::type`: description

Note that both the name and the type are set in code formatting.

This format additionally accepts two keyword arguments, that are hence are hence not passed to the underlying term:

• add_properties::Vector{Symbol}=Symbol[]: a vector of additional properties to add to the output after the description.
• name::String="": if given, this name is used instead of the term's :name property.
• type::String="": if given, this type is used instead of the term's :type property.

All arguments and keyword arguments other than these are passed to the underlying property formatting,

Fields

• show_type::Bool: whether to show the type of the argument

Constructor

Field(show_type::Bool = true)
@Field(show_type::Bool = true)

Create a new Field formatter, where the macro variant takes the current modules glossary as default, see the different forms to call a formatter at TermFormatter.

Keyword <: TermFormatter

A format representing a function keyword argument. Keyword arguments are passed to :type, and :default, and :description properties.

This formatter expects the following properties to be set:

• :name: the name of the keyword argument
• :type: the type of the keyword argument (optional)
• :default: the default value of the keyword argument (optional)
• :description: the description of the keyword argument

This formatter prints

- `name::type = default`: description

Note that the name, the type and the default are set in code formatting.

This format additionally accepts two keyword arguments, that are hence are hence not passed to the underlying term:

• name::String="": if given, this name is used instead of the term's :name property.
• add_properties::Vector{Symbol}=Symbol[]: a vector of additional properties to add to the output after the description.
• default::String="": the default value to use instead of the stored :default property.

All arguments and keyword arguments other than these are passed to the underlying property formatting,

Fields

• show_type::Bool: whether to show the type of the keyword argument

Constructor

Keyword(show_type::Bool = true)
@Keyword(show_type::Bool = true)

Create a new Keyword formatter, where the macro variant takes the current modules glossary as default, see the different forms to call a formatter at TermFormatter.

Math <: TermFormatter

print the math format. This formatter of a term passes all arguments and keyword arguments to the underlying term formatting for the :math property.

Constructor

Math()
@Math()

Create a new Math formatter, where the macro variant takes the current modules glossary as default, see the different forms to call a formatter at TermFormatter.

MathTerm <: TermFormatter

A formatter for mathematical terms.

This formatter expects the following properties to be set:

• :description: the description of the term
• :math: the math expression of the term

This formatter prints

description delimiter math delimiter

Fields

• delimiter::String: the delimiter to use around the math expression

Constructor

MathTerm(delimiter::String="``")

Use the default Julia documentation math delimiter ``...``.

Constructor

MathTerm(delimiter::String="``")
@MathTerm(delimiter::String="``")

Create a new MathTerm formatter, where the macro variant takes the current modules glossary as default, see the different forms to call a formatter at TermFormatter.

Plain <: TermFormatter

A plain format representing just the terms :name.

It then prints really just the name of the term.

Constructor

Plain()
@Plain()

Create a new Plain formatter, where the macro variant takes the current modules glossary as default, see the different forms to call a formatter at TermFormatter.

TermFormatter

A format for glossary terms. It always acts as a functor with the following methods:

(tf::TermFormatter)(keys::Vector{Symbol}; kwargs...)
(tf::TermFormatter)(glossary::Glossary, keys::Vector{Symbol}; kwargs...)

format all given keys of a glossary using the format tf. If the glossary is not given, the current_glossary is used, if no keys are given, all keys of the glossary are used.

(tf::TermFormatter)(key::Symbol, args...; kwargs...)
(tf::TermFormatter)(glossary::Glossary, key::Symbol, args...; kwargs...)

format the given key of a glossary using the format tf. If the glossary is not given, the current_glossary is used. All additional args... and kwargs... are passed to the underlying term formatting.

Formatting a single Term is done by calling

(tf::TermFormatter)(term::Term, args...; kwargs...)

where term is the Term to format. This should be implemented by all subtypes of TermFormatter. To what extend a certain formatter does support additional args... depends on the formatter. All should accept kwargs....

current_glossary()

Returns the current active glossary (or the last glossary created). Returns nothing if there is no current active glossary.

The access is thread-safe, since it also uses a lock.

current_glossary!(glossary)

Set glossary as the current active glossary.

The access is thread-safe, since it also uses a lock.