metaforce 0.2.0.alpha → 0.3.0.alpha

data/.travis.yml

@@ -0,0 +1,5 @@
+language: ruby
+rvm:
+  - 1.9.2
+  - 1.9.3
+script: bundle exec rspec spec

data/README.md

@@ -1,13 +1,15 @@
 # Metaforce
+![travis-ci](https://secure.travis-ci.org/ejholmes/metaforce.png)
+
 Metaforce is a Ruby gem for interacting with the [Salesforce Metadata API](http://www.salesforce.com/us/developer/docs/api_meta/index.htm).
 The goal of this project is to make the [Migration Tool](http://www.salesforce.com/us/developer/docs/apexcode/Content/apex_deploying_ant.htm) obsolete, favoring Rake over Ant.
 
-Metaforce is in active development and is currently in alpha status. Don't use
-it to deploy code to production instances. You've been warned!
+**Metaforce is in active development and is currently in alpha status. Don't use
+it to deploy code to production instances. You've been warned!**
 
 ## Installation
 ```bash
-gem install metaforce -v '0.2.0.alpha'
+gem install metaforce --pre
 ```
 
 ## Usage
@@ -22,7 +24,7 @@ client.describe
 client.list(:type => "CustomObject")
 # => [{ :created_by_id => "005U0000000EGpcIAG", :created_by_name => "Eric Holmes", ... }]
 
-deployment = client.deploy(File.expand_path("../src"))
+deployment = client.deploy(File.dirname(__FILE__))
 # => #<Metaforce::Transaction:0x00000102779bf8 @id="04sU0000000WNWoIAO" @type=:deploy> 
 
 deployment.done?
@@ -32,15 +34,61 @@ deployment.result(:wait_until_done => true)
 # => { :id => "04sU0000000WNWoIAO", :messages => [{ :changed => true ... :success => true }
 ```
 
+## DSL
+Metaforce includes a lightweight DSL to make deployments and retrieve's easier.
+
+```ruby
+require "metaforce/dsl"
+include Metaforce::DSL::Metadata
+
+login :username => 'username', :password => 'password', :security_token => 'security token' do
+
+  deploy File.dirname(__FILE__) do |result|
+      puts "Successful deployment!"
+      puts result
+  end
+
+  retrieve File.expand_path("../src/package.xml", __FILE__) |result, zip|
+      puts "Successful retrieve!"
+      puts result
+      File.open("retrieve.zip", "wb") do |file|
+        file.write(zip)
+      end
+  end
+
+  retrieve File.expand_path("../src/package.xml", __FILE__), :to => "directory"
+end
+```
+
 ## Roadmap
 This gem is far from being feature complete. Here's a list of things that still
 need to be done.
 
-* Implement .retrieve for retrieving metadata.
+* <del>Implement .retrieve for retrieving metadata.</del>
 * Implement CRUD based calls <http://www.salesforce.com/us/developer/docs/api_meta/Content/meta_crud_based_calls_intro.htm>.
 * Implement some helper methods for diffing metadata.
+* <del>Implement a DSL.</del>
 * And some other stuff that I haven't quite thought of yet...
 
+## Contributing
+If you'd like to contribute code, please fork the repository and implement your
+feature on a new branch, then send me a pull request with a detailed
+description. Please provide applicable rspec specs.
+
+## Version History
+**0.3.0.alpha** (January 29, 2012)
+
+* Ability to retrieve metadata from an organization.
+* Added a DSL.
+
+**0.2.0.alpha** (January 28, 2012)
+
+* Gem now supports interacting with the metadata api.
+
+**0.1.0.alpha** (January 10, 2012)
+
+* Ability to parse and modify package.xml files easily.
+
 ## License
 Copyright (C) 2012  Eric Holmes
 

data/lib/metaforce/api/metadata.rb

@@ -7,14 +7,22 @@ require 'ostruct'
 module Metaforce
   module Metadata
     class Client
-      DEPLOY_ZIP = 'deploy.zip'
-      RETRIEVE_ZIP = 'retrieve.zip'
+      DEPLOY_ZIP = 'deploy.zip' # :nodoc:
+      RETRIEVE_ZIP = 'retrieve.zip' # :nodoc:
 
+      # Performs a login and sets the session_id and metadata_server_url.
+      # _options_ should be hash containing the :username, :password and
+      # :security_token keys.
+      #
+      #  Metaforce::Metadata::Client.new :username => "username",
+      #    :password => "password",
+      #    :security_token => "security token"
       def initialize(options=nil)
         @session = Services::Client.new(options).session
         @client = Savon::Client.new File.expand_path("../../../../wsdl/#{Metaforce.configuration.api_version}/metadata.xml", __FILE__) do |wsdl|
           wsdl.endpoint = @session[:metadata_server_url]
         end
+        @client.http.auth.ssl.verify_mode = :none
         @header = {
             "ins0:SessionHeader" => {
               "ins0:sessionId" => @session[:session_id]
@@ -24,11 +32,10 @@ module Metaforce
 
       # Specify an array of component types to list
       #
-      # example:
-      # [
-      #   { :type => "ApexClass" },
-      #   { :type => "ApexComponent" }
-      # ]
+      #   [
+      #     { :type => "ApexClass" },
+      #     { :type => "ApexComponent" }
+      #   ]
       def list(queries=[])
         unless queries.is_a?(Array)
           queries = [ queries ]
@@ -73,10 +80,12 @@ module Metaforce
         self.status(id)[:done]
       end
 
-      # Deploys dir to the organisation
-      def deploy(dir, options={})
-        options = OpenStruct.new options
-
+      # Deploys _dir_ to the organisation
+      #
+      # See http://www.salesforce.com/us/developer/docs/api_meta/Content/meta_deploy.htm#deploy_options
+      # for a list of _deploy_options_. Options should be convereted from
+      # camelCase to an :underscored_symbol.
+      def deploy(dir, deploy_options={})
         if dir.is_a?(String)
           filename = File.join(File.dirname(dir), DEPLOY_ZIP)
           zip_contents = create_deploy_file(filename, dir)
@@ -84,18 +93,51 @@ module Metaforce
           zip_contents = Base64.encode64(dir.read)
         end
 
-        yield options if block_given?
-
         response = @client.request(:deploy) do |soap|
           soap.header = @header
           soap.body = {
             :zip_file => zip_contents,
-            :deploy_options => options.marshal_dump
+            :deploy_options => deploy_options
           }
         end
         Transaction.deployment self, response[:deploy_response][:result][:id]
       end
 
+      # Performs a retrieve
+      #
+      # See http://www.salesforce.com/us/developer/docs/api_meta/Content/meta_retrieve_request.htm
+      # for a list of _retrieve_request_ options. Options should be convereted from
+      # camelCase to an :underscored_symbol.
+      def retrieve(retrieve_request={})
+        response = @client.request(:retrieve) do |soap|
+          soap.header = @header
+          soap.body = {
+            :retrieve_request => retrieve_request
+          }
+        end
+        Transaction.retrieval self, response[:retrieve_response][:result][:id]
+      end
+
+      # Retrieves files specified in the manifest file (package.xml)
+      #
+      # Specificy any extra _retrieve_request_ options in _extra_.
+      def retrieve_unpackaged(manifest, extra=nil)
+        if manifest.is_a?(Metaforce::Manifest)
+          package = manifest.to_package
+        elsif manifest.is_a?(String)
+          package = Metaforce::Manifest.new(File.open(manifest).read).to_package
+        end
+        retrieve_request = { 
+          :api_version => Metaforce.configuration.api_version,
+          :single_package => true,
+          :unpackaged => {
+            :types => package
+          }
+        }
+        retrieve_request.merge!(extra) if extra.is_a?(Hash)
+        retrieve(retrieve_request)
+      end
+
     private
     
       # Creates the deploy file, reads in the contents and returns the base64

data/lib/metaforce/api/services.rb

@@ -3,8 +3,13 @@ require 'savon'
 module Metaforce
   module Services
     class Client
+      # Contains the session_id and metadata_server_url
       attr_reader :session
 
+      # Initializes a new instance of Client and logs in. _options_ should be a
+      # hash containing the username, password and security token. If options
+      # is nil, it will get the username, password and security token from the
+      # configuration.
       def initialize(options=nil)
         options = {
           :username => Metaforce.configuration.username,
@@ -14,11 +19,13 @@ module Metaforce
         @session = self.login(options[:username], options[:password], options[:security_token])
       end
 
+      # Performs a login and sets @session
       def login(username, password, security_token=nil)
         password = "#{password}#{security_token}" unless security_token.nil?
         client = Savon::Client.new File.expand_path("../../../../wsdl/#{Metaforce.configuration.api_version}/partner.xml", __FILE__) do |wsdl|
           wsdl.endpoint = wsdl.endpoint.to_s.sub(/login/, 'test') if Metaforce.configuration.test
         end
+        client.http.auth.ssl.verify_mode = :none
         response = client.request(:login) do
           soap.body = {
             :username => username,

data/lib/metaforce/api/transaction.rb

@@ -1,3 +1,5 @@
+require 'base64'
+
 module Metaforce
 
   # Convenience class for deployment/retrieval results
@@ -26,11 +28,34 @@ module Metaforce
     end
     alias :complete? :done?
     alias :completed? :done?
+
+    # Returns the zip file from a retrieval
+    def zip_file
+      raise "Request was not a retrieve." if @type != :retrieve
+      Base64.decode64(@result[:zip_file])
+    end
+
+    # Unzips the returned zip file to _destination_
+    def unzip(destination)
+      zip = zip_file
+      file = Tempfile.new("retrieve")
+      file.write(zip)
+      path = file.path
+      file.close
+
+      Zip::ZipFile.open(path) do |zip|
+        zip.each do |f|
+          path = File.join(destination, f.name)
+          FileUtils.mkdir_p(File.dirname(path))
+          zip.extract(f, path)
+        end
+      end
+    end
     
     # Returns the deploy or retrieve result
     def result(options={})
       self.wait_until_done if options[:wait_until_done]
-      raise "Request is not complete! Be sure to call .done? first!" unless @done
+      raise "Request has not completed." unless @done
       @result = @client.status(@id, @type) if @result.nil?
       @result
     end

data/lib/metaforce/config.rb

@@ -1,19 +1,35 @@
 module Metaforce
   class << self
+    # Returns the current Configuration
+    #
+    #    Metaforce.configuration.username = "username"
+    #    Metaforce.configuration.password = "password"
     def configuration
       @configuration ||= Configuration.new
     end
 
+    # Yields the Configuration
+    #
+    #    Metaforce.configure do |config|
+    #      config.username = "username"
+    #      config.password = "password"
+    #    end
     def configure
       yield configuration
     end
   end
 
   class Configuration
+    # The Salesforce API version to use. Defaults to 23.0
     attr_accessor :api_version
+    # The username to use during login.
     attr_accessor :username
+    # The password to use during login.
     attr_accessor :password
+    # The security token to use during login.
     attr_accessor :security_token
+    # Set this to true if you're authentication with a Sandbox instance.
+    # Defaults to false.
     attr_accessor :test
 
     def initialize

data/lib/metaforce/dsl.rb

@@ -0,0 +1,42 @@
+require 'tempfile'
+require 'zip/zip'
+
+module Metaforce
+  module DSL
+    module Metadata
+
+      # Logs in and creates a new instance of Metaforce::Metadata::Client
+      def login(options)
+        @client = Metaforce::Metadata::Client.new options
+        yield if block_given?
+      end
+
+      # Deploy the contents of _dir_ to the target organization
+      def deploy(dir, options={})
+        deployment = @client.deploy(dir, options)
+        result = deployment.result(:wait_until_done => true)
+        raise "Deploy failed." if !result[:success]
+        yield result if block_given?
+      end
+      
+      # Retrieve the metadata specified in the manifest file. If manifest is a
+      # Hash, the underlying .retrieve method is used instead of
+      # .retrieve_unpackaged.
+      #
+      # If _options_ # contains a key _:to_, the resulting zip
+      # file that is retrieved is unzipped to the directory specified.
+      def retrieve(manifest, options={})
+        if manifest.is_a?(Hash)
+          retrieval = @client.retrieve(manifest)
+        else
+          retrieval = @client.retrieve_unpackaged(manifest)
+        end
+        result = retrieval.result(:wait_until_done => true)
+        zip_contents = retrieval.zip_file
+        retrieval.unzip(options[:to]) if options.has_key?(:to)
+        yield result, zip_contents if block_given?
+      end
+
+    end
+  end
+end

data/lib/metaforce/manifest.rb

@@ -4,16 +4,38 @@ module Metaforce
   class Manifest
     SFDC_API_VERSION = "23.0"
 
-    # example format
-    # {
-    #   :apex_class => [
-    #     "TestController",
-    #     "TestClass"
-    #   ],
-    #   :apex_component => [
-    #     "SiteLogin"
-    #   ]
-    # }
+    # Initializes a new instance of a manifest (package.xml) file.
+    # 
+    # It can either take a hash:
+    #   {
+    #     :apex_class => [
+    #       "TestController",
+    #       "TestClass"
+    #     ],
+    #     :apex_component => [
+    #       "SiteLogin"
+    #     ]
+    #   }
+    #
+    # Or an xml string containing the contents of a packge.xml file:
+    #  <?xml version="1.0"?>
+    #  <Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    #    <types>
+    #      <members>TestClass</members>
+    #      <members>AnotherClass</members>
+    #      <name>ApexClass</name>
+    #    </types>
+    #    <types>
+    #      <members>Component</members>
+    #      <name>ApexComponent</name>
+    #    </types>
+    #    <types>
+    #      <members>Assets</members>
+    #      <name>StaticResource</name>
+    #    </types>
+    #    <version>23.0</version>
+    #  </Package>
+    # 
     def initialize(components={})
       # Map component type => folder
       if components.is_a?(Hash)
@@ -25,6 +47,8 @@ module Metaforce
     end
 
     # Adds components to the package
+    #
+    #  manifest.add :apex_class, 'SomeClass'
     def add(type, members=nil)
       unless members.nil?
         @components[type] = [] if @components[type].nil?
@@ -38,6 +62,8 @@ module Metaforce
     end
 
     # Removes components from the package
+    #
+    #  manifest.remove :apex_class, 'SomeClass'
     def remove(type, members=nil)
       unless members.nil?
         members = [members] if members.is_a?(String)
@@ -53,6 +79,8 @@ module Metaforce
     end
 
     # Filters the components based on a list of files
+    #
+    #  manifest.only(['classes/SomeClass'])
     def only(files)
       components = @components
       @components = {}
@@ -72,23 +100,41 @@ module Metaforce
     end
 
     # Returns the components name
-    def component_name(key)
+    def component_name(key) # :nodoc:
       COMPONENT_TYPE_MAP[key][:name]
     end
 
     # Returns the components folder
-    def component_folder(key)
+    def component_folder(key) # :nodoc:
       COMPONENT_TYPE_MAP[key][:folder]
     end
 
     # Returns a key for the component name
-    def component_key(name)
+    def component_key(name) # :nodoc:
       COMPONENT_TYPE_MAP.each do |key, component|
         return key if component[:name] == name
       end
     end
 
     # Returns a string containing a package.xml file
+    #
+    #  <?xml version="1.0"?>
+    #  <Package xmlns="http://soap.sforce.com/2006/04/metadata">
+    #    <types>
+    #      <members>TestClass</members>
+    #      <members>AnotherClass</members>
+    #      <name>ApexClass</name>
+    #    </types>
+    #    <types>
+    #      <members>Component</members>
+    #      <name>ApexComponent</name>
+    #    </types>
+    #    <types>
+    #      <members>Assets</members>
+    #      <name>StaticResource</name>
+    #    </types>
+    #    <version>23.0</version>
+    #  </Package>
     def to_xml
       xml_builder = Nokogiri::XML::Builder.new do |xml|
         xml.Package("xmlns" => "http://soap.sforce.com/2006/04/metadata") {
@@ -106,10 +152,22 @@ module Metaforce
       xml_builder.to_xml
     end
 
+    # Returns the underlying hash structure
+    #
+    #   {
+    #     :apex_class => [
+    #       "TestController",
+    #       "TestClass"
+    #     ],
+    #     :apex_component => [
+    #       "SiteLogin"
+    #     ]
+    #   }
     def to_hash
       @components
     end
 
+    # Used internall my Metaforce::Metadata::Client
     def to_package
       components = []
       @components.each do |type, members|

data/lib/metaforce/version.rb

@@ -1,3 +1,3 @@
 module Metaforce
-  VERSION = "0.2.0.alpha"
+  VERSION = "0.3.0.alpha"
 end

data/metaforce.gemspec

@@ -18,11 +18,12 @@ Gem::Specification.new do |s|
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
 
-  s.add_dependency "nokogiri"
-  s.add_dependency "savon"
-  s.add_dependency "rubyzip"
+  s.add_dependency "nokogiri", "~> 1.5.0"
+  s.add_dependency "savon", "~> 0.9.7"
+  s.add_dependency "rubyzip", "~> 0.9.5"
 
+  s.add_development_dependency "rake"
   s.add_development_dependency "rspec"
   s.add_development_dependency "mocha"
-  s.add_development_dependency "savon_spec"
+  s.add_development_dependency "savon_spec", "~> 0.1.6"
 end

data/spec/fixtures/requests/check_retrieve_status/success.xml

@@ -0,0 +1,37 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://soap.sforce.com/2006/04/metadata">
+  <soapenv:Body>
+    <checkRetrieveStatusResponse>
+      <result>
+        <fileProperties>
+          <createdById>005U0000000EGpcIAG</createdById>
+          <createdByName>Eric Holmes</createdByName>
+          <createdDate>2012-01-14T22:11:17.000Z</createdDate>
+          <fileName>classes/TestClass.cls</fileName>
+          <fullName>TestClass</fullName>
+          <id>01pU0000000pDrtIAE</id>
+          <lastModifiedById>005U0000000EGpcIAG</lastModifiedById>
+          <lastModifiedByName>Eric Holmes</lastModifiedByName>
+          <lastModifiedDate>2012-01-15T03:17:28.000Z</lastModifiedDate>
+          <manageableState>unmanaged</manageableState>
+          <type>ApexClass</type>
+        </fileProperties>
+        <fileProperties>
+          <createdById>005U0000000EGpcIAG</createdById>
+          <createdByName>Eric Holmes</createdByName>
+          <createdDate>2012-01-28T03:35:13.400Z</createdDate>
+          <fileName>package.xml</fileName>
+          <fullName>package.xml</fullName>
+          <id/>
+          <lastModifiedById>005U0000000EGpcIAG</lastModifiedById>
+          <lastModifiedByName>Eric Holmes</lastModifiedByName>
+          <lastModifiedDate>2012-01-28T03:35:13.400Z</lastModifiedDate>
+          <manageableState>unmanaged</manageableState>
+          <type>Package</type>
+        </fileProperties>
+        <id>04sU0000000WkdIIAS</id>
+        <zipFile>UEsDBBQACAAIAGYcPEAAAAAAAAAAAAAAAAAVAAAAY2xhc3Nlcy9UZXN0Q2xhc3MuY2xzKyhNyslMVkjOSSwuVghJLS5xBrOquWoBUEsHCKYgavMYAAAAGgAAAFBLAwQUAAgACABmHDxAAAAAAAAAAAAAAAAAHgAAAGNsYXNzZXMvVGVzdENsYXNzLmNscy1tZXRhLnhtbK2RTWsCMRCG7/srltzdibZUkWxECj321PY+xtGmbj7IRPHnN3SluwdBD87tffMM80DU6uy6+kSJbfCtmDZS1ORN2Fq/b8Xnx9tkIVa6UutI59cOmevCe27Fd85xCcABY8O7kAw1JjiYSfkC8hkcZdxiRqGruozCaL/6I3r21EgFo6InIpoD7ulSct/+vTj8Cen96DaU9FTBOI4g6wdoXqhRHiiPjrhcIo2dgiH1CnDV4ZFm8rYYcQ6J7pbjjPnIem2yPZWtS6wU/P+Yrn4BUEsHCKXszAvOAAAA5QEAAFBLAwQUAAgACABmHDxAAAAAAAAAAAAAAAAACwAAAHBhY2thZ2UueG1sTY7LCsIwEEX3/YqQvZlYRUTSFBFcu6gfENNRi82DTpD695Y+0FnNGQ53rip717I3dtQEX/C1kJyht6Fu/KPg1+q82vNSZ+pi7Ms8kA22p4I/U4oHAAomCrqHzqKwwUEu5Q7kFhwmU5tkuM7YMCp9ItK0j+zQ3YaXukJKp9YQKVhOP8kbh/oYsZ+Nkac8+AtUc3mdb4RUsFCmYO6ssy9QSwcIe4wRVJ4AAADlAAAAUEsBAhQAFAAIAAgAZhw8QKYgavMYAAAAGgAAABUAAAAAAAAAAAAAAAAAAAAAAGNsYXNzZXMvVGVzdENsYXNzLmNsc1BLAQIUABQACAAIAGYcPECl7MwLzgAAAOUBAAAeAAAAAAAAAAAAAAAAAFsAAABjbGFzc2VzL1Rlc3RDbGFzcy5jbHMtbWV0YS54bWxQSwECFAAUAAgACABmHDxAe4wRVJ4AAADlAAAACwAAAAAAAAAAAAAAAAB1AQAAcGFja2FnZS54bWxQSwUGAAAAAAMAAwDIAAAATAIAAAAA</zipFile>
+      </result>
+    </checkRetrieveStatusResponse>
+  </soapenv:Body>
+</soapenv:Envelope>

data/spec/fixtures/requests/retrieve/in_progress.xml

@@ -0,0 +1,12 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns="http://soap.sforce.com/2006/04/metadata">
+  <soapenv:Body>
+    <retrieveResponse>
+      <result>
+        <done>false</done>
+        <id>04sU0000000WkdIIAS</id>
+        <state>InProgress</state>
+      </result>
+    </retrieveResponse>
+  </soapenv:Body>
+</soapenv:Envelope>

data/spec/lib/api/metadata_spec.rb

@@ -108,17 +108,6 @@ describe Metaforce::Metadata::Client do
 
     end
 
-    # context "when given a file" do
-
-      # it "deploys the file and returns the id of the result" do
-        # path = Tempfile.new('zipfile').tap { |f| f.write('h'); f.close }.path
-        # savon.expects(:deploy).with(:zip_file => "aA==\n", :deploy_options => {}).returns(:in_progress)
-        # id = client.deploy(File.open(path))
-        # id.should eq("04sU0000000WNWoIAO")
-      # end
-
-    # end
-
     it "allows deploy options to be configured via a hash" do
       savon.expects(:deploy).with(:zip_file => '', :deploy_options => { :run_all_tests => true }).returns(:in_progress)
       expect {
@@ -126,14 +115,61 @@ describe Metaforce::Metadata::Client do
       }.to_not raise_error
     end
 
-    it "allows deploy options to be configured via a block" do
-      savon.expects(:deploy).with(:zip_file => '', :deploy_options => { :run_all_tests => true }).returns(:in_progress)
-      expect {
-        client.deploy('') do |options|
-          options.run_all_tests = true
+  end
+
+  describe ".retrieve" do
+
+    let(:manifest) do
+      Metaforce::Manifest.new(File.open(File.expand_path('../../../fixtures/sample/src/package.xml', __FILE__)).read)
+    end
+
+    describe ".retrieve_unpackaged" do
+
+      context "when given a manifest file" do
+        before(:each) do
+          savon.expects(:retrieve).with(:retrieve_request => { :api_version => Metaforce.configuration.api_version, :single_package => true, :unpackaged => { :types => manifest.to_package } }).returns(:in_progress)
+          savon.expects(:check_status).with(:ids => ['04sU0000000WkdIIAS']).returns(:done)
+          savon.expects(:check_retrieve_status).with(:ids => ['04sU0000000WkdIIAS']).returns(:success)
         end
-      }.to_not raise_error
+
+        it "returns a valid retrieve result" do
+          retrieval = client.retrieve_unpackaged(manifest)
+          retrieval.done?
+          result = retrieval.result
+          result.should be_a(Hash)
+        end
+
+      end
+
+      context "when given the path to a manifest file" do
+        before(:each) do
+          savon.expects(:retrieve).with(:retrieve_request => { :api_version => Metaforce.configuration.api_version, :single_package => true, :unpackaged => { :types => manifest.to_package } }).returns(:in_progress)
+          savon.expects(:check_status).with(:ids => ['04sU0000000WkdIIAS']).returns(:done)
+          savon.expects(:check_retrieve_status).with(:ids => ['04sU0000000WkdIIAS']).returns(:success)
+        end
+
+        it "returns a valid retrieve result" do
+          retrieval = client.retrieve_unpackaged(File.expand_path('../../../fixtures/sample/src/package.xml', __FILE__))
+          retrieval.done?
+          result = retrieval.result
+          result.should be_a(Hash)
+        end
+
+      end
+
+      context "when given extra retrieve options" do
+        before(:each) do
+          savon.expects(:retrieve).with(:retrieve_request => { :api_version => Metaforce.configuration.api_version, :single_package => true, :unpackaged => { :types => manifest.to_package }, :extra => true }).returns(:in_progress)
+        end
+
+        it "merges the options" do
+          expect {
+            retrieval = client.retrieve_unpackaged(File.expand_path('../../../fixtures/sample/src/package.xml', __FILE__), { :extra => true })
+          }.to_not raise_error
+        end
+
+      end
     end
-    
+
   end
 end

data/spec/lib/dsl_spec.rb

@@ -0,0 +1,93 @@
+require "spec_helper"
+require "metaforce/dsl"
+include Metaforce::DSL::Metadata
+
+describe Metaforce::DSL::Metadata do
+
+  let(:manifest) do
+    Metaforce::Manifest.new(File.open(File.expand_path('../../fixtures/sample/src/package.xml', __FILE__)).read)
+  end
+
+  let(:valid_credentials) do
+    { :username => 'valid', :password => 'password' }
+  end
+
+  describe ".login" do
+
+    before(:each) do
+      savon.expects(:login).with(valid_credentials).returns(:success)
+    end
+
+    it "logs the user in" do
+      expect { login valid_credentials }.to_not raise_error
+    end
+
+  end
+
+  describe ".deploy" do
+
+    before(:each) do
+      Metaforce::Metadata::Client.any_instance.stubs(:create_deploy_file).returns('')
+      savon.expects(:login).with(valid_credentials).returns(:success)
+      savon.expects(:deploy).with(:zip_file => '', :deploy_options => {}).returns(:in_progress)
+      savon.expects(:check_status).with(:ids => [ "04sU0000000WNWoIAO" ]).returns(:done)
+      savon.expects(:check_deploy_status).with(:ids => [ "04sU0000000WNWoIAO" ]).returns(:done)
+    end
+
+    context "when given a directory" do
+
+      it "deploys the directory" do
+        login valid_credentials
+        expect {
+          deploy File.expand_path('../../../fixtures/sample', __FILE__) do |result|
+            result.should be_a(Hash)
+          end
+        }.to_not raise_error
+      end
+
+    end
+
+  end
+
+  describe ".retrieve" do
+    before(:each) do
+      savon.expects(:login).with(valid_credentials).returns(:success)
+      savon.expects(:retrieve).with(:retrieve_request => { :api_version => Metaforce.configuration.api_version, :single_package => true, :unpackaged => { :types => manifest.to_package } }).returns(:in_progress)
+      savon.expects(:check_status).with(:ids => ['04sU0000000WkdIIAS']).returns(:done)
+      savon.expects(:check_retrieve_status).with(:ids => ['04sU0000000WkdIIAS']).returns(:success)
+    end
+
+    context "when given a manifest file" do
+
+      it "retrieves the components" do
+        login valid_credentials
+        expect {
+          retrieve manifest do |result, zip|
+            result.should be_a(Hash)
+            zip.should be_a(String)
+          end
+        }.to_not raise_error
+      end
+
+      context "and :to is specified" do
+
+        before(:each) do
+          Metaforce::Transaction.any_instance.stubs(:unzip).returns('')
+        end
+
+        it "retrieves the components and unzips them to the directory" do
+          login valid_credentials
+          expect {
+            retrieve manifest, :to => "test_retrieve" do |result, zip|
+              result.should be_a(Hash)
+              zip.should be_a(String)
+            end
+          }.to_not raise_error
+        end
+
+      end
+
+    end
+
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: metaforce
 version: !ruby/object:Gem::Version
-  version: 0.2.0.alpha
+  version: 0.3.0.alpha
   prerelease: 6
 platform: ruby
 authors:
@@ -9,44 +9,55 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-01-27 00:00:00.000000000 Z
+date: 2012-01-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: nokogiri
-  requirement: &2168826860 !ruby/object:Gem::Requirement
+  requirement: &3632840 !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 1.5.0
   type: :runtime
   prerelease: false
-  version_requirements: *2168826860
+  version_requirements: *3632840
 - !ruby/object:Gem::Dependency
   name: savon
-  requirement: &2168825720 !ruby/object:Gem::Requirement
+  requirement: &3631640 !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.9.7
   type: :runtime
   prerelease: false
-  version_requirements: *2168825720
+  version_requirements: *3631640
 - !ruby/object:Gem::Dependency
   name: rubyzip
-  requirement: &2168824120 !ruby/object:Gem::Requirement
+  requirement: &3630690 !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ~>
+      - !ruby/object:Gem::Version
+        version: 0.9.5
+  type: :runtime
+  prerelease: false
+  version_requirements: *3630690
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: &3629920 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-  type: :runtime
+  type: :development
   prerelease: false
-  version_requirements: *2168824120
+  version_requirements: *3629920
 - !ruby/object:Gem::Dependency
   name: rspec
-  requirement: &2168822980 !ruby/object:Gem::Requirement
+  requirement: &3629280 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -54,10 +65,10 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2168822980
+  version_requirements: *3629280
 - !ruby/object:Gem::Dependency
   name: mocha
-  requirement: &2168821960 !ruby/object:Gem::Requirement
+  requirement: &3627890 !ruby/object:Gem::Requirement
     none: false
     requirements:
     - - ! '>='
@@ -65,18 +76,18 @@ dependencies:
         version: '0'
   type: :development
   prerelease: false
-  version_requirements: *2168821960
+  version_requirements: *3627890
 - !ruby/object:Gem::Dependency
   name: savon_spec
-  requirement: &2168820680 !ruby/object:Gem::Requirement
+  requirement: &3625600 !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '0'
+        version: 0.1.6
   type: :development
   prerelease: false
-  version_requirements: *2168820680
+  version_requirements: *3625600
 description: A Ruby gem for interacting with the Salesforce Metadata API
 email:
 - eric@ejholmes.net
@@ -85,7 +96,7 @@ extensions: []
 extra_rdoc_files: []
 files:
 - .gitignore
-- .rvmrc
+- .travis.yml
 - Gemfile
 - Guardfile
 - README.md
@@ -96,6 +107,7 @@ files:
 - lib/metaforce/api/services.rb
 - lib/metaforce/api/transaction.rb
 - lib/metaforce/config.rb
+- lib/metaforce/dsl.rb
 - lib/metaforce/manifest.rb
 - lib/metaforce/version.rb
 - metaforce.gemspec
@@ -103,6 +115,7 @@ files:
 - spec/fixtures/package.xml
 - spec/fixtures/requests/check_deploy_status/done.xml
 - spec/fixtures/requests/check_deploy_status/error.xml
+- spec/fixtures/requests/check_retrieve_status/success.xml
 - spec/fixtures/requests/check_status/done.xml
 - spec/fixtures/requests/check_status/not_done.xml
 - spec/fixtures/requests/deploy/in_progress.xml
@@ -110,6 +123,7 @@ files:
 - spec/fixtures/requests/list_metadata/objects.xml
 - spec/fixtures/requests/login/failure.xml
 - spec/fixtures/requests/login/success.xml
+- spec/fixtures/requests/retrieve/in_progress.xml
 - spec/fixtures/sample/src/classes/TestClass.cls
 - spec/fixtures/sample/src/classes/TestClass.cls-meta.xml
 - spec/fixtures/sample/src/package.xml
@@ -117,6 +131,7 @@ files:
 - spec/lib/api/services_spec.rb
 - spec/lib/api/transaction_spec.rb
 - spec/lib/config_spec.rb
+- spec/lib/dsl_spec.rb
 - spec/lib/manifest_spec.rb
 - spec/spec_helper.rb
 - wsdl/23.0/metadata.xml
@@ -149,6 +164,7 @@ test_files:
 - spec/fixtures/package.xml
 - spec/fixtures/requests/check_deploy_status/done.xml
 - spec/fixtures/requests/check_deploy_status/error.xml
+- spec/fixtures/requests/check_retrieve_status/success.xml
 - spec/fixtures/requests/check_status/done.xml
 - spec/fixtures/requests/check_status/not_done.xml
 - spec/fixtures/requests/deploy/in_progress.xml
@@ -156,6 +172,7 @@ test_files:
 - spec/fixtures/requests/list_metadata/objects.xml
 - spec/fixtures/requests/login/failure.xml
 - spec/fixtures/requests/login/success.xml
+- spec/fixtures/requests/retrieve/in_progress.xml
 - spec/fixtures/sample/src/classes/TestClass.cls
 - spec/fixtures/sample/src/classes/TestClass.cls-meta.xml
 - spec/fixtures/sample/src/package.xml
@@ -163,5 +180,6 @@ test_files:
 - spec/lib/api/services_spec.rb
 - spec/lib/api/transaction_spec.rb
 - spec/lib/config_spec.rb
+- spec/lib/dsl_spec.rb
 - spec/lib/manifest_spec.rb
 - spec/spec_helper.rb

data/.rvmrc

@@ -1,55 +0,0 @@
-#!/usr/bin/env bash
-
-# This is an RVM Project .rvmrc file, used to automatically load the ruby
-# development environment upon cd'ing into the directory
-
-# First we specify our desired <ruby>[@<gemset>], the @gemset name is optional.
-environment_id="ruby-1.9.2-p290@metaforce"
-
-#
-# Uncomment following line if you want options to be set only for given project.
-#
-# PROJECT_JRUBY_OPTS=( --1.9 )
-
-#
-# First we attempt to load the desired environment directly from the environment
-# file. This is very fast and efficient compared to running through the entire
-# CLI and selector. If you want feedback on which environment was used then
-# insert the word 'use' after --create as this triggers verbose mode.
-#
-if [[ -d "${rvm_path:-$HOME/.rvm}/environments" \
-  && -s "${rvm_path:-$HOME/.rvm}/environments/$environment_id" ]]
-then
-  \. "${rvm_path:-$HOME/.rvm}/environments/$environment_id"
-
-  if [[ -s "${rvm_path:-$HOME/.rvm}/hooks/after_use" ]]
-  then
-    . "${rvm_path:-$HOME/.rvm}/hooks/after_use"
-  fi
-else
-  # If the environment file has not yet been created, use the RVM CLI to select.
-  if ! rvm --create  "$environment_id"
-  then
-    echo "Failed to create RVM environment '${environment_id}'."
-    return 1
-  fi
-fi
-
-#
-# If you use an RVM gemset file to install a list of gems (*.gems), you can have
-# it be automatically loaded. Uncomment the following and adjust the filename if
-# necessary.
-#
-# filename=".gems"
-# if [[ -s "$filename" ]]
-# then
-#   rvm gemset import "$filename" | grep -v already | grep -v listed | grep -v complete | sed '/^$/d'
-# fi
-
-# If you use bundler, this might be useful to you:
-# if command -v bundle && [[ -s Gemfile ]]
-# then
-#   bundle install
-# fi
-
-