Home / Learn / 19 Editions
19.5 Edition 0.4, a preview
Page 6 of 11
19.5.1 What edition 0.4 is
Edition 0.4 is the edition of release 0.4.0, and a preview, as 0.3 is (section 19.3). It has every construct and rule of 0.3, and it changes one thing that every earlier edition shares: where a package describes itself.
Up to edition 0.3, a package's settings live in una.toml and its solver pin in verification.lock. From edition 0.4, they live in two files written in Una's own syntax: ita.una, the manifest, the file that names the package and its settings, and ita.lock, the lock, the file that pins what the package was checked with. Think of a library card and the stamp on a returned book: the card says who you are and what you may borrow, and the stamp records exactly what you took, so that no one has to remember it.
Edition 0.4 also adds the constructs of long-running programs and of tasks and time, and lets a package use other packages, its dependencies: in this release, packages in directories of its own, since no public registry is served yet. This section shows the move itself; the new constructs have their own pages.
19.5.2 Why the manifest moves to ita.una
A manifest decides what a program may do: which files it reads, which capabilities main is granted (chapter 12), and, from edition 0.4, which other packages it runs. So the file must mean exactly what it says. ita.una is read by the same rules as a module: two-space indentation, -- comments, and nothing that runs. It has no expressions, no conditions and no environment variables, and every line has one of a fixed set of forms, so a typo is an error, never a setting that is quietly ignored. ita.lock is written only by una, and is not edited by hand.
19.5.3 The restock list in edition 0.4
Here is the restock list of section 19.4, moved to edition 0.4. Its manifest names the package, its version and its edition in a head of three lines, then its run settings as a section:
ita restock
version 0.1.0
edition 0.4
run
entry restock
grants
consoleEach part has its place:
ita restockheads the file with the package's name, whereuna.tomlhad[package] name.versionandeditionare the next lines, indented. A version is written as it is,0.1.0, with no quotes.runholds what[run]held:entry, the module whosemainruns, andgrants, one capability per line.
The lock holds the solver pin that verification.lock held, in the same syntax:
-- Written by `una ita`; do not edit.
lock 1
solver
encoding "una-smt-1"
name "z3"
version "5.1.0"
logic "QF_UFLIA"
steps 5000000
seed 0The modules do not change their language, and una run . prints what it printed in edition 0.3:
LAMP-01: order 6
SHELF-03: enough
DESK-02: order 1
7 units to order19.5.4 Moving with una migrate
You do not write these files by hand. una migrate reads una.toml and verification.lock and writes ita.una and ita.lock for you. Run it first with --dry-run, which prints what it would write and writes nothing. In the restock list of edition 0.2, before its move to 0.3:
una migrate --dry-run .$ una migrate --dry-run .
-- ita.una
ita restock
version 0.1.0
edition 0.4
run
entry restock
grants
console
-- ita.lock
-- Written by `una ita`; do not edit.
lock 1
solver
encoding "una-smt-1"
name "z3"
version "5.1.0"
logic "QF_UFLIA"
steps 5000000
seed 0
edition 0.2 -> 0.4: 2 diagnosticsThe last line counts what the new edition reads differently. Edition 0.4 has every rule of 0.3, so these are the two diagnostics of What 0.3 reports: una migrate prints them in full, with their repairs, on the error stream. It applies none of them. The move to 0.4 is the loop of The steps of a move, with una migrate in place of the edit of the edition line:
- Run
una migrate .It writesita.unaandita.lock, removesuna.tomlandverification.lock, and prints the diagnostics of the new edition. - Run
una fix ., then repair the rest by hand, guided by each diagnostic. - Run
una test ., and compare the output ofuna run .with the output before the move.
una migrate exits with code 0 even when it prints diagnostics: they are the next steps of the move, not a failure of it.
19.5.5 What una migrate changes in the code
una migrate also rewrites each module in the canonical form of edition 0.4. That form wraps a line that is too long, which earlier editions never do, so the restock list's line of three stock lines is split:
--- a/src/restock.una
+++ b/src/restock.una
@@ -25,7 +25,9 @@
pub main() -> Unit
uses @console: Console[print]
=
- let lines = [Line(sku: "LAMP-01", units: 4), Line(sku: "SHELF-03", units: 12), Line(sku: "DESK-02", units: 9)]
+ let lines = [Line(sku: "LAMP-01", units: 4), Line(sku: "SHELF-03", units: 12),
+ Line(sku: "DESK-02", units: 9)
+ ]
for line in lines
@console.print(order_text(line))
@console.print("{total(lines)} units to order")Only white space changes: the program is the same. A module that was in canonical form in its own edition changes in no other way.
19.5.6 edition = "0.4" in una.toml
Edition 0.4 is never written in una.toml. Changing only the edition line, as for the earlier moves, is U7002 at the value, with una migrate as the way forward:
[U7002] Error: edition 0.4 is described by ita.una, not una.toml; run `una migrate`
╭─[ una.toml:4:11 ]
│
4 │ edition = "0.4"
│ ──┬──
│ ╰──── edition 0.4 is described by ita.una, not una.toml; run `una migrate`
│
│ Note: run `una explain U7002` for an explanation
───╯The package is still checked in edition 0.4, so the rest of its diagnostics show too, and una migrate keeps them for after the move.
19.5.7 How edition 0.4 behaves
- A preview. A later release may add, change or remove a construct of edition
0.4, but a program it accepted then gives the same result or a diagnostic, never a silent change. That is less than0.3promises, which only gets stricter. - One manifest. A package has
ita.unaoruna.toml, never both: a directory with both is an error, so the two can never disagree. - Only
unawrites the lock.una migrateand theuna itacommands writeita.lock;una fixanduna fmtnever editita.lock, anduna fmt ita.unarewrites the manifest in its canonical form. - Words it reserves. Edition
0.4reserves words for its new constructs, such aswithin. A name that became one is U0103, with a rename thatuna fixapplies. - Earlier editions stay. A package of
una.tomlkeeps its edition, and the sameunachecks both kinds of package side by side.
19.5.8 Check yourself: a function named within
This package of edition 0.3 names a function within:
module shelf
--- Whether `units` more fit on a shelf that has `room` free.
within(units: Int, room: Int) -> Bool = units <= room
pub main() -> Unit
uses @console: Console[print]
=
@console.print("6 on a shelf with room for 10: {within(6, room: 10)}")
@console.print("12 on a shelf with room for 10: {within(12, room: 10)}")una migrate --dry-run . ends with this line:
edition 0.3 -> 0.4: 3 diagnosticsWhy three, for one function? And what does una fix --dry-run . offer once the package is moved?
Show the answer
within is a word edition 0.4 reserves, and it appears three times: the declaration and its two calls. Each is U0103:
[U0103] Error: `within` is reserved for edition 0.4 (long-running programs)
╭─[ src/shelf.una:4:1 ]
│
4 │ within(units: Int, room: Int) -> Bool = units <= room
│ ───┬──
│ ╰──── `within` is reserved for edition 0.4 (long-running programs)
│
│ Help: repair 1: rename it to `the_within`; edit src/shelf.una:4:1..4:7 to "the_within"
│
│ Note: run `una explain U0103` for an explanationuna fix applies the three renames together, so the package checks again:
$ una fix --dry-run .
fixed src/shelf.una:4:1 U0103 rename it to `the_within`
fixed src/shelf.una:9:51 U0103 rename it to `the_within`
fixed src/shelf.una:10:52 U0103 rename it to `the_within`A name that says what the function answers, such as fits, reads better: rename it by hand instead, in all three places.