LOWDOWN_DOC_PARSE(3)

NAME
lowdown_doc_parse - parse a Markdown document into an AST

LIBRARY
liblowdown

SYNOPSIS
#include <sys/queue.h>
#include <stdio.h>
#include <lowdown.h>
struct lowdown_node *
lowdown_doc_parse(hdoc *doc, size_t *maxn, const char *input, size_t inputsz);

DESCRIPTION
Parses a lowdown(5) document from input of length inputsz into an AST. This function may be invoked multiple times with a single doc. The returned node is always of type LOWDOWN_ROOT, with maxn set to one greater than the highest node identifier of the returned tree.

The AST is a tree of struct lowdown_node nodes, the structure consisting of:

    struct lowdown_node {
    	enum lowdown_rndrt type;
    	size_t id;
    	enum lowdown_chng chng;
    	union {
    		struct rndr_meta {
    			hbuf key;
    		} rndr_doc_header;
    		struct rndr_list {
    			enum hlist_fl flags;
    			char start[10];
    		} rndr_list;
    		struct rndr_listitem {
    			enum hlist_fl flags;
    			uint32_t num;
    		} rndr_listitem;
    		struct rndr_header {
    			size_t level;
    		} rndr_header;
    		struct rndr_normal_text {
    			hbuf text;
    		} rndr_normal_text;
    		struct rndr_entity {
    			hbuf text;
    		} rndr_entity;
    		struct rndr_autolink {
    			hbuf link;
    			hbuf text;
    			enum halink_type type;
    		} rndr_autolink;
    		struct rndr_raw_html {
    			hbuf text;
    		} rndr_raw_html;
    		struct rndr_link {
    			hbuf link;
    			hbuf title;
    		} rndr_link;
    		struct rndr_blockcode {
    			hbuf text;
    			hbuf lang;
    		} rndr_blockcode;
    		struct rndr_codespan {
    			hbuf text;
    		} rndr_codespan;
    		struct rndr_table_header {
    			enum htbl_flags *flags;
    			size_t columns;
    		} rndr_table_header;
    		struct rndr_table_cell {
    			enum htbl_flags flags;
    			size_t col;
    			size_t columns;
    		} rndr_table_cell;
    		struct rndr_footnote_def {
    			size_t num;
    		} rndr_footnote_def;
    		struct rndr_footnote_ref {
    			size_t num;
    		} rndr_footnote_ref;
    		struct rndr_image {
    			hbuf link;
    			hbuf title;
    			hbuf dims;
    			hbuf alt;
    		} rndr_image;
    		struct rndr_math {
    			int blockmode;
    		} rndr_math;
    		struct rndr_blockhtml {
    			hbuf text;
    		} rndr_blockhtml;
    	};
    	struct lowdown_node *parent;
    	struct lowdown_nodeq children;
    	TAILQ_ENTRY(lowdown_node) entries;
    };

The field names consist of the following:

enum lowdown_rndrt type
    The node type. (Described below.)

size_t id
    An identifier unique within the document. This can be used as a table index since the number is assigned from a monotonically increasing point during the parse.

struct lowdown_node *parent
    The parent of the node, or NULL at the root.

enum lowdown_chng chng
    Change tracking: whether this node was inserted (LOWDOWN_CHNG_INSERT), deleted (LOWDOWN_CHNG_DELETE), or neither (LOWDOWN_CHNG_NONE).

struct lowdown_nodeq children
    A possibly-empty list of child nodes.

entries
    The tail queue queue(3) FIELDNAME.

<anon union>
    An anonymous union of type-specific structures. See below for a description of each one.

The nodes may be one of the following types, with default rendering in HTML5 to illustrate functionality.

LOWDOWN_ROOT
    The root of the document. This is always the topmost node, and the only node where the parent field is NULL.

LOWDOWN_BLOCKCODE
    A block-level (and possibly language-specific) snippet of code. Described by the <pre><code> elements.

LOWDOWN_BLOCKHTML
    A block-level snippet of HTML. This is simply opaque HTML content. (Only if configured during parse.)

LOWDOWN_BLOCKQUOTE
    A block-level quotation. Described by the <blockquote> element.

LOWDOWN_CODESPAN
    A snippet of code. Described by the <code> element.

LOWDOWN_DOC_FOOTER
    Closes out the document opened in LOWDOWN_DOC_HEADER.

LOWDOWN_DOC_HEADER
    A header with data gathered from document metadata (if configured). Described by the <head> element. (Only if configured during parse.)

LOWDOWN_DOUBLE_EMPHASIS
    Bold (or otherwise notable) content. Described by the <strong> element.

LOWDOWN_EMPHASIS
    Italic (or otherwise notable) content. Described by the <em> element.

LOWDOWN_ENTITY
    An HTML entity, which may either be named or numeric.

LOWDOWN_FOOTNOTE_DEF
    A footnote within a LOWDOWN_FOOTNOTES_BLOCK node. Described by the <li id="fnXX"> element. (Only if configured during parse.)

LOWDOWN_FOOTNOTE_REF
    A reference to a LOWDOWN_FOOTNOTE_DEF. Described by the <sup><a> elements. (Only if configured during parse.)

LOWDOWN_FOOTNOTES_BLOCK
    A block of footnotes. Described by the <div class="footnotes"><hr /><ol> elements. (Only if configured during parse.)

LOWDOWN_HEADER
    A block-level header. Described by one of <h1> through <h6>. (The level is bound at 6.)

LOWDOWN_HIGHLIGHT
    Marked test. Described by the <mark> element. (Only if configured during parse.)

LOWDOWN_HRULE
    A horizontal line. Described by <hr>.

LOWDOWN_IMAGE
    An image. Described by the <img> element.

LOWDOWN_LINEBREAK
    A hard line-break within a block context. Described by the <br> element.

LOWDOWN_LINK
    A link to external media. Described by the <a> element.

LOWDOWN_LINK_AUTO
    Like LOWDOWN_LINK, except inferred from text content. Described by the <a> element. (Only if configured during parse.)

LOWDOWN_LIST
    A block-level list enclosure. Described by <ul> or <ol>.

LOWDOWN_LISTITEM
    A block-level list item, always appearing within a LOWDOWN_LIST. Described by <li>.

LOWDOWN_MATH_BLOCK
    A block (or inline) of mathematical text in LaTeX format. Described within \[xx\] or \(xx\). This is usually (in HTML) externally handled by a JavaScript renderer. (Only if configured during parse.)

LOWDOWN_META
    Meta-data keys and values. (Only if configured during parse.) These are described by elements in the <head> element.

LOWDOWN_NORMAL_TEXT
    Normal text content.

LOWDOWN_PARAGRAPH
    A block-level paragraph. Described by the <p> element.

LOWDOWN_RAW_HTML
    An inline of raw HTML. (Only if configured during parse.)

LOWDOWN_STRIKETHROUGH
    Content struck through. Described by the <del> element. (Only if configured during parse.)

LOWDOWN_SUPERSCRIPT
    A superscript. Described by the <sup> element. (Only if configured during parse.)

LOWDOWN_TABLE_BLOCK
    A table block. Described by <table>. (Only if configured during parse.)

LOWDOWN_TABLE_BODY
    A table body section. Described by <tbody>. Parent is always LOWDOWN_TABLE_BLOCK. (Only if configured during parse.)

LOWDOWN_TABLE_CELL
    A table cell. Described by <td> or <th> if in the header. Parent is always LOWDOWN_TABLE_ROW. (Only if configured during parse.)

LOWDOWN_TABLE_HEADER
    A table header section. Described by <thead>. Parent is always LOWDOWN_TABLE_BLOCK. (Only if configured during parse.)

LOWDOWN_TABLE_ROW
    A table row. Described by <tr>. Parent is always LOWDOWN_TABLE_HEADER or LOWDOWN_TABLE_BODY. (Only if configured during parse.)

LOWDOWN_TRIPLE_EMPHASIS
    Combination of LOWDOWN_EMPHASIS and LOWDOWN_DOUBLE_EMPHASIS.

The following anonymous union structures correspond to certain nodes. Note that all buffers may be zero-length.

rndr_meta
    Each LOWDOWN_META key-value pair is represented. The keys are lower-case without spaces or non-ASCII characters. Enclosed nodes may consist only of LOWDOWN_NORMAL_TEXT and LOWDOWN_ENTITY.

rndr_list
    For LOWDOWN_DOC_LIST, consists of a bitfield flags that may be set to HLIST_FL_ORDERED for an ordered list. If start is a non-empty string, it is the first list item value.

rndr_listitem
    For LOWDOWN_DOC_LISTITEM, consists of a bitfield flags that may be set to HLIST_FL_ORDERED (an ordered list) and/or HLIST_FL_BLOCK (list elements contain block elements). The num is the index in an ordered list.

rndr_header
    For LOWDOWN_HEADER, the level of the header (1–6).

rndr_normal_text
    The basic text content for LOWDOWN_NORMAL_TEXT.

rndr_entity
    For LOWDOWN_ENTITY, the entity text.

rndr_autolink
    For LOWDOWN_LINK_AUTO, the link address as link; the textual component text; and the link type type, which may be one of HALINK_EMAIL for e-mail links and HALINK_NORMAL otherwise. Any buffer may be empty-sized.

rndr_raw_html
    For LOWDOWN_RAW_HTML, the opaque HTML text.

rndr_link
    Like rndr_autolink.

rndr_blockcode
    For LOWDOWN_BLOCKCODE, the opaque text of the block and the optional lang of the code language.

rndr_codespan
    The opaque text of the contents.

rndr_table_header
    For LOWDOWN_TABLE_HEADER, the number of columns in each row and the per-column flags, which may be bits of HTBL_FL_ALIGN_LEFT, HTBL_FL_ALIGN_RIGHT, or HTBL_FL_ALIGN_CENTER when masked with HTBL_FL_ALIGNMASK; or HTBL_FL_HEADER.

rndr_table_cell
    For LOWDOWN_TABLE_CELL, the current col colum number out of columns. See rndr_table_header for a description of the bits in flags.

rndr_footnote_def
    For LOWDOWN_FOOTNOTE_DEF, the footnote number num.

rndr_footnote_ref
    For a LOWDOWN_FOOTNOTE_REF reference to a LOWDOWN_FOOTNOTE_DEF, the footnote number num.

rndr_image
    For LOWDOWN_IMAGE, the image address link, the image title title, dimensions NxN (width by height) in dims, and alternate text alt.

rndr_math
    For LOWDOWN_MATH, the mode of display displaymode: if 1, in-line math; if 2, multi-line.

rndr_blockhtml
    For LOWDOWN_BLOCKHTML, the opaque HTML text.

RETURN VALUES
Returns the root of the parse tree. The pointer is never NULL.

SEE ALSO
lowdown(3)