Package com.oracle.truffle.api.instrumentation

Class SourceSectionFilter.Builder

java.lang.Object
com.oracle.truffle.api.instrumentation.SourceSectionFilter.Builder
Enclosing class:
SourceSectionFilter
public final class SourceSectionFilter.Builder extends Object
Configure your own SourceSectionFilter before creating its instance. Specify various parameters by calling individual SourceSectionFilter.Builder methods. When done, call build().
Since:
0.12

  • Method Details

    • sourceFilter

      public SourceSectionFilter.Builder sourceFilter(SourceFilter sourceFilter)
      Add a source filter.
      Since:
      0.32

    • sourceIs

      public SourceSectionFilter.Builder sourceIs(Source... source)
      Add a filter for all source sections that reference one of the given sources.
      Since:
      0.12

    • sourceIs

      public SourceSectionFilter.Builder sourceIs(SourceSectionFilter.SourcePredicate predicate)
      Adds custom predicate to filter inclusion of sources. The predicate must always return the same result for a source instance otherwise the behavior is undefined. The predicate should be able run on multiple threads at the same time.
      Parameters:
      predicate - a test for inclusion
      Since:
      0.17

    • rootNameIs

      public SourceSectionFilter.Builder rootNameIs(Predicate<String> predicate)
      Adds custom predicate to filter inclusion for root names. The root name might be null if not provided by the guest language. If the language returns a changing value it is unspecified which root name is going to be matched. The predicate must always return the same result for a String instance otherwise the behavior is undefined. The predicate should be able run on multiple threads at the same time.
      Parameters:
      predicate - a test for inclusion
      Since:
      0.27

    • mimeTypeIs

      public SourceSectionFilter.Builder mimeTypeIs(String... mimeTypes)
      Add a filter for all source sections that declare one of the given mime-types. Mime-types which are compared must match exactly one of the mime-types specified by the target guest language.
      Parameters:
      mimeTypes - matches one of the given mime types
      Returns:
      the builder to chain calls
      Since:
      0.12

    • tagIs

      public SourceSectionFilter.Builder tagIs(Class<?>... tags)
      Add a filter for all source sections that are tagged with one of the given tags.
      Parameters:
      tags - matches one of the given tags
      Returns:
      the builder to chain calls
      Since:
      0.12

    • tagIsNot

      public SourceSectionFilter.Builder tagIsNot(Class<?>... tags)
      Add a filter for all source sections that are not tagged with one of the given tags.
      Parameters:
      tags - matches not one of the given tags
      Returns:
      the builder to chain calls
      Since:
      0.12

    • sourceSectionEquals

      public SourceSectionFilter.Builder sourceSectionEquals(SourceSection... section)
      Add a filter for all source sections that equal one of the given source sections.
      Parameters:
      section - matches one of the given source sections
      Returns:
      the builder to chain calls
      Since:
      0.12

    • sourceSectionAvailableOnly

      public SourceSectionFilter.Builder sourceSectionAvailableOnly(boolean availableOnly)
      Add a filter for available source sections. By default all locations with or without available source sections are provided. If this flag is set to true then null and not available source sections are filtered out.
      Parameters:
      availableOnly - true to include only non-null and available source sections, false to include all.
      Returns:
      the builder to chain calls
      Since:
      24.1

    • rootSourceSectionEquals

      public SourceSectionFilter.Builder rootSourceSectionEquals(SourceSection... section)
      Add a filter for all root source sections that equal one of the given source sections. All descendant source sections of a matching root source section are included in the filter. This can mean in the dynamic language domain that all nodes of a function for which the root source section matches the given source section is instrumented but its inner functions and its nodes are not instrumented.
      Parameters:
      section - matches one of the given root source sections
      Returns:
      the builder to chain calls
      Since:
      0.12

    • indexNotIn

      public SourceSectionFilter.Builder indexNotIn(SourceSectionFilter.IndexRange... ranges)
      Add a filter for all source sections which indices are not contained in one of the given index ranges.
      Parameters:
      ranges - matches indices that are not contained in one of the given index ranges
      Returns:
      the builder to chain calls
      Since:
      0.12

    • indexIn

      public SourceSectionFilter.Builder indexIn(SourceSectionFilter.IndexRange... ranges)
      Add a filter for all source sections which indices are contained in one of the given index ranges.
      Parameters:
      ranges - matches indices that are contained in one of the given index ranges
      Returns:
      the builder to chain calls
      Since:
      0.12

    • indexIn

      public SourceSectionFilter.Builder indexIn(int startIndex, int length)
      Add a filter for all source sections where the index is inside a startIndex (inclusive) plus a given length (exclusive).
      Parameters:
      startIndex - the start index (inclusive)
      length - the number of matched characters
      Returns:
      the builder to chain calls
      Since:
      0.12

    • lineIn

      public SourceSectionFilter.Builder lineIn(SourceSectionFilter.IndexRange... ranges)
      Add a filter for all source sections where lines are contained in one of the given index ranges. Line indices must be greater than or equal to 1.
      Parameters:
      ranges - matches lines that are contained in one of the given index ranges
      Returns:
      the builder to chain calls
      Since:
      0.12

    • lineNotIn

      public SourceSectionFilter.Builder lineNotIn(SourceSectionFilter.IndexRange... ranges)
      Add a filter for all source sections where lines are not contained in one of the given index ranges. Line indices must be greater than or equal to 1.
      Parameters:
      ranges - matches lines that are not contained in one of the given index ranges
      Returns:
      the builder to chain calls
      Since:
      0.12

    • lineIn

      public SourceSectionFilter.Builder lineIn(int startLine, int length)
      Add a filter for all source sections where the line is inside a startLine (first index inclusive) plus a given length (last index exclusive).
      Parameters:
      startLine - the start line (inclusive)
      length - the number of matched lines
      Returns:
      the builder to chain calls
      Since:
      0.12

    • lineStartsIn

      public SourceSectionFilter.Builder lineStartsIn(SourceSectionFilter.IndexRange... ranges)
      Add a filter for all source sections where the line starts in one of the given index ranges. Line indices must be greater than or equal to 1.
      Parameters:
      ranges - matches lines that start in one of the given index ranges
      Returns:
      the builder to chain calls
      Since:
      0.12

    • lineEndsIn

      public SourceSectionFilter.Builder lineEndsIn(SourceSectionFilter.IndexRange... ranges)
      Add a filter for all source sections where the line ends in one of the given index ranges. Line indices must be greater than or equal to 1.
      Parameters:
      ranges - matches lines that end in one of the given index ranges
      Returns:
      the builder to chain calls
      Since:
      0.12

    • columnIn

      public SourceSectionFilter.Builder columnIn(SourceSectionFilter.IndexRange... ranges)
      Add a filter for all source sections where the columns are contained in one of the given index ranges. Column indices must be greater than or equal to 1.
      Parameters:
      ranges - matches columns that are contained in one of the given index ranges
      Returns:
      the builder to chain calls
      Since:
      0.33

    • columnNotIn

      public SourceSectionFilter.Builder columnNotIn(SourceSectionFilter.IndexRange... ranges)
      Add a filter for all source sections where columns are not contained in one of the given index ranges. Column indices must be greater than or equal to 1.
      Parameters:
      ranges - matches columns that are not contained in one of the given index ranges
      Returns:
      the builder to chain calls
      Since:
      0.33

    • columnIn

      public SourceSectionFilter.Builder columnIn(int startColumn, int length)
      Add a filter for all source sections where the column is inside a startColumn (first index inclusive) plus a given length (last index exclusive).
      Parameters:
      startColumn - the start column (inclusive)
      length - the number of matched columns
      Returns:
      the builder to chain calls
      Since:
      0.33

    • columnStartsIn

      public SourceSectionFilter.Builder columnStartsIn(SourceSectionFilter.IndexRange... ranges)
      Add a filter for all source sections where the column starts in one of the given index ranges. Column indices must be greater than or equal to 1.
      Parameters:
      ranges - matches columns that start in one of the given index ranges
      Returns:
      the builder to chain calls
      Since:
      0.33

    • columnEndsIn

      public SourceSectionFilter.Builder columnEndsIn(SourceSectionFilter.IndexRange... ranges)
      Add a filter for all sources sections where the column ends in one of the given index ranges. Column indices must be greater than or equal to 1.
      Parameters:
      ranges - matches columns that end in one of the given index ranges
      Returns:
      the builder to chain calls
      Since:
      0.33

    • lineIs

      public SourceSectionFilter.Builder lineIs(int line)
      Add a filter for all sources sections where the line is exactly the given line. Line indices must be greater than or equal to 1. *
      Parameters:
      line - the line to be matched
      Returns:
      the builder to chain calls
      Since:
      0.12

    • includeInternal

      public SourceSectionFilter.Builder includeInternal(boolean internal)
      Add a filter that includes or excludes internal root nodes. By default, internal roots are included, call with false to exclude internal code from instrumentation.
      Returns:
      the builder to chain calls
      Since:
      0.29

    • and

      public SourceSectionFilter.Builder and(SourceSectionFilter filter)
      Adds all the filters defined in the given filter.
      Parameters:
      filter - an existing filter to be included
      Returns:
      the builder to chain calls
      Since:
      0.30

    • build

      public SourceSectionFilter build()
      Finalizes and constructs the SourceSectionFilter instance.
      Returns:
      the built filter expression
      Since:
      0.12