Reference: MT (markup trees)
General
MTs are a form of tree structure
for storage and manipulation of marked-up data. It is conformant with XML
semantics. An MT node (also referred to as an element) consists of an agglomeration
of TT nodes holding various aspects of its data. Hence, MTs can be cast
to TTs for transmission, sub-element manipulation and storage. MT nodes
are typed - spanning elements, empty elements, entities and data behave
in different ways. All the functions aren't implemented yet, but those
documented here are supposed to be.
Properties overview
- Types: Spanning element,
empty element, entity, data.
- Attributes: Spanning/empty
elements may have attribute name-data pairs.
- Nesting: Only spanning elements
can have children.
- Functions are named by the
same convention as their TT equivalents, when possible.
- Breakdown to TTs: Not
yet documented.
Casts
- MT(x)
Casts any kind of tree element to a MT.
Iterators
- MT_FOR_EACH(MT *root, MT *child) statements
Iterates over the direct children of given root
element, using child to store the per-iteration
pointer. Used like a for statement.
Allocation
- MT
*mt_new(MT_TYPE type);
Allocates an empty, unconnected element from memory and returns its
pointer.
Supported values for type:
MT_DATA: Plain data node.
MT_ENTITY: Entity node.
MT_EMPTY: Empty tag.
MT_SPAN: Spanning tag.
- void
mt_del(MT *mt);
Detaches and frees element pointed to by mt,
and all of its children, recursively.
- MT
*mt_dup(MT *mt);
Makes an unconnected duplicate of given element and its data.
- MT
*mt_dup_all(MT *mt);
Makes an internally connected duplicate of the tree defined by given
element. That is, its children are also duplicated and connected to
form a tree with duplicate of given element as root.
Connectivity
These functions must be used to
link trees (elements) to form larger trees.
- void
mt_add_as_first_child(MT *parent_mt, MT *mt);
Adds mt at the beginning of parent_mt's
child list.
- void
mt_add_as_last_child(MT *parent_mt, MT *mt);
Adds mt to the end of parent_mt's
child list.
- void
mt_add_as_first_sibling(MT *sibling_mt, MT *mt);
Adds mt at the beginning of sibling_mt's
parent's child list. Note: If sibling_mt is a
root, and thus has no parent to hold child lists, a new root will be
created implicitly, holding sibling_mt and tt.
See mt_is_fake_root on dealing with implicitly
created root elements.
- void
mt_add_as_last_sibling(MT *sibling_mt, MT *mt);
Adds mt to the end of sibling_mt's
parent's child list. Note: If sibling_mt is a
root, and thus has no parent to hold child lists, a new root will be
created implicitly, holding sibling_mt and tt.
See mt_is_fake_root on dealing with implicitly
created root elements.
- void
mt_add_before(MT *next_mt, MT *mt);
Adds mt before sibling_tt
in sibling_mt's parent's child list. Note: If
sibling_mt is a root, and thus has no parent
to hold child lists, a new root will be created implicitly, holding
sibling_mt and tt. See
mt_is_fake_root on dealing with implicitly created
root elements.
- void
mt_add_after(MT *prev_mt, MT *mt);
Adds mt after sibling_tt
in sibling_mt's parent's child list. Note: If
sibling_mt is a root, and thus has no parent
to hold child lists, a new root will be created implicitly, holding
sibling_mt and tt. See
mt_is_fake_root on dealing with implicitly created
root elements.
- void mt_add(MT *parent_mt, MT *mt);
Shortcut to mt_add_as_last_child.
- void
mt_swap(MT *mt0, MT *mt1);
Swaps mt0 and tt1's connectivity
contexts, meaning their positions relative to other elements are exchanged.
Nothing else is touched, and the elements take their respective data
with them.
- void
mt_detach(MT *mt);
Disconnects the subtree denoted by mt from its
parent and siblings. After the operation, mt
will be a root element.
- int
mt_is_in_path(MT *mt0, MT *mt1);
Returns TRUE if mt0
is in the path of (or rather, is a direct or indirect parent of) mt1.
Navigation
- int mt_is_root(MT *mt);
Returns TRUE if mt
is a root element (has no parent).
- int mt_is_leaf(MT *mt);
Returns TRUE if mt
is a leaf element (has no children).
- int mt_is_first(MT *mt);
Returns TRUE if mt
comes before all of its siblings (has no previous element).
- int mt_is_last(MT *mt);
Returns TRUE if mt
comes after all of its siblings (has no next element).
- int mt_is_sibling(MT *mt0, MT *mt1);
Returns TRUE if mt0
and mt1 are siblings (have same parent).
- MT
*mt_get_root(MT *mt);
Returns the root element in mt's tree.
- MT
*mt_get_first_sibling(MT *mt);
Returns the first sibling of mt.
- MT
*mt_get_last_sibling(MT *mt);
Returns the last sibling of mt.
- int mt_get_prev(MT *mt);
Returns the previous sibling of mt, or NULL
if mt is the first element.
- int mt_get_next(MT *mt);
Returns the next sibling of mt, or NULL
if mt is the last element.
- int mt_get_parent(MT *mt);
Returns the parent of mt, or NULL
if mt is the root element.
- int mt_get_first_child(MT *mt);
Returns the first child of mt, or NULL
if mt is a leaf element.
- int mt_get_last_child(MT *mt);
Returns the last child of mt, or NULL
if mt is a leaf element.
- MT
*mt_get_common_parent(MT *mt0, MT *mt1);
Returns the first common parent in the path going upwards (towards the
root) from mt0 and tt1,
or NULL if they belong to disparate trees.
Data
- void
mt_data_set_bytes(MT *mt, void *src, u32 start, u32 len);
Changes len bytes of data in mt,
starting at start, to src.
Expands data size if it crosses the boundary, so this can be used to
set data in previously empty elements too.
- void
mt_data_append_bytes(MT *mt, void *src, u32 len);
Adds len bytes of data from src
at the end of mt.
- void
mt_data_prepend_bytes(MT *mt, void *src, u32 len);
Adds len bytes of data from src
to the beginning of mt.
- void
mt_data_set_str(MT *mt, char *str);
Shortcut for setting the data of tt to a string,
str.
- TT
*mt_data_get(MT *mt);
Returns the TT node holding mt's data (if it
is a data element).
- u32
mt_data_get_bytes(MT *mt, void *dest, u32 start, u32 len);
Copies len bytes of data from mt,
starting at start, to dest.
- char
*mt_data_get_str(MT *mt);
Returns a null-terminated copy of the data in mt.
Yes, you have to free this yourself, when you're done with it. If mt
is empty, it still returns a valid string - zero-length but null-terminated.
Statistics
- u32
mt_depth(MT *mt);
Reports the depth at which mt is connected (distance
to root element). For a root element itself, this value is zero.
- u32
mt_count_children(MT *mt);
Returns the number of direct children under root.
root itself is not included.
- u32
mt_count_children_all(MT *mt);
Returns the number of direct and indirect children under root.
root itself is not included.
- u32
mt_count_siblings(MT *mt);
Returns the number of elements having the same direct parent as root.
root itself is included.
Status indicators; getting
- int mt_has_data(MT *mt);
Returns TRUE if mt
has any data associated with it.
Printable I/O
- MT
*mt_scan_from_xml_file(FILE *in, int validate);
Reads an XML file from in and if it's well-formed,
returns the root tag of the resulting markup tree. If it's not well-formed,
or if validate is TRUE and the document is invalid, returns NULL. This will be extended to handle errors more gracefully,
in the future.
- int
mt_print_to_xml_file(MT *mt, FILE *out);
Prints a markup tree, formatted as 8-bit XML, to out.
The file will have no indenting, processing instructions or comments
(as of 0.3.0), so watch out.
|