nokolexbor 0.3.3 → 0.3.5

data/ext/nokolexbor/nl_node_set.c

@@ -63,12 +63,27 @@ nl_rb_node_set_create_with_data(lexbor_array_t *array, VALUE rb_document)
   return ret;
 }
 
+/**
+ * Get the length of this NodeSet.
+ *
+ * @return [Integer]
+ */
 static VALUE
 nl_node_set_length(VALUE self)
 {
   return INT2NUM(nl_rb_node_set_unwrap(self)->length);
 }
 
+/**
+ * call-seq:
+ *   push(node)
+ *
+ * Append +node+ to the NodeSet.
+ *
+ * @param node [Node]
+ *
+ * @return [NodeSet] +self+, to support chaining of calls.
+ */
 static VALUE
 nl_node_set_push(VALUE self, VALUE rb_node)
 {
@@ -83,6 +98,16 @@ nl_node_set_push(VALUE self, VALUE rb_node)
   return self;
 }
 
+/**
+ *  call-seq:
+ *    delete(node)
+ *
+ * Delete +node+ from the NodeSet.
+ *
+ * @param node [Node]
+ *
+ * @return [Node,nil] The deleted node if found, otherwise returns nil.
+ */
 static VALUE
 nl_node_set_delete(VALUE self, VALUE rb_node)
 {
@@ -103,6 +128,12 @@ nl_node_set_delete(VALUE self, VALUE rb_node)
   return rb_node;
 }
 
+/**
+ * call-seq:
+ *   include?(node)
+ *
+ * @return true if any member of this NodeSet equals +node+.
+ */
 static VALUE
 nl_node_set_is_include(VALUE self, VALUE rb_node)
 {
@@ -166,6 +197,18 @@ nl_node_set_subseq(VALUE self, long beg, long len)
   return nl_rb_node_set_create_with_data(new_array, nl_rb_document_get(self));
 }
 
+/**
+ * call-seq:
+ *   [](index) -> Node,nil
+ *   [](start, length) -> NodeSet,nil
+ *   [](range) -> NodeSet,nil
+ *
+ * @return [Node,NodeSet,nil] the {Node} at +index+, or returns a {NodeSet}
+ *   containing nodes starting at +start+ and continuing for +length+ elements, or
+ *   returns a {NodeSet} containing nodes specified by +range+. Negative +indices+
+ *   count backward from the end of the +node_set+ (-1 is the last node). Returns
+ *   nil if the +index+ (or +start+) are out of range.
+ */
 static VALUE
 nl_node_set_slice(int argc, VALUE *argv, VALUE self)
 {
@@ -205,6 +248,9 @@ nl_node_set_slice(int argc, VALUE *argv, VALUE self)
   return nl_node_set_index_at(self, NUM2LONG(arg));
 }
 
+/**
+ * @return [Array<Node>] This list as an Array
+ */
 static VALUE
 nl_node_set_to_array(VALUE self)
 {
@@ -221,6 +267,9 @@ nl_node_set_to_array(VALUE self)
   return list;
 }
 
+/**
+ * @return [NodeSet] A new set built by merging the +other+ set, excluding duplicates.
+ */
 static VALUE
 nl_node_set_union(VALUE self, VALUE other)
 {
@@ -301,6 +350,9 @@ nl_node_set_find(VALUE self, VALUE selector, lxb_selectors_cb_f cb, void *ctx)
   return status;
 }
 
+/**
+ * (see Node#at_css)
+ */
 static VALUE
 nl_node_set_at_css(VALUE self, VALUE selector)
 {
@@ -328,6 +380,9 @@ nl_node_set_at_css(VALUE self, VALUE selector)
   return ret;
 }
 
+/**
+ * (see Node#css)
+ */
 static VALUE
 nl_node_set_css(VALUE self, VALUE selector)
 {
@@ -353,7 +408,6 @@ void Init_nl_node_set(void)
 
   rb_define_method(cNokolexborNodeSet, "length", nl_node_set_length, 0);
   rb_define_method(cNokolexborNodeSet, "[]", nl_node_set_slice, -1);
-  rb_define_method(cNokolexborNodeSet, "slice", nl_node_set_slice, -1);
   rb_define_method(cNokolexborNodeSet, "push", nl_node_set_push, 1);
   rb_define_method(cNokolexborNodeSet, "|", nl_node_set_union, 1);
   rb_define_method(cNokolexborNodeSet, "to_a", nl_node_set_to_array, 0);
@@ -362,6 +416,7 @@ void Init_nl_node_set(void)
   rb_define_method(cNokolexborNodeSet, "at_css", nl_node_set_at_css, 1);
   rb_define_method(cNokolexborNodeSet, "css", nl_node_set_css, 1);
 
+  rb_define_alias(cNokolexborNodeSet, "slice", "[]");
   rb_define_alias(cNokolexborNodeSet, "<<", "push");
   rb_define_alias(cNokolexborNodeSet, "size", "length");
   rb_define_alias(cNokolexborNodeSet, "+", "|");

data/ext/nokolexbor/nl_processing_instruction.c

@@ -4,6 +4,12 @@ VALUE cNokolexborProcessingInstruction;
 extern VALUE cNokolexborNode;
 extern VALUE mNokolexbor;
 
+/**
+ * call-seq:
+ *   new(name, content, document) { |ProcessingInstruction| ... } -> ProcessingInstruction
+ *
+ * Create a new ProcessingInstruction from +name+ and +content+.
+ */
 static VALUE
 nl_processing_instruction_new(int argc, VALUE *argv, VALUE klass)
 {

data/ext/nokolexbor/nl_text.c

@@ -4,6 +4,12 @@ VALUE cNokolexborText;
 extern VALUE cNokolexborCharacterData;
 extern VALUE mNokolexbor;
 
+/**
+ * call-seq:
+ *   new(text, document) { |Text| ... } -> Text
+ *
+ * Create a new Text from +text+.
+ */
 static VALUE
 nl_text_new(int argc, VALUE *argv, VALUE klass)
 {

data/ext/nokolexbor/nokolexbor.c

@@ -17,5 +17,6 @@ void Init_nokolexbor(void)
   Init_nl_processing_instruction();
   Init_nl_node_set();
   Init_nl_document_fragment();
+  Init_nl_attribute();
   Init_nl_xpath_context();
 }

data/ext/nokolexbor/nokolexbor.h

@@ -18,6 +18,7 @@ void Init_nl_cdata(void);
 void Init_nl_processing_instruction(void);
 void Init_nl_node_set(void);
 void Init_nl_document_fragment(void);
+void Init_nl_attribute(void);
 void Init_nl_xpath_context(void);
 
 void nl_raise_lexbor_error(lxb_status_t error);
@@ -34,6 +35,7 @@ lxb_inline VALUE nl_rb_document_get(VALUE rb_node_or_doc)
 }
 
 lxb_dom_document_t *nl_rb_document_unwrap(VALUE rb_doc);
+lexbor_array_t *nl_rb_node_set_unwrap(VALUE rb_node_set);
 
 const lxb_char_t *
 lxb_dom_node_name_qualified(lxb_dom_node_t *node, size_t *len);

data/lib/nokolexbor/document.rb

@@ -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

@@ -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