Class: Oj::Doc

Inherits:

Object

• Object
• Oj::Doc

Defined in:

ext/oj/fast.c,
ext/oj/fast.c more...

Overview

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.

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()

Examples:

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

Class Method Summary

• .open(json) ⇒ 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.

• .open_file(filename) ⇒ 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.

• .open(json) ⇒ 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.

Instance Method Summary

• #clone ⇒ Object
• #close ⇒ Object

  Closes an open document.

• #dump(path, filename) ⇒ Object

  Dumps the document or nodes to a new JSON document.

• #dup ⇒ Object
• #each_child(path = nil) ⇒ Object

  Yields to the provided block for each immediate child node with the identified location of the JSON document as the root.

• #each_leaf(path = nil) ⇒ Object

  Yields to the provided block for each leaf node with the identified location of the JSON document as the root.

• #each_value(path = nil) ⇒ Object

  Yields to the provided block for each leaf value in the identified location of the JSON document.

• #exists?(path) ⇒ Boolean

  Returns true if the value at the location identified by the path exists.

• #fetch(path = nil, default = nil) ⇒ Object

  Hash.

• #home ⇒ Object

  Moves the document marker or location to the hoot or home position.

• #local_key ⇒ Object

  Returns the final key to the current location.

• #move(path) ⇒ Object

  Moves the document marker to the path specified.

• #path ⇒ Object

  Returns a String that describes the absolute path to the current location in the JSON document.

• #size ⇒ Object

  Returns the number of nodes in the JSON document where a node is any one of the basic JSON components.

• #type(path = nil) ⇒ Object

  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.

• #where ⇒ Object

  Returns a String that describes the absolute path to the current location in the JSON document.

• #where? ⇒ Boolean deprecated Deprecated.

Class Method Details

.open(json) ⇒ 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

method call

Examples:

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()

Yield Parameters:

• doc (Oj::Doc) —

  parsed JSON document

Yield Returns:

• (Object) —

  returns the result of the yield as the result of the

# File 'ext/oj/fast.c', line 1082

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;
}

.open_file(filename) ⇒ 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

method call

Examples:

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()

Yield Parameters:

• doc (Oj::Doc) —

  parsed JSON document

Yield Returns:

• (Object) —

  returns the result of the yield as the result of the

# File 'ext/oj/fast.c', line 1122

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;
}

.open(json) ⇒ 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

method call

Examples:

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()

Yield Parameters:

• doc (Oj::Doc) —

  parsed JSON document

Yield Returns:

• (Object) —

  returns the result of the yield as the result of the

# File 'ext/oj/fast.c', line 1082

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;
}

Instance Method Details

#clone ⇒ Object

# File 'ext/oj/fast.c', line 1637

static VALUE doc_not_implemented(VALUE self) {
    rb_raise(rb_eNotImpError, "Not implemented.");
    return Qnil;
}

#close ⇒ Object

Closes an open document. No further calls to the document will be valid after closing.

Examples:

doc = Oj::Doc.open('[1,2,3]')
doc.size()  #=> 4
doc.close()

# File 'ext/oj/fast.c', line 1622

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;
}

#dump(path, filename) ⇒ Object

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

Examples:

Oj::Doc.open('[3,[2,1]]') { |doc|
    doc.dump('/2')
}
#=> "[2,1]"

# File 'ext/oj/fast.c', line 1563

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;
}

#dup ⇒ Object

# File 'ext/oj/fast.c', line 1637

static VALUE doc_not_implemented(VALUE self) {
    rb_raise(rb_eNotImpError, "Not implemented.");
    return Qnil;
}

#each_child(path = nil) ⇒ Object

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

Examples:

Oj::Doc.open('[3,[2,1]]') { |doc|
    result = []
    doc.each_value('/2') { |doc| result << doc.where? }
    result
}
#=> ["/2/1", "/2/2"]

Yield Parameters:

• Doc (Doc) —

  at the child location

# File 'ext/oj/fast.c', line 1461

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;
}

#each_leaf(path = nil) ⇒ Object

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

Examples:

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]

Yield Parameters:

• Doc (Doc) —

  at the child location

# File 'ext/oj/fast.c', line 1387

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;
}

#each_value(path = nil) ⇒ Object

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

Examples:

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]

Yield Parameters:

• val (Object) —

  each leaf value

# File 'ext/oj/fast.c', line 1533

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;
}

#exists?(path) ⇒ Boolean

Returns true if the value at the location identified by the path exists.

@param [String] path path to the location

Examples:

Oj::Doc.open('[1,2]') { |doc| doc.exists?('/1') }  #=> true
Oj::Doc.open('[1,2]') { |doc| doc.exists?('/3') }  #=> false

Returns:

• (Boolean)

# File 'ext/oj/fast.c', line 1358

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;
}

#fetch(path = nil, default = nil) ⇒ Object

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

Examples:

Oj::Doc.open('[1,2]') { |doc| doc.fetch() }      #=> [1, 2]
Oj::Doc.open('[1,2]') { |doc| doc.fetch('/1') }  #=> 1

# File 'ext/oj/fast.c', line 1331

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;
}

#home ⇒ Object

Moves the document marker or location to the hoot or home position. The same operation can be performed with a Oj::Doc.move(‘/’). #=> ‘/’

Examples:

Oj::Doc.open('[1,2,3]') { |doc| doc.move('/2'); doc.home(); doc.where? }

# File 'ext/oj/fast.c', line 1273

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;
}

#local_key ⇒ Object

Returns the final key to the current location. “one” Oj::Doc.open(‘’) { |doc| doc.local_key() } #=> nil

Examples:

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() }  #=>

# File 'ext/oj/fast.c', line 1252

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_utf8_str_new_cstr(leaf->key);
    } else if (T_ARRAY == leaf->parent_type) {
        key = LONG2NUM(leaf->index);
    }
    return key;
}

#move(path) ⇒ Object

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

“/one/2”

Examples:

Oj::Doc.open('{"one":[1,2]') { |doc| doc.move('/one/2'); doc.where? }  #=>

# File 'ext/oj/fast.c', line 1428

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;
}

#path ⇒ Object

Returns a String that describes the absolute path to the current location in the JSON document.

# File 'ext/oj/fast.c', line 1239

static VALUE doc_path(VALUE self) {
    return doc_where(self);
}

#size ⇒ Object

Returns the number of nodes in the JSON document where a node is any one of the basic JSON components.

Examples:

Oj::Doc.open('[1,2,3]') { |doc| doc.size() }  #=> 4

Returns:

• Returns the size of the JSON document.

# File 'ext/oj/fast.c', line 1607

static VALUE doc_size(VALUE self) {
    Doc d;
    TypedData_Get_Struct(self, struct _doc, &oj_doc_type, d);
    return ULONG2NUM(d->size);
}

#type(path = nil) ⇒ Object

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

Examples:

Oj::Doc.open('[1,2]') { |doc| doc.type() }	     #=> Array
Oj::Doc.open('[1,2]') { |doc| doc.type('/1') }  #=> Fixnum

# File 'ext/oj/fast.c', line 1293

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;
}

#where ⇒ Object

Returns a String that describes the absolute path to the current location in the JSON document.

# File 'ext/oj/fast.c', line 1188

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);
    }
}

#where? ⇒ Boolean

Deprecated.

Returns a String that describes the absolute path to the current location in the JSON document.

Returns:

• (Boolean)

# File 'ext/oj/fast.c', line 1230

static VALUE doc_where_q(VALUE self) {
    return doc_where(self);
}