When looking at predicate modes to understand how to use a predicate one of the first things is to know if the argument is an input (+) or output (-). However one should also remember that : is sometimes +.
The modes for predicates notes
:
Argument is a meta-argument , for example a term that can be called as goal. The predicate is thus a meta-predicate . This flag implies+.
For example in trying to find a predicate that can be run as a query to list all of the known settings when using the settings library,
setting/4, % :Name, +Type, +Default, +Comment
setting/2, % :Name, ?Value
set_setting/2, % :Name, +Value
set_setting_default/2, % :Name, +Value
restore_setting/1, % :Name
load_settings/1, % +File
load_settings/2, % +File, +Options
save_settings/0,
save_settings/1, % +File
current_setting/1, % Module:Name
setting_property/2, % ?Setting, ?Property
list_settings/0,
list_settings/1, % +Module
convert_setting_text/3 % +Type, +Text, -Value
one would hope to find a predicate with a predicate mode like +Name, +Value but there is none.
If one takes into consideration that : is the same as + then seeking :Name, +Value one finds setting/2. which is actually :Name, ?Value but hopefully by now you know that ? can be considered + or -.
The mode : requires that the pattern of Module:Name be used.
Example
?- setting(Name,Value).
false.
returns false because the pattern Module:Name was not used.
?- setting(Module:Name,Value).
Module = examples,
Name = setting_01_bool,
Value = true ;
Module = examples,
Name = setting_02_string,
Value = "a string" ;
Module = examples,
Name = setting_03_list,
Value = [1, 2, hello].
In the title I used sometimes because one also finds the predicate mode :Name, +Value for set_setting/2 but AFAIK that does not accept unbound values for :Name. I don’t know if that is a mistake in the documentation or the fact that : does not always mean +, something I did wrong in the examples below or something I need to learn.
?- set_setting(Module:Name,Value).
ERROR: Type error: `atom' expected, found `_5016:_5018' (a compound)
ERROR: In:
ERROR: [14] throw(error(type_error(atom,...),_5068))
ERROR: [10] settings:set_setting(_5110:_5112,_5106) at c:/program files/swipl/library/settings.pl:386
ERROR: [9] toplevel_call(user:user: ...) at c:/program files/swipl/boot/toplevel.pl:1116
ERROR:
ERROR: Note: some frames are missing due to last-call optimization.
ERROR: Re-run your program in debug mode (:- debug.) to get more detail.
?- set_setting(examples:Name,Value).
ERROR: Arguments are not sufficiently instantiated
ERROR: In:
ERROR: [14] throw(error(instantiation_error,_6650))
ERROR: [10] settings:set_setting(examples:_6688,_6682) at c:/program files/swipl/library/settings.pl:386
ERROR: [9] toplevel_call(user:user: ...) at c:/program files/swipl/boot/toplevel.pl:1116
ERROR:
ERROR: Note: some frames are missing due to last-call optimization.
ERROR: Re-run your program in debug mode (:- debug.) to get more detail.
?- set_setting(examples:setting_01_bool,Value).
ERROR: Arguments are not sufficiently instantiated
ERROR: In:
ERROR: [15] throw(error(instantiation_error,_8296))
ERROR: [10] settings:set_setting(examples:setting_01_bool,_8328) at c:/program files/swipl/library/settings.pl:384
ERROR: [9] toplevel_call(user:user: ...) at c:/program files/swipl/boot/toplevel.pl:1116
ERROR:
ERROR: Note: some frames are missing due to last-call optimization.
ERROR: Re-run your program in debug mode (:- debug.) to get more detail.
?- set_setting(examples:setting_01_bool,false).
true.
The file used for the examples above:
File: examples.pl
:- module(examples,[]).
:- use_module(library(settings)).
:- setting(setting_01_bool, boolean, true, 'Example setting of type: boolean.').
:- setting(setting_02_string, text, "a string", 'Example setting of type: string.').
:- setting(setting_03_list, list, [1,2,hello], 'Example setting of type: list.').