Did you know ... Search Documentation:
expand.pl -- Prolog source-code transformation
PublicShow source

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.

Source expand_term(+Input, -Output) is det
Source 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.
Source 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.
Source 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.
Source 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.
Source 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.
Source expand_term_list(:Expander, +TermList, +Pos, -NewTermList, -PosList)[private]
Source add_term(+ExpandOut, ?ExpandPosOut, -Terms, ?TermsT, -PosL, ?PosLT)[private]
Source var_intersection(+List1, +List2, -Shared) is det[private]
Shared is the ordered intersection of List1 and List2.
Source ord_intersection(+OSet1, +OSet2, -Int)[private]
Ordered list intersection. Copied from the library.
Source ord_subtract(+Set, +Subtract, -Diff)[private]
Source 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.
Source 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.
Source 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.
Source $var_info:attr_unify_hook(_, _) is det[private]
Dummy unification hook for attributed variables. Just succeeds.
Source expand_goal(+BodyTerm, +Pos0, -Out, -Pos) is det
Source expand_goal(+BodyTerm, -Out) is det
Perform macro-expansion on body terms by calling goal_expansion/2.
Source $expand_closure(+BodyIn, +ExtraArgs, -BodyOut) is semidet
Source $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.
Source 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
Source already_expanded(+Goal, +Done, -RestDone) is semidet[private]
Source 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)
Source is_meta_call(+G0, +M, -Head) is semidet[private]
True if M:G0 resolves to a real meta-goal as specified by Head.
Source expand_meta(+MetaSpec, +G0, ?P0, -G, -P, +M, +Mlist, +Term, +Done)[private]
Source 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.
Source 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.
Source 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
Source 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.
Source 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.
Source 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.
Source expand_functional_notation(+G0, +P0, -G, -P, +M, +MList, +Term) is det[private]
To be done
- : position logic
- : make functions module-local
Source contains_functions(@Term) is semidet[private]
True when Term contains a function reference.
Source replace_functions(+GoalIn, +PosIn, -Eval, -EvalPos, -GoalOut, -PosOut, +ContextTerm) is det[private]
To be done
- Proper propagation of list, dict and brace term positions.
Source map_functions(+Arg, +Arity, +TermIn, +ArgInPos, -Term, -ArgPos, -Eval, -EvalPos, +Context)[private]
Source conj(+G1, +P1, +G2, +P2, -G, -P)[private]
Source function(?Term, +Context)[multifile]
True if function expansion needs to be applied for the given term.
Source 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.
Source f2_pos(?TermPos0, ?PosArg10, ?PosArg20, ?TermPos, ?PosArg1, ?PosArg2) is det[private]
Source f1_pos(?TermPos0, ?PosArg10, ?TermPos, ?PosArg1) is det[private]
Source f_pos(?TermPos0, ?PosArgs0, ?TermPos, ?PosArgs) is det[private]
Source atomic_pos(?TermPos0, -AtomicPos) is det[private]
Position progapation routines.
Source pos_nil(+Nil, -Nil) is det[private]
Source pos_list(+List0, -H0, -T0, -List, -H, -T) is det[private]
Position propagation for lists.
Source extend_1_pos(+FunctionPos, -FArgPos, -EvalPos, -EArgPos, -VarPos)[private]
Deal with extending a function to include the return value.
Source 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.
Source simplify(+ControlIn, +Pos0, -ControlOut, -Pos) is det[private]
Simplify control structures
To be done
- Much more analysis
- Turn this into a separate module
Source 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.
Source eval_true(+Goal) is semidet[private]
Source eval_false(+Goal) is semidet[private]
Source compile_meta_call(+CallIn, -CallOut, +Module, +Term) is det[private]
Compile (complex) meta-calls into a clause.
Source replace_subterm(From, To, TermIn, TermOut)[private]
Replace instances (==/2) of From inside TermIn by To.
Source 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.

Source expand_term(Arg1, Arg2, Arg3, Arg4)
Source $including
Source expand_goal(Arg1, Arg2)