Annotation of gpl/axl/py-axl/doc/node.rst, revision 1.1.1.2
1.1.1.2 ! misho 1: :mod:`axl.Node` --- PyAxlNode class: XML node instance
! 2: ======================================================
1.1 misho 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:
1.1.1.2 ! misho 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.
1.1 misho 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:
1.1.1.2 ! misho 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:
1.1 misho 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:
1.1.1.2 ! misho 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:
1.1 misho 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:
1.1.1.2 ! misho 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).
1.1 misho 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>