Changing system behaviour and various flags

Author(s): Daniel Cabeza, Mats Carlsson.

Flags define some parameters of the system and control the behavior of system or library predicates. Each flag has a name and an associated predefined value, and except some system flags which are fixed in general their associated value is changeable. Predefined flags in the system are:

version
The Ciao version, as a term ciao(Version,Patch,CommitInfo). Version and Patch are atoms. CommitInfo is a structure describing the commit information (branch, id, date, description). Unchangeable.

dialect
Value set to ciao. Used for compatibility with other systems when in Prolog mode. Unchangeable.

argv
Its value is a list of atoms representing the program arguments supplied when the current executable was invoked. This is the value to which is instantiated the argument of the main/1 predicate at executable startup. Unchangeable.

bounded
It is false, to denote that the range of integers can be considered infinite (but see int/1). Unchangeable. ISO
fileerrors
If on, predicates handling files give errors (throw exceptions) when a file is inexistent or an operation is not allowed. If off, fail in that conditions. Initially on.

gc
Controls whether garbage collection is done. May be on (default) or off.

gc_margin
An integer Margin. If less than Margin kilobytes are reclaimed in a garbage collection then the size of the garbage collected area should be increased. Also, no garbage collection is attempted unless the garbage collected area has at least Margin kilobytes. Initially 500.

gc_trace
Governs garbage collection trace messages. An element off [on,off,terse,verbose]. Initially off.

integer_rounding_function
It is toward_zero, so that -1 =:= -3//2 succeeds. Unchangeable. ISO
max_arity
It is 255, so that no compound term (or predicate) can have more than this number of arguments. Unchangeable. ISO
quiet
Controls which messages issued using io_aux are actually written. As the system uses that library to report its messages, this flag controls the verbosity of the system. Possible states of the flag are:

on
No messages are reported.

error
Only error messages are reported.

warning
Only error and warning messages are reported.

off
All messages are reported, except debug messages. This is the default state.

debug
All messages, including debug messages, are reported. This is only intended for the system implementators.

unknown
Controls action on calls to undefined predicates. The possible states of the flag are:

error
An error is thrown with the error term existence_error(procedure, F/A).

fail
The call simply fails.

warning
A warning is written and the call fails.

The state is initially error. ISO


Usage and interface

Documentation on exports

PREDICATE
set_prolog_flag(FlagName,Value)

Set existing flag FlagName to Value.

Usage:ISO

  • The following properties should hold at call time:
    (basic_props:atm/1)FlagName is an atom.
    (basic_props:term/1)Value is any term.
  • The following properties should hold upon exit:
    (basic_props:atm/1)FlagName is an atom.
    (basic_props:term/1)Value is any term.

PREDICATE
current_prolog_flag(FlagName,Value)

FlagName is an existing flag and Value is the value currently associated with it.

Usage:

  • The following properties should hold upon exit:
    (basic_props:atm/1)FlagName is an atom.
    (basic_props:term/1)Value is any term.

PREDICATE
prolog_flag(FlagName,OldValue,NewValue)

FlagName is an existing flag, unify OldValue with the value associated with it, and set it to new value NewValue.

Usage 1:prolog_flag(A,B,C)

  • The following properties should hold at call time:
    (basic_props:term/1)C is any term.
    (term_typing:nonvar/1)C is currently a term which is not a free variable.
  • The following properties should hold upon exit:
    (basic_props:atm/1)A is an atom.
    (basic_props:term/1)B is any term.

Usage 2:prolog_flag(FlagName,OldValue,NewValue)

Same as current_prolog_flag(FlagName, OldValue). OldValue and NewValue must be strictly identical variables.

  • The following properties should hold at call time:
    (term_typing:var/1)OldValue is a free variable.
    (term_typing:var/1)NewValue is a free variable.
    (basic_props:atm/1)FlagName is an atom.
  • The following properties should hold upon exit:
    (basic_props:term/1)OldValue is any term.
    (basic_props:term/1)NewValue is any term.

PREDICATE
push_prolog_flag(Flag,NewValue)

Same as set_prolog_flag/2, but storing current value of Flag to restore it with pop_prolog_flag/1.

Usage:

  • The following properties should hold at call time:
    (basic_props:atm/1)Flag is an atom.
    (basic_props:term/1)NewValue is any term.
  • The following properties should hold upon exit:
    (basic_props:atm/1)Flag is an atom.
    (basic_props:term/1)NewValue is any term.

PREDICATE
pop_prolog_flag(Flag)

Restore the value of Flag previous to the last non-canceled push_prolog_flag/2 on it.

Usage:

  • The following properties should hold at call time:
    (basic_props:atm/1)Flag is an atom.
  • The following properties should hold upon exit:
    (basic_props:atm/1)Flag is an atom.

PREDICATE

Usage:set_ciao_flag(FlagName,Value)

  • The following properties should hold globally:
    (basic_props:equiv/2)set_ciao_flag(FlagName,Value) is equivalent to set_prolog_flag(FlagName,Value).

PREDICATE

Usage:current_ciao_flag(FlagName,Value)

  • The following properties should hold globally:
    (basic_props:equiv/2)current_ciao_flag(FlagName,Value) is equivalent to current_prolog_flag(FlagName,Value).

PREDICATE

Usage:ciao_flag(Flag,Old,New)

  • The following properties should hold globally:
    (basic_props:equiv/2)ciao_flag(Flag,Old,New) is equivalent to prolog_flag(Flag,Old,New).

PREDICATE

Usage:push_ciao_flag(Flag,NewValue)

  • The following properties should hold globally:
    (basic_props:equiv/2)push_ciao_flag(Flag,NewValue) is equivalent to push_prolog_flag(Flag,NewValue).

PREDICATE

Usage:pop_ciao_flag(Flag)

  • The following properties should hold globally:
    (basic_props:equiv/2)pop_ciao_flag(Flag) is equivalent to pop_prolog_flag(Flag).

PREDICATE
prompt(Old,New)

Unify Old with the current prompt for reading, change it to New.

Usage 1:prompt(A,B)

  • The following properties should hold at call time:
    (basic_props:atm/1)B is an atom.
  • The following properties should hold upon exit:
    (basic_props:atm/1)A is an atom.

Usage 2:prompt(Old,New)

Unify Old with the current prompt for reading without changing it. On calls, Old and New must be strictly identical variables.

  • The following properties should hold at call time:
    (term_typing:var/1)Old is a free variable.
    (term_typing:var/1)New is a free variable.
  • The following properties should hold upon exit:
    (basic_props:atm/1)Old is an atom.
    (basic_props:atm/1)New is an atom.

PREDICATE

Usage:

Enable garbage collection. Equivalent to set_prolog_flag(gc, on)

  • The following properties should hold globally:
    (basic_props:equiv/2)gc is equivalent to set_prolog_flag(gc,on).

PREDICATE

Usage:

Disable garbage collection. Equivalent to set_prolog_flag(gc, off)

  • The following properties should hold globally:
    (basic_props:equiv/2)nogc is equivalent to set_prolog_flag(gc,off).

PREDICATE

Usage:

Enable reporting of file errors. Equivalent to set_prolog_flag(fileerrors, on)

  • The following properties should hold globally:
    (basic_props:equiv/2)fileerrors is equivalent to set_prolog_flag(fileerrors,on).

PREDICATE

Usage:

Disable reporting of file errors. Equivalent to set_prolog_flag(fileerrors, off)

  • The following properties should hold globally:
    (basic_props:equiv/2)nofileerrors is equivalent to set_prolog_flag(fileerrors,off).

Documentation on multifiles

PREDICATE
define_flag(Flag,Values,Default)

New flags can be defined by writing facts of this predicate. Flag is the name of the new flag, Values defines the posible values for the flag (see below) and Default defines the predefined value associated with the flag (which should be compatible with Values).

(Trust) Usage:define_flag(Flag,FlagValues,Default)

  • The following properties hold upon exit:
    (basic_props:atm/1)Flag is an atom.
    (basic_props:flag_values/1)Define the valid flag values
The predicate is multifile.

Documentation on internals

PREDICATE
No further documentation available for this predicate.

Known bugs and planned improvements

  • Run-time checks have been reported not to work with this code. That means that either the assertions here, or the code that implements the run-time checks are erroneous.