Nickel

std.package

`ExactSemverReq`

A contract for exact semantic version ("semver") requirements, structured as a record.

An exact semver requirement looks like "=1.2.3" or "=1.2.3-rc1": it starts with an equals sign, must contain major, minor, and patch versions, and may contain a prerelease specifier.

This is a normalizing contract, which accepts either a string to be parsed or a record. If a string is provided, it will be parsed into a record (in the std.package.structured.ExactSemverReq format).

`GitDependency`

A contract identifying a dependency that can be fetched from a git repository.

`GitDependency.path | String`

The path of the nickel package within the git repository. If omitted, the nickel package is at the root of the git repository.

`GitDependency.ref | [| 'Head, 'Branch String, 'Tag String, 'Commit String |]`

The git ref to fetch from the repository.

If not provided, defaults to 'Head.

`GitDependency.url | String`

The url of a git repository.

This supports local file paths, https urls like https://example.com/example-repo, and ssh urls like user@example.com:repo.

`IndexDependency`

A contract identifying a dependency that can be fetched from a package index.

`IndexDependency.package | String`

The dependency's identifier within the package index, in the format "github/<organization>/<repository>".

`IndexDependency.version | SemverReq`

The required version of the package.

Nickel supports two kinds of requirements: semver-compatible requirements and exact version requirements. Semver-compatible requirements take the form "major.minor.patch", where minor and patch are optional. Their semantics are:

"1.2.3" will match all versions having major version 1, minor version 2, and patch version at least 3.
"1.2" will match all versions having major version 1 and minor version at least 2.
"1" will match all versions having major version 1.
a semver-compatible requirement will never match a prerelease version.

Exact version requirements take the form "=major.minor.patch-pre", where the prerelease tag is optional, but major, minor, and patch are all required.

`Manifest`

A contract for a Nickel package manifest.

Example

{
  name = "my-package",
  version = "1.0.0",
  minimal_nickel_version = "1.10",
  authors = ["Me <me@example.com>"],
  description = "My great package",

  dependencies = {
    my_local_dep = 'Path "../somewhere",
    git_dep = 'Git { url = "https://example.com/repo", ref = 'Tag "v1.0" },
    index_dep = 'Index { package = "github/nickel-lang/example", version = "1.0" },
  },
} | std.package.Manifest

`Manifest.authors | Array String`

The authors of this package.

`Manifest.dependencies | { _ : [| 'Path String, 'Git std.package.GitDependency, 'Index std.package.IndexDependency |] }`

A dictionary of package dependencies, keyed by the name that this package uses to refer to them locally.

`Manifest.description | String`

A description of this package.

`Manifest.keywords | Array String`

A list of keywords to help people find this package.

`Manifest.license | String`

The name of the license that this package is available under.

This is a completely free-form string, but some tooling may impose restrictions. For example, if you want to publish your package in Nickel's global package registry, the license field needs to be a valid SPDX license expression that allows redistribution.

`Manifest.minimal_nickel_version | String`

`Manifest.minimal_nickel_version | SemverPrefix`

The minimal nickel version required for this package.

`Manifest.name | String`

The name of this package.

`Manifest.version | String`

`Manifest.version | Semver`

The version of this package.

Any semantic version is accepted, but the build metadata field has no effect when matching versions.

`Semver`

A contract for semantic version ("semver") identifiers.

This is a normalizing contract, which accepts either a string to be parsed or a record. If a string is provided, it will be parsed into a record (in the std.package.structured.Semver format).

Examples

"1.2.0-pre1" | std.package.Semver
# => { major = 1, minor = 2, patch = 0, pre = "pre1", }

{ major = 1, minor = 2, patch = 0 } | std.package.Semver
# => { major = 1, minor = 2, patch = 0, }

{ major = 1, minor = 2 } | std.package.Semver
# => error: missing definition

"1.foo" | std.package.Semver
# => error: contract broken by a value

`SemverPrefix`

A contract for semantic version ("semver") prefixes.

This prefix must contain a major version number. It may contain a minor version and a patch version, but it must not contain a prerelease version or build metadata.

This is a normalizing contract, which accepts either a string to be parsed or a record. If a string is provided, it will be parsed into a record (in the std.package.structured.SemverPrefix format).

Examples

"1.2" | std.package.SemverPrefix
# => { major = 1, minor = 2 }

{ major = 1, minor = 2 } | std.package.SemverPrefix
# => { major = 1, minor = 2 }

"1.foo" | std.package.SemverPrefix
# => error: contract broken by a value

`SemverReq`

A contract for semantic version ("semver") requirements.

This is a normalizing contract, which accepts either a string to be parsed or a record. If a string is provided, it will be parsed into a record (in the std.package.structured.SemverReq format).

"1.2.3" will match all versions having major version 1, minor version 2, and patch version at least 3.
"1.2" will match all versions having major version 1 and minor version at least 2.
"1" will match all versions having major version 1.
a semver-compatible requirement will never match a prerelease version.

Exact version requirements take the form "=major.minor.patch-pre", where the prerelease tag is optional, but major, minor, and patch are all required.

Examples

"1.2" | SemverReq
# => 'Compatible { major = 1, minor = 2 }

"=1.2" | SemverReq
# => error: contract broken by a value

"1.2.0" | SemverReq
# => 'Compatible { major = 1, minor = 2, patch = 0 }

"=1.2.0" | SemverReq
# => 'Exact { major = 1, minor = 2, patch = 0, }

"1.2.0-pre1" | SemverReq
# => error: contract broken by a value

"=1.2.0-pre1" | SemverReq
# => 'Exact { major = 1, minor = 2, patch = 0, pre = "pre1", }

`structured`

`structured.ExactSemverReq`

A contract for exact semantic version ("semver") requirements, structured as a record.

This differs from std.package.structured.Semver in that it lacks a build metadata field.

`structured.ExactSemverReq.major | number.Nat`

The major version number.

`structured.ExactSemverReq.minor | number.Nat`

The minor version number.

`structured.ExactSemverReq.patch | number.Nat`

The patch version.

`structured.ExactSemverReq.pre | String`

The prerelease identifier.

`structured.Semver`

A contract for semantic version ("semver") identifiers, structured as a record.

See also std.package.Semver, which can produce one of these by parsing a string.

`structured.Semver.build | String`

The build metadata.

This is completely ignored while comparing versions for compatibility.

`structured.Semver.major | number.Nat`

The major version number.

`structured.Semver.minor | number.Nat`

The minor version number.

`structured.Semver.patch | number.Nat`

The patch version.

`structured.Semver.pre | String`

The prerelease identifier.

When comparing versions for compatibility, non-empty prerelease strings only match one another if they are exactly equal. See std.package.SemverReq for more details

`structured.SemverPrefix`

A contract for semantic version ("semver") prefixes, structured as a record.

`structured.SemverPrefix.major | number.Nat`

The major version number.

`structured.SemverPrefix.minor | number.Nat`

The minor version number.

`structured.SemverPrefix.patch | number.Nat`

The patch version.