Class: Nokogiri::HTML5::Document

Relationships & Source Files
Super Chains via Extension / Inclusion / Inheritance
Class Chain: self, `::Nokogiri::HTML4::Document`, `::Nokogiri::XML::Document`, `::Nokogiri::XML::Node`
Instance Chain: self, `::Nokogiri::HTML4::Document`, `::Nokogiri::XML::Document`, `::Nokogiri::XML::Node`, Enumerable, `::Nokogiri::ClassResolver`, `::Nokogiri::XML::Searchable`, `::Nokogiri::XML::PP::Node`
Inherits:	Nokogiri::HTML4::Document `::Object` Nokogiri::XML::Node Nokogiri::XML::Document Nokogiri::HTML4::Document Nokogiri::HTML5::Document
Defined in:	lib/nokogiri/html5/document.rb

Overview

Since v1.12.0

💡 ::Nokogiri::HTML5 functionality is not available when running JRuby.

Constant Summary

Class Method Summary

.parse(input) { |options| ... } → HTML5::Document)

Parse HTML input with a parser compliant with the ::Nokogiri::HTML5 spec.
.read_io(io, url_ = nil, encoding_ = nil, url: url_, encoding: encoding_, **options)

Create a new document from an IO object.
.read_memory(string, url_ = nil, encoding_ = nil, url: url_, encoding: encoding_, **options)

Create a new document from a String.
.do_parse(string_or_io, url, encoding, **options) private
.new(*args) ⇒ Document constructor Internal use only

`::Nokogiri::HTML4::Document` - Inherited

.new	Create a new empty document with base URI `uri` and external ID `external_id`.
.parse	Parse HTML4 input from a String or IO object, and return a new `::Nokogiri::HTML4::Document`.
.read_io	Read the `::Nokogiri::HTML` document from `io` with given #url, `encoding`, and `options`.
.read_memory	Read the `::Nokogiri::HTML` document contained in `string` with given #url, `encoding`, and `options`.

`::Nokogiri::XML::Document` - Inherited

.new	Alias for XML::Comment.new.
.parse	Parse XML input from a String or IO object, and return a new `::Nokogiri::XML::Document`.
.read_io	Create a new document from an IO object.
.read_memory	Create a new document from a String.
.wrap	⚠️️️ This method is only available when running JRuby.
.empty_doc?

`::Nokogiri::XML::Node` - Inherited

.new	documented in lib/nokogiri/xml/node.rb.

Instance Attribute Summary

#quirks_mode readonly

Get the parser's quirks mode value.
#url readonly

Get the url name for this document, as passed into .parse, .read_io, or .read_memory
#parse_noscript_content_as_text rw Internal use only

Whether the parser treated the content of noscript elements as text, or nil before the first parse.

`::Nokogiri::HTML4::Document` - Inherited

#meta_encoding	Get the meta tag encoding for this document.
#meta_encoding=	Set the meta tag encoding for this document.
#title	Get the title string of this document.
#title=	Set the title string of this document.

`::Nokogiri::XML::Document` - Inherited

#encoding	Get the encoding for this `Document`.
#encoding=	Set the encoding string for this `Document`.
#errors	The errors found while parsing a document.
#namespace_inheritance	When `true`, reparented elements without a namespace will inherit their new parent's namespace (if one exists).
#root	Get the root node for this document.
#root=	Set the root element on this document.

`::Nokogiri::XML::Node` - Inherited

#blank?	[Returns] `true` if the node is an empty or whitespace-only text or cdata node, else `false`.
#cdata?	Returns true if this is a CDATA.
#children	:category: Traversing Document Structure.
#children=	Set the content for this `Node` `node_or_tags`
#comment?	Returns true if this is a Comment.
#content	[Returns].
#content=	Set the content of this node to `input`.
#default_namespace=	Adds a default namespace supplied as a string #url href, to self.
#document	:category: Traversing Document Structure.
#document?	Returns true if this is a `Document`.
#elem?	Alias for XML::Node#element?.
#element?	Returns true if this is an Element node.
#fragment?	Returns true if this is a `DocumentFragment`.
#html?	Returns true if this is an `::Nokogiri::HTML4::Document` or `Document` node.
#inner_html	Get the inner_html for this node's `Node#children`
#inner_html=	Set the content for this `Node` to `node_or_tags`.
#inner_text	Alias for XML::Node#content.
#lang	Searches the language of a node, i.e.
#lang=	Set the language of a node, i.e.
#line	[Returns] The line number of this `Node`.
#line=	Sets the line for this `Node`.
#name	Alias for XML::Node#node_name.
#namespace	[Returns] The Namespace of the element or attribute node, or `nil` if there is no namespace.
#namespace=	Set the namespace of this node to the Namespace object `ns`, which must belong to this node's document.
#native_content=	Set the content of this node to `input`.
#next	Alias for XML::Node#next_sibling.
#next=	Alias for XML::Node#add_next_sibling.
#node_name	Returns the name for this `Node`.
#node_name=	Set the name for this `Node`.
#parent	Get the parent `Node` for this `Node`.
#parent=	Set the parent `Node` for this `Node`.
#previous	Alias for XML::Node#previous_sibling.
#previous=	Alias for XML::Node#add_previous_sibling.
#processing_instruction?	Returns true if this is a ProcessingInstruction node.
#read_only?	Is this a read only node?
#text	Alias for XML::Node#content.
#text?	Returns true if this is a Text node.
#to_str	Alias for XML::Node#content.
#xml?	Returns true if this is an `::Nokogiri::XML::Document` node.
#prepend_newline?, #data_ptr?

Instance Method Summary

#fragment() → Nokogiri::HTML5::DocumentFragment)

Parse a ::Nokogiri::HTML5 document fragment from markup, returning a DocumentFragment.
#xpath_doctype() → Nokogiri::CSS::XPathVisitor::DoctypeConfig)

[Returns] The document type which determines CSS-to-XPath translation.
#to_xml(options = {}, &block) Internal use only

`::Nokogiri::HTML4::Document` - Inherited

#fragment	Create a `::Nokogiri::XML::DocumentFragment` from `tags`
#serialize	Serialize Node using `options`.
#type	The type for this document.
#xpath_doctype	[Returns] The document type which determines CSS-to-XPath translation.
#meta_content_type, #set_metadata_element

`::Nokogiri::XML::Document` - Inherited

#<<	Alias for XML::Document#add_child.
#add_child,
#canonicalize	Canonicalize a document and return the results.
#clone	Clone this node.
#collect_namespaces	Recursively get all namespaces from this node and its subtree and return them as a hash.
#create_cdata	Create a CDATA Node containing `string`
#create_comment	Create a Comment Node containing `string`
#create_element	Create a new Element with `name` belonging to this document, optionally setting contents or attributes.
#create_entity	Create a new entity named `name`.
#create_text_node	Create a Text Node with `string`
#deconstruct_keys	Returns a hash describing the `Document`, to use in pattern matching.
#decorate	Apply any decorators to `node`
#decorators	Get the list of decorators given `key`
#document	A reference to `self`
#dup	Duplicate this node.
#fragment	Create a `::Nokogiri::XML::DocumentFragment` from `tags` Returns an empty fragment if `tags` is nil.
#name	The name of this document.
#namespaces	Get the hash of namespaces on the root `::Nokogiri::XML::Node`
#remove_namespaces!	Remove all namespaces from all nodes in the document.
#slop!	Explore a document with shortcut methods.
#to_java	⚠️️️ This method is only available when running JRuby.
#to_xml	Alias for XML::Node#serialize.
#url	Get the url name for this document.
#validate	Validate this `Document` against its DTD.
#version	Get the `::Nokogiri::XML` version for this `Document`.
#xpath_doctype	[Returns] The document type which determines CSS-to-XPath translation.
#inspect_attributes,
#initialize	rubocop:disable Lint/MissingSuper.

`::Nokogiri::XML::Node` - Inherited

#<<	Add `node_or_tags` as a child of this `Node`.
#<=>	Compare two `Node` objects with respect to their `Document`.
#==	`::Nokogiri::Test` to see if this `Node` is equal to `other`
#[]	Fetch an attribute from this node.
#[]=	Update the attribute `name` to `value`, or create the attribute if it does not exist.
#accept	Accept a visitor.
#add_child	Appends specified Nodes to the children of `self`; each appended `Node` has `self` as its `#parent` value, and `self.document` as its `#document` value.
#add_class	Ensure HTML `::Nokogiri::CSS` classes are present on `self`.
#add_namespace	Alias for XML::Node#add_namespace_definition.
#add_namespace_definition	:category: Manipulating Document Structure.
#add_next_sibling	Insert `node_or_tags` after this `Node` (as a sibling).
#add_previous_sibling	Insert `node_or_tags` before this `Node` (as a sibling).
#after	Insert `node_or_tags` after this node (as a sibling).
#ancestors	Get a list of ancestor `Node` for this `Node`.
#append_class	Add HTML `::Nokogiri::CSS` classes to `self`, regardless of duplication.
#attr	Alias for XML::Node#[].
#attribute	:category: Working With `Node` Attributes.
#attribute_nodes	:category: Working With `Node` Attributes.
#attribute_with_ns	:category: Working With `Node` Attributes.
#attributes	Fetch this node's attributes.
#before	Insert `node_or_tags` before this node (as a sibling).
#canonicalize,
#child	:category: Traversing Document Structure.
#classes	Fetch CSS class names of a `Node`.
#clone	Clone this node.
#create_external_subset	Create an external subset.
#create_internal_subset	Create the internal subset of a document.
#css_path	Get the path to this node as a `::Nokogiri::CSS` expression.
#deconstruct_keys	Returns a hash describing the `Node`, to use in pattern matching.
#decorate!	Decorate this node with the decorators set up in this node's `Document`.
#delete	Alias for XML::Node#remove_attribute.
#description	Fetch the `::Nokogiri::HTML4::ElementDescription` for this node.
#do_xinclude	Do XInclude substitution on the subtree below this node, replacing each with the content it references.
#dup	Duplicate this node.
#each	Iterate over each attribute name and value pair for this `Node`.
#element_children	[Returns].
#elements	Alias for XML::Node#element_children.
#encode_special_chars	Encode any special characters in `string`
#external_subset	Get the external subset.
#first_element_child	[Returns] The first child `Node` that is an element.
#fragment	Create a `DocumentFragment` containing `tags` that is relative to this context node.
#get_attribute	Alias for XML::Node#[].
#has_attribute?	Alias for XML::Node#key?.
#initialize	Create a new node with `name` that belongs to `document`.
#internal_subset	Get the internal subset.
#key?	Returns true if `attribute` is set.
#keys	Get the attribute names for this `Node`.
#kwattr_add	Ensure that values are present in a keyword attribute.
#kwattr_append	Add keywords to a Node's keyword attribute, regardless of duplication.
#kwattr_remove	Remove keywords from a keyword attribute.
#kwattr_values	Fetch values from a keyword attribute of a `Node`.
#last_element_child	[Returns] The last child `Node` that is an element.
#matches?	Returns true if this `Node` matches `selector`
#namespace_definitions	[Returns].
#namespace_scopes	[Returns] Array of all the Namespaces on this node and its ancestors.
#namespaced_key?	Returns true if `attribute` is set with `namespace`
#namespaces	Fetch all the namespaces on this node and its ancestors.
#next_element	Returns the next `::Nokogiri::XML::Element` type sibling node.
#next_sibling	Returns the next sibling node.
#node_type	Get the type for this `Node`.
#parse	Parse `string_or_io` as a document fragment within the context of this node.
#path	Returns the path associated with this `Node`.
#pointer_id	[Returns].
#prepend_child	Add `node_or_tags` as the first child of this `Node`.
#previous_element	Returns the previous `::Nokogiri::XML::Element` type sibling node.
#previous_sibling	Returns the previous sibling node.
#remove	Alias for XML::Node#unlink.
#remove_attribute	Remove the attribute named `name`
#remove_class	Remove HTML `::Nokogiri::CSS` classes from this node.
#replace	Replace this `Node` with `node_or_tags`.
#serialize	Serialize Node using `options`.
#set_attribute	Alias for XML::Node#[]=.
#swap	Swap this `Node` for `node_or_tags`
#to_html	Serialize this `Node` to `::Nokogiri::HTML`.
#to_s	Turn this node in to a string.
#to_xhtml	Serialize this `Node` to XHTML using `options`
#to_xml	Serialize this `Node` to `::Nokogiri::XML` using `options`
#traverse	Yields all children to `block` recursively, then yields self.
#type	Alias for XML::Node#node_type.
#unlink	Unlink this node from its current context.
#value?	Does this Node's attributes include .
#values	Get the attribute values for this `Node`.
#wrap	Wrap this `Node` with the node parsed from `markup` or a dup of the `node`.
#write_html_to	Write Node as `::Nokogiri::HTML` to `io` with `options`
#write_to	Serialize this node or document to `io`.
#write_xhtml_to	Write Node as XHTML to `io` with `options`
#write_xml_to	Write Node as `::Nokogiri::XML` to `io` with `options`
#add_child_node_and_reparent_attrs, #add_sibling,
#compare	Compare this `Node` to `other` with respect to their `Document`.
#dump_html	Returns the `Node` as html.
#get	Get the value for `attribute`
#html_standard_serialize,
#in_context	TODO: DOCUMENT ME.
#inspect_attributes, #keywordify,
#native_write_to	Write this `Node` to `io` with `encoding` and `options`
#process_xincludes	Loads and substitutes all xinclude elements below the node.
#set	Set the `property` to `value`
#set_namespace	Set the namespace to `namespace`
#to_format, #write_format_to, #add_child_node, #add_next_sibling_node, #add_previous_sibling_node, #replace_node

`::Nokogiri::ClassResolver` - Included

#related_class

Find a class constant within the.

`::Nokogiri::XML::Searchable` - Included

#%	Alias for XML::Searchable#at.
#/	Alias for XML::Searchable#search.
#>	Search this node's immediate children using `::Nokogiri::CSS` selector `selector`
#at	Search this object for `paths`, and return only the first result.
#at_css	Search this object for `::Nokogiri::CSS` `rules`, and return only the first match.
#at_xpath	Search this node for XPath `paths`, and return only the first match.
#css	Search this object for `::Nokogiri::CSS` `rules`.
#search	Search this object for `paths`.
#xpath	Search this node for XPath `paths`.
#css_internal, #css_rules_to_xpath, #xpath_impl, #xpath_internal, #xpath_query_from_css_rule, #extract_params

`::Nokogiri::XML::PP::Node` - Included

#inspect, #pretty_print

Constructor Details

.new(*args) ⇒ `Document`

This method is for internal use only.

[ GitHub ]

# File 'lib/nokogiri/html5/document.rb', line 167


def initialize(*args) # :nodoc:
  super
  @url = nil
  @quirks_mode = nil
  @parse_noscript_content_as_text = nil
end

Class Method Details

.do_parse(string_or_io, url, encoding, **options) (private)

[ GitHub ]

# File 'lib/nokogiri/html5/document.rb', line 151


def do_parse(string_or_io, url, encoding, **options)
  string = HTML5.read_and_encode(string_or_io, encoding)

  options[:max_attributes] ||= Nokogiri::Gumbo::DEFAULT_MAX_ATTRIBUTES
  options[:max_errors] ||= options.delete(:max_parse_errors) || Nokogiri::Gumbo::DEFAULT_MAX_ERRORS
  options[:max_tree_depth] ||= Nokogiri::Gumbo::DEFAULT_MAX_TREE_DEPTH

  noscript_content_as_text = options[:parse_noscript_content_as_text] ? true : false

  doc = Nokogiri::Gumbo.parse(string, url, self, **options)
  doc.encoding = "UTF-8"
  doc.parse_noscript_content_as_text = noscript_content_as_text
  doc
end

.parse(input) { |options| ... } → HTML5::Document) .parse(input, url: encoding:) { |options| ... } → HTML5::Document) .parse(input, **options) → HTML5::Document)

Parse HTML input with a parser compliant with the ::Nokogiri::HTML5 spec. This method uses the encoding of input if it can be determined, or else falls back to the encoding: parameter.

[Required Parameters]

input (String | IO) the HTML content to be parsed.

[Optional Parameters]

url: (String) the base URI of the document.

[Optional Keyword Arguments]

encoding: (Encoding) The name of the encoding that should be used when processing the document. When not provided, the encoding will be determined based on the document content.
max_errors: (Integer) The maximum number of parse errors to record. (default Gumbo::DEFAULT_MAX_ERRORS which is currently 0)
max_tree_depth: (Integer) The maximum depth of the parse tree. (default Gumbo::DEFAULT_MAX_TREE_DEPTH)
max_attributes: (Integer) The maximum number of attributes allowed on an element. (default Gumbo::DEFAULT_MAX_ATTRIBUTES)
parse_noscript_content_as_text: (Boolean) Whether to parse the content of noscript elements as text. (default false)

See HTML5@Parsing+options for a complete description of these parsing options.

[Yields] If present, the block will be passed a Hash object to modify with parse options before the input is parsed. See HTML5@Parsing+options for a list of available options.

⚠️️️ Note that {url:} and {encoding:} cannot be set by the configuration block.

[Returns] Document

Example: Parse a string with a specific encoding and custom max errors limit.

Nokogiri::HTML5::Document.parse(socket, encoding: "ISO-8859-1", max_errors: 10)

Example: Parse a string setting the :parse_noscript_content_as_text option using the configuration block parameter.

Nokogiri::HTML5::Document.parse(input) { |c| c[:parse_noscript_content_as_text] = true }

Yields:

(options)

[ GitHub ]

# File 'lib/nokogiri/html5/document.rb', line 108


def parse(
  string_or_io,
  url_ = nil, encoding_ = nil,
  url: url_, encoding: encoding_,
  **options, &block
)
  yield options if block
  string_or_io = "" unless string_or_io

  if string_or_io.respond_to?(:encoding) && string_or_io.encoding != Encoding::ASCII_8BIT
    encoding ||= string_or_io.encoding.name
  end

  if string_or_io.respond_to?(:read) && string_or_io.respond_to?(:path)
    url ||= string_or_io.path
  end
  unless string_or_io.respond_to?(:read) || string_or_io.respond_to?(:to_str)
    raise ArgumentError, "not a string or IO object"
  end

  do_parse(string_or_io, url, encoding, **options)
end

.read_io(io, url_ = nil, encoding_ = nil, url: url_, encoding: encoding_, **options)

Create a new document from an IO object.

💡 Most users should prefer .parse to this method.

Raises:

(ArgumentError)

[ GitHub ]

# File 'lib/nokogiri/html5/document.rb', line 134


def read_io(io, url_ = nil, encoding_ = nil, url: url_, encoding: encoding_, **options)
  raise ArgumentError, "io object doesn't respond to :read" unless io.respond_to?(:read)

  do_parse(io, url, encoding, **options)
end

.read_memory(string, url_ = nil, encoding_ = nil, url: url_, encoding: encoding_, **options)

Create a new document from a String.

💡 Most users should prefer .parse to this method.

Raises:

(ArgumentError)

[ GitHub ]

# File 'lib/nokogiri/html5/document.rb', line 143


def read_memory(string, url_ = nil, encoding_ = nil, url: url_, encoding: encoding_, **options)
  raise ArgumentError, "string object doesn't respond to :to_str" unless string.respond_to?(:to_str)

  do_parse(string, url, encoding, **options)
end

Instance Attribute Details

#parse_noscript_content_as_text (rw)

This method is for internal use only.

Whether the parser treated the content of noscript elements as text, or nil before the first parse. Fragments parsed into this document must match it, because the serializer emits noscript text literally only when this is true.

[ GitHub ]

# File 'lib/nokogiri/html5/document.rb', line 54


attr_accessor :parse_noscript_content_as_text # :nodoc:

#quirks_mode (readonly)

Get the parser's quirks mode value. See QuirksMode.

This method returns nil if the parser was not invoked (e.g., .new).

Since v1.14.0

[ GitHub ]

# File 'lib/nokogiri/html5/document.rb', line 49


attr_reader :quirks_mode

#url (readonly)

Get the url name for this document, as passed into .parse, .read_io, or .read_memory

[ GitHub ]

# File 'lib/nokogiri/html5/document.rb', line 42


attr_reader :url

Instance Method Details

#fragment() → Nokogiri::HTML5::DocumentFragment) #fragment(markup) → Nokogiri::HTML5::DocumentFragment)

Parse a ::Nokogiri::HTML5 document fragment from markup, returning a DocumentFragment.

[Properties]

markup (String) The HTML5 markup fragment to be parsed

[Returns] Nokogiri::HTML5::DocumentFragment. This object's children will be empty if markup is not passed, is empty, or is nil.

[ GitHub ]

# File 'lib/nokogiri/html5/document.rb', line 187


def fragment(markup = nil)
  DocumentFragment.new(self, markup)
end

#to_xml(options = {}, &block)

This method is for internal use only.

[ GitHub ]

# File 'lib/nokogiri/html5/document.rb', line 191


def to_xml(options = {}, &block) # :nodoc:
  # Bypass XML::Document#to_xml which doesn't add
  # XML::Node::SaveOptions::AS_XML like XML::Node#to_xml does.
  XML::Node.instance_method(:to_xml).bind_call(self, options, &block)
end

#xpath_doctype() → Nokogiri::CSS::XPathVisitor::DoctypeConfig)

[Returns] The document type which determines CSS-to-XPath translation.

See ::Nokogiri::CSS::XPathVisitor for more information.

[ GitHub ]

# File 'lib/nokogiri/html5/document.rb', line 203


def xpath_doctype
  Nokogiri::CSS::XPathVisitor::DoctypeConfig::HTML5
end

Class: Nokogiri::HTML5::Document

Overview

Constant Summary

::Nokogiri::XML::PP::Node - Included

::Nokogiri::XML::Searchable - Included

::Nokogiri::ClassResolver - Included

::Nokogiri::XML::Node - Inherited

::Nokogiri::XML::Document - Inherited

Class Method Summary

::Nokogiri::HTML4::Document - Inherited

::Nokogiri::XML::Document - Inherited

::Nokogiri::XML::Node - Inherited

Instance Attribute Summary

::Nokogiri::HTML4::Document - Inherited

::Nokogiri::XML::Document - Inherited

::Nokogiri::XML::Node - Inherited

Instance Method Summary

::Nokogiri::HTML4::Document - Inherited

::Nokogiri::XML::Document - Inherited

::Nokogiri::XML::Node - Inherited

::Nokogiri::ClassResolver - Included

::Nokogiri::XML::Searchable - Included

::Nokogiri::XML::PP::Node - Included

Constructor Details

.new(*args) ⇒ Document

Class Method Details

.do_parse(string_or_io, url, encoding, **options) (private)

.parse(input) { |options| ... } → HTML5::Document) .parse(input, url: encoding:) { |options| ... } → HTML5::Document) .parse(input, **options) → HTML5::Document)

.read_io(io, url_ = nil, encoding_ = nil, url: url_, encoding: encoding_, **options)

.read_memory(string, url_ = nil, encoding_ = nil, url: url_, encoding: encoding_, **options)

Instance Attribute Details

#parse_noscript_content_as_text (rw)

#quirks_mode (readonly)

#url (readonly)

Instance Method Details

#fragment() → Nokogiri::HTML5::DocumentFragment) #fragment(markup) → Nokogiri::HTML5::DocumentFragment)

#to_xml(options = {}, &block)

#xpath_doctype() → Nokogiri::CSS::XPathVisitor::DoctypeConfig)

`::Nokogiri::XML::PP::Node` - Included

`::Nokogiri::XML::Searchable` - Included

`::Nokogiri::ClassResolver` - Included

`::Nokogiri::XML::Node` - Inherited

`::Nokogiri::XML::Document` - Inherited

`::Nokogiri::HTML4::Document` - Inherited

`::Nokogiri::XML::Document` - Inherited

`::Nokogiri::XML::Node` - Inherited

`::Nokogiri::HTML4::Document` - Inherited

`::Nokogiri::XML::Document` - Inherited

`::Nokogiri::XML::Node` - Inherited

`::Nokogiri::HTML4::Document` - Inherited

`::Nokogiri::XML::Document` - Inherited

`::Nokogiri::XML::Node` - Inherited

`::Nokogiri::ClassResolver` - Included

`::Nokogiri::XML::Searchable` - Included

`::Nokogiri::XML::PP::Node` - Included

.new(*args) ⇒ `Document`