RubyGems - nokolexbor - Versions diffs - 0.3.4 → 0.3.5 - Mend

nokolexbor 0.3.4 → 0.3.5

Files changed (40) hide show

checksums.yaml +4 -4
data/ext/nokolexbor/nl_attribute.c +46 -0
data/ext/nokolexbor/nl_cdata.c +8 -0
data/ext/nokolexbor/nl_comment.c +6 -0
data/ext/nokolexbor/nl_document.c +53 -7
data/ext/nokolexbor/nl_document_fragment.c +9 -0
data/ext/nokolexbor/nl_error.c +21 -19
data/ext/nokolexbor/nl_node.c +255 -49
data/ext/nokolexbor/nl_node_set.c +56 -1
data/ext/nokolexbor/nl_processing_instruction.c +6 -0
data/ext/nokolexbor/nl_text.c +6 -0
data/ext/nokolexbor/nokolexbor.h +1 -0
data/lib/nokolexbor/document.rb +52 -5
data/lib/nokolexbor/document_fragment.rb +11 -0
data/lib/nokolexbor/node.rb +367 -18
data/lib/nokolexbor/node_set.rb +56 -0
data/lib/nokolexbor/version.rb +1 -1
metadata +2 -24
data/vendor/lexbor/source/lexbor/encoding/base.h +0 -218
data/vendor/lexbor/source/lexbor/encoding/big5.c +0 -42839
data/vendor/lexbor/source/lexbor/encoding/config.cmake +0 -12
data/vendor/lexbor/source/lexbor/encoding/const.h +0 -65
data/vendor/lexbor/source/lexbor/encoding/decode.c +0 -3193
data/vendor/lexbor/source/lexbor/encoding/decode.h +0 -370
data/vendor/lexbor/source/lexbor/encoding/encode.c +0 -1931
data/vendor/lexbor/source/lexbor/encoding/encode.h +0 -377
data/vendor/lexbor/source/lexbor/encoding/encoding.c +0 -252
data/vendor/lexbor/source/lexbor/encoding/encoding.h +0 -475
data/vendor/lexbor/source/lexbor/encoding/euc_kr.c +0 -53883
data/vendor/lexbor/source/lexbor/encoding/gb18030.c +0 -47905
data/vendor/lexbor/source/lexbor/encoding/iso_2022_jp_katakana.c +0 -159
data/vendor/lexbor/source/lexbor/encoding/jis0208.c +0 -22477
data/vendor/lexbor/source/lexbor/encoding/jis0212.c +0 -15787
data/vendor/lexbor/source/lexbor/encoding/multi.h +0 -53
data/vendor/lexbor/source/lexbor/encoding/range.c +0 -71
data/vendor/lexbor/source/lexbor/encoding/range.h +0 -34
data/vendor/lexbor/source/lexbor/encoding/res.c +0 -222
data/vendor/lexbor/source/lexbor/encoding/res.h +0 -34
data/vendor/lexbor/source/lexbor/encoding/single.c +0 -13748
data/vendor/lexbor/source/lexbor/encoding/single.h +0 -116

data/lib/nokolexbor/node.rb CHANGED Viewed

@@ -17,38 +17,51 @@ module Nokolexbor
     DOCUMENT_FRAG_NODE = 11
     NOTATION_NODE = 12
+    # @return [Document] The associated {Document} of this node
     attr_reader :document
     LOOKS_LIKE_XPATH = %r{^(\./|/|\.\.|\.$)}
+    # @return true if this is a {Comment}
     def comment?
       type == COMMENT_NODE
     end
+    # @return true if this is a {CDATA}
     def cdata?
       type == CDATA_SECTION_NODE
     end
+    # @return true if this is a {ProcessingInstruction}
     def processing_instruction?
       type == PI_NODE
     end
+    # @return true if this is a {Text}
     def text?
       type == TEXT_NODE
     end
+    # @return true if this is a {DocumentFragment}
     def fragment?
       type == DOCUMENT_FRAG_NODE
     end
+    # @return true if this is an {Element}
     def element?
       type == ELEMENT_NODE
     end
+    # @return true if this is a {Document}
     def document?
       is_a?(Nokolexbor::Document)
     end
+    # Get a list of ancestor Node of this Node
+    #
+    # @param [String, nil] selector The selector to match ancestors
+    #
+    # @return [NodeSet] A set of matched ancestor nodes
     def ancestors(selector = nil)
       return NodeSet.new(@document) unless respond_to?(:parent)
       return NodeSet.new(@document) unless parent
@@ -71,10 +84,39 @@ module Nokolexbor
       end)
     end
+    # Wrap this Node with another node.
+    #
+    # @param node [String, Node] A string or a node
+    #  - when {String}:
+    #    The markup that is parsed and used as the wrapper. If the parsed
+    #    fragment has multiple roots, the first root node is used as the wrapper.
+    #  - when {Node}:
+    #    An element that is cloned and used as the wrapper.
+    #
+    # @return [Node] +self+, to support chaining of calls.
+    #
+    # @see NodeSet#wrap
+    #
+    # @example with a {String} argument:
+    #
+    #   doc = Nokolexbor::HTML('<body><a>123</a></body>')
+    #   doc.at_css('a').wrap('<div></div>')
+    #   doc.at_css('body').inner_html
+    #   # => "<div><a>123</a></div>"
+    #
+    # @example with a {Node} argument:
+    #
+    #   doc = Nokolexbor::HTML('<body><a>123</a></body>')
+    #   doc.at_css('a').wrap(doc.create_element('div'))
+    #   doc.at_css('body').inner_html
+    #   # => "<div><a>123</a></div>"
+    #
     def wrap(node)
       case node
       when String
         new_parent = fragment(node).child
+      when DocumentFragment
+        new_parent = node.child
       when Node
         new_parent = node.dup
       else
@@ -91,6 +133,13 @@ module Nokolexbor
       self
     end
+    # Insert +node_or_tags+ before this Node (as a sibling).
+    #
+    # @param node_or_tags [Node, DocumentFragment, NodeSet, String] The node to be added.
+    #
+    # @return [Node,NodeSet] The reparented {Node} (if +node_or_tags+ is a {Node}), or {NodeSet} (if +node_or_tags+ is a {DocumentFragment}, {NodeSet}, or {String}).
+    #
+    # @see #before
     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?)
@@ -98,6 +147,13 @@ module Nokolexbor
       add_sibling(:previous, node_or_tags)
     end
+    # Insert +node_or_tags+ after this Node (as a sibling).
+    #
+    # @param node_or_tags [Node, DocumentFragment, NodeSet, String] The node to be added.
+    #
+    # @return [Node,NodeSet] The reparented {Node} (if +node_or_tags+ is a {Node}), or {NodeSet} (if +node_or_tags+ is a {DocumentFragment}, {NodeSet}, or {String}).
+    #
+    # @see #after
     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?)
@@ -105,11 +161,25 @@ module Nokolexbor
       add_sibling(:next, node_or_tags)
     end
+    # Insert +node_or_tags+ before this Node (as a sibling).
+    #
+    # @param node_or_tags [Node, DocumentFragment, NodeSet, String] The node to be added.
+    #
+    # @return [Node] +self+, to support chaining of calls.
+    #
+    # @see #add_previous_sibling
     def before(node_or_tags)
       add_previous_sibling(node_or_tags)
       self
     end
+    # Insert +node_or_tags+ after this Node (as a sibling).
+    #
+    # @param node_or_tags [Node, DocumentFragment, NodeSet, String] The node to be added.
+    #
+    # @return [Node] +self+, to support chaining of calls.
+    #
+    # @see #add_next_sibling
     def after(node_or_tags)
       add_next_sibling(node_or_tags)
       self
@@ -120,11 +190,25 @@ module Nokolexbor
     alias_method :next=, :add_next_sibling
     alias_method :previous=, :add_previous_sibling
+    # Add +node_or_tags+ as a child of this Node.
+    #
+    # @param node_or_tags [Node, DocumentFragment, NodeSet, String] The node to be added.
+    #
+    # @return [Node] +self+, to support chaining of calls.
+    #
+    # @see #add_child
     def <<(node_or_tags)
       add_child(node_or_tags)
       self
     end
+    # Add +node+ as the first child of this Node.
+    #
+    # @param node [Node, DocumentFragment, NodeSet, String] The node to be added.
+    #
+    # @return [Node,NodeSet] The reparented {Node} (if +node+ is a {Node}), or {NodeSet} (if +node+ is a {DocumentFragment}, {NodeSet}, or {String}).
+    #
+    # @see #add_child
     def prepend_child(node)
       if (first = children.first)
         # Mimic the error add_child would raise.
@@ -136,83 +220,175 @@ module Nokolexbor
       end
     end
+    # Traverse self and all children.
+    # @yield self and all children to +block+ recursively.
     def traverse(&block)
       children.each { |j| j.traverse(&block) }
       yield(self)
     end
+    # @param selector [String] The selector to match
+    #
+    # @return true if this Node matches +selector+
     def matches?(selector)
       ancestors.last.css(selector).any? { |node| node == self }
     end
+    # Fetch this node's attributes.
+    #
+    # @return [Hash{String => Attribute}] Hash containing attributes belonging to +self+. The hash keys are String attribute names, and the hash values are {Nokolexbor::Attribute}.
     def attributes
       attribute_nodes.each_with_object({}) do |node, hash|
         hash[node.name] = node
       end
     end
+    # Replace this Node with +node+.
+    #
+    # @param node [Node, DocumentFragment, NodeSet, String]
+    #
+    # @return [Node,NodeSet] The reparented {Node} (if +node+ is a {Node}), or {NodeSet} (if +node+ is a {DocumentFragment}, {NodeSet}, or {String}).
+    #
+    # @see #swap
     def replace(node)
-      if node.is_a?(NodeSet)
-        node.each { |n| add_sibling(:previous, n) }
-      else
-        add_sibling(:previous, node)
-      end
+      ret = add_sibling(:previous, node)
       remove
+      ret
+    end
+    # Swap this Node for +node+.
+    #
+    # @param node [Node, DocumentFragment, NodeSet, String]
+    #
+    # @return [Node] +self+, to support chaining of calls.
+    #
+    # @see #replace
+    def swap(node)
+      replace(node)
+      self
     end
+    # Set the content of this Node.
+    #
+    # @param node [Node, DocumentFragment, NodeSet, String] The node to be added.
+    #
+    # @see #inner_html=
     def children=(node)
       children.remove
-      if node.is_a?(NodeSet)
-        node.each { |n| add_child(n) }
-      else
-        add_child(node)
-      end
+      add_child(node)
     end
+    # Set the parent Node of this Node.
+    #
+    # @param parent_node [Node] The parent node.
     def parent=(parent_node)
       parent_node.add_child(self)
     end
+    # Iterate over each attribute name and value pair of this Node.
+    #
+    # @yield [String,String] The name and value of the current attribute.
     def each
       attributes.each do |name, node|
         yield [name, node.value]
       end
     end
+    # Create a {DocumentFragment} containing +tags+ that is relative to _this_
+    # context node.
+    #
+    # @return [DocumentFragment]
     def fragment(tags)
       Nokolexbor::DocumentFragment.new(document, tags, self)
     end
     alias_method :inner_html=, :children=
+    # Search this object for CSS +rules+. +rules+ must be one or more CSS
+    # selectors.
+    #
+    # This method uses Lexbor as the selector engine. Its performance is much higher than {#xpath} or {#nokogiri_css}.
+    #
+    # @example
+    #   node.css('title')
+    #   node.css('body h1.bold')
+    #   node.css('div + p.green', 'div#one')
+    #
+    # @return [NodeSet] The matched set of Nodes.
+    #
+    # @see #xpath
+    # @see #nokogiri_css
     def css(*args)
       css_impl(args.join(', '))
     end
+    # Like {#css}, but returns the first match.
+    #
+    # This method uses Lexbor as the selector engine. Its performance is much higher than {#at_xpath} or {#nokogiri_at_css}.
+    #
+    # @return [Node, nil] The first matched Node.
+    #
+    # @see #css
+    # @see #nokogiri_at_css
     def at_css(*args)
       at_css_impl(args.join(', '))
     end
+    # Search this object for CSS +rules+. +rules+ must be one or more CSS
+    # selectors. It supports a mixed syntax of CSS selectors and XPath.
+    #
+    # This method uses libxml2 as the selector engine. It works the same way as {Nokogiri::Node#css}.
+    #
+    # @return [NodeSet] The matched set of Nodes.
+    #
+    # @see #css
     def nokogiri_css(*args)
       rules, handler, ns, _ = extract_params(args)
       nokogiri_css_internal(self, rules, handler, ns)
     end
+    # Like {#nokogiri_css}, but returns the first match.
+    #
+    # This method uses libxml2 as the selector engine. It works the same way as {Nokogiri::Node#at_css}.
+    #
+    # @return [Node, nil] The first matched Node.
+    #
+    # @see #nokogiri_at_css
+    # @see #at_css
     def nokogiri_at_css(*args)
       nokogiri_css(*args).first
     end
+    # Search this node for XPath +paths+. +paths+ must be one or more XPath
+    # queries.
+    #
+    # It works the same way as {Nokogiri::Node#xpath}.
+    #
+    # @example
+    #   node.xpath('.//title')
+    #
+    # @return [NodeSet] The matched set of Nodes.
     def xpath(*args)
       paths, handler, ns, binds = extract_params(args)
       xpath_internal(self, paths, handler, ns, binds)
     end
+    # Like {#xpath}, but returns the first match.
+    #
+    # It works the same way as {Nokogiri::Node#at_xpath}.
+    #
+    # @return [Node, nil] The first matched Node.
+    #
+    # @see #xpath
     def at_xpath(*args)
       xpath(*args).first
     end
+    # Search this object for +paths+. +paths+ must be one or more XPath or CSS selectors.
+    #
+    # @return [NodeSet] The matched set of Nodes.
     def search(*args)
       paths, handler, ns, binds = extract_params(args)
@@ -225,6 +401,11 @@ module Nokolexbor
     alias_method :/, :search
+    # Like {#search}, but returns the first match.
+    #
+    # @return [Node, nil] The first matched Node.
+    #
+    # @see #search
     def at(*args)
       paths, handler, ns, binds = extract_params(args)
@@ -237,26 +418,148 @@ module Nokolexbor
     alias_method :%, :at
+    # Fetch CSS class names of a Node.
+    #
+    # This is a convenience function and is equivalent to:
+    #
+    #   node.kwattr_values("class")
+    #
+    # @see #kwattr_values
+    # @see #add_class
+    # @see #append_class
+    # @see #remove_class
+    #
+    # @return [Array]
+    #   The CSS classes present in the Node's "class" attribute. If the
+    #   attribute is empty or non-existent, the return value is an empty array.
+    #
+    # @example
+    #   node.classes # => ["section", "title", "header"]
     def classes
       kwattr_values("class")
     end
+    # Ensure 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 #kwattr_add
+    # @see #classes
+    # @see #append_class
+    # @see #remove_class
+    #
+    # @param [String, Array<String>] names
+    #   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.
+    #
+    # @return [Node] +self+, to support chaining of calls.
+    #
+    # @example
+    #   node.add_class("section") # => <div class="section"></div>
+    #   node.add_class("section") # => <div class="section"></div> # duplicate not added
+    #   node.add_class("section header") # => <div class="section header"></div>
+    #   node.add_class(["section", "header"]) # => <div class="section header"></div>
     def add_class(names)
       kwattr_add("class", names)
     end
+    # Add 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 #kwattr_append
+    # @see #classes
+    # @see #add_class
+    # @see #remove_class
+    #
+    # @return [Node] +self+, to support chaining of calls.
     def append_class(names)
       kwattr_append("class", names)
     end
+    # Remove 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)
+    #
+    # @see #kwattr_remove
+    # @see #classes
+    # @see #add_class
+    # @see #append_class
+    #
+    # @param names [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.
+    #
+    # @return [Node] +self+, to support chaining of calls.
+    #
+    # @example
+    #   node.remove_class("section")
+    #   node.remove_class(["section", "float"])
     def remove_class(names = nil)
       kwattr_remove("class", names)
     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}[https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel].
+    #
+    # @see #kwattr_add
+    # @#kwattr_append
+    # @#kwattr_remove
+    #
+    # @param attribute_name [String]
+    #   The name of the keyword attribute to be inspected.
+    #
+    # @return [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.
     def kwattr_values(attribute_name)
       keywordify(attr(attribute_name) || [])
     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}[https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel].
+    #
+    # @see #add_class
+    # @see #kwattr_values
+    # @see #kwattr_append
+    # @see #kwattr_remove
+    #
+    # @param attribute_name [String] The name of the keyword attribute to be modified.
+    # @param 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.
+    #
+    # @return [Node] +self+, to support chaining of calls.
     def kwattr_add(attribute_name, keywords)
       keywords = keywordify(keywords)
       current_kws = kwattr_values(attribute_name)
@@ -265,6 +568,27 @@ module Nokolexbor
       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}[https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel].
+    #
+    # @see #add_class
+    # @see #kwattr_values
+    # @see #kwattr_add
+    # @see #kwattr_remove
+    #
+    # @param attribute_name [String] The name of the keyword attribute to be modified.
+    # @param 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.
+    #
+    # @return [Node] +self+, to support chaining of calls.
     def kwattr_append(attribute_name, keywords)
       keywords = keywordify(keywords)
       current_kws = kwattr_values(attribute_name)
@@ -273,6 +597,30 @@ module Nokolexbor
       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}[https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/rel].
+    #
+    # @see #remove_class
+    # @see #kwattr_values
+    # @see #kwattr_add
+    # @see #kwattr_append
+    #
+    # @param attribute_name [String] The name of the keyword attribute to be modified.
+    # @param 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.
+    #
+    # @return [Node] +self+, to support chaining of calls.
     def kwattr_remove(attribute_name, keywords)
       if keywords.nil?
         remove_attr(attribute_name)
@@ -290,6 +638,15 @@ module Nokolexbor
       self
     end
+    # Serialize Node and write to +io+.
+    def write_to(io, *options)
+      io.write(to_html(*options))
+    end
+    alias_method :write_html_to, :write_to
+    private
     def keywordify(keywords)
       case keywords
       when Enumerable
@@ -302,14 +659,6 @@ module Nokolexbor
       end
     end
-    def write_to(io, *options)
-      io.write(to_html(*options))
-    end
-    alias_method :write_html_to, :write_to
-    private
     def nokogiri_css_internal(node, rules, handler, ns)
       xpath_internal(node, css_rules_to_xpath(rules, ns), handler, ns, nil)
     end