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.