Create a new Prolog flag. The ISO standard does not foresee creation of
new flags, but many libraries introduce new flags. Prolog flags are
particularly useful for managing mutating global settings in a threaded
environment. Were predicates are either local to a thread or shared
between all threads, a thread inherits its flags from the
thread that creates it (see thread_create/3)
while modifications are local to the calling thread.
SWI-Prolog flags are typed. If the type is not explicitly defined
using the type(Type) option (see below), the type is
determined from the initial value. Defined types are boolean
(if the initial value is one of false, true, on
or off),
atom if the initial value is any other atom, integer
if the value is an integer that can be expressed as a 64-bit signed
value. Any other initial value results in an untyped flag that can
represent any valid Prolog term.
By default, the new flag is added to the global flag table, making
the value available to all threads that have not set the flag. If the
flag was already defined locally in the calling thread, the value is
updated both for the calling thread and in the global flag table. See
the
local(+Boolean) option.
Options is a list of the options below. See also the
Prolog flag
user_flags.
- access(+Access)
- Define access rights for the flag. Values are
read_write
and read_only. The default is read_write.
- type(+Atom)
- Define a type restriction. Possible values are
boolean, atom, oneof(ListOfAtoms),
integer, float and term. The
default is determined from the initial value. Note that term
restricts the term to be ground.
- keep(+Boolean)
- If
true, do not modify the flag if it already exists.
Otherwise (default), this predicate behaves as set_prolog_flag/2
if the flag already exists.
If the flag has a value, but this value is incompatible with the
specified type, a warning is printed and the flag gets the value and
type specified by this call to create_prolog_flag/3.
- local(+Boolean)
- If
true (default false), if the flag does not
exist, create it only in the calling thread. The flag is only
visible in the calling thread and threads that inherit from the calling
thread.
- warn_not_accessed(+Boolean)
- If
true and the flag is never read using
current_prolog_flag/2,
print a warning. This option is used for options set using the
commandline option -D<flag>[=<value>].
