diff options
| -rw-r--r-- | man/make_man_page.py | 5 | ||||
| -rw-r--r-- | man/man3/cmark.3 | 337 | ||||
| -rw-r--r-- | src/cmark.h | 155 |
3 files changed, 332 insertions, 165 deletions
diff --git a/man/make_man_page.py b/man/make_man_page.py index dd226e6..2a7f9ab 100644 --- a/man/make_man_page.py +++ b/man/make_man_page.py @@ -47,7 +47,7 @@ single_quote_re = re.compile("(?<!\w)'([^']+)'(?!\w)") double_quote_re = re.compile("(?<!\w)''([^']+)''(?!\w)") def handle_quotes(s): - return re.sub(double_quote_re, '\\\\fB\g<1>\\\\f[]', re.sub(single_quote_re, '\\\\fI\g<1>\\\\f[]', s)) + return re.sub(double_quote_re, '**\g<1>**', re.sub(single_quote_re, '*\g<1>*', s)) typedef = False mdlines = [] @@ -91,6 +91,7 @@ with open(sourcefile, 'r') as cmarkh: mdlines.append('\n') rawsig = ''.join(sig) m = function_re.match(rawsig) + mdlines.append('.PP\n') if m: mdlines.append('\\fI' + m.group('type') + '\\f[]' + ' ') mdlines.append('\\fB' + m.group('name') + '\\f[]' + '(') @@ -107,7 +108,7 @@ with open(sourcefile, 'r') as cmarkh: mdlines.append('.RE\n\\f[]\n.fi\n') if len(mdlines) > 0 and mdlines[-1] != '\n': mdlines.append('\n') - mdlines += chunk + mdlines += md2man(''.join(chunk)) mdlines.append('\n') chunk = [] sig = [] diff --git a/man/man3/cmark.3 b/man/man3/cmark.3 index 68ce528..589ffe1 100644 --- a/man/man3/cmark.3 +++ b/man/man3/cmark.3 @@ -9,6 +9,7 @@ DESCRIPTION .SS Simple Interface +.PP .nf \fC .RS 0n @@ -17,281 +18,383 @@ Simple Interface \f[] .fi +.PP Current version of library. +.PP \fIchar *\f[] \fBcmark_markdown_to_html\f[](\fIconst char *text\f[], \fIint len\f[]) -Convert \fItext\f[] (assumed to be a UTF-8 encoded string with length -\fIlen\f[] from CommonMark Markdown to HTML, returning a null-terminated, -UTF-8-encoded string. +.PP +Convert \f[I]text\f[] (assumed to be a UTF\-8 encoded string with length +\f[I]len\f[] from CommonMark Markdown to HTML, returning a null\-terminated, +UTF\-8\-encoded string. .SS Node Structure -.nf -\fC -.RS 0n -typedef enum { - /* Error status */ - CMARK_NODE_NONE, - - /* Block */ - CMARK_NODE_DOCUMENT, - CMARK_NODE_BLOCK_QUOTE, - CMARK_NODE_LIST, - CMARK_NODE_LIST_ITEM, - CMARK_NODE_CODE_BLOCK, - CMARK_NODE_HTML, - CMARK_NODE_PARAGRAPH, - CMARK_NODE_HEADER, - CMARK_NODE_HRULE, - - CMARK_NODE_FIRST_BLOCK = CMARK_NODE_DOCUMENT, - CMARK_NODE_LAST_BLOCK = CMARK_NODE_HRULE, - - /* Inline */ - CMARK_NODE_TEXT, - CMARK_NODE_SOFTBREAK, - CMARK_NODE_LINEBREAK, - CMARK_NODE_INLINE_CODE, - CMARK_NODE_INLINE_HTML, - CMARK_NODE_EMPH, - CMARK_NODE_STRONG, - CMARK_NODE_LINK, - CMARK_NODE_IMAGE, - - CMARK_NODE_FIRST_INLINE = CMARK_NODE_TEXT, - CMARK_NODE_LAST_INLINE = CMARK_NODE_IMAGE, -} cmark_node_type; -.RE -\f[] -.fi - - - -.nf -\fC -.RS 0n -typedef enum { - CMARK_NO_LIST, - CMARK_BULLET_LIST, - CMARK_ORDERED_LIST -} cmark_list_type; -.RE -\f[] -.fi - - - -.nf -\fC -.RS 0n -typedef enum { - CMARK_PERIOD_DELIM, - CMARK_PAREN_DELIM -} cmark_delim_type; -.RE -\f[] -.fi - - - .SS Creating and Destroying Nodes +.PP \fIcmark_node*\f[] \fBcmark_node_new\f[](\fIcmark_node_type type\f[]) +.PP +Creates a new node of type \f[I]type\f[]\&. Note that the node may have +other required properties, which it is the caller's responsibility +to assign. - +.PP \fIvoid\f[] \fBcmark_node_free\f[](\fIcmark_node *node\f[]) - +.PP +Frees the memory allocated for a node. .SS Tree Traversal -\fIcmark_node*\f[] \fBcmark_node_previous\f[](\fIcmark_node *node\f[]) +.PP +\fIcmark_node*\f[] \fBcmark_node_next\f[](\fIcmark_node *node\f[]) +.PP +Returns the next node in the sequence after \f[I]node\f[], or NULL if +there is none. +.PP +\fIcmark_node*\f[] \fBcmark_node_previous\f[](\fIcmark_node *node\f[]) -\fIcmark_node*\f[] \fBcmark_node_parent\f[](\fIcmark_node *node\f[]) +.PP +Returns the previous node in the sequence after \f[I]node\f[], or NULL if +there is none. +.PP +\fIcmark_node*\f[] \fBcmark_node_parent\f[](\fIcmark_node *node\f[]) +.PP +Returns the parent of \f[I]node\f[], or NULL if there is none. +.PP \fIcmark_node*\f[] \fBcmark_node_first_child\f[](\fIcmark_node *node\f[]) +.PP +Returns the first child of \f[I]node\f[], or NULL if \f[I]node\f[] has no children. - +.PP \fIcmark_node*\f[] \fBcmark_node_last_child\f[](\fIcmark_node *node\f[]) - +.PP +Returns the last child of \f[I]node\f[], or NULL if \f[I]node\f[] has no children. .SS Iterator +.PP +An iterator will walk through a tree of nodes, starting from a root +node, returning one node at a time, together with information about +whether the node is being entered or exited. The iterator will +first descend to a child node, if there is one. When there is no +child, the iterator will go to the next sibling. When there is no +next sibling, the iterator will return to the parent (but with +a \f[I]cmark_event_type\f[] of \f[C]CMARK_EVENT_EXIT\f[]). The iterator will +return \f[C]CMARK_EVENT_DONE\f[] when it reaches the root node again. +One natural application is an HTML renderer, where an \f[C]ENTER\f[] event +outputs an open tag and an \f[C]EXIT\f[] event outputs a close tag. +An iterator might also be used to transform an AST in some systematic +way, for example, turning all level\-3 headers into regular paragraphs. +.IP +.nf +\f[C] +void +usage_example(cmark_node *root) { + cmark_event_type ev_type; + cmark_iter *iter = cmark_iter_new(root); + + while ((ev_type = cmark_iter_next(iter)) != CMARK_EVENT_DONE) { + cmark_node *cur = cmark_iter_get_node(iter); + // Do something with `cur` and `ev_type` + } + + cmark_iter_free(iter); +} +\f[] +.fi +.PP \fIcmark_iter*\f[] \fBcmark_iter_new\f[](\fIcmark_node *root\f[]) +.PP +Creates a new iterator starting at \f[I]root\f[]\&. - +.PP \fIvoid\f[] \fBcmark_iter_free\f[](\fIcmark_iter *iter\f[]) +.PP +Frees the memory allocated for an iterator. - +.PP \fIcmark_event_type\f[] \fBcmark_iter_next\f[](\fIcmark_iter *iter\f[]) +.PP +Returns the event type (\f[C]CMARK_EVENT_ENTER\f[], \f[C]CMARK_EVENT_EXIT\f[], +or \f[C]CMARK_EVENT_DONE\f[]) for the next node. - +.PP \fIcmark_node*\f[] \fBcmark_iter_get_node\f[](\fIcmark_iter *iter\f[]) - +.PP +Returns the next node in the sequence described above. .SS Accessors +.PP \fIcmark_node_type\f[] \fBcmark_node_get_type\f[](\fIcmark_node *node\f[]) +.PP +Returns the type of \f[I]node\f[], or \f[C]CMARK_NODE_NONE\f[] on error. - +.PP \fIconst char*\f[] \fBcmark_node_get_string_content\f[](\fIcmark_node *node\f[]) +.PP +Returns the string contents of \f[I]node\f[], or NULL if none. - +.PP \fIint\f[] \fBcmark_node_set_string_content\f[](\fIcmark_node *node\f[], \fIconst char *content\f[]) +.PP +Sets the string contents of \f[I]node\f[]\&. Returns 1 on success, +0 on failure. - +.PP \fIint\f[] \fBcmark_node_get_header_level\f[](\fIcmark_node *node\f[]) +.PP +Returns the header level of \f[I]node\f[], or 0 if \f[I]node\f[] is not a header. - +.PP \fIint\f[] \fBcmark_node_set_header_level\f[](\fIcmark_node *node\f[], \fIint level\f[]) +.PP +Sets the header level of \f[I]node\f[], returning 1 on success and 0 on error. - +.PP \fIcmark_list_type\f[] \fBcmark_node_get_list_type\f[](\fIcmark_node *node\f[]) +.PP +Returns the list type of \f[I]node\f[], or \f[C]CMARK_NO_LIST\f[] if \f[I]node\f[] +is not a list. - +.PP \fIint\f[] \fBcmark_node_set_list_type\f[](\fIcmark_node *node\f[], \fIcmark_list_type type\f[]) +.PP +Sets the list type of \f[I]node\f[], returning 1 on success and 0 on error. - +.PP \fIint\f[] \fBcmark_node_get_list_start\f[](\fIcmark_node *node\f[]) +.PP +Returns starting number of \f[I]node\f[], if it is an ordered list, otherwise 0. - +.PP \fIint\f[] \fBcmark_node_set_list_start\f[](\fIcmark_node *node\f[], \fIint start\f[]) +.PP +Sets starting number of \f[I]node\f[], if it is an ordered list. Returns 1 +on success, 0 on failure. - +.PP \fIint\f[] \fBcmark_node_get_list_tight\f[](\fIcmark_node *node\f[]) +.PP +Returns 1 if \f[I]node\f[] is a tight list, 0 otherwise. - +.PP \fIint\f[] \fBcmark_node_set_list_tight\f[](\fIcmark_node *node\f[], \fIint tight\f[]) +.PP +Sets the "tightness" of a list. Returns 1 on success, 0 on failure. - +.PP \fIconst char*\f[] \fBcmark_node_get_fence_info\f[](\fIcmark_node *node\f[]) +.PP +Returns the info string from a fenced code block, or NULL if none. - +.PP \fIint\f[] \fBcmark_node_set_fence_info\f[](\fIcmark_node *node\f[], \fIconst char *info\f[]) +.PP +Sets the info string in a fenced code block, returning 1 on +success and 0 on failure. - +.PP \fIconst char*\f[] \fBcmark_node_get_url\f[](\fIcmark_node *node\f[]) +.PP +Gets the URL of a link or image \f[I]node\f[], or NULL if none. - +.PP \fIint\f[] \fBcmark_node_set_url\f[](\fIcmark_node *node\f[], \fIconst char *url\f[]) +.PP +Sets the URL of a link or image \f[I]node\f[]\&. Returns 1 on success, +0 on failure. - +.PP \fIconst char*\f[] \fBcmark_node_get_title\f[](\fIcmark_node *node\f[]) +.PP +Gets the title of a link or image \f[I]node\f[], or NULL if none. - +.PP \fIint\f[] \fBcmark_node_set_title\f[](\fIcmark_node *node\f[], \fIconst char *title\f[]) +.PP +Sets the title of a link or image \f[I]node\f[]\&. Returns 1 on success, +0 on failure. - +.PP \fIint\f[] \fBcmark_node_get_start_line\f[](\fIcmark_node *node\f[]) +.PP +Returns the line on which \f[I]node\f[] begins. - +.PP \fIint\f[] \fBcmark_node_get_start_column\f[](\fIcmark_node *node\f[]) +.PP +Returns the column at which \f[I]node\f[] begins. - +.PP \fIint\f[] \fBcmark_node_get_end_line\f[](\fIcmark_node *node\f[]) - +.PP +Returns the line on which \f[I]node\f[] ends. .SS Tree Manipulation +.PP \fIvoid\f[] \fBcmark_node_unlink\f[](\fIcmark_node *node\f[]) +.PP +Unlinks a \f[I]node\f[], removing it from the tree, but not freeing its +memory. (Use \f[I]cmark_node_free\f[] for that.) - +.PP \fIint\f[] \fBcmark_node_insert_before\f[](\fIcmark_node *node\f[], \fIcmark_node *sibling\f[]) +.PP +Inserts \f[I]sibling\f[] before \f[I]node\f[]\&. Returns 1 on success, 0 on failure. - +.PP \fIint\f[] \fBcmark_node_insert_after\f[](\fIcmark_node *node\f[], \fIcmark_node *sibling\f[]) +.PP +Inserts \f[I]sibling\f[] after \f[I]node\f[]\&. Returns 1 on success, 0 on failure. - +.PP \fIint\f[] \fBcmark_node_prepend_child\f[](\fIcmark_node *node\f[], \fIcmark_node *child\f[]) +.PP +Adds \f[I]child\f[] to the beginning of the children of \f[I]node\f[]\&. +Returns 1 on success, 0 on failure. - +.PP \fIint\f[] \fBcmark_node_append_child\f[](\fIcmark_node *node\f[], \fIcmark_node *child\f[]) - +.PP +Adds \f[I]child\f[] to the end of the children of \f[I]node\f[]\&. +Returns 1 on success, 0 on failure. .SS Parsing +.PP +Simple interface: +.IP +.nf +\f[C] +cmark_node *document = cmark_parse_document("Hello *world*", 12); +\f[] +.fi +.PP +Streaming interface: +.IP +.nf +\f[C] +cmark_parser *parser = cmark_parser_new(); +FILE *fp = fopen("myfile.md", "r"); +while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0) { + cmark_parser_feed(parser, buffer, bytes); + if (bytes < sizeof(buffer)) { + break; + } +} +document = cmark_parser_finish(parser); +cmark_parser_free(parser); +\f[] +.fi +.PP \fIcmark_parser *\f[] \fBcmark_parser_new\f[](\fI\f[]) +.PP +Creates a new parser object. - +.PP \fIvoid\f[] \fBcmark_parser_free\f[](\fIcmark_parser *parser\f[]) +.PP +Frees memory allocated for a parser object. - -\fIcmark_node *\f[] \fBcmark_parser_finish\f[](\fIcmark_parser *parser\f[]) - - - +.PP \fIvoid\f[] \fBcmark_parser_feed\f[](\fIcmark_parser *parser\f[], \fIconst char *buffer\f[], \fIsize_t len\f[]) +.PP +Feeds a string of length \f[I]len\f[] to \f[I]parser\f[]\&. +.PP +\fIcmark_node *\f[] \fBcmark_parser_finish\f[](\fIcmark_parser *parser\f[]) -\fIcmark_node *\f[] \fBcmark_parse_document\f[](\fIconst char *buffer\f[], \fIsize_t len\f[]) +.PP +Finish parsing and return a pointer to a tree of nodes. +.PP +\fIcmark_node *\f[] \fBcmark_parse_document\f[](\fIconst char *buffer\f[], \fIsize_t len\f[]) +.PP +Parse a CommonMark document in \f[I]buffer\f[] of length \f[I]len\f[]\&. +Returns a pointer to a tree of nodes. +.PP \fIcmark_node *\f[] \fBcmark_parse_file\f[](\fIFILE *f\f[]) - +.PP +Parse a CommonMark document in file \f[I]f\f[], returning a pointer to +a tree of nodes. .SS Rendering +.PP \fIchar *\f[] \fBcmark_render_ast\f[](\fIcmark_node *root\f[]) +.PP +Render a \f[I]node\f[] tree for debugging purposes, showing +the hierachy of nodes and their types and contents. - +.PP \fIchar *\f[] \fBcmark_render_html\f[](\fIcmark_node *root\f[]) +.PP +Render a \f[I]node\f[] tree as an HTML fragment. It is up to the user +to add an appropriate header and footer. - +.PP \fIchar *\f[] \fBcmark_render_man\f[](\fIcmark_node *root\f[]) - +.PP +Render a \f[I]node\f[] tree as a groff man page, without the header. .SH AUTHORS diff --git a/src/cmark.h b/src/cmark.h index 85dffa4..9de1037 100644 --- a/src/cmark.h +++ b/src/cmark.h @@ -91,12 +91,14 @@ typedef enum { * ## Creating and Destroying Nodes */ -/** +/** Creates a new node of type 'type'. Note that the node may have + * other required properties, which it is the caller's responsibility + * to assign. */ CMARK_EXPORT cmark_node* cmark_node_new(cmark_node_type type); -/** +/** Frees the memory allocated for a node. */ CMARK_EXPORT void cmark_node_free(cmark_node *node); @@ -105,52 +107,83 @@ cmark_node_free(cmark_node *node); * ## Tree Traversal */ +/** Returns the next node in the sequence after 'node', or NULL if + * there is none. + */ CMARK_EXPORT cmark_node* cmark_node_next(cmark_node *node); -/** +/** Returns the previous node in the sequence after 'node', or NULL if + * there is none. */ CMARK_EXPORT cmark_node* cmark_node_previous(cmark_node *node); -/** +/** Returns the parent of 'node', or NULL if there is none. */ CMARK_EXPORT cmark_node* cmark_node_parent(cmark_node *node); -/** +/** Returns the first child of 'node', or NULL if 'node' has no children. */ CMARK_EXPORT cmark_node* cmark_node_first_child(cmark_node *node); -/** +/** Returns the last child of 'node', or NULL if 'node' has no children. */ CMARK_EXPORT cmark_node* cmark_node_last_child(cmark_node *node); /** * ## Iterator + * + * An iterator will walk through a tree of nodes, starting from a root + * node, returning one node at a time, together with information about + * whether the node is being entered or exited. The iterator will + * first descend to a child node, if there is one. When there is no + * child, the iterator will go to the next sibling. When there is no + * next sibling, the iterator will return to the parent (but with + * a 'cmark_event_type' of `CMARK_EVENT_EXIT`). The iterator will + * return `CMARK_EVENT_DONE` when it reaches the root node again. + * One natural application is an HTML renderer, where an `ENTER` event + * outputs an open tag and an `EXIT` event outputs a close tag. + * An iterator might also be used to transform an AST in some systematic + * way, for example, turning all level-3 headers into regular paragraphs. + * + * void + * usage_example(cmark_node *root) { + * cmark_event_type ev_type; + * cmark_iter *iter = cmark_iter_new(root); + * + * while ((ev_type = cmark_iter_next(iter)) != CMARK_EVENT_DONE) { + * cmark_node *cur = cmark_iter_get_node(iter); + * // Do something with `cur` and `ev_type` + * } + * + * cmark_iter_free(iter); + * } */ -/** +/** Creates a new iterator starting at 'root'. */ CMARK_EXPORT cmark_iter* cmark_iter_new(cmark_node *root); -/** +/** Frees the memory allocated for an iterator. */ CMARK_EXPORT void cmark_iter_free(cmark_iter *iter); -/** +/** Returns the event type (`CMARK_EVENT_ENTER`, `CMARK_EVENT_EXIT`, + * or `CMARK_EVENT_DONE`) for the next node. */ CMARK_EXPORT cmark_event_type cmark_iter_next(cmark_iter *iter); -/** +/** Returns the next node in the sequence described above. */ CMARK_EXPORT cmark_node* @@ -160,102 +193,108 @@ cmark_iter_get_node(cmark_iter *iter); * ## Accessors */ -/** +/** Returns the type of 'node', or `CMARK_NODE_NONE` on error. */ CMARK_EXPORT cmark_node_type cmark_node_get_type(cmark_node *node); -/** +/** Returns the string contents of 'node', or NULL if none. */ CMARK_EXPORT const char* cmark_node_get_string_content(cmark_node *node); -/** +/** Sets the string contents of 'node'. Returns 1 on success, + * 0 on failure. */ CMARK_EXPORT int cmark_node_set_string_content(cmark_node *node, const char *content); -/** +/** Returns the header level of 'node', or 0 if 'node' is not a header. */ CMARK_EXPORT int cmark_node_get_header_level(cmark_node *node); -/** +/** Sets the header level of 'node', returning 1 on success and 0 on error. */ CMARK_EXPORT int cmark_node_set_header_level(cmark_node *node, int level); -/** +/** Returns the list type of 'node', or `CMARK_NO_LIST` if 'node' + * is not a list. */ CMARK_EXPORT cmark_list_type cmark_node_get_list_type(cmark_node *node); -/** +/** Sets the list type of 'node', returning 1 on success and 0 on error. */ CMARK_EXPORT int cmark_node_set_list_type(cmark_node *node, cmark_list_type type); -/** +/** Returns starting number of 'node', if it is an ordered list, otherwise 0. */ CMARK_EXPORT int cmark_node_get_list_start(cmark_node *node); -/** +/** Sets starting number of 'node', if it is an ordered list. Returns 1 + * on success, 0 on failure. */ CMARK_EXPORT int cmark_node_set_list_start(cmark_node *node, int start); -/** +/** Returns 1 if 'node' is a tight list, 0 otherwise. */ CMARK_EXPORT int cmark_node_get_list_tight(cmark_node *node); -/** +/** Sets the "tightness" of a list. Returns 1 on success, 0 on failure. */ CMARK_EXPORT int cmark_node_set_list_tight(cmark_node *node, int tight); -/** +/** Returns the info string from a fenced code block, or NULL if none. */ CMARK_EXPORT const char* cmark_node_get_fence_info(cmark_node *node); -/** +/** Sets the info string in a fenced code block, returning 1 on + * success and 0 on failure. */ CMARK_EXPORT int cmark_node_set_fence_info(cmark_node *node, const char *info); -/** +/** Gets the URL of a link or image 'node', or NULL if none. */ CMARK_EXPORT const char* cmark_node_get_url(cmark_node *node); -/** +/** Sets the URL of a link or image 'node'. Returns 1 on success, + * 0 on failure. */ CMARK_EXPORT int cmark_node_set_url(cmark_node *node, const char *url); -/** +/** Gets the title of a link or image 'node', or NULL if none. */ CMARK_EXPORT const char* cmark_node_get_title(cmark_node *node); -/** +/** Sets the title of a link or image 'node'. Returns 1 on success, + * 0 on failure. */ CMARK_EXPORT int cmark_node_set_title(cmark_node *node, const char *title); -/** +/** Returns the line on which 'node' begins. */ CMARK_EXPORT int cmark_node_get_start_line(cmark_node *node); -/** +/** Returns the column at which 'node' begins. */ CMARK_EXPORT int cmark_node_get_start_column(cmark_node *node); -/** +/** Returns the line on which 'node' ends. */ CMARK_EXPORT int cmark_node_get_end_line(cmark_node *node); @@ -264,61 +303,83 @@ cmark_node_get_end_line(cmark_node *node); * ## Tree Manipulation */ -/** +/** Unlinks a 'node', removing it from the tree, but not freeing its + * memory. (Use 'cmark_node_free' for that.) */ CMARK_EXPORT void cmark_node_unlink(cmark_node *node); -/** +/** Inserts 'sibling' before 'node'. Returns 1 on success, 0 on failure. */ CMARK_EXPORT int cmark_node_insert_before(cmark_node *node, cmark_node *sibling); -/** +/** Inserts 'sibling' after 'node'. Returns 1 on success, 0 on failure. */ CMARK_EXPORT int cmark_node_insert_after(cmark_node *node, cmark_node *sibling); -/** +/** Adds 'child' to the beginning of the children of 'node'. + * Returns 1 on success, 0 on failure. */ CMARK_EXPORT int cmark_node_prepend_child(cmark_node *node, cmark_node *child); -/** +/** Adds 'child' to the end of the children of 'node'. + * Returns 1 on success, 0 on failure. */ CMARK_EXPORT int cmark_node_append_child(cmark_node *node, cmark_node *child); /** * ## Parsing + * + * Simple interface: + * + * cmark_node *document = cmark_parse_document("Hello *world*", 12); + * + * Streaming interface: + * + * cmark_parser *parser = cmark_parser_new(); + * FILE *fp = fopen("myfile.md", "r"); + * while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0) { + * cmark_parser_feed(parser, buffer, bytes); + * if (bytes < sizeof(buffer)) { + * break; + * } + * } + * document = cmark_parser_finish(parser); + * cmark_parser_free(parser); */ -/** +/** Creates a new parser object. */ CMARK_EXPORT cmark_parser *cmark_parser_new(); -/** +/** Frees memory allocated for a parser object. */ CMARK_EXPORT void cmark_parser_free(cmark_parser *parser); -/** +/** Feeds a string of length 'len' to 'parser'. */ CMARK_EXPORT -cmark_node *cmark_parser_finish(cmark_parser *parser); +void cmark_parser_feed(cmark_parser *parser, const char *buffer, size_t len); -/** +/** Finish parsing and return a pointer to a tree of nodes. */ CMARK_EXPORT -void cmark_parser_feed(cmark_parser *parser, const char *buffer, size_t len); +cmark_node *cmark_parser_finish(cmark_parser *parser); -/** +/** Parse a CommonMark document in 'buffer' of length 'len'. + * Returns a pointer to a tree of nodes. */ CMARK_EXPORT cmark_node *cmark_parse_document(const char *buffer, size_t len); -/** +/** Parse a CommonMark document in file 'f', returning a pointer to + * a tree of nodes. */ CMARK_EXPORT cmark_node *cmark_parse_file(FILE *f); @@ -327,17 +388,19 @@ cmark_node *cmark_parse_file(FILE *f); * ## Rendering */ -/** +/** Render a 'node' tree for debugging purposes, showing + * the hierachy of nodes and their types and contents. */ CMARK_EXPORT char *cmark_render_ast(cmark_node *root); -/** +/** Render a 'node' tree as an HTML fragment. It is up to the user + * to add an appropriate header and footer. */ CMARK_EXPORT char *cmark_render_html(cmark_node *root); -/** +/** Render a 'node' tree as a groff man page, without the header. */ CMARK_EXPORT char *cmark_render_man(cmark_node *root); |