Idio Values

There are several classes of Idio values with regards to scope and effect and provenance.

function dynamic? o

test if o is a dynamic variable

Param o:

object to test

Return:

#t if o is a dynamic variable, #f otherwise

function environ? o

test if o is an environ variable

Param o:

object to test

Return:

#t if o is an environ variable, #f otherwise

environ? is a function so quote any argument likely to be expanded by the evaluator:

environ? HOME     ; == environ? %P"/home/me"
environ? 'HOME    ; #t (or #f?)
function computed? o

test if o is a computed variable

Param o:

object to test

Return:

#t if o is a computed variable, #f otherwise

General Values

value IDIOLIB
Type:

string

IDIOLIB is the search path used by idio to find libraries and extension code.

Any non-absolute directories are ignored.

The construction of IDIOLIB is complicated but there are two things to note:

  1. idio will determine the lib directory that corresponds with the actual executable being run. This directory will be prepended to any user-supplied IDIOLIB environment variable.

  2. if you used a virtualenv-style setup (where the idio found on your PATH is a symlink to a real executable) then idio will determine the lib directory that corresponds with the virtualenv being used. This directory will be prepended to any user-supplied IDIOLIB environment variable.

In both cases, a .../lib will only be prepended if the executable/symlink name was .../bin/name, ie. the immediate directory name must be bin.

value IFS
Type:

string

Scope:

dynamic

Default:

" \t\n" (SPACE TAB NEWLINE)

IFS is the Input [1] Field Separator and is the value used by fields or the default value used by split-string to split a string into substrings.

It is not like Bash’s variable in the sense that it might recover its default value if you unset it. It’s just a regular dynamic variable.

value PID
Type:

libc/pid_t

PID is the Process ID of the current instance of idio.

This value will be updated in the child if you call libc/fork.

See also

IDIO_PID

value PPID
Type:

libc/pid_t

PPID is the parent Process ID of the current instance of idio.

This value will be updated in the child if you call libc/fork.

value RANDOM
Type:

fixnum

Computed:

RANDOM is a computed value returning a random non-negative 32-bit integer.

Setting RANDOM re-seeds the random number generator.

Rtype:

integer (irrespective of the type mentioned above)

Note

RANDOM is based on random(3) with attendant risks for use in scenarios requiring high quality randomness.

In OpenBSD, when setting RANDOM, the seed variable is ignored, and strong random number results will be provided from arc4random(3).

value SECONDS
Type:

fixnum

Computed:

SECONDS is a computed value returning the number of seconds since idio started.

There is no setter function.

Rtype:

integer (irrespective of the type mentioned above)

value TIMEFORMAT
Type:

string

Scope:

dynamic

Default:

"Real %.3R\nUser %.3U\nSyst %.3S\n"

TIMEFORMAT is a string describing the report for the time-function command (or time meta-command).

It allows for the use of three 'keyed format characters, R, U and S, for the real, user and system time, respectively. The precision given is for the fractional seconds.

value *epsilon*
Type:

bignum

Default:

1-18

*epsilon* is the machine epsilon used to truncate the calculation of infinite series.

Environment Values

All extant environment variables become environ values in idio.

If the following values do not exist in the environment at startup then they will be created as environ values as described below.

value PATH
Type:

string

Default:

any existing environment variable

If PATH is not currently set in the environment then it is set to the result of passing _CS_PATH to confstr(3) or, failing that, "/bin:/usr/bin".

value PWD
Type:

pathname

PWD is the Process Working Directory.

It assumes the value in the environment at startup (or is set to the result of libc/getcwd). It is subsequently updated by calls to cd and pushd / popd.

Warning

Calls to libc/chdir do not change PWD.

value HOME
Type:

pathname

Default:

any existing environment variable

If HOME is not currently set in the environment then it is set to the current user’s HOME directory.

value LOGNAME
Type:

string

Default:

any existing environment variable

If LOGNAME is not currently set in the environment then it is set to the current user’s login name.

value SHELL
Type:

pathname

Default:

any existing environment variable

If SHELL is not currently set in the environment then it is set to the current user’s login shell.

Note

It is not set to this instance of idio as “the running shell.”

Invocation Values

When idio is invoked it treats its arguments as:

.../idio [Idio-args] [script-name [script-args]]

where arguments to idio must come before any script name or arguments to the script as, both in essence and in practice, the first argument that isn’t recognised as an Idio argument will be treated as the name of a script. --hlep beware!

value ARGC
Type:

fixnum

This is the number of arguments to the script.

Clearly, if no arguments are passed to the script then ARGC is 0.

What if no script is being run, ie. we are in an interactive shell? Arguably, ARGC should be 0 again but currently it is -1 to distinguish that case.

value ARGV
Type:

array

Canonical:

ARGV

In particular, an array of strings.

This is the arguments to the script.

value ARGV0
Type:

string

This is either the name of the running script or is identical to IDIO_CMD.

This is similar to Bash’s $0 (and BASH_ARGV0) which is the name of the shell script or shell if running interactively.

value IDIO_CMD
Type:

pathname

This is argv[0] as idio sees it.

value IDIO_CMD_PATH
Type:

pathname

This is the normalized absolute pathname of argv[0] as idio sees it.

Normalization does not resolve symlinks but will resolve . and .. directories.

value IDIO_EXE
Type:

pathname

This is the realpath(3) canonicalized absolute pathname of argv[0] as idio sees it.

value IDIO_PID
Type:

libc/pid_t

IDIO_PID is the Process ID of the original instance of idio in this process tree.

See also

PID

value UID
Computed:

Type:

libc/uid_t

  • accessing calls getuid(2)

  • setting calls setuid(2)

value EUID
Computed:

Type:

libc/uid_t

  • accessing calls geteuid(2)

  • setting calls seteuid(2)

value GID
Computed:

Type:

libc/gid_t

  • accessing calls getgid(2)

  • setting calls setgid(2)

value EGID
Computed:

Type:

libc/gid_t

  • accessing calls getegid(2)

  • setting calls setegid(2)

value GROUPS
Type:

array

Canonical:

GROUPS

In particular, an array of libc/gid_t.

An array of the current user’s supplementary Group IDs as given by getgroups(2).

Executable Values

These are values intrinsic to the executable idio.

value IDIO_VERSION
Type:

string

IDIO_VERSION is the full version number of idio.

value IDIO_MM_VERSION
Type:

string

IDIO_MM_VERSION is the first two elements of IDIO_VERSION.

value IDIO_M_VERSION
Type:

string

IDIO_M_VERSION is the first element of IDIO_VERSION.

value IDIO_SYSTEM_ARCH
Type:

string

IDIO_SYSTEM_ARCH is used in the construction of actual directory search paths from IDIOLIB.

It takes the value of either:

value IDIO_SYSTEM_BINDIR
Type:

string

IDIO_SYSTEM_BINDIR is a reference to the determined system installation directory for executables.

See also

IDIO_SYSTEM_LIBDIR

value IDIO_SYSTEM_LIBDIR
Type:

string

IDIO_SYSTEM_LIBDIR is a reference to the determined system installation directory for libraries.

See also

IDIO_SYSTEM_BINDIR

value IDIO_BUILD_DATE
Type:

string

IDIO_BUILD_DATE is the build date of idio.

It is an RFC3339 compatible date.

value IDIO_BUILD_TIMESTAMP
Type:

string

IDIO_BUILD_TIMESTAMP is the build timestamp of idio.

It is an RFC3339 compatible value.

value IDIO_BUILD_COMMIT
Type:

string

IDIO_BUILD_COMMIT is a reference to the git commit of the program idio at the time of build.

For developers, the commit identifier might be suffixed with:

  • * if there were unstaged changes in the working tree at the time of the build

  • + if there were uncommitted changes in the index at the time of the build

value IDIO_BUILD_DESCRIBE
Type:

string

IDIO_BUILD_DESCRIBE is a reference to the git describe output of the program idio at the time of build.

value IDIO_BUILD_ASM_COMMIT
Type:

string

IDIO_BUILD_ASM_COMMIT is a reference to the git commit of the src/vm-asm.h file at the time of build.

For developers, the commit identifier might be suffixed with:

  • * if there were unstaged changes in the working tree at the time of the build

  • + if there were uncommitted changes in the index at the time of the build

value IDIO_BUILD_COMPILER_COMMIT
Type:

string

IDIO_BUILD_ASM_COMMIT is a reference to the git commit of the src/compile.c file at the time of build.

For developers, the commit identifier might be suffixed with:

  • * if there were unstaged changes in the working tree at the time of the build

  • + if there were uncommitted changes in the index at the time of the build

value IDIO_BUILD_CC
Type:

string

IDIO_BUILD_CC is a reference to the name of the compiler at the time of build.

See also

IDIO_BUILD_CC_PATH and IDIO_BUILD_CC_VERSION

value IDIO_BUILD_CC_PATH
Type:

string

IDIO_BUILD_CC_PATH is a reference to the pathname of the compiler at the time of build.

See also

IDIO_BUILD_CC and IDIO_BUILD_CC_VERSION

value IDIO_BUILD_CC_VERSION
Type:

string

IDIO_BUILD_CC_VERSION is a reference to the version string of the compiler at the time of build.

See also

IDIO_BUILD_CC and IDIO_BUILD_CC_PATH

Printing Values

value idio-print-conversion-format
Scope:

dynamic

Type:

unicode or #f

idio-print-conversion-format is the Unicode code point of the format specifier in the format string.

It is set by %format or by any functions using it.

For example, it is #\d in “%3d”.

value idio-print-conversion-precision
Scope:

dynamic

Type:

integer or #f

idio-print-conversion-precision is the precision specifier in the format string.

It is set by %format or by any functions using it.

For example, it is 3 in “%.3s”.

Error Suppression Values

value suppress-exit-on-error!
Scope:

dynamic

By default, if an external command exits with a non-zero status (from exit(3) or by signal) then idio will exit the same way.

You can suppress this behaviour by setting suppress-exit-on-error! to any non-#f value.

value suppress-pipefail!
Scope:

dynamic

By default, if any process in a job pipeline exits with a non-zero status (from exit(3) or by signal) then the whole pipeline is determined to have failed.

You can suppress this behaviour by setting suppress-pipefail! to any non-#f value.

value suppress-async-command-report!
Scope:

dynamic

By default, if any Process Substitution (or other async) command exits with a non-zero status (from exit(3) or by signal) then the failure is reported (via condition-report).

You can suppress this behaviour by setting suppress-async-command-report! to any non-#f value.

Idio Features

value *idio-features*
Type:

pair

*idio-features* is the list of features that can be tested with cond-expand. They are symbols and strings.

There are no values associated with the list elements, only presence or absence.

By default, Idio adds the following features:

  • from uname(2) the appropriate value’s for:

    • "uname/sysname/value"

    • "uname/nodename/value"

    • "uname/release/value"

    • "uname/machine/value"

  • sizeof/pointer/value – where value is sizeof (void *) * CHAR_BIT

  • IDIO_NO_F_DUPFD_CLOEXEC if libc does not define F_DUPFD_CLOEXEC

  • /dev/fd if this system uses the /dev/fd system for accessing all file descriptors

  • IDIO_DEBUG if this executable was compiled with debug enabled

There are some operating system-specific features:

  • for Linux ("uname/sysname/Linux"), from /etc/os-release:

    • "os-release/ID/value" for the value of the ID variable

    • "os-release/VERSION_ID/value" for the value of the VERSION_ID variable

    • virtualisation/WSL if running under Windows Subsystem for Linux (for WSL1 at any rate)

  • for SunOS ("uname/sysname/SunOS"), from /etc/release:

    • "release/value" where value is the first word from that file

See also

%add-feature

Last built at 2024-05-17T06:11:00Z+0000 from 62cca4c (dev) for Idio 0.3.b.6