Class: Oj::Doc

Inherits:
Object
  • Object
show all
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 collapse

Instance Method Summary collapse

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



1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
 
# File 'ext/oj/fast.c', line 1104

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

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



1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
 
# File 'ext/oj/fast.c', line 1139

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

.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



1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
 
# File 'ext/oj/fast.c', line 1104

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 



1665
1666
1667
1668
 
# File 'ext/oj/fast.c', line 1665

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


1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
 
# File 'ext/oj/fast.c', line 1650

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]"


1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
 
# File 'ext/oj/fast.c', line 1591

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 



1665
1666
1667
1668
 
# File 'ext/oj/fast.c', line 1665

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



1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
 
# File 'ext/oj/fast.c', line 1482

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



1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
 
# File 'ext/oj/fast.c', line 1405

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



1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
 
# File 'ext/oj/fast.c', line 1561

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


1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
 
# File 'ext/oj/fast.c', line 1376

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


1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
 
# File 'ext/oj/fast.c', line 1349

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


1291
1292
1293
1294
1295
1296
1297
1298
 
# File 'ext/oj/fast.c', line 1291

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('[1,2,3]') { |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() }  #=>


1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
 
# File 'ext/oj/fast.c', line 1266

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


1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
 
# File 'ext/oj/fast.c', line 1449

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.



1253
1254
1255
 
# File 'ext/oj/fast.c', line 1253

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.



1635
1636
1637
1638
1639
 
# File 'ext/oj/fast.c', line 1635

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


1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
 
# File 'ext/oj/fast.c', line 1311

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.



1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
 
# File 'ext/oj/fast.c', line 1202

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) 


1244
1245
1246
 
# File 'ext/oj/fast.c', line 1244

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