npm-semver The semantic versioner for npm

Install

npm install --save semver

Usage

作为节点模块:

const semver = require('semver')

semver.valid('1.2.3') // '1.2.3'
semver.valid('a.b.c') // null
semver.clean('  =v1.2.3   ') // '1.2.3'
semver.satisfies('1.2.3', '1.x || >=2.5.0 || 5.0.0 - 7.2.3') // true
semver.gt('1.2.3', '9.8.7') // false
semver.lt('1.2.3', '9.8.7') // true
semver.minVersion('>=1.0.0') // '1.0.0'
semver.valid(semver.coerce('v2')) // '2.0.0'
semver.valid(semver.coerce('42.6.7.9.3-alpha')) // '42.6.7'

作为命令行实用程序:

$ semver -h

A JavaScript implementation of the https://semver.org/ specification
Copyright Isaac Z. Schlueter

Usage: semver [options] <version> [<version> [...]]
Prints valid versions sorted by SemVer precedence

Options:
-r --range <range>
        Print versions that match the specified range.

-i --increment [<level>]
        Increment a version by the specified level.  Level can
        be one of: major, minor, patch, premajor, preminor,
        prepatch, or prerelease.  Default level is 'patch'.
        Only one version may be specified.

--preid <identifier>
        Identifier to be used to prefix premajor, preminor,
        prepatch or prerelease version increments.

-l --loose
        Interpret versions and ranges loosely

-p --include-prerelease
        Always include prerelease versions in range matching

-c --coerce
        Coerce a string into SemVer if possible
        (does not imply --loose)

Program exits successfully if any valid version satisfies
all supplied ranges, and prints all satisfying versions.

If no satisfying versions are found, then exits failure.

Versions are printed in ascending order, so supplying
multiple versions to the utility will just sort them.

Versions

https://semver.org/上v2.0.0规范描述了"版本".

前导的"=""v"字符被去除并被忽略.

Ranges

version range是一组comparators ,它们指定满足该范围的版本.

comparator由一个operator和一个version . 基本operators为:

例如,比较器>=1.2.7将匹配版本1.2.71.2.82.5.31.3.9 ,但不是版本1.2.61.1.0 .

比较器可以由空白连接起来以形成一个comparator set ,该comparator set由它包含的所有比较器的交集来满足.

一个范围由一个或多个比较器集组成,并由|| . 当且仅当||中的至少一个比较器中的每个比较器时,版本才匹配范围 -分隔的比较器集由版本满足.

例如,范围>=1.2.7 <1.3.0将匹配版本1.2.71.2.8 ,和1.2.99 ,而不是版本1.2.61.3.0 ,或1.1.0 .

范围1.2.7 || >=1.2.9 <2.0.0 1.2.7 || >=1.2.9 <2.0.0将匹配版本1.2.71.2.91.4.6 ,但不是版本1.2.82.0.0 .

Prerelease Tags

如果一个版本具有预发行标签(例如1.2.3-alpha.3 ),则只有在至少一个具有相同[major, minor, patch]元组的比较器也具有预发行标签的情况下[major, minor, patch]才允许它满足比较器集. .

例如,允许范围>1.2.3-alpha.3匹配版本1.2.3-alpha.7 ,但3.4.5-alpha.9 不会满足,即使3.4.5-alpha.9根据SemVer排序规则, 3.4.5-alpha.9在技​​术上"大于" 1.2.3-alpha.3 . 版本范围仅接受1.2.3版本上的预发行标签. 版本3.4.5 满足该范围,因为它没有预发布标志,并且3.4.5大于1.2.3-alpha.7 .

此行为的目的是双重的. 首先,预发行版本经常被非常快速地更新,并且包含许多重大更改,这些更改(根据作者的设计)尚不适合公众使用. 因此,默认情况下,它们从范围匹配语义中排除.

其次,选择使用预发行版本的用户已经明确表明了使用该特定的alpha / beta / rc版本集的意图. 通过在该范围中包含预发布标签,用户表示他们已经意识到风险. 但是,仍然不适合假定他们选择对下一组预发行版本承担类似的风险.

请注意,可以通过将options对象上的includePrerelease标志设置为任何进行范围匹配的函数来抑制此行为(将所有预发布版本视为正常版本,以进行范围匹配).

Prerelease Identifiers

.inc方法使用一个附加的identifier字符串参数,该参数会将字符串的值附加为预发行标识符:

semver.inc('1.2.3', 'prerelease', 'beta')
// '1.2.4-beta.0'

命令行示例:

$ semver 1.2.3 -i prerelease --preid beta
1.2.4-beta.0

然后可以用来进一步增加:

$ semver 1.2.4-beta.0 -i prerelease
1.2.4-beta.1

Advanced Range Syntax

高级范围语法以确定性方式降低了原始比较器的负担.

可以使用空白或||以与原始比较器相同的方式组合高级范围. .

Hyphen Ranges X.Y.Z - A.B.C

指定一个包含集合.

如果提供部分版本作为包含范围内的第一个版本,则缺失的部分将替换为零.

如果提供部分版本作为包含范围内的第二个版本,则接受以元组提供的部分开头的所有版本,但没有比提供的元组部分更大的版本.

X-Ranges 1.2.x 1.X 1.2.* *

Xx*任何一个都可以用来"代表" [major, minor, patch]元组中的一个数值.

部分版本范围被视为X范围,因此特殊字符实际上是可选的.

Tilde Ranges ~1.2.3 ~1.2 ~1

如果在比较器上指定了次要版本,则允许补丁程序级别的更改. 如果不允许,则允许进行次要更改.

Caret Ranges ^1.2.3 ^0.2.5 ^0.0.4

允许所做的更改不会修改[major, minor, patch]元组中最左边的非零数字. 换言之,这允许版本贴片和次要更新1.0.0以上,补丁更新为版本0.X >=0.1.0 ,以及用于版本没有更新0.0.X .

许多作者将0.x版本视为x是主要的"中断更改"指标.

当作者可能在0.2.40.3.0版本之间进行重大更改时,插入号范围是理想的,这是一种常见的做法. 但是,假定在0.2.40.2.5之间不会有重大变化. 根据通常观察到的做法,它允许假定为可加性(但不间断)的更改.

当解析插入符范围,缺少patch值desugars为数字0 ,但将允许值范围内的灵活性,即使在主要和次要版本均为0 .

丢失的minorpatch值将被减糖为零,即使主要版本为零,也允许这些值具有灵活性.

Range Grammar

综合所有这些,下面是范围的Backus-Naur语法,以使分析器作者受益:

range-set  ::= range ( logical-or range ) *
logical-or ::= ( ' ' ) * '||' ( ' ' ) *
range      ::= hyphen | simple ( ' ' simple ) * | ''
hyphen     ::= partial ' - ' partial
simple     ::= primitive | partial | tilde | caret
primitive  ::= ( '<' | '>' | '>=' | '<=' | '=' ) partial
partial    ::= xr ( '.' xr ( '.' xr qualifier ? )? )?
xr         ::= 'x' | 'X' | '*' | nr
nr         ::= '0' | ['1'-'9'] ( ['0'-'9'] ) *
tilde      ::= '~' partial
caret      ::= '^' partial
qualifier  ::= ( '-' pre )? ( '+' build )?
pre        ::= parts
build      ::= parts
parts      ::= part ( '.' part ) *
part       ::= nr | [-0-9A-Za-z]+

Functions

所有方法和类都带有最终options对象参数. 默认情况下,此对象中的所有选项均为false . 支持的选项有:

严格模式比较器和范围将严格限制其解析的SemVer字符串.

Comparison

Comparators

Ranges

请注意,由于范围可能是不连续的,因此版本可能不会大于范围,小于范围满足范围! 例如,范围1.2 <1.2.9 || >2.0.0 1.2 <1.2.9 || >2.0.0会有一个从1.2.92.0.0的孔,因此版本1.2.10不会大于范围(因为2.0.1满足,即较高),也不会小于范围(从1.2.8满足(较低),并且也不满足该范围.

如果您想知道某个版本满足还是不满足范围,请使用satisfies(version, range)函数.

Coercion

目的是为非semver字符串提供非常宽容的翻译. 它看起来在字符串的第一个数字,并且消耗所有剩余的字符满足至少一个局部semver(例如, 11.21.2.3 )直到最大允许长度(256个字符). 较长的版本会被简单地截断( 4.6.3.9.2-alpha2变为4.6.3 ). 所有周围的文本都将被忽略( v3.4 replaces v3.3.1变成3.4.0 ). 仅缺少数字的文本将无法强制转换( version one无效). 考虑强制转换的任何semver组件的最大长度为16个字符; 更长的组件将被忽略( 10000000000000000.4.7.4变成4.7.4 ). 任何semver组件的最大值为Number.MAX_SAFE_INTEGER || (2**53 - 1) Number.MAX_SAFE_INTEGER || (2**53 - 1) ; 较高值的组件无效( 9999999999999999.4.7.4可能无效).


by  ICOPY.SITE