Docile.Formats
Methods [Exported]
parsedocs(::Docile.Formats.Format{F<:Docile.Formats.AbstractFormatter}, raw, mod, obj) ¶
Parsing hook for docstring parsing.
Example:
import Docile.Formats, Markdown
const (fmt, md) = (Docile.Formats, Markdown)
fmt.parsedocs(::fmt.Format{fmt.MarkdownFormatter}, raw, mod, obj) = md.parse(raw)
When registering a package the format is then provided to PackageData
.
Arguments:
raw
: Unparsed docstring extracted from source code.mod
: Module where the docstring and object are defined.obj
: Object that the docstring is associated with.
source: Docile/src/Formats/formatting.jl:27
Methods [Internal]
applymeta(name, body, mod, obj) ¶
Apply nesting to body of metamacro when defined otherwise treat as raw text.
source: Docile/src/Formats/metaparse.jl:79
extractmeta!(text::AbstractString, mod::Module, obj) ¶
Run all 'metamacros' found in a raw docstring and return the resulting string.
source: Docile/src/Formats/metaparse.jl:63
isprefix(io::IO, chars) ¶
Does the buffer io
begin with the given prefix chars?
source: Docile/src/Formats/metaparse.jl:124
isvalid(s::AbstractString) ¶
Check that a MetaMacro
's name
is a valid identifier.
Throws a MetaMacroNameError
if the string s
is not valid.
source: Docile/src/Formats/metaparse.jl:28
readbracketed(io::IO) ¶
Extract to a string the text between matching brackets (
and )
.
Throws a ParseError
when unmatched brackets are encountered.
source: Docile/src/Formats/metaparse.jl:136
tryextract(io::IO) ¶
Try extract an embedded metadata entry name from buffer at current position.
Returns the empty symbol symbol("")
when the current position is not the start
of an embedded metadata entry.
source: Docile/src/Formats/metaparse.jl:97
Types [Internal]
Docile.Formats.MetaMacro{name, raw} ¶
Dispatch type for the metamacro
function. name
is a Symbol
.
When raw == true
the metamacro with identifier name
with not behave as a
standard metamacro. Nesting will be disabled and must be implemented explicitly
using Docile.Formats.extractmeta!
as follows:
function Formats.metamacro(::META"name"raw, body, mod, obj)
# ...
body = Docile.Formats.extractmeta!(body, mod, obj)
# ...
end
source: Docile/src/Formats/metaparse.jl:17
Macros [Internal]
@META_str(args...) ¶
Shorthand syntax for defining MetaMacro{<name>}
s as META"<name>"
.
Example
import Docile: Cache
import Docile.Formats: metamacro, @META_str
metamacro(::META"author", body, mod, obj) = isempty(body) ?
Cache.findmeta(mod, obj, :author) :
(Cache.getmeta(mod, obj)[:author = strip(body)]; "")
By default metamacros are 'nestable', which means that an author may
write metamacros within metamacros. In some cases this may not be the
behaviour that is desired. Nesting can be disabled on a per-definition
basis by using the raw
modifier:
metamacro(::META"name"raw, body, mod, obj) = ...