std:env — 環境変数

標準ライブラリモジュール (index.md)。本書中の裸の §N は本書の節を指す。言語の意味論は ../language-spec.md を参照。

import env := "std:env" は get / get_or / args の 3 slot を持つ namespace object を env に束縛する。対象はプロセスの環境変数とプログラム起動引数。読み取り専用 — 書き込み (set / unset) は副作用が大きく決定性を損なうため持たない。

環境変数とプログラム引数を同じモジュールに同居させるのは、どちらもプロセス起動時にホストから渡される入力であり、読むのに要る権限も同じだからである。

import { get, get_or, args } := "std:env"

外部リソース (プロセス環境・起動引数) に触れるため、この import 自体が capability 宣言になる (index.md)。

1. env.get

• 引数: name (String) 1 個
• 同期 (Future ではない)。戻り値は Option(String):
• 設定済み: Some(value) — value は環境変数の文字列 (空文字列に設定されていれば Some(""))
• 未設定: None
• 存在と空文字列を区別する (空文字列に設定された変数は Some("") であって None ではない)。
• 値が UTF-8 として読めないときも None — Hikari の String は UTF-8 (../language-spec.md §7.2.1) なので、読めないバイト列を String として渡さない。設定されていること自体はそこで見えなくなる。
• name が String でないときは呼び出し位置の panic 型エラー (回復可能エラーではない。path 系と同規律)。

match get("HOME") {
  Some(dir) => print("home: ${dir}")
  None => print("HOME unset")
}

2. env.get_or

• 引数: name (String), default (String) の 2 個
• 同期。戻り値は String:
• 設定済み: 環境変数の値
• 未設定、または値が UTF-8 として読めない (§1): default
• name / default が String でないときは呼び出し位置の panic 型エラー。

data_dir := get_or("XDG_DATA_HOME", "/home/u/.local/share")

get_or(name, default) は match env.get(name) { Some(v) => v None => default } と等価な糖衣。

3. env.args

• 引数: なし
• 同期。戻り値は List(String) — entry スクリプトのパスより後ろに与えられた起動引数列。スクリプト名自体は含まない。
• hikari <script.hika> a b c で起動したとき args() は ["a", "b", "c"] を返す。引数が無ければ空リスト []。
• 呼び出しのたびに新しい List を返す (要素は immutable な String)。
• hikari 自身のフラグは entry に渡る前に CLI が取り除くため args() には現れない (hikari-command.md §5)。
• args() は引数列をそのまま返し、フラグの解釈はしない。option / flag と位置引数への解析は cli.md が担う。

match args() {
  [] => print("no args")
  _ => args().each { a | print(a) }
}