class

JSON::PullParser

Inherits Reference / Object

This class allows you to consume JSON on demand, token by token.

Each read_* method consumes the next token. Sometimes it consumes only one token (like read_begin_array), sometimes it consumes a full valid value (like read_array).

You must be careful when calling those methods, as they move forward into the JSON input you are pulling. Calling read_string twice will return the next two strings (if possible), not twice the same.

If you try to read a token which is not the one currently under the cursor location, an exception ParseException will be raised.

Example:

input = %(
  {
    "type": "event",
    "values": [1, 4, "three", 10]
  }
)
pull = JSON::PullParser.new(input)
pull.read_begin_object
pull.read_object_key # => "type"
pull.read_string     # => "event"
# Actually you can also use `read_string` to read a key
pull.read_string # => "values"
pull.read_begin_array
pull.read_int    # => 1
pull.read_int    # => 4
pull.read_string # => "three"
pull.read_int    # => 10
pull.read_end_array
pull.read_end_object

Another example reading the same object:

pull = JSON::PullParser.new(input)
pull.read_object do |key|
  case key
  when "type"
    pull.read_string # => "event"
  when "values"
    pull.read_array do
      if v = pull.read?(Int8)
        v
      else
        pull.read_string
      end
    end
  end
end

This example fails:

pull = JSON::PullParser.new(input)
pull.read_begin_object
pull.read_object_key # => "type"
pull.read_string     # => "event"
pull.read_end_object # => raise an exception. The current token is a string ("values"), not the end of an object.

Constructors

new(input)

Creates a PullParser which will consume the JSON input.

input must be a String or an IO.

Instance methods

bool_value

column_number

Returns the current column number.

column_number_i64

Returns the current column number.

float_value

int_value

kind

line_number

Returns the current line number.

line_number_i64

Returns the current line number.

location

Returns the current location.

The location is a tuple {line number, column number}.

location_i64

Returns the current location.

The location is a tuple {line number, column number}.

max_nesting

max_nesting=(max_nesting : Int32)

on_key(key, & : self -> _)

Reads an object keys and yield when key is found.

All the other object keys are skipped.

Returns the return value of the block or Nil if the key was not read.

on_key!(key, & : self -> _)

Reads an object keys and yield when key is found. If not found, raise an Exception.

All the other object keys are skipped.

Returns the return value of the block.

raise(message : String) : NoReturn

Raises ParseException with message at current location.

raw_value

read?(klass : Bool.class) : Bool | Nil

Reads a Bool value and returns it.

If the value is not a Bool, returns nil.

read?(klass : Int128.class) : Int128 | Nil

Reads an Int128 value and returns it.

If the value is not an integer or does not fit in an Int128, it returns nil.

read?(klass : Int16.class) : Int16 | Nil

Reads an Int16 value and returns it.

If the value is not an integer or does not fit in an Int16, it returns nil.

read?(klass : Int32.class) : Int32 | Nil

Reads an Int32 value and returns it.

If the value is not an integer or does not fit in an Int32, it returns nil.

read?(klass : Int64.class) : Int64 | Nil

Reads an Int64 value and returns it.

If the value is not an integer or does not fit in an Int64, it returns nil.

read?(klass : Int8.class) : Int8 | Nil

Reads an Int8 value and returns it.

If the value is not an integer or does not fit in an Int8, it returns nil.

read?(klass : UInt128.class) : UInt128 | Nil

Reads an UInt128 value and returns it.

If the value is not an integer or does not fit in an UInt128, it returns nil.

read?(klass : UInt16.class) : UInt16 | Nil

Reads an UInt16 value and returns it.

If the value is not an integer or does not fit in an UInt16, it returns nil.

read?(klass : UInt32.class) : UInt32 | Nil

Reads an UInt32 value and returns it.

If the value is not an integer or does not fit in an UInt32, it returns nil.

read?(klass : UInt64.class) : UInt64 | Nil

Reads an UInt64 value and returns it.

If the value is not an integer or does not fit in an UInt64, it returns nil.

read?(klass : UInt8.class) : UInt8 | Nil

Reads an UInt8 value and returns it.

If the value is not an integer or does not fit in an UInt8, it returns nil.

read?(klass : Float32.class) : Float32 | Nil

Reads an Float32 value and returns it.

If the value is not an integer or does not fit in an Float32, it returns nil. If the value was actually an integer, it is converted to a float.

read?(klass : Float64.class) : Float64 | Nil

Reads an Float64 value and returns it.

If the value is not an integer or does not fit in a Float64 variable, it returns nil. If the value was actually an integer, it is converted to a float.

read?(klass : String.class) : String | Nil

Reads a String value and returns it.

If the value is not a String, returns nil.

read_array

Reads a whole array.

It reads the beginning of the array, yield each value of the array, and reads the end of the array. You have to consumes the values, if any, so the pull parser does not fail when reading the end of the array.

If the array is empty, it does not yield.

read_array_or_null

Reads an array or a null value, and returns it.

read_begin_array

Reads the beginning of an array.

read_begin_object

Reads the beginning of an object.

read_bool

Reads a Bool value.

read_bool_or_null

Reads a Bool or a null value, and returns it.

read_end_array

Reads the end of an array.

read_end_object

Reads the end of an object.

read_float

Reads a float value.

If the value is actually an integer, it is converted to float.

read_float_or_null

Reads a float or a null value, and returns it.

read_int

Reads an integer value.

read_int_or_null

Reads an integer or a null value, and returns it.

read_next

Reads the next lexer's token.

Contrary to read_raw, it does not read a full value. For example if the next token is the beginning of an array, it will stop there, while read_raw would have read the whole array.

read_null

Reads a null value and returns it.

read_null?

Reads the current token if its value is null.

Returns true if the token was read.

read_null_or

Reads a null value and returns it, or executes the given block if the value is not null.

read_object

Reads a whole object.

It reads the beginning of the object, yield each key and key location, and reads the end of the object. You have to consumes the values, if any, so the pull parser does not fail when reading the end of the object.

If the object is empty, it does not yield.

read_object_key

Reads an object's key and returns it.

read_object_or_null

Reads an object or a null value, and returns it.

read_raw(json : JSON::Builder) : Nil

Reads the new value and fill the a JSON builder with it.

Use this method with a JSON::Builder to read a JSON while building another one.

read_raw

Read the next value and returns it.

The value is returned as a json string. If the value is an array or an object, it returns a string representing the full value. If the value in unknown, it raises a ParseException.

pull = JSON::PullParser.new %([null, true, 1, "foo", [1, "two"], {"foo": "bar"}])
pull.read_begin_array
pull.read_raw # => "null"
pull.read_raw # => "true"
pull.read_raw # => "1"
pull.read_raw # => "\"foo\""
pull.read_raw # => "[1,\"two\"]"
pull.read_raw # => "{\"foo\":\"bar\"}"
pull.read_end_array

read_string

Reads a string and returns it.

read_string_or_null

Reads a string or a null value, and returns it.

skip

Skips the next value.

It skips the whole value, not only the next lexer's token. For example if the next value is an array, the whole array will be skipped.

string_value

Nested types

JSON::PullParser::Kind