rexml 3.2.4 → 3.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e09eaebc2e8b94e90c9529f88060a7aa21cbaed09fe2f424d1293cf5a9e19785
-  data.tar.gz: 3c9d5d8a428c10037df1b93de84f9420b31caccd435d903361f7d9d3b5b49da5
+  metadata.gz: fc3edd128c37b7817a6db92dfa9d45add8328d9c5f6983652d24562cd6968672
+  data.tar.gz: 1c604fe6aa4908d8c13134c8f0966bd1483a01ad2ccca0ad1a85057e39f36e54
 SHA512:
-  metadata.gz: 17f5224c52c6ec2f5388545f34167f486a826eeba5d9bd83f69e7bf59e194e2ee8d738a6625749dd282961b1c4ec2f3d028cd7935eff58dc3882a5272b440c5c
-  data.tar.gz: 04e0b736f5d40c3585582ffa3db301a94c116ff3d2152f911414b04917979e3c9defca5c5f98088962cde6491adec37bc6d774b5e8693cd954148d7d6fc22268
+  metadata.gz: 4b3f5f714c38e22ed05b53389e7d3950896f1da2675527c28ed6c7f91ef18bb49fec90e0120c2f2c911da85db34a3a99e9b6209ba4d5dc4876379c6302a01ace
+  data.tar.gz: 9b11b1cfcdb9404574f35ad237b141c6d6fd97b34ead68401064228eb7562c2d13576e1b66a75fa1e3ddc70d937ff638c31de03eb9bc47274c01711eb8abcf3f

data/NEWS.md

@@ -1,5 +1,42 @@
 # News
 
+## 3.2.5 - 2021-04-05 {#version-3-2-5}
+
+### Improvements
+
+  * Add more validations to XPath parser.
+
+  * `require "rexml/docuemnt"` by default.
+    [GitHub#36][Patch by Koichi ITO]
+
+  * Don't add `#dcloe` method to core classes globally.
+    [GitHub#37][Patch by Akira Matsuda]
+
+  * Add more documentations.
+    [Patch by Burdette Lamar]
+
+  * Added `REXML::Elements#parent`.
+    [GitHub#52][Patch by Burdette Lamar]
+
+### Fixes
+
+  * Fixed a bug that `REXML::DocType#clone` doesn't copy external ID
+    information.
+
+  * Fixed round-trip vulnerability bugs.
+    See also: https://www.ruby-lang.org/en/news/2021/04/05/xml-round-trip-vulnerability-in-rexml-cve-2021-28965/
+    [HackerOne#1104077][CVE-2021-28965][Reported by Juho Nurminen]
+
+### Thanks
+
+  * Koichi ITO
+
+  * Akira Matsuda
+
+  * Burdette Lamar
+
+  * Juho Nurminen
+
 ## 3.2.4 - 2020-01-31 {#version-3-2-4}
 
 ### Improvements

data/README.md

@@ -4,21 +4,9 @@ REXML was inspired by the Electric XML library for Java, which features an easy-
 
 REXML supports both tree and stream document parsing. Stream parsing is faster (about 1.5 times as fast). However, with stream parsing, you don't get access to features such as XPath.
 
-## Installation
+## API
 
-Add this line to your application's Gemfile:
-
-```ruby
-gem 'rexml'
-```
-
-And then execute:
-
-    $ bundle
-
-Or install it yourself as:
-
-    $ gem install rexml
+See the {API documentation}[https://ruby.github.io/rexml/]
 
 ## Usage
 

data/doc/rexml/context.rdoc

@@ -0,0 +1,143 @@
+== Element Context
+
+Notes:
+- All code on this page presupposes that the following has been executed:
+
+    require 'rexml/document'
+
+- For convenience, examples on this page use +REXML::Document.new+, not +REXML::Element.new+.
+  This is completely valid, because REXML::Document is a subclass of REXML::Element.
+
+The context for an element is a hash of processing directives
+that influence the way \XML is read, stored, and written.
+The context entries are:
+
+- +:respect_whitespace+: controls treatment of whitespace.
+- +:compress_whitespace+: determines whether whitespace is compressed.
+- +:ignore_whitespace_nodes+: determines whether whitespace-only nodes are to be ignored.
+- +:raw+: controls treatment of special characters and entities.
+
+The default context for a new element is <tt>{}</tt>.
+You can set the context at element-creation time:
+
+  d = REXML::Document.new('', {compress_whitespace: :all, raw: :all})
+  d.context # => {:compress_whitespace=>:all, :raw=>:all}
+
+You can reset the entire context by assigning a new hash:
+
+  d.context = {ignore_whitespace_nodes: :all}
+  d.context # => {:ignore_whitespace_nodes=>:all}
+
+Or you can create or modify an individual entry:
+
+  d.context[:raw] = :all
+  d.context # => {:ignore_whitespace_nodes=>:all, :raw=>:all}
+
+=== +:respect_whitespace+
+
+Affects: +REXML::Element.new+, +REXML::Element.text=+.
+
+By default, all parsed whitespace is respected (that is, stored whitespace not compressed):
+
+  xml_string = '<root><foo>a   b</foo>    <bar>c   d</bar>   <baz>e   f</baz></root>'
+  d = REXML::Document.new(xml_string)
+  d.to_s # => "<root><foo>a   b</foo>    <bar>c   d</bar>   <baz>e   f</baz></root>"
+
+Use +:respect_whitespace+ with an array of element names
+to specify the elements that _are_ to have their whitespace respected;
+other elements' whitespace, and whitespace between elements, will be compressed.
+
+In this example: +foo+ and +baz+ will have their whitespace respected;
++bar+ and the space between elements will have their whitespace compressed:
+
+  d = REXML::Document.new(xml_string, {respect_whitespace: ['foo', 'baz']})
+  d.to_s # => "<root><foo>a   b</foo> <bar>c d</bar> <baz>e   f</baz></root>"
+  bar = d.root[2] # => <bar> ... </>
+  bar.text = 'X   Y'
+  d.to_s # => "<root><foo>a   b</foo> <bar>X Y</bar> <baz>e   f</baz></root>"
+
+=== +:compress_whitespace+
+
+Affects: +REXML::Element.new+, +REXML::Element.text=+.
+
+Use <tt>compress_whitespace: :all</tt>
+to compress whitespace both within and between elements:
+
+  xml_string = '<root><foo>a   b</foo>    <bar>c   d</bar>   <baz>e   f</baz></root>'
+  d = REXML::Document.new(xml_string, {compress_whitespace: :all})
+  d.to_s # => "<root><foo>a b</foo> <bar>c d</bar> <baz>e f</baz></root>"
+
+Use +:compress_whitespace+ with an array of element names
+to compress whitespace in those elements,
+but not in other elements nor between elements.
+
+In this example, +foo+ and +baz+ will have their whitespace compressed;
++bar+ and the space between elements will not:
+
+  d = REXML::Document.new(xml_string, {compress_whitespace: ['foo', 'baz']})
+  d.to_s # => "<root><foo>a b</foo>    <bar>c   d</bar>   <baz>e f</baz></root>"
+  foo = d.root[0] # => <foo> ... </>
+  foo.text= 'X   Y'
+  d.to_s # => "<root><foo>X Y</foo>    <bar>c   d</bar>   <baz>e f</baz></root>"
+
+=== +:ignore_whitespace_nodes+
+
+Affects: +REXML::Element.new+.
+
+Use <tt>ignore_whitespace_nodes: :all</tt> to omit all whitespace-only elements.
+
+In this example, +bar+ has a text node, while nodes +foo+ and +baz+ do not:
+
+  xml_string = '<root><foo>   </foo><bar> BAR </bar><baz>   </baz></root>'
+  d = REXML::Document.new(xml_string, {ignore_whitespace_nodes: :all})
+  d.to_s # => "<root><foo> FOO </foo><bar/><baz> BAZ </baz></root>"
+  root = d.root   # => <root> ... </>
+  foo = root[0]   # => <foo/>
+  bar = root[1]   # => <bar> ... </>
+  baz = root[2]   # => <baz/>
+  foo.first.class # => NilClass
+  bar.first.class # => REXML::Text
+  baz.first.class # => NilClass
+
+Use +:ignore_whitespace_nodes+ with an array of element names
+to specify the elements that are to have whitespace nodes ignored.
+
+In this example, +bar+ and +baz+ have text nodes, while node +foo+ does not.
+
+  xml_string = '<root><foo>   </foo><bar> BAR </bar><baz>   </baz></root>'
+  d = REXML::Document.new(xml_string, {ignore_whitespace_nodes: ['foo']})
+  d.to_s # => "<root><foo/><bar> BAR </bar><baz>   </baz></root>"
+  root = d.root   # => <root> ... </>
+  foo = root[0]   # => <foo/>
+  bar = root[1]   # => <bar> ... </>
+  baz = root[2]   # => <baz> ... </>
+  foo.first.class # => NilClass
+  bar.first.class # => REXML::Text
+  baz.first.class # => REXML::Text
+
+=== +:raw+
+
+Affects:  +Element.text=+, +Element.add_text+, +Text.to_s+.
+
+Parsing of +a+ elements is not affected by +raw+:
+
+  xml_string = '<root><a>0 &lt; 1</a><b>1 &gt; 0</b></root>'
+  d = REXML::Document.new(xml_string, {:raw => ['a']})
+  d.root.to_s # => "<root><a>0 &lt; 1</a><b>1 &gt; 0</b></root>"
+  a, b = *d.root.elements
+  a.to_s # => "<a>0 &lt; 1</a>"
+  b.to_s # => "<b>1 &gt; 0</b>"
+
+But Element#text= is affected:
+
+  a.text = '0 &lt; 1'
+  b.text = '1 &gt; 0'
+  a.to_s # => "<a>0 &lt; 1</a>"
+  b.to_s # => "<b>1 &amp;gt; 0</b>"
+
+As is Element.add_text:
+
+  a.add_text(' so 1 &gt; 0')
+  b.add_text(' so 0 &lt; 1')
+  a.to_s # => "<a>0 &lt; 1 so 1 &gt; 0</a>"
+  b.to_s # => "<b>1 &amp;gt; 0 so 0 &amp;lt; 1</b>"

data/doc/rexml/tasks/rdoc/child.rdoc

@@ -0,0 +1,87 @@
+== Class Child
+
+Class Child includes module Node;
+see {Tasks for Node}[node_rdoc.html].
+
+:include: ../tocs/child_toc.rdoc
+
+=== Relationships
+
+==== Task: Set the Parent
+
+Use method {Child#parent=}[../../../../REXML/Parent.html#method-i-parent-3D]
+to set the parent:
+
+  e0 = REXML::Element.new('foo')
+  e1 = REXML::Element.new('bar')
+  e1.parent # => nil
+  e1.parent = e0
+  e1.parent # => <foo/>
+
+==== Task: Insert Previous Sibling
+
+Use method {Child#previous_sibling=}[../../../../REXML/Parent.html#method-i-previous_sibling-3D]
+to insert a previous sibling:
+
+  xml_string = '<root><a/><c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.to_a   # => [<a/>, <c/>]
+  c = d.root[1] # => <c/>
+  b = REXML::Element.new('b')
+  c.previous_sibling = b
+  d.root.to_a   # => [<a/>, <b/>, <c/>]
+
+==== Task: Insert Next Sibling
+
+Use method {Child#next_sibling=}[../../../../REXML/Parent.html#method-i-next-sibling-3D]
+to insert a previous sibling:
+
+  xml_string = '<root><a/><c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.to_a   # => [<a/>, <c/>]
+  a = d.root[0] # => <a/>
+  b = REXML::Element.new('b')
+  a.next_sibling = b
+  d.root.to_a   # => [<a/>, <b/>, <c/>]
+
+=== Removal or Replacement
+
+==== Task: Remove Child from Parent
+
+Use method {Child#remove}[../../../../REXML/Parent.html#method-i-remove]
+to remove a child from its parent; returns the removed child:
+
+  xml_string = '<root><a/><b/><c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.to_a   # => [<a/>, <b/>, <c/>]
+  b = d.root[1] # => <b/>
+  b.remove      # => <b/>
+  d.root.to_a   # => [<a/>, <c/>]
+
+==== Task: Replace Child
+
+Use method {Child#replace_with}[../../../../REXML/Parent.html#method-i-replace]
+to replace a child;
+returns the replaced child:
+
+  xml_string = '<root><a/><b/><c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.to_a       # => [<a/>, <b/>, <c/>]
+  b = d.root[1]     # => <b/>
+  d = REXML::Element.new('d')
+  b.replace_with(d) # => <b/>
+  d.root.to_a       # => [<a/>, <d/>, <c/>]
+
+=== Document
+
+==== Task: Get the Document
+
+Use method {Child#document}[../../../../REXML/Parent.html#method-i-document]
+to get the document for the child:
+
+  xml_string = '<root><a/><b/><c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root.to_a     # => [<a/>, <b/>, <c/>]
+  b = d.root[1]   # => <b/>
+  b.document == d # => true
+  REXML::Child.new.document # => nil

data/doc/rexml/tasks/rdoc/document.rdoc

@@ -0,0 +1,276 @@
+== Class Document
+
+Class Document has methods from its superclasses and included modules;
+see:
+
+- {Tasks for Element}[element_rdoc.html].
+- {Tasks for Parent}[parent_rdoc.html].
+- {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/document_toc.rdoc
+
+=== New Document
+
+==== Task: Create an Empty Document
+
+Use method {Document::new}[../../../../REXML/Document.html#method-c-new]
+to create an empty document.
+
+  d = REXML::Document.new
+
+==== Task: Parse a \String into a New Document
+
+Use method {Document::new}[../../../../REXML/Document.html#method-c-new]
+to parse an XML string into a new document:
+
+  xml_string = '<root><a/>text<b/>more<c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.root # => <root> ... </>
+
+==== Task: Parse an \IO Stream into a New Document
+
+Use method {Document::new}[../../../../REXML/Document.html#method-c-new]
+to parse an XML \IO stream into a new document:
+
+  xml_string = '<root><a/>text<b/>more<c/></root>'
+  File.write('t.xml', xml_string)
+  d = File.open('t.xml', 'r') do |file|
+    REXML::Document.new(file)
+  end
+  d.root # => <root> ... </>
+
+==== Task: Create a Document from an Existing Document
+
+Use method {Document::new}[../../../../REXML/Document.html#method-c-new]
+to create a document from an existing document.
+The context and attributes are copied to the new document,
+but not the children:
+
+  xml_string = '<root><a/>text<b/>more<c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.children    # => [<root> ... </>]
+  d.context = {raw: :all, compress_whitespace: :all}
+  d.add_attributes({'bar' => 0, 'baz' => 1})
+  d1 = REXML::Document.new(d)
+  d1.context    # => {:raw=>:all, :compress_whitespace=>:all}
+  d1.attributes # => {"bar"=>bar='0', "baz"=>baz='1'}
+  d1.children   # => []
+
+==== Task: Clone a Document
+
+Use method {Document#clone}[../../../../REXML/Document.html#method-i-clone]
+to clone a document.
+The context and attributes are copied to the new document,
+but not the children:
+
+  xml_string = '<root><a/>text<b/>more<c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.children    # => [<root> ... </>]
+  d.context = {raw: :all, compress_whitespace: :all}
+  d.add_attributes({'bar' => 0, 'baz' => 1})
+  d1 = d.clone  # => < bar='0' baz='1'/>
+  d1.context    # => {:raw=>:all, :compress_whitespace=>:all}
+  d1.attributes # => {"bar"=>bar='0', "baz"=>baz='1'}
+  d1.children   # => []
+
+=== Document Type
+
+==== Task: Get the Document Type
+
+Use method {Document#doctype}[../../../../REXML/Document.html#method-i-doctype]
+to get the document type:
+
+  d = REXML::Document.new('<!DOCTYPE document SYSTEM "subjects.dtd">')
+  d.doctype.class # => REXML::DocType
+  d = REXML::Document.new('')
+  d.doctype.class # => nil
+
+==== Task: Set the Document Type
+
+Use method {document#add}[../../../../REXML/Document.html#method-i-add]
+to add or replace the document type:
+
+  d = REXML::Document.new('')
+  d.doctype.class # => nil
+  d.add(REXML::DocType.new('foo'))
+  d.doctype.class # => REXML::DocType
+
+=== XML Declaration
+
+==== Task: Get the XML Declaration
+
+Use method {document#xml_decl}[../../../../REXML/Document.html#method-i-xml_decl]
+to get the XML declaration:
+
+  d = REXML::Document.new('<!DOCTYPE document SYSTEM "subjects.dtd">')
+  d.xml_decl.class # => REXML::XMLDecl
+  d.xml_decl       # => <?xml ... ?>
+  d = REXML::Document.new('')
+  d.xml_decl.class # => REXML::XMLDecl
+  d.xml_decl       # => <?xml ... ?>
+
+==== Task: Set the XML Declaration
+
+Use method {document#add}[../../../../REXML/Document.html#method-i-add]
+to replace the XML declaration:
+
+  d = REXML::Document.new('<!DOCTYPE document SYSTEM "subjects.dtd">')
+  d.add(REXML::XMLDecl.new)
+
+=== Children
+
+==== Task: Add an Element Child
+
+Use method
+{document#add_element}[../../../../REXML/Document.html#method-i-add_element]
+to add an element to the document:
+
+  d = REXML::Document.new('')
+  d.add_element(REXML::Element.new('root'))
+  d.children # => [<root/>]
+
+==== Task: Add a Non-Element Child
+
+Use method
+{document#add}[../../../../REXML/Document.html#method-i-add]
+to add a non-element to the document:
+
+  xml_string = '<root><a/>text<b/>more<c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.add(REXML::Text.new('foo'))
+  d.children # => [<root> ... </>, "foo"]
+
+=== Writing
+
+==== Task: Write to $stdout
+
+Use method
+{document#write}[../../../../REXML/Document.html#method-i-write]
+to write the document to <tt>$stdout</tt>:
+
+  xml_string = '<root><a/>text<b/>more<c/></root>'
+  d = REXML::Document.new(xml_string)
+  d.write
+
+Output:
+
+  <root><a/>text<b/>more<c/></root>
+
+==== Task: Write to IO Stream
+
+Use method
+{document#write}[../../../../REXML/Document.html#method-i-write]
+to write the document to <tt>$stdout</tt>:
+
+  xml_string = '<root><a/>text<b/>more<c/></root>'
+  d = REXML::Document.new(xml_string)
+  File.open('t.xml', 'w') do |file|
+    d.write(file)
+  end
+  p File.read('t.xml')
+
+Output:
+
+  "<root><a/>text<b/>more<c/></root>"
+
+==== Task: Write with No Indentation
+
+Use method
+{document#write}[../../../../REXML/Document.html#method-i-write]
+to write the document with no indentation:
+
+  xml_string = '<root><a><b><c></c></b></a></root>'
+  d = REXML::Document.new(xml_string)
+  d.write({indent: 0})
+
+Output:
+
+  <root>
+  <a>
+  <b>
+  <c/>
+  </b>
+  </a>
+  </root>
+
+==== Task: Write with Specified Indentation
+
+Use method
+{document#write}[../../../../REXML/Document.html#method-i-write]
+to write the document with a specified indentation:
+
+  xml_string = '<root><a><b><c></c></b></a></root>'
+  d = REXML::Document.new(xml_string)
+  d.write({indent: 2})
+
+Output:
+
+  <root>
+    <a>
+      <b>
+        <c/>
+      </b>
+    </a>
+  </root>
+
+=== Querying
+
+==== Task: Get the Document
+
+Use method
+{document#document}[../../../../REXML/Document.html#method-i-document]
+to get the document (+self+); overrides <tt>Element#document</tt>:
+
+  xml_string = '<root><a><b><c></c></b></a></root>'
+  d = REXML::Document.new(xml_string)
+  d.document == d # => true
+
+==== Task: Get the Encoding
+
+Use method
+{document#document}[../../../../REXML/Document.html#method-i-document]
+to get the document (+self+); overrides <tt>Element#document</tt>:
+
+  xml_string = '<root><a><b><c></c></b></a></root>'
+  d = REXML::Document.new(xml_string)
+  d.encoding # => "UTF-8"
+
+==== Task: Get the Node Type
+
+Use method
+{document#node_type}[../../../../REXML/Document.html#method-i-node_type]
+to get the node type (+:document+); overrides <tt>Element#node_type</tt>:
+
+  xml_string = '<root><a><b><c></c></b></a></root>'
+  d = REXML::Document.new(xml_string)
+  d.node_type # => :document
+
+==== Task: Get the Root Element
+
+Use method
+{document#root}[../../../../REXML/Document.html#method-i-root]
+to get the root element:
+
+  xml_string = '<root><a><b><c></c></b></a></root>'
+  d = REXML::Document.new(xml_string)
+  d.root # => <root> ... </>
+
+==== Task: Determine Whether Stand-Alone
+
+Use method
+{document#stand_alone?}[../../../../REXML/Document.html#method-i-stand_alone-3F]
+to get the stand-alone value:
+
+  d = REXML::Document.new('<?xml standalone="yes"?>')
+  d.stand_alone? # => "yes"
+
+==== Task: Get the Version
+
+Use method
+{document#version}[../../../../REXML/Document.html#method-i-version]
+to get the version:
+
+  d = REXML::Document.new('<?xml version="2.0" encoding="UTF-8"?>')
+  d.version # => "2.0"