Add spec for how to call Pickle::Ref

lib/pickle/jar.rb

@@ -1,7 +1,7 @@
 module Pickle
   # handles storing and retrieveing models using pickle_refs to do so.  This is not the smae as creating/finding models
   # 
-  # For cucumber use, it's better to use the methods with the same names found in in Pickle::Scenario
+  # For cucumber use, it's better to use the methods with the same names found in in Pickle::Api
   #
   # Examples: (FYI - the pickle.create_and_store methods do all of this automatically)
   #

lib/pickle/ref.rb

@@ -2,20 +2,28 @@ module Pickle
   class InvalidPickleRefError < RuntimeError
   end
 
-  # parses a pickle ref string into its component parts: factory, index, and label
-  #
-  # raises an error if the pickle_ref is invalid
   class Ref
     include Parser::Matchers
     include Parser::Canonical
 
     attr_reader :factory, :index, :label
 
-    def initialize(arg)
-      arg.is_a?(Hash) ? parse_hash(arg) : parse_string(arg)
+    # parses a pickle ref string or hash into its component parts: factory, index, and label
+    #
+    # if a config object is passed, then it will be used to perform any substitutions on :factory, and for parsing
+    #
+    # @raise ArgumentError
+    # @raise Pickle::InvalidPickleRefError
+    # @return Pickle::Ref
+    def initialize(*args)
+      options = args.extract_options!
+      self.config = options.delete(:config)
+      raise ArgumentError, "specify either a string (with optional :config), or a hash (with optional :config), not both." if args.length > 1 || (options.any? && args.any?)
+
+      args.any? ? parse_string(args.first) : parse_hash(options)
       validate!
     end
-
+            
   protected
     def validate!
       raise InvalidPickleRefError, "#{inspect} requires a factory or label" if factory.blank? && label.blank?
@@ -27,7 +35,7 @@ def parse_hash(orig)
       @factory = hash.delete(:factory)
       @index = hash.delete(:index)
       @label = hash.delete(:label)
-      raise InvalidPickleRefError, "superfluous options: #{hash.inspect}" unless hash.empty?
+      raise InvalidPickleRefError, "superfluous/unknown options: #{hash.inspect}" unless hash.empty?
     end
 
     def parse_string(orig)

spec/pickle/ref_spec.rb

@@ -1,6 +1,18 @@
 require 'spec_helper'
 
 describe Pickle::Ref do
+  describe "(how to call)" do
+    specify "can be called with a string, with an optional :config e.g. Pickle::Ref.new('foo'[, :config => <config>])" do
+      lambda { Pickle::Ref.new('foo') }.should_not raise_error(ArgumentError)
+      lambda { Pickle::Ref.new('foo', :config => mock) }.should_not raise_error(ArgumentError)
+    end
+
+    specify "can be called with a hash, with an optional config, e.g. Pickle::Ref.new(:label => 'fred'[, :config => <config>])" do
+      lambda { Pickle::Ref.new(:label => "gday") }.should_not raise_error(ArgumentError)
+      lambda { Pickle::Ref.new(:label => "gday", :config => mock) }.should_not raise_error(ArgumentError)
+    end
+  end
+
   describe "(factory) " do
     shared_examples_for 'pickle ref with :factory => "colour"' do
       its(:index) { should be_nil }
@@ -119,7 +131,7 @@
     end
   end
 
-  describe "creating with attrs hash" do
+  describe "(with config)" do
 
   end
 end