Functional Traversal API

This section is for rule authors who need to navigate the parse tree.

The sqlfluff.utils.functional submodules provide a higher-level API for working with parse-tree segments and raw file slices. Rules using these classes can express traversal and filtering logic more concisely than working with the raw segment tree directly.

Source: sqlfluff/utils/functional/

Segments

Encapsulates a sequence of one or more BaseSegments.

The segments may or may not be contiguous in a parse tree. Provides useful operations on a sequence of segments to simplify rule creation.

Parameters:

Parameter	Type	Default	Description
_	BaseSegment
templated_file	TemplatedFile | None	None

Methods

all

all(
    predicate=None
) → bool

Do all the segments match?

Parameters:

Parameter	Type	Default	Description
predicate	Callable[[BaseSegment], bool] | None	None

Returns:

bool — See return type.

any

any(
    predicate=None
) → bool

Do any of the segments match?

Parameters:

Parameter	Type	Default	Description
predicate	Callable[[BaseSegment], bool] | None	None

Returns:

bool — See return type.

apply

apply(
    fn
) → list[Any]

Apply function to every item.

Parameters:

Parameter	Type	Default	Description
fn	Callable[[BaseSegment], Any]

Returns:

list[Any] — See return type.

children

children(
    predicate=None
) → Segments

Returns an object with children of the segments in this object.

Parameters:

Parameter	Type	Default	Description
predicate	Callable[[BaseSegment], bool] | None	None

Returns:

Segments — See return type.

find

find(
    segment
) → int

Returns index if found, -1 if not found.

Parameters:

Parameter	Type	Default	Description
segment	BaseSegment | None

Returns:

int — See return type.

first

first(
    predicate=None
) → Segments

Returns the first segment (if any) that satisfies the predicates.

Parameters:

Parameter	Type	Default	Description
predicate	Callable[[BaseSegment], bool] | None	None

Returns:

Segments — See return type.

get

get(
    index=0,
    default=None
) → BaseSegment | None

Return specified item. Returns default if index out of range.

Parameters:

Parameter	Type	Default	Description
index	int	0
default	BaseSegment | None	None

Returns:

BaseSegment | None — See return type.

iterate_segments

iterate_segments(
    predicate=None
) → collections.abc.Iterable[Segments]

Loop over each element as a fresh Segments.

Parameters:

Parameter	Type	Default	Description
predicate	Callable[[BaseSegment], bool] | None	None

Returns:

collections.abc.Iterable[Segments] — See return type.

last

last(
    predicate=None
) → Segments

Returns the last segment (if any) that satisfies the predicates.

Parameters:

Parameter	Type	Default	Description
predicate	Callable[[BaseSegment], bool] | None	None

Returns:

Segments — See return type.

recursive_crawl

recursive_crawl(
    seg_type,
    recurse_into=True
) → Segments

Recursively crawl for segments of a given type.

Parameters:

Parameter	Type	Default	Description
seg_type	str
recurse_into	bool	True

Returns:

Segments — See return type.

recursive_crawl_all

recursive_crawl_all() → Segments

Recursively crawl all descendant segments.

Returns:

Segments — See return type.

reversed

reversed() → Segments

Return the same segments in reverse order.

Returns:

Segments — See return type.

select

select(
    select_if=None,
    loop_while=None,
    start_seg=None,
    stop_seg=None
) → Segments

Retrieve range/subset.

NOTE: Iterates the segments BETWEEN start_seg and stop_seg, i.e. those segments are not included in the loop.

Parameters:

Parameter	Type	Default	Description
select_if	Callable[[BaseSegment], bool] | None	None
loop_while	Callable[[BaseSegment], bool] | None	None
start_seg	BaseSegment | None	None
stop_seg	BaseSegment | None	None

Returns:

Segments — See return type.

segment_predicates functions

These predicate functions are passed to Segments.select() and similar methods to filter segments by their properties.

and_

and_(
    functions
) → Callable[[BaseSegment], bool]

Returns a function that computes the functions and-ed together.

Parameters:

Parameter	Type	Default	Description
functions	Callable[[BaseSegment], bool]

Returns:

Callable[[BaseSegment], bool] — See return type.

get_type

get_type() → Callable[[BaseSegment], str]

Returns a function that gets segment type.

Returns:

Callable[[BaseSegment], str] — See return type.

is_code

is_code() → Callable[[BaseSegment], bool]

Returns a function that checks if segment is code.

Returns:

Callable[[BaseSegment], bool] — See return type.

is_comment

is_comment() → Callable[[BaseSegment], bool]

Returns a function that checks if segment is comment.

Returns:

Callable[[BaseSegment], bool] — See return type.

is_keyword

is_keyword(
    keyword_name
) → Callable[[BaseSegment], bool]

Returns a function that determines if it's a matching keyword.

Parameters:

Parameter	Type	Default	Description
keyword_name	str

Returns:

Callable[[BaseSegment], bool] — See return type.

is_meta

is_meta() → Callable[[BaseSegment], bool]

Returns a function that checks if segment is meta.

Returns:

Callable[[BaseSegment], bool] — See return type.

is_raw

is_raw() → Callable[[BaseSegment], bool]

Returns a function that checks if segment is raw.

Returns:

Callable[[BaseSegment], bool] — See return type.

is_templated

is_templated() → Callable[[BaseSegment], bool]

Returns a function that checks if segment is templated.

Returns:

Callable[[BaseSegment], bool] — See return type.

is_type

is_type(
    seg_type
) → Callable[[BaseSegment], bool]

Returns a function that determines if segment is one of the types.

Parameters:

Parameter	Type	Default	Description
seg_type	str

Returns:

Callable[[BaseSegment], bool] — See return type.

is_whitespace

is_whitespace() → Callable[[BaseSegment], bool]

Returns a function that checks if segment is whitespace.

Returns:

Callable[[BaseSegment], bool] — See return type.

not_

not_(
    fn
) → Callable[[BaseSegment], bool]

Returns a function that computes: not fn().

Parameters:

Parameter	Type	Default	Description
fn	Callable[[BaseSegment], bool]

Returns:

Callable[[BaseSegment], bool] — See return type.

or_

or_(
    functions
) → Callable[[BaseSegment], bool]

Returns a function that computes the functions or-ed together.

Parameters:

Parameter	Type	Default	Description
functions	Callable[[BaseSegment], bool]

Returns:

Callable[[BaseSegment], bool] — See return type.

raw_is

raw_is(
    raws
) → Callable[[BaseSegment], bool]

Returns a function that determines if segment matches one of the raw inputs.

Parameters:

Parameter	Type	Default	Description
raws	str

Returns:

Callable[[BaseSegment], bool] — See return type.

raw_slices

raw_slices(
    segment,
    templated_file
) → RawFileSlices

Returns raw slices for a segment.

Parameters:

Parameter	Type	Default	Description
segment	BaseSegment
templated_file	TemplatedFile | None

Returns:

RawFileSlices — See return type.

raw_upper_is

raw_upper_is(
    raws
) → Callable[[BaseSegment], bool]

Returns a function that determines if segment matches one of the raw inputs.

Parameters:

Parameter	Type	Default	Description
raws	str

Returns:

Callable[[BaseSegment], bool] — See return type.

templated_slices

templated_slices(
    segment,
    templated_file
) → TemplatedFileSlices

Returns raw slices for a segment.

Parameters:

Parameter	Type	Default	Description
segment	BaseSegment
templated_file	TemplatedFile | None

Returns:

TemplatedFileSlices — See return type.

RawFileSlices

Encapsulates a sequence of one or more RawFileSlice.

The slices may or may not be contiguous in a file. Provides useful operations on a sequence of slices to simplify rule creation.

Parameters:

Parameter	Type	Default	Description
_	RawFileSlice
templated_file	TemplatedFile

Methods

all

all(
    predicate=None
) → bool

Do all the raw slices match?

Parameters:

Parameter	Type	Default	Description
predicate	Callable[[RawFileSlice], bool] | None	None

Returns:

bool — See return type.

any

any(
    predicate=None
) → bool

Do any of the raw slices match?

Parameters:

Parameter	Type	Default	Description
predicate	Callable[[RawFileSlice], bool] | None	None

Returns:

bool — See return type.

select

select(
    select_if=None,
    loop_while=None,
    start_slice=None,
    stop_slice=None
) → RawFileSlices

Retrieve range/subset.

NOTE: Iterates the slices BETWEEN start_slice and stop_slice, i.e. those slices are not included in the loop.

Parameters:

Parameter	Type	Default	Description
select_if	Callable[[RawFileSlice], bool] | None	None
loop_while	Callable[[RawFileSlice], bool] | None	None
start_slice	RawFileSlice | None	None
stop_slice	RawFileSlice | None	None

Returns:

RawFileSlices — See return type.

raw_file_slice_predicates functions

Predicate functions for use with RawFileSlices.select(), mirroring the role of segment_predicates for the raw slice layer.

is_slice_type

is_slice_type(
    slice_types
) → Callable[[RawFileSlice], bool]

Returns a function that determines if segment is one of the types.

Parameters:

Parameter	Type	Default	Description
slice_types	str

Returns:

Callable[[RawFileSlice], bool] — See return type.