1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<META HTTP-EQUIV="Content-Type" CONTENT="text/html; charset=iso-8859-1">
<TITLE>ENode API</TITLE>
</HEAD>
<BODY text="#000000" bgcolor="#ffffff">
<A HREF="tutorial.html"><EM> Entity Introduction </EM></A>
<b>:</b> <EM>ENode API</EM><BR>
<b>Previous:</b> <A HREF="tutorial6.html"><EM>A More complex Application</EM></A><BR>
<b>Next:</b> <A HREF="tutorial8.html"><EM>Going Further With Entity</EM></A>
<HR NOSHADE>
<H2><A NAME="7"></A>7. ENode API</H2>
<p>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.</p>
<p>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.</p>
<p>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.</p>
<p>
<ul>
<li><code>enode</code><p>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.</p>
<p>
<blockquote><code>
<pre>
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]
</pre>
</code></blockquote>
</p>
</li>
<li><code>enode_rx</code>
<p>Same as enode except the argument it accepts is a regular
expression (perl compatible), matching the basename of each
node in turn.</p>
<p>
<blockquote><code>
<pre>
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\..*]
</pre>
</code></blockquote>
</p>
</li>
<li><code>elist</code>
<p>Returns a list of nodes matching the argument.</p>
<p>
<blockquote><code>
<pre>
Examples:
perl:
my @nodes = elist("ctree");
javascript:
nodes = elist("ctree-row");
C:
python:
nodes = elist("graph");
tcl:
</pre>
</code></blockquote>
</p>
</li>
<li><code>elist_rx</code><p>Same as elist but uses a regular expression to perform the match.</p>
</li>
</ul>
</p>
<p>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:</p>
<p>
<ul>
<li><code>parent</code><p>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.</p>
</li>
<li><code>child</code><p>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.</p>
</li>
<li><code>child_rx</code><p>Same as child but uses a regular expression for matching.</p>
</li>
<li></li>
<li><code>children</code><p>Returns a list of ENode's matching the first basename argument.
If there is no argument, it returns all the immediate children.</p>
</li>
<li><code>children_rx</code><p>Like children but uses a regex.</p>
</li>
<li><code>children_attrib</code><p>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.</p>
</li>
<li><code>children_attrib_rx</code>
<p>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.</p>
</li>
<li><code>attrib</code>
<p>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).</p>
</li>
<li>
</li>
<li><code>attrib_is_true</code><p>Check to see if the attribute supplied is true, (true, yes, 1, etc).
Returns a boolean.</p>
</li>
<li><code>destroy</code><p>Destroy the current node, and all children.</p>
</li>
<li><code>destroy_children</code><p>Destroy all the children of the current node while
leaving the node it is referred from alone.</p>
</li>
<li><code>get_xml</code><p>Returns an XML representation of the given node and
all its children.</p>
</li>
<li><code>get_child_xml</code><p>Returns an XML representation of all the given node's
descendants, NOT including itself.</p>
</li>
<li><code>append_xml</code><p>Parse the given XML string and build the objects it
specifies under the referred ENode.</p>
</li>
<li><code>call</code>
<p>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'.</p>
<p>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.</p>
<p>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).</p>
<p>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.</p>
<p>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.</p>
<p>Example: calling a the python function "foo" with
parameters (1, "a string")</p>
<p>
<blockquote><code>
<pre>
node.call("python:foo", "is", 1, "a string")
</pre>
</code></blockquote>
</p>
</li>
<li><code>new_child</code><p>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.</p>
</li>
<li><code>set_data</code><p>Set the data of the ENode to the string supplied as the only arugment.</p>
</li>
<li><code>get_data</code><p>Retrieve the data of the ENode.</p>
</li>
<li><code>append_data</code><p>Append the string given as the only node, to the data currently
bound to the node.</p>
</li>
<li><code>insert_data</code><p>Insert a string at any location within the current data.</p>
</li>
<li><code>delete_data</code><p>Delete a range of data within the node beginning at any offset.</p>
</li>
</ul>
</p>
<HR NOSHADE>
<A HREF="tutorial.html"><EM> Entity Introduction </EM></A>
<b>:</b> <EM>ENode API</EM><BR>
<b>Previous:</b> <A HREF="tutorial6.html"><EM>A More complex Application</EM></A><BR>
<b>Next:</b> <A HREF="tutorial8.html"><EM>Going Further With Entity</EM></A>
</BODY>
</HTML>
|
