.. include:: ../global.rst Idio Values ----------- There are several classes of :lname:`Idio` values with regards to scope and effect and provenance. .. _`dynamic?`: .. idio: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 .. _`environ?`: .. idio: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 :ref:`quote ` any argument likely to be expanded by the evaluator: .. code-block:: idio environ? HOME ; == environ? %P"/home/me" environ? 'HOME ; #t (or #f?) .. _`computed?`: .. idio: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 ^^^^^^^^^^^^^^ .. _`IDIOLIB`: .. idio:value:: IDIOLIB :type: string :var:`IDIOLIB` is the search path used by :program:`idio` to find libraries and extension code. Any non-absolute directories are ignored. The construction of :var:`IDIOLIB` is complicated but there are two things to note: #. :program:`idio` will determine the :file:`lib` directory that corresponds with the actual executable being run. This directory will be *prepended* to any user-supplied :envvar:`IDIOLIB` environment variable. #. if you used a *virtualenv*-style setup (where the :program:`idio` found on your :envvar:`PATH` is a symlink to a real executable) then :program:`idio` will determine the :file:`lib` directory that corresponds with the virtualenv being used. This directory will be *prepended* to any user-supplied :envvar:`IDIOLIB` environment variable. In both cases, a :file:`.../lib` will only be prepended if the executable/symlink `name` was :file:`.../bin/{name}`, ie. the immediate directory name must be :file:`bin`. .. _`IFS`: .. idio:value:: IFS :type: string :scope: dynamic :default: ``" \t\n"`` (SPACE TAB NEWLINE) :var:`IFS` is the Input [#]_ Field Separator and is the value used by :ref:`fields ` or the default value used by :ref:`split-string ` to split a string into substrings. It is not like :lname:`Bash`'s variable in the sense that it might recover its default value if you unset it. It's just a regular dynamic variable. .. [#] In :lname:`Bash` it is the *Internal* Field Separator and is used for both input and output field separation processing and unlike :program:`awk`'s :var:`RS` and :var:`ORS`, say. .. _`PID`: .. idio:value:: PID :type: libc/pid_t :var:`PID` is the Process ID of the current instance of :program:`idio`. This value will be updated in the child if you call :ref:`libc/fork `. .. seealso:: :ref:`IDIO_PID ` .. _`PPID`: .. idio:value:: PPID :type: libc/pid_t :var:`PPID` is the parent Process ID of the current instance of :program:`idio`. This value will be updated in the child if you call :ref:`libc/fork `. .. _`RANDOM`: .. idio:value:: RANDOM :type: fixnum :computed: :var:`RANDOM` is a computed value returning a random non-negative 32-bit integer. Setting :var:`RANDOM` re-seeds the random number generator. :rtype: integer (irrespective of the type mentioned above) .. note:: :var:`RANDOM` is based on :manpage:`random(3)` with attendant risks for use in scenarios requiring high quality randomness. In OpenBSD, when setting :var:`RANDOM`, the seed variable is ignored, and strong random number results will be provided from :manpage:`arc4random(3)`. .. _`SECONDS`: .. idio:value:: SECONDS :type: fixnum :computed: :var:`SECONDS` is a computed value returning the number of seconds since :program:`idio` started. There is no `setter` function. :rtype: integer (irrespective of the type mentioned above) .. _`TIMEFORMAT`: .. idio:value:: TIMEFORMAT :type: string :scope: dynamic :default: ``"Real %.3R\nUser %.3U\nSyst %.3S\n"`` :var:`TIMEFORMAT` is a string describing the report for the :ref:`time-function ` command (or `time` :ref:`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. .. _`*epsilon*`: .. idio:value:: *epsilon* :type: bignum :default: 1\ :sup:`-18` :var:`*epsilon*` is the `machine epsilon `_ used to truncate the calculation of infinite series. Environment Values ^^^^^^^^^^^^^^^^^^ All extant environment variables become environ values in :program:`idio`. If the following values do not exist in the environment at startup then they will be created as environ values as described below. .. _`PATH`: .. idio:value:: PATH :type: string :default: any existing environment variable If :var:`PATH` is not currently set in the environment then it is set to the result of passing ``_CS_PATH`` to :manpage:`confstr(3)` or, failing that, ``"/bin:/usr/bin"``. .. _`PWD`: .. idio:value:: PWD :type: pathname :var:`PWD` is the Process Working Directory. It assumes the value in the environment at startup (or is set to the result of :ref:`libc/getcwd `). It is subsequently updated by calls to :ref:`cd ` and :ref:`pushd ` / :ref:`popd `. .. warning:: Calls to :ref:`libc/chdir ` **do not** change `PWD`. .. _`HOME`: .. idio:value:: HOME :type: pathname :default: any existing environment variable If :var:`HOME` is not currently set in the environment then it is set to the current user's HOME directory. .. _`LOGNAME`: .. idio:value:: LOGNAME :type: string :default: any existing environment variable If :var:`LOGNAME` is not currently set in the environment then it is set to the current user's login name. .. _`SHELL`: .. idio:value:: SHELL :type: pathname :default: any existing environment variable If :var:`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 :program:`idio` as "the running shell." Invocation Values ^^^^^^^^^^^^^^^^^ When :program:`idio` is invoked it treats its arguments as: .. parsed-literal:: .../idio [*Idio-args*] [*script-name* [*script-args*]] where arguments to :program:`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 :lname:`Idio` argument will be treated as the name of a script. ``--hlep`` beware! .. _`ARGC`: .. idio:value:: ARGC :type: fixnum This is the number of arguments to the *script*. Clearly, if no arguments are passed to the script then :var:`ARGC` is 0. What if no script is being run, ie. we are in an interactive shell? Arguably, :var:`ARGC` should be 0 again but currently it is -1 to distinguish that case. .. _`ARGV`: .. idio:value:: ARGV :type: array :canonical: ARGV In particular, an array of strings. This is the arguments to the *script*. .. _`ARGV0`: .. idio:value:: ARGV0 :type: string This is either the name of the running `script` or is identical to :ref:`IDIO_CMD `. This is similar to :lname:`Bash`'s :var:`$0` (and :var:`BASH_ARGV0`) which is the name of the shell script or shell if running interactively. .. _`IDIO_CMD`: .. idio:value:: IDIO_CMD :type: pathname This is ``argv[0]`` as :program:`idio` sees it. .. _`IDIO_CMD_PATH`: .. idio:value:: IDIO_CMD_PATH :type: pathname This is the normalized absolute pathname of ``argv[0]`` as :program:`idio` sees it. Normalization does not resolve symlinks but will resolve :file:`.` and :file:`..` directories. .. _`IDIO_EXE`: .. idio:value:: IDIO_EXE :type: pathname This is the :manpage:`realpath(3)` canonicalized absolute pathname of ``argv[0]`` as :program:`idio` sees it. .. _`IDIO_PID`: .. idio:value:: IDIO_PID :type: libc/pid_t :var:`IDIO_PID` is the Process ID of the original instance of :program:`idio` in this process tree. .. seealso:: :ref:`PID ` .. _`UID`: .. idio:value:: UID :computed: :type: libc/uid_t * accessing calls :manpage:`getuid(2)` * setting calls :manpage:`setuid(2)` .. _`EUID`: .. idio:value:: EUID :computed: :type: libc/uid_t * accessing calls :manpage:`geteuid(2)` * setting calls :manpage:`seteuid(2)` .. _`GID`: .. idio:value:: GID :computed: :type: libc/gid_t * accessing calls :manpage:`getgid(2)` * setting calls :manpage:`setgid(2)` .. _`EGID`: .. idio:value:: EGID :computed: :type: libc/gid_t * accessing calls :manpage:`getegid(2)` * setting calls :manpage:`setegid(2)` .. _`GROUPS`: .. idio: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 :manpage:`getgroups(2)`. Executable Values ^^^^^^^^^^^^^^^^^ These are values intrinsic to the executable :program:`idio`. .. _`IDIO_VERSION`: .. idio:value:: IDIO_VERSION :type: string :var:`IDIO_VERSION` is the full version number of :program:`idio`. .. _`IDIO_MM_VERSION`: .. idio:value:: IDIO_MM_VERSION :type: string :var:`IDIO_MM_VERSION` is the first two elements of :ref:`IDIO_VERSION `. .. _`IDIO_M_VERSION`: .. idio:value:: IDIO_M_VERSION :type: string :var:`IDIO_M_VERSION` is the first element of :ref:`IDIO_VERSION `. .. _`IDIO_SYSTEM_ARCH`: .. idio:value:: IDIO_SYSTEM_ARCH :type: string :var:`IDIO_SYSTEM_ARCH` is used in the construction of actual directory search paths from :ref:`IDIOLIB `. It takes the value of either: * ``${CC} -print-multiarch`` -- the Debian `Multiarch Architecture Specifiers (Tuples) `_ * ``${CC} -dumpmachine`` -- the GNU triplet .. _`IDIO_SYSTEM_BINDIR`: .. idio:value:: IDIO_SYSTEM_BINDIR :type: string :var:`IDIO_SYSTEM_BINDIR` is a reference to the determined system installation directory for executables. .. seealso:: :ref:`IDIO_SYSTEM_LIBDIR ` .. _`IDIO_SYSTEM_LIBDIR`: .. idio:value:: IDIO_SYSTEM_LIBDIR :type: string :var:`IDIO_SYSTEM_LIBDIR` is a reference to the determined system installation directory for libraries. .. seealso:: :ref:`IDIO_SYSTEM_BINDIR ` .. _`IDIO_BUILD_DATE`: .. idio:value:: IDIO_BUILD_DATE :type: string :var:`IDIO_BUILD_DATE` is the build date of :program:`idio`. It is an RFC3339_ compatible date. .. _`IDIO_BUILD_TIMESTAMP`: .. idio:value:: IDIO_BUILD_TIMESTAMP :type: string :var:`IDIO_BUILD_TIMESTAMP` is the build timestamp of :program:`idio`. It is an RFC3339_ compatible value. .. _`IDIO_BUILD_COMMIT`: .. idio:value:: IDIO_BUILD_COMMIT :type: string :var:`IDIO_BUILD_COMMIT` is a reference to the *git* commit of the program :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 .. _`IDIO_BUILD_DESCRIBE`: .. idio:value:: IDIO_BUILD_DESCRIBE :type: string :var:`IDIO_BUILD_DESCRIBE` is a reference to the *git* ``describe`` output of the program :program:`idio` at the time of build. .. _`IDIO_BUILD_ASM_COMMIT`: .. idio:value:: IDIO_BUILD_ASM_COMMIT :type: string :var:`IDIO_BUILD_ASM_COMMIT` is a reference to the *git* commit of the :file:`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 .. _`IDIO_BUILD_COMPILER_COMMIT`: .. idio:value:: IDIO_BUILD_COMPILER_COMMIT :type: string :var:`IDIO_BUILD_ASM_COMMIT` is a reference to the *git* commit of the :file:`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 .. _`IDIO_BUILD_CC`: .. idio:value:: IDIO_BUILD_CC :type: string :var:`IDIO_BUILD_CC` is a reference to the name of the compiler at the time of build. .. seealso:: :ref:`IDIO_BUILD_CC_PATH ` and :ref:`IDIO_BUILD_CC_VERSION ` .. _`IDIO_BUILD_CC_PATH`: .. idio:value:: IDIO_BUILD_CC_PATH :type: string :var:`IDIO_BUILD_CC_PATH` is a reference to the pathname of the compiler at the time of build. .. seealso:: :ref:`IDIO_BUILD_CC ` and :ref:`IDIO_BUILD_CC_VERSION ` .. _`IDIO_BUILD_CC_VERSION`: .. idio:value:: IDIO_BUILD_CC_VERSION :type: string :var:`IDIO_BUILD_CC_VERSION` is a reference to the version string of the compiler at the time of build. .. seealso:: :ref:`IDIO_BUILD_CC ` and :ref:`IDIO_BUILD_CC_PATH ` Printing Values ^^^^^^^^^^^^^^^ .. _`idio-print-conversion-format`: .. idio:value:: idio-print-conversion-format :scope: dynamic :type: unicode or ``#f`` :var:`idio-print-conversion-format` is the Unicode code point of the format specifier in the format string. It is set by :ref:`%format <%format>` or by any functions using it. For example, it is ``#\d`` in "%3d". .. _`idio-print-conversion-precision`: .. idio:value:: idio-print-conversion-precision :scope: dynamic :type: integer or ``#f`` :var:`idio-print-conversion-precision` is the precision specifier in the format string. It is set by :ref:`%format <%format>` or by any functions using it. For example, it is ``3`` in "%.3s". Error Suppression Values ^^^^^^^^^^^^^^^^^^^^^^^^ .. _`suppress-exit-on-error!`: .. idio:value:: suppress-exit-on-error! :scope: dynamic By default, if an external command exits with a non-zero status (from :manpage:`exit(3)` or by signal) then :program:`idio` will exit the same way. You can suppress this behaviour by setting :var:`suppress-exit-on-error!` to any non-``#f`` value. .. _`suppress-pipefail!`: .. idio:value:: suppress-pipefail! :scope: dynamic By default, if any process in a job pipeline exits with a non-zero status (from :manpage:`exit(3)` or by signal) then the whole pipeline is determined to have failed. You can suppress this behaviour by setting :var:`suppress-pipefail!` to any non-``#f`` value. .. _`suppress-async-command-report!`: .. idio:value:: suppress-async-command-report! :scope: dynamic By default, if any *Process Substitution* (or other *async*) command exits with a non-zero status (from :manpage:`exit(3)` or by signal) then the failure is reported (via :ref:`condition-report `). You can suppress this behaviour by setting :var:`suppress-async-command-report!` to any non-``#f`` value. .. _`idio features`: Idio Features ^^^^^^^^^^^^^ .. _`*idio-features*`: .. idio:value:: *idio-features* :type: pair :var:`*idio-features*` is the list of features that can be tested with :ref:`cond-expand `. They are symbols and strings. There are no values associated with the list elements, only presence or absence. By default, :lname:`Idio` adds the following features: * from :manpage:`uname(2)` the appropriate :samp:`{value}`'s for: * :samp:`"uname/sysname/{value}"` * :samp:`"uname/nodename/{value}"` * :samp:`"uname/release/{value}"` * :samp:`"uname/machine/{value}"` * :samp:`sizeof/pointer/{value}` -- where `value` is ``sizeof (void *) * CHAR_BIT`` * ``IDIO_NO_F_DUPFD_CLOEXEC`` if :ref:`libc ` does not define ``F_DUPFD_CLOEXEC`` * ``/dev/fd`` if this system uses the :file:`/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 :file:`/etc/os-release`: * :samp:`"os-release/ID/{value}"` for the value of the ``ID`` variable * :samp:`"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 :file:`/etc/release`: * :samp:`"release/{value}"` where :samp:`{value}` is the first word from that file .. seealso:: :ref:`%add-feature <%add-feature>` .. include:: ../commit.rst