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). Version is a floating point number, Patch is an integer. 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
- Library usage:
These predicates are builtin in Ciao, so nothing special has to be done to use them. - Exports:
- Imports:
- Packages:
prelude, nonpure, assertions, nortchecks, isomodes, define_flag.
- Packages:
Documentation on exports
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.
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.
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.
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.
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.
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).
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).
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).
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).
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).
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.
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).
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).
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).
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
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
Documentation on internals
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.
