The ENode API is the interface with which all work is done in Entity. It is through this API that the programmer is able to change the XML tree at runtime, and thereby produce a non-static application.
The enode API is similar across all languages, but not identical. The reference API is documented in docs/ENode.idl, in the Entity distribution. This API is then mapped as well as possible into each language supported by Entity. Some languages also have special ways of doing things that can make life easier. Where that is the case, those features have been used.
There are a few global methods that the langauges embedded within Entity will recognise. These will all return either a single ENode object (an instance of the ENode class), or a list of ENode objects. These are generally designed to find nodes within your application, and return the object representation of them to you so that you may manipulate them. All these search routines will start at the parent 'object' tag of the code that calls them. This allows seperate 'object's to exist within entity, and not have them interfere with one another.
This function returns the ENode that matches its argument. This is generally a 'basename' argument, that is, the type of the node concatenated with the name of the node (eg, 'button.mybutton'). The name is also optional, so you may simply search for 'button' and it will return the first match. If the arg starts with a '/' it will return the node based on a full path starting at the root of the XML tree. If no node matches it will return the appropriate NULL construct for the language it was called from.
Same as enode except the argument it accepts is a regular expression (perl compatible), matching the basename of each node in turn.
Returns a list of nodes matching the argument.
Same as elist but uses a regular expression to perform the match.
Now that we know how to get an ENode object, there are many things we can do once we get this object. The following is a list of methods supported:
Return a new ENode object that is the first parent that matches the string, this only searches directly up the tree. If no argument is given (or in the case of C, it is NULL) it will return the immediate parent.
Much like enode, but searches only the children of the ENode object it is called with. Note that this will return any matching descendant node, not just immediate children.
Same as child but uses a regular expression for matching.
Returns a list of ENode's matching the first basename argument. If there is no argument, it returns all the immediate children.
Like children but uses a regex.
Takes two arguments, attrib and value. This will search all children of the node it is called from, and return any children who have the an attribute matching the given value.
Identical to above, but a regular expression may be used for the value argument, and will return the list of nodes that have values for the supplied attribute matching that regular expression.
Get or set an attribute. The first argument is the attribute, the second is the new value. If no second argument is given, this function returns the present value of that attribute. Note that many language bindings use a more natural notation to express attribute getting and setting - python for example lets you reference a node's attributes using indexing (ie, node["attribute"] = value).
Check to see if the attribute supplied is true, (true, yes, 1, etc). Returns a boolean.
Destroy the current node, and all children.
Destroy all the children of the current node while leaving the node it is referred from alone.
Returns an XML representation of the given node and all its children.
Returns an XML representation of all the given node's descendants, NOT including itself.
Parse the given XML string and build the objects it specifies under the referred ENode.
Entity has a universal way of calling functions in any of the languages that it supports. This method of the ENode class, allows you to tap into this functionality, and call a function in another language, and optionally, in another 'object'.
The ENode object that is calling this method, will be used as the 'reference node', in determining which object the search for the function to call will be performed in. It will also appear as the first argument to the called function, regardless of other arguments supplied.
The second argument, is the name of the function you wish to call. This may use the "language:function" notation that you see in callbacks from nodes (because it's the same mechanism).
The argument string can have these letters "nesidb". n, s, and i should be all you need externally, they are for node, string, and int respectively.
Example: calling a the python function "foo" with parameters (1, "a string")
node.call("python:foo", "is", 1, "a string")
Create a new child within the node, new_child can accept info about the new node in a few ways. The name can be specified with the element like new_child("button.goodname"). Also attributes may be set by doing attrib, value, attrib, value. Note that this is another function that will vary slightly depending on the language used. This returns the newly created child ENode object.
Set the data of the ENode to the string supplied as the only arugment.
Retrieve the data of the ENode.
Append the string given as the only node, to the data currently bound to the node.
Insert a string at any location within the current data.
Delete a range of data within the node beginning at any offset.