package vendor:commonmark
Overview
Bindings for CMark.
Original authors: John MacFarlane, Vicent Marti, Kārlis Gaņģis, Nick Wellnhofer. See LICENSE for license details.
Example:
import cm "vendor:commonmark"
// Parsing - Simple interface
hellope_world :: proc() {
fmt.printf("CMark version: %v\n", cm.version_string())
str := "Hellope *world*!"
root := cm.parse_document(raw_data(str), len(str), cm.DEFAULT_OPTIONS)
defer cm.node_free(root)
html := cm.render_html(root, cm.DEFAULT_OPTIONS)
defer cm.free(html)
fmt.println(html)
}
// Parsing - Streaming interface
streaming :: proc() {
using cm
STR :: "Hellope *world*!\n\n"
N :: 50
STREAM_SIZE :: 42
str_buf: [len(STR) * N]u8
for i in 0..<N {
copy(str_buf[i*len(STR):], STR)
}
parser := parser_new(DEFAULT_OPTIONS)
defer parser_free(parser)
buf := str_buf[:]
for len(buf) > STREAM_SIZE {
parser_feed(parser, raw_data(buf), STREAM_SIZE)
buf = buf[STREAM_SIZE:]
}
if len(buf) > 0 {
parser_feed(parser, raw_data(buf), len(buf))
buf = buf[len(buf):]
}
root := parser_finish(parser)
defer cm.node_free(root)
html := cm.render_html(root, cm.DEFAULT_OPTIONS)
defer cm.free(html)
fmt.println(html)
}
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 an Event_Type.Exit).
The iterator will return .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 headings into regular paragraphs.
usage_example(root: ^Node) {
ev_type: Event_Type
iter := iter_new(root)
defer iter_free(iter)
for {
ev_type = iter_next(iter)
if ev_type == .Done do break
cur := iter_get_node(iter)
// Do something with cur and ev_type
}
}
Iterators will never return .Exit events for leaf nodes,
which are nodes of type:
HTML_Block Thematic_Break Code_Block Text Soft_Break Line_Break Code HTML_Inline
Nodes must only be modified after an .Exit event, or an .Enter event for
leaf nodes.
Index
Constants (3)
Variables (0)
This section is empty.
Procedures (75)
- consolidate_text_nodes
- free_cstring
- free_rawptr
- free_string
- get_default_mem_allocator
- get_default_mem_allocator_as_odin
- iter_free
- iter_get_event_type
- iter_get_node
- iter_get_root
- iter_new
- iter_next
- iter_reset
- markdown_to_html
- markdown_to_html_from_string
- node_append_child
- node_first_child
- node_free
- node_get_end_column
- node_get_end_line
- node_get_fence_info
- node_get_heading_level
- node_get_list_delim
- node_get_list_start
- node_get_list_tight
- node_get_list_type
- node_get_literal
- node_get_on_enter
- node_get_on_exit
- node_get_start_column
- node_get_start_line
- node_get_title
- node_get_type
- node_get_type_string
- node_get_url
- node_get_user_data
- node_insert_after
- node_insert_before
- node_last_child
- node_new
- node_new_with_mem
- node_next
- node_parent
- node_prepend_child
- node_previous
- node_replace
- node_set_fence_info
- node_set_heading_level
- node_set_list_delim
- node_set_list_start
- node_set_list_tight
- node_set_list_type
- node_set_literal
- node_set_on_enter
- node_set_on_exit
- node_set_title
- node_set_url
- node_set_user_data
- node_unlink
- parse_document
- parse_document_from_string
- parse_from_libc_file
- parser_feed
- parser_feed_from_string
- parser_finish
- parser_free
- parser_new
- parser_new_with_mem
- render_commonmark
- render_html
- render_latex
- render_man
- render_xml
- version
- version_string
Procedure Groups (1)
Types
Allocator ¶
Allocator :: struct { calloc: proc "c" (num: uint, size: uint) -> rawptr, realloc: proc "c" (ptr: rawptr, new_size: uint) -> rawptr, free: proc "c" (ptr: rawptr), }
Custom allocator - Defines the memory allocation functions to be used by CMark when parsing and allocating a document tree
Related Procedures With Parameters
Related Procedures With Returns
Delim_Type ¶
Delim_Type :: enum i32 { None, Period, Paren, }
Related Procedures With Parameters
Related Procedures With Returns
Event_Type ¶
Event_Type :: enum i32 { None, Done, Enter, Exit, }
Related Procedures With Parameters
Related Procedures With Returns
List_Type ¶
List_Type :: enum i32 { None, Bullet, Ordered, }
Related Procedures With Parameters
Related Procedures With Returns
Node ¶
Node :: struct { mem: ^Allocator, next: ^Node, prev: ^Node, parent: ^Node, first_child: ^Node, last_child: ^Node, user_data: rawptr, data: [^]u8, len: bufsize_t, start_line: i32, start_column: i32, end_line: i32, end_column: i32, type: Node_Type, flags: bit_set[Node_Flag; u16], as: struct #raw_union { list: List, code: Code, heading: Heading, link: Link, custom: Custom, html_block_type: i32, }, }
Node creation, destruction, and tree traversal
Related Procedures With Parameters
- consolidate_text_nodes
- iter_new
- iter_reset
- node_append_child
- node_first_child
- node_free
- node_get_end_column
- node_get_end_line
- node_get_fence_info
- node_get_heading_level
- node_get_list_delim
- node_get_list_start
- node_get_list_tight
- node_get_list_type
- node_get_literal
- node_get_on_enter
- node_get_on_exit
- node_get_start_column
- node_get_start_line
- node_get_title
- node_get_type
- node_get_type_string
- node_get_url
- node_get_user_data
- node_insert_after
- node_insert_before
- node_last_child
- node_next
- node_parent
- node_prepend_child
- node_previous
- node_replace
- node_set_fence_info
- node_set_heading_level
- node_set_list_delim
- node_set_list_start
- node_set_list_tight
- node_set_list_type
- node_set_literal
- node_set_on_enter
- node_set_on_exit
- node_set_title
- node_set_url
- node_set_user_data
- node_unlink
- render_commonmark
- render_html
- render_latex
- render_man
- render_xml
Related Procedures With Returns
Node_Flag ¶
Node_Flag :: enum u16 { Open = 0, Last_Line_Blank = 1, Last_Line_Checked = 2, }
Node_Type ¶
Node_Type :: enum u16 { // Error status None = 0, // Block Document, Block_Quote, List, Item, Code_Block, HTML_Block, Custom_Block, Paragraph, Heading, Thematic_Break, // Inline Text, Soft_Break, Line_Break, Code, HTML_Inline, Custom_Inline, Emph, Strong, Link, Image, First_Block = 1, Last_Block = 10, First_Inline = 11, Last_Inline = 20, }
Related Procedures With Parameters
Related Procedures With Returns
Option ¶
Option :: enum i32 { Source_Position = 1, // Include a `data-sourcepos` attribute on all block elements. Hard_Breaks = 2, // Render `softbreak` as hard line breaks. Safe = 3, // Defined for API compatibility, now enabled by default. Unsafe = 17, // Render raw HTML and unsafe links (`javascript:`, `vbscript:`, // `file:`, and `data:`, except for `image/png`, `image/gif`, // `image/jpeg`, or `image/webp` mime types). By default, // raw HTML is replaced by a placeholder HTML comment. Unsafe // links are replaced by empty strings. No_Breaks = 4, // Render `softbreak` elements as spaces. Normalize = 8, // Legacy option, no effect. Validate_UTF8 = 9, // Validate UTF-8 input before parsing, replacing illegal // sequences with the replacement character U+FFFD. Smart = 10, // Convert straight quotes to curly, --- to em dashes, -- to en dashes. }
Parser ¶
Parser :: distinct rawptr
Related Procedures With Parameters
Related Procedures With Returns
bufsize_t ¶
bufsize_t :: distinct i32
Constants
BINDING_VERSION ¶
BINDING_VERSION :: Version_Info{major = 0, minor = 30, patch = 2}
COMMONMARK_SHARED ¶
COMMONMARK_SHARED: bool : #config(COMMONMARK_SHARED, false)
Variables
This section is empty.
Procedures
consolidate_text_nodes ¶
consolidate_text_nodes :: proc "c" (root: ^Node) ---
Consolidates adjacent text nodes.
free_rawptr ¶
free_rawptr :: proc "c" (ptr: rawptr) {…}
Helpers to free results from render_*.
Related Procedure Groups
free_string ¶
free_string :: proc "c" (s: string) {…}
get_default_mem_allocator ¶
get_default_mem_allocator :: proc "c" () -> (mem: ^Allocator) ---
Returns a pointer to the default memory allocator.
get_default_mem_allocator_as_odin ¶
get_default_mem_allocator_as_odin :: proc() -> runtime.Allocator {…}
iter_get_event_type ¶
iter_get_event_type :: proc "c" (iter: ^Iter) -> (event_type: Event_Type) ---
Returns the current event type.
iter_get_node ¶
Returns the current node.
iter_get_root ¶
Returns the root node.
iter_new ¶
Creates a new iterator starting at 'root'. The current node and event
type are undefined until iter_next is called for the first time.
The memory allocated for the iterator should be released using
'iter_free' when it is no longer needed.
iter_next ¶
iter_next :: proc "c" (iter: ^Iter) -> (event_type: Event_Type) ---
Advances to the next node and returns the event type (.Enter, .Exit, .Done)
iter_reset ¶
iter_reset :: proc "c" (iter: ^Iter, current: ^Node, event_type: Event_Type) ---
Resets the iterator so that the current node is current and
the event type is event_type. The new current node must be a
descendant of the root node or the root node itself.
markdown_to_html ¶
markdown_to_html :: proc "c" (text: cstring, length: uint, options: bit_set[Option; i32]) -> (html: cstring) ---
Convert 'text' (assumed to be a UTF-8 encoded string with length len) from CommonMark Markdown to HTML
returning a null-terminated, UTF-8-encoded string. It is the caller's responsibility
to free the returned buffer.
node_append_child ¶
Adds 'child' to the end of the children of node.
Returns true on success, false on failure.
node_first_child ¶
Returns the first child of node, or nil if node has no children.
node_free ¶
node_free :: proc "c" (node: ^Node) ---
Frees the memory allocated for a node and any children.
node_get_end_column ¶
Returns the column at which node ends.
node_get_end_line ¶
Returns the line on which node ends.
node_get_fence_info ¶
Returns the info string from a fenced code block.
node_get_heading_level ¶
Returns the heading level of node, or 0 if node is not a heading.
node_get_list_delim ¶
node_get_list_delim :: proc "c" (node: ^Node) -> (delim_type: Delim_Type) ---
Returns the list delimiter type of node, or .No_Delim if not a list.
node_get_list_start ¶
Returns starting number of node, if it is an ordered list, otherwise 0.
node_get_list_tight ¶
Returns true if node is a tight list, false otherwise.
node_get_list_type ¶
Returns the list type of node, or .No_List if not a list.
node_get_literal ¶
Returns the string contents of node, or an empty string if none is set.
Returns nil if called on a node that does not have string content.
node_get_on_enter ¶
Returns the literal "on enter" text for a custom node, or an empty string if no on_enter is set.
Returns nil if called on a non-custom node.
node_get_on_exit ¶
Returns the literal "on exit" text for a custom 'node', or an empty string if no on_exit is set. Returns NULL if called on a non-custom node.
node_get_start_column ¶
Returns the column at which node begins.
node_get_start_line ¶
Returns the line on which node begins.
node_get_title ¶
Returns the title of a link or image node, or an empty string if no title is set.
Returns nil if called on a node that is not a link or image.
node_get_type ¶
Returns the type of node, or .None on error.
node_get_type_string ¶
Like node_get_type, but returns a string representation of the type, or "<unknown>".
node_get_url ¶
Returns the URL of a link or image node, or an empty string if no URL is set.
Returns nil if called on a node that is not a link or image.
node_get_user_data ¶
Returns the user data of node.
node_insert_after ¶
Inserts 'sibling' after node. Returns true on success, false on failure.
node_insert_before ¶
Inserts 'sibling' before node. Returns true on success, false on failure.
node_last_child ¶
Returns the last child of node, or nil if node has no children.
node_new ¶
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.
node_new_with_mem ¶
Same as node_new, but explicitly listing the memory allocator used to allocate the node.
Note: be sure to use the same allocator for every node in a tree, or bad things can happen.
node_next ¶
Tree Traversal
Returns the next node in the sequence after node, or nil if there is none.
node_parent ¶
Returns the parent of node, or nil if there is none.
node_prepend_child ¶
Adds 'child' to the beginning of the children of node.
Returns true on success, false on failure.
node_previous ¶
Returns the previous node in the sequence after node, or nil if there is none.
node_replace ¶
Replaces 'oldnode' with 'newnode' and unlinks 'oldnode'
(but does not free its memory).
Returns true on success, false on failure.
node_set_fence_info ¶
Sets the info string in a fenced code block, returning true on success and false on failure.
node_set_heading_level ¶
Sets the heading level of node. Returns true on success, false on failure.
node_set_list_delim ¶
node_set_list_delim :: proc "c" (node: ^Node, delim_type: Delim_Type) -> (success: b32) ---
Sets the delimiter type of node. Returns true on success, false on failure.
node_set_list_start ¶
Sets starting number of node, if it is an ordered list.
Returns true on success, false on failure.
node_set_list_tight ¶
Sets the "tightness" of a list. Returns true on success, false on failure.
node_set_list_type ¶
Sets the list type of node. Returns true on success, false on failure.
node_set_literal ¶
Sets the string contents of node. Returns true on success, false on failure.
node_set_on_enter ¶
Sets the literal text to render "on enter" for a custom node.
Any children of the node will be rendered after this text.
Returns true on success, falseon failure.
node_set_on_exit ¶
Sets the literal text to render "on exit" for a custom 'node'. Any children of the node will be rendered before this text. Returns 1 on success 0 on failure.
node_set_title ¶
Sets the title of a link or image node. Returns true on success, false on failure.
node_set_url ¶
Sets the URL of a link or image node. Returns true on success, false on failure.
node_set_user_data ¶
Sets arbitrary user data for node. Returns true on success, false on failure.
node_unlink ¶
node_unlink :: proc "c" (node: ^Node) ---
Unlinks a node, removing it from the tree, but not freeing its memory.
(Use node_free for that.)
parse_document ¶
parse_document :: proc "c" (buffer: [^]u8, len: uint, options: bit_set[Option; i32]) -> (root: ^Node) ---
Parse a CommonMark document in 'buffer' of length 'len'. Returns a pointer to a tree of nodes. The memory allocated for the node tree should be released using 'node_free' when it is no longer needed.
parser_feed ¶
Feeds a string of length 'len' to 'parser'.
parser_finish ¶
Finish parsing and return a pointer to a tree of nodes.
parser_free ¶
parser_free :: proc "c" (parser: ^Parser) ---
Frees memory allocated for a parser object.
parser_new ¶
Creates a new parser object.
parser_new_with_mem ¶
parser_new_with_mem :: proc "c" (options: bit_set[Option; i32], mem: ^Allocator) -> (parser: ^Parser) ---
Creates a new parser object with the given memory allocator.
render_commonmark ¶
render_commonmark :: proc "c" (root: ^Node, options: bit_set[Option; i32], width: i32) -> (commonmark: cstring) ---
Render a node tree as a commonmark document.
It is the caller's responsibility to free the returned buffer.
render_html ¶
Render a node tree as an HTML fragment.
It is up to the user to add an appropriate header and footer.
It is the caller's responsibility to free the returned buffer.
render_latex ¶
render_latex :: proc "c" (root: ^Node, options: bit_set[Option; i32], width: i32) -> (latex: cstring) ---
Render a node tree as a LaTeX document.
It is the caller's responsibility to free the returned buffer.
render_man ¶
render_man :: proc "c" (root: ^Node, options: bit_set[Option; i32], width: i32) -> (groff: cstring) ---
Render a node tree as a groff man page, without the header.
It is the caller's responsibility to free the returned buffer.
render_xml ¶
Render a node tree as XML.
It is the caller's responsibilityto free the returned buffer.
version ¶
version :: proc "c" () -> (res: Version_Info) ---
version_string ¶
version_string :: proc "c" () -> (res: cstring) ---
Procedure Groups
free ¶
free :: proc{ free_rawptr, free_cstring, }
Source Files
Generation Information
Generated with odin version dev-2025-11 (vendor "odin") Windows_amd64 @ 2025-11-01 21:11:16.457642700 +0000 UTC