nokolexbor 0.3.3 → 0.3.5

data/ext/nokolexbor/nl_node.c

@@ -12,6 +12,7 @@ extern VALUE cNokolexborComment;
 extern VALUE cNokolexborProcessingInstruction;
 extern VALUE cNokolexborNodeSet;
 extern VALUE cNokolexborDocumentFragment;
+extern VALUE cNokolexborAttribute;
 extern VALUE eLexborError;
 VALUE cNokolexborNode;
 VALUE cNokolexborElement;
@@ -31,8 +32,9 @@ nl_rb_node_create(lxb_dom_node_t *node, VALUE rb_document)
   case LXB_DOM_NODE_TYPE_ELEMENT:
     rb_class = cNokolexborElement;
     break;
-  // case LXB_DOM_NODE_TYPE_ATTRIBUTE:
-  //   break;
+  case LXB_DOM_NODE_TYPE_ATTRIBUTE:
+    rb_class = cNokolexborAttribute;
+    break;
   case LXB_DOM_NODE_TYPE_TEXT:
     rb_class = cNokolexborText;
     break;
@@ -49,8 +51,11 @@ nl_rb_node_create(lxb_dom_node_t *node, VALUE rb_document)
   case LXB_DOM_NODE_TYPE_COMMENT:
     rb_class = cNokolexborComment;
     break;
-  // case LXB_DOM_NODE_TYPE_DOCUMENT:
-  //   break;
+  case LXB_DOM_NODE_TYPE_DOCUMENT:
+    if (nl_rb_node_unwrap(rb_document) != node) {
+      rb_raise(rb_eRuntimeError, "Unexpected node type: Document");
+    }
+    return rb_document;
   // case LXB_DOM_NODE_TYPE_DOCUMENT_TYPE:
   //   break;
   case LXB_DOM_NODE_TYPE_DOCUMENT_FRAGMENT:
@@ -79,6 +84,23 @@ nl_rb_node_unwrap(VALUE rb_node)
   return node;
 }
 
+/**
+ * call-seq:
+ *   new(name, document) { |Node| ... } -> Node
+ *
+ * Create a new node with +name+ that belongs to +document+.
+ *
+ * If you intend to add a node to a document tree, it's likely that you will prefer one of the
+ * {Node} methods like {#add_child}, {#add_next_sibling}, {#replace}, etc. which will
+ * both create an element (or subtree) and place it in the document tree.
+ *
+ * Another alternative, if you are concerned about performance, is
+ * {Document#create_element} which accepts additional arguments for contents or
+ * attributes but (like this method) avoids parsing markup.
+ *
+ * @param name [String]
+ * @param document [Document] The document to which the the returned node will belong.
+ */
 static VALUE
 nl_node_new(int argc, VALUE *argv, VALUE klass)
 {
@@ -111,6 +133,68 @@ nl_node_new(int argc, VALUE *argv, VALUE klass)
   return rb_node;
 }
 
+/**
+ * call-seq: attribute(name) → Attribute
+ *
+ * @return [Attribute] The attribute belonging to this node with name +name+.
+ */
+static VALUE
+nl_node_attribute(VALUE self, VALUE rb_name)
+{
+  lxb_dom_node_t *node = nl_rb_node_unwrap(self);
+
+  const char *c_name = StringValuePtr(rb_name);
+  size_t name_len = RSTRING_LEN(rb_name);
+
+  if (node->type != LXB_DOM_NODE_TYPE_ELEMENT) {
+    return Qnil;
+  }
+
+  lxb_dom_attr_t *attr = lxb_dom_element_attr_by_name(lxb_dom_interface_element(node), (const lxb_char_t *)c_name, name_len);
+  if (attr == NULL) {
+    return Qnil;
+  }
+  if (attr->owner == NULL) {
+    attr->owner = lxb_dom_interface_element(node);
+  }
+  return nl_rb_node_create(attr, nl_rb_document_get(self));
+}
+
+/**
+ * @return [Array<Attribute>] An array of {Attribute} belonging to this node.
+ */
+static VALUE
+nl_node_attribute_nodes(VALUE self)
+{
+  lxb_dom_node_t *node = nl_rb_node_unwrap(self);
+  VALUE ary = rb_ary_new();
+  if (node->type != LXB_DOM_NODE_TYPE_ELEMENT) {
+    return ary;
+  }
+
+  lxb_dom_attr_t *attr = lxb_dom_element_first_attribute(lxb_dom_interface_element(node));
+
+  if (attr == NULL) {
+    return ary;
+  }
+
+  VALUE rb_doc = nl_rb_document_get(self);
+  while (attr != NULL) {
+    if (attr->owner == NULL) {
+      attr->owner = lxb_dom_interface_element(node);
+    }
+    rb_ary_push(ary, nl_rb_node_create(attr, rb_doc));
+    attr = attr->next;
+  }
+
+  return ary;
+}
+
+/**
+ * @return [String]
+ *   Contents of all the text nodes in this node's subtree, concatenated together into a single
+ *   String.
+ */
 static VALUE
 nl_node_content(VALUE self)
 {
@@ -127,6 +211,12 @@ nl_node_content(VALUE self)
   return rb_str;
 }
 
+/**
+ * Set the Node's content to a Text node containing +content+. The string gets XML escaped, not
+ * interpreted as markup.
+ *
+ * @return [String] +content+
+ */
 static VALUE
 nl_node_content_set(VALUE self, VALUE content)
 {
@@ -141,6 +231,15 @@ nl_node_content_set(VALUE self, VALUE content)
   return content;
 }
 
+/**
+ * call-seq: [](name) -> String,nil
+ *
+ * Fetch an attribute from this node.
+ *
+ * @param name The name of the attribute.
+ *
+ * @return (String, nil) The value of the attribute +name+, or +nil+ if no matching attribute exists.
+ */
 static VALUE
 nl_node_get_attr(VALUE self, VALUE rb_attr)
 {
@@ -166,6 +265,16 @@ nl_node_get_attr(VALUE self, VALUE rb_attr)
   return rb_utf8_str_new((const char *)attr_value, attr_value_len);
 }
 
+/**
+ * call-seq: []=(name, value) -> String,nil
+ *
+ * Update the attribute +name+ to +value+, or create the attribute if it does not exist.
+ *
+ * @param name The name of the attribute.
+ * @param value The value of the attribute.
+ *
+ * @return [String] +value+
+ */
 static VALUE
 nl_node_set_attr(VALUE self, VALUE rb_attr, VALUE rb_value)
 {
@@ -190,13 +299,22 @@ nl_node_set_attr(VALUE self, VALUE rb_attr, VALUE rb_value)
   return rb_value;
 }
 
+/**
+ * call-seq: remove_attr(name) -> Boolean
+ *
+ * Remove the attribute named +name+.
+ *
+ * @param name [String]
+ *
+ * @return [Boolean] +true+ if removal success, +false+ if node is not an {Element}.
+ */
 static VALUE
 nl_node_remove_attr(VALUE self, VALUE rb_attr)
 {
   lxb_dom_node_t *node = nl_rb_node_unwrap(self);
 
   if (node->type != LXB_DOM_NODE_TYPE_ELEMENT) {
-    return Qnil;
+    return Qfalse;
   }
 
   VALUE rb_attr_s = rb_String(rb_attr);
@@ -206,7 +324,12 @@ nl_node_remove_attr(VALUE self, VALUE rb_attr)
 
   lxb_dom_element_t *element = lxb_dom_interface_element(node);
 
-  return lxb_dom_element_remove_attribute(element, (const lxb_char_t *)attr_c, attr_len) == LXB_STATUS_OK ? Qtrue : Qfalse;
+  lxb_status_t status = lxb_dom_element_remove_attribute(element, (const lxb_char_t *)attr_c, attr_len);
+  if (status != LXB_STATUS_OK) {
+    nl_raise_lexbor_error(status);
+  }
+
+  return Qtrue;
 }
 
 lxb_status_t
@@ -333,6 +456,11 @@ void nl_sort_nodes_if_necessary(VALUE selector, lxb_dom_document_t *doc, lexbor_
   }
 }
 
+/**
+ * Internal implementation of {#at_css}
+ *
+ * @see #at_css
+ */
 static VALUE
 nl_node_at_css(VALUE self, VALUE selector)
 {
@@ -360,6 +488,11 @@ nl_node_at_css(VALUE self, VALUE selector)
   return ret;
 }
 
+/**
+ * Internal implementation of {#css}
+ *
+ * @see #css
+ */
 static VALUE
 nl_node_css(VALUE self, VALUE selector)
 {
@@ -377,6 +510,11 @@ nl_node_css(VALUE self, VALUE selector)
   return nl_rb_node_set_create_with_data(array, nl_rb_document_get(self));
 }
 
+/**
+ * Get the inner_html of this Node.
+ *
+ * @return [String]
+ */
 static VALUE
 nl_node_inner_html(int argc, VALUE *argv, VALUE self)
 {
@@ -414,6 +552,11 @@ nl_node_inner_html(int argc, VALUE *argv, VALUE self)
   return Qnil;
 }
 
+/**
+ * Serialize this Node to HTML, also known as outer_html.
+ *
+ * @return [String]
+ */
 static VALUE
 nl_node_outer_html(int argc, VALUE *argv, VALUE self)
 {
@@ -451,6 +594,11 @@ nl_node_outer_html(int argc, VALUE *argv, VALUE self)
   return Qnil;
 }
 
+/**
+ * call-seq: key?(name) -> Boolean
+ *
+ * @return true if +name+ is set.
+ */
 static VALUE
 nl_node_has_key(VALUE self, VALUE rb_attr)
 {
@@ -469,6 +617,11 @@ nl_node_has_key(VALUE self, VALUE rb_attr)
   return lxb_dom_element_has_attribute(element, (const lxb_char_t *)attr_c, attr_len) ? Qtrue : Qfalse;
 }
 
+/**
+ * Get the attribute names of this Node.
+ *
+ * @return [Array<String>] An array of attribute names.
+ */
 static VALUE
 nl_node_keys(VALUE self)
 {
@@ -492,6 +645,11 @@ nl_node_keys(VALUE self)
   return ary_keys;
 }
 
+/**
+ * Get the attribute values of this Node.
+ *
+ * @return [Array<String>] An array of attribute values.
+ */
 static VALUE
 nl_node_values(VALUE self)
 {
@@ -519,6 +677,11 @@ nl_node_values(VALUE self)
   return ary_values;
 }
 
+/**
+ * Get a hash of attribute names and values of this Node.
+ *
+ * @return [Hash{String => String}] A hash whose keys are attribute names and values are attribute values.
+ */
 static VALUE
 nl_node_attrs(VALUE self)
 {
@@ -547,6 +710,11 @@ nl_node_attrs(VALUE self)
   return rb_hash;
 }
 
+/**
+ * Get the parent node.
+ *
+ * @return [Node,nil] The parent node
+ */
 static VALUE
 nl_node_parent(VALUE self)
 {
@@ -554,6 +722,11 @@ nl_node_parent(VALUE self)
   return node->parent ? nl_rb_node_create(node->parent, nl_rb_document_get(self)) : Qnil;
 }
 
+/**
+ * Get the previous sibling node.
+ *
+ * @return [Node,nil] The previous sibling node
+ */
 static VALUE
 nl_node_previous(VALUE self)
 {
@@ -561,6 +734,11 @@ nl_node_previous(VALUE self)
   return node->prev ? nl_rb_node_create(node->prev, nl_rb_document_get(self)) : Qnil;
 }
 
+/**
+ * Get the previous sibling element.
+ *
+ * @return [Element,nil] The previous sibling element
+ */
 static VALUE
 nl_node_previous_element(VALUE self)
 {
@@ -574,6 +752,11 @@ nl_node_previous_element(VALUE self)
   return Qnil;
 }
 
+/**
+ * Get the next sibling node.
+ *
+ * @return [Node,nil] The previous sibling node
+ */
 static VALUE
 nl_node_next(VALUE self)
 {
@@ -581,6 +764,11 @@ nl_node_next(VALUE self)
   return node->next ? nl_rb_node_create(node->next, nl_rb_document_get(self)) : Qnil;
 }
 
+/**
+ * Get the next sibling element.
+ *
+ * @return [Element,nil] The previous sibling element
+ */
 static VALUE
 nl_node_next_element(VALUE self)
 {
@@ -594,6 +782,11 @@ nl_node_next_element(VALUE self)
   return Qnil;
 }
 
+/**
+ * Get the children of this node.
+ *
+ * @return [NodeSet] The set of this node's children.
+ */
 static VALUE
 nl_node_children(VALUE self)
 {
@@ -609,6 +802,11 @@ nl_node_children(VALUE self)
   return nl_rb_node_set_create_with_data(array, nl_rb_document_get(self));
 }
 
+/**
+ * Get the first child of this node.
+ *
+ * @return [Node,nil] The first child.
+ */
 static VALUE
 nl_node_child(VALUE self)
 {
@@ -617,14 +815,26 @@ nl_node_child(VALUE self)
   return child ? nl_rb_node_create(child, nl_rb_document_get(self)) : Qnil;
 }
 
+/**
+ * Remove this node from its current context.
+ *
+ * @return [Node] +self+, to support chaining of calls.
+ */
 static VALUE
 nl_node_remove(VALUE self)
 {
   lxb_dom_node_t *node = nl_rb_node_unwrap(self);
   lxb_dom_node_remove(node);
-  return Qnil;
+  return self;
 }
 
+/**
+ * Remove this node from its current context and free its allocated memory.
+ *
+ * @return [nil]
+ *
+ * @see #remove
+ */
 static VALUE
 nl_node_destroy(VALUE self)
 {
@@ -633,6 +843,9 @@ nl_node_destroy(VALUE self)
   return Qnil;
 }
 
+/**
+ * @return [Boolean] true if this Node is equal to +other+.
+ */
 static VALUE
 nl_node_equals(VALUE self, VALUE other)
 {
@@ -651,6 +864,11 @@ lxb_dom_node_name_qualified(lxb_dom_node_t *node, size_t *len)
   return lxb_dom_node_name(node, len);
 }
 
+/**
+ * Get the name of this Node
+ *
+ * @return [String] The name of this Node
+ */
 static VALUE
 nl_node_name(VALUE self)
 {
@@ -682,6 +900,13 @@ nl_node_parse_fragment(lxb_dom_document_t *doc, lxb_dom_element_t *element, lxb_
   return frag_root;
 }
 
+/**
+ * Parse +html+ as a document fragment within the context of
+ * *this* node.
+ *
+ * @param html [String] The fragment to be parsed.
+ * @return [NodeSet] The {NodeSet} containing the parsed nodes.
+ */
 static VALUE
 nl_node_parse(VALUE self, VALUE html)
 {
@@ -701,38 +926,48 @@ nl_node_parse(VALUE self, VALUE html)
   return nl_rb_node_set_create_with_data(array, nl_rb_document_get(self));
 }
 
+typedef void (*lxb_dom_node_add_nodes_to_f)(lxb_dom_node_t *, lxb_dom_node_t *);
+
 static VALUE
-nl_node_add_sibling(VALUE self, VALUE next_or_previous, VALUE new)
+nl_node_add_nodes(VALUE self, VALUE new, lxb_dom_node_add_nodes_to_f add_to, bool operate_on_new_node)
 {
   lxb_dom_node_t *node = nl_rb_node_unwrap(self);
   lxb_dom_document_t *doc = node->owner_document;
 
-  int insert_after;
-  if (rb_eql(rb_String(next_or_previous), rb_str_new_literal("next"))) {
-    insert_after = 1;
-  } else if (rb_eql(rb_String(next_or_previous), rb_str_new_literal("previous"))) {
-    insert_after = 0;
-  } else {
-    rb_raise(rb_eArgError, "Unsupported inserting position");
-  }
-
-  if (TYPE(new) == T_STRING) {
-    lxb_dom_node_t *frag_root = nl_node_parse_fragment(doc, NULL, (lxb_char_t *)RSTRING_PTR(new), RSTRING_LEN(new));
+  if (TYPE(new) == T_STRING || rb_obj_is_kind_of(new, cNokolexborDocumentFragment)) {
+    lxb_dom_node_t *frag_root = (TYPE(new) == T_STRING) ? nl_node_parse_fragment(doc, NULL, (lxb_char_t *)RSTRING_PTR(new), RSTRING_LEN(new))
+                                                        : nl_rb_node_unwrap(new);
     lexbor_array_t *array = lexbor_array_create();
 
+    lxb_dom_node_t *last_node = node;
     while (frag_root->first_child != NULL) {
       lxb_dom_node_t *child = frag_root->first_child;
       lxb_dom_node_remove(child);
-      insert_after ? lxb_dom_node_insert_after(node, child) : lxb_dom_node_insert_before(node, child);
+      operate_on_new_node ? add_to(last_node, child) : add_to(node, child);
+      last_node = child;
       lexbor_array_push(array, child);
     }
-    lxb_dom_node_destroy(frag_root);
+    if (TYPE(new) == T_STRING) {
+      lxb_dom_node_destroy(frag_root);
+    }
     return nl_rb_node_set_create_with_data(array, nl_rb_document_get(self));
 
+  } else if (rb_obj_is_kind_of(new, cNokolexborNodeSet)) {
+    lexbor_array_t *node_array = nl_rb_node_set_unwrap(new);
+
+    lxb_dom_node_t *last_node = node;
+    for (size_t i = 0; i < node_array->length; i++) {
+      lxb_dom_node_t *child = (lxb_dom_node_t *)node_array->list[i];
+      lxb_dom_node_remove(child);
+      operate_on_new_node ? add_to(last_node, child) : add_to(node, child);
+      last_node = child;
+    }
+    return new;
+
   } else if (rb_obj_is_kind_of(new, cNokolexborNode)) {
     lxb_dom_node_t *node_new = nl_rb_node_unwrap(new);
     lxb_dom_node_remove(node_new);
-    insert_after ? lxb_dom_node_insert_after(node, node_new) : lxb_dom_node_insert_before(node, node_new);
+    add_to(node, node_new);
     return new;
 
   } else {
@@ -741,43 +976,57 @@ nl_node_add_sibling(VALUE self, VALUE next_or_previous, VALUE new)
   return Qnil;
 }
 
+/**
+ * Insert +node_or_tags+ before or after this Node (as a sibling).
+ *
+ * @see #add_previous_sibling
+ * @see #add_next_sibling
+ *
+ * @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}).
+ */
 static VALUE
-nl_node_add_child(VALUE self, VALUE new)
+nl_node_add_sibling(VALUE self, VALUE next_or_previous, VALUE new)
 {
-  lxb_dom_node_t *node = nl_rb_node_unwrap(self);
-  lxb_dom_document_t *doc = node->owner_document;
-
-  if (TYPE(new) == T_STRING) {
-    lxb_dom_node_t *frag_root = nl_node_parse_fragment(doc, NULL, (lxb_char_t *)RSTRING_PTR(new), RSTRING_LEN(new));
-    lexbor_array_t *array = lexbor_array_create();
-
-    while (frag_root->first_child != NULL) {
-      lxb_dom_node_t *child = frag_root->first_child;
-      lxb_dom_node_remove(child);
-      lxb_dom_node_insert_child(node, child);
-      lexbor_array_push(array, child);
-    }
-    lxb_dom_node_destroy(frag_root);
-    return nl_rb_node_set_create_with_data(array, nl_rb_document_get(self));
-
-  } else if (rb_obj_is_kind_of(new, cNokolexborNode)) {
-    lxb_dom_node_t *node_new = nl_rb_node_unwrap(new);
-    lxb_dom_node_remove(node_new);
-    lxb_dom_node_insert_child(node, node_new);
-    return new;
-
+  bool insert_after;
+  if (rb_eql(rb_String(next_or_previous), rb_str_new_literal("next"))) {
+    insert_after = true;
+  } else if (rb_eql(rb_String(next_or_previous), rb_str_new_literal("previous"))) {
+    insert_after = false;
   } else {
-    rb_raise(rb_eArgError, "Unsupported node type");
+    rb_raise(rb_eArgError, "Unsupported inserting position");
   }
-  return Qnil;
+
+  return insert_after ? nl_node_add_nodes(self, new, lxb_dom_node_insert_after, true)
+                      : nl_node_add_nodes(self, new, lxb_dom_node_insert_before, false);
 }
 
+/**
+ * Add +new+ as a child of this Node.
+ *
+ * @param new [Node, DocumentFragment, NodeSet, String] The node to be added.
+ *
+ * @return [Node,NodeSet] The reparented {Node} (if +new+ is a {Node}), or {NodeSet} (if +new+ is a {DocumentFragment}, {NodeSet}, or {String}).
+ */
+static VALUE
+nl_node_add_child(VALUE self, VALUE new)
+{
+  return nl_node_add_nodes(self, new, lxb_dom_node_insert_child, false);
+}
+
+/**
+ * Get the type of this Node
+ *
+ * @return {Integer}
+ */
 static VALUE
 nl_node_get_type(VALUE self)
 {
   return INT2NUM(nl_rb_node_unwrap(self)->type);
 }
 
+/**
+ * @return [Element] The first child Node that is an element.
+ */
 static VALUE
 nl_node_first_element_child(VALUE self)
 {
@@ -805,6 +1054,9 @@ nl_node_first_element_child(VALUE self)
   return Qnil;
 }
 
+/**
+ * @return [Element] The last child Node that is an element.
+ */
 static VALUE
 nl_node_last_element_child(VALUE self)
 {
@@ -832,11 +1084,26 @@ nl_node_last_element_child(VALUE self)
   return Qnil;
 }
 
+/**
+ * Copy this node.
+ *
+ * @return [Node] The new {Node}.
+ */
 static VALUE
 nl_node_clone(VALUE self)
 {
   lxb_dom_node_t *node = nl_rb_node_unwrap(self);
-  lxb_dom_node_t *clone = lxb_dom_node_clone(node, 1);
+  lxb_dom_node_t *clone;
+
+  switch (node->type) {
+  case LXB_DOM_NODE_TYPE_ATTRIBUTE:
+    clone = (lxb_dom_node_t *)lxb_dom_attr_interface_clone(node->owner_document, lxb_dom_interface_attr(node));
+  case LXB_DOM_NODE_TYPE_CDATA_SECTION:
+    clone = (lxb_dom_node_t *)lxb_dom_cdata_section_interface_clone(node->owner_document, lxb_dom_interface_cdata_section(node));
+  default:
+    clone = lxb_dom_node_clone(node, true);
+    break;
+  }
   return nl_rb_node_create(clone, nl_rb_document_get(self));
 }
 
@@ -849,6 +1116,8 @@ void Init_nl_node(void)
   cNokolexborCharacterData = rb_define_class_under(mNokolexbor, "CharacterData", cNokolexborNode);
 
   rb_define_singleton_method(cNokolexborNode, "new", nl_node_new, -1);
+  rb_define_method(cNokolexborNode, "attribute", nl_node_attribute, 1);
+  rb_define_method(cNokolexborNode, "attribute_nodes", nl_node_attribute_nodes, 0);
   rb_define_method(cNokolexborNode, "content", nl_node_content, 0);
   rb_define_method(cNokolexborNode, "content=", nl_node_content_set, 1);
   rb_define_method(cNokolexborNode, "[]", nl_node_get_attr, 1);