diff options
| -rw-r--r-- | man/man3/cmark.3 | 314 |
1 files changed, 206 insertions, 108 deletions
diff --git a/man/man3/cmark.3 b/man/man3/cmark.3 index f294099..786e3aa 100644 --- a/man/man3/cmark.3 +++ b/man/man3/cmark.3 @@ -1,4 +1,4 @@ -.TH cmark 3 "January 10, 2016" "LOCAL" "Library Functions Manual" +.TH cmark 3 "January 11, 2016" "LOCAL" "Library Functions Manual" .SH NAME .PP @@ -13,13 +13,87 @@ Simple Interface \fIchar *\f[] \fBcmark_markdown_to_html\f[](\fIconst char *text\f[], \fIsize_t len\f[], \fIint options\f[]) .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 +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 +.PP +.nf +\fC +.RS 0n +typedef enum { + /* Error status */ + CMARK_NODE_NONE, + + /* Block */ + CMARK_NODE_DOCUMENT, + CMARK_NODE_BLOCK_QUOTE, + CMARK_NODE_LIST, + CMARK_NODE_ITEM, + CMARK_NODE_CODE_BLOCK, + CMARK_NODE_HTML_BLOCK, + CMARK_NODE_CUSTOM_BLOCK, + CMARK_NODE_PARAGRAPH, + CMARK_NODE_HEADING, + CMARK_NODE_THEMATIC_BREAK, + + CMARK_NODE_FIRST_BLOCK = CMARK_NODE_DOCUMENT, + CMARK_NODE_LAST_BLOCK = CMARK_NODE_THEMATIC_BREAK, + + /* Inline */ + CMARK_NODE_TEXT, + CMARK_NODE_SOFTBREAK, + CMARK_NODE_LINEBREAK, + CMARK_NODE_CODE, + CMARK_NODE_HTML_INLINE, + CMARK_NODE_CUSTOM_INLINE, + 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 + + + +.PP +.nf +\fC +.RS 0n +typedef enum { + CMARK_NO_LIST, + CMARK_BULLET_LIST, + CMARK_ORDERED_LIST +} cmark_list_type; +.RE +\f[] +.fi + + + +.PP +.nf +\fC +.RS 0n +typedef enum { + CMARK_NO_DELIM, + CMARK_PERIOD_DELIM, + CMARK_PAREN_DELIM +} cmark_delim_type; +.RE +\f[] +.fi + + + .SS Creating and Destroying Nodes @@ -27,9 +101,9 @@ Creating and Destroying Nodes \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\[cq]s responsibility -to assign. +Creates a new node of type \f[I]type\f[]. Note that the node may +have other required properties, which it is the caller\[cq]s +responsibility to assign. .PP \fIvoid\f[] \fBcmark_node_free\f[](\fIcmark_node *node\f[]) @@ -44,15 +118,15 @@ Tree Traversal \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. +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[]) .PP -Returns the previous node in the sequence after \f[I]node\f[], or NULL -if there is none. +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[]) @@ -64,31 +138,33 @@ Returns the parent of \f[I]node\f[], or NULL if there is none. \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. +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. +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 headings into regular paragraphs. +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 headings into regular paragraphs. .IP .nf \f[C] @@ -107,8 +183,8 @@ usage_example(cmark_node *root) { \f[] .fi .PP -Iterators will never return \f[C]EXIT\f[] events for leaf nodes, which -are nodes of type: +Iterators will never return \f[C]EXIT\f[] events for leaf nodes, +which are nodes of type: .IP \[bu] 2 CMARK_NODE_HTML_BLOCK .IP \[bu] 2 @@ -130,12 +206,28 @@ Nodes must only be modified after an \f[C]EXIT\f[] event, or an \f[C]ENTER\f[] event for leaf nodes. .PP +.nf +\fC +.RS 0n +typedef enum { + CMARK_EVENT_NONE, + CMARK_EVENT_DONE, + CMARK_EVENT_ENTER, + CMARK_EVENT_EXIT +} cmark_event_type; +.RE +\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[]. The current node and -event type are undefined until \f[C]cmark_iter_next\f[] is called for -the first time. +Creates a new iterator starting at \f[I]root\f[]. The current +node and event type are undefined until \f[C]cmark_iter_next\f[] +is called for the first time. .PP \fIvoid\f[] \fBcmark_iter_free\f[](\fIcmark_iter *iter\f[]) @@ -173,9 +265,9 @@ Returns the root node. \fIvoid\f[] \fBcmark_iter_reset\f[](\fIcmark_iter *iter\f[], \fIcmark_node *current\f[], \fIcmark_event_type event_type\f[]) .PP -Resets the iterator so that the current node is \f[I]current\f[] and the -event type is \f[I]event_type\f[]. The new current node must be a -descendant of the root node or the root node itself. +Resets the iterator so that the current node is \f[I]current\f[] +and the event type is \f[I]event_type\f[]. The new current node +must be a descendant of the root node or the root node itself. .SS Accessors @@ -190,63 +282,64 @@ Returns the user data of \f[I]node\f[]. \fIint\f[] \fBcmark_node_set_user_data\f[](\fIcmark_node *node\f[], \fIvoid *user_data\f[]) .PP -Sets arbitrary user data for \f[I]node\f[]. Returns 1 on success, 0 on -failure. +Sets arbitrary user data for \f[I]node\f[]. Returns 1 on success, +0 on failure. .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. +Returns the type of \f[I]node\f[], or \f[C]CMARK_NODE_NONE\f[] on +error. .PP \fIconst char *\f[] \fBcmark_node_get_type_string\f[](\fIcmark_node *node\f[]) .PP -Like \f[I]cmark_node_get_type\f[], but returns a string representation -of the type, or \f[C]"<unknown>"\f[]. +Like \f[I]cmark_node_get_type\f[], but returns a string +representation of the type, or \f[C]"<unknown>"\f[]. .PP \fIconst char *\f[] \fBcmark_node_get_literal\f[](\fIcmark_node *node\f[]) .PP -Returns the string contents of \f[I]node\f[], or an empty string if none -is set. +Returns the string contents of \f[I]node\f[], or an empty string +if none is set. .PP \fIint\f[] \fBcmark_node_set_literal\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. +Sets the string contents of \f[I]node\f[]. Returns 1 on success, +0 on failure. .PP \fIint\f[] \fBcmark_node_get_heading_level\f[](\fIcmark_node *node\f[]) .PP -Returns the heading level of \f[I]node\f[], or 0 if \f[I]node\f[] is not -a heading. +Returns the heading level of \f[I]node\f[], or 0 if \f[I]node\f[] +is not a heading. .PP \fIint\f[] \fBcmark_node_set_heading_level\f[](\fIcmark_node *node\f[], \fIint level\f[]) .PP -Sets the heading level of \f[I]node\f[], returning 1 on success and 0 on -error. +Sets the heading 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. +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. +Sets the list type of \f[I]node\f[], returning 1 on success and 0 +on error. .PP \fIcmark_delim_type\f[] \fBcmark_node_get_list_delim\f[](\fIcmark_node *node\f[]) @@ -259,22 +352,22 @@ Returns the list delimiter type of \f[I]node\f[], or \fIint\f[] \fBcmark_node_set_list_delim\f[](\fIcmark_node *node\f[], \fIcmark_delim_type delim\f[]) .PP -Sets the list delimiter type of \f[I]node\f[], returning 1 on success -and 0 on error. +Sets the list delimiter 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. +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. +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[]) @@ -286,8 +379,8 @@ Returns 1 if \f[I]node\f[] is a tight list, 0 otherwise. \fIint\f[] \fBcmark_node_set_list_tight\f[](\fIcmark_node *node\f[], \fIint tight\f[]) .PP -Sets the \[lq]tightness\[rq] of a list. Returns 1 on success, 0 on -failure. +Sets the \[lq]tightness\[rq] of a list. Returns 1 on success, 0 +on failure. .PP \fIconst char *\f[] \fBcmark_node_get_fence_info\f[](\fIcmark_node *node\f[]) @@ -299,66 +392,66 @@ Returns the info string from a fenced code block. \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. +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 -Returns the URL of a link or image \f[I]node\f[], or an empty string if -no URL is set. +Returns the URL of a link or image \f[I]node\f[], or an empty +string if no URL is set. .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. +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 -Returns the title of a link or image \f[I]node\f[], or an empty string -if no title is set. +Returns the title of a link or image \f[I]node\f[], or an empty +string if no title is set. .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. +Sets the title of a link or image \f[I]node\f[]. Returns 1 on +success, 0 on failure. .PP \fIconst char *\f[] \fBcmark_node_get_on_enter\f[](\fIcmark_node *node\f[]) .PP -Returns the literal \[lq]on enter\[rq] text for a custom \f[I]node\f[], -or an empty string if no on_enter is set. +Returns the literal \[lq]on enter\[rq] text for a custom +\f[I]node\f[], or an empty string if no on_enter is set. .PP \fIint\f[] \fBcmark_node_set_on_enter\f[](\fIcmark_node *node\f[], \fIconst char *on_enter\f[]) .PP Sets the literal text to render \[lq]on enter\[rq] for a custom -\f[I]node\f[]. Any children of the node will be rendered after this -text. Returns 1 on success 0 on failure. +\f[I]node\f[]. Any children of the node will be rendered after +this text. Returns 1 on success 0 on failure. .PP \fIconst char *\f[] \fBcmark_node_get_on_exit\f[](\fIcmark_node *node\f[]) .PP -Returns the literal \[lq]on exit\[rq] text for a custom \f[I]node\f[], -or an empty string if no on_exit is set. +Returns the literal \[lq]on exit\[rq] text for a custom +\f[I]node\f[], or an empty string if no on_exit is set. .PP \fIint\f[] \fBcmark_node_set_on_exit\f[](\fIcmark_node *node\f[], \fIconst char *on_exit\f[]) .PP Sets the literal text to render \[lq]on exit\[rq] for a custom -\f[I]node\f[]. Any children of the node will be rendered before this -text. Returns 1 on success 0 on failure. +\f[I]node\f[]. Any children of the node will be rendered before +this text. Returns 1 on success 0 on failure. .PP \fIint\f[] \fBcmark_node_get_start_line\f[](\fIcmark_node *node\f[]) @@ -391,43 +484,44 @@ Tree Manipulation \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.) +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. +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. +Inserts \f[I]sibling\f[] after \f[I]node\f[]. Returns 1 on +success, 0 on failure. .PP \fIint\f[] \fBcmark_node_replace\f[](\fIcmark_node *oldnode\f[], \fIcmark_node *newnode\f[]) .PP -Replaces \f[I]oldnode\f[] with \f[I]newnode\f[] and frees the memory -used by \f[I]oldnode\f[]. Returns 1 on success, 0 on failure. +Replaces \f[I]oldnode\f[] with \f[I]newnode\f[] and frees the +memory used by \f[I]oldnode\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. +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. +Adds \f[I]child\f[] to the end of the children of \f[I]node\f[]. +Returns 1 on success, 0 on failure. .PP \fIvoid\f[] \fBcmark_consolidate_text_nodes\f[](\fIcmark_node *root\f[]) @@ -492,15 +586,15 @@ Finish parsing and return a pointer to a tree of nodes. \fIcmark_node *\f[] \fBcmark_parse_document\f[](\fIconst char *buffer\f[], \fIsize_t len\f[], \fIint options\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. +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[], \fIint options\f[]) .PP -Parse a CommonMark document in file \f[I]f\f[], returning a pointer to a -tree of nodes. +Parse a CommonMark document in file \f[I]f\f[], returning a +pointer to a tree of nodes. .SS Rendering @@ -515,14 +609,15 @@ Render a \f[I]node\f[] tree as XML. \fIchar *\f[] \fBcmark_render_html\f[](\fIcmark_node *root\f[], \fIint options\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. +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[], \fIint options\f[], \fIint width\f[]) .PP -Render a \f[I]node\f[] tree as a groff man page, without the header. +Render a \f[I]node\f[] tree as a groff man page, without the +header. .PP \fIchar *\f[] \fBcmark_render_commonmark\f[](\fIcmark_node *root\f[], \fIint options\f[], \fIint width\f[]) @@ -564,7 +659,8 @@ Options affecting rendering .fi .PP -Include a \f[C]data\-sourcepos\f[] attribute on all block elements. +Include a \f[C]data\-sourcepos\f[] attribute on all block +elements. .PP .nf @@ -589,10 +685,11 @@ Render \f[C]softbreak\f[] elements as hard line breaks. .PP Suppress raw HTML and unsafe links (\f[C]javascript:\f[], -\f[C]vbscript:\f[], \f[C]file:\f[], and \f[C]data:\f[], except for -\f[C]image/png\f[], \f[C]image/gif\f[], \f[C]image/jpeg\f[], or -\f[C]image/webp\f[] mime types). Raw HTML is replaced by a placeholder -HTML comment. Unsafe links are replaced by empty strings. +\f[C]vbscript:\f[], \f[C]file:\f[], and \f[C]data:\f[], except +for \f[C]image/png\f[], \f[C]image/gif\f[], \f[C]image/jpeg\f[], +or \f[C]image/webp\f[] mime types). Raw HTML is replaced by a +placeholder HTML comment. Unsafe links are replaced by empty +strings. .SS Options affecting parsing @@ -619,8 +716,8 @@ Normalize tree by consolidating adjacent text nodes. .fi .PP -Validate UTF\-8 in the input before parsing, replacing illegal sequences -with the replacement character U+FFFD. +Validate UTF\-8 in the input before parsing, replacing illegal +sequences with the replacement character U+FFFD. .PP .nf @@ -642,8 +739,8 @@ Version information \fIint\f[] \fBcmark_version\f[](\fI\f[]) .PP -The library version as integer for runtime checks. Also available as -macro CMARK_VERSION for compile time checks. +The library version as integer for runtime checks. Also available +as macro CMARK_VERSION for compile time checks. .IP \[bu] 2 Bits 16\-23 contain the major version. .IP \[bu] 2 @@ -651,14 +748,15 @@ Bits 8\-15 contain the minor version. .IP \[bu] 2 Bits 0\-7 contain the patchlevel. .PP -In hexadecimal format, the number 0x010203 represents version 1.2.3. +In hexadecimal format, the number 0x010203 represents version +1.2.3. .PP \fIconst char *\f[] \fBcmark_version_string\f[](\fI\f[]) .PP -The library version string for runtime checks. Also available as macro -CMARK_VERSION_STRING for compile time checks. +The library version string for runtime checks. Also available as +macro CMARK_VERSION_STRING for compile time checks. .SH AUTHORS |