Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-std

Source of release 0.7.0

0.7.0 / README.md

# luce-std

Luce's standard library, as a package of its own. The compiler ships only the language
runtime (memory, ownership, interop, threads, strings, I/O streams); everything else a
program imports comes from here, versioned apart from the toolchain. It is written in Luce
Base and serves Luce and Base programs alike.

## Modules

| import | what it holds |
| --- | --- |
| `from luce_std import files` | Files and directories: whole-file text and bytes, `File` objects, listings, walks, metadata, copying, renaming, temporary directories |
| `from luce_std import paths` | Lexical filesystem paths: join, normalize, split |
| `from luce_std import process` | Running programs (`run`, background `Command`), environment variables, the working directory |
| `from luce_std import net` | TCP connections and listeners by host name, name lookup, UDP; HTTP and WebSocket wire formats for Base; for event loops, connects that do not wait (`Connection.start_connect`, `finish_connect`) and name lookups on a thread of their own (`Lookup`) |
| `from luce_std import clock` | The monotonic clock, durations, sleeping, calendar dates and ISO 8601 |
| `from luce_std import random` | A seeded pseudo-random generator |
| `from luce_std import math` | The mathematical functions |
| `from luce_std import math32` | Single-precision mathematical functions |
| `from luce_std import unicode` | Unicode 17.0.0 casing and normalization |
| `from luce_std import utf8` | Strict UTF-8 scalar encoding and decoding |
| `from luce_std import collections` | Growable storage for Base: `List[T]`, a byte `Buffer`, and a `TextPool` of copies that never move |
| `from luce_std import crash` | Crash reports in `~/.luce/crashes`, named after the program's package; hooks that save work after a trap (`on_crash`, `recovery_directory`, `note_recovery`); starting the program again to show its report (`relaunch_on_crash`, `report_to_show`), which luce-ui's crash window uses. Nothing is sent anywhere |

## Using it

Add the dependency with `luc add dymokomi/luce-std`, or in `package.prisma`:

```prisma
def dependency "luce-std" {
    str owner = "dymokomi"
    str version = "^0.4.0"
}
```

From Luce, the modules read like Python's:

```luce
from luce_std import files, clock

pub func main(arguments: list[str]) -> int!:
    let start = clock.now()
    with files.open("notes.txt") as notes:
        while let line = notes.read_line():
            print(line)
    print(f"read in {start.elapsed().seconds()} s at {clock.DateTime.now().text()}")
    return 0
```

[The standard library](https://luce.luciaos.com/guide/standard-library/) chapter of
the Luce guide describes what Luce programs call. A Luce program sees the functions,
structs and objects whose signatures cross the Base boundary; the rest is for Base.

## From Base

Functions that answer fresh storage, such as `files.read`, `files.list`, `paths.join`,
`process.run` or `unicode.to_upper`, answer an `interop.Owned[...]` result. Luce copies the
value and releases it. A Base caller reads `.value` and releases the result when done:

```lucb
let names = try files.list("notes")
defer names.release()
for name in names.value:
    print(name)
```

The storage comes from the allocator current at the call; texts are NUL-terminated, so they
may be passed on as `c.str`. Objects Luce holds (`files.File`, `files.TemporaryDirectory`,
`net.Connection`, `net.Listener`, `process.Command`) remain ordinary values in Base.

### Growable storage

`collections` is for Base only; Luce has its own `list` and `bytes`. A zero value of each
type is empty and ready. The first growth takes the current allocator and keeps it, as
`strings.Builder` does; `destroy` gives the storage back, after which the value may be used
again.

```lucb
from luce_std import collections

var rows: collections.List[Row]
defer rows.destroy()
try rows.append(Row(id = 1))
try rows.insert(0, Row(id = 0))
rows.remove(1)                      # keeps the order of the rest; remove(index, count) for a run
for row in rows.view(): ...         # const Row[]; rows.items() is a Row[] to change or sort

var line: collections.Buffer        # an io.Writer
defer line.destroy()
try line.put_text("total ")
try line.put_number(42)
try strings.write_f64(&line, 2.5, ".2f")
print(line.text())                  # the bytes as far as they are valid UTF-8
let path = try line.terminated()    # a c.str, valid until the next change

var pool: collections.TextPool      # copies stay where they are until pool.destroy()
let name = try pool.keep_text(column_bytes)
```

- `List[T]`: `length`, `capacity`, `reserve`, `append`, `insert`, `remove(index, count = 1)`,
  `truncate`, `at`, `set`, `view`, `items`, `clear`, `destroy`. The capacity at least
  doubles when it grows, so `view` and `items` are valid until the next `append`, `insert`
  or `reserve`. An index out of range traps, as indexing a span does.
- `Buffer`: `put`, `put_text`, `put_byte`, `put_number`, `write` (io.Writer), `remove`,
  `truncate`, `view`, `text`, `terminated`, `length`, `reserve`, `clear`, `destroy`.
- `TextPool`: `keep(bytes)`, `keep_text(bytes)` (cut where the bytes stop being valid UTF-8),
  `destroy`. Copies go into 64 KiB chunks; a larger one gets a chunk of its own.

## Depends on

- luce-base compiler (the runtime modules)

## Platforms

macOS, Windows, Linux.

Native libraries it links, by platform (declared in `package.prisma`, linked only when the
program reaches code that needs them):

- windows: ws2_32

## Tests

`./test.sh` runs every module's `test` blocks and the unit tests through the native and C
backends, then the program checks under `tests/programs`. It expects the compiler beside
this checkout at `../luce-base/build/luce-base` (or `--base PATH`). When a Luce compiler is
at hand (`LUCE`, or `../luce/build/luce`), it also builds the Luce programs under
`tests/luce` against this checkout: each must print its expected output and leave no object
alive. `tests/luce/run.py --leaks` also runs them under macOS's `leaks`.

## License

MIT or Apache-2.0, at your option.