Class: Yajl::Parser

Inherits:

Object

• Object
• Yajl::Parser

Defined in:

ext/yajl/yajl_ext.c,
lib/yajl.rb,
ext/yajl/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

• .new(*args) ⇒ Object

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

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

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

Instance Method Summary

• #<<(chunk) ⇒ Object

  call-seq: parse_chunk(string_chunk).

• #initialize(*args) ⇒ Object constructor

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

• #on_parse_complete=(callback) ⇒ Object

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

• #parse(*args) ⇒ Object

  call-seq: parse(input, buffer_size=8092) parse(input, buffer_size=8092) { |obj| … }.

• #parse_chunk(chunk) ⇒ Object

  call-seq: parse_chunk(string_chunk).

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.

# File 'ext/yajl/yajl_ext.c', line 416

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.

# File 'ext/yajl/yajl_ext.c', line 371

static VALUE rb_yajl_parser_new(int argc, VALUE * argv, VALUE klass) {
    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, sym_allow_comments) == Qfalse) {
            allowComments = 0;
        }
        if (rb_hash_aref(opts, sym_check_utf8) == Qfalse) {
            checkUTF8 = 0;
        }
        if (rb_hash_aref(opts, sym_symbolize_keys) == Qtrue) {
            symbolizeKeys = 1;
        }
    }
    cfg = (yajl_parser_config){allowComments, checkUTF8};

    obj = Data_Make_Struct(klass, 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(str_or_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

# File 'lib/yajl.rb', line 35

def self.parse(str_or_io, options={}, read_bufsize=nil, &block)
  new(options).parse(str_or_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.

# File 'ext/yajl/yajl_ext.c', line 498

static VALUE rb_yajl_parser_parse_chunk(VALUE self, VALUE chunk) {
    yajl_parser_wrapper * wrapper;
    unsigned int len;

    GetParser(self, wrapper);
    if (NIL_P(chunk)) {
        rb_raise(cParseError, "Can't parse a nil string.");
    }

    if (wrapper->parse_complete_callback != Qnil) {
        const char * cptr = RSTRING_PTR(chunk);
        len = RSTRING_LEN(chunk);
        yajl_parse_chunk((const unsigned char*)cptr, len, 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

# File 'ext/yajl/yajl_ext.c', line 527

static VALUE rb_yajl_parser_set_complete_cb(VALUE self, VALUE callback) {
    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.

# File 'ext/yajl/yajl_ext.c', line 441

static VALUE rb_yajl_parser_parse(int argc, VALUE * argv, VALUE self) {
    yajl_status stat;
    yajl_parser_wrapper * wrapper;
    VALUE rbufsize, input, blk;
    unsigned int len;
    const char * cptr;

    GetParser(self, wrapper);

    /* 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) {
        cptr = RSTRING_PTR(input);
        len = RSTRING_LEN(input);
        yajl_parse_chunk((const unsigned char*)cptr, len, wrapper->parser);
    } else if (rb_respond_to(input, intern_io_read)) {
        VALUE parsed = rb_str_new(0, FIX2LONG(rbufsize));
        while (rb_funcall(input, intern_io_read, 2, rbufsize, parsed) != Qnil) {
            cptr = RSTRING_PTR(parsed);
            len = RSTRING_LEN(parsed);
            yajl_parse_chunk((const unsigned char*)cptr, len, 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.

# File 'ext/yajl/yajl_ext.c', line 498

static VALUE rb_yajl_parser_parse_chunk(VALUE self, VALUE chunk) {
    yajl_parser_wrapper * wrapper;
    unsigned int len;

    GetParser(self, wrapper);
    if (NIL_P(chunk)) {
        rb_raise(cParseError, "Can't parse a nil string.");
    }

    if (wrapper->parse_complete_callback != Qnil) {
        const char * cptr = RSTRING_PTR(chunk);
        len = RSTRING_LEN(chunk);
        yajl_parse_chunk((const unsigned char*)cptr, len, wrapper->parser);
    } else {
        rb_raise(cParseError, "The on_parse_complete callback isn't setup, parsing useless.");
    }

    return Qnil;
}