derelict_m 0.6.2a

data/lib/derelict/plugin.rb

@@ -0,0 +1,29 @@
+module Derelict
+  # Represents an individual Vagrant plugin at a particular version
+  class Plugin
+    autoload :Manager,  "derelict/plugin/manager"
+    autoload :NotFound, "derelict/plugin/not_found"
+
+    attr_reader :name, :version
+
+    # Initializes a plugin with a particular name and version
+    #
+    #   * name:    The name of the plugin represented by this object
+    #   * version: The version of the plugin represented by this object
+    def initialize(name, version)
+      @name = name
+      @version = version
+    end
+
+    # Ensure equivalent Plugins are equal to this one
+    def ==(other)
+      other.name == name and other.version == version
+    end
+    alias_method :eql?, :==
+
+    # Make equivalent Plugins hash to the same value
+    def hash
+      name.hash ^ version.hash
+    end
+  end
+end

data/lib/derelict/plugin/manager.rb

@@ -0,0 +1,107 @@
+module Derelict
+  class Plugin
+    # A class that handles managing plugins for a Vagrant instance
+    class Manager
+      # Include "memoize" class method to memoize methods
+      extend Memoist
+
+      # Include "logger" method to get a logger for this class
+      include Utils::Logger
+
+      attr_reader :instance
+
+      # Initializes a Manager for use with a particular instance
+      #
+      #   * instance: The Derelict::Instance which will have its
+      #               plugins managed by this Manager
+      def initialize(instance)
+        @instance = instance
+        logger.debug "Successfully initialized #{description}"
+      end
+
+      # Retrieves the Set of currently installed plugins
+      def list
+        logger.info "Retrieving Vagrant plugin list for #{description}"
+        output = instance.execute!(:plugin, "list").stdout
+        Derelict::Parser::PluginList.new(output).plugins
+      end
+      memoize :list
+
+      # Determines whether a particular plugin is installed
+      #
+      #   * plugin_name: Name of the plugin to look for (as a string)
+      def installed?(plugin_name, version = nil)
+        fetch(plugin_name).version == version or version.nil?
+      rescue Plugin::NotFound
+        false
+      end
+
+      # Installs a plugin (optionally a particular version)
+      #
+      # If no version is specified, the latest stable version is used
+      # by Vagrant.
+      #
+      #   * plugin_name: Name of the plugin to install (as a string)
+      #   * options:     Hash of options, valid keys:
+      #      * version:  Particular version to install (optional,
+      #                  latest version will be installed if omitted)
+      #      * log:      Whether to log the output (optional, defaults
+      #                  to false)
+      def install(plugin_name, options = {})
+        options = {:log => false, :version => nil}.merge(options)
+        logger.info "Installing plugin '#{plugin_name}' using #{description}"
+
+        version = options[:version]
+        command = [:plugin, "install", plugin_name]
+        command.concat ["--plugin-version", version] unless version.nil?
+
+        log_block = options[:log] ? shell_log_block : nil
+        instance.execute!(*command, &log_block).tap do
+          flush_cache # flush memoized method return values
+        end
+      end
+
+      # Uninstalls a particular Vagrant plugin
+      #
+      #   * plugin_name: Name of the plugin to uninstall (as a string)
+      def uninstall(plugin_name, options = {})
+        options = {:log => false}.merge(options)
+        logger.info "Uninstalling plugin '#{plugin_name}' using #{description}"
+
+        log_block = options[:log] ? shell_log_block : nil
+        instance.execute!(:plugin, "uninstall", plugin_name, &log_block).tap do
+          flush_cache # flush memoized method return values
+        end
+      end
+
+      # Updates a particular Vagrant plugin
+      #
+      #   * plugin_name: Name of the plugin to update (as a string)
+      def update(plugin_name, options = {})
+        options = {:log => false}.merge(options)
+        logger.info "Updating plugin '#{plugin_name}' using #{description}"
+
+        log_block = options[:log] ? shell_log_block : nil
+        instance.execute!(:plugin, "update", plugin_name, &log_block).tap do
+          flush_cache # flush memoized method return values
+        end
+      end
+
+      # Retrieves a plugin with a particular name
+      #
+      #   * plugin_name: Name of the plugin to look for (as a string)
+      def fetch(plugin_name)
+        list.find {|plugin| plugin.name == plugin_name}.tap do |plugin|
+          raise Plugin::NotFound.new plugin_name if plugin.nil?
+        end
+      end
+
+      # Provides a description of this Connection
+      #
+      # Mainly used for log messages.
+      def description
+        "Derelict::Plugin::Manager for #{instance.description}"
+      end
+    end
+  end
+end

data/lib/derelict/plugin/not_found.rb

@@ -0,0 +1,14 @@
+module Derelict
+  class Plugin
+    # A plugin that isn't currently installed has been retrieved
+    class NotFound < Derelict::Exception
+      # Initializes a new instance of this exception, for a plugin name
+      #
+      #   * plugin_name: The name of the plugin that this exception
+      #                  relates to
+      def initialize(plugin_name)
+        super "Plugin '#{plugin_name}' is not currently installed"
+      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/utils/logger.rb

@@ -0,0 +1,59 @@
+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
+        # A block that can be passed to #execute to log the output
+        def shell_log_block
+          Proc.new do |stdout, stderr|
+            # Only stdout or stderr is populated, the other will be nil
+            logger(:type => :external).info(stdout || stderr)
+          end
+        end
+
+        # 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/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/version.rb

@@ -0,0 +1,3 @@
+module Derelict
+  VERSION = "0.6.2a"
+end

data/lib/derelict/virtual_machine.rb

@@ -0,0 +1,190 @@
+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 |*opts|
+        # Ideally this block would have one argument with a default
+        # value of an empty Hash. Unfortunately, setting a default
+        # value for the arguments to a block is only supported in Ruby
+        # 1.9+. The splatted arguments thing is a way to allow zero or
+        # one argument, but it actually allows any number of arguments.
+        # So we need to emulate the error Ruby would throw if you give
+        # the wrong number of arguments.
+        if opts.length > 1
+          message = "wrong number of arguments (#{opts.length} for 0-1)"
+          raise ArgumentError.new message
+        end
+
+        # Set defaults for the opts hash
+        opts = {:color => false, :log => false}.merge(opts.first || {})
+
+        # Log message if there's one for this command
+        log_message_for(command).tap {|m| logger.info m unless m.nil? }
+
+        # Execute the command!
+        execute! command, opts
+      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
+      # Executes a command on the connection for this VM
+      #
+      #   * command: The command to execute (as a symbol)
+      #   * options: A Hash of options, with the following optional keys:
+      #       * log:      Logs the output of the command if true
+      #                   (defaults to false)
+      #       * log_mode: Controls how commands are logged (one of
+      #                   either :chars or :lines, defaults to :lines)
+      #       * color:    Uses color in the log output (defaults to
+      #                   false, only relevant if log is true)
+      #       * provider: The Vagrant provider to use, one of
+      #                   "virtualbox" or "vmware_fusion" (defaults to
+      #                   "virtualbox")
+      def execute!(command, options)
+        # Build up the arguments to pass to connection.execute!
+        arguments = [command, name, *arguments_for(command)]
+        arguments << "--color" if options[:color]
+        if options[:provider]
+          arguments << "--provider"
+          arguments << options[:provider]
+        end
+
+        if options[:log_mode]
+          arguments << {:mode => options[:log_mode]}
+        end
+
+        # Set up the block to use when executing -- if logging is
+        # enabled, use a block that logs the output; otherwise no block.
+        block = options[:log] ? shell_log_block : nil
+
+        # Execute the command
+        connection.execute! *arguments, &block
+      end
+
+      # 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