rexml 3.2.3 → 3.2.8

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 50a1edf481c0166f41419e4ec6a7281db35e46a480c321f5f536afedc243c582
-  data.tar.gz: 2fe98cd4b1f91b895362f49d1026f6e712ce218edfda7e51e108477fc274a65a
+  metadata.gz: cef1cb55ed6a23bce0af7d46fce791961558ee885c57f1089207deb53e18ff95
+  data.tar.gz: 4fbe36d9e4422d266c2ffee71fab703e6408e9a2b5533ca0ae49411483f98368
 SHA512:
-  metadata.gz: f0babb3c1a90a87879c923edec9dc99704fe2d27a7b1c36aeefd0dc5dccc7f5aefa4f7223149ca9bc079cd4fa30128ee289d16f398cdcc4e75378212439b73d4
-  data.tar.gz: 920401977f208f24670de80b771a50915347471bba9c6a20a5672318d177c2f830c57aac1257dac5c7d93c3c4b505d307bae9955824e5867af42f94287c7dc4e
+  metadata.gz: 60da703f26ff7eaa6cf537634ad68e4c3246605c26c54ea96147fae59bb6c17eeab5c234e5e67301e342472ce8dd3cb671321168cddc212839b9347c8de62f91
+  data.tar.gz: 4d6eeaba460a22bcdc3512ac53504fe87f829cb783069fbebb989fb8f1585fbdfe9ed357c8fbda894fb68777d04f871b9073aa6d13c31eccc6b3b22db10c2ce1

data/NEWS.md

@@ -1,5 +1,224 @@
 # News
 
+## 3.2.8 - 2024-05-16 {#version-3-2-8}
+
+### Fixes
+
+  * Suppressed a warning
+
+## 3.2.7 - 2024-05-16 {#version-3-2-7}
+
+### Improvements
+
+  * Improve parse performance by using `StringScanner`.
+
+    * GH-106
+    * GH-107
+    * GH-108
+    * GH-109
+    * GH-112
+    * GH-113
+    * GH-114
+    * GH-115
+    * GH-116
+    * GH-117
+    * GH-118
+    * GH-119
+    * GH-121
+
+    * Patch by NAITOH Jun.
+
+  * Improved parse performance when an attribute has many `<`s.
+
+    * GH-124
+
+### Fixes
+
+  * XPath: Fixed a bug of `normalize_space(array)`.
+
+    * GH-110
+    * GH-111
+
+    * Patch by flatisland.
+
+  * XPath: Fixed a bug that wrong position is used with nested path.
+
+    * GH-110
+    * GH-122
+
+    * Reported by jcavalieri.
+    * Patch by NAITOH Jun.
+
+  * Fixed a bug that an exception message can't be generated for
+    invalid encoding XML.
+
+    * GH-29
+    * GH-123
+
+    * Reported by DuKewu.
+    * Patch by NAITOH Jun.
+
+### Thanks
+
+  * NAITOH Jun
+  * flatisland
+  * jcavalieri
+  * DuKewu
+
+
+## 3.2.6 - 2023-07-27 {#version-3-2-6}
+
+### Improvements
+
+  * Required Ruby 2.5 or later explicitly.
+    [GH-69][gh-69]
+    [Patch by Ivo Anjo]
+
+  * Added documentation for maintenance cycle.
+    [GH-71][gh-71]
+    [Patch by Ivo Anjo]
+
+  * Added tutorial.
+    [GH-77][gh-77]
+    [GH-78][gh-78]
+    [Patch by Burdette Lamar]
+
+  * Improved performance and memory usage.
+    [GH-94][gh-94]
+    [Patch by fatkodima]
+
+  * `REXML::Parsers::XPathParser#abbreviate`: Added support for
+    function arguments.
+    [GH-95][gh-95]
+    [Reported by pulver]
+
+  * `REXML::Parsers::XPathParser#abbreviate`: Added support for string
+    literal that contains double-quote.
+    [GH-96][gh-96]
+    [Patch by pulver]
+
+  * `REXML::Parsers::XPathParser#abbreviate`: Added missing `/` to
+    `:descendant_or_self/:self/:parent`.
+    [GH-97][gh-97]
+    [Reported by pulver]
+
+  * `REXML::Parsers::XPathParser#abbreviate`: Added support for more patterns.
+    [GH-97][gh-97]
+    [Reported by pulver]
+
+### Fixes
+
+  * Fixed a typo in NEWS.
+    [GH-72][gh-72]
+    [Patch by Spencer Goodman]
+
+  * Fixed a typo in NEWS.
+    [GH-75][gh-75]
+    [Patch by Andrew Bromwich]
+
+  * Fixed documents.
+    [GH-87][gh-87]
+    [Patch by Alexander Ilyin]
+
+  * Fixed a bug that `Attriute` convert `'` and `&apos;` even when
+    `attribute_quote: :quote` is used.
+    [GH-92][gh-92]
+    [Reported by Edouard Brière]
+
+  * Fixed links in tutorial.
+    [GH-99][gh-99]
+    [Patch by gemmaro]
+
+
+### Thanks
+
+  * Ivo Anjo
+
+  * Spencer Goodman
+
+  * Andrew Bromwich
+
+  * Burdette Lamar
+
+  * Alexander Ilyin
+
+  * Edouard Brière
+
+  * fatkodima
+
+  * pulver
+
+  * gemmaro
+
+[gh-69]:https://github.com/ruby/rexml/issues/69
+[gh-71]:https://github.com/ruby/rexml/issues/71
+[gh-72]:https://github.com/ruby/rexml/issues/72
+[gh-75]:https://github.com/ruby/rexml/issues/75
+[gh-77]:https://github.com/ruby/rexml/issues/77
+[gh-87]:https://github.com/ruby/rexml/issues/87
+[gh-92]:https://github.com/ruby/rexml/issues/92
+[gh-94]:https://github.com/ruby/rexml/issues/94
+[gh-95]:https://github.com/ruby/rexml/issues/95
+[gh-96]:https://github.com/ruby/rexml/issues/96
+[gh-97]:https://github.com/ruby/rexml/issues/97
+[gh-98]:https://github.com/ruby/rexml/issues/98
+[gh-99]:https://github.com/ruby/rexml/issues/99
+
+## 3.2.5 - 2021-04-05 {#version-3-2-5}
+
+### Improvements
+
+  * Add more validations to XPath parser.
+
+  * `require "rexml/document"` by default.
+    [GitHub#36][Patch by Koichi ITO]
+
+  * Don't add `#dclone` 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
+
+  * Don't use `taint` with Ruby 2.7 or later.
+    [GitHub#21][Patch by Jeremy Evans]
+
+### Fixes
+
+  * Fixed a `elsif` typo.
+    [GitHub#22][Patch by Nobuyoshi Nakada]
+
+### Thanks
+
+  * Jeremy Evans
+
+  * Nobuyoshi Nakada
+
 ## 3.2.3 - 2019-10-12 {#version-3-2-3}
 
 ### Fixes

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
 
@@ -45,6 +33,15 @@ doc = Document.new string
 
 So parsing a string is just as easy as parsing a file.
 
+## Support
+
+REXML support follows the same maintenance cycle as Ruby releases, as shown on <https://www.ruby-lang.org/en/downloads/branches/>.
+
+If you are running on an end-of-life Ruby, do not expect modern REXML releases to be compatible with it; in fact, it's recommended that you DO NOT use this gem, and instead use the REXML version that came bundled with your end-of-life Ruby version.
+
+The `required_ruby_version` on the gemspec is kept updated on a [best-effort basis](https://github.com/ruby/rexml/pull/70) by the community.
+Up to version 3.2.5, this information was not set. That version [is known broken with at least Ruby < 2.3](https://github.com/ruby/rexml/issues/69).
+
 ## Development
 
 After checking out the repo, run `rake test` to run the tests.

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