Nokogiri::XML::Node
is the primary API you’ll use to interact with your Document
.
A Nokogiri::XML::Node
may be treated similarly to a hash with regard to attributes. For example:
node = Nokogiri::XML::DocumentFragment.parse("<a href='#foo' id='link'>link</a>").at_css("a") node.to_html # => "<a href=\"#foo\" id=\"link\">link</a>" node['href'] # => "#foo" node.keys # => ["href", "id"] node.values # => ["#foo", "link"] node['class'] = 'green' # => "green" node.to_html # => "<a href=\"#foo\" id=\"link\" class=\"green\">link</a>"
See the method group entitled Working With Node Attributes at Node
for the full set of methods.
Nokogiri::XML::Node
also has methods that let you move around your tree:
See the method group entitled Traversing Document Structure at Node
for the full set of methods.
When printing or otherwise emitting a document or a node (and its subtree), there are a few methods you might want to use:
#content
, #text
, #inner_text
, #to_str
These methods will all **emit plaintext**, meaning that entities will be replaced (e.g., +<+ will be replaced with +<+), meaning that any sanitizing will likely be un-done in the output.
#to_s
, #to_xml
, #to_html
, #inner_html
These methods will all **emit properly-escaped markup**, meaning that it’s suitable for consumption by browsers, parsers, etc.
See the method group entitled Serialization and Generating Output at Node
for the full set of methods.
You may search this node’s subtree using methods like #xpath
and #css
.
See the method group entitled Searching via XPath or CSS Queries at Node
for the full set of methods.
Attribute declaration type
Attribute node type
CDATA
node type, see Nokogiri::XML::Node#cdata?
Comment
node type, see Nokogiri::XML::Node#comment?
DOCB document node type
Document
fragment node type
Document
node type, see Nokogiri::XML::Node#xml?
Document
type node type
DTD
node type
Element
declaration type
Element
node type, see Nokogiri::XML::Node#element?
Entity declaration type
Entity node type
Entity reference node type
HTML
document node type, see Nokogiri::XML::Node#html?
Namespace
declaration type
Notation
node type
PI node type
Text
node type, see Nokogiri::XML::Node#text?
XInclude end type
XInclude start type
# File lib/nokogiri/xml/node.rb, line 126 def initialize(name, document) # This is intentionally empty. end
Create a new node with name
that belongs to document
.
If you intend to add a node to a document tree, it’s likely that you will prefer one of the Nokogiri::XML::Node
methods like #add_child
, #add_next_sibling
, #replace
, etc. which will both create an element (or subtree) and place it in the document tree.
Another alternative, if you are concerned about performance, is Nokogiri::XML::Document#create_element
which accepts additional arguments for contents or attributes but (like this method) avoids parsing markup.
name
(String)
document
(Nokogiri::XML::Document
) The document to which the the returned node will belong.
# File lib/nokogiri/xml/node.rb, line 1150 def ==(other) return false unless other return false unless other.respond_to?(:pointer_id) pointer_id == other.pointer_id end
Test to see if this Node
is equal to other
# File lib/nokogiri/xml/node.rb, line 1144 def accept(visitor) visitor.visit(self) end
Accept a visitor. This method calls “visit” on visitor
with self.
# File lib/nokogiri/xml/node.rb, line 1114 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 search_results = root.search(selector) NodeSet.new(document, parents.find_all do |parent| search_results.include?(parent) end) end
Get a list of ancestor Node
for this Node
. If selector
is given, the ancestors must match selector
static VALUE rb_xml_node_blank_eh(VALUE self) { xmlNodePtr node; Data_Get_Struct(self, xmlNode, node); return (1 == xmlIsBlankNode(node)) ? Qtrue : Qfalse ; }
true
if the node is an empty or whitespace-only text or cdata node, else false
.
Example:
Nokogiri("<root><child/></root>").root.child.blank? # => false Nokogiri("<root>\t \n</root>").root.child.blank? # => true Nokogiri("<root><![CDATA[\t \n]]></root>").root.child.blank? # => true Nokogiri("<root>not-blank</root>").root.child .tap { |n| n.content = "" }.blank # => true
# File lib/nokogiri/xml/node.rb, line 1036 def cdata? type == CDATA_SECTION_NODE end
Returns true if this is a CDATA
# File lib/nokogiri/xml/node.rb, line 1031 def comment? type == COMMENT_NODE end
Returns true if this is a Comment
static VALUE rb_xml_node_content(VALUE self) { xmlNodePtr node; xmlChar *content; Data_Get_Struct(self, xmlNode, node); content = xmlNodeGetContent(node); if (content) { VALUE rval = NOKOGIRI_STR_NEW2(content); xmlFree(content); return rval; } return Qnil; }
Contents of all the text nodes in this node’s subtree, concatenated together into a single String.
⚠ Note that entities will always be expanded in the returned String.
See related: #inner_html
Example of how entities are handled:
Note that <
becomes <
in the returned String.
doc = Nokogiri::XML.fragment("<child>a < b</child>") doc.at_css("child").content # => "a < b"
Example of how a subtree is handled:
Note that the <span>
tags are omitted and only the text node contents are returned, concatenated into a single string.
doc = Nokogiri::XML.fragment("<child><span>first</span> <span>second</span></child>") doc.at_css("child").content # => "first second"
static VALUE create_external_subset(VALUE self, VALUE name, VALUE external_id, VALUE system_id) { xmlNodePtr node; xmlDocPtr doc; xmlDtdPtr dtd; Data_Get_Struct(self, xmlNode, node); doc = node->doc; if (doc->extSubset) { rb_raise(rb_eRuntimeError, "Document already has an external subset"); } dtd = xmlNewDtd( doc, NIL_P(name) ? NULL : (const xmlChar *)StringValueCStr(name), NIL_P(external_id) ? NULL : (const xmlChar *)StringValueCStr(external_id), NIL_P(system_id) ? NULL : (const xmlChar *)StringValueCStr(system_id) ); if (!dtd) { return Qnil; } return noko_xml_node_wrap(Qnil, (xmlNodePtr)dtd); }
Create an external subset
static VALUE create_internal_subset(VALUE self, VALUE name, VALUE external_id, VALUE system_id) { xmlNodePtr node; xmlDocPtr doc; xmlDtdPtr dtd; Data_Get_Struct(self, xmlNode, node); doc = node->doc; if (xmlGetIntSubset(doc)) { rb_raise(rb_eRuntimeError, "Document already has an internal subset"); } dtd = xmlCreateIntSubset( doc, NIL_P(name) ? NULL : (const xmlChar *)StringValueCStr(name), NIL_P(external_id) ? NULL : (const xmlChar *)StringValueCStr(external_id), NIL_P(system_id) ? NULL : (const xmlChar *)StringValueCStr(system_id) ); if (!dtd) { return Qnil; } return noko_xml_node_wrap(Qnil, (xmlNodePtr)dtd); }
Create the internal subset of a document.
doc.create_internal_subset("chapter", "-//OASIS//DTD DocBook XML//EN", "chapter.dtd") # => <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML//EN" "chapter.dtd"> doc.create_internal_subset("chapter", nil, "chapter.dtd") # => <!DOCTYPE chapter SYSTEM "chapter.dtd">
# File lib/nokogiri/xml/node.rb, line 1105 def css_path path.split(%r{/}).map do |part| part.empty? ? nil : part.gsub(/\[(\d+)\]/, ':nth-of-type(\1)') end.compact.join(" > ") end
Get the path to this node as a CSS
expression
# File lib/nokogiri/xml/node.rb, line 132 def decorate! document.decorate(self) end
Decorate this node with the decorators set up in this node’s Document
# File lib/nokogiri/xml/node.rb, line 1073 def description return nil if document.xml? Nokogiri::HTML4::ElementDescription[name] end
Fetch the Nokogiri::HTML4::ElementDescription
for this node. Returns nil on XML
documents and on unknown tags.
# File lib/nokogiri/xml/node.rb, line 1051 def document? is_a?(XML::Document) end
Returns true if this is a Document
static VALUE duplicate_node(int argc, VALUE *argv, VALUE self) { VALUE r_level, r_new_parent_doc; int level; int n_args; xmlDocPtr new_parent_doc; xmlNodePtr node, dup; Data_Get_Struct(self, xmlNode, node); n_args = rb_scan_args(argc, argv, "02", &r_level, &r_new_parent_doc); if (n_args < 1) { r_level = INT2NUM((long)1); } level = (int)NUM2INT(r_level); if (n_args < 2) { new_parent_doc = node->doc; } else { Data_Get_Struct(r_new_parent_doc, xmlDoc, new_parent_doc); } dup = xmlDocCopyNode(node, new_parent_doc, level); if (dup == NULL) { return Qnil; } noko_xml_document_pin_node(dup); return noko_xml_node_wrap(rb_obj_class(self), dup); }
Copy this node.
depth
0 is a shallow copy, 1 (the default) is a deep copy.
new_parent_doc
The new node’s parent Document
. Defaults to the this node’s document.
The new Nokgiri::XML::Node
# File lib/nokogiri/xml/node.rb, line 1086 def element? type == ELEMENT_NODE end
Returns true if this is an Element
node
static VALUE rb_xml_node_element_children(VALUE self) { xmlNodePtr node; xmlNodePtr child; xmlNodeSetPtr set; VALUE document; VALUE node_set; Data_Get_Struct(self, xmlNode, node); child = xmlFirstElementChild(node); set = xmlXPathNodeSetCreate(child); document = DOC_RUBY_OBJECT(node->doc); if (!child) { return noko_xml_node_set_wrap(set, document); } child = xmlNextElementSibling(child); while (NULL != child) { xmlXPathNodeSetAddUnique(set, child); child = xmlNextElementSibling(child); } node_set = noko_xml_node_set_wrap(set, document); return node_set; }
The node’s child elements as a NodeSet
. Only children that are elements will be returned, which notably excludes Text
nodes.
Example:
Note that #children
returns the Text
node “hello” while #element_children
does not.
div = Nokogiri::HTML5("<div>hello<span>world</span>").at_css("div") div.element_children # => [#<Nokogiri::XML::Element:0x50 name="span" children=[#<Nokogiri::XML::Text:0x3c "world">]>] div.children # => [#<Nokogiri::XML::Text:0x64 "hello">, # #<Nokogiri::XML::Element:0x50 name="span" children=[#<Nokogiri::XML::Text:0x3c "world">]>]
static VALUE encode_special_chars(VALUE self, VALUE string) { xmlNodePtr node; xmlChar *encoded; VALUE encoded_str; Data_Get_Struct(self, xmlNode, node); encoded = xmlEncodeSpecialChars( node->doc, (const xmlChar *)StringValueCStr(string) ); encoded_str = NOKOGIRI_STR_NEW2(encoded); xmlFree(encoded); return encoded_str; }
Encode any special characters in string
static VALUE external_subset(VALUE self) { xmlNodePtr node; xmlDocPtr doc; xmlDtdPtr dtd; Data_Get_Struct(self, xmlNode, node); if (!node->doc) { return Qnil; } doc = node->doc; dtd = doc->extSubset; if (!dtd) { return Qnil; } return noko_xml_node_wrap(Qnil, (xmlNodePtr)dtd); }
Get the external subset
static VALUE rb_xml_node_first_element_child(VALUE self) { xmlNodePtr node, child; Data_Get_Struct(self, xmlNode, node); child = xmlFirstElementChild(node); if (!child) { return Qnil; } return noko_xml_node_wrap(Qnil, child); }
The first child Node
that is an element.
Example:
Note that the “hello” child, which is a Text
node, is skipped and the <span>
element is returned.
div = Nokogiri::HTML5("<div>hello<span>world</span>").at_css("div") div.first_element_child # => #(Element:0x3c { name = "span", children = [ #(Text "world")] })
# File lib/nokogiri/xml/node.rb, line 928 def fragment(tags) document.related_class("DocumentFragment").new(document, tags, self) end
Create a DocumentFragment
containing tags
that is relative to this context node.
# File lib/nokogiri/xml/node.rb, line 1066 def fragment? type == DOCUMENT_FRAG_NODE end
Returns true if this is a DocumentFragment
# File lib/nokogiri/xml/node.rb, line 1046 def html? type == HTML_DOCUMENT_NODE end
Returns true if this is an HTML4::Document
or HTML5::Document
node
# File lib/nokogiri/xml/node.rb, line 1100 def inner_html(*args) children.map { |x| x.to_html(*args) }.join end
Get the inner_html
for this node’s Node#children
static VALUE internal_subset(VALUE self) { xmlNodePtr node; xmlDocPtr doc; xmlDtdPtr dtd; Data_Get_Struct(self, xmlNode, node); if (!node->doc) { return Qnil; } doc = node->doc; dtd = xmlGetIntSubset(doc); if (!dtd) { return Qnil; } return noko_xml_node_wrap(Qnil, (xmlNodePtr)dtd); }
Get the internal subset
static VALUE key_eh(VALUE self, VALUE attribute) { xmlNodePtr node; Data_Get_Struct(self, xmlNode, node); if (xmlHasProp(node, (xmlChar *)StringValueCStr(attribute))) { return Qtrue; } return Qfalse; }
Returns true if attribute
is set
static VALUE get_lang(VALUE self_rb) { xmlNodePtr self ; xmlChar *lang ; VALUE lang_rb ; Data_Get_Struct(self_rb, xmlNode, self); lang = xmlNodeGetLang(self); if (lang) { lang_rb = NOKOGIRI_STR_NEW2(lang); xmlFree(lang); return lang_rb ; } return Qnil ; }
Searches the language of a node, i.e. the values of the xml:lang attribute or the one carried by the nearest ancestor.
static VALUE set_lang(VALUE self_rb, VALUE lang_rb) { xmlNodePtr self ; xmlChar *lang ; Data_Get_Struct(self_rb, xmlNode, self); lang = (xmlChar *)StringValueCStr(lang_rb); xmlNodeSetLang(self, lang); return Qnil ; }
Set the language of a node, i.e. the values of the xml:lang attribute.
static VALUE rb_xml_node_last_element_child(VALUE self) { xmlNodePtr node, child; Data_Get_Struct(self, xmlNode, node); child = xmlLastElementChild(node); if (!child) { return Qnil; } return noko_xml_node_wrap(Qnil, child); }
The last child Node
that is an element.
Example:
Note that the “hello” child, which is a Text
node, is skipped and the <span>yes</span>
element is returned.
div = Nokogiri::HTML5("<div><span>no</span><span>yes</span>skip</div>").at_css("div") div.last_element_child # => #(Element:0x3c { name = "span", children = [ #(Text "yes")] })
static VALUE rb_xml_node_line(VALUE rb_node) { xmlNodePtr c_node; Data_Get_Struct(rb_node, xmlNode, c_node); return INT2NUM(xmlGetLineNo(c_node)); }
The line number of this Node
.
⚠ The CRuby and JRuby implementations differ in important ways!
Semantic differences:
The CRuby method reflects the node’s line number in the parsed string
The JRuby method reflects the node’s line number in the final DOM structure after corrections have been applied
Performance differences:
The CRuby method is O(1) (constant time)
The JRuby method is O(n) (linear time, where n is the number of nodes before/above the element in the DOM)
If you’d like to help improve the JRuby implementation, please review these issues and reach out to the maintainers:
static VALUE rb_xml_node_line_set(VALUE rb_node, VALUE rb_line_number) { xmlNodePtr c_node; int line_number = NUM2INT(rb_line_number); Data_Get_Struct(rb_node, xmlNode, c_node); // libxml2 optionally uses xmlNode.psvi to store longer line numbers, but only for text nodes. // search for "psvi" in SAX2.c and tree.c to learn more. if (line_number < 65535) { c_node->line = (short) line_number; } else { c_node->line = 65535; if (c_node->type == XML_TEXT_NODE) { c_node->psvi = (void *)(ptrdiff_t) line_number; } } return rb_line_number; }
Sets the line for this Node
. num must be less than 65535.
# File lib/nokogiri/xml/node.rb, line 921 def matches?(selector) ancestors.last.search(selector).include?(self) end
Returns true if this Node
matches selector
static VALUE rb_xml_node_namespace(VALUE rb_node) { xmlNodePtr c_node ; Data_Get_Struct(rb_node, xmlNode, c_node); if (c_node->ns) { return noko_xml_namespace_wrap(c_node->ns, c_node->doc); } return Qnil ; }
The Namespace
of the element or attribute node, or nil
if there is no namespace.
Example:
doc = Nokogiri::XML(<<~EOF) <root> <first/> <second xmlns="http://example.com/child"/> <foo:third xmlns:foo="http://example.com/foo"/> </root> EOF doc.at_xpath("//first").namespace # => nil doc.at_xpath("//xmlns:second", "xmlns" => "http://example.com/child").namespace # => #(Namespace:0x3c { href = "http://example.com/child" }) doc.at_xpath("//foo:third", "foo" => "http://example.com/foo").namespace # => #(Namespace:0x50 { prefix = "foo", href = "http://example.com/foo" })
static VALUE namespace_definitions(VALUE rb_node) { /* this code in the mode of xmlHasProp() */ xmlNodePtr c_node ; xmlNsPtr c_namespace; VALUE definitions = rb_ary_new(); Data_Get_Struct(rb_node, xmlNode, c_node); c_namespace = c_node->nsDef; if (!c_namespace) { return definitions; } while (c_namespace != NULL) { rb_ary_push(definitions, noko_xml_namespace_wrap(c_namespace, c_node->doc)); c_namespace = c_namespace->next; } return definitions; }
Namespaces that are defined directly on this node, as an Array of Namespace
objects. The array will be empty if no namespaces are defined on this node.
Example:
doc = Nokogiri::XML(<<~EOF) <root xmlns="http://example.com/root"> <first/> <second xmlns="http://example.com/child" xmlns:unused="http://example.com/unused"/> <foo:third xmlns:foo="http://example.com/foo"/> </root> EOF doc.at_xpath("//root:first", "root" => "http://example.com/root").namespace_definitions # => [] doc.at_xpath("//xmlns:second", "xmlns" => "http://example.com/child").namespace_definitions # => [#(Namespace:0x3c { href = "http://example.com/child" }), # #(Namespace:0x50 { # prefix = "unused", # href = "http://example.com/unused" # })] doc.at_xpath("//foo:third", "foo" => "http://example.com/foo").namespace_definitions # => [#(Namespace:0x64 { prefix = "foo", href = "http://example.com/foo" })]
static VALUE rb_xml_node_namespace_scopes(VALUE rb_node) { xmlNodePtr c_node ; xmlNsPtr *namespaces; VALUE scopes = rb_ary_new(); int j; Data_Get_Struct(rb_node, xmlNode, c_node); namespaces = xmlGetNsList(c_node->doc, c_node); if (!namespaces) { return scopes; } for (j = 0 ; namespaces[j] != NULL ; ++j) { rb_ary_push(scopes, noko_xml_namespace_wrap(namespaces[j], c_node->doc)); } xmlFree(namespaces); return scopes; }
Array of all the Namespaces on this node and its ancestors.
See also #namespaces
Example:
doc = Nokogiri::XML(<<~EOF) <root xmlns="http://example.com/root" xmlns:bar="http://example.com/bar"> <first/> <second xmlns="http://example.com/child"/> <third xmlns:foo="http://example.com/foo"/> </root> EOF doc.at_xpath("//root:first", "root" => "http://example.com/root").namespace_scopes # => [#(Namespace:0x3c { href = "http://example.com/root" }), # #(Namespace:0x50 { prefix = "bar", href = "http://example.com/bar" })] doc.at_xpath("//child:second", "child" => "http://example.com/child").namespace_scopes # => [#(Namespace:0x64 { href = "http://example.com/child" }), # #(Namespace:0x50 { prefix = "bar", href = "http://example.com/bar" })] doc.at_xpath("//root:third", "root" => "http://example.com/root").namespace_scopes # => [#(Namespace:0x78 { prefix = "foo", href = "http://example.com/foo" }), # #(Namespace:0x3c { href = "http://example.com/root" }), # #(Namespace:0x50 { prefix = "bar", href = "http://example.com/bar" })]
static VALUE namespaced_key_eh(VALUE self, VALUE attribute, VALUE namespace) { xmlNodePtr node; Data_Get_Struct(self, xmlNode, node); if (xmlHasNsProp(node, (xmlChar *)StringValueCStr(attribute), NIL_P(namespace) ? NULL : (xmlChar *)StringValueCStr(namespace))) { return Qtrue; } return Qfalse; }
Returns true if attribute
is set with namespace
# File lib/nokogiri/xml/node.rb, line 1022 def namespaces namespace_scopes.each_with_object({}) do |ns, hash| prefix = ns.prefix key = prefix ? "xmlns:#{prefix}" : "xmlns" hash[key] = ns.href end end
Fetch all the namespaces on this node and its ancestors.
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.
The default namespace for this node will be included with key “xmlns”.
See also #namespace_scopes
Hash containing all the namespaces on this node and its ancestors. The hash keys are the namespace prefix, and the hash value for each key is the namespace URI.
Example:
doc = Nokogiri::XML(<<~EOF) <root xmlns="http://example.com/root" xmlns:in_scope="http://example.com/in_scope"> <first/> <second xmlns="http://example.com/child"/> <third xmlns:foo="http://example.com/foo"/> </root> EOF doc.at_xpath("//root:first", "root" => "http://example.com/root").namespaces # => {"xmlns"=>"http://example.com/root", # "xmlns:in_scope"=>"http://example.com/in_scope"} doc.at_xpath("//child:second", "child" => "http://example.com/child").namespaces # => {"xmlns"=>"http://example.com/child", # "xmlns:in_scope"=>"http://example.com/in_scope"} doc.at_xpath("//root:third", "root" => "http://example.com/root").namespaces # => {"xmlns:foo"=>"http://example.com/foo", # "xmlns"=>"http://example.com/root", # "xmlns:in_scope"=>"http://example.com/in_scope"}
static VALUE set_native_content(VALUE self, VALUE content) { xmlNodePtr node, child, next ; Data_Get_Struct(self, xmlNode, node); child = node->children; while (NULL != child) { next = child->next ; xmlUnlinkNode(child) ; noko_xml_document_pin_node(child); child = next ; } xmlNodeSetContent(node, (xmlChar *)StringValueCStr(content)); return content; }
Set the content for this Node
static VALUE next_element(VALUE self) { xmlNodePtr node, sibling; Data_Get_Struct(self, xmlNode, node); sibling = xmlNextElementSibling(node); if (!sibling) { return Qnil; } return noko_xml_node_wrap(Qnil, sibling); }
Returns the next Nokogiri::XML::Element
type sibling node.
static VALUE next_sibling(VALUE self) { xmlNodePtr node, sibling; Data_Get_Struct(self, xmlNode, node); sibling = node->next; if (!sibling) { return Qnil; } return noko_xml_node_wrap(Qnil, sibling) ; }
Returns the next sibling node
static VALUE get_name(VALUE self) { xmlNodePtr node; Data_Get_Struct(self, xmlNode, node); if (node->name) { return NOKOGIRI_STR_NEW2(node->name); } return Qnil; }
Returns the name for this Node
static VALUE set_name(VALUE self, VALUE new_name) { xmlNodePtr node; Data_Get_Struct(self, xmlNode, node); xmlNodeSetName(node, (xmlChar *)StringValueCStr(new_name)); return new_name; }
Set the name for this Node
static VALUE node_type(VALUE self) { xmlNodePtr node; Data_Get_Struct(self, xmlNode, node); return INT2NUM((long)node->type); }
Get the type for this Node
# File lib/nokogiri/xml/node.rb, line 936 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) options = Nokogiri::XML::ParseOptions.new(options) if Integer === options yield options if block_given? contents = if string_or_io.respond_to?(:read) string_or_io.read else string_or_io end return Nokogiri::XML::NodeSet.new(document) if contents.empty? # libxml2 does not obey the +recover+ option after encountering errors during +in_context+ # parsing, and so this horrible hack is here to try to emulate recovery behavior. # # Unfortunately, this means we're no longer parsing "in context" and so namespaces that # would have been inherited from the context node won't be handled correctly. This hack was # written in 2010, and I regret it, because it's silently degrading functionality in a way # that's not easily prevented (or even detected). # # I think preferable behavior would be to either: # # a. add an error noting that we "fell back" and pointing the user to turning off the +recover+ option # b. don't recover, but raise a sensible exception # # For context and background: https://github.com/sparklemotion/nokogiri/issues/313 # FIXME bug report: https://github.com/sparklemotion/nokogiri/issues/2092 error_count = document.errors.length node_set = in_context(contents, options.to_i) if node_set.empty? && (document.errors.length > error_count) if options.recover? fragment = document.related_class("DocumentFragment").parse(contents) node_set = fragment.children else raise document.errors[error_count] end end node_set 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
.
static VALUE rb_xml_node_path(VALUE rb_node) { xmlNodePtr c_node; xmlChar *c_path ; VALUE rval; Data_Get_Struct(rb_node, xmlNode, c_node); c_path = xmlGetNodePath(c_node); if (c_path == NULL) { // see https://github.com/sparklemotion/nokogiri/issues/2250 // this behavior is clearly undesirable, but is what libxml <= 2.9.10 returned, and so we // do this for now to preserve the behavior across libxml2 versions. rval = NOKOGIRI_STR_NEW2("?"); } else { rval = NOKOGIRI_STR_NEW2(c_path); xmlFree(c_path); } return rval ; }
Returns the path associated with this Node
static VALUE rb_xml_node_pointer_id(VALUE self) { xmlNodePtr node; Data_Get_Struct(self, xmlNode, node); return INT2NUM((long)(node)); }
A unique id for this node based on the internal memory structures. This method is used by #==
to determine node identity.
static VALUE previous_element(VALUE self) { xmlNodePtr node, sibling; Data_Get_Struct(self, xmlNode, node); /* * note that we don't use xmlPreviousElementSibling here because it's buggy pre-2.7.7. */ sibling = node->prev; if (!sibling) { return Qnil; } while (sibling && sibling->type != XML_ELEMENT_NODE) { sibling = sibling->prev; } return sibling ? noko_xml_node_wrap(Qnil, sibling) : Qnil ; }
Returns the previous Nokogiri::XML::Element
type sibling node.
static VALUE previous_sibling(VALUE self) { xmlNodePtr node, sibling; Data_Get_Struct(self, xmlNode, node); sibling = node->prev; if (!sibling) { return Qnil; } return noko_xml_node_wrap(Qnil, sibling); }
Returns the previous sibling node
# File lib/nokogiri/xml/node.rb, line 1056 def processing_instruction? type == PI_NODE end
Returns true if this is a ProcessingInstruction
node
# File lib/nokogiri/xml/node.rb, line 1080 def read_only? # According to gdome2, these are read-only node types [NOTATION_NODE, ENTITY_NODE, ENTITY_DECL].include?(type) end
Is this a read only node?
# File lib/nokogiri/xml/node.rb, line 1061 def text? type == TEXT_NODE end
Returns true if this is a Text
node
# File lib/nokogiri/xml/node.rb, line 1137 def traverse(&block) children.each { |j| j.traverse(&block) } yield(self) end
Yields self and all children to block
recursively.
static VALUE unlink_node(VALUE self) { xmlNodePtr node; Data_Get_Struct(self, xmlNode, node); xmlUnlinkNode(node); noko_xml_document_pin_node(node); return self; }
Unlink this node from its current context.
# File lib/nokogiri/xml/node.rb, line 1041 def xml? type == DOCUMENT_NODE end
Returns true if this is an XML::Document
node
# File lib/nokogiri/xml/node.rb, line 1312 def coerce(data) case data when XML::NodeSet return data when XML::DocumentFragment return data.children when String return fragment(data).children when Document, XML::Attr # unacceptable when XML::Node return data end raise ArgumentError, <<~EOERR Requires a Node, NodeSet or String argument, and cannot accept a #{data.class}. (You probably want to select a node from the Document with at() or search(), or create a new Node via Node.new().) EOERR end
# File lib/nokogiri/xml/node.rb, line 190 def <<(node_or_tags) add_child(node_or_tags) 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 self, to support chaining of calls (e.g., root << child1 << child2)
Also see related method add_child
.
# File lib/nokogiri/xml/node.rb, line 145 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
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 +<<+.
static VALUE rb_xml_node_add_namespace_definition(VALUE rb_node, VALUE rb_prefix, VALUE rb_href) { xmlNodePtr c_node, element; xmlNsPtr c_namespace; const xmlChar *c_prefix = (const xmlChar *)(NIL_P(rb_prefix) ? NULL : StringValueCStr(rb_prefix)); Data_Get_Struct(rb_node, xmlNode, c_node); element = c_node ; c_namespace = xmlSearchNs(c_node->doc, c_node, c_prefix); if (!c_namespace) { if (c_node->type != XML_ELEMENT_NODE) { element = c_node->parent; } c_namespace = xmlNewNs(element, (const xmlChar *)StringValueCStr(rb_href), c_prefix); } if (!c_namespace) { return Qnil ; } if (NIL_P(rb_prefix) || c_node != element) { xmlSetNs(c_node, c_namespace); } return noko_xml_namespace_wrap(c_namespace, c_node->doc); }
Adds a namespace definition to this node with prefix
using href
value, as if this node had included an attribute “xmlns:prefix=href”.
A default namespace definition for this node can be added by passing nil
for prefix
.
prefix
(String, nil
) An XML Name
href
(String) The URI reference
The new Nokogiri::XML::Namespace
Example: adding a non-default namespace definition
doc = Nokogiri::XML("<store><inventory></inventory></store>") inventory = doc.at_css("inventory") inventory.add_namespace_definition("automobile", "http://alices-autos.com/") inventory.add_namespace_definition("bicycle", "http://bobs-bikes.com/") inventory.add_child("<automobile:tire>Michelin model XGV, size 75R</automobile:tire>") doc.to_xml # => "<?xml version=\"1.0\"?>\n" + # "<store>\n" + # " <inventory xmlns:automobile=\"http://alices-autos.com/\" xmlns:bicycle=\"http://bobs-bikes.com/\">\n" + # " <automobile:tire>Michelin model XGV, size 75R</automobile:tire>\n" + # " </inventory>\n" + # "</store>\n"
Example: adding a default namespace definition
doc = Nokogiri::XML("<store><inventory><tire>Michelin model XGV, size 75R</tire></inventory></store>") doc.at_css("tire").add_namespace_definition(nil, "http://bobs-bikes.com/") doc.to_xml # => "<?xml version=\"1.0\"?>\n" + # "<store>\n" + # " <inventory>\n" + # " <tire xmlns=\"http://bobs-bikes.com/\">Michelin model XGV, size 75R</tire>\n" + # " </inventory>\n" + # "</store>\n"
# File lib/nokogiri/xml/node.rb, line 216 def add_next_sibling(node_or_tags) raise ArgumentError, "A document may not have multiple root nodes." if parent&.document? && !(node_or_tags.comment? || node_or_tags.processing_instruction?) add_sibling(:next, 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 202 def add_previous_sibling(node_or_tags) raise ArgumentError, "A document may not have multiple root nodes." if parent&.document? && !(node_or_tags.comment? || node_or_tags.processing_instruction?) add_sibling(:previous, 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 242 def after(node_or_tags) add_next_sibling(node_or_tags) self 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 230 def before(node_or_tags) add_previous_sibling(node_or_tags) self 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 261 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 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.
Also see related method inner_html=
# File lib/nokogiri/xml/node.rb, line 333 def default_namespace=(url) add_namespace_definition(nil, url) 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 360 def do_xinclude(options = XML::ParseOptions::DEFAULT_XML) options = Nokogiri::XML::ParseOptions.new(options) if Integer === options yield options if block_given? # call c extension process_xincludes(options.to_i) 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 252 def inner_html=(node_or_tags) self.children = node_or_tags 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.
Also see related method children=
# File lib/nokogiri/xml/node.rb, line 343 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
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 162 def prepend_child(node_or_tags) if (first = children.first) # Mimic the error add_child would raise. raise "Document already has a root node" if document? && !(node_or_tags.comment? || node_or_tags.processing_instruction?) first.__send__(:add_sibling, :previous, node_or_tags) else add_child(node_or_tags) end 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 278 def replace(node_or_tags) raise("Cannot replace a node with no parent") unless parent # 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 = parent.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
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 310 def swap(node_or_tags) replace(node_or_tags) self 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 176 def wrap(html) new_parent = document.parse(html).first add_next_sibling(new_parent) new_parent.add_child(self) self end
Add html around this node
Returns self
# File lib/nokogiri/xml/node.rb, line 1300 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
# File lib/nokogiri/xml/node.rb, line 1181 def serialize(*args, &block) options = if args.first.is_a?(Hash) args.shift else { encoding: args[0], save_with: args[1], } end encoding = options[:encoding] || document.encoding options[:encoding] = encoding outstring = +"" outstring.force_encoding(Encoding.find(encoding || "utf-8")) io = StringIO.new(outstring) write_to(io, options, &block) io.string 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 1208 def to_html(options = {}) to_format(SaveOptions::DEFAULT_HTML, options) 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 1229 def to_xhtml(options = {}) to_format(SaveOptions::DEFAULT_XHTML, 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 1218 def to_xml(options = {}) options[:save_with] ||= SaveOptions::DEFAULT_XML serialize(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 1277 def write_html_to(io, options = {}) write_format_to(SaveOptions::DEFAULT_HTML, io, options) 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 1250 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] || " " # Any string times 0 returns an empty string. Therefore, use the same # string instead of generating a new empty string for every node with # zero indentation. indentation = indent_times.zero? ? "" : (indent_text * indent_times) config = SaveOptions.new(save_options.to_i) yield config if block_given? native_write_to(io, encoding, indentation, config.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 of SaveOptions
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 1285 def write_xhtml_to(io, options = {}) write_format_to(SaveOptions::DEFAULT_XHTML, io, 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 1295 def write_xml_to(io, options = {}) options[:save_with] ||= SaveOptions::DEFAULT_XML write_to(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
static VALUE rb_xml_node_child(VALUE self) { xmlNodePtr node, child; Data_Get_Struct(self, xmlNode, node); child = node->children; if (!child) { return Qnil; } return noko_xml_node_wrap(Qnil, child); }
First of this node’s children, or nil
if there are no children
This is a convenience method and is equivalent to:
node.children.first
See related: #children
static VALUE rb_xml_node_children(VALUE self) { xmlNodePtr node; xmlNodePtr child; xmlNodeSetPtr set; VALUE document; VALUE node_set; Data_Get_Struct(self, xmlNode, node); child = node->children; set = xmlXPathNodeSetCreate(child); document = DOC_RUBY_OBJECT(node->doc); if (!child) { return noko_xml_node_set_wrap(set, document); } child = child->next; while (NULL != child) { xmlXPathNodeSetAddUnique(set, child); child = child->next; } node_set = noko_xml_node_set_wrap(set, document); return node_set; }
Nokogiri::XML::NodeSet
containing this node’s children.
static VALUE rb_xml_node_document(VALUE self) { xmlNodePtr node; Data_Get_Struct(self, xmlNode, node); return DOC_RUBY_OBJECT(node->doc); }
Parent Nokogiri::XML::Document
for this node
# File lib/nokogiri/xml/node.rb, line 418 def [](name) get(name.to_s) end
Fetch an attribute from this node.
⚠ Note that attributes with namespaces cannot be accessed with this method. To access namespaced attributes, use #attribute_with_ns
.
(String, nil) value of the attribute name
, or nil
if no matching attribute exists
Example
doc = Nokogiri::XML("<root><child size='large' class='big wide tall'/></root>") child = doc.at_css("child") child["size"] # => "large" child["class"] # => "big wide tall"
Example: Namespaced attributes will not be returned.
⚠ Note namespaced attributes may be accessed with #attribute
or #attribute_with_ns
doc = Nokogiri::XML(<<~EOF) <root xmlns:width='http://example.com/widths'> <child width:size='broad'/> </root> EOF doc.at_css("child")["size"] # => nil doc.at_css("child").attribute("size").value # => "broad" doc.at_css("child").attribute_with_ns("size", "http://example.com/widths").value # => "broad"
# File lib/nokogiri/xml/node.rb, line 456 def []=(name, value) set(name.to_s, value.to_s) end
Update the attribute name
to value
, or create the attribute if it does not exist.
⚠ Note that attributes with namespaces cannot be accessed with this method. To access namespaced attributes for update, use #attribute_with_ns
. To add a namespaced attribute, see the example below.
value
Example
doc = Nokogiri::XML("<root><child/></root>") child = doc.at_css("child") child["size"] = "broad" child.to_html # => "<child size=\"broad\"></child>"
Example: Add a namespaced attribute.
doc = Nokogiri::XML(<<~EOF) <root xmlns:width='http://example.com/widths'> <child/> </root> EOF child = doc.at_css("child") child["size"] = "broad" ns = doc.root.namespace_definitions.find { |ns| ns.prefix == "width" } child.attribute("size").namespace = ns doc.to_html # => "<root xmlns:width=\"http://example.com/widths\">\n" + # " <child width:size=\"broad\"></child>\n" + # "</root>\n"
# File lib/nokogiri/xml/node.rb, line 621 def add_class(names) kwattr_add("class", names) end
Ensure HTML
CSS
classes are present on self
. Any CSS
classes in names
that already exist in the “class” attribute are not added. Note that any existing duplicates in the “class” attribute are not removed. Compare with #append_class
.
This is a convenience function and is equivalent to:
node.kwattr_add("class", names)
See related: #kwattr_add
, #classes
, #append_class
, #remove_class
names
(String, Array<String>)
CSS
class names to be added to the Node’s “class” attribute. May be a string containing whitespace-delimited names, or an Array of String names. Any class names already present will not be added. Any class names not present will be added. If no “class” attribute exists, one is created.
self
(Node
) for ease of chaining method calls.
Example: Ensure that the node has CSS
class “section”
node # => <div></div> node.add_class("section") # => <div class="section"></div> node.add_class("section") # => <div class="section"></div> # duplicate not added
Example: Ensure that the node has CSS
classes “section” and “header”, via a String argument
Note that the CSS
class “section” is not added because it is already present. Note also that the pre-existing duplicate CSS
class “section” is not removed.
node # => <div class="section section"></div> node.add_class("section header") # => <div class="section section header"></div>
Example: Ensure that the node has CSS
classes “section” and “header”, via an Array argument
node # => <div></div> node.add_class(["section", "header"]) # => <div class="section header"></div>
# File lib/nokogiri/xml/node.rb, line 665 def append_class(names) kwattr_append("class", names) end
Add HTML
CSS
classes to self
, regardless of duplication. Compare with #add_class
.
This is a convenience function and is equivalent to:
node.kwattr_append("class", names)
See related: #kwattr_append
, #classes
, #add_class
, #remove_class
names
(String, Array<String>)
CSS
class names to be appended to the Node’s “class” attribute. May be a string containing whitespace-delimited names, or an Array of String names. All class names passed in will be appended to the “class” attribute even if they are already present in the attribute value. If no “class” attribute exists, one is created.
self
(Node
) for ease of chaining method calls.
Example: Append “section” to the node’s CSS
“class” attribute
node # => <div></div> node.append_class("section") # => <div class="section"></div> node.append_class("section") # => <div class="section section"></div> # duplicate added!
Example: Append “section” and “header” to the noded’s CSS
“class” attribute, via a String argument
Note that the CSS
class “section” is appended even though it is already present
node # => <div class="section section"></div> node.append_class("section header") # => <div class="section section section header"></div>
Example: Append “section” and “header” to the node’s CSS
“class” attribute, via an Array argument
node # => <div></div> node.append_class(["section", "header"]) # => <div class="section header"></div> node.append_class(["section", "header"]) # => <div class="section header section header"></div>
static VALUE rb_xml_node_attribute(VALUE self, VALUE name) { xmlNodePtr node; xmlAttrPtr prop; Data_Get_Struct(self, xmlNode, node); prop = xmlHasProp(node, (xmlChar *)StringValueCStr(name)); if (! prop) { return Qnil; } return noko_xml_node_wrap(Qnil, (xmlNodePtr)prop); }
Attribute (Nokogiri::XML::Attr
) belonging to this node with name name
.
⚠ Note that attribute namespaces are ignored and only the simple (non-namespace-prefixed) name is used to find a matching attribute. In case of a simple name collision, only one of the matching attributes will be returned. In this case, you will need to use #attribute_with_ns
.
Example:
doc = Nokogiri::XML("<root><child size='large' class='big wide tall'/></root>") child = doc.at_css("child") child.attribute("size") # => #<Nokogiri::XML::Attr:0x550 name="size" value="large"> child.attribute("class") # => #<Nokogiri::XML::Attr:0x564 name="class" value="big wide tall">
Example showing that namespaced attributes will not be returned:
⚠ Note that only one of the two matching attributes is returned.
doc = Nokogiri::XML(<<~EOF) <root xmlns:width='http://example.com/widths' xmlns:height='http://example.com/heights'> <child width:size='broad' height:size='tall'/> </root> EOF doc.at_css("child").attribute("size") # => #(Attr:0x550 { # name = "size", # namespace = #(Namespace:0x564 { # prefix = "width", # href = "http://example.com/widths" # }), # value = "broad" # })
static VALUE rb_xml_node_attribute_nodes(VALUE rb_node) { xmlNodePtr c_node; Data_Get_Struct(rb_node, xmlNode, c_node); return noko_xml_node_attrs(c_node); }
Attributes (an Array of Nokogiri::XML::Attr
) belonging to this node.
Note that this is the preferred alternative to #attributes
when the simple (non-namespace-prefixed) attribute names may collide.
Example:
Contrast this with the colliding-name example from #attributes
.
doc = Nokogiri::XML(<<~EOF) <root xmlns:width='http://example.com/widths' xmlns:height='http://example.com/heights'> <child width:size='broad' height:size='tall'/> </root> EOF doc.at_css("child").attribute_nodes # => [#(Attr:0x550 { # name = "size", # namespace = #(Namespace:0x564 { # prefix = "width", # href = "http://example.com/widths" # }), # value = "broad" # }), # #(Attr:0x578 { # name = "size", # namespace = #(Namespace:0x58c { # prefix = "height", # href = "http://example.com/heights" # }), # value = "tall" # })]
static VALUE rb_xml_node_attribute_with_ns(VALUE self, VALUE name, VALUE namespace) { xmlNodePtr node; xmlAttrPtr prop; Data_Get_Struct(self, xmlNode, node); prop = xmlHasNsProp(node, (xmlChar *)StringValueCStr(name), NIL_P(namespace) ? NULL : (xmlChar *)StringValueCStr(namespace)); if (! prop) { return Qnil; } return noko_xml_node_wrap(Qnil, (xmlNodePtr)prop); }
Attribute (Nokogiri::XML::Attr
) belonging to this node with matching name
and namespace
.
name
(String): the simple (non-namespace-prefixed) name of the attribute
namespace
(String): the URI of the attribute’s namespace
See related: #attribute
Example:
doc = Nokogiri::XML(<<~EOF) <root xmlns:width='http://example.com/widths' xmlns:height='http://example.com/heights'> <child width:size='broad' height:size='tall'/> </root> EOF doc.at_css("child").attribute_with_ns("size", "http://example.com/widths") # => #(Attr:0x550 { # name = "size", # namespace = #(Namespace:0x564 { # prefix = "width", # href = "http://example.com/widths" # }), # value = "broad" # }) doc.at_css("child").attribute_with_ns("size", "http://example.com/heights") # => #(Attr:0x578 { # name = "size", # namespace = #(Namespace:0x58c { # prefix = "height", # href = "http://example.com/heights" # }), # value = "tall" # })
# File lib/nokogiri/xml/node.rb, line 515 def attributes attribute_nodes.each_with_object({}) do |node, hash| hash[node.node_name] = node end end
Fetch this node’s attributes.
⚠ Because the keys do not include any namespace information for the attribute, in case of a simple name collision, not all attributes will be returned. In this case, you will need to use #attribute_nodes
.
Hash containing attributes belonging to self
. The hash keys are String attribute names (without the namespace), and the hash values are Nokogiri::XML::Attr
.
Example with no namespaces:
doc = Nokogiri::XML("<root><child size='large' class='big wide tall'/></root>") doc.at_css("child").attributes # => {"size"=>#(Attr:0x550 { name = "size", value = "large" }), # "class"=>#(Attr:0x564 { name = "class", value = "big wide tall" })}
Example with a namespace:
doc = Nokogiri::XML("<root xmlns:desc='http://example.com/sizes'><child desc:size='large'/></root>") doc.at_css("child").attributes # => {"size"=> # #(Attr:0x550 { # name = "size", # namespace = #(Namespace:0x564 { # prefix = "desc", # href = "http://example.com/sizes" # }), # value = "large" # })}
Example with an attribute name collision:
⚠ Note that only one of the attributes is returned in the Hash.
doc = Nokogiri::XML(<<~EOF) <root xmlns:width='http://example.com/widths' xmlns:height='http://example.com/heights'> <child width:size='broad' height:size='tall'/> </root> EOF doc.at_css("child").attributes # => {"size"=> # #(Attr:0x550 { # name = "size", # namespace = #(Namespace:0x564 { # prefix = "height", # href = "http://example.com/heights" # }), # value = "tall" # })}
# File lib/nokogiri/xml/node.rb, line 575 def classes kwattr_values("class") end
Fetch CSS
class names of a Node
.
This is a convenience function and is equivalent to:
node.kwattr_values("class")
See related: #kwattr_values
, #add_class
, #append_class
, #remove_class
The CSS
classes (Array of String) present in the Node’s “class” attribute. If the attribute is empty or non-existent, the return value is an empty array.
Example
node # => <div class="section title header"></div> node.classes # => ["section", "title", "header"]
# File lib/nokogiri/xml/node.rb, line 541 def each attribute_nodes.each do |node| yield [node.node_name, node.value] end end
Iterate over each attribute name and value pair for this Node
.
# File lib/nokogiri/xml/node.rb, line 535 def keys attribute_nodes.map(&:node_name) end
Get the attribute names for this Node
.
# File lib/nokogiri/xml/node.rb, line 798 def kwattr_add(attribute_name, keywords) keywords = keywordify(keywords) current_kws = kwattr_values(attribute_name) new_kws = (current_kws + (keywords - current_kws)).join(" ") set_attribute(attribute_name, new_kws) self end
Ensure that values are present in a keyword attribute.
Any values in keywords
that already exist in the Node’s attribute values are not added. Note that any existing duplicates in the attribute values are not removed. Compare with #kwattr_append
.
A “keyword attribute” is a node attribute that contains a set of space-delimited values. Perhaps the most familiar example of this is the HTML
“class” attribute used to contain CSS
classes. But other keyword attributes exist, for instance the “rel” attribute.
See also #add_class
, #kwattr_values
, #kwattr_append
, #kwattr_remove
attribute_name
(String) The name of the keyword attribute to be modified.
keywords
(String, Array<String>) Keywords to be added to the attribute named attribute_name
. May be a string containing whitespace-delimited values, or an Array of String values. Any values already present will not be added. Any values not present will be added. If the named attribute does not exist, it is created.
self
(Nokogiri::XML::Node
) for ease of chaining method calls.
Example: Ensure that a Node
has “nofollow” in its rel
attribute.
Note that duplicates are not added.
node # => <a></a> node.kwattr_add("rel", "nofollow") # => <a rel="nofollow"></a> node.kwattr_add("rel", "nofollow") # => <a rel="nofollow"></a>
Example: Ensure that a Node
has “nofollow” and “noreferrer” in its rel
attribute, via a String argument.
Note that "nofollow" is not added because it is already present. Note also that the pre-existing duplicate "nofollow" is not removed. node # => <a rel="nofollow nofollow"></a> node.kwattr_add("rel", "nofollow noreferrer") # => <a rel="nofollow nofollow noreferrer"></a>
Example: Ensure that a Node
has “nofollow” and “noreferrer” in its rel
attribute, via an Array argument.
node # => <a></a> node.kwattr_add("rel", ["nofollow", "noreferrer"]) # => <a rel="nofollow noreferrer"></a>
Since v1.11.0
# File lib/nokogiri/xml/node.rb, line 851 def kwattr_append(attribute_name, keywords) keywords = keywordify(keywords) current_kws = kwattr_values(attribute_name) new_kws = (current_kws + keywords).join(" ") set_attribute(attribute_name, new_kws) self end
Add keywords to a Node’s keyword attribute, regardless of duplication. Compare with #kwattr_add
.
A “keyword attribute” is a node attribute that contains a set of space-delimited values. Perhaps the most familiar example of this is the HTML
“class” attribute used to contain CSS
classes. But other keyword attributes exist, for instance the “rel” attribute.
See also #append_class
, #kwattr_values
, #kwattr_add
, #kwattr_remove
attribute_name
(String) The name of the keyword attribute to be modified.
keywords
(String, Array<String>) Keywords to be added to the attribute named attribute_name
. May be a string containing whitespace-delimited values, or an Array of String values. All values passed in will be appended to the named attribute even if they are already present in the attribute. If the named attribute does not exist, it is created.
self
(Node
) for ease of chaining method calls.
Example: Append “nofollow” to the rel
attribute.
Note that duplicates are added.
node # => <a></a> node.kwattr_append("rel", "nofollow") # => <a rel="nofollow"></a> node.kwattr_append("rel", "nofollow") # => <a rel="nofollow nofollow"></a>
Example: Append “nofollow” and “noreferrer” to the rel
attribute, via a String argument.
Note that “nofollow” is appended even though it is already present.
node # => <a rel="nofollow"></a> node.kwattr_append("rel", "nofollow noreferrer") # => <a rel="nofollow nofollow noreferrer"></a>
Example: Append “nofollow” and “noreferrer” to the rel
attribute, via an Array argument.
node # => <a></a> node.kwattr_append("rel", ["nofollow", "noreferrer"]) # => <a rel="nofollow noreferrer"></a>
Since v1.11.0
# File lib/nokogiri/xml/node.rb, line 894 def kwattr_remove(attribute_name, keywords) if keywords.nil? remove_attribute(attribute_name) return self end keywords = keywordify(keywords) current_kws = kwattr_values(attribute_name) new_kws = current_kws - keywords if new_kws.empty? remove_attribute(attribute_name) else set_attribute(attribute_name, new_kws.join(" ")) end self end
Remove keywords from a keyword attribute. Any matching keywords that exist in the named attribute are removed, including any multiple entries.
If no keywords remain after this operation, or if keywords
is nil
, the attribute is deleted from the node.
A “keyword attribute” is a node attribute that contains a set of space-delimited values. Perhaps the most familiar example of this is the HTML
“class” attribute used to contain CSS
classes. But other keyword attributes exist, for instance the “rel” attribute.
See also #remove_class
, #kwattr_values
, #kwattr_add
, #kwattr_append
attribute_name
(String) The name of the keyword attribute to be modified.
keywords
(String, Array<String>) Keywords to be removed from the attribute named attribute_name
. May be a string containing whitespace-delimited values, or an Array of String values. Any keywords present in the named attribute will be removed. If no keywords remain, or if keywords
is nil, the attribute is deleted.
self
(Node
) for ease of chaining method calls.
Example:
Note that the rel
attribute is deleted when empty.
node # => <a rel="nofollow noreferrer">link</a> node.kwattr_remove("rel", "nofollow") # => <a rel="noreferrer">link</a> node.kwattr_remove("rel", "noreferrer") # => <a>link</a>
Since v1.11.0
# File lib/nokogiri/xml/node.rb, line 744 def kwattr_values(attribute_name) keywordify(get_attribute(attribute_name) || []) end
Fetch values from a keyword attribute of a Node
.
A “keyword attribute” is a node attribute that contains a set of space-delimited values. Perhaps the most familiar example of this is the HTML
“class” attribute used to contain CSS
classes. But other keyword attributes exist, for instance the “rel” attribute.
See also #classes
, #kwattr_add
, #kwattr_append
, #kwattr_remove
attribute_name
(String) The name of the keyword attribute to be inspected.
(Array<String>) The values present in the Node’s attribute_name
attribute. If the attribute is empty or non-existent, the return value is an empty array.
Example:
node # => <a rel="nofollow noopener external">link</a> node.kwattr_values("rel") # => ["nofollow", "noopener", "external"]
Since v1.11.0
# File lib/nokogiri/xml/node.rb, line 549 def remove_attribute(name) attr = attributes[name].remove if key?(name) clear_xpath_context if Nokogiri.jruby? attr end
Remove the attribute named name
# File lib/nokogiri/xml/node.rb, line 715 def remove_class(names = nil) kwattr_remove("class", names) end
Remove HTML
CSS
classes from this node. Any CSS
class names in css_classes
that exist in this node’s “class” attribute are removed, including any multiple entries.
If no CSS
classes remain after this operation, or if css_classes
is nil
, the “class” attribute is deleted from the node.
This is a convenience function and is equivalent to:
node.kwattr_remove("class", css_classes)
Also see #kwattr_remove
, #classes
, #add_class
, #append_class
css_classes
(String, Array<String>)
CSS
class names to be removed from the Node’s “class” attribute. May be a string containing whitespace-delimited names, or an Array of String names. Any class names already present will be removed. If no CSS
classes remain, the “class” attribute is deleted.
self
(Nokogiri::XML::Node
) for ease of chaining method calls.
Example: Deleting a CSS
class
Note that all instances of the class “section” are removed from the “class” attribute.
node # => <div class="section header section"></div> node.remove_class("section") # => <div class="header"></div>
Example: Deleting the only remaining CSS
class
Note that the attribute is removed once there are no remaining classes.
node # => <div class="section"></div> node.remove_class("section") # => <div></div>
Example: Deleting multiple CSS
classes
Note that the “class” attribute is deleted once it’s empty.
node # => <div class="section header float"></div> node.remove_class(["section", "float"]) # => <div class="header"></div>
# File lib/nokogiri/xml/node.rb, line 529 def value?(value) values.include?(value) end
Does this Node’s attributes include <value>
# File lib/nokogiri/xml/node.rb, line 523 def values attribute_nodes.map(&:value) end
Get the attribute values for this Node
.
© 2008–2018 Aaron Patterson, Mike Dalessio, Charles Nutter, Sergio Arbeo,
Patrick Mahoney, Yoko Harada, Akinori MUSHA, John Shahid, Lars Kanis
Licensed under the MIT License.
https://nokogiri.org/rdoc/Nokogiri/XML/Node.html