vagrant 0.5.4 → 0.6.0

data/lib/vagrant/command/base.rb

@@ -0,0 +1,106 @@
+require 'thor/group'
+require 'thor/actions'
+
+module Vagrant
+  module Command
+    # A {Base} is the superclass for all commands which are single
+    # commands, e.g. `vagrant init`, `vagrant up`. Not commands like
+    # `vagrant box add`. For commands which have more subcommands, use
+    # a {GroupBase}.
+    #
+    # A {Base} is a subclass of `Thor::Group`, so view the documentation
+    # there on how to add arguments, descriptions etc. The important note
+    # about this is that when invoked, _all public methods_ will be called
+    # in the order they are defined. If you don't want a method called when
+    # the command is invoked, it must be made `protected` or `private`.
+    #
+    # The best way to get examples of how to create your own command is to
+    # view the various Vagrant commands, which are relatively simple, and
+    # can be found in the Vagrant source tree at `lib/vagrant/command/`.
+    #
+    # # Defining a New Command
+    #
+    # To define a new single command, create a new class which inherits
+    # from this class, then call {register} to register the command. That's
+    # it! When the command is invoked, _all public methods_ will be called.
+    # Below is an example `SayHello` class:
+    #
+    #     class SayHello < Vagrant::Command::Base
+    #       register "hello", "Says hello"
+    #
+    #       def hello
+    #         env.ui.info "Hello"
+    #       end
+    #     end
+    #
+    # In this case, the above class is invokable via `vagrant hello`. To give
+    # this a try, just copy and paste the above into a Vagrantfile somewhere.
+    # The command will be available for that project!
+    #
+    # Also note that the above example uses `env.ui` to output. It is recommended
+    # you use this instead of raw "puts" since it is configurable and provides
+    # additional functionality, such as colors and asking for user input. See
+    # the {UI} class for more information.
+    #
+    # ## Defining Command-line Options
+    #
+    # Most command line actions won't be as simple as `vagrant hello`, and will
+    # probably require parameters or switches. Luckily, Thor makes adding these
+    # easy:
+    #
+    #     class SayHello < Vagrant::Command::Base
+    #       register "hello", "Says hello"
+    #       argument :name, :type => :string
+    #
+    #       def hello
+    #         env.ui.info "Hello, #{name}"
+    #       end
+    #     end
+    #
+    # Then, the above can be invoked with `vagrant hello Mitchell` which would
+    # output "Hello, Mitchell." If instead you're looking for switches, such as
+    # "--name Mitchell", then take a look at `class_option`, an example of which
+    # can be found in the {PackageCommand}.
+    class Base < Thor::Group
+      include Thor::Actions
+      include Helpers
+
+      attr_reader :env
+
+      # Register the command with the main Vagrant CLI under the
+      # given name. The name will be used for accessing it from the CLI,
+      # so if you name it "lamp", then the command to invoke this
+      # will be `vagrant lamp`.
+      #
+      # The description is used when the help is listed, and is meant to be
+      # a brief (one sentence) description of what the command does.
+      #
+      # Some additional options may be passed in as the last parameter:
+      #
+      # * `:alias` - If given as an array or string, these will be aliases
+      #  for the same command. For example, `vagrant version` is also
+      #  `vagrant --version` and `vagrant -v`
+      #
+      # @param [String] usage
+      # @param [String] description
+      # @param [Hash] opts
+      def self.register(usage, description, opts=nil)
+        desc description
+        CLI.register(self, extract_name_from_usage(usage), usage, desc, opts)
+      end
+
+      def initialize(*args)
+        super
+        initialize_environment(*args)
+      end
+
+      protected
+
+      # Extracts the name of the command from a usage string. Example:
+      # `init [box_name] [box_url]` becomes just `init`.
+      def self.extract_name_from_usage(usage)
+        /^([-_a-zA-Z0-9]+)(\s+(.+?))?$/.match(usage).to_a[1]
+      end
+    end
+  end
+end

data/lib/vagrant/command/box.rb

@@ -0,0 +1,33 @@
+module Vagrant
+  module Command
+    class BoxCommand < GroupBase
+      register "box", "Commands to manage system boxes"
+
+      desc "add NAME URI", "Add a box to the system"
+      def add(name, uri)
+        Box.add(env, name, uri)
+      end
+
+      desc "remove NAME", "Remove a box from the system"
+      def remove(name)
+        b = env.boxes.find(name)
+        raise BoxNotFound.new(:name => name) if !b
+        b.destroy
+      end
+
+      desc "repackage NAME", "Repackage an installed box into a `.box` file."
+      def repackage(name)
+        b = env.boxes.find(name)
+        raise BoxNotFound.new(:name => name) if !b
+        b.repackage
+      end
+
+      desc "list", "Lists all installed boxes"
+      def list
+        boxes = env.boxes.sort
+        return env.ui.warn(I18n.t("vagrant.commands.box.no_installed_boxes"), :prefix => false) if boxes.empty?
+        boxes.each { |b| env.ui.info(b.name, :prefix => false) }
+      end
+    end
+  end
+end

data/lib/vagrant/command/destroy.rb

@@ -0,0 +1,17 @@
+module Vagrant
+  module Command
+    class DestroyCommand < NamedBase
+      register "destroy", "Destroy the environment, deleting the created virtual machines"
+
+      def execute
+        target_vms.each do |vm|
+          if vm.created?
+            vm.destroy
+          else
+            vm.env.ui.info I18n.t("vagrant.commands.common.vm_not_created")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vagrant/command/group_base.rb

@@ -0,0 +1,99 @@
+require 'thor'
+require 'thor/actions'
+
+module Vagrant
+  module Command
+    # A {GroupBase} is the superclass which should be used if you're
+    # creating a CLI command which has subcommands such as `vagrant box`,
+    # which has subcommands such as `add`, `remove`, `list`. If you're
+    # creating a simple command which has no subcommands, such as `vagrant up`,
+    # then use {Base} instead.
+    #
+    # Unlike {Base}, where all public methods are executed, in a {GroupBase},
+    # each public method defines a separate task which can be invoked. The best
+    # way to get examples of how to create a {GroupBase} command is to look
+    # at the built-in commands, such as {BoxCommand}.
+    #
+    # # Defining a New Command
+    #
+    # To define a new command with subcommands, create a new class which inherits
+    # from this class, then call {register} to register the command. That's it! When
+    # the command is invoked, the method matching the subcommand is invoked. An
+    # example is shown below:
+    #
+    #     class SayCommand < Vagrant::Command::GroupBase
+    #       register "say", "Say hello or goodbye"
+    #
+    #       desc "hello", "say hello"
+    #       def hello
+    #         env.ui.info "Hello"
+    #       end
+    #
+    #       desc "goodbye", "say goodbye"
+    #       def goodbye
+    #         env.ui.info "Goodbye"
+    #       end
+    #     end
+    #
+    # In this case, the above class is invokable via `vagrant say hello` or
+    # `vagrant say goodbye`. To give it a try yourself, just copy and paste
+    # the above into a Vagrantfile somewhere, and run `vagrant` from within
+    # that directory. You should see the new command!
+    #
+    # Also notice that in the above, each task follows a `desc` call. This
+    # call is used to provide usage and description for each task, and is
+    # required.
+    #
+    # ## Defining Command-line Options
+    #
+    # ### Arguments
+    #
+    # To define arguments to your commands, such as `vagrant say hello mitchell`,
+    # then you simply define them as arguments to the method implementing the
+    # task. An example is shown below (only the method, to keep things brief):
+    #
+    #     def hello(name)
+    #       env.ui.info "Hello, #{name}"
+    #     end
+    #
+    # Then, if `vagrant say hello mitchell` was called, then the output would
+    # be "Hello, mitchell"
+    #
+    # ### Switches or Other Options
+    #
+    # TODO
+    class GroupBase < Thor
+      include Thor::Actions
+      include Helpers
+
+      attr_reader :env
+
+      # Register the command with the main Vagrant CLI under the given
+      # usage. The usage will be used for accessing it from the CLI,
+      # so if you give it a usage of `lamp [subcommand]`, then the command
+      # to invoke this will be `vagrant lamp` (with a subcommand).
+      #
+      # The description is used when a listing of the commands is given
+      # and is meant to be a brief (one sentence) description of what this
+      # command does.
+      #
+      # Some additional options may be passed in as the last parameter:
+      #
+      # * `:alias` - If given as an array or string, these will be aliases
+      #  for the same command. For example, `vagrant version` is also
+      #  `vagrant --version` and `vagrant -v`
+      #
+      # @param [String] usage
+      # @param [String] description
+      # @param [Hash] opts
+      def self.register(usage, description, opts=nil)
+        CLI.register(self, Base.extract_name_from_usage(usage), usage, description, opts)
+      end
+
+      def initialize(*args)
+        super
+        initialize_environment(*args)
+      end
+    end
+  end
+end

data/lib/vagrant/command/halt.rb

@@ -0,0 +1,18 @@
+module Vagrant
+  module Command
+    class HaltCommand < NamedBase
+      class_option :force, :type => :boolean, :default => false, :aliases => "-f"
+      register "halt", "Halt the running VMs in the environment"
+
+      def execute
+        target_vms.each do |vm|
+          if vm.created?
+            vm.halt(options)
+          else
+            vm.env.ui.info I18n.t("vagrant.commands.common.vm_not_created")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vagrant/command/helpers.rb

@@ -0,0 +1,33 @@
+module Vagrant
+  module Command
+    module Helpers
+      # Initializes the environment by pulling the environment out of
+      # the configuration hash and sets up the UI if necessary.
+      def initialize_environment(args, options, config)
+        raise Errors::CLIMissingEnvironment.new if !config[:env]
+        @env = config[:env]
+      end
+
+      # This returns an array of {VM} objects depending on the arguments
+      # given to the command.
+      def target_vms(name=nil)
+        raise Errors::NoEnvironmentError.new if !env.root_path
+
+        name ||= self.name rescue nil
+
+        @target_vms ||= begin
+          if env.multivm?
+            return env.vms.values if !name
+            vm = env.vms[name.to_sym]
+            raise Errors::VMNotFoundError.new(:name => name) if !vm
+          else
+            raise Errors::MultiVMEnvironmentRequired.new if name
+            vm = env.vms.values.first
+          end
+
+          [vm]
+        end
+      end
+    end
+  end
+end

data/lib/vagrant/command/init.rb

@@ -0,0 +1,14 @@
+module Vagrant
+  module Command
+    class InitCommand < Base
+      argument :box_name, :type => :string, :optional => true, :default => "base"
+      argument :box_url, :type => :string, :optional => true
+      source_root File.expand_path("templates/commands/init", Vagrant.source_root)
+      register "init [box_name] [box_url]", "Initializes the current folder for Vagrant usage"
+
+      def execute
+        template "Vagrantfile.erb", "Vagrantfile"
+      end
+    end
+  end
+end

data/lib/vagrant/command/named_base.rb

@@ -0,0 +1,14 @@
+module Vagrant
+  module Command
+    # Same as {Base} except adds the `name` argument for you. This superclass
+    # is useful if you're creating a command which should be able to target
+    # a specific VM in a multi-VM environment. For example, in a multi-VM
+    # environment, `vagrant up` "ups" all defined VMs, but you can specify a
+    # name such as `vagrant up web` to target only a specific VM. That name
+    # argument is from {NamedBase}. Of course, you can always add it manually
+    # yourself, as well.
+    class NamedBase < Base
+      argument :name, :type => :string, :optional => true
+    end
+  end
+end

data/lib/vagrant/command/package.rb

@@ -0,0 +1,41 @@
+module Vagrant
+  module Command
+    class PackageCommand < NamedBase
+      class_option :base, :type => :string, :default => nil
+      class_option :output, :type => :string, :default => nil
+      class_option :include, :type => :array, :default => nil
+      class_option :vagrantfile, :type => :string, :default => nil
+      register "package", "Package a Vagrant environment for distribution"
+
+      def execute
+        return package_base if options[:base]
+        package_target
+      end
+
+      protected
+
+      def package_base
+        vm = VM.find(options[:base], env)
+        raise Errors::BaseVMNotFoundError.new(:name => options[:base]) if !vm.created?
+        package_vm(vm)
+      end
+
+      def package_target
+        raise Errors::MultiVMTargetRequired.new(:command => "package") if target_vms.length > 1
+        vm = target_vms.first
+        raise Errors::VMNotCreatedError.new if !vm.created?
+        package_vm(vm)
+      end
+
+      def package_vm(vm)
+        opts = options.inject({}) do |acc, data|
+          k,v = data
+          acc["package.#{k}"] = v
+          acc
+        end
+
+        vm.package(opts)
+      end
+    end
+  end
+end

data/lib/vagrant/command/provision.rb

@@ -0,0 +1,17 @@
+module Vagrant
+  module Command
+    class ProvisionCommand < NamedBase
+      register "provision", "Rerun the provisioning scripts on a running VM"
+
+      def execute
+        target_vms.each do |vm|
+          if vm.created? && vm.vm.running?
+            vm.provision
+          else
+            vm.env.ui.info I18n.t("vagrant.commands.common.vm_not_created")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vagrant/command/reload.rb

@@ -0,0 +1,17 @@
+module Vagrant
+  module Command
+    class ReloadCommand < NamedBase
+      register "reload", "Reload the environment, halting it then restarting it."
+
+      def execute
+        target_vms.each do |vm|
+          if vm.created?
+            vm.reload
+          else
+            vm.env.ui.info I18n.t("vagrant.commands.common.vm_not_created")
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vagrant/command/resume.rb

@@ -0,0 +1,17 @@
+module Vagrant
+  module Command
+    class ResumeCommand < NamedBase
+      register "resume", "Resume a suspended Vagrant environment."
+
+      def execute
+        target_vms.each do |vm|
+          if vm.created?
+            vm.resume
+          else
+            vm.env.ui.info I18n.t("vagrant.commands.common.vm_not_created")
+          end
+        end
+      end
+    end
+  end
+end