module MultiJson

A unified interface for JSON libraries in Ruby

MultiJson allows swapping between JSON backends without changing your code. It auto-detects available JSON libraries and uses the fastest one available.

@example Basic usage

MultiJson.load('{"foo":"bar"}')  #=> {"foo" => "bar"}
MultiJson.dump({foo: "bar"})     #=> '{"foo":"bar"}'

@example Specifying an adapter

MultiJson.use(:oj)
MultiJson.load('{"foo":"bar"}', adapter: :json_gem)

@api public

Constants

ALIASES: Legacy alias for adapter name mappings
REQUIREMENT_MAP: Maps adapter symbols to their require paths for auto-loading

Public Class Methods

adapter= (new_adapter)

Sets the adapter to use for JSON operations

@api private @return [Class] the loaded adapter class @example

MultiJson.adapter = :json_gem

Alias for: use

decode (string, options = {})

Parses a JSON string into a Ruby object

@api private @deprecated Use {.load} instead @return [Object] parsed Ruby object @example

MultiJson.decode('{"foo":"bar"}')  #=> {"foo" => "bar"}

Alias for: load

encode (object, options = {})

Serializes a Ruby object to a JSON string

@api private @deprecated Use {.dump} instead @return [String] JSON string @example

MultiJson.encode({foo: "bar"})  #=> '{"foo":"bar"}'

Alias for: dump

engine= (new_adapter)

Sets the adapter to use for JSON operations

@api private @deprecated Use {.adapter=} instead @return [Class] the loaded adapter class @example

MultiJson.engine = :json_gem

Alias for: use

with_engine (new_adapter)

Executes a block using the specified adapter

@api private @deprecated Use {.with_adapter} instead @return [Object] result of the block @example

MultiJson.with_engine(:json_gem) { MultiJson.dump({}) }

Alias for: with_adapter

Public Instance Methods

adapter ()

Returns the current adapter class

@api private @return [Class] the current adapter class @example

MultiJson.adapter  #=> MultiJson::Adapters::Oj

# File lib/multi_json.rb, line 99
def adapter
  @adapter ||= use(nil)
end

Also aliased as: engine

current_adapter (options = {})

Returns the adapter to use for the given options

@api private @param options [Hash] options that may contain :adapter key @return [Class] adapter class @example

MultiJson.current_adapter(adapter: :oj)  #=> MultiJson::Adapters::Oj

# File lib/multi_json.rb, line 180
def current_adapter(options = {})
  options ||= {}
  adapter_override = options[:adapter]
  adapter_override ? load_adapter(adapter_override) : adapter
end

default_options ()

Get the default options

@api private @deprecated Use {.load_options} or {.dump_options} instead @return [Hash] the current load options @example

MultiJson.default_options  #=> {}

# File lib/multi_json.rb, line 52
def default_options
  Kernel.warn "MultiJson.default_options is deprecated\n" \
              "Use MultiJson.load_options or MultiJson.dump_options instead"
  load_options
end

default_options= (value)

Set default options for both load and dump operations

@api private @deprecated Use {.load_options=} and {.dump_options=} instead @param value [Hash] options hash @return [Hash] the options hash @example

MultiJson.default_options = {symbolize_keys: true}

# File lib/multi_json.rb, line 39
def default_options=(value)
  Kernel.warn "MultiJson.default_options setter is deprecated\n" \
              "Use MultiJson.load_options and MultiJson.dump_options instead"
  self.load_options = self.dump_options = value
end

dump (object, options = {})

Serializes a Ruby object to a JSON string

@api private @param object [Object] object to serialize @param options [Hash] serialization options (adapter-specific) @return [String] JSON string @example

MultiJson.dump({foo: "bar"})  #=> '{"foo":"bar"}'

# File lib/multi_json.rb, line 194
def dump(object, options = {})
  current_adapter(options).dump(object, options)
end

Also aliased as: encode

engine ()

Returns the current adapter class (alias for adapter)

@api private @deprecated Use {.adapter} instead @return [Class] the current adapter class @example

MultiJson.engine  #=> MultiJson::Adapters::Oj

Alias for: adapter

load (string, options = {})

Parses a JSON string into a Ruby object

@api private @param string [String, read] JSON string or IO-like object @param options [Hash] parsing options (adapter-specific) @return [Object] parsed Ruby object @raise [ParseError] if parsing fails @example

MultiJson.load('{"foo":"bar"}')  #=> {"foo" => "bar"}

# File lib/multi_json.rb, line 156
def load(string, options = {})
  adapter_class = current_adapter(options)
  adapter_class.load(string, options)
rescue adapter_class::ParseError => e
  raise ParseError.build(e, string)
end

Also aliased as: decode

use (new_adapter)

Sets the adapter to use for JSON operations

@api private @param new_adapter [Symbol, String, Module, nil] adapter specification @return [Class] the loaded adapter class @example

MultiJson.use(:oj)

# File lib/multi_json.rb, line 119
def use(new_adapter)
  @adapter = load_adapter(new_adapter)
ensure
  OptionsCache.reset
end

Also aliased as: adapter=, engine=

with_adapter (new_adapter) { || ... }

Executes a block using the specified adapter

@api private @param new_adapter [Symbol, String, Module] adapter to use @yield block to execute with the temporary adapter @return [Object] result of the block @example

MultiJson.with_adapter(:json_gem) { MultiJson.dump({}) }

# File lib/multi_json.rb, line 216
def with_adapter(new_adapter)
  previous_adapter = adapter
  self.adapter = new_adapter
  yield
ensure
  self.adapter = previous_adapter
end

Also aliased as: with_engine