GitHub - jgm/cmark-lua: Lua bindings to libcmark CommonMark parser (original) (raw)

cmark-lua

Lua wrapper for libcmark, CommonMark parsing and rendering library

To install: luarocks install cmark.

cmark

cmark exposes the entire API of libcmark, as documented in the cmark(3) man page. Basic usage:

local cmark = require("cmark")

local doc = cmark.parse_document(input, string.len(input), cmark.OPT_DEFAULT) local html = cmark.render_html(doc, cmark.OPT_DEFAULT)

For convenience, constants and functions are renamed so that an initial cmark_ or CMARK_ is omitted: for example,CMARK_NODE_PARAGRAPH is exposed as cmark.NODE_PARAGRAPH andcmark_parse_document as cmark.parse_document.

Two additional functions are provided:

cmark.parse_string(s, opts) is like parse_document, but does not require you to specify the length of the input string.

cmark.walk(node) wraps cmark's iterator interface in a format that is more lua-esque. Usage example:

local links = 0 for cur, entering, node_type in cmark.walk(doc) do if node_type == cmark.NODE_LINK and not entering then links = links + 1 -- insert " (link #n)" after the link: local t = cmark.node_new(NODE_TEXT) cmark.node_set_literal(t, string.format(" (link #%d)", links)) cmark.node_insert_after(cur, t) end end

The memory allocated by libcmark for node objects must be freed by the calling program by calling cmark.node_free on the document node. (This will automatically free all children as well.)

In addition, a C function

void push_cmark_node(lua_State *L, cmark_node *node)

is exported to make it easier to use these functions from the C API.

For a higher-level interface, seelcmark.

cmark.builder

A special module, cmark.builder, is provided to make it easier to construct cmark nodes.

Usage examples:

local b = require 'cmark.builder' local mydoc = b.document{ b.paragraph{ b.text "Hello ", b.emph{ b.text "world" }, b.link{ url = "http://example.com", b.text "!" } } }

The arguments to builder functions are generally tables. Key-value pairs are used to set attributes, and the other values are used as children or literal string content, as appropriate.

The library will interpret values as the appropriate types, when possible. So, you can supply a single value instead of an array. And you can supply a string instead of an inline node, or a node instead of a list item. The following is equivalent to the example above:

local mydoc = b.document{ b.paragraph{ "Hello ", b.emph "world", b.link{ url="http://example.com", "!"} }}

The builder functions are

builder.document{block1, block2, ...} builder.block_quote{block1, block2, ...} builder.ordered_list{delim = cmark.PAREN_DELIM, item1, item2, ...} -- attributes: delim, start, tight builder.bullet_list -- attributes: tight builder.item builder.code_block -- attributes: info builder.html_block builder.custom_block -- attributes: on_enter, on_exit builder.thematic_break builder.heading -- attributes: level builder.paragraph builder.text builder.emph builder.strong builder.link -- attributes: title, url builder.image -- attributes: title, url builder.linebreak builder.softbreak builder.code builder.html_inline builder.custom_inline -- attributes: on_enter, on_exit builder.get_children(node) -- returns children of a node as a table

For developers

make builds the rock and installs it locally.

make test runs some tests. These are in test.t. You'll need the prove executable and the lua-TestMore rock.

make update will update the C sources and spec test from the../cmark directory.