Class: Vagrant::Config::VersionBase

Inherits:
Object
  • Object
show all
Defined in:
lib/vagrant/config/version_base.rb

Overview

This is the base class for any configuration versions, and includes the stub methods that configuration versions must implement. Vagrant supports configuration versioning so that backwards compatibility can be maintained for past Vagrantfiles while newer configurations are added. Vagrant only introduces new configuration versions for major versions of Vagrant.

Class Method Summary collapse

Class Method Details

.finalize(obj) ⇒ Object

This is called just before configuration loading is complete of a potentially completely-merged value to perform final touch-ups to the configuration, if required.

This is an optional method to implement. The default implementation will simply return the same object.

This will ONLY be called if this is the version that is being used. In the case that an upgrade is called, this will never be called.

Parameters:

  • obj (Object) —

    Final configuration object.

  • Finalized (Object) —

    configuration object.



35
36
37
 
# File 'lib/vagrant/config/version_base.rb', line 35

def self.finalize(obj)
  obj
end

.init ⇒ Object

Returns an empty configuration object. This can be any kind of object, since it is treated as an opaque value on the other side, used only for things like calling into merge.

Returns:

  • (Object)

Raises:

  • (NotImplementedError) 


18
19
20
 
# File 'lib/vagrant/config/version_base.rb', line 18

def self.init
  raise NotImplementedError
end

.load(proc) ⇒ Object

Loads the configuration for the given proc and returns a configuration object. The return value is treated as an opaque object, so it can be anything you'd like. The return value is the object that is passed into methods like merge, so it should be something you expect.

Parameters:

  • proc (Proc) —

    The proc that is to be configured.

Returns:

  • (Object)

Raises:

  • (NotImplementedError) 


46
47
48
 
# File 'lib/vagrant/config/version_base.rb', line 46

def self.load(proc)
  raise NotImplementedError
end

.merge(old, new) ⇒ Object

Merges two configuration objects, returning the merged object. The values of old and new are the opaque objects returned by load or init.

Once again, the return object is treated as an opaque value by the Vagrant configuration loader, so it can be anything you'd like.

Parameters:

  • old (Object) —

    Old configuration object.

  • new (Object) —

    New configuration object.

Returns:

  • (Object) —

    The merged configuration object.

Raises:

  • (NotImplementedError) 


60
61
62
 
# File 'lib/vagrant/config/version_base.rb', line 60

def self.merge(old, new)
  raise NotImplementedError
end

.upgrade(old) ⇒ Array

This is called if a previous version of configuration needs to be upgraded to this version. Each version of configuration should know how to upgrade the version immediately prior to it. This should be a best effort upgrade that makes many assumptions. The goal is for this to work in almost every case, but perhaps with some warnings. The return value for this is a 3-tuple: [object, warnings, errors], where object is the upgraded configuration object, warnings is an array of warning messages, and errors is an array of error messages.

Parameters:

  • old (Object) —

    The version of the configuration object just prior to this one.

Returns:

  • (Array) —

    The 3-tuple result. Please see the above documentation for more information on the exact structure of this object.

Raises:

  • (NotImplementedError) 


78
79
80
 
# File 'lib/vagrant/config/version_base.rb', line 78

def self.upgrade(old)
  raise NotImplementedError
end