Home / Learn / 19 Editions

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

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:

steps/21-restock-0-4/ita.unacheckrununa
ita restock
  version 0.1.0
  edition 0.4

run
  entry restock
  grants
    console

Each part has its place:

The lock holds the solver pin that verification.lock held, in the same syntax:

steps/21-restock-0-4/ita.lockuna
-- 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

The modules do not change their language, and una run . prints what it printed in edition 0.3:

Output
LAMP-01: order 6
SHELF-03: enough
DESK-02: order 1
7 units to order

19.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:

sh
una migrate --dry-run .
Terminal
$ 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 diagnostics

The 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:

  1. Run una migrate . It writes ita.una and ita.lock, removes una.toml and verification.lock, and prints the diagnostics of the new edition.
  2. Run una fix ., then repair the rest by hand, guided by each diagnostic.
  3. Run una test ., and compare the output of una 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:

src/restock.unadiff
--- 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:

Diagnostic
[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

19.5.8 Check yourself: a function named within

This package of edition 0.3 names a function within:

steps/23-fits-0-3/src/shelf.unacheckrununa
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:

Output
edition 0.3 -> 0.4: 3 diagnostics

Why 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:

Diagnostic
[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 explanation

una fix applies the three renames together, so the package checks again:

Terminal
$ 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.

Next:19.6 Day-to-day: a shelf-label printer