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, const char *input, size_t inputsz, struct lowdown_meta **meta, size_t *metasz);

DESCRIPTION
The lowdown_doc_parse function parses a Markdown document in the buffer input of length inputsz into an AST. It also fills in the metadata meta, if not NULL, with an array of length metasz. This function may be invoked multiple times with a single doc, which is reset upon each invocation.

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_doc_header {
    			struct lowdown_meta *m;
    			size_t msz;
    		} rndr_doc_header;
    		struct rndr_list {
    			enum hlist_fl flags;
    		} rndr_list;
    		struct rndr_listitem {
    			enum hlist_fl flags;
    			size_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 displaymode;
    		} 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 documented opened in LOWDOWN_DOC_HEADER. (Only if configured during parse.)

LOWDOWN_DOC_HEADER
    A header with data gathered from document metadata (if configured). Described by elements up to the <body>. (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_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_doc_header
    Valid for LOWDOWN_DOC_HEADER nodes. Consists of m, an array of raw metadata values of size msz.

rndr_list
    For LOWDOWN_DOC_LIST, 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).

rndr_listitem
    For LOWDOWN_DOC_LISTITEM, having the same flags of the LOWDOWN_DOC_LIST as well as num, 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)