[Gd-chatter] r11222 - trunk/documentation/gwydion/gdcore/text
agent at gwydiondylan.org
agent at gwydiondylan.org
Fri Mar 2 10:04:34 CET 2007
Author: agent
Date: Fri Mar 2 10:04:27 2007
New Revision: 11222
Modified:
trunk/documentation/gwydion/gdcore/text/module.simple-xml.system.txt
trunk/documentation/gwydion/gdcore/text/name.Lfile-locatorR.txt
trunk/documentation/gwydion/gdcore/text/name.LobjectR.txt
trunk/documentation/gwydion/gdcore/text/name.Lstretchy-object-vectorR.txt
trunk/documentation/gwydion/gdcore/text/name.Lstring-tableR.txt
trunk/documentation/gwydion/gdcore/text/name.LstringR.txt
trunk/documentation/gwydion/gdcore/text/name.LvectorR.txt
trunk/documentation/gwydion/gdcore/text/name.Lxml-documentR.txt
trunk/documentation/gwydion/gdcore/text/name.Lxml-elementR.txt
trunk/documentation/gwydion/gdcore/text/name.Lxml-errorR.txt
trunk/documentation/gwydion/gdcore/text/name.Lxml-nodeR.txt
trunk/documentation/gwydion/gdcore/text/name.document-element-setter.txt
trunk/documentation/gwydion/gdcore/text/name.document-element.txt
trunk/documentation/gwydion/gdcore/text/name.document-location-setter.txt
trunk/documentation/gwydion/gdcore/text/name.document-location.txt
trunk/documentation/gwydion/gdcore/text/name.node-attribute-setter.txt
trunk/documentation/gwydion/gdcore/text/name.node-attribute.txt
trunk/documentation/gwydion/gdcore/text/name.node-attributes.txt
trunk/documentation/gwydion/gdcore/text/name.node-children.txt
trunk/documentation/gwydion/gdcore/text/name.node-name.txt
trunk/documentation/gwydion/gdcore/text/name.node-text-setter.txt
trunk/documentation/gwydion/gdcore/text/name.node-text.txt
trunk/documentation/gwydion/gdcore/text/name.read-xml-document.txt
trunk/documentation/gwydion/gdcore/text/name.select-node-text.txt
trunk/documentation/gwydion/gdcore/text/name.select-nodes.txt
trunk/documentation/gwydion/gdcore/text/name.select-single-node.txt
Log:
Bug: 7344
Documented simple-xml module.
Modified: trunk/documentation/gwydion/gdcore/text/module.simple-xml.system.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/module.simple-xml.system.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/module.simple-xml.system.txt Fri Mar 2 10:04:27 2007
@@ -1,7 +1,15 @@
Module: Module simple-xml
==============================
-The simple-xml module.
+The simple-xml module provides basic XML parsing and navigation. It only
+supports character data and start, end, and empty-element tags. The module
+does _not_ support entities, comments, CDATA sections, or processing
+instructions. Entities are treated as literal character data, and any other
+markup will likely produce an error.
+
+Therefore, this module can parse some _well-formed_ XML documents, but cannot
+parse any _valid_ XML documents, as valid documents contain a document type
+declaration.
Exported from:
Modified: trunk/documentation/gwydion/gdcore/text/name.Lfile-locatorR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Lfile-locatorR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Lfile-locatorR.txt Fri Mar 2 10:04:27 2007
@@ -25,4 +25,13 @@
- #<file-url>#
+Functions on <file-locator>:
+------------------------------
+- #document-location-setter#
+- #read-xml-document#
+
+Functions returning <file-locator>:
+------------------------------
+- #document-location#
+- #document-location-setter#
Modified: trunk/documentation/gwydion/gdcore/text/name.LobjectR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.LobjectR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.LobjectR.txt Fri Mar 2 10:04:27 2007
@@ -129,10 +129,6 @@
- #direct-instance-of#
- #disjoin#
- #do#
-- #document-element#
-- #document-element-setter#
-- #document-location#
-- #document-location-setter#
- #do-get-input-buffer#
- #do-get-output-buffer#
- #do-next-input-buffer#
@@ -235,13 +231,6 @@
- #negative-option?#
- #next-input-buffer#
- #next-output-buffer#
-- #node-attribute#
-- #node-attributes#
-- #node-attribute-setter#
-- #node-children#
-- #node-name#
-- #node-text#
-- #node-text-setter#
- #null?#
- #object-address#
- #object-class#
@@ -290,7 +279,6 @@
- #read-text-into!#
- #read-through#
- #read-to#
-- #read-xml-document#
- #reduce#
- #reduce-l#
- #reduce-r#
@@ -309,9 +297,6 @@
- #satisfies#
- #second#
- #second-setter#
-- #select-nodes#
-- #select-node-text#
-- #select-single-node#
- #sequence-diff#
- #set-add#
- #set-add!#
@@ -449,10 +434,6 @@
- #direct-instance-of#
- #direct-subclasses#
- #direct-superclasses#
-- #document-element#
-- #document-element-setter#
-- #document-location#
-- #document-location-setter#
- #do-printing-object#
- #do-remove-property!#
- #element#
@@ -522,13 +503,6 @@
- #multi-buffer-working-set#
- #negative#
- #negative-option?#
-- #node-attribute#
-- #node-attributes#
-- #node-attribute-setter#
-- #node-children#
-- #node-name#
-- #node-text#
-- #node-text-setter#
- #option-default-value#
- #option-default-value-setter#
- #option-might-have-parameters?#
@@ -561,7 +535,6 @@
- #read-text-into!#
- #read-through#
- #read-to#
-- #read-xml-document#
- #reduce#
- #reduce1#
- #reduce-l#
@@ -573,9 +546,6 @@
- #satisfies#
- #second#
- #second-setter#
-- #select-nodes#
-- #select-node-text#
-- #select-single-node#
- #sequence-diff#
- #set-add#
- #set-add!#
Modified: trunk/documentation/gwydion/gdcore/text/name.Lstretchy-object-vectorR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Lstretchy-object-vectorR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Lstretchy-object-vectorR.txt Fri Mar 2 10:04:27 2007
@@ -21,4 +21,6 @@
- <builtin-stretchy-vector>
-
+Functions returning <stretchy-object-vector>:
+------------------------------
+- #node-children#
Modified: trunk/documentation/gwydion/gdcore/text/name.Lstring-tableR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Lstring-tableR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Lstring-tableR.txt Fri Mar 2 10:04:27 2007
@@ -30,4 +30,6 @@
- #<value-table>#
-
+Functions returning <string-table>:
+------------------------------
+- #node-attributes#
Modified: trunk/documentation/gwydion/gdcore/text/name.LstringR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.LstringR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.LstringR.txt Fri Mar 2 10:04:27 2007
@@ -55,6 +55,9 @@
- #make-regexp-replacer#
- #make-splitter#
- #make-translator#
+- #node-attribute#
+- #node-attribute-setter#
+- #node-text-setter#
- #option-description-setter#
- #option-parser-by-long-name#
- #option-present?-by-long-name#
@@ -65,6 +68,9 @@
- #regexp-position#
- #regexp-replace#
- #run-application#
+- #select-node-text#
+- #select-nodes#
+- #select-single-node#
- #signal#
- #signal-application-event#
- #split#
@@ -92,6 +98,11 @@
- #login-group#
- #login-name#
- #machine-word-to-string#
+- #node-attribute#
+- #node-attribute-setter#
+- #node-name#
+- #node-text#
+- #node-text-setter#
- #number-to-string#
- #option-description#
- #option-description-setter#
@@ -99,6 +110,7 @@
- #owner-organization#
- #print-to-string#
- #regexp-replace#
+- #select-node-text#
- #split#
- #thread-name#
- #translate#
Modified: trunk/documentation/gwydion/gdcore/text/name.LvectorR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.LvectorR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.LvectorR.txt Fri Mar 2 10:04:27 2007
@@ -50,3 +50,7 @@
- #find-first-key#
- #find-last-key#
+
+Methods returning <vector>:
+------------------------------
+- #select-nodes#
Modified: trunk/documentation/gwydion/gdcore/text/name.Lxml-documentR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Lxml-documentR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Lxml-documentR.txt Fri Mar 2 10:04:27 2007
@@ -1,7 +1,7 @@
Class: <xml-document>
==============================
-A class.
+A class representing an XML document.
Exported from:
@@ -14,9 +14,26 @@
concrete free sealed
+Make keywords:
+------------------------------
+location: - An instance of #<file-locator>#. Required.
+element: - An instance of #<xml-element>#. The document element. Optional.
+
+
Superclasses:
------------------------------
- #<object>#
+Functions on <xml-document>:
+------------------------------
+- #document-element#
+- #document-element-setter#
+- #document-location#
+- #document-location-setter#
+
+
+Functions returning <xml-document>:
+------------------------------
+- #read-xml-document#
Modified: trunk/documentation/gwydion/gdcore/text/name.Lxml-elementR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Lxml-elementR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Lxml-elementR.txt Fri Mar 2 10:04:27 2007
@@ -1,7 +1,7 @@
Class: <xml-element>
==============================
-A class.
+A class representing an XML element.
Exported from:
@@ -14,9 +14,37 @@
concrete free sealed
+Make keywords:
+------------------------------
+name: - An instance of #<string>#. Required.
+attributes: - An instance of #<string-table>#. Optional.
+text: - An instance of #<string>#. Defaults to "".
+
+
Superclasses:
------------------------------
- #<xml-node>#
+Functions on <xml-element>:
+------------------------------
+- #document-element-setter#
+- #node-attribute#
+- #node-attribute-setter#
+- #node-attributes#
+- #node-children#
+- #node-name#
+- #node-text#
+- #node-text-setter#
+- #select-node-text#
+- #select-nodes#
+- #select-single-node#
+
+Functions returning <xml-element>:
+------------------------------
+- #document-element#
+- #document-element-setter#
+- #node-children#
+- #select-nodes#
+- #select-single-node#
Modified: trunk/documentation/gwydion/gdcore/text/name.Lxml-errorR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Lxml-errorR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Lxml-errorR.txt Fri Mar 2 10:04:27 2007
@@ -1,7 +1,7 @@
Class: <xml-error>
==============================
-A class.
+The class of XML parsing errors.
Exported from:
@@ -17,7 +17,7 @@
Superclasses:
------------------------------
- #<error>#
- - #<format-string-condition>#
+- #<format-string-condition>#
Modified: trunk/documentation/gwydion/gdcore/text/name.Lxml-nodeR.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.Lxml-nodeR.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.Lxml-nodeR.txt Fri Mar 2 10:04:27 2007
@@ -1,7 +1,7 @@
Class: <xml-node>
==============================
-A class.
+A class representing an XML node.
Exported from:
Modified: trunk/documentation/gwydion/gdcore/text/name.document-element-setter.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.document-element-setter.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.document-element-setter.txt Fri Mar 2 10:04:27 2007
@@ -1,7 +1,7 @@
Generic: document-element-setter
==============================
-A generic function.
+Sets the root element of an #<xml-document>#.
Exported from:
@@ -16,13 +16,13 @@
Arguments:
------------------------------
-arg - An instance of #<object>#.
-arg - An instance of #<object>#.
+element - An instance of #<xml-element># or #f.
+document - An instance of #<xml-document>#.
Values:
------------------------------
-#rest more - Instances of #<object>#.
+element - The _element_ argument.
Modified: trunk/documentation/gwydion/gdcore/text/name.document-element.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.document-element.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.document-element.txt Fri Mar 2 10:04:27 2007
@@ -1,7 +1,7 @@
Generic: document-element
==============================
-A generic function.
+Returns the root element of an #<xml-document>#.
Exported from:
@@ -16,12 +16,12 @@
Arguments:
------------------------------
-arg - An instance of #<object>#.
+document - An instance of #<xml-document>#.
Values:
------------------------------
-#rest more - Instances of #<object>#.
+element - An instance of #<xml-element>#, or #f.
Modified: trunk/documentation/gwydion/gdcore/text/name.document-location-setter.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.document-location-setter.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.document-location-setter.txt Fri Mar 2 10:04:27 2007
@@ -1,7 +1,8 @@
Generic: document-location-setter
==============================
-A generic function.
+Sets the file location of an #<xml-document>#. This does not cause the
+document to be re-parsed.
Exported from:
@@ -16,13 +17,13 @@
Arguments:
------------------------------
-arg - An instance of #<object>#.
-arg - An instance of #<object>#.
+locator - An instance of #<file-locator>#.
+document - An instance of #<xml-document>#.
Values:
------------------------------
-#rest more - Instances of #<object>#.
+locator - An instance of #<file-locator>#. The _locator_ argument.
Modified: trunk/documentation/gwydion/gdcore/text/name.document-location.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.document-location.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.document-location.txt Fri Mar 2 10:04:27 2007
@@ -1,7 +1,7 @@
Generic: document-location
==============================
-A generic function.
+Returns the file location of an #<xml-document>#.
Exported from:
@@ -16,12 +16,12 @@
Arguments:
------------------------------
-arg - An instance of #<object>#.
+document - An instance of #<xml-document>#.
Values:
------------------------------
-#rest more - Instances of #<object>#.
+locator - An instance of #<file-locator>#.
Modified: trunk/documentation/gwydion/gdcore/text/name.node-attribute-setter.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.node-attribute-setter.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.node-attribute-setter.txt Fri Mar 2 10:04:27 2007
@@ -1,7 +1,9 @@
Generic: node-attribute-setter
==============================
-A generic function.
+Sets the value of an attribute of an #<xml-element>#. This function does not
+follow the normal -setter syntax. If _attribute_ is not present in _element_,
+it is added.
Exported from:
@@ -16,14 +18,13 @@
Arguments:
------------------------------
-arg - An instance of #<object>#.
-arg - An instance of #<object>#.
-arg - An instance of #<object>#.
+value - An instance of #<string>#. The new value of the attribute.
+element - An instance of #<xml-element>#.
+attribute - An instance of #<string>#. The name of the attribute.
Values:
------------------------------
-#rest more - Instances of #<object>#.
-
+value - An instance of #<string>#. The _value_ argument.
Modified: trunk/documentation/gwydion/gdcore/text/name.node-attribute.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.node-attribute.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.node-attribute.txt Fri Mar 2 10:04:27 2007
@@ -1,7 +1,7 @@
Generic: node-attribute
==============================
-A generic function.
+Returns the value of an attribute of an #<xml-element>#.
Exported from:
@@ -16,13 +16,14 @@
Arguments:
------------------------------
-arg - An instance of #<object>#.
-arg - An instance of #<object>#.
+element - An instance of #<xml-element>#.
+attribute - An instance of #<string>#. The name of an attribute.
Values:
------------------------------
-#rest more - Instances of #<object>#.
+value - An instances of #<string># or #f if the _attribute_ is not present
+ in the _element_.
Modified: trunk/documentation/gwydion/gdcore/text/name.node-attributes.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.node-attributes.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.node-attributes.txt Fri Mar 2 10:04:27 2007
@@ -1,7 +1,8 @@
Generic: node-attributes
==============================
-A generic function.
+Returns all the attributes of an #<xml-element># in a table. The table may be
+modified safely.
Exported from:
@@ -16,12 +17,12 @@
Arguments:
------------------------------
-arg - An instance of #<object>#.
+element - An instance of #<xml-element>#.
Values:
------------------------------
-#rest more - Instances of #<object>#.
+attributes - An instance of #<string-table>#.
Modified: trunk/documentation/gwydion/gdcore/text/name.node-children.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.node-children.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.node-children.txt Fri Mar 2 10:04:27 2007
@@ -1,7 +1,7 @@
Generic: node-children
==============================
-A generic function.
+Returns the child elements of an #<xml-element>#.
Exported from:
@@ -16,12 +16,13 @@
Arguments:
------------------------------
-arg - An instance of #<object>#.
+element - An instance of #<xml-element>#.
Values:
------------------------------
-#rest more - Instances of #<object>#.
+children - An instance of #<stretchy-object-vector># containing instances of
+ #<xml-element>#.
Modified: trunk/documentation/gwydion/gdcore/text/name.node-name.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.node-name.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.node-name.txt Fri Mar 2 10:04:27 2007
@@ -1,7 +1,7 @@
Generic: node-name
==============================
-A generic function.
+Returns the tag name of an #<xml-element>#.
Exported from:
@@ -16,12 +16,12 @@
Arguments:
------------------------------
-arg - An instance of #<object>#.
+element - An instance of #<xml-element>#.
Values:
------------------------------
-#rest more - Instances of #<object>#.
+name - An instance of #<string>#.
Modified: trunk/documentation/gwydion/gdcore/text/name.node-text-setter.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.node-text-setter.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.node-text-setter.txt Fri Mar 2 10:04:27 2007
@@ -1,7 +1,7 @@
Generic: node-text-setter
==============================
-A generic function.
+Sets the character data of an #<xml-element>#.
Exported from:
@@ -16,13 +16,13 @@
Arguments:
------------------------------
-arg - An instance of #<object>#.
-arg - An instance of #<object>#.
+text - An instance of #<string>#.
+element - An instance of #<xml-element>#.
Values:
------------------------------
-#rest more - Instances of #<object>#.
+text - An instance of #<string>#. The _text_ argument.
Modified: trunk/documentation/gwydion/gdcore/text/name.node-text.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.node-text.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.node-text.txt Fri Mar 2 10:04:27 2007
@@ -1,7 +1,8 @@
Generic: node-text
==============================
-A generic function.
+Returns the character data of an #<xml-element>#. This does not include child
+elements' character data.
Exported from:
@@ -16,12 +17,12 @@
Arguments:
------------------------------
-arg - An instance of #<object>#.
+element - An instance of #<xml-element>#.
Values:
------------------------------
-#rest more - Instances of #<object>#.
+text - An instance of #<string>#.
Modified: trunk/documentation/gwydion/gdcore/text/name.read-xml-document.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.read-xml-document.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.read-xml-document.txt Fri Mar 2 10:04:27 2007
@@ -1,7 +1,8 @@
Generic: read-xml-document
==============================
-A generic function.
+Reads a simple XML file and returns an #<xml-document>#. If the file cannot be
+parsed, this function signals an #<xml-error>#.
Exported from:
@@ -16,12 +17,12 @@
Arguments:
------------------------------
-arg - An instance of #<object>#.
+file - An instance of #<file-locator>#.
Values:
------------------------------
-#rest more - Instances of #<object>#.
+page - An instance of #<xml-document>#.
Modified: trunk/documentation/gwydion/gdcore/text/name.select-node-text.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.select-node-text.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.select-node-text.txt Fri Mar 2 10:04:27 2007
@@ -1,7 +1,30 @@
Generic: select-node-text
==============================
-A generic function.
+Returns the character data of the first XML element matching a path. This
+function calls #select-nodes# with _node_ and _path_ and returns the character
+data for the first element. See #select-nodes# for more about _path_.
+
+(example)
+<population>
+ <pack id="1">
+ <name>Scar</name>
+ <name>Notch</name>
+ </pack>
+ <pack id="2">
+ <leader>Rex</leader>
+ <name>Spotty</name>
+ </pack>
+</population>
+(end)
+
+Given the above example document, #select-node-text# behaves as follows.
+
+(code)
+select-node-text(rootNode, "pack/name")
+ ⇒ "Scar"
+(end code)
+
Exported from:
@@ -16,13 +39,15 @@
Arguments:
------------------------------
-arg - An instance of #<object>#.
-arg - An instance of #<object>#.
+node - An instance of #<xml-element>#.
+path - An instance of #<string>#.
+default: - An instance of #<string>#. A string to return if a matching XML
+ element is not found. Defaults to "".
Values:
------------------------------
-#rest more - Instances of #<object>#.
+text - An instance of #<string>#.
Modified: trunk/documentation/gwydion/gdcore/text/name.select-nodes.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.select-nodes.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.select-nodes.txt Fri Mar 2 10:04:27 2007
@@ -1,7 +1,38 @@
Generic: select-nodes
==============================
-A generic function.
+Returns nodes matching a path. _path_ is a string of the form "name" or
+"name/name/name…" and denotes a series of child nodes relative to _node_. _path_ should not begin or end with '/'.
+
+#select-nodes# follows _node_'s children down the first child of every subnode
+that matches the corresponding _name_. If the last _name_ in the path matches
+more than one element, all are returned.
+
+(example)
+<population>
+ <pack id="1">
+ <name>Scar</name>
+ <name>Notch</name>
+ </pack>
+ <pack id="2">
+ <leader>Rex</leader>
+ <name>Spotty</name>
+ </pack>
+</population>
+(end)
+
+Given the above example document, #select-nodes# behaves as follows.
+
+(code)
+select-nodes(rootNode, "pack")
+ ⇒ #[ {pack id="1"}, {pack id="2"} ]
+
+select-nodes(rootNode, "pack/name")
+ ⇒ #[ {name "Scar"}, {name "Notch"} ]
+
+select-nodes(rootNode, "pack/leader")
+ ⇒ #[]
+(end code)
Exported from:
@@ -16,13 +47,12 @@
Arguments:
------------------------------
-arg - An instance of #<object>#.
-arg - An instance of #<object>#.
+node - An instance of #<xml-element>#.
+path - An instance of #<string>#.
Values:
------------------------------
-#rest more - Instances of #<object>#.
-
+nodes - An instance of #<vector># containing #<xml-element># objects.
Modified: trunk/documentation/gwydion/gdcore/text/name.select-single-node.txt
==============================================================================
--- trunk/documentation/gwydion/gdcore/text/name.select-single-node.txt (original)
+++ trunk/documentation/gwydion/gdcore/text/name.select-single-node.txt Fri Mar 2 10:04:27 2007
@@ -1,7 +1,30 @@
Generic: select-single-node
==============================
-A generic function.
+Returns the first XML element matching a path. This function calls
+#select-nodes# with _node_ and _path_ and returns the first element found. See
+#select-nodes# for more about _path_.
+
+(example)
+<population>
+ <pack id="1">
+ <name>Scar</name>
+ <name>Notch</name>
+ </pack>
+ <pack id="2">
+ <leader>Rex</leader>
+ <name>Spotty</name>
+ </pack>
+</population>
+(end)
+
+Given the above example document, #select-single-node# behaves as follows.
+
+(code)
+select-nodes(rootNode, "pack/name")
+ ⇒ {name "Scar"}
+(end code)
+
Exported from:
@@ -16,13 +39,14 @@
Arguments:
------------------------------
-arg - An instance of #<object>#.
-arg - An instance of #<object>#.
+node - An instance of #<xml-element>#.
+path - An instance of #<string>#.
Values:
------------------------------
-#rest more - Instances of #<object>#.
+found-node - An instance of #<xml-element>#, or #f if no matching XML element
+ was found.
More information about the chatter
mailing list