Home / Learn / 19 Editions
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 release is a version of the
unaprogram itself, such as una 0.4.0. You install a release, and a newer one replaces it. - An edition is a version of the Una language: its keywords, its constructs and its rules. Una 0.4.0 serves five,
0.1to0.5, and this chapter uses the first four.
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:
[package]
name = "restock"
version = "0.1.0"
edition = "0.1"
[run]
entry = "restock"
grants = ["console"]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")6 units arrivedIn 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:
--- 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"[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.1"is the first edition. It has kinds, functions, lists, contracts, capabilities and labels.edition = "0.2"is the edition of most of this tutorial. It adds loops (chapter 9), theeditandtakeparameter modes (chapter 16 teachesedit, and section 16.3take),together(chapter 15), maps and more (section 19.2).edition = "0.3"is a preview, with stricter rules and a few constructs that narrow what a program may do (section 19.3).
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:
--- 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"[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:
[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:
[package]
name = "shelf"
version = "0.1.0"
edition = "0.1"
[run]
entry = "shelf"
grants = ["console"]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:
2 lines, 5 units19.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:
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:
[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 explanationuna fix --dry-run . would rename every use:
$ 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.