Refactor code, tests, and documentation

README.md

@@ -18,10 +18,18 @@ multiple arguments.
 Examples
 --------
 
+### Notes
+
+All calls via RForce-wrapper have their results wrapped in an array. You can
+disable this functionality by specifying the option `:wrap_results => false`
+in the constructor to your `RForce::Wrapper::Connection`.
+
+### Overview
+
     require 'rforce-wrapper'
 
     # Connect to our sandbox.
-    sf = RForce::Wrapper::Connection.new('email', 'password' + 'token', :test)
+    sf = RForce::Wrapper::Connection.new('email', 'password' + 'token', {:environment => :test})
 
     # Describe the sObject "Account" and get a list of fields.
     account_description = sf.describeSObjects('Account').first

lib/rforce-wrapper/connection.rb

@@ -12,17 +12,34 @@ class Connection
       include RForce::Wrapper::DescribeMethods
       include RForce::Wrapper::UtilityMethods
 
+      # Returns the underlying `RForce::Binding` object.
       attr_reader :binding
 
-      # Create a connection to the database with the given email and password/token combo.
-      # Optional parameter type can be used to specify live or test accounts (defaults to live).
-      def initialize(email, pass, type = :live, version = '21.0')
-        @binding = RForce::Binding.new RForce::Wrapper::Connection.url_for_environment(type, version)
+      # Creates a new connect to the Salesforce API using the given email and
+      # password or password+token combination. Additional options can be
+      # specified.
+      #
+      # @param [String] email the email address of the account to log in with
+      # @param [String] pass the password or password+token combo for the account
+      # @param [Hash] options additional options for the connection
+      # @option options [:live, :test] :environment the environment, defaults to `:live`
+      # @option options [String] :version the version of the Salesforce API to use, defaults to `'21.0'`
+      # @option options [Boolean] :wrap_results whether or not to wrap single-element results into an array, defaults to `true`
+      def initialize(email, pass, options = {})
+        options = {
+          :environment  => :live,
+          :version      => '21.0',
+          :wrap_results => true
+        }.merge(options)
+        @wrap_results = options[:wrap_results]
+        @binding = RForce::Binding.new RForce::Wrapper::Connection.url_for_environment(options[:environment], options[:version])
         @binding.login email, pass
       end
 
-      # Returns the URL for the given environment type.
-      # Valid types are :test and :live.
+      # Returns the URL for the given environment type and version.
+      #
+      # @param [:live, :test] type the environment type
+      # @param [String] version the version of the Salesforce API to use
       def self.url_for_environment(type, version)
         case type
         when :test
@@ -36,8 +53,18 @@ def self.url_for_environment(type, version)
 
       protected
 
-        # Make the SOAP API call identified by method
-        # using the given params.
+        # Performs a SOAP API call via the underlying `RForce::Binding`
+        # object. Raises an exception if a `Fault` is detected. Returns
+        # the data portion of the result (wrapped in an `Array` if
+        # `wrap_results` is true; see {#initialize}).
+        #
+        # @param [Symbol] method the API method to call
+        # @param [Array, Hash, nil] params the parameters to pass to the API
+        #   method. `RForce::Binding` expects either an `Array` or `Hash` to
+        #   turn into SOAP arguments. Pass `nil`, `[]` or `{}` if the API
+        #   call takes no parameters.
+        # @raise [RForce::Wrapper::SalesforceFaultException] indicates that
+        #   a `Fault` was returned from the Salesforce API
         def make_api_call(method, params = nil)
           if params
             result = @binding.send method, params
@@ -54,7 +81,8 @@ def make_api_call(method, params = nil)
           # which will contain the key :result
           result_field_name = method.to_s + "Response"
           if result[result_field_name.to_sym]
-            return RForce::Wrapper::Utilities.ensure_array result[result_field_name.to_sym][:result]
+            data = result[result_field_name.to_sym][:result]
+            return @wrap_results ? RForce::Wrapper::Utilities.ensure_array(data) : data
           else
             return nil
           end

spec/rforce-wrapper_connection_spec.rb

@@ -3,9 +3,10 @@
 
 describe RForce::Wrapper::Connection do
   before :each do
+    @default_constructor_args = [TEST_USER, TEST_PASS_TOKEN]
     RForce::Binding.any_instance.stubs(:login).returns(:login)
     RForce::Binding.any_instance.stubs(:call_remote).returns(api_response_for(API_METHOD))
-    @wrapper = RForce::Wrapper::Connection.new TEST_USER, TEST_PASS_TOKEN, :live
+    @wrapper = RForce::Wrapper::Connection.new *@default_constructor_args
   end
 
   context "#initialize" do
@@ -14,16 +15,32 @@
     end
 
     it "should create an RForce binding to the correct version" do
-      @wrapper = RForce::Wrapper::Connection.new TEST_USER, TEST_PASS_TOKEN, :live, '20.0'
+      @wrapper = RForce::Wrapper::Connection.new *@default_constructor_args, {:environment => :live, :version => '20.0'}
       correct_url = RForce::Wrapper::Connection.url_for_environment(:live, '20.0')
       @wrapper.binding.url.should == URI.parse(correct_url)
     end
 
+    it "should default to a live environment" do
+      @wrapper = RForce::Wrapper::Connection.new *@default_constructor_args
+      correct_url = RForce::Wrapper::Connection.url_for_environment(:live, '21.0')
+      @wrapper.binding.url.should == URI.parse(correct_url)
+    end
+
     it "should default to version 21.0 of the API" do
-      @wrapper = RForce::Wrapper::Connection.new TEST_USER, TEST_PASS_TOKEN, :live
+      @wrapper = RForce::Wrapper::Connection.new *@default_constructor_args, {:environment => :live}
       correct_url = RForce::Wrapper::Connection.url_for_environment(:live, '21.0')
       @wrapper.binding.url.should == URI.parse(correct_url)
     end
+
+    it "should set wrap_results to false if passed" do
+      @wrapper = RForce::Wrapper::Connection.new *@default_constructor_args, {:wrap_results => false}
+      @wrapper.instance_exec do
+        def wrap_results
+          @wrap_results
+        end
+      end
+      @wrapper.wrap_results.should == false
+    end
   end
 
   context "#url_for_environment" do
@@ -55,6 +72,17 @@
     it "should return the results sub-hash of the API call" do
       @wrapper.send(:make_api_call, API_METHOD, ['params']).should == api_results_for(API_METHOD)
     end
+
+    it "should wrap results in an array by default" do
+      RForce::Wrapper::Utilities.expects(:ensure_array).once
+      @wrapper.send(:make_api_call, API_METHOD, ['params'])
+    end
+
+    it "should not wrap results in an array if the option is passed" do
+      @wrapper = RForce::Wrapper::Connection.new TEST_USER, TEST_PASS_TOKEN, :wrap_results => false
+      RForce::Wrapper::Utilities.expects(:ensure_array).never
+      @wrapper.send(:make_api_call, API_METHOD, ['params'])
+    end
   end
 
   context "core api method" do