comparison prolog/utils.pl @ 0:0dd31a8c66bd

Initial check in to Mercurial, V.1

+% Some general utilities
+
+:- module(utils,[
+
+	% type testing and enumeration
+		natural/1		% test or enumerate natural numbers
+	,	isfinite/1     % check number is non NaN or Inf
+	,	int/1				% test or enumerate integers
+	,	in/2
+
+	% mathematical utilities
+	,	max/3
+	,	min/3
+
+	% list utilities
+	,	list_idx1_member/3  % like nth1 but more useful argument order
+	,	apply_to_nth1/4
+	,	measure/3      % match list lengths
+	,  equal_length/2 % match 2 list lengths
+	,	getopts/2
+	,  rep/3          % make a list of repeats of the same term
+	,  cons/3         % list constructror
+	,	decons/3       % list deconstructor
+
+	% comma lists
+	,	cl_list/2
+	,	cl_list_vt/2
+	,	cl_length/2
+	,	cl_length_vt/2
+	,	cl_member/2
+
+
+	% term manipulation
+	,	copy_head/2    % check terms for same head and arity
+	,	unify_args/5
+	,	reinstatevars/3
+	,	reinstatevars/4
+
+	% formatting and parsing
+	,	aphrase/2		% like phrase but makes an atom instead of a string
+	,	aphrase/3		% like aphrase but takes code list
+	,	print_list/1	% writes each element on a new line 
+	,	printq_list/1	% as print_list but quotes atom as necessary
+	,	print_numbered_list/1
+	
+	% database management
+	,	extensible/1	% declare dynamic multifile predicate
+	,	bt_assert/1
+	,	bt_retract/1
+	,	strict_assert/1
+	,	strict_retract/1
+	,	browse/2			% browse predicate with unknown arity
+	,	current_state/2
+	,	set_state/2 
+
+	% file system utilities
+	,	dir/2				% directory listing
+	,	path_atom/2		% expand paths
+	,	expand_path/2	% expand paths
+
+	% operating system 
+	,	open_with/2		% apply shell command to a file (SIDE EFFECTS)
+	,	open_with/3		% apply shell command to a file with options (SIDE EFFECTS)
+	,	shellcmd/2		% apply shell command to arguments
+	,	open_/1			% open with 'open' command (Mac OS X).
+	, 	fmt_shellcmd/3 % format a shell command with switches and args
+	,	hostname/1
+
+	% user interaction
+	,	read_char_echo/1 % read one character and echo it immediately
+	,	get_key/2		% read and validate keypress
+	,	userchk/1		% unary predicate which allows user to force failure
+	,	prompt_for_key/3
+
+	% ---- high order stuff ----
+	
+	% modes of computation
+	,	retry/1			% keep trying until success
+	,  parallel/1 		% parallel computation using threads
+	,	bt_call/2		% Construct backtrackable operation
+	,	on_backtracking/1
+
+	% iteration
+	,	exhaust/1		% trigger all solutions to a goal (SIDE EFFECTS)
+	,	iterate/3		% apply predicate recursively till failure
+
+	% mapping
+	,	for_naturals/2 % call predicate with natural numbers N down to 1
+	,	mapints/2      % call predicate with integers
+	,	mapints/3      
+	,	mapargs/2, mapargs/3, mapargs/4
+	,	mapargs_x/4, mapargs_x/5, mapargs_x/6
+	,	mapargs_xx/6
+	,	sfold/4			% structural fold for lists
+	,	take/3
+	,	drop/3
+	,	drop_while/3
+	,	take_while/3
+
+	% lambda expressions
+	,	mcall/2, mcall/3, mcall/4
+
+	]).
+
+/** <module> General utilities
+
+The predicates in this module can be divided into several groups as listed
+below.
+
+---+++ Type testing and enumeration
+	*	natural/1		- test or enumerate natural numbers
+	*	isfinite/1     - check number is non NaN or Inf
+	*	int/1				- test or enumerate integers
+	*	in/2
+
+---+++	 mathematical utilities
+	*	max/3
+	*	min/3
+
+---+++	 list utilities
+	*	list_idx1_member/3  % like nth1 but more useful argument order
+	*	measure/3      - match list lengths
+	*	equal_length/2 - match two list lenghts
+	*	getopts/2
+	*  rep/3          - make a list of repeats of the same term
+	*  cons/3         - make list from head and tail
+	*  decons/3       - get head and tail from list
+
+---+++ term manipulation
+	*	copy_head/2    - check terms for same head and arity
+	*	unify_args/5
+	*	reinstatevars/3
+	*	reinstatevars/4
+
+---+++ formatting and parsing
+	*	aphrase/2		- like phrase but makes an atom instead of a string
+	*	aphrase/3		- like aphrase but takes code list
+	*	print_list/1	- write/1 each element, one per line
+	*	printq_list/1	- as print_list but quotes atom as with writeq/1
+	*	print_numbered_list/1 - as print_list/1 but with line numbers
+	
+---+++ database management
+	*	extensible/1	- declare dynamic multifile predicate
+	*	bt_assert/1
+	*	bt_retract/1
+	*	strict_assert/1
+	*	strict_retract/1
+	*	browse/2			- browse predicate with unknown arity
+	*	current_state/2
+	*	set_state/2 
+
+---+++ file system utilities
+	*	dir/2				- directory listing
+	*	path_atom/2		- expand paths
+	*	expand_path/2	- expand paths
+
+---+++ operating system 
+	*	open_with/2		- apply shell command to a file (SIDE EFFECTS)
+	*	open_with/3		- apply shell command to a file with options (SIDE EFFECTS)
+	*	shellcmd/2		- apply shell command to arguments
+	*	open_/1			- open with 'open' command (Mac OS X).
+	* 	fmt_shellcmd/3 - format a shell command with switches and args
+	*	hostname/1
+
+---+++ user interaction
+	*	read_char_echo/1 - read one character and echo it immediately
+	*	get_key/2		- read and validate keypress
+	*	userchk/1		- unary predicate which allows user to force failure
+	*	prompt_for_key/3 - print message and get keypress from user
+
+---+++ High order stuff
+	
+---++++ modes of computation
+	*	retry/1			- keep trying until success
+	*  parallel/1 		- parallel computation using threads
+	*	bt_call/2		- Construct backtrackable operation
+	,	on_backtracking/1
+
+---++++ iteration
+	*	exhaust/1		- trigger all solutions to a goal (SIDE EFFECTS)
+	*	iterate/3		- apply predicate recursively till failure
+
+---++++ mapping
+	*	for_naturals/2 - call predicate with natural numbers N down to 1
+	*	mapints/2      - call predicate with integers
+	*	mapints/3      
+	*	mapargs/2, mapargs/3, mapargs/4
+	*	mapargs_xx/6
+	*	sfold/4			- structural fold for lists
+	*	take/3
+	*	drop/3
+	*	drop_while/3
+	*	take_while/3
+
+---++++ lambda expressions
+	*	mcall/2, mcall/3, mcall/4
+ */
+
+:- use_module(library(ops)).
+
+:- meta_predicate
+		exhaust(0)
+	,	retry(0)
+	,	iterate(2,?,?)
+	,	drop_while(1,?,?)
+	,	take_while(1,?,?)
+	,	apply_to_nth1(?,2,?,?)
+	,	for_naturals(+,1)
+	,	for_ints(+,+,1)
+	,	mapints(1,?)
+	,	mapints(2,?,?)
+	,	mapargs(1,?)
+	, 	mapargs(2,?,?)
+	,	mapargs(3,?,?,?)
+	,	mapargs_x(+,+,1,?)
+	, 	mapargs_x(+,+,2,?,?)
+	,	mapargs_x(+,+,3,?,?,?)
+	,	mapargs_xx(2,?,?,?,?,?)
+	,	on_backtracking(0)
+	,	bt_call(0,0)
+	,	bt_assert(:)
+	,	bt_retract(:)
+	,	strict_assert(:)
+	,	strict_retract(:)
+	,	extensible(:)
+	,	aphrase(2,?)
+	,	aphrase(2,?,?)
+	.
+
+:- multifile user:path/2.
+:- multifile user:demo/1.
+:- dynamic current_state/2.
+
+
+%% extensible(+P) is det.
+%  declares 'extensible' predicates, ie ones that can have new clauses
+%  added in other files. Equivalent to dynamic(P), multifile(P).
+extensible(P) :- dynamic(P), multifile(P).
+
+
+%% natural(+N) is semidet.
+%% natural(-N:natural) is multi.
+%
+% Means N is a natural number (includes 0). If N is
+% a variable, succeeds an infinite number of times on backtracking,
+% returning all natural numbers.
+natural(N) :- (var(N) -> between(0,inf,N); integer(N), N>=0).
+
+
+%% int(+N) is semidet.
+%% int(-N:integer) is multi.
+%
+% Means N is an integer. If N is
+% a variable, succeeds an infinite number of times on backtracking,
+% returning all integers starting at zero and interleaving positive
+% and negative values.
+int(N)     :- nonvar(N), integer(N).
+int(N)     :- var(N), (N=0; (between(1,inf,M), (N=M; N is -M))).
+
+
+%% isfinite(+N:number) is semidet.
+%
+%  Succeeds when N is a finite number.
+isfinite(N):- catch(_ is N+0,error(_,_),fail). % !! workable hack
+
+
+%% in(+X,Set) is semidet.
+%% in(-X,Set) is nondet.
+%
+%  Simple testing and enumration of values in some sets.
+%  Set can be
+%  * {A,B,_}
+%    Explicit list of values.
+%  * natural
+%    Natural numbers starting from 0.
+%  * integer
+%    Natural numbers.
+%  * real
+%    Real (floating point) numbers.
+%  * A..B
+%    Integer range from A to B inclusive.
+%  * A--B
+%    Closed interval [A,B].
+X in A--\B   :- X in A--(\B).
+X in \A--(\B):- !, ch(A<X), ch(X<B).
+X in \A--B   :- !, ch(A<X), ch(X=<B).
+X in A--(\B) :- !, ch(A=<X), ch(X<B).
+X in A--B    :- !, ch(A=<X), ch(X=<B).
+X in A..B    :- integer(A), integer(B), between(A,B,X). 
+X in {CList} :- member_clist(X,CList).
+X in natural :- natural(X). % enumerate!
+X in integer :- int(X). % enumerates!
+X in real    :- number(X). % same as X :: real
+
+
+ch(_  =<inf) :- !.
+ch(inf=< _ ) :- !, fail.
+ch(-inf=< _) :- !.
+ch(_ =<(-inf)) :- !, fail.
+ch(A=<B) :- !, A=<B.
+
+ch(inf<_  ) :- !, fail.
+ch(_  <inf) :- !.
+ch(_   <(-inf)) :- !, fail.
+ch(-inf<_     ) :- !.
+ch(A<B) :- !, A<B.
+
+
+
+%% exhaust(:Goal) is det.
+%
+%  Repeat Goal until failure, then succeed.
+exhaust(Q) :- call(Q), fail; true.
+
+%% iterate(+P:pred(A,A), X:A, Y:A) is semidet.
+%  apply P recursively to X until failure, then return final value Y.
+iterate(P,X,Y) :- call(P,X,Z) -> iterate(P,Z,Y); Y=X.               
+
+%% sfold(Functor,Initial,L:list,Final) is semidet.
+% *Structural* fold applied to a term,
+% rather than a relational fold using a predicate name.
+sfold(_,E,[],E).
+sfold(O,E,[X|XX],R) :- R=..[O,X,YY], sfold(O,E,XX,YY).
+
+
+%% dir( +Pattern, -File) is nondet.
+%
+% Directory listing for directory matching Pattern. File
+% names are returned one by one on backtracking.
+dir(Pattern,File) :-
+	expand_file_name(Pattern,List),
+	member(File,List).
+
+
+%% path_atom( +Spec:path_expr, -Path:atom) is nondet.
+%
+%  Expand a 'path expression' into a flat path (an atom).
+%  A path expression is defined by:
+%  ==
+%  path_expr ---> atom            % literal path component name
+%               ; path_expr/atom  % child of path_expr
+%               ; path_macro      % a previously defined abbr for a path.
+%  ==
+%  A path_macro is defined using path/2.
+
+path_atom(P,C) :- path(P,C), atom(C).
+	
+path_atom(PA/B,C) :-
+	once((nonvar(C); nonvar(B); nonvar(PA))),
+	path_atom(PA,A),
+	concat3atoms(A,'/',B,C).
+
+
+path_atom(Path,Atom) :- path(Path, Def), \+atom(Def), path_atom(Def,Atom).
+path_atom(Path,Atom) :-
+	nonvar(Path),
+	\+path(Path,_),
+	Path\=_/_,
+	Atom=Path.
+
+concat3atoms(A,B,C,ABC) :-
+	nonvar(A), nonvar(B), nonvar(C), !, concat_atom([A,B,C],ABC).
+
+concat3atoms(_,_,_,ABC) :- var(ABC), !, fail.
+concat3atoms(A,B,C,ABC) :- nonvar(C), !, atom_concat(AB,C,ABC), atom_concat(A,B,AB). 
+concat3atoms(A,B,C,ABC) :- nonvar(A), !, atom_concat(A,BC,ABC), atom_concat(B,C,BC). 
+concat3atoms(A,B,C,ABC) :-
+	maplist(atom_codes,[B,ABC],[BX,ABCX]),
+	append(ABX,CX,ABCX),
+	append(AX,BX,ABX),
+	maplist(atom_codes,[A,C],[AX,CX]).
+
+%% expand_path( +P:path_expr, -FP:atom) is semidet.
+%
+%  Expand path_exp including wildcards to fully qualified path
+expand_path(P,FP) :- path_atom(P,PP), expand_file_name(PP,[FP]).
+
+
+%% open_with( +Program:atom, +Thing:path_expr, +Options:list) is semidet.
+%% open_with( +Program:atom, +Thing:path_expr) is semidet.
+%
+%  The only option is bg, which adds "&" to make command execute in background.
+open_with(Q,P) :- open_with(Q,P,[]).
+open_with(Q,P,Opts) :- 
+	expand_path(P,FP), 
+	(member(bg,Opts) -> OO=' &'; OO=''),
+	sformat(S,'~w ~q~w',[Q,FP,OO]), 
+	shell(S).
+
+%% open_( +Thing:path_expr) is semidet.
+%  Equivalent to open_with(open,Thing).
+open_(P) :- open_with(open,P).
+
+%% shellcmd( +Head:atom, +Args:list(atom)) is det.
+%
+% Execute a shell command on a given list of arguments
+shellcmd(Head,Args) :-
+	concat_atom([Head|Args],' ',Cmd),
+	shell(Cmd,_Status).
+
+%% fmt_shellcmd( +Prog:atom, +Args:list(shellarg), -Cmd) is det.
+% make a shell command string.
+fmt_shellcmd(Prog,Args,Cmd) :-
+	phrase(utils:shellcmd(l_(Args)),FArgs),
+	concat_atom([Prog|FArgs],' ',Cmd).
+
+shellcmd(l_([]))    --> !, [].
+shellcmd(l_([H|T])) --> !, shellcmd(H), shellcmd(l_(T)).
+shellcmd(s(N,V))  --> !, shellcmd(s(N)), shellcmd(V).
+shellcmd(q(X)) --> !, { concat_atom(['"',X,'"'],A) }, [A].
+shellcmd(s(N)) --> !, { 
+	(atom_codes(N,[_]) -> F='-' ; F='--'),
+	atom_concat(F,N,A) }, [A].
+shellcmd(l(X)) --> [X].
+
+
+
+%% read_char_echo( -C:atom) is det.
+%
+%  Read a single character from the current input,
+%  echo it to the output.
+read_char_echo(C) :-
+	get_single_char(Code), 
+	put_code(Code), flush_output,
+	char_code(C,Code). 
+
+
+
+%% set_state( +Key, +Value) is det.
+%
+% Maintains a mutable global set of Key-Value pairs, sets the value
+% associated with Key to Value.
+set_state(Flag,Value) :-
+	ground(Flag),
+	retractall(current_state(Flag,_)),
+	assert(current_state(Flag,Value)).
+
+
+%% current_state( -Key, -Value) is nondet.
+%% current_state( +Key, -Value) is semidet.
+%
+%  Lookup the value associated with Key, or enumerate all the
+%  key value pairs.
+
+
+
+%% parallel( +List:list(query)) is semidet.
+%
+% Use this by giving a list of queries of the form
+%    [Vars2:Goal, Vars2:Goal2, ...]
+% where Vars is the term that each thread must return
+% when it has finished computing its Goal. The 
+% parallel predicate finishes when all the threads
+% have finished, and should result in all the Vars
+% being bound appropriately. 
+
+parallel(Queries) :-
+	maplist(async,Queries,Collecters),
+	maplist(call,Collecters).
+
+% these are used to initiate and wait for each
+% computation thread.
+async_collect(Id,X:_) :- thread_join(Id,exited(X)).
+async(X:Goal,utils:async_collect(Id,X:_)) :-
+	thread_create((Goal,thread_exit(X)),Id,[]).
+
+%% browse( +PredSpec, -Goal) is nondet.
+%
+%  PredSpec is a term like (PredicateName/Arity). Goal
+%  is unified with solutions of PredicateName/Arity.
+browse(P/A,Goal) :-
+	current_predicate(P/A),
+	length(L,A),
+	Goal=..[P|L],
+	call(Goal).
+
+
+
+%% aphrase(P:phrase(code), -A:atom, +S:list(code)) is nondet.
+%% aphrase(P:phrase(code), +A:atom, -S:list(code)) is nondet.
+%% aphrase(P:phrase(code), -A:atom, -S:list(code)) is nondet.
+%% aphrase(P:phrase(code), -A:atom) is nondet.
+%
+%  Generate or parse an atom using given DCG phrase P.
+%  aphrase(P,A) is equivalent to aphrase(P,A,_).
+aphrase(X,A) :- aphrase(X,A,_). 
+aphrase(X,A,S) :- 
+	(	ground(A) 
+	->	atom_codes(A,S), phrase(X,S)
+	;	phrase(X,S), atom_codes(A,S)).
+
+
+%% print_list( +L:list) is det.
+%
+%  Print a list, one item per line.
+print_list([]) :- writeln('~'), nl.
+print_list([H|T]) :- print(H), nl, print_list(T).
+
+%% printq_list( +L:list) is det.
+%
+%  Print a list, one item per line, as with writeq/1.
+printq_list([]) :- writeln('~'), nl.
+printq_list([H|T]) :- writeq(H), nl, printq_list(T).
+
+%% print_numbered_list( +L:list) is det.
+%
+%  Print a list with numbered lines.
+print_numbered_list(L) :- 
+	length(L,Max), 
+	number_codes(Max,MC),
+	length(MC,Width),
+	print_num_list(Width,1,L).
+
+print_num_list(_,_,[]) :- nl.
+print_num_list(Width,N,[H|T]) :- succ(N,M),
+	copy_term(H,H1),
+	numbervars(H1,0,_),
+	number_codes(N,NC), " "=[Pad],
+	padleft(Pad,Width,NC,PNC),
+	format('~s. ~q\n',[PNC,H1]), 
+	print_num_list(Width,M,T).
+
+padleft(_,W,In,In) :- length(In,W).
+padleft(P,W,In,[P|Out]) :- succ(V,W), padleft(P,V,In,Out).
+
+
+
+
+%% get_key( +Valid:list(char), -C:char) is det.
+%
+%  Get and validate a key press from the user. The character
+%  must be one of the ones listed in Valid, otherwise, an
+%  error message is printed and the user prompted again.
+get_key(Valid,C) :-
+	read_char_echo(D), nl,
+	(	member(D,Valid) -> C=D
+	;	D='\n' -> get_key(Valid,C) % this improves interaction with acme
+	;	format('Unknown command "~q"; valid keys are ~q.\n', [D,Valid]),
+		write('Command? '),
+		get_key(Valid,C)).
+
+
+%% userchk(T) is semidet.
+%
+%  Write T and ask this user if it is ok. User presses y or n.
+%  userchk succeeds if if the keypress was y and fails if it was n.
+userchk(T) :- prompt_for_key(T,[y,n],y).
+
+
+%% prompt_for_key( +Msg:atom, +Keys:list(char), -Key:char) is semidet.
+%
+%  Prompt user for a keypress. Prompt message is Msg, and valid keys are
+%  listed in Keys. 
+prompt_for_key(Msg,Keys,Key) :- format('~p ~q? ',[Msg,Keys]), get_key(Keys,Key).
+
+% ------------------- TERM MANIPULATION ------------------------------
+
+
+%% copy_head(+T1,-T2) is det.
+%% copy_head(+T1,+T2) is semidet.
+%
+% true if T1 and T2 have the same head and arity
+copy_head(T1,T2) :- functor(T1,N,A), functor(T2,N,A).
+
+
+
+%% reinstatevars( F:atom, V:list, Eh, What) is nondet.
+%% reinstatevars( V:list, Eh, What) is nondet.
+%
+% Reverse of numbervars. Each '$VAR'(N) subterm of X is replaced
+% with the Nth element of V, which can be uninstantiated on entry
+% reinstatevars/4 uses an arbitrary functor F instead of $VAR.
+
+reinstatevars(V,'$VAR'(N),Y) :- !, nth0(N,V,Y).
+reinstatevars(_,X,Y) :- atomic(X), !, Y=X.
+reinstatevars(V,X,Y) :- mapargs(reinstatevars(V),X,Y).
+
+reinstatevars(F,V,T,Y) :- functor(T,F,1), !, arg(1,T,N), nth0(N,V,Y).
+reinstatevars(_,_,X,Y) :- atomic(X), !, Y=X.
+reinstatevars(F,V,X,Y) :- mapargs(reinstatevars(F,V),X,Y).
+
+
+%% unify_args( Src, SrcIndex, Dest, DestIndex, Num) is det.
+%
+% this unifies N consecutive arguments of Src and Dest starting
+% from SI and DI in each term respectively
+unify_args(_,_,_,_,0).
+unify_args(Src,SI,Dest,DI,N) :-
+	arg(SI,Src,X), arg(DI,Dest,X), !,
+	succ(SI,SI2), succ(DI,DI2), succ(N2,N),
+	unify_args(Src,SI2,Dest,DI2,N2).
+
+
+% ---------------------- LIST UTILITIES -----------------------------
+
+
+%member_clist(_,Z) :- var(Z), !, fail.
+member_clist(A,A) :- A\=(_,_).
+member_clist(A,(A,_)).
+member_clist(A,(_,B)) :- member_clist(A,B).
+
+
+
+%% measure(Ruler,In,Out) is det.
+% true if Out is the same length as Ruler but matches In as far as possible
+measure([],_I,[]).
+measure([_|R],[],[_|O]) :- measure(R,[],O).
+measure([_|R],[X|I],[X|O]) :- measure(R,I,O).
+
+%% equal_length( ?In, ?Out) is nondet.
+%  equal_length( +L1:list, -L2:list) is det.
+%  equal_length( -L1:list, +L2:list) is det.
+%
+%  True if L1 and L2 are the same length.
+equal_length([],[]).
+equal_length([_|T1],[_|T2]) :- equal_length(T1,T2).
+
+%split_at(0,T,I-I,T).	
+%split_at(N,[H|T],[H|I1]-Z,T1) :- succ(M,N), split_at(M,T,I1-Z,T1).	
+
+%split_at2(0,T,I-I,T).	
+%split_at2(N,[H|T],[H|I1]-Z,T1) :- split_at2(M,T,I1-Z,T1), succ(M,N).	
+
+%% max(+X:number, +Y:number, -Z:number) is det.
+%
+%  Unify Z with the larger of X and Y. Legal values are
+%  any numerical value or inf or -inf.
+max(_,inf,inf) :- !.
+max(inf,_,inf) :- !.
+max(X,-inf,X)  :- !.
+max(-inf,X,X)  :- !.
+max(X,Y,Z)     :- X<Y -> Z=Y; Z=X.
+
+%% max(+X:number, +Y:number, -Z:number) is det.
+%
+%  Unify Z with the larger of X and Y. Legal values are
+%  any numerical value or inf or -inf.
+min(_,-inf,-inf) :- !.
+min(-inf,_,-inf) :- !.
+min(X,inf,X)  :- !.
+min(inf,X,X)  :- !.
+min(X,Y,Z)     :- X<Y -> Z=X; Z=Y.
+
+%% list_idx1_member( +L:list(A), +N:natural, ?X:A) is semidet.
+%% list_idx1_member( ?L:list(A), ?N:natural, ?X:A) is nondet.
+%
+%  Equivalent to nth1(N,L,X).
+list_idx1_member(L,I,X) :- nth1(I,L,X).
+
+
+%% getopts( +Opts:list(option), ?Spec:list(optspec))  is det.
+%
+%  Get value from option list. 
+%  ==
+%  option(A) ---> term(A).
+%  optspec   ---> option(A)/A.
+%  ==
+getopts(OptsIn,Spec) :- maplist(getopt(OptsIn),Spec).
+getopt(OptsIn,Option/Default) :- option(Option,OptsIn,Default).
+
+%% cons( ?Head:A, ?Tail:list(A), ?List:list(A)) is det.
+%
+%  List constructor.
+cons(H,T,[H|T]).
+
+%% decons( ?Head:A, ?List:list(A), ?Tail:list(A)) is det.
+%
+%  List deconstructor.
+decons(H,[H|T],T).
+
+% ---------------------- MAPPING, HIGH ORDER STUFF ---------------------
+
+%% for_naturals(+N:natural, P:pred(natural)) is nondet.
+% apply predicate to each natural number from 1 to N (backwards)
+for_naturals(0,_).
+for_naturals(N,P) :- succ(M,N), call(P,N), for_naturals(M,P). 
+
+%% mapints( +P:pred(integer,A), +R:intrange, -X:list) is nondet.
+%% mapints( +P:pred(integer), +R:intrange) is nondet.
+%
+% Mapping predicates over lists of integers. Range is like M..N.
+% mapints/3 maps 2 argument predicate over implicit list of
+% integers M..N and explicit list of values X.
+mapints(_,M..N) :- N<M, !.
+mapints(P,M..N) :- call(P,M), plus(M,1,L), mapints(P,L..N).
+
+mapints(_,M..N,[])    :- N<M, !.
+mapints(P,M..N,[X|T]) :- call(P,M,X), plus(M,1,L), mapints(P,L..N,T).
+
+%% rep( +N:natural, ?X:A, -L:list(A)) is det.
+%% rep( -N:natural, ?X:A, -L:list(A)) is multi.
+% Make a list consisting of N repeats of the same term. If called
+% with N unbount, creates progressively longer and longer lists
+% on backtracking.
+rep(0,_,[]).
+rep(N,A,[A|X]) :- 
+	(	nonvar(N) 
+	-> succ(M,N), rep(M,A,X)
+	; rep(M,A,X), succ(M,N)
+	).
+
+%% mapargs( P:pred(A,B,C), T1:tuple(F,A), T2:tuple(F,B), T3:tuple(F,C)) is nondet.
+%% mapargs( P:pred(A,B), T1:tuple(F,A), T2:tuple(F,B)) is nondet.
+%% mapargs( P:pred(A), T1:term) is nondet.
+%
+% Map predicate over to args of a term preserving head.
+% A tuple(F,A) is a term with head functor F and any number of arguments
+% of type A, ie
+% ==
+% tuple(F,A) ---> F ; F(A) ; F(A,A) ; F(A,A,A) ; .. .
+% ==
+
+mapargs(P,T1) :- 
+	functor(T1,_,N), 
+	mapargs_x(1,N,P,T1).
+
+mapargs(P,T1,T2) :-
+	(	nonvar(T1)  
+	-> functor(T1,F,N), functor(T2,F,N)
+	;	functor(T2,F,N), functor(T1,F,N)),
+	mapargs_x(1,N,P,T1,T2).
+
+mapargs(P,T1,T2,T3) :-
+	functor(T1,F,N),
+	functor(T2,F,N),
+	functor(T3,F,N),
+	mapargs_x(1,N,P,T1,T2,T3).
+
+mapargs_x(I,N,P,T1) :-
+	(	I>N -> true
+	;  arg(I,T1,X1),
+		call(P,X1),
+		succ(I,J), mapargs_x(J,N,P,T1)).
+
+mapargs_x(I,N,P,T1,T2) :-
+	(	I>N -> true
+	;  arg(I,T1,X1),
+		arg(I,T2,X2),
+		call(P,X1,X2),
+		succ(I,J), mapargs_x(J,N,P,T1,T2)).
+
+mapargs_x(I,N,P,T1,T2,T3) :-
+	(	I>N -> true
+	;  arg(I,T1,X1),
+		arg(I,T2,X2),
+		arg(I,T3,X3),
+		call(P,X1,X2,X3),
+		succ(I,J), mapargs_x(J,N,P,T1,T2,T3)).
+
+%% drop( +N:natural, +In:list(A), -Out:list(A)) is det.
+drop(0,T,T).
+drop(N,[_|T],V) :- succ(M,N), drop(M,T,V).
+
+
+%% take( +N:natural, +In:list(A), -Out:list(A)) is det.
+take(N,T,X) :- length(X,N), append(X,_,T).
+
+
+%% drop_while( +P:pred(A), +In:list(A), -Out:list(A)) is det.
+%
+%  Remove all elements from head of In that are accepted by P
+%  and return the remained in Out.
+drop_while(P,[X|T],V) :- call(P,X) -> drop_while(P,T,V); V=[X|T].
+
+
+%% take_while( +P:pred(A), +In:list(A), -Out:list(A)) is det.
+%
+%  Remove all elements from head of In that are accepted by P
+%  and return them in Out.
+take_while(P,[X|T],O) :- call(P,X) -> O=[X|V], take_while(P,T,V); O=[].
+
+
+
+%% retry( :Goal) is det.
+%
+%  Keep retrying Goal until it succeeds. Only makes sense if Goal
+%  has side effects. Might be nonterminating.
+retry(G) :- once((repeat,G)).
+
+%% apply_to_nth1( N:natural, Op:pred(A,A), +In:list(A), +Out:list(A)) is nondet.
+%
+%  Apply predicate Op to the N th element of list In and unify Out with the result.
+%apply_to_nth1(N,Op,Old,Init) :- 
+%	(	nonvar(N) 
+%	-> succ(M,N), split_at(M,Old,Init-[Y|Tail],[X|Tail])
+%	;	split_at2(M,Old,Init-[Y|Tail],[X|Tail]), succ(M,N) 
+%	),
+%	call(Op,X,Y).
+
+apply_to_nth1(1,P,[X|XX],[Y|XX]) :- call(P,X,Y).
+apply_to_nth1(N,P,[X|X1],[X|Y1]) :- nonvar(N), !, N>1, succ(M,N), apply_to_nth1(M,P,X1,Y1).
+apply_to_nth1(N,P,[X|X1],[X|Y1]) :- var(N), !, apply_to_nth1(M,P,X1,Y1), succ(M,N).
+
+
+%% mapargs_xx( +P:pred(A,B), +Src:term(_,A), +SrcIndex:natural, +Dest:term(_,B), +DestIndex:natural, +N:natural) is nondet.
+%
+%  Maps predicate P over N consecutive arguments of Src and Dest. Starts
+%  at SrcIndex th argument of Src and DestIndex th argument of Dest.
+mapargs_xx(_,_,_,_,_,0).
+mapargs_xx(Pred,Src,SI,Dest,DI,N) :-
+	arg(SI,Src,SX), arg(DI,Dest,DX), call(Pred,SX,DX), !,
+	succ(SI,SI2), succ(DI,DI2), succ(N2,N),
+	mapargs_xx(Pred,Src,SI2,Dest,DI2,N2).
+
+
+%% mcall(P:pred(A), X:A) is nondet.
+%% mcall(P:pred(A,B), X:A, Y:B) is nondet.
+%% mcall(P:pred(A,B,C), X:A, Y:B, Z:C) is nondet.
+%% mcall(P:pred(A,B,C,D), X:A, Y:B, Z:C, W:D) is nondet.
+%
+%  Like call/N but P can additionally be a lambda expression in one of several
+%  forms:
+%  * Tuple :- Body
+%  If functor(Tuple,\,N), Body is executed after unifying tuple arguments
+%  with arguments to mcall, eg =mcall(\(X):-member(X,[a,b,c]),Y)= is equivalent
+%  to member(Y,[a,b,c]), or =mcall(\(X,Y):-nth1(X,[a,b,c],Y),2,c)=.
+%  * Tuple
+%  Equivalent to Tuple:-true.
+
+mcall(P,A) :- mc(P,\(A),Q), Q.
+mcall(P,A,B) :- mc(P,\(A,B),Q), Q.
+mcall(P,A,B,C) :- mc(P,\(A,B,C),Q), Q.
+mcall(P,A,B,C,D) :- mc(P,\(A,B,C,D),Q), Q.
+
+mc(Tuple:-Body,Params,Goal) :- !, copy_term(Tuple/Body,Params/Goal).
+mc(Tuple,Params,true)       :- functor(Tuple,\,_), !, copy_term(Tuple,Params).
+mc(P,Params,apply(P,Args))  :- Params=..[\|Args].
+
+
+%% on_backtracking( :Goal) is det.
+%
+%  The first time this is called, it succeeds and does nothing.
+%  On backtracking, Goal is called and then a failure is generated.
+
+on_backtracking(_).
+on_backtracking(P) :- P, !, fail.
+
+
+%% bt_call( :Do, :Undo) is nondet.
+%
+%  Creates a backtrackable operation from a non-backtrackable Do
+%  operation and a corresponding operation to undo it. Do can
+%  be non-deterministic, in which case bt_call(Do,Undo) will also
+%  have multiple solutions. Undo is called inside once/1.
+%
+%  bt_call/2 is implemented both as a predicate and as a goal
+%  expansion (see goal_expansion/2).
+bt_call(Do,Undo)  :- Do, (true; once(Undo), fail).
+
+user:goal_expansion( bt_call(Do,Undo), (Do, (true; once(Undo), fail))).
+
+
+
+/* Might include these at some point
+
+% apply lambda term to another term
+app(X\\F,Y,G) :- !, copy_term(X\\F,Y\\G).
+app(T,A,Z)   :- addargs(T,[A],Z). 
+app(T,A,B,Z) :- addargs(T,[A,B],Z).
+app(T,A,B,C,Z) :- addargs(T,[A,B,C],Z).
+
+applist(F,N,A,Z) :- length(Z,N), maplist(app(F),A,Z).
+applist(F,N,A,B,Z) :- length(Z,N), maplist(app(F),A,B,Z).
+applist(F,N,A,B,C,Z) :- length(Z,N), maplist(app(F),A,B,C,Z).
+
+*/
+
+
+% ------------------ DATABASE ------------------------------
+
+%% bt_assert(Clause) is det.
+%  Backtrackable assert.
+bt_assert(H)      :- bt_call(assert(H),retract(H)).
+
+%% bt_retract(Clause) is det.
+%  Backtrackable retract.
+bt_retract(H)     :- bt_call(retract(H), assert(H)).
+
+%% strict_assert(Fact) is semidet.
+%
+%  Asserts fact only if it is not already true. Fails
+%  if fact is already provable. Retracts fact on backtracking.
+strict_assert(H)  :- \+call(H), bt_call(assert(H),retract(H)).
+
+
+%% strict_retract(Fact) is semidet.
+%
+%  Retracts fact only if it is currently in the database. Fails
+%  if fact is not provable. Reasserts fact on backtracking.
+strict_retract(H) :- call(H), bt_call(retract(H), assert(H)).
+
+
+% when loaded, this sets the hostname/1 predicate.
+:- dynamic hostname/1.
+
+%% hostname( -A:atom) is det.
+%
+%  Unifies A with the computer's hostname. This is set when the 
+%  module is loaded by calling the system command 'hostname -s'.
+
+% init_hostname is det - read hostname from UNIX command hostname.
+init_hostname :-
+	setup_call_cleanup(
+		open(pipe('hostname -s'),read,SID), 
+		(read_line_to_codes(SID,C), atom_codes(H,C), retractall(hostname(_)), assert(hostname(H))),
+		close(SID)).
+
+:- (	hostname(H)
+	-> format('% hostname already set to ~w\n',[H])
+	;  init_hostname, hostname(H), format('% hostname set to ~w\n',[H])
+	).
+
+% Comma lists
+% ie, lists built up using (,) as a pairing functor
+% Note, these functor lists do NOT have a nil element - the
+% last item in the list is the 2nd argument to the final
+% functor term, which can therefore be a term headed by any
+% other functor. Eg:
+% (1,(2,3))    <-> [1,2,3]
+% (1,(2,(3+4)) <-> [1,2,(3+4)]
+
+%% cl_list( +CL:clist(A), -L:list(A)) is det.
+%% cl_list( -CL:clist(A), +L:list(A)) is det.
+%
+%  Convert between comma lists and ordinary lists
+cl_list((A,B),[A|BL]) :- cl_list(B,BL). 
+cl_list(A,[A]) :- A\=(_,_). 
+
+%% cl_length( +L:clist, -N:natural) is det.
+%% cl_length( -L:clist, +N:natural) is det.
+%
+%  Length of a comma-list.
+cl_length((_,B),N) :- cl_length(B,M), succ(M,N).
+cl_length(X,1)     :- X\=(_,_).
+
+
+%% cl_list_vt( +CL:clist(A), -L:list(A)) is det.
+%% cl_list_vt( -CL:clist(A), +L:list(A)) is det.
+%
+%  Convert between comma lists (with open tails) and ordinary lists.
+cl_list_vt(FL,[FL])   :- var(FL), !.
+cl_list_vt(FL,[A|BL]) :- FL = (A,B), cl_list_vt(B,BL). 
+cl_list_vt(A,[A])     :- A\=(_,_). 
+
+
+%% cl_length_vt( +L:clist, -N:natural) is det.
+%% cl_length_vt( -L:clist, +N:natural) is det.
+%
+%  Length of a comma-list with possible variable tail.
+%  This version handles lists where the last element is variable (counts as 1)
+cl_length_vt(FL,1) :- var(FL), !.
+cl_length_vt(FL,N) :- FL=(_,B), cl_length_vt(B,M), succ(M,N).
+cl_length_vt(FL,1) :- FL\=(_,_).
+
+%% cl_member(-X, +L:clist) is nondet.
+%  List membership for comma lists.
+cl_member(X,(X,_)).	
+cl_member(X,(_,T)) :- cl_member(X,T).	
+cl_member(X,X)     :- X\=(_,_).
+