gomd

gomd package contains the core functionality for parsing and building a markup document tree using a pluggable engine system.

---

This package contains:

• The Engine interface, that allows to bring support for any markup language for tagging and building the content tree.
• The Runner struct, that allows to run an engine by tagging, cleaning tags and building the content tree using that engine.
• The ./types package:
  • ./types/tag.go: Includes the definition of Tag struct, that holds pieces of content of any text that are remarkable for a extension builder. They will be generated during the tagging phase.
  • ./types/extension.go: Definition of Extension interface and related types.
• Others helper subpackages:
  • ./iterator: Contains the Iterator[T], a generic thread-safe iterator for slices generic items, that provides methods for navigating through a collection of items, iterating over them or filtering based on certain conditions.
  • ./tree: Contains the Node structure, that allows to represent a document as a hierarchical tree of pieces of content. It not just enable to build complex document structures, but also to navigate trough parent-sibling-child relationships.

The engine based system allows for extensions to provide custom tagging rules and node builders, enabling flexible and extensible markup processing. The process involves two main steps:

1. Tagging: The input content is read and processed line by line and character by character to generate a series of tags based on the rules defined by the engine extensions.
2. Building: The generated tags are then used to construct a tree structure representing the markup document, using node builders provided by the engine extensions.

Engines

Engines are sets of definitions that allows to developers to bring support for any markup language, even those designed by they.

Each engine should implement the Engine interface to provide its own collection of types.Extensions and DefaultTag() function definition:

• Extensions(): Returns the list of available extensions for this engine.
• DefaultTag(): Returns the default tag that will be used as a fallback if no extension taggers is used.

Each extension should implement the types.Extension interface to provide its own parsing rules and node builders:

• CharTaggingRuleSet(): Returns a set of character-level tagging rules.
• LineTaggingRuleSet(): Returns a set of line-level tagging rules.
• TagCleaner(): Returns a function to clean or modify the generated tags.
• NodeBuilders(): Returns a set of node builders for constructing the tree.

Engine example

Basic example of a extension workflow:

1. The Engine definition includes some types.Extension that includes its own tagging rules and node builders.

2. In the tagging phase, the Runner applies the line and character tagging rules to the input content to generate tags. The extension's rules will receive lines and characters to tag accordingly. These rules should check if the content receives matches their criteria and return the appropriate tags, or skip if not.

3. After tagging, the Runner continues with clearing, by applying the TagCleaner function from the extension to clean or modify the generated tags as needed. It could be used to remove redundant tags, merge adjacent tags, or perform any other necessary adjustments before building the tree.

4. In the building phase, the Runner uses the node builders provided by the extension to construct the tree structure from the cleaned tags. Each node builder will attempt to decode tags into tree nodes based on the extension's logic. The extension can use the BuildTree function to generate child subtrees recursively using the extension builders. It should skip those tags that it cannot decode.

For more information about custom Engine's definition, follow the Engine example guide.