Home / Learn / 19 Editions

Release v0.4.0Edition 0.1, 0.2, 0.3, 0.4

19.1 An edition is part of the package

Page 2 of 11

19.1.1 What an edition is

A board game sold for many years often comes in editions. The second edition adds new cards and fixes a rule that players found unfair, and the box says which edition it is. Friends who own the first edition still play by its rules, and their game still works; nobody comes to their house to change the cards.

Una works the same way, with two words that are easy to mix up:

A keyword is a word the language keeps for itself, such as if, for or uses: it starts a piece of syntax, so it cannot name a value, a parameter or a field. A construct is one form of code with its own syntax and meaning, such as a for loop, a kind or a uses clause.

Each package names its edition in una.toml, and a release checks each package by the rules of the edition it names. One release serves several editions at once, so installing a newer release does not change the language your packages are written in. Only you change that, by editing one line.

Each example of this chapter is a package, made as chapter 2 explains, and the chapter's download, 19-editions.tar.gz, holds them all.

19.1.2 Why a language needs editions

Here is a small package in edition 0.1. It counts how many units arrived on a shelf, and names its parameters old and new:

steps/01-arrived/una.tomltoml
[package]
name = "restock"
version = "0.1.0"
edition = "0.1"

[run]
entry = "restock"
grants = ["console"]
steps/01-arrived/src/restock.unacheckrununa
module restock

--- How many units arrived: the count `new` on the shelf now, less the count `old` from before.
arrived(old: Int, new: Int) -> Int = new - old

pub main() -> Unit
  uses @console: Console[print]
=
  @console.print("{arrived(4, new: 10)} units arrived")
Output
6 units arrived

In edition 0.1, old is an ordinary word. Edition 0.2 made it a keyword: inside an ensures clause, old(x) names the value an edit parameter had when the call began (chapter 5). Check the same code under edition 0.2, with only the edition line changed:

una.tomldiff
--- a/una.toml
+++ b/una.toml
@@ -1,7 +1,7 @@
 [package]
 name = "restock"
 version = "0.1.0"
-edition = "0.1"
+edition = "0.2"
 
 [run]
 entry = "restock"
Diagnostic
[U0101] Error: `old` is a reserved keyword, so it cannot name a binding
   ╭─[ src/restock.una:4:9 ]
   │
 4 │ arrived(old: Int, new: Int) -> Int = new - old
   │         ─┬─
   │          ╰─── `old` is a reserved keyword, so it cannot name a binding
   │
   │ Help: repair 1: choose another name, such as `old_value`
   │
   │ Note: run `una explain U0101` for an explanation
───╯

U0101: a keyword cannot name a binding. The code did not change; the language did. In a language without editions, that would happen to this package on the day una was upgraded, whether or not anyone was ready.

With editions, nothing happens to it. The package says edition = "0.1", and every release that serves edition 0.1 checks it by the rules of 0.1, where old is a name. It moves to 0.2 only when someone changes that line, and section 19.4 shows how.

19.1.3 How to write the edition

[package] edition names the edition, as a text in quotes. It is a required key of una.toml, with name and version.

19.1.3.1 edition = "0.1", "0.2" or "0.3"

Each of the three editions is written the same way:

Edition 0.4, also a preview, is not written in una.toml: a package of edition 0.4 describes itself in a file of its own, ita.una (section 19.5), so edition = "0.4" in una.toml is U7002, whose message says to run una migrate. Edition 0.5, a later preview, is described in ita.una too; this book does not use it yet.

19.1.3.2 An edition una does not know

An edition this release does not serve is U7002, the code for a problem in una.toml:

una.tomldiff
--- a/una.toml
+++ b/una.toml
@@ -1,7 +1,7 @@
 [package]
 name = "restock"
 version = "0.1.0"
-edition = "0.1"
+edition = "0.9"
 
 [run]
 entry = "restock"
Diagnostic
[U7002] Error: edition `0.9` is not supported; the editions are "0.1", "0.2", "0.3", "0.4" and "0.5"
   ╭─[ una.toml:4:11 ]
   │
 4 │ edition = "0.9"
   │           ──┬──
   │             ╰──── edition `0.9` is not supported; the editions are "0.1", "0.2", "0.3", "0.4" and "0.5"
   │
   │ Note: run `una explain U7002` for an explanation
───╯

The mark is on the value, and the message lists the editions this release serves, 0.4 and 0.5 included.

19.1.3.3 A manifest without an edition

Leaving the line out is U7002 too, at the [package] table that lacks it:

Diagnostic
[U7002] Error: [package] has no `edition`
   ╭─[ una.toml:1:2 ]
   │
 1 │ [package]
   │  ───┬───
   │     ╰───── [package] has no `edition`
   │
   │ Note: run `una explain U7002` for an explanation
───╯

A package has no default edition: its manifest must state one.

19.1.3.4 A single file

A single .una file checked on its own, outside a package, as in una check shelf.una, has no una.toml. It has edition 0.1.

19.1.4 A stock list in edition 0.1

This step is a stock list in edition 0.1. It has a record kind, a function and a list, and its total is computed with fold (chapter 10), since edition 0.1 has no loops:

steps/05-edition-0-1/una.tomltoml
[package]
name = "shelf"
version = "0.1.0"
edition = "0.1"

[run]
entry = "shelf"
grants = ["console"]
steps/05-edition-0-1/src/shelf.unacheckrununa
module shelf

--- A line of a stock list: a SKU and the units on hand.
kind Line
  sku: Text
  units: Int

--- The units of every line, added up.
total(lines: List[Line]) -> Int = lines.fold(initial: 0, step: fn(sum, line) -> sum + line.units)

pub main() -> Unit
  uses @console: Console[print]
=
  let lines = [Line(sku: "LAMP-01", units: 4), Line(sku: "DESK-02", units: 1)]
  @console.print("{lines.len} lines, {total(lines)} units")

una run . prints:

Output
2 lines, 5 units

19.1.5 How editions behave

19.1.5.1 One binary serves every edition

una --version prints the version of una, the editions it serves, which of them are previews, and the version of Z3 built into it. At this release it lists the editions 0.1 to 0.5, of which 0.3, 0.4 and 0.5 are previews. Every one of them is checked by the same binary, so one machine can check, test and build packages of different editions side by side.

19.1.5.2 Stable editions and previews

An edition is either stable or a preview:

Edition Status What it promises
0.1 Stable A later release does not change what it accepts or rejects, except to fix a soundness or security error
0.2 Stable The same promise
0.3 Preview It may still get stricter in a later release, never looser for the programs 0.2 can express
0.4 Preview It may change in a later release, never in silence: a construct that changes or leaves gives a diagnostic; described in ita.una (section 19.5)
0.5 Preview A later preview, also described in ita.una; this book does not use it yet

A package on a stable edition can stay there for as long as it likes.

Release 0.4.0 serves edition 0.4 as a preview: a later release makes it stable. Edition 0.5, also a preview, holds what comes after it.

19.1.5.3 Words reserved for later editions

Some words were set aside before the editions that use them existed. In edition 0.1, edit, take and together are reserved: not keywords yet, and not names either. Using one gives U0103, whose message names the edition that has it, written with a v, such as `edit` is reserved for v0.2 (memory model), or says a later edition for a word that no edition has yet. Reserving a word early keeps it free: no 0.1 package can use edit as a name, so no 0.1 package breaks when 0.2 makes it a keyword. old was not reserved in 0.1, which is why the package of Why a language needs editions could use it. Nor was weak, a name in 0.1 that edition 0.2 reserves for a later edition (The keywords 0.2 adds).

19.1.5.4 What an edition fixes, and what improves with every release

What an edition fixes is the language a package is written in: its keywords, its constructs, its rules and the headers of the prelude, the functions every module has without an import (chapter 3). For example, min, max and sum work on Int in edition 0.1, and a later release keeps those headers for it, while edition 0.2 makes them generic: they work on any type with the right constraint, such as Ord for min (chapter 4). What improves with every release, for every edition, is everything around the language: the wording of messages, the explanations of una explain, the repairs, the speed of the checks and the tools of chapter 18.

19.1.6 Check yourself: a word reserved for later

This package is in edition 0.1, and names a parameter take:

steps/06-take/src/shelf.unauna
module shelf

--- The units left after a customer takes `take` of `units`.
left(units: Int, take: Int) -> Int = units - take

pub main() -> Unit
  uses @console: Console[print]
=
  @console.print("{left(10, take: 3)} left")

Does it check? If not, what does una fix --dry-run . offer?

Show the answer

It does not check. take is reserved in edition 0.1, so each of its three uses is U0103; the first:

Diagnostic
[U0103] Error: `take` is reserved for v0.2 (memory model)
   ╭─[ src/shelf.una:4:18 ]
   │
 4 │ left(units: Int, take: Int) -> Int = units - take
   │                  ──┬─
   │                    ╰─── `take` is reserved for v0.2 (memory model)
   │
   │ Help: repair 1: rename it to `the_take`; edit src/shelf.una:4:18..4:22 to "the_take"
   │
   │ Note: run `una explain U0103` for an explanation

una fix --dry-run . would rename every use:

Terminal
$ una fix --dry-run .
fixed src/shelf.una:4:18 U0103 rename it to `the_take`
fixed src/shelf.una:4:46 U0103 rename it to `the_take`
fixed src/shelf.una:9:29 U0103 rename it to `the_take`

Here the rename is right, since take is meant as a name: the_take works, and a better name, such as taken, works too. When a reserved word is meant as the construct of a later edition, the rename is wrong; Letting una fix rename a keyword shows that case.

Next:19.2 What edition 0.2 adds