% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\section{library(macros): Macro expansion}

\label{sec:macros}

This library defines a macro expansion mechanism that operates on
arbitrary terms. Unlike \predref{term_expansion}{2} and \predref{goal_expansion}{2}, a term is
explicitly designed for expansion using the term \verb$#(Macro)$. Macros are
first of all intended to deal with compile time constants. They can also
be used to construct terms at compile time.

\subsection{Defining and using macros}

\label{sec:macros-define-and-use}

Macros are defined for the current module using one of the three
constructs below.

\begin{code}
#define(Macro, Replacement).
#define(Macro, Replacement) :- Code.
#import(ModuleFile).
\end{code}

\arg{Macro} is a \textit{callable term}, not being \verb$define(_,_)$, or \verb$import(_)$.
\arg{Replacement} is an arbitrary Prolog term. \arg{Code} is a Prolog \textit{body
term} that \textit{must} succeed and can be used to dynamically generate (parts
of) \arg{Replacement}.

The \verb$#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 \verb$#(Macro)$. \verb$#$ is defined as a
low-priority (10) prefix operator to allow for \verb$#Macro$. Macros can
appear at the following places:

\begin{itemize}
    \item An entire sentence (clause)
    \item Any argument of a compound. This implies also the head and body of
a clause.
    \item Anywhere in a list, including as the tail of a list
    \item As a value for a dict key or as a dict key name.
\end{itemize}

Macros can \textbf{not} appear as name of a compound or tag of a dict. A term
\verb$#Macro$ appearing in one of the allowed places \textbf{must} have a matching
macro defined, i.e., \verb$#Macro$ is \textbf{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 \textit{Single Sided Unification} (SSU),
implemented using \verb$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.

\begin{code}
#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)]}).
\end{code}

Macro expansion expands terms \verb$#(Callable)$. If the argument to the
\#-term is not a \const{callable}, the \#-term is not modified. This notably
allows for \verb$#(Var)$ as used by \file{library(clpfd)} to indicate that a
variable is constraint to be an (\verb$clp(fd)$) integer.

\subsection{Implementation details}

\label{sec:macros-implementation}

A macro \verb$#define(Macro, Expanded) :- Body.$ is, after some basic sanity
checks, translated into a rule

\begin{code}
'$macro'(Macro, Var), Body => Var = Expanded.
\end{code}

The \verb$#import(File)$ is translated into \verb$:- use_module(File, [])$ and a
\textit{link clause} that links the macro expansion from the module defined in
\arg{File} to the current module.

Macro expansion is realised by creating a clause for \predref{term_expansion}{2} in
the current module. This clause results from expanding the first
\verb$#define$ or \verb$#import$ definition. Thus, if macros are defined before
any other local definition for \predref{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 \const{user} and \const{system} that is performed after
the local expansion is completed.

\subsection{Predicates}

\label{sec:macros-predicates}\vspace{0.7cm}

\begin{description}
    \predicate[semidet]{include_macros}{3}{+M, +Macro, -Expanded}
Include macros from another module. This predicate is a helper for
\verb$#import(File)$. It calls '\$macro'/2 in \arg{M}, but fails silently in
case \arg{Macro} is not defined in \arg{M} as it may be defined in another
imported macro file or further down in the current file.

    \predicate[semidet]{expand_macros}{5}{+Module, +TermIn, -TermOut, +PosIn, -PosOut}
Perform macro expansion on \arg{TermIn} with layout \arg{PosIn} to produce
\arg{TermOut} with layout \arg{PosOut}. The transformation is performed if the
current load context module is \arg{Module} (see \predref{prolog_load_context}{2}).

This predicate is not intended for direct usage.

    \predicate[det]{macro_position}{1}{-Position}
True when \arg{Position} is the position of the macro. \arg{Position} is a term
\verb$File:Line:LinePos$. If \arg{File} is unknown it is unified with \verb$-$. 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 \verb$#pp(Var)$ to print a
variable together with the variable name and source location.

\begin{code}
#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])
    ].
\end{code}

\end{description}