- Documentation
- Reference manual
- The SWI-Prolog library
- library(aggregate): Aggregation operators on backtrackable predicates
- library(ansi_term): Print decorated text to ANSI consoles
- library(apply): Apply predicates on a list
- library(assoc): Association lists
- library(broadcast): Broadcast and receive event notifications
- library(charsio): I/O on Lists of Character Codes
- library(check): Consistency checking
- library(clpb): CLP(B): Constraint Logic Programming over Boolean Variables
- library(clpfd): CLP(FD): Constraint Logic Programming over Finite Domains
- library(clpqr): Constraint Logic Programming over Rationals and Reals
- library(csv): Process CSV (Comma-Separated Values) data
- library(dcg/basics): Various general DCG utilities
- library(dcg/high_order): High order grammar operations
- library(debug): Print debug messages and test assertions
- library(dicts): Dict utilities
- library(error): Error generating support
- library(fastrw): Fast reading and writing of terms
- library(gensym): Generate unique symbols
- library(heaps): heaps/priority queues
- library(increval): Incremental dynamic predicate modification
- library(intercept): Intercept and signal interface
- library(iostream): Utilities to deal with streams
- library(listing): List programs and pretty print clauses
- library(lists): List Manipulation
- library(macros): Macro expansion
- library(main): Provide entry point for scripts
- library(nb_set): Non-backtrackable set
- library(www_browser): Open a URL in the users browser
- library(occurs): Finding and counting sub-terms
- library(option): Option list processing
- library(optparse): command line parsing
- library(ordsets): Ordered set manipulation
- library(pairs): Operations on key-value lists
- library(persistency): Provide persistent dynamic predicates
- library(pio): Pure I/O
- library(portray_text): Portray text
- library(predicate_options): Declare option-processing of predicates
- library(prolog_coverage): Coverage analysis tool
- library(prolog_debug): User level debugging tools
- library(prolog_jiti): Just In Time Indexing (JITI) utilities
- library(prolog_trace): Print access to predicates
- library(prolog_versions): Demand specific (Prolog) versions
- library(prolog_xref): Prolog cross-referencer data collection
- library(quasi_quotations): Define Quasi Quotation syntax
- library(random): Random numbers
- library(rbtrees): Red black trees
- library(readutil): Read utilities
- library(record): Access named fields in a term
- library(registry): Manipulating the Windows registry
- library(rwlocks): Read/write locks
- library(settings): Setting management
- library(statistics): Get information about resource usage
- library(strings): String utilities
- library(simplex): Solve linear programming problems
- library(solution_sequences): Modify solution sequences
- library(tables): XSB interface to tables
- library(terms): Term manipulation
- library(thread): High level thread primitives
- library(thread_pool): Resource bounded thread management
- library(ugraphs): Graph manipulation library
- library(url): Analysing and constructing URL
- library(varnumbers): Utilities for numbered terms
- library(yall): Lambda expressions
- The SWI-Prolog library
- Packages
- Reference manual
A.25 library(macros): Macro expansion
This library defines a macro expansion mechanism that operates on
arbitrary terms. Unlike term_expansion/2
and goal_expansion/2,
a term is explicitly designed for expansion using the term #(Macro)
.
Macros are first of all intended to deal with compile time constants.
They can also be used to construct terms at compile time.
A.25.1 Defining and using macros
Macros are defined for the current module using one of the three constructs below.
#define(Macro, Replacement). #define(Macro, Replacement) :- Code. #import(ModuleFile).
Macro is a callable term, not being define(_,_)
,
or import(_)
.
Replacement is an arbitrary Prolog term. Code is a
Prolog body term that must succeed and can be used to
dynamically generate (parts of) Replacement.
The #import(ModuleFile)
definition makes all macros from
the given module available for expansion in the module it appears.
Normally this shall be appear after local macro definitions.
A macro is called using the term #(Macro)
. #
is defined as a low-priority (10) prefix operator to allow for #Macro
.
Macros can appear at the following places:
- An entire sentence (clause)
- Any argument of a compound. This implies also the head and body of a clause.
- Anywhere in a list, including as the tail of a list
- As a value for a dict key or as a dict key name.
Macros can not appear as name of a compound or tag of a dict.
A term
#Macro
appearing in one of the allowed places must
have a matching macro defined, i.e., #Macro
is always
expanded. An error is emitted if the expansion fails. Macro expansion is
applied recursively and thus, macros may be passed to macro arguments
and macro expansion may use other macros.
Macros are matched to terms using Single Sided Unification
(SSU), implemented using Head => Body
rules. This
implies that the matching never instantiates variables in the term that
is being expanded.
Below are some examples. The first line defines the macro and the indented line after show example usage of the macro.
#define(max_width, 100). W < #max_width #define(calc(Expr), Value) :- Value is Expr. fact(#calc(#max_width*2)). #define(pt(X,Y), point{x:X, y:Y}). reply_json(json{type:polygon, points:[#pt(0,0), #pt(0,5), #pt(5,0)]}).
Macro expansion expands terms #(Callable)
. If the
argument to the
#-term is not a callable
, the #-term is not modified. This
notably allows for #(Var)
as used by library(clpfd)
to indicate that a variable is constraint to be an (clp(fd)
)
integer.
A.25.2 Implementation details
A macro #define(Macro, Expanded) :- Body.
is, after some
basic sanity checks, translated into a rule
'$macro'(Macro, Var), Body => Var = Expanded.
The #import(File)
is translated into :- use_module(File, [])
and a
link clause that links the macro expansion from the module
defined in
File to the current module.
Macro expansion is realised by creating a clause for term_expansion/2
in the current module. This clause results from expanding the first
#define
or #import
definition. Thus, if macros
are defined before any other local definition for term_expansion/2
it is executed as the first step. The macro expansion fails if no macros
were encounted in the term, allowing other term_expansion rules local to
the module to take effect. In other words, a term holding macros is not
subject to any other term expansion local to the module. It is subject
to term expansion defined in module user
and system
that is performed after the local expansion is completed.
A.25.3 Predicates
- [semidet]include_macros(+M, +Macro, -Expanded)
- Include macros from another module. This predicate is a helper for
#import(File)
. It calls’$macro’/2 in M, but fails silently in case Macro is not defined in M as it may be defined in another imported macro file or further down in the current file. - [semidet]expand_macros(+Module, +TermIn, -TermOut, +PosIn, -PosOut)
- Perform macro expansion on TermIn with layout PosIn
to produce
TermOut with layout PosOut. The transformation is
performed if the current load context module is Module (see prolog_load_context/2).
This predicate is not intended for direct usage.
- [det]macro_position(-Position)
- True when Position is the position of the macro. Position
is a term
File:Line:LinePos
. If File is unknown it is unified with-
. If Line and/or LinePos are unknown they are unified with 0. This predicate can be used in the body of a macro definition to provide the source location. The example below defines#pp(Var)
to print a variable together with the variable name and source location.#define(pp(Var), print_message(debug, dump_var(Pos, Name, Var))) :- ( var_property(Var, name(Name)) -> true ; Name = 'Var' ), macro_position(Pos). :- multifile prolog:message//1. prolog:message(dump_var(Pos,Name,Var)) --> [ url(Pos), ': ', ansi([fg(magenta),bold], '~w', [Name]), ' = ', ansi(code, '~p', [Var]) ].