rexml 3.2.4 → 3.2.5

data/doc/rexml/tasks/rdoc/node.rdoc

@@ -0,0 +1,97 @@
+== Module Node
+
+:include: ../tocs/node_toc.rdoc
+
+=== Siblings
+
+==== Task: Find Previous Sibling
+
+Use method
+{Node.previous_sibling_node}[../../../../REXML/Node.html#method-i-previous_sibling]
+to retrieve the previous sibling:
+
+  d = REXML::Document.new('<root><a/><b/><c/></root>')
+  b = d.root[1]           # => <b/>
+  b.previous_sibling_node # => <a/>
+
+==== Task: Find Next Sibling
+
+Use method
+{Node.next_sibling_node}[../../../../REXML/Node.html#method-i-next_sibling]
+to retrieve the next sibling:
+
+  d = REXML::Document.new('<root><a/><b/><c/></root>')
+  b = d.root[1]       # => <b/>
+  b.next_sibling_node # => <c/>
+
+=== Position
+
+==== Task: Find Own Index Among Siblings
+
+Use method
+{Node.index_in_parent}[../../../../REXML/Node.html#method-i-index_in_parent]
+to retrieve the 1-based index of this node among its siblings:
+
+  d = REXML::Document.new('<root><a/><b/><c/></root>')
+  b = d.root[1]     # => <b/>
+  b.index_in_parent # => 2
+
+=== Recursive Traversal
+
+==== Task: Traverse Each Recursively
+
+Use method
+{Node.each_recursive}[../../../../REXML/Node.html#method-i-each_recursive]
+to traverse a tree of nodes recursively:
+
+  xml_string = '<root><a><b><c></c></b><b><c></c></b></a></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.each_recursive {|node| p node }
+
+Output:
+
+  <a> ... </>
+  <b> ... </>
+  <c/>
+  <b> ... </>
+  <c/>
+
+=== Recursive Search
+
+==== Task: Traverse Each Recursively
+
+Use method
+{Node.find_first_recursive}[../../../../REXML/Node.html#method-i-find_first_recursive]
+to search a tree of nodes recursively:
+
+  xml_string = '<root><a><b><c></c></b><b><c></c></b></a></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.find_first_recursive {|node| node.name == 'c' } # => <c/>
+
+=== Representation
+
+==== Task: Represent a String
+
+Use method {Node.to_s}[../../../../REXML/Node.html#method-i-to_s]
+to represent the node as a string:
+
+  xml_string = '<root><a><b><c></c></b><b><c></c></b></a></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.to_s # => "<root><a><b><c/></b><b><c/></b></a></root>"
+
+=== Parent?
+
+==== Task: Determine Whether the Node is a Parent
+
+Use method {Node.parent?}[../../../../REXML/Node.html#method-i-parent-3F]
+to determine whether the node is a parent;
+class Text derives from Node:
+
+  d = REXML::Document.new('<root><a/>text<b/>more<c/></root>')
+  t = d.root[1] # => "text"
+  t.parent?     # => false
+
+Class Parent also derives from Node, but overrides this method:
+
+  p = REXML::Parent.new
+  p.parent? # => true

data/doc/rexml/tasks/rdoc/parent.rdoc

@@ -0,0 +1,267 @@
+== Class Parent
+
+Class Parent has methods from its superclasses and included modules;
+see:
+
+- {Tasks for Child}[child_rdoc.html].
+- {Tasks for Node}[node_rdoc.html].
+- {Module Enumerable}[https://docs.ruby-lang.org/en/master/Enumerable.html].
+
+:include: ../tocs/parent_toc.rdoc
+
+=== Queries
+
+==== Task: Get the Count of Children
+
+Use method {Parent#size}[../../../../REXML/Parent.html#method-i-size]
+(or its alias +length+) to get the count of the parent's children:
+
+  p = REXML::Parent.new
+  p.size # => 0
+  xml_string = '<root><a/><b/><c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.size # => 3
+
+==== Task: Get the Child at a Given Index
+
+Use method {Parent#[]}[../../../../REXML/Parent.html#method-i-5B-5D]
+to get the child at a given index:
+
+  xml_string = '<root><a/><b/><c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root[1]  # => <b/>
+  d.root[-1] # => <c/>
+  d.root[50] # => nil
+
+==== Task: Get the Index of a Given Child
+
+Use method {Parent#index}[../../../../REXML/Parent.html#method-i-index]
+to get the index (0-based offset) of a child:
+
+  d = REXML::Document.new('<root></root>')
+  root = d.root
+  e0 = REXML::Element.new('foo')
+  e1 = REXML::Element.new('bar')
+  root.add(e0)  # => <foo/>
+  root.add(e1)  # => <bar/>
+  root.add(e0)  # => <foo/>
+  root.add(e1)  # => <bar/>
+  root.index(e0) # => 0
+  root.index(e1) # => 1
+
+==== Task: Get the Children
+
+Use method {Parent#children}[../../../../REXML/Parent.html#method-i-children]
+(or its alias +to_a+) to get the parent's children:
+
+  xml_string = '<root><a/><b/><c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.children # => [<a/>, <b/>, <c/>]
+
+==== Task: Determine Whether the Node is a Parent
+
+Use method {Parent#parent?}[../../../../REXML/Parent.html#method-i-parent-3F]
+to determine whether the node is a parent;
+class Text derives from Node:
+
+  d = REXML::Document.new('<root><a/>text<b/>more<c/></root>')
+  t = d.root[1] # => "text"
+  t.parent?     # => false
+
+Class Parent also derives from Node, but overrides this method:
+
+  p = REXML::Parent.new
+  p.parent? # => true
+
+=== Additions
+
+==== Task: Add a Child at the Beginning
+
+Use method {Parent#unshift}[../../../../REXML/Parent.html#method-i-unshift]
+to add a child as at the beginning of the children:
+
+  xml_string = '<root><a/><b/><c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.children # => [<a/>, <b/>, <c/>]
+  d.root.unshift REXML::Element.new('d')
+  d.root.children # => [<d/>, <a/>, <b/>, <c/>]
+
+==== Task: Add a Child at the End
+
+Use method {Parent#<<}[../../../../REXML/Parent.html#method-i-3C-3C]
+(or an alias +push+ or +add+) to add a child as at the end of the children:
+
+  xml_string = '<root><a/><b/><c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.children # => [<a/>, <b/>, <c/>]
+  d.root << REXML::Element.new('d')
+  d.root.children # => [<a/>, <b/>, <c/>, <d/>]
+
+==== Task: Replace a Child with Another Child
+
+Use method {Parent#replace}[../../../../REXML/Parent.html#method-i-replace]
+
+  xml_string = '<root><a/><b/><c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.children # => [<a/>, <b/>, <c/>]
+  b = d.root[1]   # => <b/>
+  d.replace_child(b, REXML::Element.new('d'))
+  d.root.children # => [<a/>, <c/>]
+
+==== Task: Replace Multiple Children with Another Child
+
+Use method {Parent#[]=}[../../../../REXML/Parent.html#method-i-parent-5B-5D-3D]
+to replace multiple consecutive children with another child:
+
+  xml_string = '<root><a/><b/><c/><d/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.children # => [<a/>, <b/>, <c/>, <d/>]
+  d.root[1, 2] = REXML::Element.new('x')
+  d.root.children # => [<a/>, <x/>, <d/>]
+  d.root[1, 5] = REXML::Element.new('x')
+  d.root.children # => [<a/>, <x/>] # BUG?
+
+==== Task: Insert Child Before a Given Child
+
+Use method {Parent#insert_before}[../../../../REXML/Parent.html#method-i-insert_before]
+to insert a child immediately before a given child:
+
+  xml_string = '<root><a/><b/><c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.children # => [<a/>, <b/>, <c/>]
+  b = d.root[1]   # => <b/>
+  x = REXML::Element.new('x')
+  d.root.insert_before(b, x)
+  d.root.children # => [<a/>, <x/>, <b/>, <c/>]
+
+==== Task: Insert Child After a Given Child
+
+Use method {Parent#insert_after}[../../../../REXML/Parent.html#method-i-insert_after]
+to insert a child immediately after a given child:
+
+  xml_string = '<root><a/><b/><c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.children # => [<a/>, <b/>, <c/>]
+  b = d.root[1]   # => <b/>
+  x = REXML::Element.new('x')
+  d.root.insert_after(b, x)
+  d.root.children # => [<a/>, <b/>, <x/>, <c/>]
+
+=== Deletions
+
+==== Task: Remove a Given Child
+
+Use method {Parent#delete}[../../../../REXML/Parent.html#method-i-delete]
+to remove all occurrences of a given child:
+
+  d = REXML::Document.new('<root></root>')
+  a = REXML::Element.new('a')
+  b = REXML::Element.new('b')
+  d.root.add(a)
+  d.root.add(b)
+  d.root.add(a)
+  d.root.add(b)
+  d.root.children # => [<a/>, <b/>, <a/>, <b/>]
+  d.root.delete(b)
+  d.root.children # => [<a/>, <a/>]
+
+==== Task: Remove the Child at a Specified Offset
+
+Use method {Parent#delete_at}[../../../../REXML/Parent.html#method-i-delete_at]
+to remove the child at a specified offset:
+
+  d = REXML::Document.new('<root></root>')
+  a = REXML::Element.new('a')
+  b = REXML::Element.new('b')
+  d.root.add(a)
+  d.root.add(b)
+  d.root.add(a)
+  d.root.add(b)
+  d.root.children # => [<a/>, <b/>, <a/>, <b/>]
+  d.root.delete_at(2)
+  d.root.children # => [<a/>, <b/>, <b/>]
+
+==== Task: Remove Children That Meet Specified Criteria
+
+Use method {Parent#delete_if}[../../../../REXML/Parent.html#method-i-delete_if]
+to remove children that meet criteria specified in the given block:
+
+  d = REXML::Document.new('<root></root>')
+  d.root.add(REXML::Element.new('x'))
+  d.root.add(REXML::Element.new('xx'))
+  d.root.add(REXML::Element.new('xxx'))
+  d.root.add(REXML::Element.new('xxxx'))
+  d.root.children # => [<x/>, <xx/>, <xxx/>, <xxxx/>]
+  d.root.delete_if {|child| child.name.size.odd? }
+  d.root.children # => [<xx/>, <xxxx/>]
+
+=== Iterations
+
+==== Task: Iterate Over Children
+
+Use method {Parent#each_child}[../../../../REXML/Parent.html#method-i-each_child]
+(or its alias +each+) to iterate over all children:
+
+  xml_string = '<root><a/><b/><c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.children # => [<a/>, <b/>, <c/>]
+  d.root.each_child {|child| p child }
+
+Output:
+
+  <a/>
+  <b/>
+  <c/>
+
+==== Task: Iterate Over Child Indexes
+
+Use method {Parent#each_index}[../../../../REXML/Parent.html#method-i-each_index]
+to iterate over all child indexes:
+
+  xml_string = '<root><a/><b/><c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.children # => [<a/>, <b/>, <c/>]
+  d.root.each_index {|child| p child }
+
+Output:
+
+  0
+  1
+  2
+
+=== Clones
+
+==== Task: Clone Deeply
+
+Use method {Parent#deep_clone}[../../../../REXML/Parent.html#method-i-deep_clone]
+to clone deeply; that is, to clone every nested node that is a Parent object:
+
+  xml_string = <<-EOT
+    <?xml version="1.0" encoding="UTF-8"?>
+    <bookstore>
+      <book category="cooking">
+        <title lang="en">Everyday Italian</title>
+        <author>Giada De Laurentiis</author>
+        <year>2005</year>
+        <price>30.00</price>
+      </book>
+      <book category="children">
+        <title lang="en">Harry Potter</title>
+        <author>J K. Rowling</author>
+        <year>2005</year>
+        <price>29.99</price>
+      </book>
+      <book category="web">
+        <title lang="en">Learning XML</title>
+        <author>Erik T. Ray</author>
+        <year>2003</year>
+        <price>39.95</price>
+      </book>
+    </bookstore>
+  EOT
+  d = REXML::Document.new(xml_string)
+  root = d.root
+  shallow = root.clone
+  deep = root.deep_clone
+  shallow.to_s.size # => 12
+  deep.to_s.size    # => 590

data/doc/rexml/tasks/tocs/child_toc.rdoc

@@ -0,0 +1,12 @@
+Tasks on this page:
+
+- {Relationships}[#label-Relationships]
+  - {Task: Set the Parent}[#label-Task-3A+Set+the+Parent]
+  - {Task: Insert Previous Sibling}[#label-Task-3A+Insert+Previous+Sibling]
+  - {Task: Insert Next Sibling}[#label-Task-3A+Insert+Next+Sibling]
+- {Removal or Replacement}[#label-Removal+or+Replacement]
+  - {Task: Remove Child from Parent}[#label-Task-3A+Remove+Child+from+Parent]
+  - {Task: Replace Child}[#label-Task-3A+Replace+Child]
+- {Document}[#label-Document]
+  - {Task: Get the Document}[#label-Task-3A+Get+the+Document]
+

data/doc/rexml/tasks/tocs/document_toc.rdoc

@@ -0,0 +1,30 @@
+Tasks on this page:
+
+- {New Document}[#label-New+Document]
+  - {Task: Create an Empty Document}[#label-Task-3A+Create+an+Empty+Document]
+  - {Task: Parse a String into a New Document}[#label-Task-3A+Parse+a+String+into+a+New+Document]
+  - {Task: Parse an IO Stream into a New Document}[#label-Task-3A+Parse+an+IO+Stream+into+a+New+Document]
+  - {Task: Create a Document from an Existing Document}[#label-Task-3A+Create+a+Document+from+an+Existing+Document]
+  - {Task: Clone a Document}[#label-Task-3A+Clone+a+Document]
+- {Document Type}[#label-Document+Type]
+  - {Task: Get the Document Type}[#label-Task-3A+Get+the+Document+Type]
+  - {Task: Set the Document Type}[#label-Task-3A+Set+the+Document+Type]
+- {XML Declaration}[#label-XML+Declaration]
+  - {Task: Get the XML Declaration}[#label-Task-3A+Get+the+XML+Declaration]
+  - {Task: Set the XML Declaration}[#label-Task-3A+Set+the+XML+Declaration]
+- {Children}[#label-Children]
+  - {Task: Add an Element Child}[#label-Task-3A+Add+an+Element+Child]
+  - {Task: Add a Non-Element Child}[#label-Task-3A+Add+a+Non-Element+Child]
+- {Writing}[#label-Writing]
+  - {Task: Write to $stdout}[#label-Task-3A+Write+to+-24stdout]
+  - {Task: Write to IO Stream}[#label-Task-3A+Write+to+IO+Stream]
+  - {Task: Write with No Indentation}[#label-Task-3A+Write+with+No+Indentation]
+  - {Task: Write with Specified Indentation}[#label-Task-3A+Write+with+Specified+Indentation]
+- {Querying}[#label-Querying]
+  - {Task: Get the Document}[#label-Task-3A+Get+the+Document]
+  - {Task: Get the Encoding}[#label-Task-3A+Get+the+Encoding]
+  - {Task: Get the Node Type}[#label-Task-3A+Get+the+Node+Type]
+  - {Task: Get the Root Element}[#label-Task-3A+Get+the+Root+Element]
+  - {Task: Determine Whether Stand-Alone}[#label-Task-3A+Determine+Whether+Stand-Alone]
+  - {Task: Get the Version}[#label-Task-3A+Get+the+Version]
+

data/doc/rexml/tasks/tocs/element_toc.rdoc

@@ -0,0 +1,55 @@
+Tasks on this page:
+
+- {New Element}[#label-New+Element]
+  - {Task: Create a Default Element}[#label-Task-3A+Create+a+Default+Element]
+  - {Task: Create a Named Element}[#label-Task-3A+Create+a+Named+Element]
+  - {Task: Create an Element with Name and Parent}[#label-Task-3A+Create+an+Element+with+Name+and+Parent]
+  - {Task: Create an Element with Name, Parent, and Context}[#label-Task-3A+Create+an+Element+with+Name-2C+Parent-2C+and+Context]
+  - {Task: Create a Shallow Clone}[#label-Task-3A+Create+a+Shallow+Clone]
+- {Attributes}[#label-Attributes]
+  - {Task: Create and Add an Attribute}[#label-Task-3A+Create+and+Add+an+Attribute]
+  - {Task: Add an Existing Attribute}[#label-Task-3A+Add+an+Existing+Attribute]
+  - {Task: Add Multiple Attributes from a Hash}[#label-Task-3A+Add+Multiple+Attributes+from+a+Hash]
+  - {Task: Add Multiple Attributes from an Array}[#label-Task-3A+Add+Multiple+Attributes+from+an+Array]
+  - {Task: Retrieve the Value for an Attribute Name}[#label-Task-3A+Retrieve+the+Value+for+an+Attribute+Name]
+  - {Task: Retrieve the Attribute Value for a Name and Namespace}[#label-Task-3A+Retrieve+the+Attribute+Value+for+a+Name+and+Namespace]
+  - {Task: Delete an Attribute}[#label-Task-3A+Delete+an+Attribute]
+  - {Task: Determine Whether the Element Has Attributes}[#label-Task-3A+Determine+Whether+the+Element+Has+Attributes]
+- {Children}[#label-Children]
+  - {Task: Create and Add an Element}[#label-Task-3A+Create+and+Add+an+Element]
+  - {Task: Add an Existing Element}[#label-Task-3A+Add+an+Existing+Element]
+  - {Task: Create and Add an Element with Attributes}[#label-Task-3A+Create+and+Add+an+Element+with+Attributes]
+  - {Task: Add an Existing Element with Added Attributes}[#label-Task-3A+Add+an+Existing+Element+with+Added+Attributes]
+  - {Task: Delete a Specified Element}[#label-Task-3A+Delete+a+Specified+Element]
+  - {Task: Delete an Element by Index}[#label-Task-3A+Delete+an+Element+by+Index]
+  - {Task: Delete an Element by XPath}[#label-Task-3A+Delete+an+Element+by+XPath]
+  - {Task: Determine Whether Element Children}[#label-Task-3A+Determine+Whether+Element+Children]
+  - {Task: Get Element Descendants by XPath}[#label-Task-3A+Get+Element+Descendants+by+XPath]
+  - {Task: Get Next Element Sibling}[#label-Task-3A+Get+Next+Element+Sibling]
+  - {Task: Get Previous Element Sibling}[#label-Task-3A+Get+Previous+Element+Sibling]
+  - {Task: Add a Text Node}[#label-Task-3A+Add+a+Text+Node]
+  - {Task: Replace the First Text Node}[#label-Task-3A+Replace+the+First+Text+Node]
+  - {Task: Remove the First Text Node}[#label-Task-3A+Remove+the+First+Text+Node]
+  - {Task: Retrieve the First Text Node}[#label-Task-3A+Retrieve+the+First+Text+Node]
+  - {Task: Retrieve a Specific Text Node}[#label-Task-3A+Retrieve+a+Specific+Text+Node]
+  - {Task: Determine Whether the Element has Text Nodes}[#label-Task-3A+Determine+Whether+the+Element+has+Text+Nodes]
+  - {Task: Get the Child at a Given Index}[#label-Task-3A+Get+the+Child+at+a+Given+Index]
+  - {Task: Get All CDATA Children}[#label-Task-3A+Get+All+CDATA+Children]
+  - {Task: Get All Comment Children}[#label-Task-3A+Get+All+Comment+Children]
+  - {Task: Get All Processing Instruction Children}[#label-Task-3A+Get+All+Processing+Instruction+Children]
+  - {Task: Get All Text Children}[#label-Task-3A+Get+All+Text+Children]
+- {Namespaces}[#label-Namespaces]
+  - {Task: Add a Namespace}[#label-Task-3A+Add+a+Namespace]
+  - {Task: Delete the Default Namespace}[#label-Task-3A+Delete+the+Default+Namespace]
+  - {Task: Delete a Specific Namespace}[#label-Task-3A+Delete+a+Specific+Namespace]
+  - {Task: Get a Namespace URI}[#label-Task-3A+Get+a+Namespace+URI]
+  - {Task: Retrieve Namespaces}[#label-Task-3A+Retrieve+Namespaces]
+  - {Task: Retrieve Namespace Prefixes}[#label-Task-3A+Retrieve+Namespace+Prefixes]
+- {Iteration}[#label-Iteration]
+  - {Task: Iterate Over Elements}[#label-Task-3A+Iterate+Over+Elements]
+  - {Task: Iterate Over Elements Having a Specified Attribute}[#label-Task-3A+Iterate+Over+Elements+Having+a+Specified+Attribute]
+  - {Task: Iterate Over Elements Having a Specified Attribute and Value}[#label-Task-3A+Iterate+Over+Elements+Having+a+Specified+Attribute+and+Value]
+  - {Task: Iterate Over Elements Having Specified Text}[#label-Task-3A+Iterate+Over+Elements+Having+Specified+Text]
+- {Context}[#label-Context]
+- {Other Getters}[#label-Other+Getters]
+