Module: MultiJson

Extended by:
AdapterSelector, Options
Defined in:
lib/multi_json.rb,
lib/multi_json/adapter.rb,
lib/multi_json/options.rb,
lib/multi_json/version.rb,
lib/multi_json/adapters/oj.rb,
lib/multi_json/parse_error.rb,
lib/multi_json/adapter_error.rb,
lib/multi_json/adapters/gson.rb,
lib/multi_json/adapters/yajl.rb,
lib/multi_json/options_cache.rb,
lib/multi_json/vendor/okjson.rb,
lib/multi_json/adapter_selector.rb,
lib/multi_json/adapters/ok_json.rb,
lib/multi_json/adapters/json_gem.rb,
lib/multi_json/adapters/oj_common.rb,
lib/multi_json/adapters/jr_jackson.rb,
lib/multi_json/convertible_hash_keys.rb,
lib/multi_json/adapters/fast_jsonparser.rb

Overview

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.

Examples:

Basic usage

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

Specifying an adapter

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

Defined Under Namespace

Modules: AdapterSelector, Adapters, ConvertibleHashKeys, OkJson, Options, OptionsCache Classes: Adapter, AdapterError, ParseError, Version

Configuration collapse

ALIASES =

Legacy alias for adapter name mappings

AdapterSelector::ALIASES
REQUIREMENT_MAP =

Maps adapter symbols to their require paths for auto-loading

{
  fast_jsonparser: "fast_jsonparser",
  oj: "oj",
  yajl: "yajl",
  jr_jackson: "jrjackson",
  json_gem: "json",
  gson: "gson"
}.freeze

Constant Summary collapse

VERSION =

Current version string in semver format

Version.to_s.freeze
DecodeError =

Legacy aliases for backward compatibility

LoadError = ParseError

Constants included from AdapterSelector

AdapterSelector::LOADERS

Configuration collapse

Adapter Management collapse

JSON Operations collapse

Methods included from Options

default_dump_options, default_load_options, dump_options, dump_options=, load_options, load_options=

Methods included from AdapterSelector

default_adapter

Class Method Details

.adapter ⇒ Class Also known as: engine

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the current adapter class

Examples:

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

Returns:

  • (Class) —

    the current adapter class



99
100
101
 
# File 'lib/multi_json.rb', line 99

def adapter
  @adapter ||= use(nil)
end

.current_adapter(options = {}) ⇒ Class

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns the adapter to use for the given options

Examples:

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

Parameters:

  • options (Hash) (defaults to: {}) —

    options that may contain :adapter key

Returns:

  • (Class) —

    adapter class



178
179
180
181
182
 
# File 'lib/multi_json.rb', line 178

def current_adapter(options = {})
  options ||= {}
  adapter_override = options[:adapter]
  adapter_override ? load_adapter(adapter_override) : adapter
end

.default_options ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

Use load_options or dump_options instead

Get the default options

Examples:

MultiJson.default_options  #=> {}

Returns:

  • (Hash) —

    the current load options



52
53
54
55
56
 
# 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) ⇒ Hash

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Deprecated.

Use load_options= and dump_options= instead

Set default options for both load and dump operations

Examples:

MultiJson.default_options = {symbolize_keys: true}

Parameters:

  • value (Hash) —

    options hash

Returns:

  • (Hash) —

    the options hash



39
40
41
42
43
 
# 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 = {}) ⇒ String Also known as: encode

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Serializes a Ruby object to a JSON string

Examples:

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

Parameters:

  • object (Object) —

    object to serialize

  • options (Hash) (defaults to: {}) —

    serialization options (adapter-specific)

Returns:

  • (String) —

    JSON string



192
193
194
 
# File 'lib/multi_json.rb', line 192

def dump(object, options = {})
  current_adapter(options).dump(object, options)
end

.load(string, options = {}) ⇒ Object Also known as: decode

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Parses a JSON string into a Ruby object

Examples:

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

Parameters:

  • string (String, #read) —

    JSON string or IO-like object

  • options (Hash) (defaults to: {}) —

    parsing options (adapter-specific)

Returns:

  • (Object) —

    parsed Ruby object

Raises:



156
157
158
159
160
161
 
# 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

.use(new_adapter) ⇒ Class Also known as: adapter=, engine=

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Sets the adapter to use for JSON operations

Examples:

MultiJson.use(:oj)

Parameters:

  • new_adapter (Symbol, String, Module, nil) —

    adapter specification

Returns:

  • (Class) —

    the loaded adapter class



119
120
121
122
123
 
# File 'lib/multi_json.rb', line 119

def use(new_adapter)
  @adapter = load_adapter(new_adapter)
ensure
  OptionsCache.reset
end

.with_adapter(new_adapter) { ... } ⇒ Object Also known as: with_engine

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Executes a block using the specified adapter

Examples:

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

Parameters:

  • new_adapter (Symbol, String, Module) —

    adapter to use

Yields:

  • block to execute with the temporary adapter

Returns:

  • (Object) —

    result of the block



212
213
214
215
216
217
218
 
# File 'lib/multi_json.rb', line 212

def with_adapter(new_adapter)
  previous_adapter = adapter
  self.adapter = new_adapter
  yield
ensure
  self.adapter = previous_adapter
end