Class: Vagrant::Command::Base

Inherits:
Thor::Group
  • Object
show all
Includes:
Thor::Actions, Helpers
Defined in:
lib/vagrant/command/base.rb

Overview

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 Base.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.

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Helpers

#initialize_environment, #target_vms

Constructor Details

#initialize(*args) ⇒ Base

Returns a new instance of Base.



92
93
94
95
 
# File 'lib/vagrant/command/base.rb', line 92

def initialize(*args)
  super
  initialize_environment(*args)
end

Instance Attribute Details

#env ⇒ Object (readonly)

Returns the value of attribute env.



68
69
70
 
# File 'lib/vagrant/command/base.rb', line 68

def env
  @env
end

Class Method Details

.register(usage, description, opts = nil) ⇒ Object

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

Parameters:

  • usage (String)
  • description (String)
  • opts (Hash) (defaults to: nil) 


87
88
89
90
 
# File 'lib/vagrant/command/base.rb', line 87

def self.register(usage, description, opts=nil)
  desc description
  CLI.register(self, extract_name_from_usage(usage), usage, desc, opts)
end