W3cubDocs

class Nokogiri::XML::Node

Parent:: Object
Included modules:: Nokogiri::XML::PP::Node, Nokogiri::XML::Searchable

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 #[] and Nokogiri::XML#[]= for more information.

Nokogiri::XML::Node also has methods that let you move around your tree. For navigating your tree, see:

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: emit plaintext

These methods will all emit the plaintext version of your document, 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: emit well-formed markup

These methods will all emit properly-escaped markup, meaning that it's suitable for consumption by browsers, parsers, etc.

You may search this node's subtree using Nokogiri::XML::Searchable#xpath and Nokogiri::XML::Searchable#css

Constants

ATTRIBUTE_DECL: Attribute declaration type
ATTRIBUTE_NODE: Attribute node type
CDATA_SECTION_NODE: CDATA node type, see #cdata?
COMMENT_NODE: Comment node type, see #comment?
DOCB_DOCUMENT_NODE: DOCB document node type
DOCUMENT_FRAG_NODE: Document fragment node type
DOCUMENT_NODE: Document node type, see #xml?
DOCUMENT_TYPE_NODE: Document type node type
DTD_NODE: DTD node type
ELEMENT_DECL: Element declaration type
ELEMENT_NODE: Element node type, see #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, see #html?
NAMESPACE_DECL: Namespace declaration type
NOTATION_NODE: Notation node type
PI_NODE: PI node type
TEXT_NODE: Text node type, see #text?
XINCLUDE_END: XInclude end type
XINCLUDE_START: XInclude start type

Public Class Methods

new(name, document) Show source

static VALUE new(int argc, VALUE *argv, VALUE klass)
{
  xmlDocPtr doc;
  xmlNodePtr node;
  VALUE name;
  VALUE document;
  VALUE rest;
  VALUE rb_node;

  rb_scan_args(argc, argv, "2*", &name, &document, &rest);

  Data_Get_Struct(document, xmlDoc, doc);

  node = xmlNewNode(NULL, (xmlChar *)StringValueCStr(name));
  node->doc = doc->doc;
  nokogiri_root_node(node);

  rb_node = Nokogiri_wrap_xml_node(
              klass == cNokogiriXmlNode ? (VALUE)NULL : klass,
              node
            );
  rb_obj_call_init(rb_node, argc, argv);

  if(rb_block_given_p()) { rb_yield(rb_node); }

  return rb_node;
}

Create a new node with name sharing GC lifecycle with document

Public Instance Methods

<<(node_or_tags) Show source

# File lib/nokogiri/xml/node.rb, line 183
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.

<=>(other) Show source

# File lib/nokogiri/xml/node.rb, line 800
def <=> other
  return nil unless other.is_a?(Nokogiri::XML::Node)
  return nil unless document == other.document
  compare other
end

Compare two Node objects with respect to their Document. Nodes from different documents cannot be compared.

==(other) Show source

# File lib/nokogiri/xml/node.rb, line 667
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

>(selector) Show source

# File lib/nokogiri/xml/node.rb, line 113
def > selector
  ns = document.root.namespaces
  xpath CSS.xpath_for(selector, :prefix => "./", :ns => ns).first
end

Search this node's immediate children using CSS selector selector

[](name) Show source

# File lib/nokogiri/xml/node.rb, line 120
def [] name
  get(name.to_s)
end

Get the attribute value for the attribute name

Also aliased as: get_attribute, attr

[]=(name, value) Show source

# File lib/nokogiri/xml/node.rb, line 126
def []= name, value
  set name.to_s, value.to_s
end

Set the attribute value for the attribute name to value

Also aliased as: set_attribute

accept(visitor) Show source

# File lib/nokogiri/xml/node.rb, line 661
def accept visitor
  visitor.visit(self)
end

Accept a visitor. This method calls “visit” on visitor with self.

add_child(node_or_tags) Show source

# File lib/nokogiri/xml/node.rb, line 137
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 +<<+.

add_class(name) Show source

# File lib/nokogiri/xml/node.rb, line 380
def add_class name
  names = classes
  self['class'] = (names + (name.scan(/\S+/) - names)).join(' ')
  self
end

Add name to the “class” attribute value of this Node and return self. If the value is already in the current value, it is not added. If no “class” attribute exists yet, one is created with the given value.

More than one class may be added at a time, separated by a space.

add_namespace(p1, p2)

Alias for: add_namespace_definition

add_namespace_definition(prefix, href) Show source

static VALUE add_namespace_definition(VALUE self, VALUE prefix, VALUE href)
{
  xmlNodePtr node, namespace;
  xmlNsPtr ns;

  Data_Get_Struct(self, xmlNode, node);
  namespace = node ;

  ns = xmlSearchNs(
         node->doc,
         node,
         (const xmlChar *)(NIL_P(prefix) ? NULL : StringValueCStr(prefix))
       );

  if(!ns) {
    if (node->type != XML_ELEMENT_NODE) {
      namespace = node->parent;
    }
    ns = xmlNewNs(
           namespace,
           (const xmlChar *)StringValueCStr(href),
           (const xmlChar *)(NIL_P(prefix) ? NULL : StringValueCStr(prefix))
         );
  }

  if (!ns) { return Qnil ; }

  if(NIL_P(prefix) || node != namespace) { xmlSetNs(node, ns); }

  return Nokogiri_wrap_xml_namespace(node->doc, ns);
}

Adds a namespace definition with prefix using href value. The result is as if parsed XML for this node had included an attribute 'xmlns:prefix=value'. A default namespace for this node (“xmlns=”) can be added by passing 'nil' for prefix. Namespaces added this way will not show up in attributes, but they will be included as an xmlns attribute when the node is serialized to XML.

Also aliased as: add_namespace

add_next_sibling(node_or_tags) Show source

# File lib/nokogiri/xml/node.rb, line 208
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.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.

add_previous_sibling(node_or_tags) Show source

# File lib/nokogiri/xml/node.rb, line 195
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.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.

Also aliased as: previous=

after(node_or_tags) Show source

# File lib/nokogiri/xml/node.rb, line 233
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.

ancestors(selector = nil) Show source

# File lib/nokogiri/xml/node.rb, line 601
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 { |parent|
    search_results.include?(parent)
  })
end

Get a list of ancestor Node for this Node. If selector is given, the ancestors must match selector

append_class(name) Show source

# File lib/nokogiri/xml/node.rb, line 394
def append_class name
  self['class'] = (classes + name.scan(/\S+/)).join(' ')
  self
end

Append name to the “class” attribute value of this Node and return self. The value is simply appended without checking if it is already in the current value. If no “class” attribute exists yet, one is created with the given value.

More than one class may be appended at a time, separated by a space.

attr(name)

Alias for: []

attribute(name) Show source

static VALUE attr(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 Nokogiri_wrap_xml_node(Qnil, (xmlNodePtr)prop);
}

Get the attribute node with name

attribute_nodes() Show source

static VALUE attribute_nodes(VALUE self)
{
  /* this code in the mode of xmlHasProp() */
  xmlNodePtr node;
  VALUE attr;

  Data_Get_Struct(self, xmlNode, node);

  attr = rb_ary_new();
  Nokogiri_xml_node_properties(node, attr);

  return attr ;
}

returns a list containing the Node attributes.

attribute_with_ns(name, namespace) Show source

static VALUE 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 Nokogiri_wrap_xml_node(Qnil, (xmlNodePtr)prop);
}

Get the attribute node with name and namespace

attributes() Show source

# File lib/nokogiri/xml/node.rb, line 339
def attributes
  Hash[attribute_nodes.map { |node|
    [node.node_name, node]
  }]
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.

before(node_or_tags) Show source

# File lib/nokogiri/xml/node.rb, line 221
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.

blank? Show source

static VALUE blank_eh(VALUE self)
{
  xmlNodePtr node;
  Data_Get_Struct(self, xmlNode, node);
  return (1 == xmlIsBlankNode(node)) ? Qtrue : Qfalse ;
}

Is this node blank?

canonicalize(mode=XML::XML_C14N_1_0,inclusive_namespaces=nil,with_comments=false) Show source

# File lib/nokogiri/xml/node.rb, line 820
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

cdata?() Show source

# File lib/nokogiri/xml/node.rb, line 524
def cdata?
  type == CDATA_SECTION_NODE
end

Returns true if this is a CDATA

child Show source

static VALUE child(VALUE self)
{
  xmlNodePtr node, child;
  Data_Get_Struct(self, xmlNode, node);

  child = node->children;
  if(!child) { return Qnil; }

  return Nokogiri_wrap_xml_node(Qnil, child);
}

Returns the child node

children Show source

static VALUE 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 Nokogiri_wrap_xml_node_set(set, document); }

  child = child->next;
  while(NULL != child) {
    xmlXPathNodeSetAddUnique(set, child);
    child = child->next;
  }

  node_set = Nokogiri_wrap_xml_node_set(set, document);

  return node_set;
}

Get the list of children for this node as a NodeSet

children=(node_or_tags) Show source

# File lib/nokogiri/xml/node.rb, line 257
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

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=

classes() Show source

# File lib/nokogiri/xml/node.rb, line 368
def classes
  self['class'].to_s.scan(/\S+/)
end

Get the list of class names of this Node, without deduplication or sorting.

clone(p1 = v1, p2 = v2)

Alias for: dup

comment?() Show source

# File lib/nokogiri/xml/node.rb, line 519
def comment?
  type == COMMENT_NODE
end

Returns true if this is a Comment

content Show source

static VALUE get_native_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;
}

Returns the content for this Node

Also aliased as: text, inner_text

content=(string) Show source

# File lib/nokogiri/xml/node.rb, line 486
def content= string
  self.native_content = encode_special_chars(string.to_s)
end

Set the Node's content to a Text node containing string. The string gets XML escaped, not interpreted as markup.

create_external_subset(name, external_id, system_id) Show source

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 Nokogiri_wrap_xml_node(Qnil, (xmlNodePtr)dtd);
}

Create an external subset

create_internal_subset(name, external_id, system_id) Show source

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 Nokogiri_wrap_xml_node(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">

css_path() Show source

# File lib/nokogiri/xml/node.rb, line 592
def css_path
  path.split(/\//).map { |part|
    part.length == 0 ? nil : part.gsub(/\[(\d+)\]/, ':nth-of-type(\1)')
  }.compact.join(' > ')
end

Get the path to this node as a CSS expression

decorate!() Show source

# File lib/nokogiri/xml/node.rb, line 107
def decorate!
  document.decorate(self)
end

Decorate this node with the decorators set up in this node's Document

default_namespace=(url) Show source

# File lib/nokogiri/xml/node.rb, line 628
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=

delete(name)

Alias for: remove_attribute

description() Show source

# File lib/nokogiri/xml/node.rb, line 561
def description
  return nil if document.xml?
  Nokogiri::HTML::ElementDescription[name]
end

Fetch the Nokogiri::HTML::ElementDescription for this node. Returns nil on XML documents and on unknown tags.

do_xinclude(options = XML::ParseOptions::DEFAULT_XML) { |options| ... } Show source

# File lib/nokogiri/xml/node.rb, line 810
def do_xinclude options = XML::ParseOptions::DEFAULT_XML, &block
  options = Nokogiri::XML::ParseOptions.new(options) if Integer === options

  # give options to user
  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.

document Show source

static VALUE document(VALUE self)
{
  xmlNodePtr node;
  Data_Get_Struct(self, xmlNode, node);
  return DOC_RUBY_OBJECT(node->doc);
}

Get the document for this Node

document?() Show source

# File lib/nokogiri/xml/node.rb, line 539
def document?
  is_a? XML::Document
end

Returns true if this is a Document

dup Show source

dup(depth)

dup(depth, new_parent_doc)

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; }

  nokogiri_root_node(dup);

  return Nokogiri_wrap_xml_node(rb_obj_class(self), dup);
}

Copy this node. An optional depth may be passed in. 0 is a shallow copy, 1 (the default) is a deep copy. An optional new_parent_doc may also be passed in, which will be the new node's parent document. Defaults to the current node's document. current document.

Also aliased as: clone

each() { |node_name, value| ... } Show source

# File lib/nokogiri/xml/node.rb, line 359
def each
  attribute_nodes.each { |node|
    yield [node.node_name, node.value]
  }
end

Iterate over each attribute name and value pair for this Node.

elem?()

Alias for: element?

element?() Show source

# File lib/nokogiri/xml/node.rb, line 574
def element?
  type == ELEMENT_NODE
end

Returns true if this is an Element node

Also aliased as: elem?

element_children Show source

static VALUE 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 Nokogiri_wrap_xml_node_set(set, document); }

  child = xmlNextElementSibling(child);
  while(NULL != child) {
    xmlXPathNodeSetAddUnique(set, child);
    child = xmlNextElementSibling(child);
  }

  node_set = Nokogiri_wrap_xml_node_set(set, document);

  return node_set;
}

Get the list of children for this node as a NodeSet. All nodes will be element nodes.

Example:

@doc.root.element_children.all? { |x| x.element? } # => true

Also aliased as: elements

elements()

Alias for: element_children

encode_special_chars(string) Show source

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

external_subset Show source

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 Nokogiri_wrap_xml_node(Qnil, (xmlNodePtr)dtd);
}

Get the external subset

first_element_child Show source

static VALUE first_element_child(VALUE self)
{
  xmlNodePtr node, child;
  Data_Get_Struct(self, xmlNode, node);

  child = xmlFirstElementChild(node);
  if(!child) { return Qnil; }

  return Nokogiri_wrap_xml_node(Qnil, child);
}

Returns the first child node of this node that is an element.

Example:

@doc.root.first_element_child.element? # => true

fragment(tags) Show source

# File lib/nokogiri/xml/node.rb, line 441
def fragment tags
  type = document.html? ? Nokogiri::HTML : Nokogiri::XML
  type::DocumentFragment.new(document, tags, self)
end

Create a DocumentFragment containing tags that is relative to this context node.

fragment?() Show source

# File lib/nokogiri/xml/node.rb, line 554
def fragment?
  type == DOCUMENT_FRAG_NODE
end

Returns true if this is a DocumentFragment

get_attribute(name)

Alias for: []

has_attribute?(p1)

Alias for: key?

html?() Show source

# File lib/nokogiri/xml/node.rb, line 534
def html?
  type == HTML_DOCUMENT_NODE
end

Returns true if this is an HTML::Document node

inner_html(*args) Show source

# File lib/nokogiri/xml/node.rb, line 587
def inner_html *args
  children.map { |x| x.to_html(*args) }.join
end

Get the #inner_html for this node's #children

inner_html=(node_or_tags) Show source

# File lib/nokogiri/xml/node.rb, line 245
def inner_html= node_or_tags
  self.children = node_or_tags
  self
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=

inner_text()

Alias for: content

internal_subset Show source

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 Nokogiri_wrap_xml_node(Qnil, (xmlNodePtr)dtd);
}

Get the internal subset

key?(attribute) Show source

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

Also aliased as: has_attribute?

keys() Show source

# File lib/nokogiri/xml/node.rb, line 353
def keys
  attribute_nodes.map(&:node_name)
end

Get the attribute names for this Node.

lang Show source

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.

lang= Show source

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.

last_element_child Show source

static VALUE last_element_child(VALUE self)
{
  xmlNodePtr node, child;
  Data_Get_Struct(self, xmlNode, node);

  child = xmlLastElementChild(node);
  if(!child) { return Qnil; }

  return Nokogiri_wrap_xml_node(Qnil, child);
}

Returns the last child node of this node that is an element.

Example:

@doc.root.last_element_child.element? # => true

line Show source

static VALUE line(VALUE self)
{
  xmlNodePtr node;
  Data_Get_Struct(self, xmlNode, node);

  return INT2NUM(xmlGetLineNo(node));
}

Returns the line for this Node

matches?(selector) Show source

# File lib/nokogiri/xml/node.rb, line 434
def matches? selector
  ancestors.last.search(selector).include?(self)
end

Returns true if this Node matches selector

name()

Alias for: node_name

name=(p1)

Alias for: node_name=

namespace() Show source

static VALUE namespace(VALUE self)
{
xmlNodePtr node ;
Data_Get_Struct(self, xmlNode, node);

if (node->ns) {
  return Nokogiri_wrap_xml_namespace(node->doc, node->ns);
}

returns the namespace of the element or attribute node as a Namespace object, or nil if there is no namespace for the element or attribute.

namespace=(ns) Show source

# File lib/nokogiri/xml/node.rb, line 639
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.

namespace_definitions() Show source

static VALUE namespace_definitions(VALUE self)
{
  /* this code in the mode of xmlHasProp() */
  xmlNodePtr node ;
  VALUE list;
  xmlNsPtr ns;

  Data_Get_Struct(self, xmlNode, node);

  list = rb_ary_new();

  ns = node->nsDef;

  if(!ns) { return list; }

  while(NULL != ns) {
    rb_ary_push(list, Nokogiri_wrap_xml_namespace(node->doc, ns));
    ns = ns->next;
  }

  return list;
}

returns namespaces defined on self element directly, as an array of Namespace objects. Includes both a default namespace (as in“xmlns=”), and prefixed namespaces (as in “xmlns:prefix=”).

namespace_scopes() Show source

static VALUE namespace_scopes(VALUE self)
{
  xmlNodePtr node ;
  VALUE list;
  xmlNsPtr *ns_list;
  int j;

  Data_Get_Struct(self, xmlNode, node);

  list = rb_ary_new();
  ns_list = xmlGetNsList(node->doc, node);

  if(!ns_list) { return list; }

  for (j = 0 ; ns_list[j] != NULL ; ++j) {
    rb_ary_push(list, Nokogiri_wrap_xml_namespace(node->doc, ns_list[j]));
  }

  xmlFree(ns_list);
  return list;
}

returns namespaces in scope for self – those defined on self element directly or any ancestor node – as an array of Namespace objects. Default namespaces (“xmlns=” style) for self are included in this array; Default namespaces for ancestors, however, are not. See also namespaces

namespaced_key?(attribute, namespace) Show source

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

namespaces() Show source

# File lib/nokogiri/xml/node.rb, line 511
def namespaces
  Hash[namespace_scopes.map { |nd|
    key = ['xmlns', nd.prefix].compact.join(':')
    [key, nd.href]
  }]
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.

content= Show source

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) ;
    nokogiri_root_node(child);
    child = next ;
  }

  xmlNodeSetContent(node, (xmlChar *)StringValueCStr(content));
  return content;
}

Set the content for this Node

next()

Alias for: next_sibling

next_element Show source

static VALUE next_element(VALUE self)
{
  xmlNodePtr node, sibling;
  Data_Get_Struct(self, xmlNode, node);

  sibling = xmlNextElementSibling(node);
  if(!sibling) { return Qnil; }

  return Nokogiri_wrap_xml_node(Qnil, sibling);
}

Returns the next Nokogiri::XML::Element type sibling node.

next_sibling Show source

static VALUE next_sibling(VALUE self)
{
  xmlNodePtr node, sibling;
  Data_Get_Struct(self, xmlNode, node);

  sibling = node->next;
  if(!sibling) { return Qnil; }

  return Nokogiri_wrap_xml_node(Qnil, sibling) ;
}

Returns the next sibling node

Also aliased as: next

name Show source

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

Also aliased as: name

name=(new_name) Show source

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

Also aliased as: name=

node_type Show source

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

Also aliased as: type

parent Show source

static VALUE get_parent(VALUE self)
{
  xmlNodePtr node, parent;
  Data_Get_Struct(self, xmlNode, node);

  parent = node->parent;
  if(!parent) { return Qnil; }

  return Nokogiri_wrap_xml_node(Qnil, parent) ;
}

Get the parent Node for this Node

parent=(parent_node) Show source

# File lib/nokogiri/xml/node.rb, line 492
def parent= parent_node
  parent_node.add_child(self)
  parent_node
end

Set the parent Node for this Node

parse(string_or_io, options = nil) { |options| ... } Show source

# File lib/nokogiri/xml/node.rb, line 450
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 Integer === 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

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.

path Show source

static VALUE path(VALUE self)
{
  xmlNodePtr node;
  xmlChar *path ;
  VALUE rval;

  Data_Get_Struct(self, xmlNode, node);

  path = xmlGetNodePath(node);
  rval = NOKOGIRI_STR_NEW2(path);
  xmlFree(path);
  return rval ;
}

Returns the path associated with this Node

pointer_id Show source

static VALUE pointer_id(VALUE self)
{
  xmlNodePtr node;
  Data_Get_Struct(self, xmlNode, node);

  return INT2NUM((long)(node));
}

Get the internal pointer number

prepend_child(node_or_tags) Show source

# File lib/nokogiri/xml/node.rb, line 154
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.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.

previous()

Alias for: previous_sibling

previous=(node_or_tags)

Alias for: add_previous_sibling

previous_element Show source

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 ? Nokogiri_wrap_xml_node(Qnil, sibling) : Qnil ;
}

Returns the previous Nokogiri::XML::Element type sibling node.

previous_sibling Show source

static VALUE previous_sibling(VALUE self)
{
  xmlNodePtr node, sibling;
  Data_Get_Struct(self, xmlNode, node);

  sibling = node->prev;
  if(!sibling) { return Qnil; }

  return Nokogiri_wrap_xml_node(Qnil, sibling);
}

Returns the previous sibling node

Also aliased as: previous

processing_instruction?() Show source

# File lib/nokogiri/xml/node.rb, line 544
def processing_instruction?
  type == PI_NODE
end

Returns true if this is a ProcessingInstruction node

read_only?() Show source

# File lib/nokogiri/xml/node.rb, line 568
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?

remove()

Alias for: unlink

remove_attribute(name) Show source

# File lib/nokogiri/xml/node.rb, line 425
def remove_attribute name
  attr = attributes[name].remove if key? name
  clear_xpath_context if Nokogiri.jruby?
  attr
end

Remove the attribute named name

Also aliased as: delete

remove_class(name = nil) Show source

# File lib/nokogiri/xml/node.rb, line 409
def remove_class name = nil
  if name
    names = classes - name.scan(/\S+/)
    if names.empty?
      delete 'class'
    else
      self['class'] = names.join(' ')
    end
  else
    delete "class"
  end
  self
end

Remove name from the “class” attribute value of this Node and return self. If there are many occurrences of the name, they are all removed.

More than one class may be removed at a time, separated by a space.

If no class name is left after removal, or when name is nil, the “class” attribute is removed from this Node.

replace(node_or_tags) Show source

# File lib/nokogiri/xml/node.rb, line 275
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

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.

serialize(*args, &block) Show source

# File lib/nokogiri/xml/node.rb, line 687
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 = String.new
  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)

node.serialize(:encoding => 'UTF-8') do |config|
  config.format.as_xml
end

set_attribute(name, value)

Alias for: []=

swap(node_or_tags) Show source

# File lib/nokogiri/xml/node.rb, line 305
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.

text()

Also aliased as: to_str

Alias for: content

text?() Show source

# File lib/nokogiri/xml/node.rb, line 549
def text?
  type == TEXT_NODE
end

Returns true if this is a Text node

to_html(options = {}) Show source

# File lib/nokogiri/xml/node.rb, line 710
def to_html options = {}
  to_format SaveOptions::DEFAULT_HTML, options
end

Serialize this Node to HTML

doc.to_html

See #write_to for a list of options. For formatted output, use #to_xhtml instead.

to_s() Show source

# File lib/nokogiri/xml/node.rb, line 582
def to_s
  document.xml? ? to_xml : to_html
end

Turn this node in to a string. If the document is HTML, this method returns html. If the document is XML, this method returns XML.

to_str()

Alias for: text

to_xhtml(options = {}) Show source

# File lib/nokogiri/xml/node.rb, line 731
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 #write_to for a list of options

to_xml(options = {}) Show source

# File lib/nokogiri/xml/node.rb, line 720
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 #write_to for a list of options

traverse(&block) Show source

# File lib/nokogiri/xml/node.rb, line 654
def traverse &block
  children.each{|j| j.traverse(&block) }
  block.call(self)
end

Yields self and all children to block recursively.

type()

Alias for: node_type

unlink Show source

static VALUE unlink_node(VALUE self)
{
  xmlNodePtr node;
  Data_Get_Struct(self, xmlNode, node);
  xmlUnlinkNode(node);
  nokogiri_root_node(node);
  return self;
}

Unlink this node from its current context.

Also aliased as: remove

values() Show source

# File lib/nokogiri/xml/node.rb, line 347
def values
  attribute_nodes.map(&:value)
end

Get the attribute values for this Node.

wrap(html) Show source

# File lib/nokogiri/xml/node.rb, line 169
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

write_html_to(io, options = {}) Show source

# File lib/nokogiri/xml/node.rb, line 774
def write_html_to io, options = {}
  write_format_to SaveOptions::DEFAULT_HTML, io, options
end

Write Node as HTML to io with options

See #write_to for a list of options

write_to(io, *options) { |config| ... } Show source

# File lib/nokogiri/xml/node.rb, line 752
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 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)

write_xhtml_to(io, options = {}) Show source

# File lib/nokogiri/xml/node.rb, line 782
def write_xhtml_to io, options = {}
  write_format_to SaveOptions::DEFAULT_XHTML, io, options
end

Write Node as XHTML to io with options

See #write_to for a list of options

write_xml_to(io, options = {}) Show source

# File lib/nokogiri/xml/node.rb, line 792
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 #write_to for a list of options

xml?() Show source

# File lib/nokogiri/xml/node.rb, line 529
def xml?
  type == DOCUMENT_NODE
end

Returns true if this is an XML::Document 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.