Class: Oj::Doc

Inherits:

Object

• Object
• Oj::Doc

Defined in:

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

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

Instance Method Summary

• #clone ⇒ Object
• #close ⇒ Object
• #dump(*args) ⇒ Object
• #dup ⇒ Object
• #each_child(*args) ⇒ Object
• #each_leaf(*args) ⇒ Object
• #each_value(*args) ⇒ Object
• #exists?(str) ⇒ Object
• #fetch(*args) ⇒ Object
• #home ⇒ Object
• #local_key ⇒ Object
• #move(str) ⇒ Object
• #path ⇒ Object
• #size ⇒ Object
• #type(*args) ⇒ Object
• #where ⇒ Object
• #where? ⇒ Object

Class Method Details

.open(str) ⇒ Object

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

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  = RSTRING_LEN(str) + 1;
    json = OJ_R_ALLOC_N(char, len);

    memcpy(json, StringValuePtr(str), len);
    obj = parse_json(clas, json, given);
    // json is owned by the doc and freed by doc_free(); do not free it here.
    return obj;
}

.open_file(filename) ⇒ Object

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

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);
    // Open in binary mode. On Windows a text mode read translates CRLF into LF
    // so fewer bytes are read than the file size reported by ftell().
    if (0 == (f = fopen(path, "rb"))) {
        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);
    // json is owned by the doc and freed by doc_free(); do not free it here.
    return obj;
}

.parse(str) ⇒ Object

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

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  = RSTRING_LEN(str) + 1;
    json = OJ_R_ALLOC_N(char, len);

    memcpy(json, StringValuePtr(str), len);
    obj = parse_json(clas, json, given);
    // json is owned by the doc and freed by doc_free(); do not free it here.
    return obj;
}

Instance Method Details

#clone ⇒ Object

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

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

#close ⇒ Object

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

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(*args) ⇒ Object

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

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 1700

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

#each_child(*args) ⇒ Object

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

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;

            if (MAX_STACK <= (doc->where + 1) - doc->where_path) {
                rb_raise(rb_const_get_at(Oj, rb_intern("DepthError")), "Path too deep. Limit is %d levels.", MAX_STACK);
            }
            doc->where++;
            do {
                *doc->where = e;
                rb_yield(self);
                if (NULL == DATA_PTR(self)) {
                    rb_raise(rb_eIOError, "Document closed.");
                }
                e = e->next;
            } while (e != first);
            doc->where--;
        }
        if (0 < wlen) {
            memcpy(doc->where_path, save_path, sizeof(Leaf) * (wlen + 1));
        }
        doc->where = where_orig;
    }
    return Qnil;
}

#each_leaf(*args) ⇒ Object

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

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;
            }
        }
        if (NULL == doc->where || NULL == *doc->where) {
            return Qnil;
        }
        each_leaf(doc, self);
        if (0 < wlen) {
            memcpy(doc->where_path, save_path, sizeof(Leaf) * (wlen + 1));
        }
    }
    return Qnil;
}

#each_value(*args) ⇒ Object

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

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, self);
        }
    }
    return Qnil;
}

#exists?(str) ⇒ Object

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

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(*args) ⇒ Object

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

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

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

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

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

static VALUE doc_local_key(VALUE self) {
    Doc            doc = self_doc(self);
    Leaf           leaf;
    volatile VALUE key = Qnil;

    if (NULL == doc->where || NULL == *doc->where) {
        return Qnil;
    }
    leaf = *doc->where;
    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(str) ⇒ Object

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

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

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

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

#size ⇒ Object

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

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

#type(*args) ⇒ Object

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

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

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

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? ⇒ Object

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

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