yajl-ruby

You can use yajl-ruby as a replacement for the standard Ruby json gem by requiring yajl/json_gem. This enables compatibility for the following methods:

• JSON.parse
• JSON.generate
• JSON.pretty_generate
• JSON.load
• JSON.dump
• #to_json instance method overrides for Ruby primitives

require 'yajl/json_gem'

You can install the gem via the command line or include it in your Gemfile. When using a Gemfile, use the require: 'yajl' option to ensure the library is loaded correctly.

gem install yajl-ruby

gem 'yajl-ruby', require: 'yajl'

The Yajl::HttpStream module allows making HTTP requests where the response bodies are streamed directly into the Yajl parser. This is useful for processing large JSON payloads without loading the entire response into memory.

Supported HTTP methods include get, post, put, and delete. You can provide a block to the method, which will be called with the constructed object once a full JSON object has been parsed from the stream.

The following extensions are not loaded automatically to keep the footprint small. You can require them manually if needed:

• yajl/http_stream for Yajl::HttpStream
• yajl/gzip for Yajl::Gzip
• yajl/deflate for Yajl::Deflate
• yajl/bzip2 for Yajl::Bzip2

To compress the JSON stream while encoding (e.g., for network transmission), use Yajl::Gzip::StreamWriter or Yajl::Deflate::StreamWriter.

require 'yajl/gzip'
socket = TCPSocket.new('192.168.1.101', 9000)
hash = {:foo => 12425125, :bar => "some string"}
Yajl::Gzip::StreamWriter.encode(hash, socket)

You can parse JSON directly from compressed files using the Yajl::Bzip2::StreamReader class.

require 'yajl/bzip2'

file = File.new('some.json.bz2', 'r')
result = Yajl::Bzip2::StreamReader.parse(file)

Use Yajl::Encoder.encode to convert Ruby objects to JSON. You can encode directly to an IO object (like a socket) to stream the output in chunks. If you do not provide an IO object or a block, it returns the JSON as a String.

# Encode directly to an IO (e.g., a socket)
socket = TCPSocket.new('192.168.1.101', 9000)
hash = {:foo => 12425125, :bar => "some string"}
Yajl::Encoder.encode(hash, socket)

# Encode multiple objects to the same stream
socket = TCPSocket.new('192.168.1.101', 9000)
encoder = Yajl::Encoder.new
50.times do
  hash = {:current_time => Time.now.to_f, :foo => 12425125}
  encoder.encode(hash, socket)
end

# Encode to a String
str = Yajl::Encoder.encode(obj)

If you are receiving JSON data in chunks (e.g., from a network socket or an event loop like EventMachine), you can use the << operator on a Yajl::Parser instance to feed it data. Use the on_parse_complete callback to handle the Ruby object once a full JSON object has been successfully parsed from the stream.

# Example of incremental chunk parsing
@parser = Yajl::Parser.new(:symbolize_keys => true)

@parser.on_parse_complete = method(:object_parsed)

def object_parsed(obj)
  puts obj.inspect
end

def receive_data(data)
  @parser << data
end

Use Yajl::Parser#parse to convert JSON from a File, StringIO, or any IO object into a Ruby object. For simple cases where you have the entire string or IO ready, you can use the class method Yajl::Parser.parse(str_or_io).

# From a File
json = File.new('test.json', 'r')
parser = Yajl::Parser.new
hash = parser.parse(json)

# From a StringIO
json = StringIO.new("...some JSON...")
parser = Yajl::Parser.new
hash = parser.parse(json)

# Simple class method
obj = Yajl::Parser.parse(str_or_io)

When using Yajl::HttpStream, be prepared to rescue the following exceptions:

• Yajl::HttpStream::InvalidContentType: Raised when the HTTP response Content-Type is not in the ALLOWED_MIME_TYPES list (application/json or text/plain).
• Yajl::HttpStream::HttpError: Raised when the HTTP response code is not 200 OK. This error object contains the response message and headers.