Pakete und Built-ins

println(str(42))
println(len("hello"))
println(map([1, 2, 3], |x| -> x * 2))

my key = keyword("verbose")
my opts = map_assoc(%{}, key, true)

println(opts.verbose)
println(opts[key])

import Antra::Value as Value

println(type(42))
println(type(|x| -> x))
println(type(Value.tagged_map("User", %{name: "Ada"})))
println(Value.tag(Value.tagged_map("User", %{name: "Ada"})))

import Antra::IO::File as File
import Antra::Result as Result

my fh = File.open("out.txt", [mode: [:write, :create, :truncate]]).!
println("hello", [to: fh])
Result.unwrap!(File.close(fh))

my user = %User{name: "Ada", age: 36}
dd(user)

val xs = [1, "a"]
val n = dbg(len(xs), "n") + 1   # stderr: [line 2] n = 2
xs |> dbg() |> len              # stderr: [line 3] [1, 'a']

package Demo {
    pub fn greet(name) -> "Hello " <> name
}

import Demo
import Demo as D

chess-tools/
    src/
        main.ant
    lib/
        Chess/
            Board.ant
            PGN.ant

antra -I lib src/main.ant

antra -I lib main.ant

import Chess::Board
import Chess::PGN

antra -I lib -I vendor/lib src/main.ant

ANTRA_LIB=lib:vendor/lib antra src/main.ant

package Build {
    our next_build = 1000       # privat, kein pub
}

Build.next_build                # Fehler: 'next_build' is private to package 'Build'
Build.nope                      # Fehler: package 'Build' has no member 'nope'

package Counter {
    pub our total = 0

    pub fn inc() -> {
        total = total + 1
    }
}

Counter.inc()
Counter.total = 10
println(Counter.total)

package Counter {
    pub our total = 0
    pub our total = 1   # Fehler: gleicher Package-Scope
}

#: Liest eine Datei.
@deprecated("Use read_text")
pub fn read(path) -> "..."

`pub` und Namen mit `_` am Anfang bleiben draußen, mehrere Klauseln einer
Funktion stehen untereinander.

```antra
#: Liest die Konfiguration.
#:
#: ```antra
#: Config.load("app.and").!   # => %{port: 8080}
#: ```
pub fn load(path :- String) :- Result[Map, String] -> %Ok[%{port: 8080}]
```

```sh
antra doc                       # docs/ und lib/ -> zig-out/doc/
antra doc --out site            # anderer Zielordner
antra doc --docs handbuch --lib src
```

Neben der API nimmt `antra doc` die Markdown-Kapitel unter `docs/` mit: die
Gruppen und die Reihenfolge der Seitenleiste kommen aus `docs/README.md`
(`## Gruppe`, darunter verlinkte Kapitel), die Gruppen der Pakete aus
`docs/stdlib/README.md` (`### Gruppe`, darunter Zeilen mit `Antra::X`). Liegt
zu einem Paket eine Seite `docs/stdlib/X.md` (bei `Antra::Net::HTTP`:
`Net.HTTP.md`), steht ihr Text über der API. Die Seite braucht keinen Server
und lädt nichts nach: `index.html` direkt im Browser öffnen genügt.

## Die Standardbibliothek

Die Pakete unter `Antra::` sind in der [Stdlib-Referenz](stdlib/README.md)
beschrieben: eine Seite pro Paket, mit Erklärungen und der API, die `antra doc`
aus den `#:`-Kommentaren in `lib/Antra/` erzeugt.

## Praktische Lesestrategie für Bibliotheken

Wenn du ein Modul neu ansiehst, starte in dieser Reihenfolge:

1. Welche Tagged Values oder Result-Formen liefert es zurück?
2. Arbeitet es eher funktional oder mutierend?
3. Gibt es ein `!`-Pendant, das bei Fehlern wirft?
4. Ist die API eher Daten-in-Daten-raus oder Callback-orientiert?

## Empfehlung für Einsteiger

Wenn du die Sprache gerade erst lernst, reichen anfangs meist diese Module:

- `Antra::Array`
- `Antra::Result`
- `Antra::String`
- `Antra::Regex`

Die übrigen kannst du später bedarfsgesteuert dazunehmen.

## Referenz: Built-ins im Überblick

Die alte Doku hat diese Built-ins explizit hervorgehoben:

```antra
println(x)
dd(x, [pretty: true, indent: 2, colorize: false])
dbg(x, label)
head(list)
head!(list)
tail(list)
tail!(list)
concat(a, b)
len(str)
str(x)
num(x)
int(x)
rat(x)
assert(cond)
upper(str)
lower(str)
chars(str)
split(str, pattern)
map(list, fn)
filter(list, pred)
foreach(list, fn)
take(n, list)
range(start, end, step)
match(str, pattern)
test(str, pattern)
replace(str, pattern, repl)
keyword(name)
eval(code)
```

`dd(...)` ist fuer Debug-Ausgaben gedacht und gibt den ursprünglichen Wert
zurück. `print(...)`/`println(...)` liefern `undef` — wer einen Wert ausgeben
**und** weiterreichen will, nimmt `dbg`.

Wo ein String **als Literal** dargestellt wird — geschachtelt in Collections
(auch bei `println`), in `dd(...)`, und in Fehlermeldungen, die Werte zeigen —
ist die Anzeige immer round-trip-sicher als Antra-Literal. Wie bei Pythons
`repr` wird die Quote-Art gewählt, die **weniger Escaping** braucht:

```antra
dd("plain")                    # -> 'plain'
dd("er sagte \"hi\"")          # -> 'er sagte "hi"'   (hat ", also single)
dd("can't stop")               # -> "can't stop"      (hat ', also double)
println(%{name: "Ada"})        # -> %{ :name => 'Ada' }
println(%Err["expected 'c'"])  # -> %Err["expected 'c'"]  (Apostrophe → double)
```

Ein blanker Top-Level-`println("Klaus")` gibt weiterhin nur den Inhalt aus
(`Klaus`, ohne Quotes) — die Literal-Anzeige greift nur, wenn der String
geschachtelt oder von `dd` gezeigt wird. Andere Serialisierer bleiben bei
ihrer eigenen Konvention: `AND.encode`, `JSON`-Ausgabe und `HTML.render`
verwenden weiter `"..."`.

Aktuell unterstützte `dd(...)`-Optionen:

- `pretty: true|false` schaltet zwischen mehrzeiliger Strukturansicht und kompakter Ein-Zeilen-Ausgabe um
- `indent: n` setzt die Einrückung für Pretty-Ausgabe; `n` muss eine nichtnegative ganze Zahl sein
- `colorize: true|false` aktiviert ANSI-Farben in der Terminal-Ausgabe
- `show_bless: true|false` zeigt bei geblessten Werten zusätzlich das gebundene Package an
- `show_methods: true|false` zeigt bei geblessten Werten zusätzlich öffentliche Methoden an; impliziert intern dieselbe Metadaten-Sicht wie `show_bless`
- `colors: [...]` oder `colors: %{...}` überschreibt einzelne Farben der Palette

Unter `colors:` sind aktuell diese Schlüssel erlaubt:

- `punctuation`
- `tag`
- `keyword`
- `string`
- `number`
- `boolean`
- `undef`

Die Farbwerte müssen Hex-Strings wie `"#rrggbb"` sein.

Beispiel:

```antra
dd(
    value,
    [
        pretty: true,
        indent: 4,
        colorize: true,
        show_bless: true,
        show_methods: true,
        colors: [
            string: "#ffd166",
            tag: "#85bf8e"
        ]
    ]
)
```

Wichtig fuer den Aufruf:

- bei mehreren Nutzwerten liest `dd(...)` Optionen nur aus dem letzten Argument
- bei genau einem Nutzwert akzeptiert `dd(...)` zusätzlich auch direkt eine Map als Optionsargument

## Referenz: Pakete, `our` und Doku-Metadaten

Package-Variablen aus der alten Referenz:

- `our x = 10` ist intern sichtbar
- `pub our x = 10` ist intern und extern les-/schreibbar
- `pub const PI = 3` ist öffentlich, aber immutable

Dokumentationskommentare verwenden `#:` direkt über `package`, `pub fn` oder `fn`. Attribute wie `@spec`, `@deprecated` oder `@title` werden als Metadaten gespeichert und können über `Antra::Meta` ausgelesen werden.