Implement load/dump; deprecate decode/encode

Closes #36.

Author: sferik

lib/multi_json.rb

@@ -72,19 +72,31 @@ def engine=(new_engine)
     end
   end
 
+  # TODO: Remove for 2.0 release (but not any sooner)
+  def decode(string, options={})
+    warn "#{Kernel.caller.first}: [DEPRECATION] MultiJson.decode is deprecated and will be removed in the next major version. Use MultiJson.load instead."
+    load(string, options)
+  end
+
+  # TODO: Remove for 2.0 release (but not any sooner)
+  def encode(object, options={})
+    warn "#{Kernel.caller.first}: [DEPRECATION] MultiJson.encode is deprecated and will be removed in the next major version. Use MultiJson.dump instead."
+    dump(object, options)
+  end
+
   # Decode a JSON string into Ruby.
   #
   # <b>Options</b>
   #
   # <tt>:symbolize_keys</tt> :: If true, will use symbols instead of strings for the keys.
-  def decode(string, options = {})
-    engine.decode(string, options)
+  def load(string, options={})
+    engine.load(string, options)
   rescue engine::ParseError => exception
     raise DecodeError.new(exception.message, exception.backtrace, string)
   end
 
   # Encodes a Ruby object as JSON.
-  def encode(object, options = {})
-    engine.encode(object, options)
+  def dump(object, options={})
+    engine.dump(object, options)
   end
 end

lib/multi_json/engines/json_common.rb

@@ -2,12 +2,12 @@ module MultiJson
   module Engines
     module JsonCommon
 
-      def decode(string, options={})
+      def load(string, options={})
         string = string.read if string.respond_to?(:read)
         ::JSON.parse(string, :symbolize_names => options[:symbolize_keys])
       end
 
-      def encode(object, options={})
+      def dump(object, options={})
         object.to_json(process_options(options))
       end
 

lib/multi_json/engines/json_gem.rb

@@ -3,7 +3,7 @@
 
 module MultiJson
   module Engines
-    # Use the JSON gem to encode/decode.
+    # Use the JSON gem to dump/load.
     class JsonGem
       ParseError = ::JSON::ParserError
       extend JsonCommon

lib/multi_json/engines/json_pure.rb

@@ -3,7 +3,7 @@
 
 module MultiJson
   module Engines
-    # Use JSON pure to encode/decode.
+    # Use JSON pure to dump/load.
     class JsonPure
       ParseError = ::JSON::ParserError
       extend JsonCommon

lib/multi_json/engines/nsjsonserialization.rb

@@ -6,19 +6,19 @@ module Engines
     class Nsjsonserialization < MultiJson::Engines::OkJson
       ParseError = ::MultiJson::OkJson::Error
 
-      def self.decode(string, options = {})
+      def self.load(string, options={})
         string = string.read if string.respond_to?(:read)
         data = string.dataUsingEncoding(NSUTF8StringEncoding)
         object = NSJSONSerialization.JSONObjectWithData(data, options: NSJSONReadingMutableContainers | NSJSONReadingMutableLeaves, error: nil)
         if object
           object = symbolize_keys(object) if options[:symbolize_keys]
           object
         else
-          super(string, options = {})
+          super(string, options={})
         end
       end
 
-      def self.encode(object, options = {})
+      def self.dump(object, options={})
         pretty = options[:pretty] ? NSJSONWritingPrettyPrinted : 0
         object = object.as_json if object.respond_to?(:as_json)
         if NSJSONSerialization.isValidJSONObject(object)

lib/multi_json/engines/oj.rb

@@ -2,17 +2,17 @@
 
 module MultiJson
   module Engines
-    # Use the Oj library to encode/decode.
+    # Use the Oj library to dump/load.
     class Oj
       ParseError = SyntaxError
 
       ::Oj.default_options = {:mode => :compat}
 
-      def self.decode(string, options = {}) #:nodoc:
+      def self.load(string, options={}) #:nodoc:
         ::Oj.load(string, :symbol_keys => options[:symbolize_keys])
       end
 
-      def self.encode(object, options = {}) #:nodoc:
+      def self.dump(object, options={}) #:nodoc:
         ::Oj.dump(object, options)
       end
     end

lib/multi_json/engines/ok_json.rb

@@ -5,13 +5,13 @@ module Engines
     class OkJson
       ParseError = ::MultiJson::OkJson::Error
 
-      def self.decode(string, options = {}) #:nodoc:
+      def self.load(string, options={}) #:nodoc:
         string = string.read if string.respond_to?(:read)
         result = ::MultiJson::OkJson.decode(string)
         options[:symbolize_keys] ? symbolize_keys(result) : result
       end
 
-      def self.encode(object, options = {}) #:nodoc:
+      def self.dump(object, options={}) #:nodoc:
         ::MultiJson::OkJson.valenc(stringify_keys(object))
       end
 

lib/multi_json/engines/yajl.rb

@@ -2,15 +2,15 @@
 
 module MultiJson
   module Engines
-    # Use the Yajl-Ruby library to encode/decode.
+    # Use the Yajl-Ruby library to dump/load.
     class Yajl
       ParseError = ::Yajl::ParseError
 
-      def self.decode(string, options = {}) #:nodoc:
+      def self.load(string, options={}) #:nodoc:
         ::Yajl::Parser.new(:symbolize_keys => options[:symbolize_keys]).parse(string)
       end
 
-      def self.encode(object, options = {}) #:nodoc:
+      def self.dump(object, options={}) #:nodoc:
         ::Yajl::Encoder.encode(object, options)
       end
     end

spec/engine_shared_example.rb

@@ -8,17 +8,17 @@
     end
   end
 
-  describe '.encode' do
+  describe '.dump' do
     it 'writes decodable JSON' do
       [
         {'abc' => 'def'},
         [1, 2, 3, "4"],
       ].each do |example|
-        MultiJson.decode(MultiJson.encode(example)).should == example
+        MultiJson.load(MultiJson.dump(example)).should == example
       end
     end
 
-    it 'encodes symbol keys as strings' do
+    it 'dumps symbol keys as strings' do
       [
         [
           {:foo => {:bar => 'baz'}},
@@ -33,64 +33,64 @@
           {'foo' => [{'bar' => 'baz'}]},
         ]
       ].each do |example, expected|
-        encoded_json = MultiJson.encode(example)
-        MultiJson.decode(encoded_json).should == expected
+        dumped_json = MultiJson.dump(example)
+        MultiJson.load(dumped_json).should == expected
       end
     end
 
-    it 'encodes rootless JSON' do
-      MultiJson.encode("random rootless string").should == "\"random rootless string\""
-      MultiJson.encode(123).should == "123"
+    it 'dumps rootless JSON' do
+      MultiJson.dump("random rootless string").should == "\"random rootless string\""
+      MultiJson.dump(123).should == "123"
     end
 
     it 'passes options to the engine' do
-      MultiJson.engine.should_receive(:encode).with('foo', {:bar => :baz})
-      MultiJson.encode('foo', :bar => :baz)
+      MultiJson.engine.should_receive(:dump).with('foo', {:bar => :baz})
+      MultiJson.dump('foo', :bar => :baz)
     end
 
     if engine == 'json_gem' || engine == 'json_pure'
       describe 'with :pretty option set to true' do
         it 'passes default pretty options' do
           object = 'foo'
           object.should_receive(:to_json).with(JSON::PRETTY_STATE_PROTOTYPE.to_h)
-          MultiJson.encode(object,:pretty => true)
+          MultiJson.dump(object,:pretty => true)
         end
       end
     end
 
-    it "encodes custom objects which implement as_json" do
-      MultiJson.encode(TimeWithZone.new).should == "\"2005-02-01T15:15:10Z\""
+    it 'dumps custom objects which implement as_json' do
+      MultiJson.dump(TimeWithZone.new).should == "\"2005-02-01T15:15:10Z\""
     end
   end
 
-  describe '.decode' do
-    it 'properly decodes valid JSON' do
-      MultiJson.decode('{"abc":"def"}').should == {'abc' => 'def'}
+  describe '.load' do
+    it 'properly loads valid JSON' do
+      MultiJson.load('{"abc":"def"}').should == {'abc' => 'def'}
     end
 
     it 'raises MultiJson::DecodeError on invalid JSON' do
       lambda do
-        MultiJson.decode('{"abc"}')
+        MultiJson.load('{"abc"}')
       end.should raise_error(MultiJson::DecodeError)
     end
 
     it 'raises MultiJson::DecodeError with data on invalid JSON' do
       data = '{invalid}'
       begin
-        MultiJson.decode(data)
+        MultiJson.load(data)
       rescue MultiJson::DecodeError => de
         de.data.should == data
       end
     end
 
     it 'stringifys symbol keys when encoding' do
-      encoded_json = MultiJson.encode(:a => 1, :b => {:c => 2})
-      MultiJson.decode(encoded_json).should == {"a" => 1, "b" => {"c" => 2}}
+      dumped_json = MultiJson.dump(:a => 1, :b => {:c => 2})
+      MultiJson.load(dumped_json).should == {"a" => 1, "b" => {"c" => 2}}
     end
 
-    it "properly decodes valid JSON in StringIOs" do
+    it 'properly loads valid JSON in StringIOs' do
       json = StringIO.new('{"abc":"def"}')
-      MultiJson.decode(json).should == {'abc' => 'def'}
+      MultiJson.load(json).should == {'abc' => 'def'}
     end
 
     it 'allows for symbolization of keys' do
@@ -108,7 +108,7 @@
           {:abc => [{:def => 'hgi'}]},
         ],
       ].each do |example, expected|
-        MultiJson.decode(example, :symbolize_keys => true).should == expected
+        MultiJson.load(example, :symbolize_keys => true).should == expected
       end
     end
   end

spec/helper.rb

@@ -14,17 +14,17 @@ def macruby?
 require 'rspec'
 
 class MockDecoder
-  def self.decode(string, options = {})
+  def self.load(string, options={})
     {'abc' => 'def'}
   end
 
-  def self.encode(string)
+  def self.dump(string)
     '{"abc":"def"}'
   end
 end
 
 class TimeWithZone
-  def to_json(options = {})
+  def to_json(options={})
     "\"2005-02-01T15:15:10Z\""
   end
 end