derelict 0.0.1 → 0.1.0

data/lib/derelict/parser/status.rb

@@ -0,0 +1,89 @@
+module Derelict
+  # Parses the output of "vagrant status"
+  class Parser::Status < Parser
+    autoload :InvalidFormat, "derelict/parser/status/invalid_format"
+
+    # Include "memoize" class method to memoize methods
+    extend Memoist
+
+    # Regexp to extract the VM list from the "vagrant status" output
+    PARSE_LIST_FROM_OUTPUT = /\n\n((?:.*\n)+)\n/
+
+    # Regexp to extract the state from a line in the VM list
+    PARSE_STATE_FROM_LIST_ITEM = %r[
+      ^(.*?) # VM name starts at the start of the line,
+      \s{2,} # to the first instance of 2 or more spaces.
+      (.*?)  # VM state starts after the whitespace,
+      \s+\(  # continuing until whitespace and open bracket.
+        (.*) # The provider name starts after the bracket,
+      \)$    # and ends at a closing bracket at line end.
+      ]x     # Ignore whitespace to allow these comments
+
+    # Retrieves the names of all virtual machines in the output
+    #
+    # The names are returned as a Set of symbols.
+    def vm_names
+      Set[*states.keys]
+    end
+
+    # Determines if a particular virtual machine exists in the output
+    #
+    #   * vm_name: The name of the virtual machine to look for
+    def exists?(vm_name)
+      vm_names.include? vm_name.to_sym
+    end
+
+    # Determines the state of a particular virtual machine
+    #
+    # The state is returned as a symbol, e.g. :running.
+    #
+    #   * vm_name: The name of the virtual machine to retrieve state
+    def state(vm_name)
+      unless states.include? vm_name.to_sym
+        raise Derelict::VirtualMachine::NotFound.new vm_name
+      end
+
+      states[vm_name.to_sym]
+    end
+
+    # Provides a description of this Parser
+    #
+    # Mainly used for log messages.
+    def description
+      "Derelict::Parser::Status instance"
+    end
+
+    private
+      # Retrieves the virtual machine list section of the output
+      def vm_lines
+        output.match(PARSE_LIST_FROM_OUTPUT).tap {|list|
+          logger.debug "Parsing VM list from output using #{description}"
+          raise InvalidFormat.new "Couldn't find VM list" if list.nil?
+        }.captures[0].lines
+      end
+      memoize :vm_lines
+
+      # Retrieves the state data for all virtual machines in the output
+      #
+      # The state is returned as a Hash, mapping virtual machine names
+      # (as symbols) to their state (also as a symbol). Both of these
+      # symbols have spaces converted to underscores (for convenience
+      # when writing literals in other code).
+      def states
+        logger.debug "Parsing states from VM list using #{description}"
+        vm_lines.inject Hash.new do |hash, line|
+          hash.merge! parse_line(line.match PARSE_STATE_FROM_LIST_ITEM)
+        end
+      end
+      memoize :states
+
+      def parse_line(match)
+        raise InvalidFormat.new "Couldn't parse VM list" if match.nil?
+        Hash[*match.captures[0..1].map {|value| sanitize value }]
+      end
+
+      def sanitize(value)
+        value.to_s.gsub(/\s+/, "_").downcase.to_sym
+      end
+  end
+end

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

@@ -0,0 +1,16 @@
+module Derelict
+  class Parser
+    class Version
+      # The version 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 --version' was in an unexpected format"
+          end
+      end
+    end
+  end
+end

data/lib/derelict/parser/version.rb

@@ -0,0 +1,28 @@
+module Derelict
+  # Parses the output of "vagrant --version"
+  class Parser::Version < Parser
+    autoload :InvalidFormat, "derelict/parser/version/invalid_format"
+
+    # Include "memoize" class method to memoize methods
+    extend Memoist
+
+    # Regexp to extract the version from the "vagrant --version" output
+    PARSE_VERSION_FROM_OUTPUT = /^Vagrant v(?:ersion )?(.*)?$/
+
+    # Determines the version of Vagrant based on the output
+    def version
+      logger.debug "Parsing version from output using #{description}"
+      matches = output.match PARSE_VERSION_FROM_OUTPUT
+      raise InvalidFormat.new output if matches.nil?
+      matches.captures[0]
+    end
+    memoize :version
+
+    # Provides a description of this Parser
+    #
+    # Mainly used for log messages.
+    def description
+      "Derelict::Parser::Version instance"
+    end
+  end
+end

data/lib/derelict/parser.rb

@@ -0,0 +1,25 @@
+module Derelict
+  # Base class for parsers, which extract data from command output
+  class Parser
+    autoload :Status,  "derelict/parser/status"
+    autoload :Version, "derelict/parser/version"
+
+    # Include "logger" method to get a logger for this class
+    include Utils::Logger
+
+    attr_reader :output
+
+    # Initializes the parser with the output it will be parsing
+    def initialize(output)
+      @output = output
+      logger.debug "Successfully initialized #{description}"
+    end
+
+    # Provides a description of this Parser
+    #
+    # Mainly used for log messages.
+    def description
+      "Derelict::Parser (unknown type)"
+    end
+  end
+end

data/lib/derelict/utils/logger/array_outputter.rb

@@ -0,0 +1,43 @@
+module Derelict
+  module Utils
+    module Logger
+      # A Log4r Outputter which stores all logs in an array
+      #
+      # Logs are stored in the internal array by #write. Logs can be
+      # cleared using #flush, which returns the flushed logs too.
+      class ArrayOutputter < Log4r::Outputter
+        # Include "memoize" class method to memoize methods
+        extend Memoist
+
+        # Force the outputter to receive and store all levels of messages
+        def level
+          Log4r::ALL
+        end
+
+        # The internal array of messages
+        def messages
+          []
+        end
+        memoize :messages
+
+        # Clear internal log messages array and return the erased data
+        def flush
+          messages.dup.tap { messages.clear }
+        end
+
+        private
+
+          # Write a message to the internal array
+          #
+          # This is an abstract method in the parent class, and handles
+          # persisting the log data. In this class, it saves the message
+          # into an internal array to be retrieved later.
+          #
+          #   * message: The log message to be persisted
+          def write(message)
+            messages << message
+          end
+      end
+    end
+  end
+end

data/lib/derelict/utils/logger/invalid_type.rb

@@ -0,0 +1,15 @@
+module Derelict
+  module Utils
+    module Logger
+      # The "type" option when requesting the logger was invalid
+      class InvalidType < ::Derelict::Exception
+        # Initializes a new instance of this exception for a type
+        #
+        #   * type: The (invalid) requested type
+        def initialize(type)
+          super "Invalid logger type '#{type}'"
+        end
+      end
+    end
+  end
+end

data/lib/derelict/utils/logger/raw_formatter.rb

@@ -0,0 +1,12 @@
+module Derelict
+  module Utils
+    module Logger
+      # A Formatter that passes the log message through untouched
+      class RawFormatter < Log4r::Formatter
+        def format(event)
+          event.data
+        end
+      end
+    end
+  end
+end

data/lib/derelict/utils/logger.rb

@@ -0,0 +1,51 @@
+module Derelict
+  module Utils
+    # Provides a method to retrieve a logger
+    module Logger
+      autoload :ArrayOutputter, "derelict/utils/logger/array_outputter"
+      autoload :InvalidType,    "derelict/utils/logger/invalid_type"
+      autoload :RawFormatter,   "derelict/utils/logger/raw_formatter"
+
+      # Retrieves the logger for this class
+      def logger(options = {})
+        options = {:type => :internal}.merge(options)
+
+        case options[:type].to_sym
+          when :external
+            external_logger
+          when :internal
+            find_or_create_logger(logger_name)
+          else raise InvalidType.new options[:type]
+        end
+      end
+
+      private
+        # Finds or creates a Logger with a particular fullname
+        def find_or_create_logger(fullname)
+          Log4r::Logger[fullname.to_s] || Log4r::Logger.new(fullname.to_s)
+        end
+
+        # Gets the "external" logger, used to print to stdout
+        def external_logger
+          @@external ||= find_or_create_logger("external").tap do |external|
+            logger.debug "Created external logger instance"
+            external.add(Log4r::Outputter.stdout.tap do |outputter|
+              outputter.formatter = RawFormatter.new
+            end)
+          end
+        end
+
+        # Retrieves the name of the logger for this class
+        #
+        # By default, the name of the logger is just the lowercase
+        # version of the class name.
+        def logger_name
+          if self.is_a? Module
+            self.name.downcase
+          else
+            self.class.name.downcase
+          end
+        end
+    end
+  end
+end

data/lib/derelict/utils.rb

@@ -0,0 +1,11 @@
+module Derelict
+  # A namespaced collection of utilities for general purpose use
+  #
+  # Derelict::Utils contains all the individual sub-modules inside it.
+  module Utils
+    autoload :Logger,    "derelict/utils/logger"
+
+    # Include sub-modules here
+    include Derelict::Utils::Logger
+  end
+end

data/lib/derelict/version.rb

@@ -1,3 +1,3 @@
-class Derelict
-  VERSION = "0.0.1"
+module Derelict
+  VERSION = "0.1.0"
 end

data/lib/derelict/virtual_machine/invalid.rb

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

data/lib/derelict/virtual_machine/not_found.rb

@@ -0,0 +1,18 @@
+module Derelict
+  class VirtualMachine
+    # The requested virtual machine isn't defined in the Vagrantfile
+    class NotFound < Invalid
+      # Initializes a new instance of this exception for a given name
+      #
+      #   * name:       The requested name of the virtual machine
+      #   * connection: The Derelict connection used for this VM
+      def initialize(name, connection = nil)
+        if connection.respond_to? :path
+          super "Virtual machine #{name} not found in #{connection.path}"
+        else
+          super "Virtual machine #{name} not found"
+        end
+      end
+    end
+  end
+end

data/lib/derelict/virtual_machine.rb

@@ -0,0 +1,154 @@
+module Derelict
+  # A Vagrant virtual machine in a particular Derelict connection
+  class VirtualMachine
+    autoload :Invalid,  "derelict/virtual_machine/invalid"
+    autoload :NotFound, "derelict/virtual_machine/not_found"
+
+    # Include "memoize" class method to memoize methods
+    extend Memoist
+
+    # Include "logger" method to get a logger for this class
+    include Utils::Logger
+
+    COMMANDS = [
+      :up,
+      :halt,
+      :destroy,
+      :reload,
+      :suspend,
+      :resume,
+    ]
+
+    attr_reader :connection
+    attr_reader :name
+
+    # Initializes a new VirtualMachine for a connection and name
+    #
+    #   * connection: The +Derelict::Connection+ to use to manipulate
+    #                 the VirtualMachine instance
+    #   * name:       The name of the virtual machine, used when
+    #                 communicating with the connection)
+    def initialize(connection, name)
+      @connection = connection
+      @name = name
+      logger.debug "Successfully initialized #{description}"
+    end
+
+    # Validates the data used for this connection
+    #
+    # Raises exceptions on failure:
+    #
+    #   * +Derelict::VirtualMachine::NotFound+ if the connection
+    #     doesn't know about a virtual machine with the requested
+    #     name
+    def validate!
+      logger.debug "Starting validation for #{description}"
+      raise NotFound.new name, connection unless exists?
+      logger.info "Successfully validated #{description}"
+      self
+    end
+
+    # Determines whether this Vagrant virtual machine exists
+    #
+    # Returns +true+ if the connection reports a virtual machine with
+    # the requested name, otherwise returns +false+.
+    def exists?
+      status.exists? name
+    end
+    memoize :exists?
+
+    # Gets the current state of this Vagrant virtual machine
+    #
+    # The state is returned as a symbol, e.g. :running.
+    def state
+      status.state name
+    end
+    memoize :state
+
+    # Determines whether this virtual machine is currently running
+    def running?
+      (state == :running)
+    end
+    memoize :running?
+
+    # Add methods for each command
+    #
+    # A method is defined for each of the symbols in COMMANDS. The
+    # method name will be the symbol with an added bang (!). For
+    # example, #up!, #halt!, etc.
+    #
+    # Each method takes an options hash as an argument. For example:
+    #
+    #   vm.up! :log => true
+    #
+    # This example will run the "up" command with logging enabled. The
+    # option keys can optionally include any of the following symbols:
+    #
+    #     * log: Should the log output be printed? (defaults to false)
+    COMMANDS.each do |command|
+      define_method :"#{command}!" do |options|
+        # Log message if there's one for this command
+        message = log_message_for command
+        logger.info message unless message.nil?
+
+        # Set defaults for the options hash
+        options = {:log => false}.merge options
+
+        # Execute the command, optionally logging output
+        log_block = options[:log] ? shell_log_block : nil
+        connection.execute! command, name, *arguments_for(command), &log_block
+      end
+    end
+
+    # Retrieves the (parsed) status from the connection
+    def status
+      logger.info "Retrieving Vagrant status for #{description}"
+      output = connection.execute!(:status).stdout
+      Derelict::Parser::Status.new(output)
+    end
+    memoize :status
+
+    # Provides a description of this Connection
+    #
+    # Mainly used for log messages.
+    def description
+      "Derelict::VirtualMachine '#{name}' from #{connection.description}"
+    end
+
+    private
+      # A block that can be passed to #execute to log the output
+      def shell_log_block
+        Proc.new do |line|
+          logger(:type => :external).info line
+        end
+      end
+      memoize :shell_log_block
+
+      # Retrieves the arguments for a particular action
+      #
+      #   * action: The symbol representing the action (one of :up,
+      #             :halt, :destroy, :reload, :suspend, :resume)
+      def arguments_for(action)
+        case action
+          when :destroy then ['--force']
+          else []
+        end
+      end
+
+      # Retrieves the correct log message for a particular action
+      #
+      #   * action: The symbol representing the action (one of :up,
+      #             :halt, :destroy, :reload, :suspend, :resume)
+      def log_message_for(action)
+        case action
+          when :up      then "Bringing up #{description}"
+          when :halt    then "Halting #{description}"
+          when :destroy then "Destroying #{description}"
+          when :reload  then "Reloading #{description}"
+          when :suspend then "Suspending #{description}"
+          when :resume  then "Resuming #{description}"
+          else nil
+        end
+      end
+  end
+end

data/lib/derelict.rb

@@ -1,22 +1,69 @@
-require "rubygems"
 require "derelict/version"
+require "log4r"
+require "memoist"
+require "shell/executer"
 
-# Controls a Vagrant instance
-class Derelict
-  autoload :Instance, "derelict/instance"
-  autoload :Exception, "derelict/exception"
+Log4r::Logger["root"] # creates the level constants (INFO, etc).
 
-  # Connects to an instance of Vagrant installed via Installer package
+# Main module/entry point for Derelict
+module Derelict
+  autoload :Connection,     "derelict/connection"
+  autoload :Exception,      "derelict/exception"
+  autoload :Instance,       "derelict/instance"
+  autoload :Parser,         "derelict/parser"
+  autoload :Utils,          "derelict/utils"
+  autoload :VirtualMachine, "derelict/virtual_machine"
+
+  # Make functions accessible by Derelict.foo and private when included
+  module_function
+
+  # Include "logger" method to get a logger for this class
+  extend Utils::Logger
+
+  # Creates a new Derelict instance for a Vagrant installation
   #
-  #   path: The path to the location of the Vagrant instance
-  def self.connect(path)
-    Instance.new path
+  #   * path: The path to the Vagrant installation (optional, defaults
+  #           to Instance::DEFAULT_PATH)
+  def instance(path = Instance::DEFAULT_PATH)
+    logger.info "Creating and validating new instance for '#{path}'"
+    Instance.new(path).validate!
   end
 
-  # Determines if an instance is currently active
-  def self.active?
-    Module.const_get("::Vagrant").is_a?(Class)
-  rescue NameError
-    false
+  # Enables (or disables) Derelict's debug mode
+  #
+  # When in debug mode, Derelict will log to stderr. The debug level
+  # can be controlled as well (which affects the verbosity of the
+  # logging).
+  #
+  # Valid (symbol) keys for the options hash include:
+  #
+  #   * enabled: Whether debug mode should be enabled (defaults to true)
+  #   * level:   Allows setting a custom log level (defaults to INFO)
+  def debug!(options = {})
+    options = debug_options_defaults.merge options
+    logger.level = options[:enabled] ? options[:level] : Log4r::OFF
+
+    if options[:enabled]
+      logger.add stderr unless logger.outputters.include? stderr
+      logger.info "enabling debug mode"
+    else
+      logger.info "disabling debug mode"
+      logger.remove "stderr"
+    end
+
+    self
   end
+
+  private
+    # Retrieves the default values for the options hash for #debug!
+    def self.debug_options_defaults
+      {
+        :enabled => true,
+        :level => Log4r::INFO,
+      }
+    end
+
+    def self.stderr
+      Log4r::Outputter.stderr
+    end
 end

data/spec/coverage_helper.rb

@@ -0,0 +1,16 @@
+if ENV['TRAVIS']
+  # Running on Travis CI: initialize Coveralls to submit coverage data
+  require "coveralls"
+  Coveralls.wear!
+else
+  # Not running on Travis CI: Run SimpleCov locally for coverage data
+  # Since SimpleCov requires Ruby 1.9+, only include it if we're
+  # running on a compatible version.
+  version_major = RbConfig::CONFIG["MAJOR"].to_i
+  version_minor = RbConfig::CONFIG["MINOR"].to_i
+  if version_major >= 1 and version_minor >= 9
+    require "simplecov"
+    SimpleCov.start
+  end
+end
+

data/spec/derelict/connection/invalid_spec.rb

@@ -0,0 +1,16 @@
+require "spec_helper"
+
+describe Derelict::Connection::Invalid do
+  it "is autoloaded" do
+    should be_a Derelict::Connection::Invalid
+  end
+
+  context "when using default reason" do
+    its(:message) { should eq "Invalid Derelict connection" }
+  end
+
+  context "when using custom reason" do
+    subject { Derelict::Connection::Invalid.new "reason" }
+    its(:message) { should eq "Invalid Derelict connection: reason" }
+  end
+end

data/spec/derelict/connection/not_found_spec.rb

@@ -0,0 +1,13 @@
+require "spec_helper"
+
+describe Derelict::Connection::NotFound do
+  subject { Derelict::Connection::NotFound.new "/foo/bar" }
+
+  it "is autoloaded" do
+    should be_a Derelict::Connection::NotFound
+  end
+
+  its(:message) {
+    should eq "Invalid Derelict connection: Vagrantfile not found for /foo/bar"
+  }
+end