Documentation
¶
Overview ¶
Package version provides parsing of version strings, such as "1.2.3". The package returns a struct that contains several pieces of information.
The primary motivation for this package was to create a representation of versions that can be stored and sorted in a Postgres database. To that end, we turn all versions into a slice of `*decimal.Big` (github.com/ericlagergren/decimal) values.
It is not possible to produce reasonably sortable versions across multiple language ecosystems, or even between different packages in the same ecosystem. Instead, we simply aim to make sure that all versions of a single package are sortable, even if the versioning scheme for that package changes over time. We assume that even if the versioning scheme changes, that the "major" version portion of the new scheme will sort higher than the "major" version of the old scheme. We have "major" in quotes there because some versioning schemes don't really distinguish between major, minor, and patch portions of a version.
The various parsing schemes handle non-numeric components as well as numbers appropriately. For some schemes, non-numeric components like strings have special meaning. For example, in semver there is a strict ordering for "alpha", "beta", etc. For other schemes we simply encode non-numeric values into decimal values using the Unicode codepoint for each letter.
We currently make no guarantee that the decimal representation of a version will not change between releases of this module. That means that if you store the versions you may have to re-parse existing versions if you upgrade this module. Given that fact, you should always make sure to store the original version that you parsed alongside the decimal slice representation.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
Types ¶
type ParsedAs ¶
type ParsedAs int
ParsedAs is an enum for the various types of versions we can parse.
const ( // Unknown should never be used. Unknown ParsedAs = iota // Generic is a generic version. Generic // SemVer is the well known semver scheme (https://semver.org/). SemVer // PerlDecimal is for Perl versions which are simply numbers (42, 1.2, etc.). PerlDecimal // PerlVString is for Perl v-strings like "v1.1.2" (but these don't // require the leading "v", so "1.2.3" is also valid). PerlVString // PHP is for PHP versions as used by composer. PHP // PythonLegacy is for Python versions before PEP440 was adopted. PythonLegacy // PythonPEP440 is for versions as described in PEP440. PythonPEP440 // Ruby is for Ruby versions. Ruby )
func ParsedAsString ¶ added in v0.0.3
ParsedAsString retrieves an enum value from the enum constants string name. Throws an error if the param is not part of the enum.
func ParsedAsValues ¶ added in v0.0.3
func ParsedAsValues() []ParsedAs
ParsedAsValues returns all values of the enum
func (ParsedAs) IsAParsedAs ¶ added in v0.0.3
IsAParsedAs returns "true" if the value is listed in the enum definition. "false" otherwise
type Version ¶
type Version struct {
// Original is the string that was passed to the parsing func.
Original string `json:"version"`
// Decimal contains a slice of `*decimal.Big` values. This will always
// contain at least one element.
Decimal []*decimal.Big `json:"sortable_version"`
// ParsedAs indicates which type the version was parsed as.
ParsedAs ParsedAs `json:"-"`
}
Version is the struct returned from all parsing funcs.
func ParseGeneric ¶
ParseGeneric parses the version string into an array of decimal numbers such that two parsed version strings can be compared. This function treats numbers as individually comparable segments and not as decimal numbers, i.e. 1.2 is parsed to be compared as two numbers: 1 and 2.
func ParsePHP ¶ added in v0.0.7
ParsePHP attempts to parse a version according to the same rules used by composer (https://github.com/composer/semver)
func ParsePerl ¶
ParsePerl parses version using the version parsing algorithm used by version.pm (https://metacpan.org/pod/distribution/version/lib/version.pm). version.pm considers there to be two perl version types: decimal (1.20) and dotted-decimal (v1.2.3). This function parses both types and normalizes them to dotted-decimal for comparison purposes.
func ParsePython ¶
ParsePython attempts to parse a version according to PEP440 (https://www.python.org/dev/peps/pep-0440/) and falls back to legacy Python parsing if that fails.
func ParseRuby ¶ added in v0.0.4
ParseRuby attempts to parse a version according to the same rules used by rubygems (https://github.com/rubygems/rubygems)
func ParseSemVer ¶
ParseSemVer parses the semantic version (https://semver.org/) version string into an array of decimal numbers such that two parsed version strings can be compared as required by the semantic versioning specification.
Source Files