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



32
33
34
 
# File 'lib/vagrant/config/version_base.rb', line 32

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) 


15
16
17
 
# File 'lib/vagrant/config/version_base.rb', line 15

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) 


43
44
45
 
# File 'lib/vagrant/config/version_base.rb', line 43

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) 


57
58
59
 
# File 'lib/vagrant/config/version_base.rb', line 57

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) 


75
76
77
 
# File 'lib/vagrant/config/version_base.rb', line 75

def self.upgrade(old)
  raise NotImplementedError
end