Ekeko 2.0.9 API documentation

damp.ekeko.jdt.ast documentation

Low-level relations of JDT AST nodes.

Reifies the relation between ASTNode instances ?node
and their kind ?keyword.
In general, ?keyword is the keyword that corresponds 
to the capitalized, unqualified name of ?node's class.

Examples:
;; all method declarations
(ekeko* [?node] (ast :MethodDeclaration ?node))
;; all ast nodes of any kind
(ekeko* [?keyword ?node] (ast ?keyword ?node))

See also:
API documentation of org.eclipse.jdt.core.dom.ASTNode

Relation between ASTNode ?ast and Clojure vector ?locationVector 
representing its location: [begin-character-index-in-file, 
                            end-chararacter-index-in-file, 
                            begin-line-number, 
                            end-line-number]

Relation between ASTNode ?ast and the MethodDeclaration ?m that encompasses it.

Operationally, performs a recursive ascend.

See also: 
Predicate ast-encompassing-method-non-failing/2 unifies ?m with nil
if there is no encompassing method.

Relation between ASTNode ?ast and either the MethodDeclaration ?m that encompasses it, 
or nil if there is no encopassing MethodDeclaration.

Operationally, performs a recursive ascend.

See also: 
Predicate ast-encompassing-method/2 which fails if there is no encompassing method.

Relation between an ASTNode instance ?ast and its parent node 
?parent. Note that this predicate fails for CompilationUnit instances, 
which function as the root of the AST.

See also:
- API documentation of org.eclipse.jdt.core.dom.ASTNode
- Condition (has ?property ?parent ?value),
which also works for primitive values and lists that stem from an AST.

Relation between an ASTNode and one of its ancestor ASTNodes.

See also:
- binary predicate value-parent+/2 which works for property values that aren't nodes
- binary predicate astorvalue-parent+/2 which works for both

Relation between an ASTNode instance ?ast and the root of its tree ?cu,
an instance of CompilationUnit.

See also:
API documentation of org.eclipse.jdt.core.dom.ASTNode

Relation between ASTNode ?ast and the TypeDeclaration ?t that encompasses it.

Relation between an ASTNode or a list that stems from an ASTNode 
and one of its offspring nodes or their values (i.e., complete recursive descent).

Note that this predicate will produce bindings 
   ?offspring->list
   ?offspring->list members 

See also: binary predicate child+/2, which implements the sub-relation 
between two ASTNodes only.

Relation between an ASTNode or a property value and their root CompilationUnit.

Like binary ast/2 predicate, but ensures ?ast is
 a declaration ASTNode instance.

See also:
Binary predicate ast/2

Reifies the relation between a declaration AST node ?ast 
of kind ?key and any of its modifiers ?mod.

See also: 
Ternary predicate ast/3

Like binary ast/2 predicate, but ensures ?ast 
 is a resolveable declaration ASTNode instance.

See also:
Binary predicates ast|resolveable/2 and ast|declaration/2.

Relation between an Expression instance ?ast and 
the keyword ?key representing its kind.

Relation between a reference-valued Expression instance ?ast and 
the keyword ?keyw representing its kind.

Like binary ast/2 predicate, but ensures ?ast is 
an ASTNode that accesses a field.

Note that ?ast can be an instance of FieldAccess, 
SuperFieldAccess, SimpleName or QualifiedName.

Like binary ast/2, but ensures ?ast is an ASTNode 
that invokes a method or constructor.

Note that ?ast can be an instance of MethodInvocation, 
SuperMethodInvocation, ClassInstanceCreation,
ConstructorInvocation or SuperConstructorInvocation

Relation between a local variable ?ast (either a SimpleName or QualifiedName), 
used as an expression, 
and the keyword ?key corresponding to its kind.

Like ast/2, but ensures ?name is the SimpleName 
of a formal parameter declaration.

Like binary ast/2 predicate, but ensures ?ast is an ASTNode
instance that can be resolved to an IBinding 
(i.e., implements method resolveBinding).

See also:
Binary predicate ast/2
API documentation of org.eclipse.jdt.core.dom.IBinding

Like ast/2, but ensures ?type is an 
instance of one of the Type subclasses.
Note that these are references to types within the source code, 
rather than a canonical representation of a type.

Same behaviour as has if keyword is a ChildProperty of SimpleProperty.
Same behaviour as child if keyword is a ChildListProperty.

See also:
Ternary predicate has/3 and child/3

Reifies the relation between an ASTNode instance ?node 
and its ASTNode children ?child that are either the value
of the child property or an element of the child list 
property named ?keyword. 
In contrast to has/3, ?child is therefore always an
instance of ASTNode. 

Note that ?keyword is the keyword that corresponds to 
the decapitalized name of the property's PropertyDescriptor.

Examples:
;;?child is any of the arguments to the method invocation ?inv
(ekeko* [?inv ?child] (ast :MethodInvocation ?inv)
                      (child :arguments ?inv ?child))

See also: 
Ternary predicate has/3 
API documentation of org.eclipse.jdt.core.dom.ASTNode 
and org.eclipse.jdt.core.dom.StructuralPropertyDescriptor

Transitive closure of the child relation.
 In other words, ?child is an ASTNode instance that resides at
 an arbitrary depth within the ASTNode instance ?node. 

Operationally, a recursive descent is performed through ?node. 

Examples:
;;?exp is an expression within method declaration ?m
(ekeko* [?m ?ch] (ast :MethodDeclaration ?m)
                 (child+ ?m ?ch))   

See also:
- Ternary predicate child/3.
- Binary predicate has+/2 which implements the super-relation
  between any two values.

Reifies the relation between an ASTNode instance ?node 
and the value ?child of its property named ?keyword.
 
 Here, ?keyword is the keyword that corresponds to the
 decapitalized name of the property's PropertyDescriptor. 
 In general, ?child is either another ASTNode instance, 
 a primitive value or an instance of ASTNode$NodeList. 

 Examples:
 ;; method invocations and their receiver
 (ekeko* [?inv ?exp]
   (ast :MethodInvocation ?inv) 
   (has :expression ?inv exp)) 
 ;; all properties of all compilation units 
 (ekeko* [?cu ?key ?child] 
   (ast :CompilationUnit ?cu) 
   (has ?key ?cu ?child))
 
 See also: 
 Ternary predicate child/3 
 API documentation of org.eclipse.jdt.core.dom.ASTNode 
 and org.eclipse.jdt.core.dom.StructuralPropertyDescriptor

Relation between a MethodDeclaration ?m, its control
 flow graph ?cfg (an EclipseCFG), 
 and its entry and exit points (both EclipseCFGNode instances), 
 all in a format suitable to be queried with
 the regular path expressions provided by the damp.qwal libraries.

 Example:

 Methods in which there is at least one path on which ?nodebefore is an AST
 node evaluated immediately before a ?return statement. A synthetic CFG node is allowed
 in between ?nodebefore and ?return. One transition to a synthetic node and the exit point 
 of the cfg is required. 
 See src-crystal/cfgthrows.png and src-crystal/cfguberreturn.png for
 example visualiations of control flow graphs.

 (ekeko* [?m ?cfg ?entry ?exit ?nodebefore ?return ?syntheticbetween ?syntheticend]
         (method-cfg-entry-exit ?m ?cfg ?entry ?exit)
         (fresh [?beforeReturn ?return]
                (project [?cfg]
                         (qwal ?cfg ?entry ?exit 
                               []
                               (q=>*)
                               (qcurrent [cfgnode]
                                         (node|cfg-node|ast cfgnode ?nodebefore))
                               q=>
                               (q? (qcurrent [cfgnode]
                                        (equals ?syntheticbetween cfgnode)
                                        (node|cfg|syntethic ?syntheticbetween)) q=>)
                               (qcurrent [cfgnode] 
                                         (node|cfg-node|ast cfgnode ?return)
                                         (ast :ReturnStatement ?return))
                               q=>
                               (qcurrent [cfgnode] 
                                         (equals ?syntheticend cfgnode)
                                         (node|cfg|syntethic ?syntheticend))
                               
                               q=>))))

 Equivalent, without information about synthetic nodes:
 (ekeko* [?m ?cfg ?entry ?exit ?nodebefore ?return]
         (method-cfg-entry-exit ?m ?cfg ?entry ?exit)
         (fresh [?beforeReturn ?return]
                (project [?cfg]
                         (qwal ?cfg ?entry ?exit 
                               []
                               (q=>*)
                               (qcurrent [cfgnode]
                                         (node|cfg-node|ast cfgnode ?nodebefore))
                               q=>
                               (q? (qcurrent [cfgnode] (node|cfg|syntethic? cfgnode) q=>))

                               (qcurrent [cfgnode] 
                                         (node|cfg-node|ast cfgnode ?return)
                                         (ast :ReturnStatement ?return))
                               q=>
                               (qcurrent [cfgnode] (node|cfg|syntethic? cfgnode))
                               q=>
                               ))))

See also:
Documentation of the damp.qwal library.

Relation between a MethodDeclaration ?m and its
ASTNode$NodeList list of statements ?slist in its body. 
Note that abstract methods are not included in this relation, 
but methods with en empty body are.

Relation between two (Simple/Qualified)Name instances whose qualified name as a string is the same.

Relation between a SimpleName or QualifiedName ASTNode and its fully qualified name as a string.

Relation between a QualifiedName ASTNode and its last SimpleName part.

Relation between a QualifiedName ASTNode and its qualifier QualiefiedName part .

Relation between a QualifiedName ASTNode and its identifier string.

Relation between two SimpleName instances that share the same identifier.

Relation between a SimpleName ASTNode and its identifier string.

Relation between a given EclipseCFGNode ?cfgnode and the ASTNode ?astnode that it wraps. 
Non-relational.

Logic goal that succeeds when a given CFGNode is synthetic. Non-relational.
Synthetic CFG nodes do not correspond to an AST node, but to a methods' uber return or throws node.

Function for testing whether a given CFGNode is synthetic.
Synthetic CFG nodes do not correspond to an AST node, but to a methods' uber return or throws node.

Relation of ASTNode property values that aren't ASTNode themselves:
nil, primitive values and lists.

Relation between an ASTNode property value that isn't an ASTNode itself
 (a primitive value, null, or a list) and one of its ancestor ASTNodes.

See also:
- binary predicate ast-parent+/2 which works for ASTNodes
- binary predicate astorvalue-parent+/2 which works for both

Relation of an ASTNode property value that isn't an ASTNode itself
and its raw value (either a primitive, nil, or a list).

Relation between a non-ASTNode property value and its root CompilationUnit.

Relation of all list-valued ASTNode property values.

Relation of all null-valued ASTNode property values.

Relation of all primitive-valued ASTNode property values.