diff options
Diffstat (limited to 'vendor/bundle/ruby/3.4.0/gems/rexml-3.4.1/doc/rexml/context.rdoc')
| -rw-r--r-- | vendor/bundle/ruby/3.4.0/gems/rexml-3.4.1/doc/rexml/context.rdoc | 143 |
1 files changed, 143 insertions, 0 deletions
diff --git a/vendor/bundle/ruby/3.4.0/gems/rexml-3.4.1/doc/rexml/context.rdoc b/vendor/bundle/ruby/3.4.0/gems/rexml-3.4.1/doc/rexml/context.rdoc new file mode 100644 index 0000000..7ef01f7 --- /dev/null +++ b/vendor/bundle/ruby/3.4.0/gems/rexml-3.4.1/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 < 1</a><b>1 > 0</b></root>' + d = REXML::Document.new(xml_string, {:raw => ['a']}) + d.root.to_s # => "<root><a>0 < 1</a><b>1 > 0</b></root>" + a, b = *d.root.elements + a.to_s # => "<a>0 < 1</a>" + b.to_s # => "<b>1 > 0</b>" + +But Element#text= is affected: + + a.text = '0 < 1' + b.text = '1 > 0' + a.to_s # => "<a>0 < 1</a>" + b.to_s # => "<b>1 &gt; 0</b>" + +As is Element.add_text: + + a.add_text(' so 1 > 0') + b.add_text(' so 0 < 1') + a.to_s # => "<a>0 < 1 so 1 > 0</a>" + b.to_s # => "<b>1 &gt; 0 so 0 &lt; 1</b>" |