README
¶
exver
Package exver implements parser and type for extended Sementic Versionning 2.0.
exver is superset of go's semver.
The general form of a semantic version string accepted by this package is
[v]MAJOR[.MINOR[.PATCH[.EXTRA][-PRERELEASE][+BUILD]]]
Basically same as go's semver package. But small extensios are added:
vprefix is optional.- One EXTRA version component is added.
- All version components are limited at maximum of
9999.- This limitation is placed to convert version to numeric form.
numeric conversion
Core.Int64 converts core parts (version without pre-release and build-meta) into numeric form
so that it can be saved in any storage and compared naturally within them.
The conversion logic is roghly equivalent of strconv.ParseInt(fmt.Sprintf("%04d%04d%04d%04d", a, b, c, d), 10, 64) but more efficient.
Documentation
¶
Index ¶
- type Core
- func (c Core) Compare(u Core) int
- func (c Core) Component() [4]uint16
- func (c Core) Extra() uint16
- func (c Core) Int64() int64
- func (c Core) Len() int
- func (c Core) Major() uint16
- func (c Core) MarshalJSON() ([]byte, error)
- func (c Core) MarshalText() ([]byte, error)
- func (c Core) Minor() uint16
- func (c Core) Normalize() Core
- func (c Core) NormalizeExtended() Core
- func (c Core) Nums() []uint
- func (c Core) Patch() uint16
- func (c Core) String() string
- func (c *Core) UnmarshalJSON(data []byte) error
- func (c *Core) UnmarshalText(text []byte) error
- type Version
- func (v Version) Build() string
- func (v Version) Compare(u Version) int
- func (v Version) Core() Core
- func (v Version) MarshalJSON() ([]byte, error)
- func (v Version) MarshalText() ([]byte, error)
- func (v Version) PreRelease() string
- func (v Version) PreReleaseSortable() string
- func (v Version) String() string
- func (v *Version) UnmarshalJSON(data []byte) error
- func (v *Version) UnmarshalText(text []byte) error
- func (v Version) V() bool
- func (v Version) WithBuild(buildMeta string) (Version, error)
- func (v Version) WithCore(core Core) Version
- func (v Version) WithPreRelease(prerelease string) (Version, error)
- func (v Version) WithV(vPrefix bool) Version
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Core ¶
type Core struct {
// contains filtered or unexported fields
}
Core is Version without v-prefix, pre-release and build-meta.
Core represents numeric version. In text representation, it contains 1 to 4 numeric component separated by '.' letter: <major> "." <minor> "." <patch> "." <extra>. Each comopnent is limited at maximum of 9999.
The zero value of Core is invalid and must be initialized with NewCore or ParseCore. However calling Core.String with zero value returns "0.0.0" and works fine almost all situation.
func MustNewCore ¶
MustNewCore is like NewCore but panics if an error occurs.
func MustParseCore ¶
MustParseCore is like ParseCore but panics if any error occurs.
func NewCore ¶
NewCore initializes Core. len(nums) must be between 1 and 4. If any component of nums are greater than 9999, it returns an error.
func ParseCore ¶
ParseCore parses string expression and returns Core. s must be dot-separated numeric values without leading zeros. Same rules to NewCore apply here: the number of version fields must be in between 1 to 4 and each version component must not be greater than 9999.
func (Core) Compare ¶
Compare returns
-1 if c is less than u, 0 if c equals u, +1 if c is greater than u.
Missing parts are always treated as 0. e.g. comparing 1 and 1.0 returns 0, 1.0.0.2 and 1.0 returns +1.
func (Core) Component ¶
Component returns internal version field expression, ordered as <major>, <minor>, <patch>, <extra>.
func (Core) Int64 ¶
Int64 returns version fields as int64 value. The conversion logic is roghly same of `strconv.ParseInt(fmt.Sprintf("%04d%04d%04d%04d", a, b, c, d), 10, 64)`.
func (Core) MarshalJSON ¶
func (Core) MarshalText ¶
func (Core) Normalize ¶ added in v1.1.0
Normalize normalizes c into sem ver compatible form, that is, <major> "." <minor> "." <patch>. If version compoments were missed, Normalize fills them as 0.
func (Core) NormalizeExtended ¶ added in v1.1.0
NormalizeExtended normalizes c into extended form, that is, <major> "." <minor> "." <patch> "." <extra>. If version compoments were missed, NormalizeExtended fills them as 0.
func (Core) Nums ¶
Nums returns version fields as slice of uint. The length of the return value may vary depending on input for NewCore or ParseCore, e.g. if input was `1` then Nums returns []uint{1}, if was `1.2.3.4`, it returns []uint{1, 2, 3, 4}.
func (Core) String ¶
String returns string representation of the version. If c is zero, it returns "0.0.0".
func (*Core) UnmarshalJSON ¶
func (*Core) UnmarshalText ¶
type Version ¶
type Version struct {
// contains filtered or unexported fields
}
Version represents an extended semantic versioning v2. The general form of a semantic version string accepted by Version is
[v]MAJOR[.MINOR[.PATCH[.EXTRA][-PRERELEASE][+BUILD]]
- `v` prefix is optionally allowed
- One extra version field (EXTRA) is also allowed
- Each version components are limited to 9999.
- pre-release and build-meta is only allowed when the verions is full (has PATCH) or extended (has EXTRA).
func MustParse ¶
MustParse is like Parse but panics when s is not accepted as the extended version string.
func (Version) Build ¶
Build returns build-meta string. The retunred value is empty if v is not suffixed with build-meta.
func (Version) Compare ¶
Compare returns
-1 if v is less than u, 0 if v equals u, +1 if v is greater than u.
Unlike Core.Compare, the number of version fields affects ordering: if cores and pre-release of both v and u are semantically same, the shorter one is considered less. e.g. 1.0 is less than 1.0.0.
The pre-release values are compared as per spec. see https://semver.org/#spec-item-11
func (Version) MarshalJSON ¶
func (Version) MarshalText ¶
func (Version) PreRelease ¶
PreRelease returns pre-release string. The returned value is empty if v is not suffixed with pre-prelease.
func (Version) PreReleaseSortable ¶ added in v1.1.0
PreReleaseSortable returns pre-release string normalized so that it can be sorted simply by ascii order.
The size of returned string is always fixed at 256 by laying following limitations;
- Dot-separated parts are limited at maximum of 8.
- Each sperated part is limited at maximum of 31 letters.
You can safely cut off the right-most character (v.PreReleaseSortable()[:255]) to fit it to 255 chars (for VARCHAR(255) fields.)
As per semantic version 2 spec, pre-release can be dot-separated ascii text. Each sperated part is compared as like version components in version core. Parts with only numeric value is compared as number, others as ascii text.
To simulate the comparison rule, PreReleaseSortable pads '0' at left if a part consits of only numeric value, otherwise right.
PreReleaseSortable returns strings.Repeat("~", 256) if v is not with pre-release, since as per the spec, version without pre-prelease is more than versions with that.
func (*Version) UnmarshalJSON ¶
func (*Version) UnmarshalText ¶
func (Version) WithBuild ¶
WithBuild returns v with build-meta value is changed to the input. If the input is not compliant to the spec, it returns unmodified v and an non-nil error.
func (Version) WithPreRelease ¶
WithPreRelease returns v with pre-prelease value is changed to the input. If the input is not compliant to the spec, it returns unmodified v and an non-nil error.
Source Files