aboutsummaryrefslogtreecommitdiff
path: root/man/man3/cmark.3
blob: 5df89c33aeb0280997e77fed332b35a3e47d72df (plain)
  1. .TH cmark 3 "January 11, 2015" "LOCAL" "Library Functions Manual"
  2. .SH
  3. NAME
  4. .PP
  5. \f[B]cmark\f[] \- CommonMark parsing, manipulating, and rendering
  6. .SH
  7. DESCRIPTION
  8. .SS
  9. Simple Interface
  10. .PP
  11. .nf
  12. \fC
  13. .RS 0n
  14. #define CMARK_VERSION "0.1"
  15. .RE
  16. \f[]
  17. .fi
  18. .PP
  19. Current version of library.
  20. .PP
  21. \fIchar *\f[] \fBcmark_markdown_to_html\f[](\fIconst char *text\f[], \fIint len\f[])
  22. .PP
  23. Convert \f[I]text\f[] (assumed to be a UTF\-8 encoded string with length
  24. \f[I]len\f[] from CommonMark Markdown to HTML, returning a null\-terminated,
  25. UTF\-8\-encoded string.
  26. .SS
  27. Node Structure
  28. .SS
  29. Creating and Destroying Nodes
  30. .PP
  31. \fIcmark_node*\f[] \fBcmark_node_new\f[](\fIcmark_node_type type\f[])
  32. .PP
  33. Creates a new node of type \f[I]type\f[]\&. Note that the node may have
  34. other required properties, which it is the caller's responsibility
  35. to assign.
  36. .PP
  37. \fIvoid\f[] \fBcmark_node_free\f[](\fIcmark_node *node\f[])
  38. .PP
  39. Frees the memory allocated for a node.
  40. .SS
  41. Tree Traversal
  42. .PP
  43. \fIcmark_node*\f[] \fBcmark_node_next\f[](\fIcmark_node *node\f[])
  44. .PP
  45. Returns the next node in the sequence after \f[I]node\f[], or NULL if
  46. there is none.
  47. .PP
  48. \fIcmark_node*\f[] \fBcmark_node_previous\f[](\fIcmark_node *node\f[])
  49. .PP
  50. Returns the previous node in the sequence after \f[I]node\f[], or NULL if
  51. there is none.
  52. .PP
  53. \fIcmark_node*\f[] \fBcmark_node_parent\f[](\fIcmark_node *node\f[])
  54. .PP
  55. Returns the parent of \f[I]node\f[], or NULL if there is none.
  56. .PP
  57. \fIcmark_node*\f[] \fBcmark_node_first_child\f[](\fIcmark_node *node\f[])
  58. .PP
  59. Returns the first child of \f[I]node\f[], or NULL if \f[I]node\f[] has no children.
  60. .PP
  61. \fIcmark_node*\f[] \fBcmark_node_last_child\f[](\fIcmark_node *node\f[])
  62. .PP
  63. Returns the last child of \f[I]node\f[], or NULL if \f[I]node\f[] has no children.
  64. .SS
  65. Iterator
  66. .PP
  67. An iterator will walk through a tree of nodes, starting from a root
  68. node, returning one node at a time, together with information about
  69. whether the node is being entered or exited. The iterator will
  70. first descend to a child node, if there is one. When there is no
  71. child, the iterator will go to the next sibling. When there is no
  72. next sibling, the iterator will return to the parent (but with
  73. a \f[I]cmark_event_type\f[] of \f[C]CMARK_EVENT_EXIT\f[]). The iterator will
  74. return \f[C]CMARK_EVENT_DONE\f[] when it reaches the root node again.
  75. One natural application is an HTML renderer, where an \f[C]ENTER\f[] event
  76. outputs an open tag and an \f[C]EXIT\f[] event outputs a close tag.
  77. An iterator might also be used to transform an AST in some systematic
  78. way, for example, turning all level\-3 headers into regular paragraphs.
  79. .IP
  80. .nf
  81. \f[C]
  82. void
  83. usage_example(cmark_node *root) {
  84. cmark_event_type ev_type;
  85. cmark_iter *iter = cmark_iter_new(root);
  86. while ((ev_type = cmark_iter_next(iter)) != CMARK_EVENT_DONE) {
  87. cmark_node *cur = cmark_iter_get_node(iter);
  88. // Do something with `cur` and `ev_type`
  89. }
  90. cmark_iter_free(iter);
  91. }
  92. \f[]
  93. .fi
  94. .PP
  95. Iterators will never return \f[C]EXIT\f[] events for leaf nodes, which are nodes
  96. of type:
  97. .IP \[bu] 2
  98. CMARK_NODE_HTML
  99. .IP \[bu] 2
  100. CMARK_NODE_HRULE
  101. .IP \[bu] 2
  102. CMARK_NODE_CODE_BLOCK
  103. .IP \[bu] 2
  104. CMARK_NODE_TEXT
  105. .IP \[bu] 2
  106. CMARK_NODE_SOFTBREAK
  107. .IP \[bu] 2
  108. CMARK_NODE_LINEBREAK
  109. .IP \[bu] 2
  110. CMARK_NODE_CODE
  111. .IP \[bu] 2
  112. CMARK_NODE_INLINE_HTML
  113. .PP
  114. Nodes must only be modified after an \f[C]EXIT\f[] event, or an \f[C]ENTER\f[] event for
  115. leaf nodes.
  116. .PP
  117. \fIcmark_iter*\f[] \fBcmark_iter_new\f[](\fIcmark_node *root\f[])
  118. .PP
  119. Creates a new iterator starting at \f[I]root\f[]\&. The current node and event
  120. type are undefined until \f[C]cmark_iter_next\f[] is called for the first time.
  121. .PP
  122. \fIvoid\f[] \fBcmark_iter_free\f[](\fIcmark_iter *iter\f[])
  123. .PP
  124. Frees the memory allocated for an iterator.
  125. .PP
  126. \fIcmark_event_type\f[] \fBcmark_iter_next\f[](\fIcmark_iter *iter\f[])
  127. .PP
  128. Advances to the next node and returns the event type (\f[C]CMARK_EVENT_ENTER\f[],
  129. \f[C]CMARK_EVENT_EXIT\f[] or \f[C]CMARK_EVENT_DONE\f[]).
  130. .PP
  131. \fIcmark_node*\f[] \fBcmark_iter_get_node\f[](\fIcmark_iter *iter\f[])
  132. .PP
  133. Returns the current node.
  134. .PP
  135. \fIcmark_event_type\f[] \fBcmark_iter_get_event_type\f[](\fIcmark_iter *iter\f[])
  136. .PP
  137. Returns the current event type.
  138. .PP
  139. \fIvoid\f[] \fBcmark_iter_reset\f[](\fIcmark_iter *iter\f[], \fIcmark_node *current\f[], \fIcmark_event_type event_type\f[])
  140. .PP
  141. Resets the iterator so that the current node is \f[I]current\f[] and
  142. the event type is \f[I]event_type\f[]\&. The new current node must be a
  143. descendant of the root node or the root node itself.
  144. .SS
  145. Accessors
  146. .PP
  147. \fIcmark_node_type\f[] \fBcmark_node_get_type\f[](\fIcmark_node *node\f[])
  148. .PP
  149. Returns the type of \f[I]node\f[], or \f[C]CMARK_NODE_NONE\f[] on error.
  150. .PP
  151. \fIconst char*\f[] \fBcmark_node_get_type_string\f[](\fIcmark_node *node\f[])
  152. .PP
  153. Like \f[I]cmark_node_get_type\f[], but returns a string representation
  154. of the type, or \f[C]"<unknown>"\f[]\&.
  155. .PP
  156. \fIconst char*\f[] \fBcmark_node_get_literal\f[](\fIcmark_node *node\f[])
  157. .PP
  158. Returns the string contents of \f[I]node\f[], or NULL if none.
  159. .PP
  160. \fIint\f[] \fBcmark_node_set_literal\f[](\fIcmark_node *node\f[], \fIconst char *content\f[])
  161. .PP
  162. Sets the string contents of \f[I]node\f[]\&. Returns 1 on success,
  163. 0 on failure.
  164. .PP
  165. \fIint\f[] \fBcmark_node_get_header_level\f[](\fIcmark_node *node\f[])
  166. .PP
  167. Returns the header level of \f[I]node\f[], or 0 if \f[I]node\f[] is not a header.
  168. .PP
  169. \fIint\f[] \fBcmark_node_set_header_level\f[](\fIcmark_node *node\f[], \fIint level\f[])
  170. .PP
  171. Sets the header level of \f[I]node\f[], returning 1 on success and 0 on error.
  172. .PP
  173. \fIcmark_list_type\f[] \fBcmark_node_get_list_type\f[](\fIcmark_node *node\f[])
  174. .PP
  175. Returns the list type of \f[I]node\f[], or \f[C]CMARK_NO_LIST\f[] if \f[I]node\f[]
  176. is not a list.
  177. .PP
  178. \fIint\f[] \fBcmark_node_set_list_type\f[](\fIcmark_node *node\f[], \fIcmark_list_type type\f[])
  179. .PP
  180. Sets the list type of \f[I]node\f[], returning 1 on success and 0 on error.
  181. .PP
  182. \fIcmark_delim_type\f[] \fBcmark_node_get_list_delim\f[](\fIcmark_node *node\f[])
  183. .PP
  184. Returns the list delimiter type of \f[I]node\f[], or \f[C]CMARK_NO_DELIM\f[] if \f[I]node\f[]
  185. is not a list.
  186. .PP
  187. \fIint\f[] \fBcmark_node_set_list_delim\f[](\fIcmark_node *node\f[], \fIcmark_delim_type delim\f[])
  188. .PP
  189. Sets the list delimiter type of \f[I]node\f[], returning 1 on success and 0
  190. on error.
  191. .PP
  192. \fIint\f[] \fBcmark_node_get_list_start\f[](\fIcmark_node *node\f[])
  193. .PP
  194. Returns starting number of \f[I]node\f[], if it is an ordered list, otherwise 0.
  195. .PP
  196. \fIint\f[] \fBcmark_node_set_list_start\f[](\fIcmark_node *node\f[], \fIint start\f[])
  197. .PP
  198. Sets starting number of \f[I]node\f[], if it is an ordered list. Returns 1
  199. on success, 0 on failure.
  200. .PP
  201. \fIint\f[] \fBcmark_node_get_list_tight\f[](\fIcmark_node *node\f[])
  202. .PP
  203. Returns 1 if \f[I]node\f[] is a tight list, 0 otherwise.
  204. .PP
  205. \fIint\f[] \fBcmark_node_set_list_tight\f[](\fIcmark_node *node\f[], \fIint tight\f[])
  206. .PP
  207. Sets the "tightness" of a list. Returns 1 on success, 0 on failure.
  208. .PP
  209. \fIconst char*\f[] \fBcmark_node_get_fence_info\f[](\fIcmark_node *node\f[])
  210. .PP
  211. Returns the info string from a fenced code block, or NULL if none.
  212. .PP
  213. \fIint\f[] \fBcmark_node_set_fence_info\f[](\fIcmark_node *node\f[], \fIconst char *info\f[])
  214. .PP
  215. Sets the info string in a fenced code block, returning 1 on
  216. success and 0 on failure.
  217. .PP
  218. \fIconst char*\f[] \fBcmark_node_get_url\f[](\fIcmark_node *node\f[])
  219. .PP
  220. Gets the URL of a link or image \f[I]node\f[], or NULL if none.
  221. .PP
  222. \fIint\f[] \fBcmark_node_set_url\f[](\fIcmark_node *node\f[], \fIconst char *url\f[])
  223. .PP
  224. Sets the URL of a link or image \f[I]node\f[]\&. Returns 1 on success,
  225. 0 on failure.
  226. .PP
  227. \fIconst char*\f[] \fBcmark_node_get_title\f[](\fIcmark_node *node\f[])
  228. .PP
  229. Gets the title of a link or image \f[I]node\f[], or NULL if none.
  230. .PP
  231. \fIint\f[] \fBcmark_node_set_title\f[](\fIcmark_node *node\f[], \fIconst char *title\f[])
  232. .PP
  233. Sets the title of a link or image \f[I]node\f[]\&. Returns 1 on success,
  234. 0 on failure.
  235. .PP
  236. \fIint\f[] \fBcmark_node_get_start_line\f[](\fIcmark_node *node\f[])
  237. .PP
  238. Returns the line on which \f[I]node\f[] begins.
  239. .PP
  240. \fIint\f[] \fBcmark_node_get_start_column\f[](\fIcmark_node *node\f[])
  241. .PP
  242. Returns the column at which \f[I]node\f[] begins.
  243. .PP
  244. \fIint\f[] \fBcmark_node_get_end_line\f[](\fIcmark_node *node\f[])
  245. .PP
  246. Returns the line on which \f[I]node\f[] ends.
  247. .PP
  248. \fIint\f[] \fBcmark_node_get_end_column\f[](\fIcmark_node *node\f[])
  249. .PP
  250. Returns the column at which \f[I]node\f[] ends.
  251. .SS
  252. Tree Manipulation
  253. .PP
  254. \fIvoid\f[] \fBcmark_node_unlink\f[](\fIcmark_node *node\f[])
  255. .PP
  256. Unlinks a \f[I]node\f[], removing it from the tree, but not freeing its
  257. memory. (Use \f[I]cmark_node_free\f[] for that.)
  258. .PP
  259. \fIint\f[] \fBcmark_node_insert_before\f[](\fIcmark_node *node\f[], \fIcmark_node *sibling\f[])
  260. .PP
  261. Inserts \f[I]sibling\f[] before \f[I]node\f[]\&. Returns 1 on success, 0 on failure.
  262. .PP
  263. \fIint\f[] \fBcmark_node_insert_after\f[](\fIcmark_node *node\f[], \fIcmark_node *sibling\f[])
  264. .PP
  265. Inserts \f[I]sibling\f[] after \f[I]node\f[]\&. Returns 1 on success, 0 on failure.
  266. .PP
  267. \fIint\f[] \fBcmark_node_prepend_child\f[](\fIcmark_node *node\f[], \fIcmark_node *child\f[])
  268. .PP
  269. Adds \f[I]child\f[] to the beginning of the children of \f[I]node\f[]\&.
  270. Returns 1 on success, 0 on failure.
  271. .PP
  272. \fIint\f[] \fBcmark_node_append_child\f[](\fIcmark_node *node\f[], \fIcmark_node *child\f[])
  273. .PP
  274. Adds \f[I]child\f[] to the end of the children of \f[I]node\f[]\&.
  275. Returns 1 on success, 0 on failure.
  276. .PP
  277. \fIvoid\f[] \fBcmark_consolidate_text_nodes\f[](\fIcmark_node *root\f[])
  278. .PP
  279. Consolidates adjacent text nodes.
  280. .SS
  281. Parsing
  282. .PP
  283. Simple interface:
  284. .IP
  285. .nf
  286. \f[C]
  287. cmark_node *document = cmark_parse_document("Hello *world*", 12);
  288. \f[]
  289. .fi
  290. .PP
  291. Streaming interface:
  292. .IP
  293. .nf
  294. \f[C]
  295. cmark_parser *parser = cmark_parser_new();
  296. FILE *fp = fopen("myfile.md", "r");
  297. while ((bytes = fread(buffer, 1, sizeof(buffer), fp)) > 0) {
  298. cmark_parser_feed(parser, buffer, bytes);
  299. if (bytes < sizeof(buffer)) {
  300. break;
  301. }
  302. }
  303. document = cmark_parser_finish(parser);
  304. cmark_parser_free(parser);
  305. \f[]
  306. .fi
  307. .PP
  308. \fIcmark_parser *\f[] \fBcmark_parser_new\f[](\fI\f[])
  309. .PP
  310. Creates a new parser object.
  311. .PP
  312. \fIvoid\f[] \fBcmark_parser_free\f[](\fIcmark_parser *parser\f[])
  313. .PP
  314. Frees memory allocated for a parser object.
  315. .PP
  316. \fIvoid\f[] \fBcmark_parser_feed\f[](\fIcmark_parser *parser\f[], \fIconst char *buffer\f[], \fIsize_t len\f[])
  317. .PP
  318. Feeds a string of length \f[I]len\f[] to \f[I]parser\f[]\&.
  319. .PP
  320. \fIcmark_node *\f[] \fBcmark_parser_finish\f[](\fIcmark_parser *parser\f[])
  321. .PP
  322. Finish parsing and return a pointer to a tree of nodes.
  323. .PP
  324. \fIcmark_node *\f[] \fBcmark_parse_document\f[](\fIconst char *buffer\f[], \fIsize_t len\f[])
  325. .PP
  326. Parse a CommonMark document in \f[I]buffer\f[] of length \f[I]len\f[]\&.
  327. Returns a pointer to a tree of nodes.
  328. .PP
  329. \fIcmark_node *\f[] \fBcmark_parse_file\f[](\fIFILE *f\f[])
  330. .PP
  331. Parse a CommonMark document in file \f[I]f\f[], returning a pointer to
  332. a tree of nodes.
  333. .SS
  334. Rendering
  335. .PP
  336. \fIchar *\f[] \fBcmark_render_xml\f[](\fIcmark_node *root\f[], \fIlong options\f[])
  337. .PP
  338. Render a \f[I]node\f[] tree as XML.
  339. .PP
  340. \fIchar *\f[] \fBcmark_render_html\f[](\fIcmark_node *root\f[], \fIlong options\f[])
  341. .PP
  342. Render a \f[I]node\f[] tree as an HTML fragment. It is up to the user
  343. to add an appropriate header and footer.
  344. .PP
  345. \fIchar *\f[] \fBcmark_render_man\f[](\fIcmark_node *root\f[], \fIlong options\f[])
  346. .PP
  347. Render a \f[I]node\f[] tree as a groff man page, without the header.
  348. .PP
  349. .nf
  350. \fC
  351. .RS 0n
  352. #define CMARK_OPT_DEFAULT 0
  353. .RE
  354. \f[]
  355. .fi
  356. .PP
  357. Default writer options.
  358. .PP
  359. .nf
  360. \fC
  361. .RS 0n
  362. #define CMARK_OPT_SOURCEPOS 1
  363. .RE
  364. \f[]
  365. .fi
  366. .PP
  367. Include a \f[C]data\-sourcepos\f[] attribute on all block elements.
  368. .PP
  369. .nf
  370. \fC
  371. .RS 0n
  372. #define CMARK_OPT_HARDBREAKS 2
  373. .RE
  374. \f[]
  375. .fi
  376. .PP
  377. Render \f[C]softbreak\f[] elements as hard line breaks.
  378. .PP
  379. .nf
  380. \fC
  381. .RS 0n
  382. #define CMARK_OPT_NORMALIZE 4
  383. .RE
  384. \f[]
  385. .fi
  386. .PP
  387. Normalize tree by consolidating adjacent text nodes.
  388. .SH
  389. AUTHORS
  390. .PP
  391. John MacFarlane, Vicent Marti, Kārlis Gaņģis, Nick Wellnhofer.