env

Expose process-level metadata to CX code: environment variables, command-line arguments, and process identity. Read, list, and typed-default environment variables; parse argv into declarative flags and positionals; query process metadata such as PID, executable path, cwd, hostname, and OS/arch; reach the standard stream handles; and terminate the process. The environment is read-only from CX code — there are no setters. This is a Tier B runtime surface and is necessarily impure.

env:var

[$env:var] -> [or string [sequence string]] — Read an environment variable, signaling absence (the empty sequence) when it is unset.

            [?lib 'cx-stdlib/env']
[$env:var "CX_DEFINITELY_UNSET_VAR_XYZ_001"]

            cx-err:CXER0271

env:vars

[$env:vars] -> map — Return all environment variables as a name-to-value map.

            [?lib 'cx-stdlib/env']
[= [$env:vars] [$env:vars]]

            cx-err:CXER0271

env:has-var

[$env:has-var] -> bool — Report whether a variable is set, distinguishing set-to-empty from unset.

            [?lib 'cx-stdlib/env']
[$env:has-var "CX_DEFINITELY_UNSET_VAR_XYZ_002"]

            cx-err:CXER0271

env:var-or-default

[$env:var-or-default] -> string — Read a variable, returning the supplied default when it is unset.

            [?lib 'cx-stdlib/env']
[$env:var-or-default "CX_DEFINITELY_UNSET_VAR_XYZ_003" "fallback"]

            cx-err:CXER0271

env:var-int

[$env:var-int] -> int — Read a variable as an int, returning the default if unset or raising if set-but-unparseable.

            [?lib 'cx-stdlib/env']
[$env:var-int "CX_DEFINITELY_UNSET_VAR_XYZ_004" 8080]

            cx-err:CXER0271

env:var-float

[$env:var-float] -> float — Read a variable as a float, returning the default if unset or raising if set-but-unparseable.

            [?lib 'cx-stdlib/env']
[$env:var-float "CX_DEFINITELY_UNSET_VAR_XYZ_005" 2.5]

            cx-err:CXER0271

env:var-bool

[$env:var-bool] -> bool — Read a variable as a bool (true/false/1/0/yes/no/on/off), returning the default if unset.

            [?lib 'cx-stdlib/env']
[$env:var-bool "CX_DEFINITELY_UNSET_VAR_XYZ_006" true]

            cx-err:CXER0271

env:var-required

[$env:var-required] -> string — Read a variable, raising a fault if it is unset.

            [?lib 'cx-stdlib/env']
[$env:var-required "CX_DEFINITELY_UNSET_VAR_XYZ_007"]

            cx-err:CXER0271

env:argv

[$env:argv] -> [sequence string] — Return the raw command-line argument vector, with argv[0] as the executable path.

            [?lib 'cx-stdlib/env']
[= [$env:argv] [$env:argv]]

            true

env:parse-args

[$env:parse-args] -> element — Parse argv against a spec into an [args] element of flags, positionals, and unparsed extras.

            [?lib 'cx-stdlib/env']
[?let [= $spec [argspec [flag name=verbose short=v type=bool]]]
  [$env-parse-args $spec ("prog", "--nope")]]

            cx-err:CXER2501

env:flag

[$env:flag] -> any — Look up a parsed flag value by name from a parse-args result.

            [?lib 'cx-stdlib/env']
[?let [= $spec [argspec [flag name=verbose short=v type=bool] [flag name=limit short=n type=int default=100]]]
  [= $parsed [$env-parse-args $spec ("prog", "--verbose", "--limit", "10")]]
  [$env:flag $parsed "verbose"]]

            true

env:positional

[$env:positional] -> string — Look up a parsed positional argument by name from a parse-args result.

            [?lib 'cx-stdlib/env']
[?let [= $spec [argspec [positional name=input-file type=string required=true]]]
  [= $parsed [$env-parse-args $spec ("prog", "data.cx")]]
  [$env:positional $parsed "input-file"]]

            'data.cx'

env:remaining

[$env:remaining] -> [sequence string] — Return the leftover arguments not consumed by declared flags or positionals.

            [?lib 'cx-stdlib/env']
[?let [= $spec [argspec [positional name=first type=string]]]
  [= $parsed [$env-parse-args $spec ("prog", "a", "b", "c")]]
  [$env:remaining $parsed]]

            ('b', 'c')

env:usage

[$env:usage] -> string — Render a human-readable usage string from an argument spec, for --help or parse failures.

            [?lib 'cx-stdlib/env']
[?lib 'cx-stdlib/strings']
[?let [= $spec [argspec [flag name=verbose short=v type=bool] [positional name=input-file type=string required=true]]]
  [$strings:is-empty [$env:usage $spec]]]

            false

env:pid

[$env:pid] -> int — Return the current process ID.

            [?lib 'cx-stdlib/env']
[> [$env:pid] 0]

            true

env:ppid

[$env:ppid] -> int — Return the parent process ID.

            [?lib 'cx-stdlib/env']
[>= [$env:ppid] 0]

            true

env:executable-path

[$env:executable-path] -> string — Return the filesystem path of the running executable.

            [?lib 'cx-stdlib/env']
[?lib 'cx-stdlib/strings']
[$strings:is-empty [$env:executable-path]]

            cx-err:CXER0271

env:cwd

[$env:cwd] -> string — Return the current working directory.

            [?lib 'cx-stdlib/env']
[?lib 'cx-stdlib/strings']
[$strings:is-empty [$env:cwd]]

            cx-err:CXER0271

env:hostname

[$env:hostname] -> string — Return the host machine name.

            [?lib 'cx-stdlib/env']
[?lib 'cx-stdlib/strings']
[$strings:is-empty [$env:hostname]]

            cx-err:CXER0271

env:username

[$env:username] -> string — Return the name of the current user.

            [?lib 'cx-stdlib/env']
[?lib 'cx-stdlib/strings']
[$strings:is-empty [$env:username]]

            cx-err:CXER0271

env:os-name

[$env:os-name] -> string — Return the operating-system name, such as linux or darwin.

            [?lib 'cx-stdlib/env']
[?lib 'cx-stdlib/strings']
[$strings:is-empty [$env:os-name]]

            false

env:os-arch

[$env:os-arch] -> string — Return the CPU architecture, such as amd64 or arm64.

            [?lib 'cx-stdlib/env']
[?lib 'cx-stdlib/strings']
[$strings:is-empty [$env:os-arch]]

            false

env:cpu-count

[$env:cpu-count] -> int — Return the logical CPU count, including hyperthreads.

            [?lib 'cx-stdlib/env']
[> [$env:cpu-count] 0]

            true

env:stdin

[$env:stdin] -> element — Return the standard-input stream handle, to pass to cx-stdlib/io for I/O.

            [?lib 'cx-stdlib/env']
[$env:stdin]

            [std-stream name=stdin fd=0]

env:stdout

[$env:stdout] -> element — Return the standard-output stream handle, to pass to cx-stdlib/io for I/O.

            [?lib 'cx-stdlib/env']
[$env:stdout]

            [std-stream name=stdout fd=1]

env:stderr

[$env:stderr] -> element — Return the standard-error stream handle, to pass to cx-stdlib/io for I/O.

            [?lib 'cx-stdlib/env']
[$env:stderr]

            [std-stream name=stderr fd=2]

env:exit

[$env:exit] -> null — Flush pending I/O, run finalizers, and terminate the process with the given exit code.

            [?lib 'cx-stdlib/env']
[$env:exit 0]

            [subprocess-harness: child exits with status 0]

env:abort

[$env:abort] -> null — Terminate the process immediately without flushing; use only for unrecoverable corruption.

            [?lib 'cx-stdlib/env']
[$env:abort]

            [subprocess-harness: child terminates via abort signal]