Py-nickel

=========================

Nickel 1.10 includes various bug fixes and quality of life improvements. Nickel
now comes with more prebuilt binary packages (adding Windows and arm-based
MacOS), is now built with LTO (Link-Time Optimization), and comes with official
python bindings to be published on PyPI together with this release.

Under the hood, a lot of work has been devoted to internal refactorings in order
to prepare the implementation of a bytecode compiler and virtual machine
(RFC007). Those changes shouldn't have any noticeable effects currently for
users.

Breaking changes
----------------

* Record freezing ([2113](https://github.com/tweag/nickel/pull/2113),
[2131](https://github.com/tweag/nickel/pull/2131)). To fix an unsound and
unexpected behavior appearing when first altering a record with dictionary
operations (`std.record.remove`, `std.record.insert` or `std.record.update` -
see [1877](https://github.com/tweag/nickel/issues/1877) and then overriding it,
the aforementioned stdlib operations now **freeze** the returned record,
which removes the possibility of performing further recursive overriding.

Typically, the record returned by one of those operations is a static
dictionary instead of a record with recursive dependencies. While you can
still override specific fields through merging, the information about internal
dependencies is lost and their reverse dependencies won't be updated
automatically.

Documentation
-------------

* Mention any_of as alternative to enum by yannham in [2119](https://github.com/tweag/nickel/pull/2119)
* Link to the CLI chapter in the manual intro by yannham in [2144](https://github.com/tweag/nickel/pull/2144)

Stdlib
------

* Add the package std module by jneem in [2104](https://github.com/tweag/nickel/pull/2104)
* Fix empty capture groups in regexes by jneem in [2109](https://github.com/tweag/nickel/pull/2109)
* Add `filter_map`, `dedup` and some variants to the stdlib by yannham in [2120](https://github.com/tweag/nickel/pull/2120)

LSP
---

* Fix crash in NLS by jneem in [2093](https://github.com/tweag/nickel/pull/2093)
* Fix NLS crash when typechecking parse errors by jneem in [2154](https://github.com/tweag/nickel/pull/2154)

Tooling
-------

* Add support for packages to nickel-lang-core by jneem in [2094](https://github.com/tweag/nickel/pull/2094)
* Add support warnings by jneem in [2086](https://github.com/tweag/nickel/pull/2086)
* Fixed `Debug` impl of `EvalOrDeserError` printing entire source of files by rben01 in [2118](https://github.com/tweag/nickel/pull/2118)
* Do deep eval for doctests by jneem in [2110](https://github.com/tweag/nickel/pull/2110)
* pass thru feature `nix-experimental` by KiaraGrouwstra in [2132](https://github.com/tweag/nickel/pull/2132)
* Add github action for packaging and publishing python packages to PyPI (1592) by vlcek in [2126](https://github.com/tweag/nickel/pull/2126)
* Include a release artifact for nls by jneem in [2139](https://github.com/tweag/nickel/pull/2139)
* Update rustyline to 15.0 by neuschaefer in [2142](https://github.com/tweag/nickel/pull/2142)
* Add LTO to static builds by jneem in [2147](https://github.com/tweag/nickel/pull/2147)
* Add import_paths parameter to Python bindings by yannham in [2157](https://github.com/tweag/nickel/pull/2157)

========================

Nickel 1.9 includes various bug fixes and quality of life improvements.

Noteworthy additions are:

- let-blocks: declaring several variables at once instead of chaining
`let ... in ...`
- explicit import: the ability to specify explicitly the format of an imported
file (it was based on the file extension implicitly and would default
to Nickel), e.g. as `import "foo.txt" as 'Json` or `import "bar.ncl" as
'Text`.
- the addition of a `nickel test` command that can extract snippets from the
in-code documentation (the `| doc` metadata) together with their expected
result and run them. The feature is detailed in a new CLI chapter of the user
manual.

Two important future evolutions have been designed and discussed through RFCs:
package management and a performant bytecode virtual machine. Those features
aren't implemented yet, but the initial designs have been agreed upon.

Breaking changes
----------------

* Formatting: the formatting of let bindings has been fixed and improved. To
avoid a large, irrelevant diff on your next commits, we advise formatting your
whole codebase first after upgrading to 1.9 in a separate commit.

Core language
-------------

* Let blocks by jneem ([2010](https://github.com/tweag/nickel/pull/2010),
[2031](https://github.com/tweag/nickel/pull/2031),
[2051](https://github.com/tweag/nickel/pull/2051))
* Fix unsound record contract deduplication by yannham in https://github.com/tweag/nickel/pull/2042
* Explicit import format: `import "sample.html" as 'Text` by vi
([2036](https://github.com/tweag/nickel/pull/2036),
[2070](https://github.com/tweag/nickel/pull/2070))
* Thunks for resolved imports (detect import infinite loops and avoid work duplication) by jneem in https://github.com/tweag/nickel/pull/2052
* Use a persistent vector to represent arrays instead of an `Rc<[..]>` by jneem in [2057](https://github.com/tweag/nickel/pull/2057

Documentation
-------------

* Add a manual chapter for the cli. by jneem in https://github.com/tweag/nickel/pull/2065
* [RFC006] Package management by jneem in https://github.com/tweag/nickel/pull/1983
* [RFC007] Bytecode interpreter by yannham in https://github.com/tweag/nickel/pull/2045

LSP
---

* Remove the option for an external formatter in nls by jneem in https://github.com/tweag/nickel/pull/2064
* Fix completions in incomplete field name position. by jneem in https://github.com/tweag/nickel/pull/2069
* Bound the length of nls completions by jneem in https://github.com/tweag/nickel/pull/2073

Tooling
-------

* Add `--format` argument to `nickel query` command by suimong in https://github.com/tweag/nickel/pull/2015
* Adds a `nickel test` subcommand for testing examples in docs. by jneem in https://github.com/tweag/nickel/pull/2020
* Detect infinite recursions in `nickel doc` by yannham in https://github.com/tweag/nickel/pull/2055
* Strict typechecking mode by jneem in https://github.com/tweag/nickel/pull/2077
* Switch to toml-edit for spanned deserialization fixing TOML deserialization bug by jneem in https://github.com/tweag/nickel/pull/2074
* Make serde-wasm-bindgen optional in core by akavel in https://github.com/tweag/nickel/pull/2089
* Move 'clap' crate dependency behind feature flag in core by akavel in https://github.com/tweag/nickel/pull/2090

========================

After a summer break, the team is happy to release Nickel 1.8!

This release ships with an important rework of the contract system, and in
particular the interface of custom contracts. The new system is more intuitive
for users implementing their own contracts, and makes it possible to use a
limited form of boolean logic on contracts that have been added to the stdlib
(`std.contract.one_of`, `std.contract.all_of`, `std.contract.not`,
`std.contract.check`).

We advise reading the updated manual section on writing custom contracts and to
migrate your custom contracts to take advantage of the simplification of the
interface and those new operators. A lot of custom contract can most likely be
implemented as validators (see `std.contract.from_validator`).

The contract system rework is backward compatible and existing custom contracts
will continue to work as before. Though in the future, Nickel will probably emit
a warning of deprecation when a custom contract is defined as a naked function
instead of using one of the new contract constructor.

A limited form of subtyping has been added in 1.8 as well, making it easier to
use records as dictionaries in statically typed code. A new paragraph has been
added to the typing chapter of the manual accordingly.

Breaking changes
----------------

* Formatting: to better accommodate the new contract system, the formatting of
function applications and definitions have been changed. To avoid a large,
irrelevant diff on your next commits, we advise formatting your whole
codebase first after upgrading to 1.8 in a separate commit.

Core language
-------------

* Contract system rework:
* Do not evaluate types away by yannham in https://github.com/tweag/nickel/pull/1954
* Add a contract node to the AST by yannham in https://github.com/tweag/nickel/pull/1955
* Add dedicated node and constructor for general custom contracts by yannham in https://github.com/tweag/nickel/pull/1964
* Introduce validators for building custom contracts by yannham in https://github.com/tweag/nickel/pull/1970
* Split contracts into an immediate part and a delayed part by yannham in https://github.com/tweag/nickel/pull/1975
* Re-introduce unified representation for custom contracts, migrate builtin contracts by yannham in https://github.com/tweag/nickel/pull/1987
* Allow some function equality comparison by yannham in https://github.com/tweag/nickel/pull/1978
* Dictionary subtyping:
* Add a subsumption rule between record types and dictionary types by Eckaos in https://github.com/tweag/nickel/pull/1977
* Add array constructor to subsumption rule by Eckaos in https://github.com/tweag/nickel/pull/1991
* Add dictionary constructor to subsumption rule by Eckaos in https://github.com/tweag/nickel/pull/1998
* Add record constructor to subtyping by Eckaos in https://github.com/tweag/nickel/pull/2007
* Add record/split_pair and record/disjoint_merge by yannham in https://github.com/tweag/nickel/pull/1982
* Optimize `std.contract.Equal` using %record/split_pair% by yannham in https://github.com/tweag/nickel/pull/1988
* [Optimization] Cache contract generation and pre-compile some match expression by yannham in https://github.com/tweag/nickel/pull/2013
* Fix and improve contract generation optimization for static types by yannham in https://github.com/tweag/nickel/pull/2017

Stdlib
------

* Comparisons for number, string, array, and record by jeremyschlatter in https://github.com/tweag/nickel/pull/1985
* Add boolean contract combinators to the stdlib by yannham in https://github.com/tweag/nickel/pull/1995
* Add short-circuiting fold_left by jneem in https://github.com/tweag/nickel/pull/2000
* Add trigonometric functions, pi, e and log to the number module by Hugal31 in https://github.com/tweag/nickel/pull/2006

Documentation
-------------

* Pass on the contract chapter of the manual by yannham in https://github.com/tweag/nickel/pull/1999
* Adding documentation for subtyping by Eckaos in https://github.com/tweag/nickel/pull/1990

LSP
---

* Combine metadata for completion items instead of choosing arbitrarily. by jneem in https://github.com/tweag/nickel/pull/1940
* Don't blacklist files forever by thufschmitt in https://github.com/tweag/nickel/pull/1973
* Make the LSP configurable by thufschmitt in https://github.com/tweag/nickel/pull/1974
* More aggressive type/contract deduplication on hover by jneem in https://github.com/tweag/nickel/pull/1984

Tooling
-------

* Add span information for TOML imports by yannham in https://github.com/tweag/nickel/pull/1949
* Update to latest topiary-queries (formatting) by yannham in https://github.com/tweag/nickel/pull/2032

========================

Nickel 1.7 ships with several extensions to pattern matching which was
introduced in Nickel 1.5 but had a number of limitations. See below for further details.

Additionally, the publication of [Topiary](https://topiary.tweag.io/) to the
crates registry makes it so that all versions of Nickel from 1.7 and onward,
however they are built, ship with `nickel format` and the language server
formatting command working out of the box without needing a separate
installation of Topiary (which was previously required when installing from
crates.io using `cargo install nickel-lang-cli` or `cargo install
nickel-lang-lsp`).

Breaking changes
----------------

* Although primitive operators are internal and aren't officially part of any
stability guarantee, some libraries sometimes need to resort to using them,
when there's no equivalent in the stdlib. Nickel 1.7 had a big primop
refactoring, amounting mostly to renaming. If you're using primops, please
look at the corresponding [pull
request](https://github.com/tweag/nickel/pull/1937)
* The behavior of destructuring has been changed to match exactly the behavior
of pattern matching. While there should be no difference on well-behaving
programs, this change makes destructuring stricter and can lead to some
programs that were running fine before 1.7 to now fail with `unmatched
pattern`. The typical example is when destructuring a record with a field
that is not present: `let {x,y, ..} = import "lib.ncl" in`. If `x` is absent
from the `lib.ncl` but is never used anywhere, this used to work fine before
1.7 (the error would only trigger upon usage of `x`) but will now fail eagerly.

If you need to fix a large codebase with long import destructuring chains
and you don't know which fields are the offending ones, one possible
technique is to open the importing file in an editor and use the `goto
definition` command of the NLS on each field of a faulty
pattern. If it works, the field is present, but if it doesn't, the field
might be faulty.

Core language
-------------

* Patterns now support constant values (`1`, `null`, `"a"`, etc.), array
patterns (`[fst, snd, ..tail]`), pattern guards (`'Foo x if std.is_number
x`), wildcard patterns (`_` placeholder) and or-patterns (`('Foo x) or ('Bar
x) or ('Baz x)`): (see the syntax section on of the manual for more details)
* Implement wildcard patterns by yannham in https://github.com/tweag/nickel/pull/1904
* Implement constant patterns by yannham in https://github.com/tweag/nickel/pull/1897
* Implement pattern guards by yannham in https://github.com/tweag/nickel/pull/1910
* Implement array patterns by yannham in https://github.com/tweag/nickel/pull/1912
* Implement or-patterns by yannham in https://github.com/tweag/nickel/pull/1916
* Uniformize destruct and pattern matching logic by yannham in https://github.com/tweag/nickel/pull/1907
* Opaque values by jneem in https://github.com/tweag/nickel/pull/1913

Stdlib
------

* Add `record.get_or` to get value from record supplying default value by olorin37 in https://github.com/tweag/nickel/pull/1920
* [Fix] Avoid `record.get_or` failing on field without definition by yannham in https://github.com/tweag/nickel/pull/1946
* Add stdlib function `array.at_or` by olorin37 in https://github.com/tweag/nickel/pull/1927
* Add `std.enum.(from/to)_tag_and_arg` and `std.enum.map` to dynamically decompose and recompose an enum by yannham in https://github.com/tweag/nickel/pull/1939

Documentation
-------------

* Fix typo in BlameError documentation by ErinvanderVeen in https://github.com/tweag/nickel/pull/1899
* Update README.md for nix profile install by cloudyluna in https://github.com/tweag/nickel/pull/1918

LSP
---

* Tell NLS about variable bindings in match statements by jneem in https://github.com/tweag/nickel/pull/1926
* Add --version support to NLS and fix feature unification issues by yannham in https://github.com/tweag/nickel/pull/1936
* Fix NLS crash and better refresh diagnostics by jneem in https://github.com/tweag/nickel/pull/1944

Tooling
-------

* Include field path in non serializable error by yannham in https://github.com/tweag/nickel/pull/1905
* Allow single input to `nickel xxx` command to be JSON, YAML or TOML as well by olorin37 in https://github.com/tweag/nickel/pull/1902
* Use Topiary's published crates over git to always enable formatting by ErinvanderVeen in https://github.com/tweag/nickel/pull/1919

========================

Nickel 1.6 is a maintenance release including several bug fixes and
improvements, in particular around the features introduced in Nickel 1.5 (enum
variants and background evaluation in the LSP).

Core language
-------------

* Extend merge to enum variants by yannham in https://github.com/tweag/nickel/pull/1862
* [Fix] Allow multiple underscore to start identifiers by yannham in https://github.com/tweag/nickel/pull/1884

Stdlib
------

* Add `std.string.find_all` by fuzzypixelz in https://github.com/tweag/nickel/pull/1870
* Add empty optional fields-aware record operator variants by yannham in https://github.com/tweag/nickel/pull/1876

Documentation
-------------

* modular-configurations.md: to_lower -> lowercase by Jasha10 in https://github.com/tweag/nickel/pull/1857
* manual/modular-configurations.md: add argument to std.string.join by Jasha10 in https://github.com/tweag/nickel/pull/1859
* manual/syntax.md: minor typo by Jasha10 in https://github.com/tweag/nickel/pull/1860

LSP
---

* Improve diagnostic location in nls by jneem in https://github.com/tweag/nickel/pull/1856
* Propagate pending array contracts in permissive_eval by jneem in https://github.com/tweag/nickel/pull/1854
* Don't leak memory in background eval by jneem in https://github.com/tweag/nickel/pull/1869
* Add a recursion limit to background evaluation by jneem in https://github.com/tweag/nickel/pull/1878
* Dedup diagnostics by jneem in https://github.com/tweag/nickel/pull/1883
* Extend the symbol range to include the rhs by jneem in https://github.com/tweag/nickel/pull/1887
* Leverage function contract information by yannham in https://github.com/tweag/nickel/pull/1888
* Fix LSP not showing type signature in untyped code by yannham in https://github.com/tweag/nickel/pull/1889

Tooling
-------

* Markdown documentation generation: do not insert line breaks by yannham in https://github.com/tweag/nickel/pull/1879
* [Fix] Nickel doc: fix missing newline in markdown output by yannham in https://github.com/tweag/nickel/pull/1880
* Fix infinite recursion in doc symbols. by jneem in https://github.com/tweag/nickel/pull/1881

Fixes
-----

* [Fix] Polymorphic field typechecking by yannham in https://github.com/tweag/nickel/pull/1872
* Force enum payloads by jneem in https://github.com/tweag/nickel/pull/1890

========================

Nickel 1.5 is a major release (albeit not literally), with new core language
features and improved LSP. In particular, Nickel 1.5 introduces:

- Full blown pattern matching. Patterns were previously restricted to
destructuring let-bindings. They can now be used within match expressions as
well (which only supported simple enum tags before).
- Enum variants. Enum variants are a new language constructs which are
enum tags with associated data (they are applied to an argument). They can
be seen as form of algebraic data types (ADT). Patterns, enum types,
typechecking and other parts of the language are extended accordingly to
support them.
- Background evaluation in the LSP. The LSP now performs evaluation of the
current document in the background to report evaluation errors directly in
your editor, and in particular contract errors.
- A new section of the manual on writing modular configurations.


Core language
-------------

* Allow metadata keywords in field position by yannham in https://github.com/tweag/nickel/pull/1768
* Support other bases than decimal for num literals by yannham in https://github.com/tweag/nickel/pull/1798

* Enum variants:
* Structural ADTs: first step by yannham in https://github.com/tweag/nickel/pull/1770
* Implement equality on ADTs by yannham in https://github.com/tweag/nickel/pull/1787
* Fix laziness closurization bug, add support for ADTs by yannham in https://github.com/tweag/nickel/pull/1789
* ADT destructuring by yannham in https://github.com/tweag/nickel/pull/1812
* Enum tag destructuring by yannham in https://github.com/tweag/nickel/pull/1813
* Implement ADT contracts by yannham in https://github.com/tweag/nickel/pull/1821
* Introduce application syntax for ADTs by yannham in https://github.com/tweag/nickel/pull/1825
* Relax enum row conflicts by yannham in https://github.com/tweag/nickel/pull/1831
* Properly force enum variants by yannham in https://github.com/tweag/nickel/pull/1835
* Fix enum contract stripping unwrapping variant argument by yannham in https://github.com/tweag/nickel/pull/1833

* Pattern matching:
* [Refactor] Pattern matching by yannham in https://github.com/tweag/nickel/pull/1799
* Record pattern compilation by yannham in https://github.com/tweag/nickel/pull/1816
* Enum pattern compilation by yannham in https://github.com/tweag/nickel/pull/1817
* [Refactor] Pattern positions by yannham in https://github.com/tweag/nickel/pull/1819
* Full pattern matching by yannham in https://github.com/tweag/nickel/pull/1820
* Support pattern contracts in match statement by yannham in https://github.com/tweag/nickel/pull/1823
* Fix the semantics of default values in patterns by yannham in https://github.com/tweag/nickel/pull/1826
* Specialized pattern compilation for enum tags by yannham in https://github.com/tweag/nickel/pull/1846

Stdlib
------

* Add `array.zip_with` and `array.map_with_index` to the standard library by vkleen in https://github.com/tweag/nickel/pull/1797
* fixed std.array.split_at behavior at right boundary. by suimong in https://github.com/tweag/nickel/pull/1803
* Update stdlib for ADTs by yannham in https://github.com/tweag/nickel/pull/1822

Tooling
-------

* LSP: Add "goto definition" support for the import term by jneem in https://github.com/tweag/nickel/pull/1756
* LSP: Add support for NICKEL_IMPORT_PATH environment variable jneem in https://github.com/tweag/nickel/pull/1795
* LSP: Improved reference-finding by jneem in https://github.com/tweag/nickel/pull/1800
* LSP: rename action by jneem in https://github.com/tweag/nickel/pull/1811
* LSP: evaluation in the background by jneem in https://github.com/tweag/nickel/pull/1814
* LSP: Improve document symbols by jneem in https://github.com/tweag/nickel/pull/1848
* Add more spacing to contract error messages by yannham in https://github.com/tweag/nickel/pull/1767
* Proper error message for non exhaustive match by yannham in https://github.com/tweag/nickel/pull/1772
* Add InvalidContractError by yannham in https://github.com/tweag/nickel/pull/1824

Documentation
-------------

* Add patterns to the syntax section of the manual by yannham in https://github.com/tweag/nickel/pull/1832
* Improve the description of identifier syntax in the manual by vkleen in https://github.com/tweag/nickel/pull/1839
* Add subsection on enum types in the manual by yannham in https://github.com/tweag/nickel/pull/1836
* Fix old CLI syntax in documentation by cydparser in https://github.com/tweag/nickel/pull/1844
* Add manual section on modular configurations by yannham in https://github.com/tweag/nickel/pull/1841
* Update/refresh examples using latest Nickel idioms by yannham in https://github.com/tweag/nickel/pull/1849

Fixes
-----

* Check if stderr is a terminal for error messages by vkleen in https://github.com/tweag/nickel/pull/1766
* correctly drop Array::IntoIter by Radvendii in https://github.com/tweag/nickel/pull/1773
* LSP: vendor codespan, and fix character offset issues by jneem in https://github.com/tweag/nickel/pull/1793
* [Fix & Refactor] Row conflict error by yannham in https://github.com/tweag/nickel/pull/1808
* Fix unbound identifier when querying in REPL by yannham in https://github.com/tweag/nickel/pull/1843
* Fix --field not applying pending contracts by yannham in https://github.com/tweag/nickel/pull/1778