144 lines
5.2 KiB
Plaintext
144 lines
5.2 KiB
Plaintext
== 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>"
|