filter.md

title	tags	keywords	last_updated
Filter	quering	quering, query, filter, ast, elements	October 5, 2015

Spoon aims at giving developers a way to query code elements in one single line of code in the normal cases. Code query is Spoon is done in plain Java, in the spirit of an embedded DSL. The information that can be queried is that of a well-formed typed AST. For this, we provide the query API, based on the notion of Filter (javadoc). A Filter defines a predicate of the form of a matches method that returns true if an element is part of the filter. A Filter is given as parameter to a depth-first search algorithm. During AST traversal, the elements satisfying the matching predicate are given to the developer for subsequent treatment. This table gives an excerpt of built-in filters.

Filter class	Description
AbstractFilter (javadoc)	defines an abstract filter based on matching on the element types.
TypeFilter (javadoc)	returns all meta-model elements of a certain type (e.g. all assignment statements).
AnnotationFilter (javadoc)	returns all elements annotated with a given annotation type.
ReturnOrThrowFilter (javadoc)	returns all elements that ends the execution flow of a method.
InvocationFilter (javadoc)	returns all accesses to a given executable or any executable that overrides it.
VariableAccessFilter (javadoc)	returns all accesses to a given variable.
FieldAccessFilter (javadoc)	returns all accesses to a given field.
ReferenceTypeFilter (javadoc)	returns all references of a given type.
DirectReferenceFilter (javadoc)	returns all references to a given element by using reference equality.
NameFilter (javadoc)	filters elements by name.
RegexFilter (javadoc)	filters elements with a regular expression on the element's code.
CompositeFilter (javadoc)	defines a composite filter, which can compose several filters together by using FilteringOperator (javadoc).
OverridingMethodFilter (javadoc)	get all overriding methods from the method given.
OverriddenMethodFilter (javadoc)	get all overridden methods from the method given.

See below a code example about the usage of these filters. Three filters of them are used. The first returns all AST nodes of type CtAssignment (javadoc). The second one selects all deprecated classes. The last one is a user-defined filter that only matches public fields across all classes.

// collecting all assignments of a method body
list1 = methodBody.getElements(new TypeFilter(CtAssignment.class));

// collecting all deprecated classes
list2 = rootPackage.getElements(new AnnotationFilter(Deprecated.class));

// creating a custom filter to select all public fields
list3 = rootPackage.getElements(
  new AbstractFilter<CtField>(CtField.class) {
    @Override
    public boolean matches(CtField field) {
      return field.getModifiers.contains(ModifierKind.PUBLIC);
    }
  }
);