Class: Yajl::Parser

Inherits:
Object show all
Defined in:
ext/yajl_ext.c,
lib/yajl.rb,
ext/yajl_ext.c

Overview

This class contains methods for parsing JSON directly from an IO object. The only basic requirment currently is that the IO object respond to #read(len) and #eof? The IO is parsed until a complete JSON object has been read and a ruby object will be returned.

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(*args) ⇒ Object

call-seq: new([:symbolize_keys => true, [:allow_comments => false[, :check_utf8 => false]]])

:symbolize_keys will turn hash keys into Ruby symbols, defaults to false.

:allow_comments will turn on/off the check for comments inside the JSON stream, defaults to true.

:check_utf8 will validate UTF8 characters found in the JSON stream, defaults to true.



329
330
331
 
# File 'ext/yajl_ext.c', line 329

static VALUE rb_yajl_parser_init(int argc, VALUE * argv, VALUE self) {
    return self;
}

Class Method Details

.new(*args) ⇒ Object

call-seq: new([:symbolize_keys => true, [:allow_comments => false[, :check_utf8 => false]]])

:symbolize_keys will turn hash keys into Ruby symbols, defaults to false.

:allow_comments will turn on/off the check for comments inside the JSON stream, defaults to true.

:check_utf8 will validate UTF8 characters found in the JSON stream, defaults to true.



284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
 
# File 'ext/yajl_ext.c', line 284

static VALUE rb_yajl_parser_new(int argc, VALUE * argv, VALUE klass) {
    struct yajl_parser_wrapper * wrapper;
    yajl_parser_config cfg;
    VALUE opts, obj;
    int allowComments = 1, checkUTF8 = 1, symbolizeKeys = 0;
    
    // Scan off config vars
    if (rb_scan_args(argc, argv, "01", &opts) == 1) {
        Check_Type(opts, T_HASH);
        
        if (rb_hash_aref(opts, ID2SYM(sym_allow_comments)) == Qfalse) {
            allowComments = 0;
        }
        if (rb_hash_aref(opts, ID2SYM(sym_check_utf8)) == Qfalse) {
            checkUTF8 = 0;
        }
        if (rb_hash_aref(opts, ID2SYM(sym_symbolize_keys)) == Qtrue) {
            symbolizeKeys = 1;
        }
    }
    cfg = (yajl_parser_config){allowComments, checkUTF8};
    
    obj = Data_Make_Struct(klass, struct yajl_parser_wrapper, yajl_parser_wrapper_mark, yajl_parser_wrapper_free, wrapper);
    wrapper->parser = yajl_alloc(&callbacks, &cfg, NULL, (void *)obj);
    wrapper->nestedArrayLevel = 0;
    wrapper->nestedHashLevel = 0;
    wrapper->objectsFound = 0;
    wrapper->symbolizeKeys = symbolizeKeys;
    wrapper->builderStack = rb_ary_new();
    wrapper->parse_complete_callback = Qnil;
    rb_obj_call_init(obj, 0, 0);
    return obj;
}

.parse(io, options = {}, read_bufsize = nil, &block) ⇒ Object

A helper method for parse-and-forget use-cases

io is the stream to parse JSON from

The options hash allows you to set two parsing options - :allow_comments and :check_utf8

:allow_comments accepts a boolean will enable/disable checks for in-line comments in the JSON stream

:check_utf8 accepts a boolean will enable/disable UTF8 validation for the JSON stream



28
29
30
 
# File 'lib/yajl.rb', line 28

def self.parse(io, options={}, read_bufsize=nil, &block)
  new(options).parse(io, read_bufsize, &block)
end

Instance Method Details

#<<(chunk) ⇒ Object

call-seq: parse_chunk(string_chunk)

string_chunk can be a partial or full JSON string to push on the parser.

This method will throw an exception if the on_parse_complete callback hasn’t been assigned yet. The on_parse_complete callback assignment is required so the user can handle objects that have been parsed off the stream as they’re found.



406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
 
# File 'ext/yajl_ext.c', line 406

static VALUE rb_yajl_parser_parse_chunk(VALUE self, VALUE chunk) {
    struct yajl_parser_wrapper * wrapper;
    
    GetParser(self, wrapper);
    if (NIL_P(chunk)) {
        rb_raise(cParseError, "Can't parse a nil string.");
        return Qnil;
    }
    
    if (wrapper->parse_complete_callback != Qnil) {
        yajl_parse_chunk((const unsigned char *)RSTRING_PTR(chunk), RSTRING_LEN(chunk), wrapper->parser);
    } else {
        rb_raise(cParseError, "The on_parse_complete callback isn't setup, parsing useless.");
    }

    return Qnil;
}

#on_parse_complete=(callback) ⇒ Object

call-seq: on_parse_complete = Proc.new { |obj| … }

This callback setter allows you to pass a Proc/lambda or any other object that responds to #call.

It will pass a single parameter, the ruby object built from the last parsed JSON object



433
434
435
436
437
438
 
# File 'ext/yajl_ext.c', line 433

static VALUE rb_yajl_parser_set_complete_cb(VALUE self, VALUE callback) {
    struct yajl_parser_wrapper * wrapper;
    GetParser(self, wrapper);
    wrapper->parse_complete_callback = callback;
    return Qnil;
}

#parse(*args) ⇒ Object

call-seq:

parse(input, buffer_size=8092)
parse(input, buffer_size=8092) { |obj| ... }

input can either be a string or an IO to parse JSON from

buffer_size is the size of chunk that will be parsed off the input (if it’s an IO) for each loop of the parsing process. 8092 is a good balance between the different types of streams (off disk, off a socket, etc…), but this option is here so the caller can better tune their parsing depending on the type of stream being passed. A larger read buffer will perform better for files off disk, where as a smaller size may be more efficient for reading off of a socket directly.

If a block was passed, it’s called when an object has been parsed off the stream. This is especially usefull when parsing a stream of multiple JSON objects.

NOTE: you can optionally assign the on_parse_complete callback, and it will be called the same way the optional block is for this method.



354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
 
# File 'ext/yajl_ext.c', line 354

static VALUE rb_yajl_parser_parse(int argc, VALUE * argv, VALUE self) {
    yajl_status stat;
    struct yajl_parser_wrapper * wrapper;
    VALUE parsed, rbufsize, input, blk;
    
    GetParser(self, wrapper);
    parsed = rb_str_new2("");
    
    // setup our parameters
    rb_scan_args(argc, argv, "11&", &input, &rbufsize, &blk);
    if (NIL_P(rbufsize)) {
        rbufsize = INT2FIX(READ_BUFSIZE);
    } else {
        Check_Type(rbufsize, T_FIXNUM);
    }
    if (!NIL_P(blk)) {
        rb_yajl_parser_set_complete_cb(self, blk);
    }
    
    if (TYPE(input) == T_STRING) {
        yajl_parse_chunk((const unsigned char *)RSTRING_PTR(input), RSTRING_LEN(input), wrapper->parser);
    } else if (rb_respond_to(input, intern_eof)) {
        while (rb_funcall(input, intern_eof, 0) != Qtrue) {
            rb_funcall(input, intern_io_read, 2, rbufsize, parsed);
            yajl_parse_chunk((const unsigned char *)RSTRING_PTR(parsed), RSTRING_LEN(parsed), wrapper->parser);
        }
    } else {
        rb_raise(cParseError, "input must be a string or IO");
    }
    
    // parse any remaining buffered data
    stat = yajl_parse_complete(wrapper->parser);
    
    if (wrapper->parse_complete_callback != Qnil) {
        yajl_check_and_fire_callback((void *)self);
        return Qnil;
    }

    return rb_ary_pop(wrapper->builderStack);
}

#parse_chunk(chunk) ⇒ Object

call-seq: parse_chunk(string_chunk)

string_chunk can be a partial or full JSON string to push on the parser.

This method will throw an exception if the on_parse_complete callback hasn’t been assigned yet. The on_parse_complete callback assignment is required so the user can handle objects that have been parsed off the stream as they’re found.



406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
 
# File 'ext/yajl_ext.c', line 406

static VALUE rb_yajl_parser_parse_chunk(VALUE self, VALUE chunk) {
    struct yajl_parser_wrapper * wrapper;
    
    GetParser(self, wrapper);
    if (NIL_P(chunk)) {
        rb_raise(cParseError, "Can't parse a nil string.");
        return Qnil;
    }
    
    if (wrapper->parse_complete_callback != Qnil) {
        yajl_parse_chunk((const unsigned char *)RSTRING_PTR(chunk), RSTRING_LEN(chunk), wrapper->parser);
    } else {
        rb_raise(cParseError, "The on_parse_complete callback isn't setup, parsing useless.");
    }

    return Qnil;
}