class JSON::PullParser
inherits Reference
¶
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.
Class methods¶
.new(input)
¶
View source
(input)
Methods¶
#location : Tuple(Int32, Int32)
¶
: Tuple(Int32, Int32)
Returns the current location.
The location is a tuple {line number, column number}.
#on_key(key, & : self -> _)
¶
(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 -> _)
¶
(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.
#read?(klass : Bool.class)
¶
View source
(klass : Bool.class)
#read?(klass : Int16.class)
¶
(klass : Int16.class)
Reads an Int16 value and returns it.
If the value is not an integer or does not fit in a Int16 variable, it returns nil.
#read?(klass : Int32.class)
¶
(klass : Int32.class)
Reads an Int32 value and returns it.
If the value is not an integer or does not fit in a Int32 variable, it returns nil.
#read?(klass : Int64.class)
¶
(klass : Int64.class)
Reads an Int64 value and returns it.
If the value is not an integer or does not fit in a Int64 variable, it returns nil.
#read?(klass : UInt8.class)
¶
(klass : UInt8.class)
Reads an UInt8 value and returns it.
If the value is not an integer or does not fit in a UInt8 variable, it returns nil.
#read?(klass : Int8.class)
¶
(klass : Int8.class)
Reads an Int8 value and returns it.
If the value is not an integer or does not fit in a Int8 variable, it returns nil.
#read?(klass : UInt16.class)
¶
(klass : UInt16.class)
Reads an UInt16 value and returns it.
If the value is not an integer or does not fit in a UInt16 variable, it returns nil.
#read?(klass : UInt32.class)
¶
(klass : UInt32.class)
Reads an UInt32 value and returns it.
If the value is not an integer or does not fit in a UInt32 variable, it returns nil.
#read?(klass : UInt64.class)
¶
(klass : UInt64.class)
Reads an Int64 value and returns it.
If the value is not an integer or does not fin in an Int64 variable, it returns nil.
#read?(klass : Float32.class)
¶
(klass : Float32.class)
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)
¶
(klass : Float64.class)
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)
¶
View source
(klass : String.class)
#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_float
¶
Reads a float value.
If the value is actually an integer, it is converted to float.
#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_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_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_raw(json)
¶
(json)
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.
#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.