Class: Vagrant::Actions::Base

Inherits:
Object
  • Object
show all
Includes:
Util
Defined in:
lib/vagrant/actions/base.rb

Overview

Base class for any command actions.

Actions are the smallest unit of functionality found within Vagrant. Vagrant composes many actions together to execute its complex tasks while keeping the individual pieces of a task as discrete reusable actions. Actions are ran exclusively by an action runner which is simply a subclass of Runner.

Actions work by implementing any or all of the following methods which a Runner executes:

  • ‘prepare` - Called once for each action before any action has `execute!` called. This is meant for basic setup.

  • ‘execute!` - This is where the meat of the action typically goes; the main code which executes the action.

  • ‘cleanup` - This is called exactly once for each action after every other action is completed. It is meant for cleaning up any resources.

  • ‘rescue` - This is called if an exception occurs in _any action_. This gives every other action a chance to clean itself up.

For details of each step of an action, read the specific function call documentation below.

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Util

#error_and_exit, included, #logger, #wrap_output

Constructor Details

#initialize(runner, *args) ⇒ Base

Initialization of the action, passing any arguments which may have been given to the runner. This method can be used by subclasses to save any of the configuration options which are passed in.



35
36
37
 
# File 'lib/vagrant/actions/base.rb', line 35

def initialize(runner, *args)
  @runner = runner
end

Instance Attribute Details

#runner ⇒ Object (readonly)

The runner which is executing the action



27
28
29
 
# File 'lib/vagrant/actions/base.rb', line 27

def runner
  @runner
end

Instance Method Details

#cleanup ⇒ Object

This method is called after all actions have finished executing. It is meant as a place where final cleanup code can be done, knowing that all other actions are finished using your data.



72
 
# File 'lib/vagrant/actions/base.rb', line 72

def cleanup; end

#execute! ⇒ Object

This method is called once, after preparing, to execute the actual task. This method is responsible for calling any callbacks. Adding new actions here will have unpredictable effects and should never be done.

Examples of its usage:

def execute!
  @vm.invoke_callback(:before_oven, "cookies")
  # Do lots of stuff here
  @vm.invoke_callback(:after_oven, "more", "than", "one", "option")
end



67
 
# File 'lib/vagrant/actions/base.rb', line 67

def execute!; end

#follows ⇒ Object

This method is called when the runner is determining the actions that must precede a given action. You would say “This action follows [Action1, Action2]”



94
 
# File 'lib/vagrant/actions/base.rb', line 94

def follows; [] end

#precedes ⇒ Object

This method is called when the runner is determining the actions that must follow a given action. You would say “This action precedes [Action3, Action4]



98
 
# File 'lib/vagrant/actions/base.rb', line 98

def precedes; [] end

#prepare ⇒ Object

This method is called once per action, allowing the action to setup any callbacks, add more events, etc. Prepare is called in the order the actions are defined, and the action itself has no control over this.

Examples of its usage:

Perhaps we need an additional action only if a configuration is set:

def prepare
  @vm.actions << FooAction if Vagrant.config[:foo] == :bar
end



52
 
# File 'lib/vagrant/actions/base.rb', line 52

def prepare; end

#rescue(exception) ⇒ Object

This method is only called if some exception occurs in the chain of actions. If an exception is raised in any action in the current chain, then every action part of that chain has #rescue called before raising the exception further. This method should be used to perform any cleanup necessary in the face of errors.

Warning: Since this method is called when an exception is already raised, be _extra careful_ when implementing this method to handle all your own exceptions, otherwise it’ll mask the initially raised exception.



84
 
# File 'lib/vagrant/actions/base.rb', line 84

def rescue(exception); end