oj 1.0.6 → 1.1.0

data/README.md

@@ -24,9 +24,15 @@ A fast JSON parser and Object marshaller as a Ruby gem.
 
 ## <a name="release">Release Notes</a>
 
-### Release 1.0.6
+### Release 1.1.0
 
- - Gave Oj::Doc a speed increase. It is now 8 times fast than JSON::Ext.
+ - Errors are not longer raised when comments are encountered in JSON documents.
+
+ - Oj can now mimic JSON. With some expections calling JSON.mimic_JSON will allow all JSON calls to use OJ instead of JSON. This gives a speedup of more than 2x on parsing and 5x for generating over the JSON::Ext module.
+
+ - Oj::Doc now allows a document to be left open and then closed with the Oj::Doc.close() class.
+
+ - Changed the default encoding to UTF-8 instead of the Ruby default String encoding.
 
 ## <a name="description">Description</a>
 

data/ext/oj/dump.c

@@ -33,14 +33,9 @@
 #include <time.h>
 #include <stdio.h>
 #include <string.h>
+#include <math.h>
 
 #include "oj.h"
-#if IVAR_HELPERS
-#include "ruby/st.h"
-#else
-#include "st.h"
-#endif
-
 #include "cache8.h"
 
 typedef unsigned long   ulong;
@@ -341,8 +336,35 @@ static void
 dump_float(VALUE obj, Out out) {
     char	buf[64];
     char	*b;
-    int		cnt = sprintf(buf, "%0.16g", RFLOAT_VALUE(obj)); // used sprintf due to bug in snprintf
+    double	d = RFLOAT_VALUE(obj);
+    int		cnt;
 
+    switch (fpclassify(d)) {
+    case FP_NAN:
+	printf("*** nan\n");
+	cnt = sprintf(buf, "%0.16g", d); // used sprintf due to bug in snprintf
+	break;
+    case FP_INFINITE:
+	b = buf;
+	cnt = 8;
+	if (d < 0.0) {
+	    *b++ = '-';
+	    cnt++;
+	}
+	strcpy(b, "Infinity");
+	break;
+    case FP_ZERO:
+	b = buf;
+	*b++ = '0';
+	*b++ = '.';
+	*b++ = '0';
+	*b++ = '\0';
+	cnt = 3;
+	break;
+    default:
+	cnt = sprintf(buf, "%0.16g", d); // used sprintf due to bug in snprintf
+	break;
+    }
     if (out->end - out->cur <= (long)cnt) {
         grow(out, cnt);
     }
@@ -520,12 +542,30 @@ dump_array(VALUE a, int depth, Out out) {
 	if (0 < id) {
 	    *out->cur++ = ',';
 	}
-	size = d2 * out->indent + 2;
+	if (0 == out->opts->dump_opts) {
+	    size = d2 * out->indent + 2;
+	} else {
+	    size = d2 * out->opts->dump_opts->indent_size + out->opts->dump_opts->array_size + 1;
+	}
 	for (; 0 < cnt; cnt--, np++) {
 	    if (out->end - out->cur <= (long)size) {
 		grow(out, size);
 	    }
-	    fill_indent(out, d2);
+	    if (0 == out->opts->dump_opts) {
+		fill_indent(out, d2);
+	    } else {
+		if (0 < out->opts->dump_opts->array_size) {
+		    strcpy(out->cur, out->opts->dump_opts->array_nl);
+		    out->cur += out->opts->dump_opts->array_size;
+		}
+		if (0 < out->opts->dump_opts->indent_size) {
+		    int	i;
+		    for (i = d2; 0 < i; i--) {
+			strcpy(out->cur, out->opts->dump_opts->indent);
+			out->cur += out->opts->dump_opts->indent_size;
+		    }
+		}
+	    }
 	    dump_val(*np, d2, out);
 	    if (1 < cnt) {
 		*out->cur++ = ',';
@@ -535,7 +575,22 @@ dump_array(VALUE a, int depth, Out out) {
 	if (out->end - out->cur <= (long)size) {
 	    grow(out, size);
 	}
-	fill_indent(out, depth);
+	if (0 == out->opts->dump_opts) {
+	    fill_indent(out, depth);
+	} else {
+	    //printf("*** d2: %u  indent: %u '%s'\n", d2, out->opts->dump_opts->indent_size, out->opts->dump_opts->indent);
+	    if (0 < out->opts->dump_opts->array_size) {
+		strcpy(out->cur, out->opts->dump_opts->array_nl);
+		out->cur += out->opts->dump_opts->array_size;
+	    }
+	    if (0 < out->opts->dump_opts->indent_size) {
+		int	i;
+		for (i = depth; 0 < i; i--) {
+		    strcpy(out->cur, out->opts->dump_opts->indent);
+		    out->cur += out->opts->dump_opts->indent_size;
+		}
+	    }
+	}
 	*out->cur++ = ']';
     }
     *out->cur = '\0';
@@ -544,19 +599,51 @@ dump_array(VALUE a, int depth, Out out) {
 static int
 hash_cb_strict(VALUE key, VALUE value, Out out) {
     int		depth = out->depth;
-    long	size = depth * out->indent + 1;
+    long	size;
 
-    if (out->end - out->cur <= size) {
-	grow(out, size);
+    if (rb_type(key) != T_STRING) {
+	rb_raise(rb_eTypeError, "In :strict mode all Hash keys must be Strings.");
     }
-    fill_indent(out, depth);
-    if (rb_type(key) == T_STRING) {
+    if (0 == out->opts->dump_opts) {
+	size = depth * out->indent + 1;
+	if (out->end - out->cur <= size) {
+	    grow(out, size);
+	}
+	fill_indent(out, depth);
 	dump_str_comp(key, out);
 	*out->cur++ = ':';
-	dump_val(value, depth, out);
     } else {
-	rb_raise(rb_eTypeError, "In :strict mode all Hash keys must be Strings.");
+	size = depth * out->opts->dump_opts->indent_size + out->opts->dump_opts->hash_size + 1;
+	if (out->end - out->cur <= size) {
+	    grow(out, size);
+	}
+	if (0 < out->opts->dump_opts->hash_size) {
+	    strcpy(out->cur, out->opts->dump_opts->hash_nl);
+	    out->cur += out->opts->dump_opts->hash_size;
+	}
+	if (0 < out->opts->dump_opts->indent_size) {
+	    int	i;
+	    for (i = depth; 0 < i; i--) {
+		strcpy(out->cur, out->opts->dump_opts->indent);
+		out->cur += out->opts->dump_opts->indent_size;
+	    }
+	}
+	dump_str_comp(key, out);
+	size = out->opts->dump_opts->before_size + out->opts->dump_opts->after_size + 2;
+	if (out->end - out->cur <= size) {
+	    grow(out, size);
+	}
+	if (0 < out->opts->dump_opts->before_size) {
+	    strcpy(out->cur, out->opts->dump_opts->before_sep);
+	    out->cur += out->opts->dump_opts->before_size;
+	}
+	*out->cur++ = ':';
+	if (0 < out->opts->dump_opts->after_size) {
+	    strcpy(out->cur, out->opts->dump_opts->after_sep);
+	    out->cur += out->opts->dump_opts->after_size;
+	}
     }
+    dump_val(value, depth, out);
     out->depth = depth;
     *out->cur++ = ',';
 
@@ -566,12 +653,31 @@ hash_cb_strict(VALUE key, VALUE value, Out out) {
 static int
 hash_cb_compat(VALUE key, VALUE value, Out out) {
     int		depth = out->depth;
-    long	size = depth * out->indent + 1;
+    long	size;
 
-    if (out->end - out->cur <= size) {
-	grow(out, size);
+    if (0 == out->opts->dump_opts) {
+	size = depth * out->indent + 1;
+	if (out->end - out->cur <= size) {
+	    grow(out, size);
+	}
+	fill_indent(out, depth);
+    } else {
+	size = depth * out->opts->dump_opts->indent_size + out->opts->dump_opts->hash_size + 1;
+	if (out->end - out->cur <= size) {
+	    grow(out, size);
+	}
+	if (0 < out->opts->dump_opts->hash_size) {
+	    strcpy(out->cur, out->opts->dump_opts->hash_nl);
+	    out->cur += out->opts->dump_opts->hash_size;
+	}
+	if (0 < out->opts->dump_opts->indent_size) {
+	    int	i;
+	    for (i = depth; 0 < i; i--) {
+		strcpy(out->cur, out->opts->dump_opts->indent);
+		out->cur += out->opts->dump_opts->indent_size;
+	    }
+	}
     }
-    fill_indent(out, depth);
     switch (rb_type(key)) {
     case T_STRING:
 	dump_str_comp(key, out);
@@ -583,7 +689,23 @@ hash_cb_compat(VALUE key, VALUE value, Out out) {
 	rb_raise(rb_eTypeError, "In :strict mode all Hash keys must be Strings.");
 	break;
     }
-    *out->cur++ = ':';
+    if (0 == out->opts->dump_opts) {
+	*out->cur++ = ':';
+    } else {
+	size = out->opts->dump_opts->before_size + out->opts->dump_opts->after_size + 2;
+	if (out->end - out->cur <= size) {
+	    grow(out, size);
+	}
+	if (0 < out->opts->dump_opts->before_size) {
+	    strcpy(out->cur, out->opts->dump_opts->before_sep);
+	    out->cur += out->opts->dump_opts->before_size;
+	}
+	*out->cur++ = ':';
+	if (0 < out->opts->dump_opts->after_size) {
+	    strcpy(out->cur, out->opts->dump_opts->after_sep);
+	    out->cur += out->opts->dump_opts->after_size;
+	}
+    }
     dump_val(value, depth, out);
     out->depth = depth;
     *out->cur++ = ',';
@@ -696,10 +818,28 @@ dump_hash(VALUE obj, int depth, int mode, Out out) {
 	if (',' == *(out->cur - 1)) {
 	    out->cur--; // backup to overwrite last comma
 	}
-	if (out->end - out->cur <= (long)size) {
-	    grow(out, size);
+	if (0 == out->opts->dump_opts) {
+	    if (out->end - out->cur <= (long)size) {
+		grow(out, size);
+	    }
+	    fill_indent(out, depth);
+	} else {
+	    size = depth * out->opts->dump_opts->indent_size + out->opts->dump_opts->hash_size + 1;
+	    if (out->end - out->cur <= (long)size) {
+		grow(out, size);
+	    }
+	    if (0 < out->opts->dump_opts->hash_size) {
+		strcpy(out->cur, out->opts->dump_opts->hash_nl);
+		out->cur += out->opts->dump_opts->hash_size;
+	    }
+	    if (0 < out->opts->dump_opts->indent_size) {
+		int	i;
+		for (i = depth; 0 < i; i--) {
+		    strcpy(out->cur, out->opts->dump_opts->indent);
+		    out->cur += out->opts->dump_opts->indent_size;
+		}
+	    }
 	}
-	fill_indent(out, depth);
 	*out->cur++ = '}';
     }
     *out->cur = '\0';
@@ -1034,7 +1174,7 @@ dump_val(VALUE obj, int depth, Out out) {
 	default:		dump_sym_obj(obj, out);		break;
 	}
 	break;
-    case T_ARRAY:	dump_array(obj, depth, out);	break;
+    case T_ARRAY:	dump_array(obj, depth, out);		break;
     case T_HASH:	dump_hash(obj, depth, out->opts->mode, out);	break;
     case T_CLASS:
 	switch (out->opts->mode) {

data/ext/oj/fast.c

@@ -36,6 +36,8 @@
 
 #include "oj.h"
 
+// maximum to allocate on the stack, arbitrary limit
+#define SMALL_XML	65536
 #define MAX_STACK	100
 //#define BATCH_SIZE	(4096 / sizeof(struct _Leaf) - 1)
 #define BATCH_SIZE	100
@@ -55,6 +57,7 @@ typedef struct _Doc {
 #else
     void		*encoding;
 #endif
+    char		*json;
     unsigned long	size;        // number of leaves/branches in the doc
     VALUE		self;
     Batch		batches;
@@ -86,9 +89,10 @@ static Leaf	read_false(ParseInfo pi);
 static Leaf	read_nil(ParseInfo pi);
 static void	next_non_white(ParseInfo pi);
 static char*	read_quoted_value(ParseInfo pi);
+static void	skip_comment(ParseInfo pi);
 
 static VALUE	protect_open_proc(VALUE x);
-static VALUE	parse_json(VALUE clas, char *json);
+static VALUE	parse_json(VALUE clas, char *json, int given, int allocated);
 static void	each_leaf(Doc doc, VALUE self);
 static int	move_step(Doc doc, const char *path, int loc);
 static Leaf	get_doc_leaf(Doc doc, const char *path);
@@ -123,6 +127,9 @@ next_non_white(ParseInfo pi) {
 	case '\n':
 	case '\r':
 	    break;
+	case '/':
+	    skip_comment(pi);
+	    break;
 	default:
 	    return;
 	}
@@ -270,6 +277,46 @@ leaf_value(Doc doc, Leaf leaf) {
     return leaf->value;
 }
 
+inline static Doc
+self_doc(VALUE self) {
+    Doc	doc = DATA_PTR(self);
+
+    if (0 == doc) {
+	rb_raise(rb_eIOError, "Document already closed or not open.");
+    }
+    return doc;
+}
+
+static void
+skip_comment(ParseInfo pi) {
+    pi->s++; // skip first /
+    if ('*' == *pi->s) {
+	pi->s++;
+	for (; '\0' != *pi->s; pi->s++) {
+	    if ('*' == *pi->s && '/' == *(pi->s + 1)) {
+		pi->s++;
+		return;
+	    } else if ('\0' == *pi->s) {
+		raise_error("comment not terminated", pi->str, pi->s);
+	    }
+	}
+    } else if ('/' == *pi->s) {
+	for (; 1; pi->s++) {
+	    switch (*pi->s) {
+	    case '\n':
+	    case '\r':
+	    case '\f':
+	    case '\0':
+		return;
+	    default:
+		break;
+	    }
+	}
+    } else {
+	raise_error("invalid comment", pi->str, pi->s);
+    }
+}
+
 #ifdef RUBINIUS
 #define NUM_MAX 0x07FFFFFF
 #else
@@ -733,6 +780,7 @@ doc_init(Doc doc) {
     doc->encoding = 0;
 #endif
     doc->size = 0;
+    doc->json = 0;
     doc->batches = &doc->batch0;
     doc->batch0.next = 0;
     doc->batch0.next_avail = 0;
@@ -760,30 +808,41 @@ protect_open_proc(VALUE x) {
     pi->doc->data = read_next(pi); // parse
     *pi->doc->where = pi->doc->data;
     pi->doc->where = pi->doc->where_path;
-
-    return rb_yield(pi->doc->self); // caller processing
+    if (rb_block_given_p()) {
+	return rb_yield(pi->doc->self); // caller processing
+    }
+    return Qnil;
 }
 
 static VALUE
-parse_json(VALUE clas, char *json) {
+parse_json(VALUE clas, char *json, int given, int allocated) {
     struct _ParseInfo	pi;
     VALUE		result = Qnil;
-    struct _Doc		doc;
+    Doc			doc;
     int			ex = 0;
 
-    if (!rb_block_given_p()) {
-	rb_raise(rb_eArgError, "Block or Proc is required.");
+    if (given) {
+	doc = ALLOCA_N(struct _Doc, 1);
+    } else {
+	doc = ALLOC_N(struct _Doc, 1);
     }
     pi.str = json;
     pi.s = pi.str;
-    doc_init(&doc);
-    pi.doc = &doc;
-    doc.self = rb_obj_alloc(clas);
-    DATA_PTR(doc.self) = pi.doc;
+    doc_init(doc);
+    pi.doc = doc;
+    doc->self = rb_obj_alloc(clas);
+    doc->json = json;
+    DATA_PTR(doc->self) = doc;
     result = rb_protect(protect_open_proc, (VALUE)&pi, &ex);
-    DATA_PTR(doc.self) = 0;
-    doc_free(pi.doc);
-    //xfree(pi.str);
+    if (given || 0 != ex) {
+	DATA_PTR(doc->self) = 0;
+	doc_free(pi.doc);
+	if (allocated) {
+	    xfree(json);
+	}
+    } else {
+	result = doc->self;
+    }
     if (0 != ex) {
 	rb_jump_tag(ex);
     }
@@ -1014,32 +1073,51 @@ each_value(Doc doc, Leaf leaf) {
 
 /* call-seq: open(json) { |doc| ... } => Object
  *
- * Parses a JSON document String and then yields to the provided block with an
- * instance of the Oj::Doc as the single yield parameter.
+ * Parses a JSON document String and then yields to the provided block if one
+ * is given with an instance of the Oj::Doc as the single yield parameter. If
+ * a block is not given then an Oj::Doc instance is returned and must be
+ * closed with a call to the #close() method when no longer needed.
  *
  * @param [String] json JSON document string
  * @yieldparam [Oj::Doc] doc parsed JSON document
  * @yieldreturn [Object] returns the result of the yield as the result of the method call
  * @example
  *   Oj::Doc.open('[1,2,3]') { |doc| doc.size() }  #=> 4
+ *   # or as an alternative
+ *   doc = Oj::Doc.open('[1,2,3]')
+ *   doc.size()  #=> 4
+ *   doc.close()
  */
 static VALUE
 doc_open(VALUE clas, VALUE str) {
     char	*json;
     size_t	len;
+    VALUE	obj;
+    int		given = rb_block_given_p();
+    int		allocate;
 
     Check_Type(str, T_STRING);
     len = RSTRING_LEN(str) + 1;
-    json = ALLOCA_N(char, len);
+    allocate = (SMALL_XML < len || !given);
+    if (allocate) {
+	json = ALLOC_N(char, len);
+    } else {
+	json = ALLOCA_N(char, len);
+    }
     memcpy(json, StringValuePtr(str), len);
-
-    return parse_json(clas, json);
+    obj = parse_json(clas, json, given, allocate);
+    if (given && allocate) {
+	xfree(json);
+    }
+    return obj;
 }
 
 /* call-seq: open_file(filename) { |doc| ... } => Object
  *
- * Parses a JSON document from a file and then yields to the provided block
- * with an instance of the Oj::Doc as the single yield parameter.
+ * Parses a JSON document from a file and then yields to the provided block if
+ * one is given with an instance of the Oj::Doc as the single yield
+ * parameter. If a block is not given then an Oj::Doc instance is returned and
+ * must be closed with a call to the #close() method when no longer needed.
  *
  * @param [String] filename name of file that contains a JSON document
  * @yieldparam [Oj::Doc] doc parsed JSON document
@@ -1047,6 +1125,10 @@ doc_open(VALUE clas, VALUE str) {
  * @example
  *   File.open('array.json', 'w') { |f| f.write('[1,2,3]') }
  *   Oj::Doc.open_file(filename) { |doc| doc.size() }  #=> 4
+ *   # or as an alternative
+ *   doc = Oj::Doc.open_file(filename)
+ *   doc.size()  #=> 4
+ *   doc.close()
  */
 static VALUE
 doc_open_file(VALUE clas, VALUE filename) {
@@ -1054,6 +1136,9 @@ doc_open_file(VALUE clas, VALUE filename) {
     char	*json;
     FILE	*f;
     size_t	len;
+    VALUE	obj;
+    int		given = rb_block_given_p();
+    int		allocate;
 
     Check_Type(filename, T_STRING);
     path = StringValuePtr(filename);
@@ -1062,7 +1147,12 @@ doc_open_file(VALUE clas, VALUE filename) {
     }
     fseek(f, 0, SEEK_END);
     len = ftell(f);
-    json = ALLOCA_N(char, len + 1);
+    allocate = (SMALL_XML < len || !given);
+    if (allocate) {
+	json = ALLOC_N(char, len + 1);
+    } else {
+	json = ALLOCA_N(char, len + 1);
+    }
     fseek(f, 0, SEEK_SET);
     if (len != fread(json, 1, len, f)) {
         fclose(f);
@@ -1070,8 +1160,11 @@ doc_open_file(VALUE clas, VALUE filename) {
     }
     fclose(f);
     json[len] = '\0';
-
-    return parse_json(clas, json);
+    obj = parse_json(clas, json, given, allocate);
+    if (given && allocate) {
+	xfree(json);
+    }
+    return obj;
 }
 
 /* Document-method: parse
@@ -1085,7 +1178,7 @@ doc_open_file(VALUE clas, VALUE filename) {
  */
 static VALUE
 doc_where(VALUE self) {
-    Doc	doc = DATA_PTR(self);
+    Doc	doc = self_doc(self);
 
     if (0 == *doc->where_path || doc->where == doc->where_path) {
 	return oj_slash_string;
@@ -1116,7 +1209,7 @@ doc_where(VALUE self) {
 	    *p++ = '/';
 	}
 	*--p = '\0';
-	return rb_str_new2(path);
+	return rb_str_new(path, p - path);
     }
 }
 
@@ -1130,7 +1223,7 @@ doc_where(VALUE self) {
  */
 static VALUE
 doc_local_key(VALUE self) {
-    Doc		doc = DATA_PTR(self);
+    Doc		doc = self_doc(self);
     Leaf	leaf = *doc->where;
     VALUE	key = Qnil;
 
@@ -1156,7 +1249,7 @@ doc_local_key(VALUE self) {
  */
 static VALUE
 doc_home(VALUE self) {
-    Doc	doc = DATA_PTR(self);
+    Doc	doc = self_doc(self);
 
     *doc->where_path = doc->data;
     doc->where = doc->where_path;
@@ -1177,7 +1270,7 @@ doc_home(VALUE self) {
  */
 static VALUE
 doc_type(int argc, VALUE *argv, VALUE self) {
-    Doc		doc = DATA_PTR(self);
+    Doc		doc = self_doc(self);
     Leaf	leaf;
     const char	*path = 0;
     VALUE	type = Qnil;
@@ -1216,7 +1309,7 @@ doc_type(int argc, VALUE *argv, VALUE self) {
  */
 static VALUE
 doc_fetch(int argc, VALUE *argv, VALUE self) {
-    Doc		doc = DATA_PTR(self);
+    Doc		doc = self_doc(self);
     Leaf	leaf;
     VALUE	val = Qnil;
     const char	*path = 0;
@@ -1253,7 +1346,7 @@ static VALUE
 doc_each_leaf(int argc, VALUE *argv, VALUE self) {
     if (rb_block_given_p()) {
 	Leaf		save_path[MAX_STACK];
-	Doc		doc = DATA_PTR(self);
+	Doc		doc = self_doc(self);
 	const char	*path = 0;
 	size_t		wlen;
 
@@ -1287,7 +1380,7 @@ doc_each_leaf(int argc, VALUE *argv, VALUE self) {
  */
 static VALUE
 doc_move(VALUE self, VALUE str) {
-    Doc		doc = DATA_PTR(self);
+    Doc		doc = self_doc(self);
     const char	*path;
     int		loc;
 
@@ -1323,7 +1416,7 @@ static VALUE
 doc_each_child(int argc, VALUE *argv, VALUE self) {
     if (rb_block_given_p()) {
 	Leaf		save_path[MAX_STACK];
-	Doc		doc = DATA_PTR(self);
+	Doc		doc = self_doc(self);
 	const char	*path = 0;
 	size_t		wlen;
 
@@ -1383,7 +1476,7 @@ doc_each_child(int argc, VALUE *argv, VALUE self) {
 static VALUE
 doc_each_value(int argc, VALUE *argv, VALUE self) {
     if (rb_block_given_p()) {
-	Doc		doc = DATA_PTR(self);
+	Doc		doc = self_doc(self);
 	const char	*path = 0;
 	Leaf		leaf;
 
@@ -1412,7 +1505,7 @@ doc_each_value(int argc, VALUE *argv, VALUE self) {
  */
 static VALUE
 doc_dump(int argc, VALUE *argv, VALUE self) {
-    Doc		doc = DATA_PTR(self);
+    Doc		doc = self_doc(self);
     Leaf	leaf;
     const char	*path = 0;
     const char	*filename = 0;
@@ -1457,6 +1550,26 @@ doc_size(VALUE self) {
     return ULONG2NUM(((Doc)DATA_PTR(self))->size);
 }
 
+/* call-seq: close() => nil
+ *
+ * Closes an open document. No further calls to the document will be valid
+ * after closing.
+ * @example
+ *   doc = Oj::Doc.open('[1,2,3]')
+ *   doc.size()  #=> 4
+ *   doc.close()
+ */
+static VALUE
+doc_close(VALUE self) {
+    Doc		doc = self_doc(self);
+
+    DATA_PTR(doc->self) = 0;
+    xfree(doc->json);
+    doc_free(doc);
+
+    return Qnil;
+}
+
 /* Document-class: Oj::Doc
  *
  * The Doc class is used to parse and navigate a JSON document. The model it
@@ -1498,8 +1611,10 @@ doc_size(VALUE self) {
  *   end
  *   #=> 2
  *   
- *   # Now try again using a path to Oj::Doc.fetch() directly.
- *   Oj::Doc.open(json) { |doc| doc.fetch('/2/three') }  #=> 3
+ *   # Now try again using a path to Oj::Doc.fetch() directly and not using a block.
+ *   doc = Oj::Doc.open(json)
+ *   doc.fetch('/2/three')  #=> 3
+ *   doc.close()
  */
 void
 oj_init_doc() {
@@ -1518,4 +1633,5 @@ oj_init_doc() {
     rb_define_method(oj_doc_class, "each_value", doc_each_value, -1);
     rb_define_method(oj_doc_class, "dump", doc_dump, -1);
     rb_define_method(oj_doc_class, "size", doc_size, 0);
+    rb_define_method(oj_doc_class, "close", doc_close, 0);
 }