1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
|
\libdoc{record}{Access named fields in a term}
\label{sec:lib:record}
The library \pllib{record} provides named access to fields in a record
represented as a compound term such as \exam{point(X, Y)}. The Prolog
world knows various approaches to solve this problem, unfortunately with
no consensus. The approach taken by this library is proposed by Richard
O'Keefe on the SWI-Prolog mailinglist.
The approach automates a technique commonly described in Prolog
text-books, where access and modification predicates are defined for
the record type. Such predicates are subject to normal import/export as
well as analysis by cross-referencers. Given the simple nature of the
access predicates, an optimizing compiler can easily inline them for
optimal performance.
A record is defined using the directive record/1. We introduce the
library with a short example:
\begin{code}
:- record point(x:integer=0, y:integer=0).
...,
default_point(Point),
point_x(Point, X),
set_x_of_point(10, Point, Point1),
make_point([y(20)], YPoint),
\end{code}
The principal functor and arity of the term used defines the name and
arity of the compound used as records. Each argument is described using
a term of the format below.
\begin{quote}
<name>[:<type>][=<default>]
\end{quote}
In this definition, <name> is an atom defining the name of the argument,
<type> is an optional type specification as defined by must_be/2 from
library \pllib{error}, and <default> is the default initial value. The
<type> defaults to \const{any}. If no default value is specified the
default is an unbound variable.
A record declaration creates a set of predicates through
\jargon{term-expansion}. We describe these predicates below. In this
description, <constructor> refers to the name of the record (`point'
in the example above) and <name> to the name of an argument (field).
\begin{itemlist}
\item [default_<constructor>(-Record)]
Create a new record where all fields have their default values. This is
the same as \mbox{make_<constructor>([], Record)}.
\item [make_<constructor>(+Fields, -Record)]
Create a new record where specified fields have the specified values and
remaining fields have their default value. Each field is specified as
a term <name>(<value>). See example in the introduction.
\item [make_<constructor>(+Fields, -Record, -RestFields)]
Same as make_<constructor>/2, but named fields that do not appear in
\arg{Record} are returned in \arg{RestFields}. This predicate is
motivated by option-list processing. See library \pllib{option}.
\item [<constructor>_<name>(Record, Value)]
Unify \arg{Value} with argument in \arg{Record} named <name>.%
\footnote{Note this is not called `get_' as it performs
unification and can perfectly well instantiate the
argument.}
\item [<constructor>_data(?Name, +Record, ?Value)]
True when \arg{Value} is the value for the field named \arg{Name}
in \arg{Record}. This predicate does not perform type-checking.
\item [set_<name>_of_<constructor>(+Value, +OldRecord, -NewRecord)]
Replace the value for <name> in \arg{OldRecord} by \arg{Value} and unify
the result with \arg{NewRecord}.
\item [set_<name>_of_<constructor>(+Value, !Record)]
Destructively replace the argument <name> in \arg{Record} by
\arg{Value} based on setarg/3. Use with care.
\item [nb_set_<name>_of_<constructor>(+Value, !Record)]
As above, but using non-backtrackable assignment based on nb_setarg/3.
Use with \emph{extreme} care.
\item [set_<constructor>_fields(+Fields, +Record0, -Record)]
Set multiple fields using the same syntax as make_<constructor>/2, but
starting with \arg{Record0} rather than the default record.
\item [set_<constructor>_fields(+Fields, +Record0, -Record, -RestFields)]
Similar to set_<constructor>_fields/4, but fields not defined by
<constructor> are returned in \arg{RestFields}.
\item [set_<constructor>_field(+Field, +Record0, -Record)]
Set a single field specified as a term <name>(<value>).
\end{itemlist}
\begin{description}
\predicate{record}{1}{+Spec}
The construct \exam{:- record Spec, ...} is used to define access to
named fields in a compound. It is subject to term-expansion (see
expand_term/2) and cannot be called as a predicate. See
\secref{lib:record} for details.
\end{description}
|
