Changing system behaviour and various flags

Author(s): Daniel Cabeza, Mats Carlsson.

Version: 1.11#222 (2004/5/24, 13:8:7 CEST)

Version of last change: 1.7#213 (2002/5/14, 18:11:29 CEST)

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.

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 (prolog_flags)
• Documentation on exports (prolog_flags)
• Documentation on multifiles (prolog_flags)

Usage and interface (prolog_flags)

Documentation on exports (prolog_flags)

PREDICATE: set_prolog_flag/2:

set_prolog_flag(FlagName, Value)

Set existing flag FlagName to Value.

Usage: * ISO *

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

PREDICATE: current_prolog_flag/2:

current_prolog_flag(FlagName, Value)

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

Usage: * ISO *

• Calls should, and exit will be compatible with: FlagName is an atom. (basic_props:atm/1) Value is any term. (basic_props:term/1)
• The following properties hold upon exit: FlagName is an atom. (basic_props:atm/1) Value is any term. (basic_props:term/1)

PREDICATE: prolog_flag/3:

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:

• Calls should, and exit will be compatible with: FlagName is an atom. (basic_props:atm/1) OldValue is any term. (basic_props:term/1)
• The following properties should hold at call time: NewValue is any term. (basic_props:term/1)
• The following properties hold upon exit: FlagName is an atom. (basic_props:atm/1) OldValue is any term. (basic_props:term/1)

Usage 2: prolog_flag(FlagName, OldValue, NewValue)

• Description: Same as current_prolog_flag(FlagName, OldValue)
• The following properties should hold at call time: OldValue is a free variable. (term_typing:var/1) NewValue is a free variable. (term_typing:var/1) FlagName is an atom. (basic_props:atm/1) The terms OldValue and NewValue are strictly identical. (term_compare:== /2)

PREDICATE: push_prolog_flag/2:

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: Flag is an atom. (basic_props:atm/1) NewValue is any term. (basic_props:term/1)

PREDICATE: pop_prolog_flag/1:

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: Flag is an atom. (basic_props:atm/1)

PREDICATE: prompt/2:

prompt(Old, New)

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

Usage 1:

• Calls should, and exit will be compatible with: Old is an atom. (basic_props:atm/1)
• The following properties should hold at call time: New is an atom. (basic_props:atm/1)
• The following properties hold upon exit: Old is an atom. (basic_props:atm/1)

Usage 2: prompt(Old, New)

• Description: Unify Old with the current prompt for reading without changing it.
• The following properties should hold at call time: Old is a free variable. (term_typing:var/1) New is a free variable. (term_typing:var/1) The terms Old and New are strictly identical. (term_compare:== /2)
• The following properties hold upon exit: Old is an atom. (basic_props:atm/1) New is an atom. (basic_props:atm/1)

PREDICATE: gc/0:

Usage:

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

PREDICATE: nogc/0:

Usage:

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

PREDICATE: fileerrors/0:

Usage:

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

PREDICATE: nofileerrors/0:

Usage:

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

Documentation on multifiles (prolog_flags)

PREDICATE: define_flag/3:

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).

The predicate is multifile.

Usage 1: define_flag(Flag, ==(atom), Default)

• Description: Posible values for the flag are atoms. Example:

  :- multifile define_flag/3.
  define_flag(tmpdir, atom, '/tmp').
  

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

Usage 2: define_flag(Flag, ==(integer), Default)

• Description: Posible values for the flag are integers. Example:

  :- multifile define_flag/3.
  define_flag(max_connections, integer, 10).
  

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

Usage 3: define_flag(atm, list(Values), Default)

• Description: Posible values for the flag are the elements of Values. Example:

  :- multifile define_flag/3.
  define_flag(debug, [on,debug,trace,off], off).
  

• The following properties should hold upon exit: Default is an element of Values. (basic_props:member/2)

Go to the first, previous, next, last section, table of contents.