write_canonical/1, write_canonical/2,
write_term/2, write_term/3, writeq/1, writeq/2]).
+/** Builtin predicates
+
+This library, unlike the rest, is loaded by default and it exposes the most fundamental and general
+predicates of the Prolog system under the ISO standard. Basic operators, metaprogramming, exceptions,
+internal settings and basic I/O are all here.
+*/
+
% unify.
+
+%% =(?X, ?Y)
+%
+% Unify two variables. This is the most basic operation of Prolog.
+% Unification also happens when doing head matching in a rule.
X = X.
+%% true.
+%
+% Always succeeds
true.
+%% false.
+%
+% Always fails
false :- '$fail'.
% Once Scryer is bootstrapped, each is replaced with a version that
% uses expand_goal to pass the expanded goal along to '$call'.
+
+%% call(Goal).
+%
+% Execute the Goal. Typically used when the Goal is not known at compile time.
call(_).
+%% call(Goal, ExtraArg1).
+%
+% Execute the Goal with ExtraArg1 appended to the argument list. For example:
+%
+% ?- call(format("~s~n"), ["Alain Colmerauer"]).
+% Alain Colmerauer
+% true.
+%
+% Which is equivalent to: `format("~s~n", ["Alain Colmerauer"]).`
call(_, _).
+%% call(Goal, ExtraArg1, ExtraArg2).
+%
+% Execute Goal with ExtraArg1 and ExtraArg2 appended to the argument list.
call(_, _, _).
+%% call(Goal, ExtraArg1, ExtraArg2, ExtraArg3).
+%
+% Execute Goal with ExtraArg1, ExtraArg2 and ExtraArg3 appended to the argument list.
call(_, _, _, _).
+%% call(Goal, ExtraArg1, ExtraArg2, ExtraArg3, ExtraArg4).
+%
+% Execute Goal with ExtraArg1, ExtraArg2, ExtraArg3 and ExtraArg4 appended to the argument list.
call(_, _, _, _, _).
+%% call(Goal, ExtraArg1, ExtraArg2, ExtraArg3, ExtraArg4, ExtraArg5).
+%
+% Execute Goal with ExtraArg1, ExtraArg2, ExtraArg3, ExtraArg4 and ExtraArg5 appended to the argument list.
call(_, _, _, _, _, _).
+%% call(Goal, ExtraArg1, ExtraArg2, ExtraArg3, ExtraArg4, ExtraArg5, ExtraArg6).
+%
+% Execute Goal with ExtraArg1, ExtraArg2, ExtraArg3, ExtraArg4, ExtraArg5 and ExtraArg6 appended
+% to the argument list.
call(_, _, _, _, _, _, _).
+%% call(Goal, ExtraArg1, ExtraArg2, ExtraArg3, ExtraArg4, ExtraArg5, ExtraArg6, ExtraArg7).
+%
+% Execute Goal with ExtraArg1, ExtraArg2, ExtraArg3, ExtraArg4, ExtraArg5, ExtraArg6 and ExtraArg7
+% appended to the argument list.
call(_, _, _, _, _, _, _, _).
+%% call(Goal, ExtraArg1, ExtraArg2, ExtraArg3, ExtraArg4, ExtraArg5, ExtraArg6, ExtraArg7, ExtraArg8).
+%
+% Execute Goal with ExtraArg1, ExtraArg2, ExtraArg3, ExtraArg4, ExtraArg5, ExtraArg6, ExtraArg7 and
+% ExtraArg8, appended to the argument list.
call(_, _, _, _, _, _, _, _, _).
% flags.
+%% current_prolog_flag(Flag, Value)
+%
+% Returns the current Value of several flags in the running system. A flag is a setting which value affects
+% internal operation of the Prolog system. Some flags are read-only, while others can be set with set\_prolog\_flag/2.
+%
+% The flags that Scryer Prolog support are:
+% * `max\_arity`: The max arity a predicate can have in Prolog. On Scryer is set to 1023. Read only.
+% * `bounded`: `true` if integer arithmethic is bounded between some min/max values. On Scryer is always set
+% to `false` since it supports unbounded integer arithmethic. Read only.
+% * `integer\_rounding\_function`: Describes the rounding donde by `//` and `rem` functions. On Scryer is
+% always set to `toward\_zero`. Read only
+% * `double\_quotes`: Determines how double quoted strings are red by Prolog. Scryer uses `chars` by default
+% which is a list of one-character atoms. Other values are codes (list of integers representing characters),
+% and atom which creates a whole atom for the string value. Read and write.
+% * `max\_integer`: Maximum integer supported by the system. As Scryer Prolog has unbounded integer arithmethic,
+% checking the value of this flag fails. Read only.
+% * `min\_integer`: Minimum integer supported by the system. As Scryer Prolog has unbounded integer arithmethic,
+% checking the value of this flag fails. Read only.
+% * `occurs\_check`: Returns if the occurs check is enabled. The occurs check prevents the creation cyclic terms.
+% Historically the Prolog unification algorithm didn't do that check so changing the value modifies how Prolog
+% operates in the low-level. Possible values are `false` (default), `true` (unification has this check
+% enabled) and `error` which throws an exception when a cylic term is created. Read ans write.
+%
current_prolog_flag(Flag, Value) :- Flag == max_arity, !, Value = 1023.
current_prolog_flag(max_arity, 1023).
current_prolog_flag(Flag, Value) :- Flag == bounded, !, Value = false.
nonvar(Flag),
throw(error(type_error(atom, Flag), current_prolog_flag/2)). % 8.17.2.3 a
+%% set_prolog_flag(Flag, Value).
+%
+% Changes the internal value of the flag. To see the list of flags supported by Scryer Prolog,
+% check current\_prolog\_flag/2. The flags that are read only will fail if you try to change their values
set_prolog_flag(Flag, Value) :-
(var(Flag) ; var(Value)),
throw(error(instantiation_error, set_prolog_flag/2)). % 8.17.1.3 a, b
% control operators.
+%% fail.
+%
+% A predicate that always fails
fail :- '$fail'.
:- meta_predicate \+(0).
+%% \+(Goal)
+%
+% Succeeds if Goal fails
\+ G :- call(G), !, false.
\+ _.
-
+%% \=(?X, ?Y)
+%
+% Succeeds if X and Y can't be unified
X \= X :- !, false.
_ \= _.
:- meta_predicate once(0).
+%% once(Goal)
+%
+% Execute Goal (like call/1) but exactly once, ignoring any kind of alternative solutions the original predicate
+% could have generated.
once(G) :- call(G), !.
-
+%% repeat.
+%
+% This predicate enters an infinite loop, always succeeding and generating infinite choice points
repeat.
repeat :- repeat.
:- meta_predicate ->(0,0).
-
+%% ->(G1, G2)
+%
+% If-then and if-then-else constructs
G1 -> G2 :- control_entry_point((G1 -> G2)).
'$set_cp'(B),
call(G2).
+%% ;(G1, G2)
+%
+% Disjunction (or)
G1 ; G2 :- control_entry_point((G1 ; G2)).
staggered_sc(G, _) :- call(G).
staggered_sc(_, G) :- call(G).
-
+%% !.
+%
+% Cut operator. Discards the choicepoints created since entering the prediacate in which the operator appears.
+% Using cut is not recommended as it introduces a non-declarative flow of programming and makes it more difficult
+% to reason about the programs. Also restricts the ability to run the program with alternative execution strategies
!.
:- non_counted_backtracking set_cp/1.
set_cp(B) :- '$set_cp'(B).
+%% ,(G1, G2)
+%
+% Conjuction (and)
','(G1, G2) :- control_entry_point((G1, G2)).
:- non_counted_backtracking control_entry_point/1.
:- non_counted_backtracking (=..)/2.
+%% =..(Term, List)
+%
+% Univ operator. Term is a term whose functor is the head of the List, and the rest of arguments of Term
+% are in tail of the List. Example:
+%
+% ?- f(a, X) =.. List.
+% List = [f,a,X].
Term =.. List :-
univ_errors(Term, List, N),
univ_worker(Term, List, N).
; throw(error(instantiation_error, write_term/2))
).
-
+%% write_term(+Term, +Options).
+%
+% Write Term to the current output stream according to some output syntax options.
+% Options are specified in detail in write_term/3.
write_term(Term, Options) :-
current_output(Stream),
write_term(Stream, Term, Options).
+%% write_term(+Stream, +Term, +Options).
+%
+% Write Term to the stream Stream according to some output syntax options. The options avaibale are:
+% * `ignore\_ops(+Boolean)` if `true`, the generic term representation is used everywhere. In `false`
+% (default), operators do not use that generic term representation.
+% * `max\_depth(+N)` if the term is nested deeper than N, print the reminder as ellipses.
+% If N = 0 (default), there's no limit.
+% * `numbervars(+Boolean)` if true, replaces `$VAR(N)` variables with letters, in order. Default is false.
+% * `quoted(+Boolean)` if true, strings and atoms that need quotes to be valid Prolog synytax, are quoted. Default is false.
+% * `variable\_names(+List)` assign names to variables in term. List should be a list of terms of format `Name=Var`.
write_term(Stream, Term, Options) :-
parse_write_options(Options, [IgnoreOps, MaxDepth, NumberVars, Quoted, VNNames], write_term/3),
'$write_term'(Stream, Term, IgnoreOps, NumberVars, Quoted, VNNames, MaxDepth).
+%% write(+Term).
+%
+% Write Term to the current output stream using a syntax similar to Prolog
write(Term) :-
current_output(Stream),
'$write_term'(Stream, Term, false, true, false, [], 0).
+%% write(+Stream, +Term).
+%
+% Write Term to the stream Stream using a syntax similar to Prolog
write(Stream, Term) :-
'$write_term'(Stream, Term, false, true, false, [], 0).
+%% write_canonical(+Term).
+%
+% Write Term to the current output stream using canonical Prolog syntax. Can be read back as Prolog terms.
write_canonical(Term) :-
current_output(Stream),
'$write_term'(Stream, Term, true, false, true, [], 0).
+%% write_canonical(+Stream, +Term).
+%
+% Write Term to the stream Stream using canonical Prolog syntax. Can be read back as Prolog terms.
write_canonical(Stream, Term) :-
'$write_term'(Stream, Term, true, false, true, [], 0).
+%% writeq(+Term).
+%
+% Write Term to the current output stream using a syntax similar to write/1 but quoting the atoms that need to be
+% quoted according to Prolog syntax.
writeq(Term) :-
current_output(Stream),
'$write_term'(Stream, Term, false, true, true, [], 0).
+%% writeq(+Stream, +Term).
+%
+% Write Term to the stream Stream using a syntax similar to write/1 but quoting the atoms that need to be
+% quoted according to Prolog syntax.
writeq(Stream, Term) :-
'$write_term'(Stream, Term, false, true, true, [], 0).
throw(error(domain_error(read_option, E), _)).
-
+%% read_term(+Stream, -Term, +Options).
+%
+% Read Term from the stream Stream. It supports several options:
+% * `variables(-Vars)` unifies Vars with a list of variables in the term. Similar to do term\_variables/2 with the new term.
+% * `variable\_names(-Vars)` unifies Vars with a list `Name=Var` with Name describing the variable name and Var the variable itself that appears in Term.
+% * `singletons` similar to `variable\_names` but only reports variables occurring only once in Term.
read_term(Stream, Term, Options) :-
parse_read_term_options(Options, [Singletons, VariableNames, Variables], read_term/3),
'$read_term'(Stream, Term, Singletons, Variables, VariableNames).
+%% read_term(-Term, +Options).
+%
+% Read Term from the current input stream. It supports several options described in more detail in read\_term/3.
read_term(Term, Options) :-
current_input(Stream),
read_term(Stream, Term, Options).
+%% read(-Term).
+%
+% Read Term from the current input stream with default options. **NOTE** This is not a general predicate
+% to read input from a file or the user. Use other predicates like phrase\_from\_file/2 for that.
read(Term) :-
current_input(Stream),
read(Stream, Term).
% term_variables.
+%% term_variables(+Term, -Vars).
+%
+% Unify Vars with a list of unique variables that appear in Term. The variables are sorted depth-first
+% and left-to-right.
+%
+% ?- term_variables(f(X, Y, X, g(Z)), Vars).
+% Vars = [X, Y, Z].
term_variables(Term, Vars) :-
can_be_list(Vars, term_variables/2),
'$term_variables'(Term, Vars).
:- non_counted_backtracking catch/3.
+%% catch(Goal, Catcher, Recover).
+%
+% Calls Goal, but if it throws an exception that unifies with Catcher, Recover will be called instead
+% and the program will be resumed. Example:
+%
+% ?- catch(number_chars(X, "not_a_number"), error(syntax_error(_), _), X = 0).
+% X = 0.
catch(G,C,R) :-
'$get_current_block'(Bb),
catch(G,C,R,Bb).
:- non_counted_backtracking throw/1.
+%% throw(+Exception).
+%
+% Raise the exception Exception. The system looks for the innermost catch/3 for which Exception
+% unifies with Catcher. Example:
+%
+% ?- throw(custom_error(42)).
+% throw(custom_error(42)).
+% ?- catch(throw(custom_error(42)), custom_error(_), true).
+% true.
throw(Ball) :-
( var(Ball) ->
'$set_ball'(error(instantiation_error,throw/1))
:- non_counted_backtracking findall/3.
+%% findall(Template, Goal, Solutions).
+%
+% Unify Solutions with a list of all values that variables in Template can take in Goal.
+% findall/3 is equivalent to bagof/3 with all free variables scoped to the Goal (`^` operator)
+% except that bagof/3 fails when no solutions are found and findall/3 unifies with an empty list.
+% Example:
+%
+% f(1,2).
+% f(1,3).
+% f(1,4).
+% ?- findall(X-Y, f(X, Y), Solutions).
+% Solutions = [1-2,1-3,1-4].
findall(Template, Goal, Solutions) :-
error:can_be(list, Solutions),
'$lh_length'(LhLength),
:- non_counted_backtracking findall/4.
+%% findall(Template, Goal, Solutions0, Solutions1)
+%
+% Similar to findall/3 but returns the solutions as the difference list Solutions0-Solutions1.
findall(Template, Goal, Solutions0, Solutions1) :-
error:can_be(list, Solutions0),
error:can_be(list, Solutions1),
:- non_counted_backtracking bagof/3.
+%% bagof(Template, Goal, Solution).
+%
+% Unify Solution with a list of alternatives of the variables in Template coming from calling Goal.
+% If Goal has no solutions, the predicate fails.
+% If free variables that are not in Template appear in Goal, the predicate will backtrack over
+% the alternatives of those free variables. However, you can use the syntax `Var^Goal` to not bind
+% Var in Goal and prevent that.
+%
+% Example:
+%
+% f(1, 3).
+% f(2, 4).
+% ?- bagof(X, f(X, Y), Bag).
+% Y = 3, Bag = [1],
+% ; Y = 4, Bag = [2].
+% ?- bagof(X, Y^f(X, Y), Bag).
+% Bag = [1,2].
bagof(Template, Goal, Solution) :-
error:can_be(list, Solution),
term_variables(Template, TemplateVars0),
:- non_counted_backtracking setof/3.
+%% setof(Template, Goal, Solution).
+%
+% Similar to bagof/3 but Solution is sorted and duplicates are removed. Example:
+%
+% f(1, 2).
+% f(1, 3).
+% f(2, 4).
+% ?- setof(X, Y^f(X, Y), Set).
+% Set = [1, 2].
setof(Template, Goal, Solution) :-
error:can_be(list, Solution),
term_variables(Template, TemplateVars0),
; throw(error(type_error(callable, H), clause/2))
).
+%% clause(Head, Body).
+%
+% Succeeds if Head can be unified with a clause head and Body with its corresponding clause body.
clause(H, B) :-
( var(H) ->
throw(error(instantiation_error, clause/2))
:- meta_predicate asserta(:).
+%% asserta(Clause).
+%
+% Asserts (inserts) a new clause (rule or fact) into the current module.
+% The clause will be inserted at the beginning of the module.
asserta(Clause0) :-
loader:strip_subst_module(Clause0, user, Module, Clause),
iso_ext:asserta(Module, Clause).
:- meta_predicate assertz(:).
+%% assertz(Clause).
+%
+% Asserts (inserts) a new clause (rule or fact) into the current module.
+% The clase will be inserted at the end of the module.
assertz(Clause0) :-
loader:strip_subst_module(Clause0, user, Module, Clause),
iso_ext:assertz(Module, Clause).
:- meta_predicate retract(:).
+%% retract(Clause)
+%
+% Retracts (deletes) a clause present in the current module.
+% It only affects dynamic predicates.
retract(Clause0) :-
loader:strip_module(Clause0, Module, Clause),
( Clause \= (_ :- _) ->
:- meta_predicate retractall(:).
+%% retractall(Head)
+%
+% Retracts (deletes) all clauses that unify which head unifies with Head
+% It only affects dynamic predicates.
retractall(Head) :-
retract_clause(Head, _),
false.
:- meta_predicate abolish(:).
+%% abolish(Pred).
+%
+% Pred should satisfy: `Pred = Name/Arity`.
+% Deletes all clauses of a predicate with name Name and arity Arity.
+% It only affects dynamic predicates
abolish(Pred) :-
( var(Pred) ->
throw(error(instantiation_error, abolish/1))
'$get_next_db_ref'(RName, RArity, RRName, RRArity),
'$iterate_db_refs'(RRName, RRArity, Name/Arity).
-
+%% current_predicate(Pred).
+%
+% Pred must satisfy: `Pred = Name/Arity`.
+% Pred unifies with a predicate description of a predicate that is currently loaded at the moment.
+% It can be used to check for existence of a predicate or to enumerate all loaded predicates
current_predicate(Pred) :-
( var(Pred) ->
'$get_next_db_ref'(RN, RA, _, _),
can_be_op_specifier(Spec) :- op_specifier(Spec).
+%% current_op(Priority, Spec, Op)
+%
+% Succeeds if there's an operator defined with name Op, with spec Spec and priority Priority.
+% Can be used to find all operators currently defined.
current_op(Priority, Spec, Op) :-
( can_be_op_priority(Priority),
can_be_op_specifier(Spec),
'$op'(Priority, OpSpec, Op).
+%% op(Priority, Spec, Op)
+%
+% Declares an operated named Op, with priority Priority and a spec Spec.
+% The priority is an integer between 0 (null) and 1200.
+% Spec can be: `xf`, `yf`, `xfx`, `xfy`, `yfx`, `fy` and `fx` where f indicates the position of the
+% operator and x and y the arguments.
op(Priority, OpSpec, Op) :-
( var(Priority) ->
throw(error(instantiation_error, op/3)) % 8.14.3.3 a)
!
; throw(error(type_error(list, Op), op/3)) % 8.14.3.3 f)
).
-
+%% halt.
+%
+% Exits the Prolog system with exit code 0
halt :- halt(0).
+
+%% halt(+ExitCode)
+%
+% Exits the Prolog system with exit code N
halt(N) :-
( var(N) ->
throw(error(instantiation_error, halt/1)) % 8.17.4.3 a)
; throw(error(domain_error(exit_code, N), halt/1))
).
-
+%% atom_length(+Atom, -Length).
+%
+% Succeeds when Atom is an atom of Length characters. Example:
+%
+% ?- atom_length(marseille, N).
+% N = 9.
atom_length(Atom, Length) :-
( var(Atom) ->
throw(error(instantiation_error, atom_length/2)) % 8.16.1.3 a)
; throw(error(type_error(atom, Atom), atom_length/2)) % 8.16.1.3 b)
).
-
+%% atom_chars(?Atom, ?Chars).
+%
+% Relates an atom with a string in chars representation. It can be used to convert
+% between atoms and strings. Examples:
+%
+% ?- atom_chars(marseille, X).
+% X = "marseille".
+% ?- atom_chars(X, "marseille").
+% X = marseille.
atom_chars(Atom, List) :-
'$skip_max_list'(_, _, List, Tail),
( ( Tail == [] ; var(Tail) ) ->
; throw(error(type_error(atom, Atom), atom_chars/2))
).
+%% atom_codes(?Atom, ?Codes).
+%
+% Relates an atom with a string in codes representation. It can be used to convert
+% between atoms and strings. However, codes is not the default representation of double quoutes
+% strings in Scryer Prolog. Examples:
+%
+% ?- atom_codes(marseille, X).
+% X = [109,97,114,115,101,105,108,108,101].
+% ?- atom_codes(X, [109,97,114,115,101,105,108,108,101]).
+% X = marseille.
atom_codes(Atom, List) :-
'$skip_max_list'(_, _, List, Tail),
( ( Tail == [] ; var(Tail) ) ->
; throw(error(type_error(atom, Atom), atom_codes/2))
).
-
+%% atom_concat(?A1, ?A2, ?A12)
+%
+% Similar to append/3 but operating on atom characters. Example:
+%
+% ?- atom_concat(a, X, ab).
+% X = b.
atom_concat(Atom_1, Atom_2, Atom_12) :-
error:can_be(atom, Atom_1),
error:can_be(atom, Atom_2),
atom_chars(Atom_12, Atom_12_Chars)
).
-
+%% sub_atom(+Atom, ?Before, ?Length, ?After, ?SubAtom).
+%
+% Relates an atom to a subatom inside with some key properties:
+% * SubAtom starts at Before characters (0-based) from Atom
+% * SubAtom has Length characters
+% * After SubAtom there are After characters in Atom
+% Example:
+%
+% ?- sub_atom(abcdefg, 2, 3, X, SubAtom).
+% X = 2, SubAtom = cde.
sub_atom(Atom, Before, Length, After, Sub_atom) :-
error:must_be(atom, Atom),
error:can_be(atom, Sub_atom),
atom_chars(Sub_atom, LengthChars)
).
-
+%% char_code(?Char, ?Code)
+%
+% Relates a Char to its Code (an integer). Example:
+%
+% ?- char_code(a, X).
+% X = 97.
char_code(Char, Code) :-
( var(Char) ->
( var(Code) ->
; throw(error(type_error(character, Char), char_code/2))
).
+%% get_char(-Char).
+%
+% From the current input stream, unify Char with the next character.
+% When there are no more characters to read, Char unifies with `end\_of\_file`.
get_char(C) :-
error:can_be(in_character, C),
current_input(S),
'$get_char'(S, C).
+%% get_char(+Stream, -Char).
+%
+% From the stream Stream, unify Char with the next character.
+% When there are no more characters to read, Char unifies with `end\_of\_file`.
get_char(S, C) :-
error:can_be(in_character, C),
'$get_char'(S, C).
; codes_or_vars(Cs, PI)
).
-
+%% number_chars(?N, ?Chars).
+%
+% Relates a number and its representation as list of chars (string).
+% Throws an error if Chars is not the representation of a number.
+% Examples:
+%
+% ?- number_chars(42, X).
+% X = "42".
+% ?- number_chars(X, "42").
+% X = 42.
+% ?- number_chars(X, "not_a_number").
+% error(syntax_error(cannot_parse_big_int),number_chars/2:0).
number_chars(N, Chs) :-
( ground(Chs) ->
can_be_number(N, number_chars/2),
error:must_be(list, Ns),
lists:maplist(error:must_be(integer), Ns).
-
+%% number_codes(?N, ?Codes).
+%
+% Relates a number and its representation as list of codes.
+% Throws an error if Codes is not the representation of a number.
+% Examples:
+%
+% ?- number_codes(42, X).
+% X = [52,50].
+% ?- number_codes(X, [52,50]).
+% X = 42.
+% ?- number_codes(X, [65]).
+% error(syntax_error(cannot_parse_big_int),number_codes/2:0).
number_codes(N, Chs) :-
( ground(Chs) ->
can_be_number(N, number_codes/2),
'$number_to_codes'(N, Chs)
).
-
+%% subsumes_term(General, Specific)
+%
+% Succeeds if General can be made equivalent to Specific by only binding variables
+% in Generic. The implementation unifies with occurs check always and ensures that
+% the variables of Specific did not change. Some examples:
+%
+% ?- subsumes_term(f(A, A), f(2, 2)).
+% true.
+% ?- subsumes_term(f(A, 2), f(2, A)).
+% false.
subsumes_term(General, Specific) :-
\+ \+ (
term_variables(Specific, SVs1),
SVs1 == SVs2
).
-
+%% unify_with_occurs_check(?X, ?Y).
+%
+% Unify with occurs check.The occurs check prevents the creation cyclic terms but is
+% computationally more expensive. The (=)/2 operator can also do occurs check if enabled
+% via set\_prolog\_flag/2. Example:
+%
+% ?- A = f(A).
+% A = f(A).
+% ?- unify_with_occurs_check(A, f(A)).
+% false.
unify_with_occurs_check(X, Y) :- '$unify_with_occurs_check'(X, Y).
-
+%% current_input(-Stream).
+%
+% Unifies with the current input stream.
current_input(S) :- '$current_input'(S).
+%% current_output(-Stream).
+%
+% Unifies with the current output stream.
current_output(S) :- '$current_output'(S).
-
+%% set_input(+Stream).
+%
+% Sets the current input stream to Stream.
set_input(S) :-
( var(S) ->
throw(error(instantiation_error, set_input/1))
; '$set_input'(S)
).
+%% set_output(Stream).
+%
+% Sets the current output stream to Stream.
set_output(S) :-
( var(S) ->
throw(error(instantiation_error, set_output/1))
parse_stream_options_(E, _) :-
throw(error(domain_error(stream_option, E), _)). % 8.11.5.3i)
-
+%% open(+File, +Mode, +Stream).
+%
+% Equivalent to `open(File, Mode, Stream, [])`.
open(SourceSink, Mode, Stream) :-
open(SourceSink, Mode, Stream, []).
-
+%% open(+File, +Mode, -Stream, +StreamOptions).
+%
+% Opens a file named File with a Mode and StreamOptions, and returns a Stream
+% that can be used by other predicates to read and write (depending on Mode).
+%
+% Mode can be: `read`, `write` or `append`. `read` creates a Stream
+% that is read-only, `write` is write-only and `append`
+% is write-only but at the end of the file.
+%
+% The following options are available:
+%
+% * `alias(+Alias)`: Set an alias to the stream
+% * `eof\_action(+Action)`: Defined what happens if the end of the stream is reached. Values: `error`, `eof_code` and `reset`.
+% * `reposition(+Boolean)`: Specifies whether repositioning is required for the stream. `false` is the default.
+% * `type(+Type)`: Type can be `text` or `binary`. Defines the type of the stream, if it's optimized for plain text
+% or just binary
+%
+% Example:
+%
+% ?- open("README.md", read, S, []), get_n_chars(S, 20, C).
+% S = '$stream'(0x55dece980218), C = "\n# Scryer Prolog\n\nS ..."
open(SourceSink, Mode, Stream, StreamOptions) :-
( var(SourceSink) ->
throw(error(instantiation_error, open/4)) % 8.11.5.3a)
parse_close_options_(E, _) :-
throw(error(domain_error(close_option, E), _)).
-
+%% close(+Stream, +CloseOptions).
+%
+% Closes a stream. It takes a CloseOptions list. The only option available is `force` which takes a `true`
+% or `false`.
close(Stream, CloseOptions) :-
parse_close_options(CloseOptions, [Force], close/2),
'$close'(Stream, CloseOptions).
+%% close(+Stream).
+%
+% Closes a stream. Equivalent to `close(Stream, []).`.
close(Stream) :-
'$close'(Stream, []).
-
+%% flush_output(+Stream).
+%
+% Flushes the output of the stream Stream
flush_output(S) :-
'$flush_output'(S).
+%% flush_output.
+%
+% Flushes the output of the current output stream
flush_output :-
current_output(S),
'$flush_output'(S).
-
+%% get_byte(+Stream, -Byte).
+%
+% From the stream Stream, unify Byte with the next byte (an integer between 0 and 255)
+% When there are no more bytes to read, Byte unifies with -1.
get_byte(S, B) :-
'$get_byte'(S, B).
+%% get_byte(-Byte).
+%
+% From the current input stream, unify Byte with the next byte (an integer between 0 and 255)
+% When there are no more bytes to read, Byte unifies with -1.
get_byte(B) :-
current_input(S),
'$get_byte'(S, B).
-
+%% put_char(+Char).
+%
+% Writes to the current output stream the character Char.
put_char(C) :-
current_output(S),
'$put_char'(S, C).
+%% put_char(+Stream, +Char).
+%
+% Writes to the stream Stream the character Char.
put_char(S, C) :-
'$put_char'(S, C).
-
+%% put_byte(+Byte).
+%
+% Writes to the current output stream the byte Byte (should be an integer between 0 and 255).
put_byte(C) :-
current_output(S),
'$put_byte'(S, C).
+%% put_byte(+Stream, +Byte).
+%
+% Writes to the stream Stream the byte Byte (should be an integer between 0 and 255).
put_byte(S, C) :-
'$put_byte'(S, C).
-
+%% put_code(+Code).
+%
+% Writes to the current output stream the character represented by code Code
put_code(C) :-
current_output(S),
'$put_code'(S, C).
+%% put_code(+Stream, +Code).
+%
+% Writes to the stream Stream the character represented by code Code
put_code(S, C) :-
'$put_code'(S, C).
-
+%% get_code(-Code).
+%
+% From the current input stream, unify Code with the character code of the next character.
+% When there are no more characters to read, Code unifies with -1.
get_code(C) :-
current_input(S),
'$get_code'(S, C).
+%% get_code(+Stream, -Code).
+%
+% From the stream Stream, unify Code with the character code of the next character.
+% When there are no more characters to read, Code unifies with -1.
get_code(S, C) :-
'$get_code'(S, C).
-
+%% peek_byte(+Stream, -Byte).
+%
+% From the stream Stream, unify Byte with the next byte. However, it doesn't move the stream
+% position, allowing it to be read again.
peek_byte(S, B) :-
'$peek_byte'(S, B).
+%% peek_byte(-Byte).
+%
+% From the current input stream, unify Byte with the next byte. However, it doesn't move the stream
+% position, allowing it to be read again.
peek_byte(B) :-
current_input(S),
'$peek_byte'(S, B).
-
+%% peek_code(-Code).
+%
+% From the current input stream, unify Code with the character code of the next character.
+% However, it doesn't move the stream position, allowing it to be read again.
peek_code(C) :-
current_input(S),
'$peek_code'(S, C).
+%% peek_code(+Stream, -Code).
+%
+% From the stream Stream, unify Code with the character code of the next character.
+% However, it doesn't move the stream position, allowing it to be read again.
peek_code(S, C) :-
'$peek_code'(S, C).
-
+%% peek_char(-Char).
+%
+% From the current input stream, unify Char with the next character.
+% However, it doesn't move the stream position, allowing it to be read again.
peek_char(C) :-
current_input(S),
'$peek_char'(S, C).
+%% peek_char(+Stream, -Char).
+%
+% From the stream Stream, unify Char with the next character.
+% However, it doesn't move the stream position, allowing it to be read again.
peek_char(S, C) :-
'$peek_char'(S, C).
stream_iter_(S0, S)
).
-
+%% stream_property(Stream, StreamProperty).
+%
+% For stream Stream, StreamProperty is a property that applies to that stream.
+% StreamProperty can be one of the following:
+% * `input` if stream is an input stream.
+% * `output` if stream is an output stream.
+% * `input\_output` if stream is both an input and an output stream.
+% * `alias(-Alias)` if the stream has an associated alias.
+% * `file\_name(-FileName)` if Stream is associated to a file, unifies with the name of the file
+% * `mode(-Mode)`: Mode unifies with the mode of the stream: `read`, `write` or `append`.
+% * `position(position_and_lines_read(P, L))` current position of the stream.
+% * `end\_of\_stream(-X)` where X can be `not`, `at` or `past` depending if the stream has ended or not.
+% * `eof\_action(-X)` where X can be `error`, `eof_code` or `reset` depending on the action that will happen on the end of the file.
+% * `reposition(-Boolean)` specifies if reposition has been enabled for this stream.
+% * `type(-Type)` where Type can be `text` or `binary`.
stream_property(S, P) :-
( nonvar(P), \+ check_stream_property(P, _, _) ->
throw(error(domain_error(stream_property, P), stream_property/2))
'$stream_property'(S, PropertyName, PropertyValue)
).
-
+%% at_end_of_stream(+Stream).
+%
+% Succeeds if the stream Stream has ended
at_end_of_stream(S_or_a) :-
( var(S_or_a) ->
throw(error(instantiation_error, at_end_of_stream/1))
stream_property(S, end_of_stream(E)),
( E = at -> true ; E = past ).
+%% at_end_of_stream.
+%
+% Succeeds if the current input stream has ended
at_end_of_stream :-
current_input(S),
stream_property(S, end_of_stream(E)),
!,
( E = at ; E = past ).
-
+%% set_stream_position(+Stream, +Position).
+%
+% Sets the current position of the stream Stream to Position.
set_stream_position(S_or_a, Position) :-
( var(Position) ->
throw(error(instantiation_error, set_stream_position/2))
; throw(error(domain_error(stream_position, Position), set_stream_position/2))
).
+%% callable(X).
+%
+% Succeeds if X is bound o an atom or a compund term.
callable(X) :-
( nonvar(X), functor(X, F, _), atom(F) ->
true
; false
).
+%% nl.
+%
+% Writes a new line character to the current output stream.
nl :-
current_output(Stream),
nl(Stream).
+%% nl(+Stream).
+%
+% Writes a new line character to the stream Stream.
nl(Stream) :-
put_char(Stream, '\n').
+%% error(ErrorTerm, ImpDef).
+%
+% Throws an exception of the following structure: `error(ErrorTerm, ImpDef)`.
error(Error_term, Imp_def) :-
throw(error(Error_term, Imp_def)).
projects / scryer-prolog.git / commitdiff