1: :mod:`axl.Node` --- PyAxlNode class: XML node instance
2: ======================================================
3:
4: .. currentmodule:: axl
5:
6:
7: =====
8: Intro
9: =====
10:
11: :class:`axl.Node` class represents a single node instance that is hold
12: by a document (:class:`axl.Doc`).
13:
14: The usual operation is to load a document and the acquire a reference to the node inside as follows::
15:
16: # load the document
17: (doc, err) = axl.parse ("<root-node><child /></root-node>")
18: if err:
19: print ("Failed to parse content: " + err.msg)
20: return -1
21:
22: # get the <child> node
23: node = doc.get ("/root-node/child")
24:
25:
26: However, you can also create new nodes using the type constructor of :class:`axl.Node` as follows::
27:
28: # set a new root node
29: doc.root = axl.Node ("test")
30:
31:
32: ==========
33: Module API
34: ==========
35:
36: .. class:: Node
37:
38: .. method:: next_called (node_name)
39:
40: Allows to get the next node on the same level or the instance
41: node, but with the provide name.
42:
43: :param node_name: node name to match.
44: :type node_name: String
45:
46: :rtype: Returns an instance of :class:`axl.Node` or None if no node was found.
47:
48: .. method:: previous_called (node_name)
49:
50: Allows to get the previous node on the same level or the instance
51: node, but with the provide name.
52:
53: :param node_name: node name to match.
54: :type node_name: String
55:
56: :rtype: Returns an instance of :class:`axl.Node` or None if no node was found.
57:
58: .. method:: child_called (node_name)
59:
60: Allows to get the first node child, but with the provide name.
61:
62: :param node_name: node name to match.
63: :type node_name: String
64:
65: :rtype: Returns an instance of :class:`axl.Node` or None if no node was found.
66:
67: .. method:: find_called (node_name)
68:
69: Gets the xml child node called as provided. The child is looked
70: up in all childs found starting the parent node.
71:
72: :param node_name: node name to match.
73: :type node_name: String
74:
75: :rtype: Returns an instance of :class:`axl.Node` or None if no node was found.
76:
77: .. method:: nth_called (position)
78:
79: Allows to get a reference to the child node located at the same
80: level at the nth position.
81:
82: :param position: node position.
83: :type position: Integer
84:
85: :rtype: Returns an instance of :class:`axl.Node` or None if no node was found.
86:
87: .. method:: has_attr (attr_name, [attr_value])
88:
89: Allows to check if the provided node has the given attribute.
90:
91: :param attr_name: the attribute name to check.
92: :type attr_name: String
93:
94: :param attr_value: Optional the attribute value to check. If provided the method check if the node has an attribute with the provided value.
95: :type attr_value: String
96:
97: :rtype: Returns the presence of the provided attribute on the given node, and optionall checking if that attribute has a particular value.
98:
99: .. method:: attr (attr_name, [value])
100:
101: Allows to get the value associated to the attribute (attr_name)
102: or to configure the provided value if two arguments are
103: provided.
104:
105: :param attr_name: the attribute name to get its value.
106: :type attr_name: String
107:
108: :param value: If provided, allows to configure the value on the attribute (attr_name).
109: :type value: String
110:
111: :rtype: Returns a string if only one parameter is provided representing the attribute value or None if attribute and value are provided.
112:
113: .. method:: attr_trans (attr_name)
114:
115: Gets the attribute content for the provided attribute name, at the provided node, but translating entity references found.
116:
117: :param attr_name: the attribute name to get its value.
118: :type attr_name: String
119:
120: :rtype: Returns a string or None representing the attribute value.
121:
122: .. method:: set_child (node)
123:
124: Allows to configure a new child node.
125:
126: :param node: the new child node to configure.
127: :type node: :class:`axl.Node`
128:
129: .. method:: set_child_after (node)
130:
131: Allows to configure a new child node placing it after the calling node inside the same level. Both nodes will share parent node. Node must be not attached to a document. See :meth:`deattach` to disconnect a node from a document or create a new node (:class:`axl.Node`).
132:
133: :param node: the new child node to configure.
134: :type node: :class:`axl.Node`
135:
136: .. method:: attr_cursor_new ()
137:
138: Creates a new :class:`axl.AttrCursor` instance which is used to
139: perform efficient node attribute iteration. See axl_node_attr_cursor_new.
140:
141: :param node: the new child node to configure.
142: :type node: axl.Node
143:
144: .. method:: remove ([dealloc=True])
145:
146: Allows to remove the node from its current document. By default
147: the internal node is deallocated.
148:
149: :param node: the new node to be removed from current holding document
150: :type node: :class:`axl.Node`
151:
152: .. method:: replace ([dealloc=True])
153:
154: Allows to remove the node from its current document. By default
155: the internal node is deallocated.
156:
157: :param node: the new node to be removed from current holding document
158: :type node: :class:`axl.Node`
159:
160: .. method:: deattach ()
161:
162: Allows to disconnect the node from its current document.
163:
164: .. method:: set_empty ()
165:
166: Allows to clear all content set inside a particular node.
167:
168: .. attribute:: name
169:
170: (Read only attribute) (String) Allows to get the node name.
171:
172: .. attribute:: first_child
173:
174: (Read only attribute) (:class:`axl.Node`) Allows to get first node child.
175:
176: .. attribute:: next
177:
178: (Read only attribute) (:class:`axl.Node`) Allows to get next node.
179:
180: .. attribute:: previous
181:
182: (Read only attribute) (:class:`axl.Node`) Allows to get previous node.
183:
184: .. attribute:: parent
185:
186: (Read only attribute) (:class:`axl.Node`) Allows to get parent node.
187:
188: .. attribute:: content
189:
190: (Read/Write attribute) (:class:`axl.Node`) Allows to get/set the
191: node content. See axl_node_get_content and axl_node_set_content
192: from C API. The attribute detects on write operations if the
193: content to be configured is not supported directly without replacing &, <, ', >, ", and ;. In such case, Axl API translate the content (replacing those values by &, <, etc...).
194:
195: The attribute returns a tuple with (content, size).
196:
197: .. attribute:: trans
198:
199: (Read only attribute) (:class:`axl.Node`) Allows to get content stored on a node translating known entity references: &, <, etc..
200:
201: The attribute returns a tuple with (content, size).
202:
203: .. attribute:: doc
204:
205: (Read only attribute) (:class:`axl.Doc`) Allows to get the document that holds the node.
206:
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>