Class: Vagrant::Plugin::V2::Plugin

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

Overview

This is the superclass for all V2 plugins.

Direct Known Subclasses

Remote::Plugin

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::v2::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, hook_name = nil, &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 (String) —

    Name of the action.

  • hook_name (Symbol) (defaults to: nil) —

    The location to hook. If this isn't set, every middleware action is hooked.

Returns:

  • (Array) —

    List of the hooks for the given action.



92
93
94
95
96
97
98
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 92

def self.action_hook(name, hook_name=nil, &block)
  # The name is currently not used but we want it for the future.
  hook_name = hook_name.to_s if hook_name

  hook_name ||= ALL_ACTIONS
  components.action_hooks[hook_name.to_sym] << block
end

.command(name, **opts, &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) —

    Subcommand key.



105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 105

def self.command(name, **opts, &block)
  # 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

  # By default, the command is primary
  opts[:primary] = true if !opts.key?(:primary)

  # Register the command
  components.commands.register(name.to_sym) do
    [block, opts]
  end

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



130
131
132
133
134
135
136
137
138
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 130

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

.components ⇒ Components

Returns the Components for this plugin.

Returns:



53
54
55
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 53

def self.components
  @components ||= Components.new
end

.config(name, scope = nil, &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) —

    Configuration key.



148
149
150
151
152
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 148

def self.config(name, scope=nil, &block)
  scope ||= :top
  components.configs[scope].register(name.to_sym, &block)
  nil
end

.data ⇒ Hash

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

Returns:

  • (Hash) 


286
287
288
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 286

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

.description(value = UNSET_VALUE) ⇒ String

Sets a human-friendly description of the plugin.

Parameters:

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

    Description of the plugin.

Returns:

  • (String) —

    Description of the plugin.



80
81
82
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 80

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

.disable_remote_manager ⇒ Object 



45
46
47
48
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 45

def self.disable_remote_manager
  Remote::Manager.client = nil
  @manager = local_manager
end

.enable_remote_manager(client, core_client: nil) ⇒ Object 



39
40
41
42
43
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 39

def self.enable_remote_manager(client, core_client: nil)
  Remote::Manager.client = client
  Remote::Manager.core_client = core_client
  @manager = remote_manager
end

.guest(name, parent = nil, &block) ⇒ Object

Defines an additionally available guest implementation with the given key.

Parameters:

  • name (String) —

    Name of the guest.

  • parent (String) (defaults to: nil) —

    Name of the parent guest (if any)



159
160
161
162
163
164
165
166
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 159

def self.guest(name, parent=nil, &block)
  components.guests.register(name.to_sym) do
    parent = parent.to_sym if parent

    [block.call, parent]
  end
  nil
end

.guest_capability(guest, cap, &block) ⇒ Object

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.

Parameters:

  • guest (String) —

    The name of the guest

  • cap (String) —

    The name of the capability



175
176
177
178
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 175

def self.guest_capability(guest, cap, &block)
  components.guest_capabilities[guest.to_sym].register(cap.to_sym, &block)
  nil
end

.host(name, parent = nil, &block) ⇒ Object

Defines an additionally available host implementation with the given key.

Parameters:

  • name (String) —

    Name of the host.

  • parent (String) (defaults to: nil) —

    Name of the parent host (if any)



185
186
187
188
189
190
191
192
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 185

def self.host(name, parent=nil, &block)
  components.hosts.register(name.to_sym) do
    parent = parent.to_sym if parent

    [block.call, parent]
  end
  nil
end

.host_capability(host, cap, &block) ⇒ Object

Defines a capability for the given host. 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.

Parameters:

  • host (String) —

    The name of the host

  • cap (String) —

    The name of the capability



201
202
203
204
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 201

def self.host_capability(host, cap, &block)
  components.host_capabilities[host.to_sym].register(cap.to_sym, &block)
  nil
end

.local_manager ⇒ Object 



31
32
33
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 31

def self.local_manager
  @_manager ||= Manager.new
end

.manager ⇒ V2::Manager

This returns the manager for all V2 plugins.

Returns:



27
28
29
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 27

def self.manager
  @manager ||= local_manager
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.



64
65
66
67
68
69
70
71
72
73
74
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 64

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, options = nil, &block) ⇒ Object

Registers additional providers to be available.

Parameters:

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

    Name of the provider.



209
210
211
212
213
214
215
216
217
218
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 209

def self.provider(name=UNSET_VALUE, options=nil, &block)
  options ||= {}
  options[:priority] ||= 5

  components.providers.register(name.to_sym) do
    [block.call, options]
  end

  nil
end

.provider_capability(provider, cap, &block) ⇒ Object

Defines a capability for the given provider. 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.

Parameters:

  • provider (String) —

    The name of the provider

  • cap (String) —

    The name of the capability



227
228
229
230
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 227

def self.provider_capability(provider, cap, &block)
  components.provider_capabilities[provider.to_sym].register(cap.to_sym, &block)
  nil
end

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

Registers additional provisioners to be available.

Parameters:

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

    Name of the provisioner.



235
236
237
238
239
240
241
242
243
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 235

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

.push(name, options = nil, &block) ⇒ Object

Registers additional pushes to be available.

Parameters:

  • name (String) —

    Name of the push.

  • options (Hash) (defaults to: nil) —

    List of options for the push.



249
250
251
252
253
254
255
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 249

def self.push(name, options=nil, &block)
  components.pushes.register(name.to_sym) do
    [block.call, options]
  end

  nil
end

.remote_manager ⇒ Object 



35
36
37
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 35

def self.remote_manager
  @_remote_manager ||= Remote::Manager.new(local_manager)
end

.synced_folder(name, priority = 10, &block) ⇒ Object

Registers additional synced folder implementations.

higher (big) numbers are tried before lower (small) numbers.

Parameters:

  • name (String) —

    Name of the implementation.

  • priority (Integer) (defaults to: 10) —

    The priority of the implementation,



262
263
264
265
266
267
268
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 262

def self.synced_folder(name, priority=10, &block)
  components.synced_folders.register(name.to_sym) do
    [block.call, priority]
  end

  nil
end

.synced_folder_capability(synced_folder, cap, &block) ⇒ Object

Defines a capability for the given synced folder. 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.

Parameters:

  • synced_folder (String) —

    The name of the synced folder

  • cap (String) —

    The name of the capability



277
278
279
280
 
# File 'lib/vagrant/plugin/v2/plugin.rb', line 277

def self.synced_folder_capability(synced_folder, cap, &block)
  components.synced_folder_capabilities[synced_folder.to_sym].register(cap.to_sym, &block)
  nil
end