DOC: initial documentation for library(pairs) in DocLog format
+/** Reasoning about pairs.
+
+ Pairs are Prolog terms with principal functor `(-)/2`. A pair
+ often has the form `Key-Value`. The predicates of this library
+ relate pairs to keys and values.
+*/
+
:- module(pairs, [pairs_keys_values/3,
pairs_keys/2,
pairs_values/2,
:- meta_predicate map_list_to_pairs(2, ?, ?).
+%% pairs_keys_values(?Pairs, ?Keys, ?Values)
+%
+% The first argument is a list of Pairs, the second the corresponding
+% Keys, and the third argument the corresponding values.
+
pairs_keys_values([], [], []).
pairs_keys_values([A-B|ABs], [A|As], [B|Bs]) :-
pairs_keys_values(ABs, As, Bs).
+%% pairs_keys(?Pairs, ?Keys)
+%
+% Same as `pairs_keys_values(Pairs, Keys, _)`.
+
pairs_keys(Ps, Ks) :- pairs_keys_values(Ps, Ks, _).
+%% pairs_values(?Pairs, ?Values)
+%
+% Same as `pairs_keys_values(Pairs, _, Values)`.
+
pairs_values(Ps, Vs) :- pairs_keys_values(Ps, _, Vs).
map_list_to_pairs(Pred, Ls, Ps) :-
