7. ENode API

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.

• enode

  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.

  		Examples:
  			perl:
  				my $node = enode("button.Mybutton");
  			javascript:
  				othernode = enode ("ctree.FooCtree");
  			C:
  				ENode *thisnode;
  				thisnode = enode ("valign.MyAlign");
  			python:
  				thatnode = enode("object");
  			tcl:
  				set node [enode object.FooObject]
                  
  

• enode_rx

  Same as enode except the argument it accepts is a regular expression (perl compatible), matching the basename of each node in turn.

  		Examples:
  			perl:
  				$node = enode_rx('window\.Win[1-4]');
  			javascript:
  				anothernode = enode_rx("ctree\.FB.*");
  			C:
  				Enode *mynode;
  				mynode = enode_rx ("[button|window]\.ThisNode");
  			python:
  				nodetwo = enode_rx (".*");
  			tcl:
  				set foonode [enode_rx object\..*]
                  
  

• elist

  Returns a list of nodes matching the argument.

  		Examples:
  			perl:
  				my @nodes = elist("ctree");
  			javascript:
  				nodes = elist("ctree-row");
  			C:
  			python:
  				nodes = elist("graph");
  			tcl:
                  
  

• elist_rx

  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:

• parent

  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.

• child

  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.

• child_rx

  Same as child but uses a regular expression for matching.

• children

  Returns a list of ENode's matching the first basename argument. If there is no argument, it returns all the immediate children.

• children_rx

  Like children but uses a regex.

• children_attrib

  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.

• children_attrib_rx

  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.

• attrib

  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).

• attrib_is_true

  Check to see if the attribute supplied is true, (true, yes, 1, etc). Returns a boolean.

• destroy

  Destroy the current node, and all children.

• destroy_children

  Destroy all the children of the current node while leaving the node it is referred from alone.

• get_xml

  Returns an XML representation of the given node and all its children.

• get_child_xml

  Returns an XML representation of all the given node's descendants, NOT including itself.

• append_xml

  Parse the given XML string and build the objects it specifies under the referred ENode.

• call

  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 third argument, is the prototype string that lists the type of the following arguments. This had to be done for languages like C that make it impossible to determine argument types, and because many language have stricter typing rules than perl, python, javascript etc.

  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")
                  
  

• new_child

  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_data

  Set the data of the ENode to the string supplied as the only arugment.

• get_data

  Retrieve the data of the ENode.

• append_data

  Append the string given as the only node, to the data currently bound to the node.

• insert_data

  Insert a string at any location within the current data.

• delete_data

  Delete a range of data within the node beginning at any offset.