Module: Versionomy::Conversion

Defined in:
lib/versionomy/conversion.rb,
lib/versionomy/conversion/base.rb,
lib/versionomy/conversion/parsing.rb,
lib/versionomy/format_definitions/semver.rb,
lib/versionomy/format_definitions/rubygems.rb

Overview

Conversion between version schemas.

Conversions are algorithms for converting from one schema to another. This is useful for performing conversions as well as comparing version numbers that use different schemas.

To implement a conversion algorithm, implement the API defined by Versionomy::Conversion::Base. Then, register your conversion by calling Versionomy::Conversion#register. You will need to specify which schemas (from and to) that your conversion should handle. From that point on, whenever Versionomy needs to convert a value between those two schemas, it will use your conversion. You can register the same conversion object for multiple pairs of schemas, but you can register only one conversion object for any pair.

A common technique for doing conversions is to unparse the version to a string, and then parse it in the new format. Versionomy provides a tool, Versionomy::Conversion::Parsing, for performing such conversions. The conversions between the standard and rubygems formats uses this tool. See Versionomy::Conversion::Rubygems for annotated examples.

Defined Under Namespace

Modules: Rubygems, Semver Classes: Base, Parsing

Class Method Summary collapse

Class Method Details

.convert(value_, format_, convert_params_ = nil) ⇒ Object

Convert the given value to the given format. This is identical to calling value_.convert(format_, convert_params_).

The format may be specified as a format object or as the name of a format in the Format registry.

Raises Versionomy::Errors::ConversionError if the value could not be converted.



81
82
83
# File 'lib/versionomy/conversion.rb', line 81

def convert(value_, format_, convert_params_=nil)
  value_.convert(format_, convert_params_)
end

.get(from_schema_, to_schema_, strict_ = false) ⇒ Object

Get a conversion capable of converting between the given schemas.

The schemas may be specified as format names, Format objects, schema wrapper objects, or the root field of the schema.

If strict is set to false, returns nil if no such conversion could be found. If strict is set to true, may raise one of these errors:

Raises Versionomy::Errors::UnknownFormatError if a format was specified by name but the name is not known.

Raises Versionomy::Errors::UnknownConversionError if the formats were recognized but no conversion was found to handle them.



100
101
102
103
104
105
106
107
# File 'lib/versionomy/conversion.rb', line 100

def get(from_schema_, to_schema_, strict_=false)
  key_ = _get_key(from_schema_, to_schema_)
  conversion_ = @mutex.synchronize{ @registry[key_] }
  if strict_ && conversion_.nil?
    raise Errors::UnknownConversionError
  end
  conversion_
end

.register(from_schema_, to_schema_, conversion_, silent_ = false) ⇒ Object

Register the given conversion as the handler for the given schemas.

The schemas may be specified as format names, Format objects, schema wrapper objects, or the root field of the schema.

Raises Versionomy::Errors::ConversionRedefinedError if a conversion has already been registered for the given schemas.

Raises Versionomy::Errors::UnknownFormatError if a format was specified by name but the name is not known.



121
122
123
124
125
126
127
128
129
130
131
132
# File 'lib/versionomy/conversion.rb', line 121

def register(from_schema_, to_schema_, conversion_, silent_=false)
  key_ = _get_key(from_schema_, to_schema_)
  @mutex.synchronize do
    if @registry.include?(key_)
      unless silent_
        raise Errors::ConversionRedefinedError
      end
    else
      @registry[key_] = conversion_
    end
  end
end