Antra
/

Standardbibliothek

Antra::System

import Antra::System

Process/system utilities for Antra.

Environment access returns Result to avoid hard runtime aborts.

Überblick#

Für Systemzugriff wie Environment-Variablen und fork-basierte Child-Processes.

System.send(...) und System.receive(...) serialisieren Werte intern ueber Antra::AND. Damit koennen ueber Fork-/Process-Kanaele direkt normale Antra-Daten wie Strings, Zahlen, Arrays, Maps und Tagged Values ausgetauscht werden.

Die dabei unterstuetzten Werttypen und Grenzen entsprechen Antra::AND. Laufzeitgebundene Werte wie Process, FileHandle oder Funktionen lassen sich also auch hier bewusst nicht senden. Die Formatspezifikation steht in 31-and-format.md.

Fuer einfache fremde Zeilenprotokolle ohne AND gibt es zusaetzlich System.send_text(...) und System.receive_text(...).

Wichtige Funktionen:

  • System.pid()
  • System.ppid()
  • System.pgrp()
  • System.get_env(...)
  • System.cwd(...), System.chdir(dir)
  • System.script_dir() — Ordner des Hauptskripts, egal von wo gestartet
  • System.os(), System.arch(), System.platform() — :linux/:macos/:windows, :x86_64/:aarch64, "linux-x86_64"
  • System.version() ("dev" bei lokalen Builds), System.executable(), System.stdlib_dir()
  • System.command_path(...)
  • System.fork(...)
  • System.send(...)
  • System.receive(...)
  • System.send_text(...)
  • System.receive_text(...)

Beispiel:

import Antra::AND as AND
import Antra::Process as Process
import Antra::Result as Result
import Antra::System as System

my child = System.fork(|stdin, stdout| -> {
    my msg = System.receive(stdin).!
    Result.unwrap!(System.send(stdout, %Reply{ok: true, payload: msg}))
}).!

Result.unwrap!(System.send(child, %User{name: "Ada", tags: [:admin, :active]}))
Result.unwrap!(Process.close_input(child))
println(AND.encode(System.receive(child).!).!)
println(Process.wait(child).!)

Fuer rohe Textkommunikation ohne Datenserialisierung:

import Antra::Process as Process
import Antra::Result as Result
import Antra::System as System

my child = System.fork(|stdin, stdout| -> {
    my msg = System.receive_text(stdin).!
    Result.unwrap!(System.send_text(stdout, "raw: " <> msg))
}).!

Result.unwrap!(System.send_text(child, "hello raw"))
Result.unwrap!(Process.close_input(child))
println(System.receive_text(child).!)
println(Process.wait(child).!)

Fuer kleine Prozessdiagnosen ohne #Process<...>-Handle gibt es zusaetzlich:

import Antra::System as System

println(System.pid())
println(System.ppid())
println(System.pgrp())

Wenn du das ohne Vorwissen Schritt fuer Schritt lesen willst, siehe auch 28-process-und-fork-fuer-einsteiger.md.

Referenz#

System.get_env("HOME")
System.get_env("HOME").!
System.get_env_or("OPTIONAL_VAR", "dev")
System.has_env("HOME")
System.set_env("MODE", "test")   # %Ok[undef]; gilt auch fuer danach gestartete Prozesse
System.cwd()
System.cwd().!
System.chdir("build")   # %Ok[undef]
System.script_dir()     # %Ok[ordner des hauptskripts]
System.command_path("curl")
System.command_exists("curl")
System.os()          # :linux, :macos, :windows
System.arch()        # :x86_64, :aarch64
System.platform()    # "linux-x86_64"
System.version()     # "1.2.3" bzw. "dev"
System.executable()  # %Ok[pfad des laufenden antra]
System.stdlib_dir()  # %Ok[verzeichnis mit Antra/Prelude.ant]
System.send(process, value)
System.receive(process)
System.receive(process).!
System.send_text(process, text)
System.receive_text(process)
System.receive_text(process).!

Funktionen#

archfn</>
fn arch()

Returns a keyword: the CPU architecture (:x86_64, :aarch64, ...).

argvfn</>
fn argv()

Returns the command-line arguments passed to the script as an array of strings.

chdirfn</>
fn chdir(dir)

Changes the current working directory; returns %Ok[undef] or %Err[%Error{...}]. Relative paths are resolved against it afterwards.

import Antra::System
System.chdir("build").!
command_existsfn</>
fn command_exists(name)

Returns true if an executable can be resolved.

command_pathfn</>
fn command_path(name)

Resolves an executable path from PATH (or direct path input).

cwdfn</>
fn cwd()

Returns the current working directory as %Ok["..."] or %Err[%Error{...}].

executablefn</>
fn executable()

Returns %Ok[path] of the running antra executable, or %Err.

forkfn</>
fn fork(child_fun)

Forks the current interpreter process and runs child_fun(stdin, stdout) in the child.

The parent receives %Ok[#Process<...>] for bidirectional communication.

get_envfn</>
fn get_env(name)

Reads an environment variable.

Returns %Ok["..."] if set, otherwise %Err[%Error{...}].

get_env_orfn</>
fn get_env_or(name, default)

Reads an environment variable with a default fallback.

Returns the plain value (string) when found, otherwise default.

has_envfn</>
fn has_env(name)

Returns true when an environment variable exists.

osfn</>
fn os()

Returns a keyword: the operating system (:linux, :macos, :windows, ...).

pgrpfn</>
fn pgrp()

Returns the process group ID of the current process.

pidfn</>
fn pid()

Returns the current process ID.

platformfn</>
fn platform()

Returns a String "<os>-<arch>", e.g. "linux-x86_64" — the directory under native/ where antra native installs C libraries.

ppidfn</>
fn ppid()

Returns the parent process ID of the current process.

receivefn</>
fn receive(source)

Empfaengt einen einzelnen AND-codierten Wert von einem lesbaren Process oder FileHandle.

receive_bytesfn</>
fn receive_bytes(source)

Empfaengt eine einzelne rohe Byte-Nachricht als ByteString.

receive_textfn</>
fn receive_text(source)

Empfaengt eine einzelne rohe UTF-8-Textzeile von einem lesbaren Process oder FileHandle.

script_dirfn</>
fn script_dir()

Returns %Ok[dir]: the directory of the main script (absolute), also when it was started from somewhere else — the place to look for files that ship with the program. %Err when the program came from stdin.

import Antra::System
val sprites = System.script_dir().! <> "/resources/sprites.png"
sendfn</>
fn send(target, data)

Serialisiert einen Antra-Wert als AND und sendet ihn an ein beschreibbares Process oder FileHandle.

send_bytesfn</>
fn send_bytes(target, bytes)

Sendet eine einzelne rohe Byte-Nachricht an ein beschreibbares Process oder FileHandle.

Dafuer wird ein laengenpraefixierter Frame uebertragen, damit auch 0x00, Zeilenumbrueche oder komprimierte Daten sauber transportiert werden koennen.

send_textfn</>
fn send_text(target, text)

Sendet eine einzelne rohe UTF-8-Textzeile an ein beschreibbares Process oder FileHandle.

set_envfn</>
fn set_env(name, value)

Sets an environment variable for this process and every process it starts afterwards. Returns %Ok[undef] or %Err[%Error{...}].

Example:

System.set_env("ANTRA_RAYLIB_HIDDEN", "1").!
Process.spawn(System.executable().!, ["demo.ant"])   # sees the variable
stdlib_dirfn</>
fn stdlib_dir()

Returns %Ok[dir]: the directory holding the standard library (<dir>/Antra/Prelude.ant) this interpreter uses, or %Err.

versionfn</>
fn version()

Returns a String: the antra version ("dev" for local builds).

Quelle dieser Seite