Class: Vagrant::Plugin::V1::Plugin

Inherits:
Object
  • Object
show all
Defined in:
lib/vagrant/plugin/v1/plugin.rb

Overview

This is the superclass for all V1 plugins.

Constant Summary collapse

ALL_ACTIONS =

Special marker that can be used for action hooks that matches all action sequences.

:__all_actions__
LOGGER =

The logger for this class.

Log4r::Logger.new("vagrant::plugin::v1::plugin")
ROOT_CLASS =

Set the root class up to be ourself, so that we can reference this from within methods which are probably in subclasses.

self

Class Method Summary collapse

Class Method Details

.action_hook(name, &block) ⇒ Array

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.

Parameters:

  • name (Symbol) —

    Name of the action.

Returns:

  • (Array) —

    List of the hooks for the given action.



61
62
63
64
65
66
67
68
69
70
71
 
# File 'lib/vagrant/plugin/v1/plugin.rb', line 61

def self.action_hook(name, &block)
  # Get the list of hooks for the given hook name
  data[:action_hooks] ||= {}
  hooks = data[:action_hooks][name.to_sym] ||= []

  # Return the list if we don't have a block
  return hooks if !block_given?

  # Otherwise add the block to the list of hooks for this action.
  hooks << block
end

.command(name = UNSET_VALUE, &block) ⇒ Object

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.

Parameters:

  • name (String) (defaults to: UNSET_VALUE) —

    Subcommand key.



78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
 
# File 'lib/vagrant/plugin/v1/plugin.rb', line 78

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

.communicator(name = UNSET_VALUE, &block) ⇒ Object

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.

Parameters:

  • name (String) (defaults to: UNSET_VALUE) —

    Communicator name.



103
104
105
106
107
108
109
110
111
 
# File 'lib/vagrant/plugin/v1/plugin.rb', line 103

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

.config(name = UNSET_VALUE, upgrade_safe = false, &block) ⇒ Object

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.

Parameters:

  • name (String) (defaults to: UNSET_VALUE) —

    Configuration key.

  • upgrade_safe (Boolean) (defaults to: false) —

    If this is true, then this configuration key is safe to load during an upgrade, meaning that it depends on NO Vagrant internal classes. Do not set this to true unless you really know what you’re doing, since you can cause Vagrant to crash (although Vagrant will output a user-friendly error message if this were to happen).



127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
 
# File 'lib/vagrant/plugin/v1/plugin.rb', line 127

def self.config(name=UNSET_VALUE, upgrade_safe=false, &block)
  data[:config] ||= Registry.new

  # Register a new config class only if a name was given.
  if name != UNSET_VALUE
    data[:config].register(name.to_sym, &block)

    # If we were told this is an upgrade safe configuration class
    # then we add it to the set.
    if upgrade_safe
      data[:config_upgrade_safe] ||= Set.new
      data[:config_upgrade_safe].add(name.to_sym)
    end
  end

  # Return the registry
  data[:config]
end

.data ⇒ Hash

Returns the internal data associated with this plugin. This should NOT be called by the general public.

Returns:

  • (Hash) 


204
205
206
 
# File 'lib/vagrant/plugin/v1/plugin.rb', line 204

def self.data
  @data ||= {}
end

.description(value = UNSET_VALUE) ⇒ String

Sets a human-friendly descrition of the plugin.

Parameters:

  • value (String) (defaults to: UNSET_VALUE) —

    Description of the plugin.

Returns:

  • (String) —

    Description of the plugin.



51
52
53
 
# File 'lib/vagrant/plugin/v1/plugin.rb', line 51

def self.description(value=UNSET_VALUE)
  get_or_set(:description, value)
end

.guest(name = UNSET_VALUE, &block) ⇒ Object

Defines an additionally available guest implementation with the given key.

Parameters:

  • name (String) (defaults to: UNSET_VALUE) —

    Name of the guest.



150
151
152
153
154
155
156
157
158
 
# File 'lib/vagrant/plugin/v1/plugin.rb', line 150

def self.guest(name=UNSET_VALUE, &block)
  data[:guests] ||= Registry.new

  # Register a new guest class only if a name was given
  data[:guests].register(name.to_sym, &block) if name != UNSET_VALUE

  # Return the registry
  data[:guests]
end

.host(name = UNSET_VALUE, &block) ⇒ Object

Defines an additionally available host implementation with the given key.

Parameters:

  • name (String) (defaults to: UNSET_VALUE) —

    Name of the host.



164
165
166
167
168
169
170
171
172
 
# File 'lib/vagrant/plugin/v1/plugin.rb', line 164

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

.manager ⇒ V1::Manager

This returns the manager for all V1 plugins.

Returns:



24
25
26
 
# File 'lib/vagrant/plugin/v1/plugin.rb', line 24

def self.manager
  @manager ||= Manager.new
end

.name(name = UNSET_VALUE) ⇒ String

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.

Parameters:

  • name (String) (defaults to: UNSET_VALUE) —

    Name of the plugin.

Returns:

  • (String) —

    The name of the plugin.



35
36
37
38
39
40
41
42
43
44
45
 
# File 'lib/vagrant/plugin/v1/plugin.rb', line 35

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

.provider(name = UNSET_VALUE, &block) ⇒ Object

Registers additional providers to be available.

Parameters:

  • name (Symbol) (defaults to: UNSET_VALUE) —

    Name of the provider.



177
178
179
180
181
182
183
184
185
 
# File 'lib/vagrant/plugin/v1/plugin.rb', line 177

def self.provider(name=UNSET_VALUE, &block)
  data[:providers] ||= Registry.new

  # Register a new provider class only if a name was given
  data[:providers].register(name.to_sym, &block) if name != UNSET_VALUE

  # Return the registry
  data[:providers]
end

.provisioner(name = UNSET_VALUE, &block) ⇒ Object

Registers additional provisioners to be available.

Parameters:

  • name (String) (defaults to: UNSET_VALUE) —

    Name of the provisioner.



190
191
192
193
194
195
196
197
198
 
# File 'lib/vagrant/plugin/v1/plugin.rb', line 190

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