# `NPMSemver`
[🔗](https://github.com/dannote/npm_semver/blob/v0.1.0/lib/npm_semver.ex#L1)

npm-compatible semantic versioning.

Parses and matches version ranges using npm's semver syntax:
`^1.2.3`, `~1.2.3`, `>=1.0.0 <2.0.0`, `1.x`, `1.0.0 - 2.0.0`, `||` unions.

## Examples

    iex> NPMSemver.matches?("1.2.3", "^1.0.0")
    true

    iex> NPMSemver.matches?("2.0.0", "^1.0.0")
    false

    iex> NPMSemver.matches?("1.5.0", ">=1.2.3 <2.0.0")
    true

    iex> NPMSemver.matches?("1.2.4", "~1.2.3")
    true

    iex> NPMSemver.matches?("2.1.3", "2.x.x")
    true

Test fixtures ported from [node-semver](https://github.com/npm/node-semver).

# `matches?`

```elixir
@spec matches?(String.t(), String.t(), keyword()) :: boolean()
```

Check if a version satisfies a range.

    iex> NPMSemver.matches?("1.8.1", "^1.2.3")
    true

    iex> NPMSemver.matches?("0.1.2", "^0.1")
    true

# `max_satisfying`

```elixir
@spec max_satisfying([String.t()], String.t(), keyword()) :: String.t() | nil
```

Find the highest version in a list that satisfies the range.

    iex> NPMSemver.max_satisfying(["1.0.0", "1.5.0", "2.0.0"], "^1.0.0")
    "1.5.0"

    iex> NPMSemver.max_satisfying(["0.1.0", "0.2.0"], "^1.0.0")
    nil

# `parse_range`

```elixir
@spec parse_range(
  String.t(),
  keyword()
) :: {:ok, NPMSemver.Range.t()} | :error
```

Parse a range string into a `NPMSemver.Range` struct.

    iex> {:ok, _range} = NPMSemver.parse_range("^1.2.3")

# `parse_version`

```elixir
@spec parse_version(
  String.t(),
  keyword()
) :: {:ok, NPMSemver.Version.t()} | :error
```

Parse a version string into a `NPMSemver.Version` struct.

    iex> {:ok, v} = NPMSemver.parse_version("1.2.3-beta.1")
    iex> {v.major, v.minor, v.patch, v.pre}
    {1, 2, 3, ["beta", 1]}

# `to_elixir_requirement`

```elixir
@spec to_elixir_requirement(
  String.t(),
  keyword()
) :: {:ok, String.t()} | :error
```

Convert an npm range string to a `hex_solver`-compatible Elixir requirement string.

    iex> NPMSemver.to_elixir_requirement("^1.2.3")
    {:ok, ">= 1.2.3 and < 2.0.0-0"}

    iex> NPMSemver.to_elixir_requirement("~1.2.3")
    {:ok, ">= 1.2.3 and < 1.3.0-0"}

    iex> NPMSemver.to_elixir_requirement(">=1.0.0 <2.0.0 || >=3.0.0")
    {:ok, ">= 1.0.0 and < 2.0.0 or >= 3.0.0"}

# `to_hex_constraint`

```elixir
@spec to_hex_constraint(
  String.t(),
  keyword()
) :: {:ok, HexSolver.constraint()} | :error
```

Convert an npm range string to a `HexSolver` constraint.

Returns an opaque constraint value that can be used with `HexSolver.run/4`
and returned from `HexSolver.Registry` callbacks.

    iex> {:ok, _constraint} = NPMSemver.to_hex_constraint("^1.2.3")

---

*Consult [api-reference.md](api-reference.md) for complete listing*