Download
Markup trees

Contact
About
Docs
CVS

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.

 

 

Flux, these web pages, and all related material are Copyright©1999-2000 Simplemente and the respective authors, and are licensed under the GNU GPL. Please see the About page for more details. Web design by Joakim Ziegler <joakim@simplemente.net>, illustrations by Belinda Laws, <boysdontcry@zombieworld.com>.