module Versionomy::Conversion

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.

Public Class Methods

convert(value_, format_, convert_params_=nil) click to toggle source

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.

# 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) click to toggle source

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.

# 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

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.

# 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