class Yajl::Parser - yajl-ruby-1.2.1 Documentation

# class Yajl::Parser

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.

### Public Class Methods

new([:symbolize_keys => true, [:allow_comments => false[, :check_utf8 → false]]]) click to toggle source

: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.

    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 || rb_hash_aref(opts, sym_symbolize_names) == 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) click to toggle source

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

### Public Instance Methods

parse_chunk(string_chunk) click to toggle source

`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.

    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 = Proc.new { |obj| ... } click to toggle source

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

    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(input, buffer_size=8092) click to toggle source
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.

    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(string_chunk) click to toggle source

`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.

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