This module exports the main definitions and methods for working with Ondim.

Here, we shall call by a "node" any type that implements OndimNode, which means it is compatible with the Ondim template system. Many types can be used as nodes at once, and in fact in a single format like HTML there are multiple types that are regarded as nodes (the HTML document, element, node and attribute are different types implementing the class). In other formats like Pandoc the necessity of this approach is more evident, since there are not only the Block and Inline types but also metadata types and so on.

Each node may have an name, which is simply a Text string and acessed by the identify class method. A node which has an name is meant to be expanded by the template system, and this is done by applying it to an Expansion bound to the same name in the local state.

Another thing specified by the OndimNode instances is how different node types are found inside a given node type, and this information is used to recursively expand the templates in a macro-like fashion. The main sorts of "substructures" of a node are its children and attributes, which are acessed via the children and attributes methods, repectively. Since those are part of the class, they can be used for writing expansions that don't depend on the node type. Those polymorphic expansions are special enough to have a type alias for them: PolyExpansion. The nice thing about them is that you can write templating code only once and expand templates of any format, while still being able to specify expansions for a given type.

So the main function in this module is probably expandNode, which when applied to a node runs the expansion machinery and turns the node into something else.

Expansions are just Haskell functions of type t -> Ondim s [t], and can be defined inside Haskell code. The expansion's argument is the node whose name matched the name of the expansion (the "caller"), and the expansion returns a list of nodes that will replace it in the expansion process. Expansions are bound to names in the Ondim monad state, and they can also be organized into more nested Namespaces. See Ondim.State for more information on how to manipulate the state.

The state also store templates, which are essentialy values of type OndimNode t => t and are used to store data like text and file templates. Every template stored in the state is also seen as an expansion, the expansion that ignores the caller argument and returns the expanded template:

templateToExpansion tpl = const $ expandNode tpl

This is not the true definition --- the caller node is not actually ignored, instead it may be acessed from the template via the state in the caller namespace. Most importantly, templates may be loaded from disk, see the module Ondim.Loading.

For dealing with exceptions and debug data, see the module Ondim.Debug.