Represents a single directive implementation.
API to implement by the actual directive parser.
API to implement by the actual directive parser.
The methods of this trait correspond to the methods of the Parts
object,
only differing in return type.
Represents a single part (argument, field or body) of a directive.
API entry point for setting up a block directive.
Type class required for using the generic Builders
API with directives.
The public user API for specifying the required and optional parts of a directive (arguments, fields or body) together with optional converter/validator functions.
API entry point for setting up a span directive that can be used in substitution definitions.
API for creating directives, the extension mechanism of reStructuredText. The API did not aim to mimic the API of the original Python reference implementation. Instead the goal was to create an API that is idiomatic Scala, fully typesafe and as concise as possible. Yet it should be flexible enough to semantically support the options of the Python directives, so that ideally most existing Python directives could theoretically get ported to Laika.
Entry points are the
BlockDirective
andSpanDirective
objects. The Python reference parser does not make this distinction on the API level, but does this internally based on the context a directive is parsed in. Since Laika APIs are typesafe, the distinction is necessary since block level and span level directives create different types of document tree nodes. ASpanDirective
can only be used in a substitution definition which can then be used within flow elements. ABlockDirective
can be used directly in any location other block level content like paragraphs or lists can be used.A directive may consist of any combination of arguments, fields and body elements:
In the example above
arg1
andarg2
are arguments,field1
andfield2
are fields, and followed by body elements after a blank line. If there are no arguments or fields the blank line may be omitted. For the full specification, see http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#directives.For each of these directive elements, the API offers a method to specify whether the element is required or optional, and an optional function to convert or validate the parsed value.
Consider the following simple example of a directive with just one argument and a body:
The implementation of this directive could look like this:
The
argument()
method specifies a required argument of typeString
(since no conversion function was supplied). We need to set thewithWS
flag to true as an argument cannot have whitespace per default. TheblockContent
method specifies standard block content (any block-level elements that are supported in normal blocks, too) which results in a parsed value of typeSeq[Block]
. Finally you need to provide a function that accepts the results of the specified directive elements as parameters (of the corresponding type). Here we created a case class with a matching signature so can pass it directly as the target function. For a block directive the final result has to be of typeBlock
which theNote
class satisfies. Finally the directive gets registered with theReStructuredText
parser.If any conversion or validation is required on the individual parts of the directive they can be passed to the corresponding function:
The function has to provide an
Either[String, T]
as a result. ALeft
result will be interpreted as an error by the parser with the string being used as the message and an instance ofInvalidBlock
containing the validator message and the raw source of the directive will be inserted into the document tree. In this case the final function (Message
) will never be invoked. ARight
result will be used as an argument to the final function. Note how the case class now expects anInt
as the first parameter.Finally arguments and fields can also be optional. In case they are missing, the directive is still considered valid and
None
will be passed to your function:The argument may be missing, but if it is present it has to pass the specified validator.
In case of multiple arguments, the order you specify them is also the order in which they are parsed from the directive markup, with the only exception being that required arguments will always be parsed before optional ones, and arguments with whitespace need to come last.