derelict 0.0.1 → 0.1.0

checksums.yaml

@@ -1,15 +1,7 @@
 ---
-!binary "U0hBMQ==":
-  metadata.gz: !binary |-
-    YzA4ZGRlMzg1YWNjOGYzZmI2MzhlZDVlMTNiYjI5MDhmYzAxZjNmOA==
-  data.tar.gz: !binary |-
-    N2RmNTAwOTcwM2VkYTFmNGZmZDQ4NzI2NDhlYTgxNTZlODVjNzU3Mw==
+SHA1:
+  metadata.gz: 4fa06a401e855d7793e04db862ea95dab0af609b
+  data.tar.gz: b0f47b9b5f6a5c4613cea9e73f422c62c68b3b50
 SHA512:
-  metadata.gz: !binary |-
-    YTM4NDgzOWUzYjQ0NzI4ODQ5OWFmMzE3MzU4NzFmNjhmMGU3NDM2OGNkZGZm
-    NzAxMmQ0ZGQxNzMyZjljZTc2MWU3MGVkOGU0OTcwMzdhMjBhMmZlZGEzZWQy
-    ZGU2NjAwNDhiNTNlNGFhNTVjMWExNjEyYjAyYjdhMjJiNTQ5MGE=
-  data.tar.gz: !binary |-
-    MmFkMmJkMjk1ZWRlNTY2N2IxYTc5ZTU5NWFhZjMxZTQ4MDI4YjQ1MDRlMzg3
-    N2Q5ZDhjZmQxOTYyZDEzNmFiYzE1ZDY5MDhmYzg4N2I0NTY2MzIxYWM1NjEw
-    MDMxNmUwNjRhYTgzM2QyODRkNDljNmM5ZDY2NDA5Mjk5YTMzZGU=
+  metadata.gz: 022c6640fd37eaf97cfa45a1d8d5ff8fed190487d032614ba138beace12b52dd94419018b006444153289fe440740a24c17f070b1ccb6a89e4bf87aa889b8228
+  data.tar.gz: a0e5c3a9c89be92bedb6310299634e4bf9d8cf3bd00396ff7a6b457adcc3647497400821190e3e103c8e000dc258b0c14abc675404e9a9a71b43aed783d048de

data/.cane

@@ -0,0 +1,2 @@
+--style-exclude spec/**/*.rb
+--gte coverage/.last_run.json,100

data/.coveralls.yml

@@ -0,0 +1 @@
+service_name: travis-ci

data/.travis.yml

@@ -0,0 +1,13 @@
+language: ruby
+rvm:
+  - 1.8.7
+  - 1.9.3
+  - 2.0.0
+deploy:
+  provider: rubygems
+  api_key:
+    secure: lm8VbzXJIylbk3bHC5KBU7x0zI5zDHgOaYUkrc4z8R2gjdW9RLAoX8dwJ0N2FEX24zMf3s1fPT4dg70YD2S7FnVy3zan25BP2C2FKGkQ5kqRzV+gJCSD0Hwk8Yj5Breh1RF3xutV12asLq/+rltei7Fu6BnE2pQDk9/gGSCxILs=
+  gem: derelict
+  on:
+    repo: bradfeehan/derelict
+    ruby: 2.0.0

data/README.md

@@ -1,5 +1,11 @@
 # Derelict
 
+[![Gem Version](https://badge.fury.io/rb/derelict.png)](http://badge.fury.io/rb/derelict)
+[![Build Status](https://travis-ci.org/bradfeehan/derelict.png?branch=master)](https://travis-ci.org/bradfeehan/derelict)
+[![Coverage Status](https://coveralls.io/repos/bradfeehan/derelict/badge.png)](https://coveralls.io/r/bradfeehan/derelict)
+[![Code Climate](https://codeclimate.com/github/bradfeehan/derelict.png)](https://codeclimate.com/github/bradfeehan/derelict)
+[![Dependency Status](https://gemnasium.com/bradfeehan/derelict.png)](https://gemnasium.com/bradfeehan/derelict)
+
 Provides a Ruby API to control [Vagrant][1] where Vagrant is installed
 via the Installer package on Mac OS X.
 
@@ -13,15 +19,9 @@ Currently a work-in-progress.
 Vagrant was historically available as a [gem][2], naturally providing a
 Ruby API to control Vagrant in other Ruby libraries and applications.
 However, [since version 1.1.0][3], [Vagrant is distributed exclusively
-using an Installer package][4]. To control Vagrant when it's installed
-this way, other Ruby libraries and applications typically need to
-invoke the Vagrant binary, which requires forking a new process and
-parsing its output using string manipulation.
-
-Derelict is a Ruby gem that can control an instance of Vagrant that's
-installed with the Installer package, which avoids calling the Vagrant
-binary by interfacing directly with the Ruby source files in the
-Vagrant installation.
+using an Installer package][4]. Derelict is a Ruby library that wraps
+the Vagrant binary, shelling out and parsing the results of each
+command.
 
 [2]: <https://rubygems.org>
 [3]: <https://groups.google.com/forum/#!msg/vagrant-up/kX_wvn7wcds/luwNur4kgDEJ>
@@ -43,6 +43,52 @@ Or install it yourself as:
     $ gem install derelict
 
 
+## Usage
+
+Some examples of common operations using Derelict:
+
+```ruby
+require "derelict"
+
+# Determine if there's a "default" VM defined in /path/to/project
+Derelict.instance.connect("/path/to/project").vm(:default).exists?
+```
+
+### Advanced
+
+```ruby
+require "derelict"
+
+# Create an instance (represents a Vagrant installation)
+instance = Derelict.instance("/path/to/vagrant")
+instance = Derelict.instance # Defaults to /Applications/Vagrant
+
+# Issue commands to the instance directly (not usually necessary)
+result = instance.execute('--version') # Shell::Executer object
+print "success" if result.success?     # if Vagrant's exit status was 0
+print result.stdout                    # "Vagrant 1.3.3\n"
+
+# Connect to a Vagrant project (containing a Vagrantfile)
+connection = instance.connect("/path/to/project")
+
+# Issue commands to the connection directly (runs from the project dir)
+result = connection.execute(:up) # runs "vagrant up" in project dir
+result.success?                  # it's a Shell::Executer object again
+
+# Retrieve a particular VM from a connection (multi-machine support)
+vm = connection.vm(:web) # "vm" is a Derelict::VirtualMachine
+vm.exists?               # does the connection define a "web" VM?
+vm.state                 # current VM state (:running, :not_created...)
+vm.running?              # whether the VM is currently running or not
+vm.up!                   # runs "vagrant up" for this VM only
+vm.halt!                 # runs "vagrant halt" for this VM only
+vm.destroy!              # runs "vagrant destroy --force" for this VM
+vm.reload!               # runs "vagrant reload" for this VM only
+vm.suspend!              # runs "vagrant suspend" for this VM only
+vm.resume!               # runs "vagrant resume" for this VM only
+```
+
+
 ## Contributing
 
 1. Fork it

data/Rakefile

@@ -1 +1,22 @@
 require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+# Define "spec" task using RSpec's built-in Rake task
+RSpec::Core::RakeTask.new :spec do |spec|
+  spec.verbose = false
+end
+
+version_major = RbConfig::CONFIG["MAJOR"].to_i
+version_minor = RbConfig::CONFIG["MINOR"].to_i
+if version_major >= 1 and version_minor >= 9
+  require "cane/rake_task"
+
+  # Define "quality" task using Cane's built-in Rake task
+  Cane::RakeTask.new :quality do |quality|
+    quality.canefile = File.join File.dirname(__FILE__), ".cane"
+  end
+
+  task :default => [:spec, :quality]
+else
+  task :default => :spec
+end

data/derelict.gemspec

@@ -20,7 +20,7 @@ Gem::Specification.new do |spec|
     "applications typically need to invoke the Vagrant binary, which ",
     "requires forking a new process and parsing its output using ",
     "string manipulation.",
-  ].join
+  ].join,
   spec.summary       =
     "Ruby API for Vagrant installed via Installer package on Mac OS X."
   spec.homepage      = "https://github.com/bradfeehan/derelict"
@@ -31,7 +31,31 @@ Gem::Specification.new do |spec|
   spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
   spec.require_paths = ["lib"]
 
+  spec.add_runtime_dependency "log4r"
+  spec.add_runtime_dependency "memoist"
+  spec.add_runtime_dependency "shell-executer"
+
+
+  version_major = RbConfig::CONFIG["MAJOR"].to_i
+  version_minor = RbConfig::CONFIG["MINOR"].to_i
+  cane_supported = (version_major >= 1 and version_minor >= 9)
+
   spec.add_development_dependency "bundler", "~> 1.3"
+  spec.add_development_dependency "cane" if cane_supported
+  spec.add_development_dependency "coveralls"
   spec.add_development_dependency "rake"
   spec.add_development_dependency "rspec"
+  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency "its"
+
+  # When running on Travis CI, any passing builds will be deployed
+  # (i.e. pushed to RubyGems). This changes the version number so that
+  # these deployments are marked as pre-release versions (which will
+  # occur if the version number has a letter in it, so we add
+  # "travis" followed by the job number to the version string).
+  # So version 1.2.3 will be marked as (e.g.) "1.2.4.travis.567".
+  if ENV["TRAVIS"]
+    build = ENV["TRAVIS_JOB_NUMBER"].split(".").first
+    spec.version = "#{spec.version.to_s.succ}.travis.#{build}"
+  end
 end

data/lib/derelict/connection/invalid.rb

@@ -0,0 +1,14 @@
+module Derelict
+  class Connection
+    # Represents an invalid connection, which Derelict can't use
+    class Invalid < Derelict::Exception
+      include Derelict::Exception::OptionalReason
+
+      private
+        # Retrieves the default error message
+        def default_message
+          "Invalid Derelict connection"
+        end
+    end
+  end
+end

data/lib/derelict/connection/not_found.rb

@@ -0,0 +1,13 @@
+module Derelict
+  class Connection
+    # The Vagrantfile for the connection was not found
+    class NotFound < Invalid
+      # Initializes a new instance of this exception for a given path
+      #
+      #   * path: The requested path of the instance
+      def initialize(path)
+        super "Vagrantfile not found for #{path}"
+      end
+    end
+  end
+end

data/lib/derelict/connection.rb

@@ -0,0 +1,84 @@
+module Derelict
+  # Connects a Derelict::Instance to its use in a particular directory
+  class Connection
+    autoload :Invalid,  "derelict/connection/invalid"
+    autoload :NotFound, "derelict/connection/not_found"
+
+    # Include "logger" method to get a logger for this class
+    include Utils::Logger
+
+    attr_reader :instance
+    attr_reader :path
+
+    # Initializes a Connection for use in a particular directory
+    #
+    #   * instance: The Derelict::Instance to use to control Vagrant
+    #   * path:     The project path, which contains the Vagrantfile
+    def initialize(instance, path)
+      @instance = instance
+      @path = path
+      logger.debug "Successfully initialized #{description}"
+    end
+
+    # Validates the data used for this connection
+    #
+    # Raises exceptions on failure:
+    #
+    #   * +Derelict::Connection::NotFound+ if the path is not found
+    def validate!
+      logger.debug "Starting validation for #{description}"
+      raise NotFound.new path unless File.exists? path
+      logger.info "Successfully validated #{description}"
+      self
+    end
+
+    # Executes a Vagrant subcommand using this connection
+    #
+    #   * subcommand: Vagrant subcommand to run (:up, :status, etc.)
+    #   * arguments:  Arguments to pass to the subcommand (optional)
+    #   * block:      Passed through to @instance#execute
+    def execute(subcommand, *arguments, &block)
+      log_execute subcommand, *arguments
+      Dir.chdir path do
+        instance.execute subcommand.to_sym, *arguments, &block
+      end
+    end
+
+    # Executes a Vagrant subcommand, raising an exception on failure
+    #
+    #   * subcommand: Vagrant subcommand to run (:up, :status, etc.)
+    #   * arguments:  Arguments to pass to the subcommand (optional)
+    #   * block:      Passed through to Shell.execute (shell-executer)
+    #
+    # Raises +Derelict::Instance::CommandFailed+ if the command fails.
+    def execute!(subcommand, *arguments, &block)
+      log_execute subcommand, *arguments
+      Dir.chdir path do
+        instance.execute! subcommand.to_sym, *arguments, &block
+      end
+    end
+
+    # Retrieves a Derelict::VirtualMachine for a particular VM
+    #
+    #   * name: The name of the virtual machine to retrieve
+    def vm(name)
+      logger.debug "Retrieving VM '#{name}' from #{description}"
+      Derelict::VirtualMachine.new(self, name).validate!
+    end
+
+    # Provides a description of this Connection
+    #
+    # Mainly used for log messages.
+    def description
+      "Derelict::Connection at '#{path}' using #{instance.description}"
+    end
+
+    private
+      # Handles the logging that should occur for a call to #execute(!)
+      def log_execute(subcommand, *arguments)
+        logger.debug do
+          "Executing #{subcommand} #{arguments.inspect} on #{description}"
+        end
+      end
+  end
+end

data/lib/derelict/exception/optional_reason.rb

@@ -0,0 +1,32 @@
+module Derelict
+  class Exception
+    # An exception that has a message and optional additional reason
+    #
+    # The reason can be passed to the constructor (if desired). When a
+    # reason is passed, it's appended to the default message. If no
+    # reason is passed, the default message is used.
+    module OptionalReason
+      # Initializes a new instance of this exception, with a reason
+      #
+      #   * reason: Optional reason to add to the default error message
+      #             (optional, the default message will be used if no
+      #             reason is provided)
+      def initialize(reason = nil)
+        if reason.nil?
+          super default_message
+        else
+          super "#{default_message}: #{reason}"
+        end
+      end
+
+      private
+        # Retrieves the default error message
+        #
+        # This needs to be overridden in child classes in order to
+        # customize the default error message.
+        def default_message
+          raise NotImplementedError.new "#default_message not defined"
+        end
+    end
+  end
+end

data/lib/derelict/exception.rb

@@ -1,5 +1,6 @@
-class Derelict
-  # The base class for exceptions thrown by Derelict
+module Derelict
+  # Base class for any exceptions thrown by Derelict
   class Exception < ::Exception
+    autoload :OptionalReason, "derelict/exception/optional_reason"
   end
 end

data/lib/derelict/instance/command_failed.rb

@@ -0,0 +1,28 @@
+module Derelict
+  class Instance
+    # Represents an invalid instance, which can't be used with Derelict
+    class CommandFailed < Derelict::Exception
+      # Initializes a new instance of this exception, with a reason
+      #
+      #   * reason: The result (Shell::Executer) for the command that
+      #             failed (optional, provides extra detail in the
+      #             message)
+      def initialize(command = nil, result = nil)
+        super [default_message, describe(command, result)].join
+      end
+
+      private
+        # Retrieves the default error message
+        def default_message
+          "Error executing Vagrant command"
+        end
+
+        def describe(command = nil, result = nil)
+          [
+            command.nil? ? "" : " '#{command}'",
+            result.nil? ? "" : ", STDERR output:\n#{result.stderr}",
+          ].join
+        end
+    end
+  end
+end

data/lib/derelict/instance/invalid.rb

@@ -1,14 +1,14 @@
-class Derelict
-  # The requested Vagrant instance can't be used with Derelict
-  class Instance::Invalid < Exception
-    # Initialize with a default message (with optional detailed reason)
-    #
-    #   reason: An additional reason to add to the message (optional)
-    def initialize(reason = nil)
-      super [
-        "Derelict can't use the specified Vagrant instance",
-        reason.nil? ? '' : ": #{reason}"
-      ].join
+module Derelict
+  class Instance
+    # Represents an invalid instance, which can't be used with Derelict
+    class Invalid < Derelict::Exception
+      include Derelict::Exception::OptionalReason
+
+      private
+        # Retrieves the default error message
+        def default_message
+          "Invalid Derelict instance"
+        end
     end
   end
 end

data/lib/derelict/instance/missing_binary.rb

@@ -0,0 +1,13 @@
+module Derelict
+  class Instance
+    # The "vagrant" binary was missing from the instance
+    class MissingBinary < Invalid
+      # Initializes a new instance of this exception for a given file
+      #
+      #   * file: The expected location of the binary
+      def initialize(file)
+        super "'vagrant' binary not found at #{file}"
+      end
+    end
+  end
+end

data/lib/derelict/instance/non_directory.rb

@@ -1,11 +1,13 @@
-class Derelict::Instance
-  # The requested Vagrant instance path is not a directory
-  class NonDirectory < Invalid
-    # Creates an instance of this exception for a particular path
-    #
-    #   path: The path that this exception relates to
-    def initialize(path)
-      super "not a directory: #{path}"
+module Derelict
+  class Instance
+    # The path used for the instance was a file, not a directory
+    class NonDirectory < Invalid
+      # Initializes a new instance of this exception for a given path
+      #
+      #   * path: The requested path of the instance
+      def initialize(path)
+        super "expected directory, found file: #{path}"
+      end
     end
   end
 end

data/lib/derelict/instance/not_found.rb

@@ -1,11 +1,13 @@
-class Derelict::Instance
-  # The requested Vagrant instance directory doesn't exist
-  class NotFound < Invalid
-    # Creates an instance of this exception for a particular path
-    #
-    #   path: The path that this exception relates to
-    def initialize(path)
-      super "directory not found: #{path}"
+module Derelict
+  class Instance
+    # The path used for the instance was not found
+    class NotFound < Invalid
+      # Initializes a new instance of this exception for a given path
+      #
+      #   * path: The requested path of the instance
+      def initialize(path)
+        super "directory doesn't exist: #{path}"
+      end
     end
   end
 end

data/lib/derelict/instance.rb

@@ -1,53 +1,125 @@
-class Derelict
-  # Represents a connection to an package-installed instance of Vagrant
+module Derelict
+  # Represents a Vagrant instance installed via the Installer package
   class Instance
-    autoload :AlreadyActive, "derelict/instance/already_active"
+    autoload :CommandFailed, "derelict/instance/command_failed"
+    autoload :Invalid,       "derelict/instance/invalid"
+    autoload :MissingBinary, "derelict/instance/missing_binary"
     autoload :NonDirectory,  "derelict/instance/non_directory"
     autoload :NotFound,      "derelict/instance/not_found"
 
-    attr_reader :namespace
+    # Include "memoize" class method to memoize methods
+    extend Memoist
 
-    # Initializes a new instance
+    # Include "logger" method to get a logger for this class
+    include Utils::Logger
+
+    # The default path to the Vagrant installation folder
+    DEFAULT_PATH = "/Applications/Vagrant"
+
+    attr_reader :path
+
+    # Initialize an instance for a particular directory
     #
-    #   path: The path to the location of the Vagrant instance
-    def initialize(path)
-      raise NotFound.new unless File.exists? path
-      raise NonDirectory.new unless File.directory? path
-      @path = path.chomp "/"
+    #   * path: The path to the Vagrant installation folder (optional,
+    #           defaults to DEFAULT_PATH)
+    def initialize(path = DEFAULT_PATH)
+      @path = path
+      logger.debug "Successfully initialized #{description}"
     end
 
-    # Loads the Vagrant module into an instance variable
-    def activate!
-      raise AlreadyActive.new if Derelict.active?
+    # Validates the data used for this instance
+    #
+    # Raises exceptions on failure:
+    #
+    #   * +Derelict::Instance::NotFound+ if the instance is not found
+    #   * +Derelict::Instance::NonDirectory+ if the path is a file,
+    #     instead of a directory as expected
+    #   * +Derelict::Instance::MissingBinary+ if the "vagrant" binary
+    #     isn't in the expected location or is not executable
+    def validate!
+      logger.debug "Starting validation for #{description}"
+      raise NotFound.new path unless File.exists? path
+      raise NonDirectory.new path unless File.directory? path
+      raise MissingBinary.new vagrant unless File.exists? vagrant
+      raise MissingBinary.new vagrant unless File.executable? vagrant
+      logger.info "Successfully validated #{description}"
+      self
+    end
 
-      gemspec_files.each {|gemspec_file|
-        Gem::Specification.load(gemspec_file).add_self_to_load_path
-      }
+    # Determines the version of this Vagrant instance
+    def version
+      logger.info "Determining Vagrant version for #{description}"
+      output = execute!("--version").stdout
+      Derelict::Parser::Version.new(output).version
+    end
+    memoize :version
 
-      require vagrant_entrypoint
+    # Executes a Vagrant subcommand using this instance
+    #
+    #   * subcommand: Vagrant subcommand to run (:up, :status, etc.)
+    #   * arguments:  Arguments to pass to the subcommand (optional)
+    #   * block:      Passed through to Shell.execute (shell-executer)
+    def execute(subcommand, *arguments, &block)
+      command = command(subcommand, *arguments)
+      logger.debug "Executing #{command} using #{description}"
+      Shell.execute command, &block
     end
 
-    # # Pass through any method calls to the Vagrant module
-    # def method_missing(method, *args)
-    #   @module.Vagrant.send method, args
-    # end
+    # Executes a Vagrant subcommand, raising an exception on failure
+    #
+    #   * subcommand: Vagrant subcommand to run (:up, :status, etc.)
+    #   * arguments:  Arguments to pass to the subcommand (optional)
+    #   * block:      Passed through to Shell.execute (shell-executer)
+    #
+    # Raises +Derelict::Instance::CommandFailed+ if the command fails.
+    def execute!(subcommand, *arguments, &block)
+      execute(subcommand, *arguments, &block).tap do |result|
+        unless result.success?
+          command = command(subcommand, *arguments)
+          exception = CommandFailed.new command
+          logger.warn "Command #{command} failed: #{exception.message}"
+          raise exception, result
+        end
+      end
+    end
+
+    # Initializes a Connection for use in a particular directory
+    #
+    #   * instance: The Derelict::Instance to use to control Vagrant
+    #   * path:     The project path, which contains the Vagrantfile
+    def connect(path)
+      logger.info "Creating connection for '#{path}' by #{description}"
+      Derelict::Connection.new(self, path).validate!
+    end
+
+    # Provides a description of this Instance
+    #
+    # Mainly used for log messages.
+    def description
+      "Derelict::Instance at '#{path}'"
+    end
 
     private
-      # Retrieves the path to the directory containing embedded gems
-      def gems_path
-        File.join @path, "embedded", "gems"
+      # Retrieves the path to the vagrant binary for this instance
+      def vagrant
+        File.join(@path, "bin", "vagrant").tap do |vagrant|
+          logger.debug "Vagrant binary for #{description} is '#{vagrant}'"
+        end
       end
+      memoize :vagrant
 
-      # Creates a pattern to match all embedded gemspec files
-      def gemspec_files
-        pattern = File.join gems_path, "specifications", "*.gemspec"
-        Dir.glob(pattern).sort
-      end
 
-      # Retrieves the absolute path of the main vagrant.rb in the gem
-      def vagrant_entrypoint
-        file = File.join gems_path, *%w[gems vagrant-* lib vagrant.rb]
-        Dir.glob(file).sort.last
+      # Constructs the command to execute a Vagrant subcommand
+      #
+      #   * subcommand: Vagrant subcommand to run (:up, :status, etc.)
+      #   * arguments:  Arguments to pass to the subcommand (optional)
+      def command(subcommand, *arguments)
+        args = [vagrant, subcommand.to_s, arguments].flatten
+        args.map {|a| Shellwords.escape a }.join(' ').tap do |command|
+          logger.debug "Generated command '#{command}' from " +
+            "subcommand '#{subcommand.to_s}' with arguments " +
+            arguments.inspect
+        end
       end
   end
 end

data/lib/derelict/parser/status/invalid_format.rb

@@ -0,0 +1,16 @@
+module Derelict
+  class Parser
+    class Status
+      # The status wasn't in the expected format and couldn't be parsed
+      class InvalidFormat < Derelict::Exception
+        include Derelict::Exception::OptionalReason
+
+        private
+          # Retrieves the default error message
+          def default_message
+            "Output from 'vagrant status' was in an unexpected format"
+          end
+      end
+    end
+  end
+end