class Nokogiri::XML::Node
Nokogiri::XML::Node
is your window to the fun filled world of dealing with XML
and HTML
tags. A Nokogiri::XML::Node
may be treated similarly to a hash with regard to attributes. For example (from irb):
irb(main):004:0> node => <a href="#foo" id="link">link</a> irb(main):005:0> node['href'] => "#foo" irb(main):006:0> node.keys => ["href", "id"] irb(main):007:0> node.values => ["#foo", "link"] irb(main):008:0> node['class'] = 'green' => "green" irb(main):009:0> node => <a href="#foo" id="link" class="green">link</a> irb(main):010:0>
See Nokogiri::XML::Node#[]
and Nokogiri::XML#[]= for more information.
Nokogiri::XML::Node
also has methods that let you move around your tree. For navigating your tree, see:
-
Nokogiri::XML::Node#parent
-
Nokogiri::XML::Node#children
-
Nokogiri::XML::Node#next
-
Nokogiri::XML::Node#previous
You may search this node's subtree using Node#xpath
and Node#css
Constants
- ATTRIBUTE_DECL
Attribute declaration type
- ATTRIBUTE_NODE
Attribute node type
- CDATA_SECTION_NODE
CDATA
node type, seeNokogiri::XML::Node#cdata?
- COMMENT_NODE
Comment node type, see
Nokogiri::XML::Node#comment?
- DOCB_DOCUMENT_NODE
DOCB document node type
- DOCUMENT_FRAG_NODE
Document
fragment node type- DOCUMENT_NODE
Document
node type, seeNokogiri::XML::Node#xml?
- DOCUMENT_TYPE_NODE
Document
type node type- DTD_NODE
DTD
node type- ELEMENT_DECL
Element declaration type
- ELEMENT_NODE
Element node type, see
Nokogiri::XML::Node#element?
- ENTITY_DECL
Entity declaration type
- ENTITY_NODE
Entity node type
- ENTITY_REF_NODE
Entity reference node type
- HTML_DOCUMENT_NODE
HTML
document node type, seeNokogiri::XML::Node#html?
- NAMESPACE_DECL
Namespace
declaration type- NOTATION_NODE
Notation
node type- PI_NODE
PI node type
- TEXT_NODE
Text
node type, seeNokogiri::XML::Node#text?
- XINCLUDE_END
XInclude end type
- XINCLUDE_START
XInclude start type
Public Instance Methods
Add node_or_tags
as a child of this Node
. node_or_tags
can be a Nokogiri::XML::Node
, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
Returns self, to support chaining of calls (e.g., root << child1 << child2)
Also see related method add_child
.
# File lib/nokogiri/xml/node.rb, line 304 def << node_or_tags add_child node_or_tags self end
Test to see if this Node
is equal to other
# File lib/nokogiri/xml/node.rb, line 732 def == other return false unless other return false unless other.respond_to?(:pointer_id) pointer_id == other.pointer_id end
Search this node's immediate children using CSS
selector selector
# File lib/nokogiri/xml/node.rb, line 219 def > selector ns = document.root.namespaces xpath CSS.xpath_for(selector, :prefix => "./", :ns => ns).first end
Get the attribute value for the attribute name
# File lib/nokogiri/xml/node.rb, line 253 def [] name get(name.to_s) end
Set the attribute value for the attribute name
to value
# File lib/nokogiri/xml/node.rb, line 259 def []= name, value set name.to_s, value.to_s end
Accept a visitor. This method calls “visit” on visitor
with self.
# File lib/nokogiri/xml/node.rb, line 726 def accept visitor visitor.visit(self) end
Add node_or_tags
as a child of this Node
. node_or_tags
can be a Nokogiri::XML::Node
, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
Returns the reparented node (if node_or_tags
is a Node
), or NodeSet
(if node_or_tags
is a DocumentFragment
, NodeSet
, or string).
Also see related method +<<+.
# File lib/nokogiri/xml/node.rb, line 270 def add_child node_or_tags node_or_tags = coerce(node_or_tags) if node_or_tags.is_a?(XML::NodeSet) node_or_tags.each { |n| add_child_node_and_reparent_attrs n } else add_child_node_and_reparent_attrs node_or_tags end node_or_tags end
Insert node_or_tags
after this Node
(as a sibling). node_or_tags
can be a Nokogiri::XML::Node
, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
Returns the reparented node (if node_or_tags
is a Node
), or NodeSet
(if node_or_tags
is a DocumentFragment
, NodeSet
, or string).
Also see related method after
.
# File lib/nokogiri/xml/node.rb, line 328 def add_next_sibling node_or_tags raise ArgumentError.new("A document may not have multiple root nodes.") if (parent && parent.document?) && !node_or_tags.processing_instruction? add_sibling :next, node_or_tags end
Insert node_or_tags
before this Node
(as a sibling). node_or_tags
can be a Nokogiri::XML::Node
, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
Returns the reparented node (if node_or_tags
is a Node
), or NodeSet
(if node_or_tags
is a DocumentFragment
, NodeSet
, or string).
Also see related method before
.
# File lib/nokogiri/xml/node.rb, line 315 def add_previous_sibling node_or_tags raise ArgumentError.new("A document may not have multiple root nodes.") if (parent && parent.document?) && !node_or_tags.processing_instruction? add_sibling :previous, node_or_tags end
Insert node_or_tags
after this node (as a sibling). node_or_tags
can be a Nokogiri::XML::Node
, a Nokogiri::XML::DocumentFragment
, or a string containing markup.
Returns self, to support chaining of calls.
Also see related method add_next_sibling
.
# File lib/nokogiri/xml/node.rb, line 353 def after node_or_tags add_next_sibling node_or_tags self end
Get a list of ancestor Node
for this Node
. If selector
is given, the ancestors must match selector
# File lib/nokogiri/xml/node.rb, line 667 def ancestors selector = nil return NodeSet.new(document) unless respond_to?(:parent) return NodeSet.new(document) unless parent parents = [parent] while parents.last.respond_to?(:parent) break unless ctx_parent = parents.last.parent parents << ctx_parent end return NodeSet.new(document, parents) unless selector root = parents.last NodeSet.new(document, parents.find_all { |parent| root.search(selector).include?(parent) }) end
Search for the first occurrence of path
.
Returns nil if nothing is found, otherwise a Node
.
# File lib/nokogiri/xml/node.rb, line 228 def at path, ns = document.root ? document.root.namespaces : {} search(path, ns).first end
Search this node for the first occurrence of XPath
paths
. Equivalent to xpath(paths).first
See Node#xpath
for more information.
# File lib/nokogiri/xml/node.rb, line 238 def at_xpath *paths xpath(*paths).first end
Returns a hash containing the node's attributes. The key is the attribute name without any namespace, the value is a Nokogiri::XML::Attr
representing the attribute. If you need to distinguish attributes with the same name, with different namespaces use attribute_nodes instead.
# File lib/nokogiri/xml/node.rb, line 459 def attributes Hash[attribute_nodes.map { |node| [node.node_name, node] }] end
Insert node_or_tags
before this node (as a sibling). node_or_tags
can be a Nokogiri::XML::Node
, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
Returns self, to support chaining of calls.
Also see related method add_previous_sibling
.
# File lib/nokogiri/xml/node.rb, line 341 def before node_or_tags add_previous_sibling node_or_tags self end
# File lib/nokogiri/xml/node.rb, line 887 def canonicalize(mode=XML::XML_C14N_1_0,inclusive_namespaces=nil,with_comments=false) c14n_root = self document.canonicalize(mode, inclusive_namespaces, with_comments) do |node, parent| tn = node.is_a?(XML::Node) ? node : parent tn == c14n_root || tn.ancestors.include?(c14n_root) end end
Returns true if this is a CDATA
# File lib/nokogiri/xml/node.rb, line 590 def cdata? type == CDATA_SECTION_NODE end
Set the inner html for this Node
node_or_tags
node_or_tags
can be a Nokogiri::XML::Node
, a Nokogiri::XML::DocumentFragment
, or a string containing markup.
Returns the reparented node (if node_or_tags
is a Node
), or NodeSet
(if node_or_tags
is a DocumentFragment
, NodeSet
, or string).
Also see related method inner_html=
# File lib/nokogiri/xml/node.rb, line 377 def children= node_or_tags node_or_tags = coerce(node_or_tags) children.unlink if node_or_tags.is_a?(XML::NodeSet) node_or_tags.each { |n| add_child_node_and_reparent_attrs n } else add_child_node_and_reparent_attrs node_or_tags end node_or_tags end
Returns true if this is a Comment
# File lib/nokogiri/xml/node.rb, line 585 def comment? type == COMMENT_NODE end
Search this node for CSS
rules
. rules
must be one or more CSS
selectors. For example:
node.css('title') node.css('body h1.bold') node.css('div + p.green', 'div#one')
A hash of namespace bindings may be appended. For example:
node.css('bike|tire', {'bike' => 'http://schwinn.com/'})
Custom CSS
pseudo classes may also be defined. To define custom pseudo classes, create a class and implement the custom pseudo class you want defined. The first argument to the method will be the current matching NodeSet
. Any other arguments are ones that you pass in. For example:
node.css('title:regex("\w+")', Class.new { def regex node_set, regex node_set.find_all { |node| node['some_attribute'] =~ /#{regex}/ } end }.new)
Note that the CSS
query string is case-sensitive with regards to your document type. That is, if you're looking for “H1” in an HTML
document, you'll never find anything, since HTML
tags will match only lowercase CSS
queries. However, “H1” might be found in an XML
document, where tags names are case-sensitive (e.g., “H1” is distinct from “h1”).
# File lib/nokogiri/xml/node.rb, line 205 def css *rules rules, handler, ns, binds = extract_params(rules) prefix = "#{implied_xpath_context}/" rules = rules.map { |rule| CSS.xpath_for(rule, :prefix => prefix, :ns => ns) }.flatten.uniq + [ns, handler, binds].compact xpath(*rules) end
Get the path to this node as a CSS
expression
# File lib/nokogiri/xml/node.rb, line 658 def css_path path.split(/\//).map { |part| part.length == 0 ? nil : part.gsub(/\[(\d+)\]/, ':nth-of-type(\1)') }.compact.join(' > ') end
Decorate this node with the decorators set up in this node's Document
# File lib/nokogiri/xml/node.rb, line 89 def decorate! document.decorate(self) end
Adds a default namespace supplied as a string url
href, to self. The consequence is as an xmlns attribute with supplied argument were present in parsed XML
. A default namespace set with this method will now show up in attributes
, but when this node is serialized to XML
an “xmlns” attribute will appear. See also namespace and namespace=
# File lib/nokogiri/xml/node.rb, line 693 def default_namespace= url add_namespace_definition(nil, url) end
Fetch the Nokogiri::HTML::ElementDescription
for this node. Returns nil on XML
documents and on unknown tags.
# File lib/nokogiri/xml/node.rb, line 627 def description return nil if document.xml? Nokogiri::HTML::ElementDescription[name] end
Do xinclude substitution on the subtree below node. If given a block, a Nokogiri::XML::ParseOptions
object initialized from options
, will be passed to it, allowing more convenient modification of the parser options.
# File lib/nokogiri/xml/node.rb, line 877 def do_xinclude options = XML::ParseOptions::DEFAULT_XML, &block options = Nokogiri::XML::ParseOptions.new(options) if Fixnum === options # give options to user yield options if block_given? # call c extension process_xincludes(options.to_i) end
Returns true if this is a Document
# File lib/nokogiri/xml/node.rb, line 605 def document? is_a? XML::Document end
Iterate over each attribute name and value pair for this Node
.
# File lib/nokogiri/xml/node.rb, line 479 def each attribute_nodes.each { |node| yield [node.node_name, node.value] } end
Returns true if this is an Element node
# File lib/nokogiri/xml/node.rb, line 640 def element? type == ELEMENT_NODE end
Create a DocumentFragment
containing tags
that is relative to this context node.
# File lib/nokogiri/xml/node.rb, line 501 def fragment tags type = document.html? ? Nokogiri::HTML : Nokogiri::XML type::DocumentFragment.new(document, tags, self) end
Returns true if this is a DocumentFragment
# File lib/nokogiri/xml/node.rb, line 620 def fragment? type == DOCUMENT_FRAG_NODE end
Returns true if this is an HTML::Document
node
# File lib/nokogiri/xml/node.rb, line 600 def html? type == HTML_DOCUMENT_NODE end
Get the inner_html
for this node's Node#children
# File lib/nokogiri/xml/node.rb, line 653 def inner_html *args children.map { |x| x.to_html(*args) }.join end
Set the inner html for this Node
to node_or_tags
node_or_tags
can be a Nokogiri::XML::Node
, a Nokogiri::XML::DocumentFragment
, or a string containing markup.
Returns self.
Also see related method children=
# File lib/nokogiri/xml/node.rb, line 365 def inner_html= node_or_tags self.children = node_or_tags self end
Get the attribute names for this Node
.
# File lib/nokogiri/xml/node.rb, line 473 def keys attribute_nodes.map { |node| node.node_name } end
Returns true if this Node
matches selector
# File lib/nokogiri/xml/node.rb, line 494 def matches? selector ancestors.last.search(selector).include?(self) end
Set the default namespace on this node (as would be defined with an “xmlns=” attribute in XML
source), as a Namespace
object ns
. Note that a Namespace
added this way will NOT be serialized as an xmlns attribute for this node. You probably want default_namespace=
instead, or perhaps add_namespace_definition with a nil prefix argument.
# File lib/nokogiri/xml/node.rb, line 704 def namespace= ns return set_namespace(ns) unless ns unless Nokogiri::XML::Namespace === ns raise TypeError, "#{ns.class} can't be coerced into Nokogiri::XML::Namespace" end if ns.document != document raise ArgumentError, 'namespace must be declared on the same document' end set_namespace ns end
Returns a Hash of {prefix => value} for all namespaces on this node and its ancestors.
This method returns the same namespaces as namespace_scopes.
Returns namespaces in scope for self – those defined on self element directly or any ancestor node – as a Hash of attribute-name/value pairs. Note that the keys in this hash XML
attributes that would be used to define this namespace, such as “xmlns:prefix”, not just the prefix. Default namespace set on self will be included with key “xmlns”. However, default namespaces set on ancestor will NOT be, even if self has no explicit default namespace.
# File lib/nokogiri/xml/node.rb, line 571 def namespaces Hash[namespace_scopes.map { |nd| key = ['xmlns', nd.prefix].compact.join(':') if RUBY_VERSION >= '1.9' && document.encoding begin key.force_encoding document.encoding rescue ArgumentError end end [key, nd.href] }] end
Parse string_or_io
as a document fragment within the context of this node. Returns a XML::NodeSet
containing the nodes parsed from string_or_io
.
# File lib/nokogiri/xml/node.rb, line 510 def parse string_or_io, options = nil ## # When the current node is unparented and not an element node, use the # document as the parsing context instead. Otherwise, the in-context # parser cannot find an element or a document node. # Document Fragments are also not usable by the in-context parser. if !element? && !document? && (!parent || parent.fragment?) return document.parse(string_or_io, options) end options ||= (document.html? ? ParseOptions::DEFAULT_HTML : ParseOptions::DEFAULT_XML) if Fixnum === options options = Nokogiri::XML::ParseOptions.new(options) end # Give the options to the user yield options if block_given? contents = string_or_io.respond_to?(:read) ? string_or_io.read : string_or_io return Nokogiri::XML::NodeSet.new(document) if contents.empty? ## # This is a horrible hack, but I don't care. See #313 for background. error_count = document.errors.length node_set = in_context(contents, options.to_i) if node_set.empty? and document.errors.length > error_count and options.recover? fragment = Nokogiri::HTML::DocumentFragment.parse contents node_set = fragment.children end node_set end
Add node_or_tags
as the first child of this Node
. node_or_tags
can be a Nokogiri::XML::Node
, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
Returns the reparented node (if node_or_tags
is a Node
), or NodeSet
(if node_or_tags
is a DocumentFragment
, NodeSet
, or string).
Also see related method add_child
.
# File lib/nokogiri/xml/node.rb, line 287 def prepend_child node_or_tags if first = children.first # Mimic the error add_child would raise. raise RuntimeError, "Document already has a root node" if document? && !node_or_tags.processing_instruction? first.__send__(:add_sibling, :previous, node_or_tags) else add_child(node_or_tags) end end
Returns true if this is a ProcessingInstruction
node
# File lib/nokogiri/xml/node.rb, line 610 def processing_instruction? type == PI_NODE end
Is this a read only node?
# File lib/nokogiri/xml/node.rb, line 634 def read_only? # According to gdome2, these are read-only node types [NOTATION_NODE, ENTITY_NODE, ENTITY_DECL].include?(type) end
Remove the attribute named name
# File lib/nokogiri/xml/node.rb, line 487 def remove_attribute name attributes[name].remove if key? name end
Replace this Node
with node_or_tags
. node_or_tags
can be a Nokogiri::XML::Node
, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
Returns the reparented node (if node_or_tags
is a Node
), or NodeSet
(if node_or_tags
is a DocumentFragment
, NodeSet
, or string).
Also see related method swap
.
# File lib/nokogiri/xml/node.rb, line 395 def replace node_or_tags # We cannot replace a text node directly, otherwise libxml will return # an internal error at parser.c:13031, I don't know exactly why # libxml is trying to find a parent node that is an element or document # so I can't tell if this is bug in libxml or not. issue #775. if text? replacee = Nokogiri::XML::Node.new 'dummy', document add_previous_sibling_node replacee unlink return replacee.replace node_or_tags end node_or_tags = coerce(node_or_tags) if node_or_tags.is_a?(XML::NodeSet) node_or_tags.each { |n| add_previous_sibling n } unlink else replace_node node_or_tags end node_or_tags end
Search this node for paths
. paths
can be XPath
or CSS
, and an optional hash of namespaces may be appended. See Node#xpath
and Node#css
.
# File lib/nokogiri/xml/node.rb, line 97 def search *paths # TODO use paths, handler, ns, binds = extract_params(paths) ns = paths.last.is_a?(Hash) ? paths.pop : (document.root ? document.root.namespaces : {}) prefix = "#{implied_xpath_context}/" xpath(*(paths.map { |path| path = path.to_s path =~ /^(\.\/|\/|\.\.|\.$)/ ? path : CSS.xpath_for( path, :prefix => prefix, :ns => ns ) }.flatten.uniq) + [ns]) end
Serialize Node
using options
. Save options can also be set using a block. See SaveOptions
.
These two statements are equivalent:
node.serialize(:encoding => 'UTF-8', :save_with => FORMAT | AS_XML)
or
node.serialize(:encoding => 'UTF-8') do |config| config.format.as_xml end
# File lib/nokogiri/xml/node.rb, line 752 def serialize *args, &block options = args.first.is_a?(Hash) ? args.shift : { :encoding => args[0], :save_with => args[1] } encoding = options[:encoding] || document.encoding options[:encoding] = encoding outstring = "" if encoding && outstring.respond_to?(:force_encoding) outstring.force_encoding(Encoding.find(encoding)) end io = StringIO.new(outstring) write_to io, options, &block io.string end
Swap this Node
for node_or_tags
node_or_tags
can be a Nokogiri::XML::Node
, a ::DocumentFragment, a ::NodeSet, or a string containing markup.
Returns self, to support chaining of calls.
Also see related method replace
.
# File lib/nokogiri/xml/node.rb, line 425 def swap node_or_tags replace node_or_tags self end
Returns true if this is a Text
node
# File lib/nokogiri/xml/node.rb, line 615 def text? type == TEXT_NODE end
doc.to_html
See Node#write_to
for a list of options
. For formatted output, use Node#to_xhtml
instead.
# File lib/nokogiri/xml/node.rb, line 777 def to_html options = {} to_format SaveOptions::DEFAULT_HTML, options end
Serialize this Node
to XHTML using options
doc.to_xhtml(:indent => 5, :encoding => 'UTF-8')
See Node#write_to
for a list of options
# File lib/nokogiri/xml/node.rb, line 798 def to_xhtml options = {} to_format SaveOptions::DEFAULT_XHTML, options end
Serialize this Node
to XML
using options
doc.to_xml(:indent => 5, :encoding => 'UTF-8')
See Node#write_to
for a list of options
# File lib/nokogiri/xml/node.rb, line 787 def to_xml options = {} options[:save_with] ||= SaveOptions::DEFAULT_XML serialize(options) end
Yields self and all children to block
recursively.
# File lib/nokogiri/xml/node.rb, line 719 def traverse &block children.each{|j| j.traverse(&block) } block.call(self) end
Get the attribute values for this Node
.
# File lib/nokogiri/xml/node.rb, line 467 def values attribute_nodes.map { |node| node.value } end
Write Node
as HTML
to io
with options
See Node#write_to
for a list of options
# File lib/nokogiri/xml/node.rb, line 841 def write_html_to io, options = {} write_format_to SaveOptions::DEFAULT_HTML, io, options end
Write Node
to io
with options
. options
modify the output of this method. Valid options are:
-
:encoding
for changing the encoding -
:indent_text
the indentation text, defaults to one space -
:indent
the number of:indent_text
to use, defaults to 2 -
:save_with
a combination ofSaveOptions
constants.
To save with UTF-8 indented twice:
node.write_to(io, :encoding => 'UTF-8', :indent => 2)
To save indented with two dashes:
node.write_to(io, :indent_text => '-', :indent => 2
# File lib/nokogiri/xml/node.rb, line 819 def write_to io, *options options = options.first.is_a?(Hash) ? options.shift : {} encoding = options[:encoding] || options[0] if Nokogiri.jruby? save_options = options[:save_with] || options[1] indent_times = options[:indent] || 0 else save_options = options[:save_with] || options[1] || SaveOptions::FORMAT indent_times = options[:indent] || 2 end indent_text = options[:indent_text] || ' ' config = SaveOptions.new(save_options.to_i) yield config if block_given? native_write_to(io, encoding, indent_text * indent_times, config.options) end
Write Node
as XHTML to io
with options
See Node#write_to
for a list of options
# File lib/nokogiri/xml/node.rb, line 849 def write_xhtml_to io, options = {} write_format_to SaveOptions::DEFAULT_XHTML, io, options end
Write Node
as XML
to io
with options
doc.write_xml_to io, :encoding => 'UTF-8'
See Node#write_to
for a list of options
# File lib/nokogiri/xml/node.rb, line 859 def write_xml_to io, options = {} options[:save_with] ||= SaveOptions::DEFAULT_XML write_to io, options end
Returns true if this is an XML::Document
node
# File lib/nokogiri/xml/node.rb, line 595 def xml? type == DOCUMENT_NODE end
Search this node for XPath
paths
. paths
must be one or more XPath
queries.
node.xpath('.//title')
A hash of namespace bindings may be appended. For example:
node.xpath('.//foo:name', {'foo' => 'http://example.org/'}) node.xpath('.//xmlns:name', node.root.namespaces)
A hash of variable bindings may also be appended to the namespace bindings. For example:
node.xpath('.//address[@domestic=$value]', nil, {:value => 'Yes'})
Custom XPath
functions may also be defined. To define custom functions create a class and implement the function you want to define. The first argument to the method will be the current matching NodeSet
. Any other arguments are ones that you pass in. Note that this class may appear anywhere in the argument list. For example:
node.xpath('.//title[regex(., "\w+")]', Class.new { def regex node_set, regex node_set.find_all { |node| node['some_attribute'] =~ /#{regex}/ } end }.new)
# File lib/nokogiri/xml/node.rb, line 145 def xpath *paths return NodeSet.new(document) unless document paths, handler, ns, binds = extract_params(paths) sets = paths.map { |path| ctx = XPathContext.new(self) ctx.register_namespaces(ns) path = path.gsub(/xmlns:/, ' :') unless Nokogiri.uses_libxml? binds.each do |key,value| ctx.register_variable key.to_s, value end if binds ctx.evaluate(path, handler) } return sets.first if sets.length == 1 NodeSet.new(document) do |combined| sets.each do |set| set.each do |node| combined << node end end end end