This module specifies, together with dcg.pl, the transformation of terms as they are read from a file before they are processed by the compiler.

The toplevel is expand_term/2. This uses three other translators:

• Conditional compilation
• term_expansion/2 rules provided by the user
• DCG expansion

Note that this ordering implies that conditional compilation directives cannot be generated by term_expansion/2 rules: they must literally appear in the source-code.

Term-expansion may choose to overrule DCG expansion. If the result of term-expansion is a DCG rule, the rule is subject to translation into a predicate.

Next, the result is passed to expand_bodies/2, which performs goal expansion.

 expand_term(+Input, -Output) is det

 expand_term(+Input, +Pos0, -Output, -Pos) is det

This predicate is used to translate terms as they are read from a source-file before they are added to the Prolog database.

 prepare_directive(+Directive) is det[private]

Try to autoload goals associated with a directive such that we can allow for term expansion of autoloaded directives such as setting/4. Trying to do so shall raise no errors nor fail as the directive may be further expanded.

 expand_bodies(+Term, +Pos0, -Out, -Pos) is det[private]

Find the body terms in Term and give them to expand_goal/2 for further processing. Note that we maintain status information about variables. Currently we only detect whether variables are fresh or not. See var_info/3.

 expand_terms(:Closure, +In, +Pos0, -Out, -Pos)[private]

Loop over two constructs that can be added by term-expansion rules in order to run the next phase: calling term_expansion/2 can return a list and terms may be preceded with a source-location.

 add_source_location(+Term, +SrcLoc, -SrcTerm)[private]

Re-apply source location after term expansion. If the result is a list, claim all terms to originate from this location.

 expand_term_list(:Expander, +TermList, +Pos, -NewTermList, -PosList)[private]

 add_term(+ExpandOut, ?ExpandPosOut, -Terms, ?TermsT, -PosL, ?PosLT)[private]

 var_intersection(+List1, +List2, -Shared) is det[private]

Shared is the ordered intersection of List1 and List2.

 ord_intersection(+OSet1, +OSet2, -Int)[private]

Ordered list intersection. Copied from the library.

 ord_subtract(+Set, +Subtract, -Diff)[private]

 merge_variable_info(+Saved)[private]

Merge info from two branches. The info in Saved is the saved info from the first branch, while the info in the actual variables is the info in the second branch. Only if both branches claim the variable to be fresh, we can consider it fresh.

 var_property(+Var, ?Property)

True when Var has a property Key with Value. Defined properties are:

fresh(Fresh)

Variable is first introduced in this goal and thus guaranteed to be unbound. This property is always present.

singleton(Bool)

It true indicate that the variable appears once in the source. Note this doesn't mean it is a semantic singleton.

name(-Name)

True when Name is the name of the variable.

 remove_attributes(+Term, +Attribute) is det[private]

Remove all variable attributes Attribute from Term. This is used to make term_expansion end with a clean term. This is currently required for saving directives in QLF files. The compiler ignores attributes, but I think it is cleaner to remove them anyway.

 $var_info:attr_unify_hook(_, _) is det[private]

Dummy unification hook for attributed variables. Just succeeds.

 expand_goal(+BodyTerm, +Pos0, -Out, -Pos) is det

 expand_goal(+BodyTerm, -Out) is det

Perform macro-expansion on body terms by calling goal_expansion/2.

 $expand_closure(+BodyIn, +ExtraArgs, -BodyOut) is semidet

 $expand_closure(+BodyIn, +PIn, +ExtraArgs, -BodyOut, -POut) is semidet

Expand a closure using goal expansion for some extra arguments. Note that the extra argument must remain at the end. If this is not the case, '$expand_closure'/3,5 fail.

 expand_goal(+GoalIn, ?PosIn, -GoalOut, -PosOut, +Module, -ModuleList, +Term, +Done) is det[private]

Arguments:

Module	- is the current module to consider
ModuleList	- are the other expansion modules
Term	- is the overall term that is being translated
Done	- is a list of terms that have already been expanded

 already_expanded(+Goal, +Done, -RestDone) is semidet[private]

 fixup_or_lhs(+OldLeft, -ExpandedLeft, +ExpPos, -Fixed, -FixedPos) is det[private]

The semantics of (A;B) is different if A is (If->Then). We need to keep the same semantics if -> is introduced or removed by the expansion. If -> is introduced, we make sure that the whole thing remains a disjunction by creating ((EA,true);B)

 is_meta_call(+G0, +M, -Head) is semidet[private]

True if M:G0 resolves to a real meta-goal as specified by Head.

 expand_meta(+MetaSpec, +G0, ?P0, -G, -P, +M, +Mlist, +Term, +Done)[private]

 extended_pos(+Pos0, +N, -Pos) is det[private]

extended_pos(-Pos0, +N, +Pos) is det[private]

Pos is the result of adding N extra positions to Pos0.

 expand_meta_arg(+MetaSpec, +Arg0, +ArgPos0, -Eval, -EvalPos, -Arg, -ArgPos, +ModuleList, +Term, +Done) is det[private]

Goal expansion for a meta-argument.

Arguments:

Eval	- is always true. Future versions should allow for functions on such positions. This requires proper position management for function expansion.

 extend_arg_pos(+A0, +P0, +Ex, -A, -P) is det[private]

Adds extra arguments Ex to A0, and extra subterm positions to P for such arguments.

 remove_arg_pos(+A0, +P0, +M, +Ex, +VL, -A, -P) is det[private]

Removes the Ex arguments from A0 and the respective extra positions from P0. Note that if they are not at the end, a wrapper with the elements of VL as arguments is generated to put them in order.

See also

- wrap_meta_arguments/5

 extend_existential(+G0, +G1, -V) is semidet[private]

Extend the variable template to compensate for intermediate variables introduced during goal expansion (notably for functional notation).

 call_goal_expansion(+ExpandModules, +Goal0, ?Pos0, -Goal, -Pos, +Done) is semidet[private]

Succeeds if the context has a module that defines goal_expansion/2 this rule succeeds and Goal is not equal to Goal0. Note that the translator is called recursively until a fixed-point is reached.

 allowed_expansion(:Goal) is semidet[private]

Calls prolog:sandbox_allowed_expansion(:Goal) prior to calling Goal for the purpose of term or goal expansion. This hook can prevent the expansion to take place by raising an exception.

throws

- exceptions from prolog:sandbox_allowed_expansion/1.

 expand_functions(+G0, +P0, -G, -P, +M, +MList, +Term) is det[private]

Expand functional notation and arithmetic functions.

Arguments:

MList

- is the list of modules defining goal_expansion/2 in the expansion context.

 expand_functional_notation(+G0, +P0, -G, -P, +M, +MList, +Term) is det[private]

To be done

- : position logic

- : make functions module-local

 contains_functions(@Term) is semidet[private]

True when Term contains a function reference.

 replace_functions(+GoalIn, +PosIn, -Eval, -EvalPos, -GoalOut, -PosOut, +ContextTerm) is det[private]

To be done

- Proper propagation of list, dict and brace term positions.

 map_functions(+Arg, +Arity, +TermIn, +ArgInPos, -Term, -ArgPos, -Eval, -EvalPos, +Context)[private]

 conj(+G1, +P1, +G2, +P2, -G, -P)[private]

 function(?Term, +Context)[multifile]

True if function expansion needs to be applied for the given term.

 expand_arithmetic(+G0, +P0, -G, -P, +Term) is semidet[private]

Expand arithmetic expressions in is/2, (>)/2, etc. This is currently a dummy. The idea is to call rules similar to goal_expansion/2,4 that allow for rewriting an arithmetic expression. The system rules will perform evaluation of constant expressions.

 f2_pos(?TermPos0, ?PosArg10, ?PosArg20, ?TermPos, ?PosArg1, ?PosArg2) is det[private]

 f1_pos(?TermPos0, ?PosArg10, ?TermPos, ?PosArg1) is det[private]

 f_pos(?TermPos0, ?PosArgs0, ?TermPos, ?PosArgs) is det[private]

 atomic_pos(?TermPos0, -AtomicPos) is det[private]

Position progapation routines.

 pos_nil(+Nil, -Nil) is det[private]

 pos_list(+List0, -H0, -T0, -List, -H, -T) is det[private]

Position propagation for lists.

 extend_1_pos(+FunctionPos, -FArgPos, -EvalPos, -EArgPos, -VarPos)[private]

Deal with extending a function to include the return value.

 expected_layout(+Expected, +Found)[private]

Print a message if the layout term does not satisfy our expectations. This means that the transformation requires support from term_expansion/4 and/or goal_expansion/4 to achieve proper source location information.

 simplify(+ControlIn, +Pos0, -ControlOut, -Pos) is det[private]

Simplify control structures

To be done

- Much more analysis

- Turn this into a separate module

 simple(+Goal, +GoalPos, -Simple, -SimplePos)[private]

Simplify a control structure. Note that we do not simplify (A;fail). Logically, this is the same as A if A is not _->_ or _*->_, but the choice point may be created on purpose.

 eval_true(+Goal) is semidet[private]

 eval_false(+Goal) is semidet[private]

 compile_meta_call(+CallIn, -CallOut, +Module, +Term) is det[private]

Compile (complex) meta-calls into a clause.

 replace_subterm(From, To, TermIn, TermOut)[private]

Replace instances (==/2) of From inside TermIn by To.

 intersection_eq(+Small, +Big, -Shared) is det[private]

Shared are the variables in Small that also appear in Big. The variables in Shared are in the same order as Small.

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

 $including

 expand_goal(Arg1, Arg2)

 expand_term(Arg1, Arg2, Arg3, Arg4)