RubyGems - nokolexbor - Versions diffs - 0.3.3-x86_64-darwin → 0.3.5-x86_64-darwin - Mend

nokolexbor 0.3.3-x86_64-darwin → 0.3.5-x86_64-darwin

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

checksums.yaml +4 -4
data/lib/nokolexbor/2.6/nokolexbor.bundle +0 -0
data/lib/nokolexbor/2.7/nokolexbor.bundle +0 -0
data/lib/nokolexbor/3.0/nokolexbor.bundle +0 -0
data/lib/nokolexbor/3.1/nokolexbor.bundle +0 -0
data/lib/nokolexbor/document.rb +52 -5
data/lib/nokolexbor/document_fragment.rb +11 -0
data/lib/nokolexbor/node.rb +370 -24
data/lib/nokolexbor/node_set.rb +56 -0
data/lib/nokolexbor/version.rb +1 -1
data/lib/nokolexbor.rb +0 -1
metadata +2 -3
data/lib/nokolexbor/attribute.rb +0 -18

checksums.yaml CHANGED Viewed

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cead1d5973dbabeb2bac9e3e413d21e7dbe4e36e42e58fdf22ad110e02f3decf
-  data.tar.gz: 443c22b64508e785863c7e552ead72cc00f71369b216f6ea38d2e29d10bb4f8a
+  metadata.gz: 2a0c4d52b626f7d8567f4efc3dcf3ad66f89b01b54070c1231e4d6f1f48d135d
+  data.tar.gz: 4fb65cf148b777ef42d5d7e2a06b3d578b59194cbc8d49bc904a8cfef4c491a3
 SHA512:
-  metadata.gz: 82efd32a9058e2e3ee63e1215dddfa3bb24fbe11a81d50f795738d10406b0d09eed48d00e301aab44796124150e7cf3d6cfd11295d833f0edfda3b21a50a5bb5
-  data.tar.gz: abce68297cb6cdfd144291d1ad40b8c1c5d16b512400890e5405eedf16976e3d8434a79838cab2690ebb54763f3770c996c1c4b5926b5196efb1ed25f3116524
+  metadata.gz: 912239a30461c910936f8182c6e3f580065c86a6362b06726214201d9dce59f6879b8fee4c95e24776190fdf4a0ef99234ab4b843587cec735dbfbbae2aa4f1d
+  data.tar.gz: cb85061c416597510856bd18404224b6931c5c63bc483b030ce3c92fd95584120dc5c08f0422b1335b5e9a9de94236973aa2a5cd7bfc5841147ac9422356231c

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

Binary file

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

Binary file

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

Binary file

data/lib/nokolexbor/3.1/nokolexbor.bundle 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,86 +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
-    def attribute(name)
-      return nil unless key?(name)
-      Attribute.new(name, attr(name))
-    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
-      attrs.map { |k, v| [k, Attribute.new(k, v)] }.to_h
+      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)
@@ -228,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)
@@ -240,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)
@@ -268,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)
@@ -276,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)
@@ -293,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
@@ -305,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.3'
+  VERSION = '0.3.5'
 end

data/lib/nokolexbor.rb CHANGED Viewed

@@ -26,7 +26,6 @@ require 'nokolexbor/node'
 require 'nokolexbor/document'
 require 'nokolexbor/node_set'
 require 'nokolexbor/document_fragment'
-require 'nokolexbor/attribute'
 require 'nokolexbor/xpath'
 require 'nokolexbor/xpath_context'

metadata CHANGED Viewed

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nokolexbor
 version: !ruby/object:Gem::Version
-  version: 0.3.3
+  version: 0.3.5
 platform: x86_64-darwin
 authors:
 - Yicheng Zhou
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-01-09 00:00:00.000000000 Z
+date: 2023-01-25 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake-compiler
@@ -50,7 +50,6 @@ files:
 - lib/nokolexbor/2.7/nokolexbor.bundle
 - lib/nokolexbor/3.0/nokolexbor.bundle
 - lib/nokolexbor/3.1/nokolexbor.bundle
-- lib/nokolexbor/attribute.rb
 - lib/nokolexbor/document.rb
 - lib/nokolexbor/document_fragment.rb
 - lib/nokolexbor/node.rb

data/lib/nokolexbor/attribute.rb DELETED Viewed

@@ -1,18 +0,0 @@
-# frozen_string_literal: true
-module Nokolexbor
-  class Attribute
-    attr_accessor :name
-    attr_accessor :value
-    def initialize(name, value)
-      @name = name
-      @value = value
-    end
-    alias_method :text, :value
-    alias_method :content, :value
-    alias_method :to_s, :value
-    alias_method :to_str, :value
-  end
-end