documents/userman/umsmacros.tex

44   are expanded just after a Prolog term has been read by the
47   \biptxtref{term-reading}{read/1}{../bips/kernel/ioterm/read-1.html}
51   are expanded only during compilation and only when a term occurs
55   are expanded just before a Prolog term is printed by one of the
61 In addition to transforming a term, macros can also be
63 the transformed term if
64 supplied with source annotation information for the orginal term.  Source
65 annotation information is about the source and position of a term, and is
141 The term to transform is passed as the first argument, the second is a free
143 term. In the case of the source annotation aware version of \about{TransPred},
145 the term was read in by \predspec{read_annotated/2,3}, the annotated version of
147 term to transformed is passed in the third argument, and the transformation
148 should bind the fourth argument to the annotated transformed term;
152 argument is the module where the term was being read in. See
156 to a local read term macro) or contain specifications from
165     This is a read macro and shall be applied after reading a term (default).
168     This is a write macro and shall be applied before printing a term.
176   \item[term:]\index{macros!term}
180     Transform only if the term is a program clause, i.e., inside
192     Goal-read-macros are transformed only if the term is a subgoal in the body
207     Consider only the whole term, not subterms (optional).
254 If the transformation function fails, the term is not transformed. Thus,
259 subterms of a transformed term by specifying the flag \notation{protect_arg}.
261 A term can be protected against transformation by quoting it with
342 original term should be mapped to the transformed term.
344 An annotated term provides the source information about a term. It
345 is structurally similar to the original term and
346 contains all information about the term, plus additional type information,
356                                 term,     % var, atomic or compound
357                                 type,     % term type (see below)
366 The type-field describes the type of the original term and provide type
371 In the case of atomic terms and variables, the term-field simply contains the
372 plain original term. For compound terms, the term-field contains a structure
373 whose functor is the functor of the plain term, but whose arguments are
374 annotated versions of the plain term arguments.
376 For example, the annotated term representing the source term
393 The file/line/from/to-fields of an annotated term describe the
394 "source position" of the term, as follows:
406     The exact term position as integer offsets in the source stream,
411 annotated terms for the original and transformed term. The predicate will
412 be supplied with the annotated term for the original term if available,
413 and the predicate is responsible for specifying the annotated term for the
414 transformed term---the structure of the transformed annotated term must
415 match the annotated term structure expected for the transformed term. If
416 no annotated information is available, the original annotated term will be
417 a variable, and the predicate must not bind the transformed annotated term.
432               AnnA = annotated_term{term:a(_AnnX, AnnY),
435               AnnTrans = annotated_term{term:b(AnnY),
454 inherits the annotation information for the original term's principal
455 functor, \predspec{a/2}. The argument Y in the transformed term takes the
457 term.
462 allow the user to access the details of how the subterms of the original term
463 are mapped to the transformed term. Without this extra information, the whole of
464 the transformed term is given the source information (source position, source
465 file etc.) of the original source term. This extra information is useful when
511 term or variable), the terminals are lists of prolog terms (typically
513 term is transformed, unless it is enclosed in curly brackets. The control