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

nokolexbor 0.3.4-x86-mingw32 → 0.3.5-x86-mingw32

Files changed (11) hide show

checksums.yaml +4 -4
data/lib/nokolexbor/2.6/nokolexbor.so +0 -0
data/lib/nokolexbor/2.7/nokolexbor.so +0 -0
data/lib/nokolexbor/3.0/nokolexbor.so +0 -0
data/lib/nokolexbor/3.1/nokolexbor.so +0 -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 -2

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ca5252b82ee773ad65b0a925c748cc818df92352b1f86a5afe83bf3cba540e3e
-  data.tar.gz: 57c09a0abd52f4d44908fb1c0ce116c62ed965ee5ac2d126afaf644e7282fead
+  metadata.gz: 98828151d60be1dd3e0ba7f4a24b0cb85a8c4184899707273d3cac4b6c613d14
+  data.tar.gz: 6812ad37bfee69ce5b660c08d075d2388f3fc0c52ea8cc7821df64f9e67ff1f1
 SHA512:
-  metadata.gz: 9f068f0361b4b42cf7ca86e6de227e38a2b7c1767c5683c9eb8600c7592792451a74f9d99741d656e2dec7b74544f1c12d3c9b62456186eb797aa937c0ab7aab
-  data.tar.gz: 5f0c23bb8953f6153c9d7a68f91cf3db87c5b624657069908c77522a57af7385a66453c68e82087f0c26ae245123842ef32b91bfc88ed9d7bc46a624c5ef8dbd
+  metadata.gz: f252720b71fd46c6eb526f47c7944c55b69a94f539a312822069556b8f62151ce83d8c96a84d8d2f1251549faf5fb4494a1e6897336761064d2f4f1008e3d4cf
+  data.tar.gz: cc7908d0931a8fdb8320c539774a864763585ee409611c9f72389375c789783abadd1d4333f6b31455f7405c065253f3f22d980e44ab447c4c6016a378ae197d

data/lib/nokolexbor/2.6/nokolexbor.so CHANGED Viewed

Binary file

data/lib/nokolexbor/2.7/nokolexbor.so CHANGED Viewed

Binary file

data/lib/nokolexbor/3.0/nokolexbor.so CHANGED Viewed

Binary file

data/lib/nokolexbor/3.1/nokolexbor.so CHANGED Viewed

Binary file

data/lib/nokolexbor/document.rb CHANGED Viewed

@@ -2,6 +2,33 @@
 module Nokolexbor
   class Document < Nokolexbor::Node
+    # Create an {Element} with +name+ belonging to this document, optionally setting contents or
+    # attributes.
+    #
+    # @param name [String]
+    # @param contents_or_attrs [#to_s, Hash]
+    #
+    # @return [Element]
+    #
+    # @example An empty element without attributes
+    #   doc.create_element("div")
+    #   # => <div></div>
+    #
+    # @example An element with contents
+    #   doc.create_element("div", "contents")
+    #   # => <div>contents</div>
+    #
+    # @example An element with attributes
+    #   doc.create_element("div", {"class" => "container"})
+    #   # => <div class='container'></div>
+    #
+    # @example An element with contents and attributes
+    #   doc.create_element("div", "contents", {"class" => "container"})
+    #   # => <div class='container'>contents</div>
+    #
+    # @example Passing a block to mutate the element
+    #   doc.create_element("div") { |node| node["class"] = "blue" }
+    #   # => <div class='blue'></div>
     def create_element(name, *contents_or_attrs, &block)
       elm = Nokolexbor::Element.new(name, self, &block)
       contents_or_attrs.each do |arg|
@@ -11,32 +38,43 @@ module Nokolexbor
             elm[k.to_s] = v.to_s
           end
         else
-          elm.content = arg
+          elm.content = arg.to_s
         end
       end
       elm
     end
-    # Create a Text Node with +string+
+    # Create a {Text} with +string+.
+    #
+    # @return [Text]
     def create_text_node(string, &block)
       Nokolexbor::Text.new(string.to_s, self, &block)
     end
-    # Create a CDATA Node containing +string+
+    # Create a {CDATA} containing +string+.
+    #
+    # @return [CDATA]
     def create_cdata(string, &block)
       Nokolexbor::CDATA.new(string.to_s, self, &block)
     end
-    # Create a Comment Node containing +string+
+    # Create a {Comment} containing +string+.
+    #
+    # @return [Comment]
     def create_comment(string, &block)
       Nokolexbor::Comment.new(string.to_s, self, &block)
     end
-    # A reference to +self+
+    # A reference to +self+.
+    #
+    # @return [Document]
     def document
       self
     end
+    # Get the meta tag encoding for this document. If there is no meta tag, nil is returned.
+    #
+    # @return [String]
     def meta_encoding
       if (meta = at_css("meta[charset]"))
         meta[:charset]
@@ -45,6 +83,15 @@ module Nokolexbor
       end
     end
+    # Set the meta tag encoding for this document.
+    #
+    # If an meta encoding tag is already present, its content is
+    # replaced with the given text.
+    #
+    # Otherwise, this method tries to create one at an appropriate
+    # place supplying head and/or html elements as necessary, which
+    # is inside a head element if any, and before any text node or
+    # content element (typically <body>) if any.
     def meta_encoding=(encoding)
       if (meta = meta_content_type)
         meta["content"] = format("text/html; charset=%s", encoding)

data/lib/nokolexbor/document_fragment.rb CHANGED Viewed

@@ -2,10 +2,17 @@
 module Nokolexbor
   class DocumentFragment < Nokolexbor::Node
+    # Create a {DocumentFragment} from +tags+.
+    #
+    # @return [DocumentFragment]
     def self.parse(tags)
       new(Nokolexbor::Document.new, tags, nil)
     end
+    #  Create a new {DocumentFragment} from +tags+.
+    #
+    #  If +ctx+ is present, it is used as a context node for the
+    #  subtree created.
     def initialize(document, tags = nil, ctx = nil)
       return self unless tags
@@ -15,6 +22,7 @@ module Nokolexbor
       nil
     end
+    # @return [String] The name of {DocumentFragment}
     def name
       "#document-fragment"
     end
@@ -24,6 +32,9 @@ module Nokolexbor
     alias_method :to_s, :outer_html
     alias_method :serialize, :outer_html
+    # Create a {DocumentFragment} from +data+.
+    #
+    # @return [DocumentFragment]
     def fragment(data)
       document.fragment(data)
     end

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

data/lib/nokolexbor/node_set.rb CHANGED Viewed

@@ -4,6 +4,11 @@ module Nokolexbor
   class NodeSet < Nokolexbor::Node
     include Enumerable
+    # Create a NodeSet with +document+ defaulting to +list+.
+    #
+    # @yield [Document]
+    #
+    # @return [Document]
     def self.new(document, list = [])
       obj = allocate
       obj.instance_variable_set(:@document, document)
@@ -12,6 +17,9 @@ module Nokolexbor
       obj
     end
+    # Iterate over each node.
+    #
+    # @yield [Node]
     def each
       return to_enum unless block_given?
@@ -21,6 +29,11 @@ module Nokolexbor
       self
     end
+    # Get the first +n+ elements of the NodeSet.
+    #
+    # @param n [Numeric,nil]
+    #
+    # @return [Node,Array<Node>] {Node} if +n+ is nil, otherwise {Array<Node>}
     def first(n = nil)
       return self[0] unless n
@@ -29,14 +42,19 @@ module Nokolexbor
       list
     end
+    # Get the last element of the NodeSet.
+    #
+    # @return [Node,nil]
     def last
       self[-1]
     end
+    # @return [Boolean] true if this NodeSet is empty.
     def empty?
       length == 0
     end
+    # @return [Integer] The index of the first node in this NodeSet that is equal to +node+ or meets the given block. Returns nil if no match is found.
     def index(node = nil)
       if node
         each_with_index { |member, j| return j if member == node }
@@ -46,6 +64,9 @@ module Nokolexbor
       nil
     end
+    # Get the content of all contained Nodes.
+    #
+    # @return [String]
     def content
       self.map(&:content).join
     end
@@ -54,10 +75,16 @@ module Nokolexbor
     alias_method :inner_text, :content
     alias_method :to_str, :content
+    # Get the inner html of all contained Nodes.
+    #
+    # @return [String]
     def inner_html(*args)
       self.map { |n| n.inner_html(*args) }.join
     end
+    # Convert this NodeSet to HTML.
+    #
+    # @return [String]
     def outer_html(*args)
       self.map { |n| n.outer_html(*args) }.join
     end
@@ -66,6 +93,9 @@ module Nokolexbor
     alias_method :to_html, :outer_html
     alias_method :serialize, :outer_html
+    # Remove all nodes in this NodeSet.
+    #
+    # @see Node#remove
     def remove
       self.each(&:remove)
     end
@@ -73,22 +103,32 @@ module Nokolexbor
     alias_method :unlink, :remove
     alias_method :to_ary, :to_a
+    # Destroy all nodes in the NodeSet.
+    #
+    # @see Node#destroy
     def destroy
       self.each(&:destroy)
     end
+    # @return [Node,nil] The last element of this NodeSet and removes it. Returns
+    #   +nil+ if the set is empty.
     def pop
       return nil if length == 0
       delete(last)
     end
+    # @return [Node,nil] The first element of this NodeSet and removes it. Returns
+    #   +nil+ if the set is empty.
     def shift
       return nil if length == 0
       delete(first)
     end
+    # @return [Boolean] true if two NodeSets contain the same number
+    #   of elements and each element is equal to the corresponding
+    #   element in the other NodeSet.
     def ==(other)
       return false unless other.is_a?(NodeSet)
       return false unless length == other.length
@@ -99,6 +139,8 @@ module Nokolexbor
       true
     end
+    # @return [NodeSet] A new NodeSet containing all the children of all the nodes in
+    #   the NodeSet.
     def children
       node_set = NodeSet.new(@document)
       each do |node|
@@ -107,6 +149,8 @@ module Nokolexbor
       node_set
     end
+    # @return [NodeSet] A new NodeSet containing all the nodes in the NodeSet
+    #   in reverse order.
     def reverse
       node_set = NodeSet.new(@document)
       (length - 1).downto(0) do |x|
@@ -115,6 +159,17 @@ module Nokolexbor
       node_set
     end
+    # Wrap all nodes of this NodeSet with +node_or_tags+.
+    #
+    # @see Node#wrap
+    #
+    # @return [NodeSet] +self+, to support chaining.
+    def wrap(node_or_tags)
+      map { |node| node.wrap(node_or_tags) }
+      self
+    end
+    # (see Node#xpath)
     def xpath(*args)
       paths, handler, ns, binds = extract_params(args)
@@ -127,6 +182,7 @@ module Nokolexbor
       end
     end
+    # (see Node#nokogiri_css)
     def nokogiri_css(*args)
       rules, handler, ns, _ = extract_params(args)
       paths = css_rules_to_xpath(rules, ns)

data/lib/nokolexbor/version.rb CHANGED Viewed

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 module Nokolexbor
-  VERSION = '0.3.4'
+  VERSION = '0.3.5'
 end

metadata CHANGED Viewed

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nokolexbor
 version: !ruby/object:Gem::Version
-  version: 0.3.4
+  version: 0.3.5
 platform: x86-mingw32
 authors:
 - Yicheng Zhou
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-01-10 00:00:00.000000000 Z
+date: 2023-01-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler