Node

A class to work with QUB trees in Python

Node( name )

the new node's name. default: ""

Creates an unconnected node.

NullNode()

Creates a null node object, referring to no actual node.

CommentNode( text )

the contents of the comment. default: ""

Creates a node named "QTR_COMMENT" that will appear as a full-line comment in the text format.

Open( path, readOnly )

path		the path to an existing file
readOnly		whether to open the file read-only. default: false

Opens a binary qubtree file and returns its root node. If root.isNull the file could not be opened.

ReadText( path )

the path to a qubtree text file

Reads a qubtree from a text file and returns its root node. If root.isNull the file could not be opened.

ReadString( treeString )

such as str(tree)

Reads a text qubtree from a string and returns its root node.

ReadBytes( treeBytesString )

treeBytesString

a string containing the binary qubtree (as returned by getBytes())

Reads a binary qubtree from a string and returns its root node.

isNull

true if this Node refers to no node

name

string: read/write: the node's name

child

Node: this node's first child

sibling

Node: this node's next sibling (parent's next child)

parent

Node: the node which has this node as a child, possibly null

data

Node.data:
read: a sequence-like view on the node's data
write: a number, list of numbers, string, or None

lineComment

string: read/write: the comment appearing with the node in the text representation.

path

the path of the node's file, if open, or None.

modified

whether the node or its children have changed since saving.

Node[ childName ]

childName		name of a child node
returns		Node

Gets the first child node named childName. If none exist, one will be created. If you'd rather not have one created, use find instead.

clone( deep )

deep		true: copy the subtree rooted here. false: copy just this node and its data. default: true
returns		Node

Makes a copy of this node.

saveAsText( path )

path		file name
returns		true if successful

Saves the node as a plain text qubtree.

saveAs( path )

path		file name
returns		true if successful

Saves the node as a binary file, and leaves the file open for further modifications.
This node will be the root of that file's tree. If it has a parent, it will be removed first.

save()

true if successful

If this node is in an open file, saves changes to this node and its subtree.
If all you've changed is some node's data, make sure you have setChanged() that node, or your changes may be lost.

close()

If this node is in an open file, closes the file without saving. The file's contents remain available in memory.

To avoid copying a large file into memory when you're done with it, make sure you hold no references except the root node (del all variables pointing into the tree), then del rootNode. The file is closed automatically when there are no references to its root node.

getBytes()

Returns a string containing the binary representation of the subtree rooted at this node. The result can be written to disk as a valid qubtree file or read by ReadBytes.

list()

a list of the names of this node's children

find( name )

name		the name of a child node
returns		Node, possibly null

Finds the first child node with that name. If none, returns a null node. If you'd rather the missing child be automatically created, use [] (dictionary-style) instead.

next( name )

name		the name of a sibling
returns		Node, possibly null

Finds the next sibling with that name. If none, returns a null node.

append( newChild )

append( newChildName )

newChild		a node
newChild		the name for a newly created child
returns		the newly appended child

Adds newChild to this node's children, and makes this node newChild's parent.
If newChild already has a parent, it will be removed first.

append( template, deep )

template		a node
deep		whether to copy template's children or just its data
returns		the newly appended clone

Appends a copy of template to this node's children.

insert( newChild, afterChild )

newChild		a node
afterChild		a child of this node, or None
returns		the newly inserted child

Adds newChild to the list of children, after afterChild. If afterChild == None: insert as first child.

insertClone( template, deep, afterChild )

template		a node
deep		whether to copy template's children or just its data
afterChild		a child of this node, or None
returns		the newly inserted child

Adds a copy of template to this node's children, after afterChild. If afterChild == None: insert as first child.

remove( child )

child		a child of this node
returns		None

setChanged()

Marks this node as needing to be written next time you save().
It's marked automatically when you change e.g. the name, the tree structure, or the data length. You're responsible for calling it after modifying the data contents.

lock( timeoutMS )

timeoutMS		how long to wait for the mutex before giving up
returns		true if we got the mutex

The mutex controls all access to the node; most importantly its reference count. It's shared among all nodes with the same root. Don't hold it for too long.

unlock()

Releases the mutex.