tnargav 1.3.5 → 1.3.6

data/lib/vagrant/plugin/v2/plugin.rb

@@ -0,0 +1,226 @@
+require "set"
+
+require "log4r"
+
+require "vagrant/plugin/v2/components"
+
+module Vagrant
+  module Plugin
+    module V2
+      # This is the superclass for all V2 plugins.
+      class Plugin
+        # Special marker that can be used for action hooks that matches
+        # all action sequences.
+        ALL_ACTIONS = :__all_actions__
+
+        # The logger for this class.
+        LOGGER = Log4r::Logger.new("vagrant::plugin::v2::plugin")
+
+        # Set the root class up to be ourself, so that we can reference this
+        # from within methods which are probably in subclasses.
+        ROOT_CLASS = self
+
+        # This returns the manager for all V2 plugins.
+        #
+        # @return [V2::Manager]
+        def self.manager
+          @manager ||= Manager.new
+        end
+
+        # Returns the {Components} for this plugin.
+        #
+        # @return [Components]
+        def self.components
+          @components ||= Components.new
+        end
+
+        # Set the name of the plugin. The moment that this is called, the
+        # plugin will be registered and available. Before this is called, a
+        # plugin does not exist. The name must be unique among all installed
+        # plugins.
+        #
+        # @param [String] name Name of the plugin.
+        # @return [String] The name of the plugin.
+        def self.name(name=UNSET_VALUE)
+          # Get or set the value first, so we have a name for logging when
+          # we register.
+          result = get_or_set(:name, name)
+
+          # The plugin should be registered if we're setting a real name on it
+          Plugin.manager.register(self) if name != UNSET_VALUE
+
+          # Return the result
+          result
+        end
+
+        # Sets a human-friendly descrition of the plugin.
+        #
+        # @param [String] value Description of the plugin.
+        # @return [String] Description of the plugin.
+        def self.description(value=UNSET_VALUE)
+          get_or_set(:description, value)
+        end
+
+        # Registers a callback to be called when a specific action sequence
+        # is run. This allows plugin authors to hook into things like VM
+        # bootup, VM provisioning, etc.
+        #
+        # @param [String] name Name of the action.
+        # @param [Symbol] hook_name The location to hook. If this isn't
+        #   set, every middleware action is hooked.
+        # @return [Array] List of the hooks for the given action.
+        def self.action_hook(name, hook_name=nil, &block)
+          # The name is currently not used but we want it for the future.
+
+          hook_name ||= ALL_ACTIONS
+          components.action_hooks[hook_name] << block
+        end
+
+        # Defines additional command line commands available by key. The key
+        # becomes the subcommand, so if you register a command "foo" then
+        # "vagrant foo" becomes available.
+        #
+        # @param [String] name Subcommand key.
+        def self.command(name=UNSET_VALUE, &block)
+          data[:command] ||= Registry.new
+
+          if name != UNSET_VALUE
+            # Validate the name of the command
+            if name.to_s !~ /^[-a-z0-9]+$/i
+              raise InvalidCommandName, "Commands can only contain letters, numbers, and hyphens"
+            end
+
+            # Register a new command class only if a name was given.
+            data[:command].register(name.to_sym, &block)
+          end
+
+          # Return the registry
+          data[:command]
+        end
+
+        # Defines additional communicators to be available. Communicators
+        # should be returned by a block passed to this method. This is done
+        # to ensure that the class is lazy loaded, so if your class inherits
+        # from or uses any Vagrant internals specific to Vagrant 1.0, then
+        # the plugin can still be defined without breaking anything in future
+        # versions of Vagrant.
+        #
+        # @param [String] name Communicator name.
+        def self.communicator(name=UNSET_VALUE, &block)
+          data[:communicator] ||= Registry.new
+
+          # Register a new communicator class only if a name was given.
+          data[:communicator].register(name.to_sym, &block) if name != UNSET_VALUE
+
+          # Return the registry
+          data[:communicator]
+        end
+
+        # Defines additional configuration keys to be available in the
+        # Vagrantfile. The configuration class should be returned by a
+        # block passed to this method. This is done to ensure that the class
+        # is lazy loaded, so if your class inherits from any classes that
+        # are specific to Vagrant 1.0, then the plugin can still be defined
+        # without breaking anything in future versions of Vagrant.
+        #
+        # @param [String] name Configuration key.
+        def self.config(name, scope=nil, &block)
+          scope ||= :top
+          components.configs[scope].register(name.to_sym, &block)
+          nil
+        end
+
+        # Defines an additionally available guest implementation with
+        # the given key.
+        #
+        # @param [String] name Name of the guest.
+        # @param [String] parent Name of the parent guest (if any)
+        def self.guest(name=UNSET_VALUE, parent=nil, &block)
+          components.guests.register(name.to_sym) do
+            parent = parent.to_sym if parent
+
+            [block.call, parent]
+          end
+          nil
+        end
+
+        # Defines a capability for the given guest. The block should return
+        # a class/module that has a method with the capability name, ready
+        # to be executed. This means that if it is an instance method,
+        # the block should return an instance of the class.
+        #
+        # @param [String] guest The name of the guest
+        # @param [String] cap The name of the capability
+        def self.guest_capability(guest, cap, &block)
+          components.guest_capabilities[guest.to_sym].register(cap.to_sym, &block)
+          nil
+        end
+
+        # Defines an additionally available host implementation with
+        # the given key.
+        #
+        # @param [String] name Name of the host.
+        def self.host(name=UNSET_VALUE, &block)
+          data[:hosts] ||= Registry.new
+
+          # Register a new host class only if a name was given
+          data[:hosts].register(name.to_sym, &block) if name != UNSET_VALUE
+
+          # Return the registry
+          data[:hosts]
+        end
+
+        # Registers additional providers to be available.
+        #
+        # @param [Symbol] name Name of the provider.
+        def self.provider(name=UNSET_VALUE, options=nil, &block)
+          components.providers.register(name.to_sym) do
+            [block.call, options || {}]
+          end
+
+          nil
+        end
+
+        # Registers additional provisioners to be available.
+        #
+        # @param [String] name Name of the provisioner.
+        def self.provisioner(name=UNSET_VALUE, &block)
+          data[:provisioners] ||= Registry.new
+
+          # Register a new provisioner class only if a name was given
+          data[:provisioners].register(name.to_sym, &block) if name != UNSET_VALUE
+
+          # Return the registry
+          data[:provisioners]
+        end
+
+        # Returns the internal data associated with this plugin. This
+        # should NOT be called by the general public.
+        #
+        # @return [Hash]
+        def self.data
+          @data ||= {}
+        end
+
+        protected
+
+        # Sentinel value denoting that a value has not been set.
+        UNSET_VALUE = Object.new
+
+        # Helper method that will set a value if a value is given, or otherwise
+        # return the already set value.
+        #
+        # @param [Symbol] key Key for the data
+        # @param [Object] value Value to store.
+        # @return [Object] Stored value.
+        def self.get_or_set(key, value=UNSET_VALUE)
+          # If no value is to be set, then return the value we have already set
+          return data[key] if value.eql?(UNSET_VALUE)
+
+          # Otherwise set the value
+          data[key] = value
+        end
+      end
+    end
+  end
+end

data/lib/vagrant/plugin/v2/provider.rb

@@ -0,0 +1,69 @@
+module Vagrant
+  module Plugin
+    module V2
+      # This is the base class for a provider for the V2 API. A provider
+      # is responsible for creating compute resources to match the needs
+      # of a Vagrant-configured system.
+      class Provider
+        # Initialize the provider to represent the given machine.
+        #
+        # @param [Vagrant::Machine] machine The machine that this provider
+        #   is responsible for.
+        def initialize(machine)
+        end
+
+        # This should return an action callable for the given name.
+        #
+        # @param [Symbol] name Name of the action.
+        # @return [Object] A callable action sequence object, whether it
+        #   is a proc, object, etc.
+        def action(name)
+          nil
+        end
+
+        # This method is called if the underying machine ID changes. Providers
+        # can use this method to load in new data for the actual backing
+        # machine or to realize that the machine is now gone (the ID can
+        # become `nil`). No parameters are given, since the underlying machine
+        # is simply the machine instance given to this object. And no
+        # return value is necessary.
+        def machine_id_changed
+        end
+
+        # This should return a hash of information that explains how to
+        # SSH into the machine. If the machine is not at a point where
+        # SSH is even possible, then `nil` should be returned.
+        #
+        # The general structure of this returned hash should be the
+        # following:
+        #
+        #     {
+        #       :host => "1.2.3.4",
+        #       :port => "22",
+        #       :username => "mitchellh",
+        #       :private_key_path => "/path/to/my/key"
+        #     }
+        #
+        # **Note:** Vagrant only supports private key based authentication,
+        # mainly for the reason that there is no easy way to exec into an
+        # `ssh` prompt with a password, whereas we can pass a private key
+        # via commandline.
+        #
+        # @return [Hash] SSH information. For the structure of this hash
+        #   read the accompanying documentation for this method.
+        def ssh_info
+          nil
+        end
+
+        # This should return the state of the machine within this provider.
+        # The state must be an instance of {MachineState}. Please read the
+        # documentation of that class for more information.
+        #
+        # @return [MachineState]
+        def state
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/vagrant/plugin/v2/provisioner.rb

@@ -0,0 +1,53 @@
+module Vagrant
+  module Plugin
+    module V2
+      # This is the base class for a provisioner for the V2 API. A provisioner
+      # is primarily responsible for installing software on a Vagrant guest.
+      class Provisioner
+        attr_reader :machine
+        attr_reader :config
+
+        # Initializes the provisioner with the machine that it will be
+        # provisioning along with the provisioner configuration (if there
+        # is any).
+        #
+        # The provisioner should _not_ do anything at this point except
+        # initialize internal state.
+        #
+        # @param [Machine] machine The machine that this will be provisioning.
+        # @param [Object] config Provisioner configuration, if one was set.
+        def initialize(machine, config)
+          @machine = machine
+          @config  = config
+        end
+
+        # Called with the root configuration of the machine so the provisioner
+        # can add some configuration on top of the machine.
+        #
+        # During this step, and this step only, the provisioner should modify
+        # the root machine configuration to add any additional features it
+        # may need. Examples include sharing folders, networking, and so on.
+        # This step is guaranteed to be called before any of those steps are
+        # done so the provisioner may do that.
+        #
+        # No return value is expected.
+        def configure(root_config)
+        end
+
+        # This is the method called when the actual provisioning should be
+        # done. The communicator is guaranteed to be ready at this point,
+        # and any shared folders or networks are already setup.
+        #
+        # No return value is expected.
+        def provision
+        end
+
+        # This is the method called when destroying a machine that allows
+        # for any state related to the machine created by the provisioner
+        # to be cleaned up.
+        def cleanup
+        end
+      end
+    end
+  end
+end

data/lib/vagrant/registry.rb

@@ -0,0 +1,78 @@
+module Vagrant
+  # Register components in a single location that can be queried.
+  #
+  # This allows certain components (such as guest systems, configuration
+  # pieces, etc.) to be registered and queried, lazily.
+  class Registry
+    def initialize
+      @items = {}
+      @results_cache = {}
+    end
+
+    # Register a key with a lazy-loaded value.
+    #
+    # If a key with the given name already exists, it is overwritten.
+    def register(key, &block)
+      raise ArgumentError, "block required" if !block_given?
+      @items[key] = block
+    end
+
+    # Get a value by the given key.
+    #
+    # This will evaluate the block given to `register` and return the
+    # resulting value.
+    def get(key)
+      return nil if !@items.has_key?(key)
+      return @results_cache[key] if @results_cache.has_key?(key)
+      @results_cache[key] = @items[key].call
+    end
+    alias :[] :get
+
+    # Checks if the given key is registered with the registry.
+    #
+    # @return [Boolean]
+    def has_key?(key)
+      @items.has_key?(key)
+    end
+
+    # Iterate over the keyspace.
+    def each(&block)
+      @items.each do |key, _|
+        yield key, get(key)
+      end
+    end
+
+    # Merge one registry with another and return a completely new
+    # registry. Note that the result cache is completely busted, so
+    # any gets on the new registry will result in a cache miss.
+    def merge(other)
+      self.class.new.tap do |result|
+        result.merge!(self)
+        result.merge!(other)
+      end
+    end
+
+    # Like #{merge} but merges into self.
+    def merge!(other)
+      @items.merge!(other.__internal_state[:items])
+      self
+    end
+
+    # Converts this registry to a hash
+    def to_hash
+      result = {}
+      self.each do |key, value|
+        result[key] = value
+      end
+
+      result
+    end
+
+    def __internal_state
+      {
+        :items => @items,
+        :results_cache => @results_cache
+      }
+    end
+  end
+end

data/lib/vagrant/ui.rb

@@ -0,0 +1,215 @@
+require "thread"
+
+require "log4r"
+
+require "vagrant/util/platform"
+require "vagrant/util/safe_puts"
+
+module Vagrant
+  module UI
+    # Vagrant UIs handle communication with the outside world (typically
+    # through a shell). They must respond to the following methods:
+    #
+    # * `info`
+    # * `warn`
+    # * `error`
+    # * `success`
+    class Interface
+      def initialize
+        @logger   = Log4r::Logger.new("vagrant::ui::interface")
+      end
+
+      [:ask, :warn, :error, :info, :success].each do |method|
+        define_method(method) do |message, *opts|
+          # Log normal console messages
+          @logger.info { "#{method}: #{message}" }
+        end
+      end
+
+      [:clear_line, :report_progress].each do |method|
+        # By default do nothing, these aren't logged
+        define_method(method) { |*args| }
+      end
+
+      # Returns a new UI class that is scoped to the given resource name.
+      # Subclasses can then use this scope name to do whatever they please.
+      #
+      # @param [String] scope_name
+      # @return [Interface]
+      def scope(scope_name)
+        self
+      end
+    end
+
+    # This is a UI implementation that does nothing.
+    class Silent < Interface
+      def ask(*args)
+        super
+
+        # Silent can't do this, obviously.
+        raise Errors::UIExpectsTTY
+      end
+    end
+
+    # This is a UI implementation that outputs the text as is. It
+    # doesn't add any color.
+    class Basic < Interface
+      include Util::SafePuts
+
+      def initialize
+        super
+
+        @lock = Mutex.new
+      end
+
+      # Use some light meta-programming to create the various methods to
+      # output text to the UI. These all delegate the real functionality
+      # to `say`.
+      [:info, :warn, :error, :success].each do |method|
+        class_eval <<-CODE
+          def #{method}(message, *args)
+            super(message)
+            say(#{method.inspect}, message, *args)
+          end
+        CODE
+      end
+
+      def ask(message, opts=nil)
+        super(message)
+
+        # We can't ask questions when the output isn't a TTY.
+        raise Errors::UIExpectsTTY if !$stdin.tty? && !Vagrant::Util::Platform.cygwin?
+
+        # Setup the options so that the new line is suppressed
+        opts ||= {}
+        opts[:new_line] = false if !opts.has_key?(:new_line)
+        opts[:prefix]   = false if !opts.has_key?(:prefix)
+
+        # Output the data
+        say(:info, message, opts)
+
+        # Get the results and chomp off the newline. We do a logical OR
+        # here because `gets` can return a nil, for example in the case
+        # that ctrl-D is pressed on the input.
+        input = $stdin.gets || ""
+        input.chomp
+      end
+
+      # This is used to output progress reports to the UI.
+      # Send this method progress/total and it will output it
+      # to the UI. Send `clear_line` to clear the line to show
+      # a continuous progress meter.
+      def report_progress(progress, total, show_parts=true)
+        if total && total > 0
+          percent = (progress.to_f / total.to_f) * 100
+          line    = "Progress: #{percent.to_i}%"
+          line   << " (#{progress} / #{total})" if show_parts
+        else
+          line    = "Progress: #{progress}"
+        end
+
+        info(line, :new_line => false)
+      end
+
+      def clear_line
+        reset = "\r"
+        reset += "\e[0K" if Util::Platform.windows? && !Util::Platform.cygwin?
+
+        info(reset, :new_line => false)
+      end
+
+      # This method handles actually outputting a message of a given type
+      # to the console.
+      def say(type, message, opts=nil)
+        defaults = { :new_line => true, :prefix => true }
+        opts     = defaults.merge(opts || {})
+
+        # Determine whether we're expecting to output our
+        # own new line or not.
+        printer = opts[:new_line] ? :puts : :print
+
+        # Determine the proper IO channel to send this message
+        # to based on the type of the message
+        channel = type == :error || opts[:channel] == :error ? $stderr : $stdout
+
+        # Output! We wrap this in a lock so that it safely outputs only
+        # one line at a time.
+        @lock.synchronize do
+          safe_puts(format_message(type, message, opts),
+                    :io => channel, :printer => printer)
+        end
+      end
+
+      def scope(scope_name)
+        BasicScope.new(self, scope_name)
+      end
+
+      # This is called by `say` to format the message for output.
+      def format_message(type, message, opts=nil)
+        opts ||= {}
+        message = "[#{opts[:scope]}] #{message}" if opts[:scope] && opts[:prefix]
+        message
+      end
+    end
+
+    # This implements a scope for the {Basic} UI.
+    class BasicScope < Interface
+      def initialize(ui, scope)
+        super()
+
+        @ui    = ui
+        @scope = scope
+      end
+
+      [:ask, :warn, :error, :info, :success].each do |method|
+        define_method(method) do |message, opts=nil|
+          opts ||= {}
+          opts[:scope] = @scope
+          @ui.send(method, message, opts)
+        end
+      end
+
+      [:clear_line, :report_progress].each do |method|
+        # By default do nothing, these aren't logged
+        define_method(method) { |*args| @ui.send(method, *args) }
+      end
+    end
+
+    # This is a UI implementation that outputs color for various types
+    # of messages. This should only be used with a TTY that supports color,
+    # but is up to the user of the class to verify this is the case.
+    class Colored < Basic
+      # Terminal colors
+      COLORS = {
+        :clear  => "\e[0m",
+        :red    => "\e[31m",
+        :green  => "\e[32m",
+        :yellow => "\e[33m"
+      }
+
+      # Mapping between type of message and the color to output
+      COLOR_MAP = {
+        :warn    => COLORS[:yellow],
+        :error   => COLORS[:red],
+        :success => COLORS[:green]
+      }
+
+      # This is called by `say` to format the message for output.
+      def format_message(type, message, opts=nil)
+        # Get the format of the message before adding color.
+        message = super
+
+        # Colorize the message if there is a color for this type of message,
+        # either specified by the options or via the default color map.
+        if opts.has_key?(:color)
+          color   = COLORS[opts[:color]]
+          message = "#{color}#{message}#{COLORS[:clear]}"
+        else
+          message = "#{COLOR_MAP[type]}#{message}#{COLORS[:clear]}" if COLOR_MAP[type]
+        end
+
+        message
+      end
+    end
+  end
+end