class Oj::Doc
The Doc
class is used to parse and navigate a JSON
document. The model it employs is that of a document that while open can be navigated and values extracted. Once the document is closed the document can not longer be accessed. This allows the parsing and data extraction to be extremely fast compared to other JSON
parses.
An Oj::Doc
class is not created directly but the _open()_ class method is used to open a document and the yield parameter to the block of the open() call is the Doc
instance. The Doc
instance can be moved across, up, and down the JSON
document. At each element the data associated with the element can be extracted. It is also possible to just provide a path to the data to be extracted and retrieve the data in that manner.
For many of the methods a path is used to describe the location of an element. Paths follow a subset of the XPath syntax. The slash (‘/’) character is the separator. Each step in the path identifies the next branch to take through the document. A JSON
object will expect a key string while an array will expect a positive index. A .. step indicates a move up the JSON
document.
@example
json = %{[ { "one" : 1, "two" : 2 }, { "three" : 3, "four" : 4 } ]} # move and get value Oj::Doc.open(json) do |doc| doc.move('/1/two') # doc location is now at the 'two' element of the hash that is the first
element of the array. doc.fetch() end
#=> 2 # 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()
Public Class Methods
@overload open(json) { |doc| … } => Object
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; volatile VALUE obj; int given = rb_block_given_p(); Check_Type(str, T_STRING); len = (int)RSTRING_LEN(str) + 1; json = OJ_R_ALLOC_N(char, len); memcpy(json, StringValuePtr(str), len); obj = parse_json(clas, json, given); // TBD is this needed /* if (given) { OJ_R_FREE(json); } */ return obj; }
@overload open_file
(filename) { |doc| … } => Object
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 @yieldreturn [Object] returns the result of the yield as the result of the method call @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) { char *path; char *json; FILE *f; size_t len; volatile VALUE obj; int given = rb_block_given_p(); path = StringValuePtr(filename); if (0 == (f = fopen(path, "r"))) { rb_raise(rb_eIOError, "%s", strerror(errno)); } fseek(f, 0, SEEK_END); len = ftell(f); json = OJ_R_ALLOC_N(char, len + 1); fseek(f, 0, SEEK_SET); if (len != fread(json, 1, len, f)) { fclose(f); rb_raise(rb_const_get_at(Oj, rb_intern("LoadError")), "Failed to read %lu bytes from %s.", (unsigned long)len, path); } fclose(f); json[len] = '\0'; obj = parse_json(clas, json, given); // TBD is this needed /* if (given) { OJ_R_FREE(json); } */ return obj; }
@see Oj::Doc.open
static VALUE doc_open(VALUE clas, VALUE str) { char *json; size_t len; volatile VALUE obj; int given = rb_block_given_p(); Check_Type(str, T_STRING); len = (int)RSTRING_LEN(str) + 1; json = OJ_R_ALLOC_N(char, len); memcpy(json, StringValuePtr(str), len); obj = parse_json(clas, json, given); // TBD is this needed /* if (given) { OJ_R_FREE(json); } */ return obj; }
Public Instance Methods
static VALUE doc_not_implemented(VALUE self) { rb_raise(rb_eNotImpError, "Not implemented."); return Qnil; }
@overload 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); rb_gc_unregister_address(&doc->self); DATA_PTR(doc->self) = NULL; if (0 != doc) { doc_free(doc); } return Qnil; }
@overload dump(path, filename)
Dumps the document or nodes to a new JSON
document. It uses the default options for generating the JSON
.
@param path [String] if provided it identified the top of the branch to
dump to JSON
@param filename [String] if provided it is the filename to write the output
to @example
Oj::Doc.open('[3,[2,1]]') { |doc| doc.dump('/2') } #=> "[2,1]"
static VALUE doc_dump(int argc, VALUE *argv, VALUE self) { Doc doc = self_doc(self); Leaf leaf; const char *path = 0; const char *filename = 0; if (1 <= argc) { if (Qnil != *argv) { path = StringValuePtr(*argv); } if (2 <= argc) { filename = StringValuePtr(argv[1]); } } if (0 != (leaf = get_doc_leaf(doc, path))) { volatile VALUE rjson; if (0 == filename) { struct _out out; oj_out_init(&out); out.omit_nil = oj_default_options.dump_opts.omit_nil; oj_dump_leaf_to_json(leaf, &oj_default_options, &out); rjson = rb_str_new2(out.buf); oj_out_free(&out); } else { oj_write_leaf_to_file(leaf, filename, &oj_default_options); rjson = Qnil; } return rjson; } return Qnil; }
@overload each_child
(path=nil) { |doc| … } => nil
Yields to the provided block for each immediate child node with the identified location of the JSON
document as the root. The parameter passed to the block on yield is the Doc
instance after moving to the child location.
@param [String] path if provided it identified the top of the branch to
process the children of @yieldparam [Doc] Doc
at the child location @example
Oj::Doc.open('[3,[2,1]]') { |doc| result = [] doc.each_value('/2') { |doc| result << doc.where? } result } #=> ["/2/1", "/2/2"]
static VALUE doc_each_child(int argc, VALUE *argv, VALUE self) { if (rb_block_given_p()) { Leaf save_path[MAX_STACK]; Doc doc = self_doc(self); const char *path = 0; size_t wlen; Leaf *where_orig = doc->where; wlen = doc->where - doc->where_path; if (0 < wlen) { memcpy(save_path, doc->where_path, sizeof(Leaf) * (wlen + 1)); } if (1 <= argc) { path = StringValuePtr(*argv); if ('/' == *path) { doc->where = doc->where_path; path++; } if (0 != move_step(doc, path, 1)) { if (0 < wlen) { memcpy(doc->where_path, save_path, sizeof(Leaf) * (wlen + 1)); } doc->where = where_orig; return Qnil; } } if (NULL == doc->where || NULL == *doc->where) { return Qnil; } if (COL_VAL == (*doc->where)->value_type && 0 != (*doc->where)->elements) { Leaf first = (*doc->where)->elements->next; Leaf e = first; doc->where++; do { *doc->where = e; rb_yield(self); e = e->next; } while (e != first); } if (0 < wlen) { memcpy(doc->where_path, save_path, sizeof(Leaf) * (wlen + 1)); } doc->where = where_orig; } return Qnil; }
@overload each_leaf
(path=nil) => nil
Yields to the provided block for each leaf node with the identified location of the JSON
document as the root. The parameter passed to the block on yield is the Doc
instance after moving to the child location.
@param [String] path if provided it identified the top of the branch to
process the leaves of @yieldparam [Doc] Doc
at the child location @example
Oj::Doc.open('[3,[2,1]]') { |doc| result = {} doc.each_leaf() { |d| result[d.where?] = d.fetch() } result } #=> ["/1" => 3, "/2/1" => 2, "/2/2" => 1]
static VALUE doc_each_leaf(int argc, VALUE *argv, VALUE self) { if (rb_block_given_p()) { Leaf save_path[MAX_STACK]; Doc doc = self_doc(self); const char *path = 0; size_t wlen; wlen = doc->where - doc->where_path; if (0 < wlen) { memcpy(save_path, doc->where_path, sizeof(Leaf) * (wlen + 1)); } if (1 <= argc) { path = StringValuePtr(*argv); if ('/' == *path) { doc->where = doc->where_path; path++; } if (0 != move_step(doc, path, 1)) { if (0 < wlen) { memcpy(doc->where_path, save_path, sizeof(Leaf) * (wlen + 1)); } return Qnil; } } each_leaf(doc, self); if (0 < wlen) { memcpy(doc->where_path, save_path, sizeof(Leaf) * (wlen + 1)); } } return Qnil; }
@overload each_value
(path=nil) { |val| … } => nil
Yields to the provided block for each leaf value in the identified location of the JSON
document. The parameter passed to the block on yield is the value of the leaf. Only those leaves below the element specified by the path parameter are processed.
@param [String] path if provided it identified the top of the branch to
process the leaf values of @yieldparam [Object] val each leaf value @example
Oj::Doc.open('[3,[2,1]]') { |doc| result = [] doc.each_value() { |v| result << v } result } #=> [3, 2, 1] Oj::Doc.open('[3,[2,1]]') { |doc| result = [] doc.each_value('/2') { |v| result << v } result } #=> [2, 1]
static VALUE doc_each_value(int argc, VALUE *argv, VALUE self) { if (rb_block_given_p()) { Doc doc = self_doc(self); const char *path = 0; Leaf leaf; if (1 <= argc) { path = StringValuePtr(*argv); } if (0 != (leaf = get_doc_leaf(doc, path))) { each_value(doc, leaf); } } return Qnil; }
@overload exists?(path) => true, false
Returns true if the value at the location identified by the path exists.
@param [String] path path to the location
@example
Oj::Doc.open('[1,2]') { |doc| doc.exists?('/1') } #=> true Oj::Doc.open('[1,2]') { |doc| doc.exists?('/3') } #=> false
static VALUE doc_exists(VALUE self, VALUE str) { Doc doc; Leaf leaf; doc = self_doc(self); if (0 != (leaf = get_doc_leaf(doc, StringValuePtr(str)))) { if (NULL != leaf) { return Qtrue; } } return Qfalse; }
@overload fetch(path=nil,default=nil) => nil, true, false, Fixnum, Float, String
, Array, Hash
Returns the value at the location identified by the path or the current location if the path is nil or not provided. This method will create and return an Array or Hash if that is the type of Object
at the location specified. This is more expensive than navigating to the leaves of the JSON
document. If a default is provided that is used if no value if found.
@param [String] path path to the location to get the type of if provided
@example
Oj::Doc.open('[1,2]') { |doc| doc.fetch() } #=> [1, 2] Oj::Doc.open('[1,2]') { |doc| doc.fetch('/1') } #=> 1
static VALUE doc_fetch(int argc, VALUE *argv, VALUE self) { Doc doc; Leaf leaf; volatile VALUE val = Qnil; const char *path = 0; doc = self_doc(self); if (1 <= argc) { path = StringValuePtr(*argv); if (2 == argc) { val = argv[1]; } } if (0 != (leaf = get_doc_leaf(doc, path))) { val = leaf_value(doc, leaf); } return val; }
@overload home() => nil
Moves the document marker or location to the hoot or home position. The same operation can be performed with a Oj::Doc.move
(‘/’). @example
Oj::Doc.open('[1,2,3]') { |doc| doc.move('/2'); doc.home(); doc.where? }
#=> ‘/’
static VALUE doc_home(VALUE self) { Doc doc = self_doc(self); *doc->where_path = doc->data; doc->where = doc->where_path; return oj_slash_string; }
@overload local_key
() => String
, Fixnum, nil
Returns the final key to the current location. @example
Oj::Doc.open('[1,2,3]') { |doc| doc.move('/2'); doc.local_key() } #=> 2 Oj::Doc.open('{"one":3}') { |doc| doc.move('/one'); doc.local_key() } #=>
“one” Oj::Doc.open('[1,2,3]
‘) { |doc| doc.local_key() } #=> nil
static VALUE doc_local_key(VALUE self) { Doc doc = self_doc(self); Leaf leaf = *doc->where; volatile VALUE key = Qnil; if (T_HASH == leaf->parent_type) { key = rb_str_new2(leaf->key); key = oj_encode(key); } else if (T_ARRAY == leaf->parent_type) { key = LONG2NUM(leaf->index); } return key; }
@overload move(path) => nil
Moves the document marker to the path specified. The path can an absolute path or a relative path.
@param [String] path path to the location to move to
@example
Oj::Doc.open('{"one":[1,2]') { |doc| doc.move('/one/2'); doc.where? } #=>
“/one/2”
static VALUE doc_move(VALUE self, VALUE str) { Doc doc = self_doc(self); const char *path; int loc; path = StringValuePtr(str); if ('/' == *path) { doc->where = doc->where_path; path++; } if (0 != (loc = move_step(doc, path, 1))) { rb_raise(rb_eArgError, "Failed to locate element %d of the path %s.", loc, path); } return Qnil; }
@overload size() => Fixnum
Returns the number of nodes in the JSON
document where a node is any one of the basic JSON
components. @return Returns the size of the JSON
document. @example
Oj::Doc.open('[1,2,3]') { |doc| doc.size() } #=> 4
static VALUE doc_size(VALUE self) { return ULONG2NUM(((Doc)DATA_PTR(self))->size); }
@overload type(path=nil) => Class
Returns the Class of the data value at the location identified by the path or the current location if the path is nil or not provided. This method does not create the Ruby Object
at the location specified so the overhead is low.
@param [String] path path to the location to get the type of if provided
@example
Oj::Doc.open('[1,2]') { |doc| doc.type() } #=> Array Oj::Doc.open('[1,2]') { |doc| doc.type('/1') } #=> Fixnum
static VALUE doc_type(int argc, VALUE *argv, VALUE self) { Doc doc = self_doc(self); Leaf leaf; const char *path = 0; VALUE type = Qnil; if (1 <= argc) { path = StringValuePtr(*argv); } if (0 != (leaf = get_doc_leaf(doc, path))) { switch (leaf->rtype) { case T_NIL: type = rb_cNilClass; break; case T_TRUE: type = rb_cTrueClass; break; case T_FALSE: type = rb_cFalseClass; break; case T_STRING: type = rb_cString; break; case T_FIXNUM: type = rb_cInteger; break; case T_FLOAT: type = rb_cFloat; break; case T_ARRAY: type = rb_cArray; break; case T_HASH: type = rb_cHash; break; default: break; } } return type; }
@overload where() => String
Returns a String
that describes the absolute path to the current location in the JSON
document.
static VALUE doc_where(VALUE self) { Doc doc = self_doc(self); if (0 == *doc->where_path || doc->where == doc->where_path) { return oj_slash_string; } else { Leaf *lp; Leaf leaf; size_t size = 3; // leading / and terminating \0 char *path; char *p; for (lp = doc->where_path; lp <= doc->where; lp++) { leaf = *lp; if (T_HASH == leaf->parent_type) { size += esc_strlen((*lp)->key) + 1; } else if (T_ARRAY == leaf->parent_type) { size += ((*lp)->index < 100) ? 3 : 11; } } path = ALLOCA_N(char, size); p = path; for (lp = doc->where_path; lp <= doc->where; lp++) { leaf = *lp; if (T_HASH == leaf->parent_type) { p = append_key(p, (*lp)->key); } else if (T_ARRAY == leaf->parent_type) { p = ulong_fill(p, (*lp)->index); } *p++ = '/'; } *--p = '\0'; return rb_str_new(path, p - path); } }