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()
Class Method Summary collapse
-
.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 collapse
- #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
1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 |
# File 'ext/oj/fast.c', line 1088
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
1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 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 |
# File 'ext/oj/fast.c', line 1128
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();
Check_Type(filename, T_STRING);
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
1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 |
# File 'ext/oj/fast.c', line 1088
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
1656 1657 1658 1659 |
# File 'ext/oj/fast.c', line 1656 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.
1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 |
# File 'ext/oj/fast.c', line 1641
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
1582 1583 1584 1585 1586 1587 1588 1589 1590 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 |
# File 'ext/oj/fast.c', line 1582
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) {
Check_Type(*argv, T_STRING);
path = StringValuePtr(*argv);
}
if (2 <= argc) {
Check_Type(argv[1], T_STRING);
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
1656 1657 1658 1659 |
# File 'ext/oj/fast.c', line 1656 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
1478 1479 1480 1481 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 |
# File 'ext/oj/fast.c', line 1478
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) {
Check_Type(*argv, T_STRING);
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
1402 1403 1404 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 |
# File 'ext/oj/fast.c', line 1402
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) {
Check_Type(*argv, T_STRING);
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
1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 |
# File 'ext/oj/fast.c', line 1551
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) {
Check_Type(*argv, T_STRING);
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
1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 |
# File 'ext/oj/fast.c', line 1372
static VALUE doc_exists(VALUE self, VALUE str) {
Doc doc;
Leaf leaf;
doc = self_doc(self);
Check_Type(str, T_STRING);
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
1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 |
# File 'ext/oj/fast.c', line 1344
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) {
Check_Type(*argv, T_STRING);
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(‘/’). #=> ‘/’
1281 1282 1283 1284 1285 1286 1287 1288 |
# File 'ext/oj/fast.c', line 1281
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
1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 |
# File 'ext/oj/fast.c', line 1259
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;
}
|
#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”
1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 |
# File 'ext/oj/fast.c', line 1444
static VALUE doc_move(VALUE self, VALUE str) {
Doc doc = self_doc(self);
const char *path;
int loc;
Check_Type(str, T_STRING);
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.
1246 1247 1248 |
# File 'ext/oj/fast.c', line 1246 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.
1628 1629 1630 |
# File 'ext/oj/fast.c', line 1628
static VALUE doc_size(VALUE self) {
return ULONG2NUM(((Doc)DATA_PTR(self))->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
1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 |
# File 'ext/oj/fast.c', line 1301
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) {
Check_Type(*argv, T_STRING);
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;
#ifdef RUBY_INTEGER_UNIFICATION
case T_FIXNUM: type = rb_cInteger; break;
#else
case T_FIXNUM: type = rb_cFixnum; break;
#endif
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.
1195 1196 1197 1198 1199 1200 1201 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 |
# File 'ext/oj/fast.c', line 1195
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
Returns a String that describes the absolute path to the current location in the JSON document.
1237 1238 1239 |
# File 'ext/oj/fast.c', line 1237 static VALUE doc_where_q(VALUE self) { return doc_where(self); } |