Lua wrapper for libcmark, CommonMark parsing and rendering library
To install: luarocks install 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 and
cmark_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
endThe 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, see lcmark.
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 tablemake 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.