Statement

Statement#

class scubatrace.Statement(node: Node, parent: BlockStatement | Function | File)#

Bases: object

A statement in the source code.

ancestor_by_type(type: str) → Statement | None#

The nearest ancestor of the specified type.

Parameters:: type (str) – The type of the ancestor to find.
Returns:: The nearest ancestor of the specified type, or None if not found.
Return type:: Statement | None

ancestor_by_types(types: list[str]) → Statement | None#

The nearest ancestor of any of the specified types.

Parameters:: types (list[str]) – The types of the ancestors to find.
Returns:: The nearest ancestor of any of the specified types, or None if not found.
Return type:: Statement | None

walk_backward(filter: Callable[[Statement], bool] | None = None, stop_by: Callable[[Statement], bool] | None = None, depth: int = -1, base: str = 'control') → Generator[Statement, None, None]#

Walks backward through the control flow graph of the statement.

Parameters:

filter (Callable[[Statement], bool] | None) – A filter function to apply to each statement. If the filter returns True, the statement is yielded.
stop_by (Callable[[Statement], bool] | None) – A function to stop the walking when it returns True.
depth (int) – The maximum depth to walk backward. Default is -1, which means no limit.
base (str) – The base type of the walk. Can be “control”, “data_dependent”, or “control_dependent”.

Yields:

Statement – The statements that match the filter or all statements if no filter is provided.

walk_forward(filter: Callable[[Statement], bool] | None = None, stop_by: Callable[[Statement], bool] | None = None, depth: int = -1, base: str = 'control') → Generator[Statement, None, None]#

Walks forward through the control flow graph of the statement.

Parameters:

filter (Callable[[Statement], bool] | None) – A filter function to apply to each statement. If the filter returns True, the statement is yielded.
stop_by (Callable[[Statement], bool] | None) – A function to stop the walking when it returns True.
depth (int) – The maximum depth to walk forward. Default is -1, which means no limit.
base (str) – The base type of the walk. Can be “control”, “data_dependent”, “control_dependent”, “call”.

Yields:

Statement – The statements that match the filter or all statements if no filter is provided.

property definitions: dict[Identifier, list[Statement]]#

Definitions of variables in the statement.

Includes variables that are defined in the whole project.

property end_column: int#: The end column of the statement.

property end_line: int#: The end line of the statement.

property field_name: str | None#: The field name of the tree-sitter node.

property file: File#: The file this statement belongs to.

property function: Function | None#

The function this statement belongs to, if any.

If the statement is not part of a function, returns None.

property identifiers: list[Identifier]#

Identifiers in the statement.

This includes variables, function names, and other identifiers.

abstract property is_jump_statement: bool#: Checks if the statement is a jump statement (e.g., break, continue, return).

property is_taint_from_entry: bool#: Checks if the variables of the statement are tainted from the parameters of the function.

property language: type[Language]#: The language of the file this statement belongs to.

property left_values: list[Identifier]#

Variables that are left values in the statement.

Left values are variables that are modified or assigned in the statement.

property length#: The length of the statement in lines.

property next_sibling: Statement | None#

The next sibling statement in the same block.

If there is no next sibling, returns None.

node: Node#: The tree-sitter node representing this statement.

property node_type: str#: The type of the tree-sitter node.

parent: BlockStatement | Function | File#: The parent block or function or file this statement belongs to.

property post_control_dependents: list[Statement]#: Statements that are dependent on this statement in the control flow.

property post_controls: list[Statement]#

Post-control statements of the statement.

These are statements that are executed after this statement in the control flow.

property post_data_dependents: dict[Identifier, list[Statement]]#: Data-dependent statements that are executed after this statement.

property pre_control_dependents: list[Statement]#: Statements that are dependent on this statement in the control flow before it.

property pre_controls: list[Statement]#

Pre-control statements of the statement.

These are statements that are executed before this statement in the control flow.

property pre_data_dependents: dict[Identifier, list[Statement]]#: Data-dependent statements that are executed before this statement.

property preorder_successor: Statement | None#

The preorder successor of the statement.

The preorder successor is the next statement in the preorder traversal of the block. If there is no such statement, returns None.

property prev_sibling: Statement | None#

The previous sibling statement in the same block.

If there is no previous sibling, returns None.

property project: Project#: The project this statement belongs to.

property references: dict[Identifier, list[Statement]]#

References to variables in the statement.

Includes variables that are in the whole project.

property right_uncle_ancestor: Statement | None#

The right uncle ancestor of the statement.

The right uncle ancestor is the next statement in the control flow after this statement.

property right_values: list[Identifier]#

Variables that are right values in the statement.

Right values are variables that are used in the statement but not modified or assigned.

property signature: str#: A unique signature for the statement.

property start_column: int#: The start column of the statement.

property start_line: int#: The start line of the statement.

property text: str#: The text of the statement.

property variables: list[Identifier]#: Variables in the statement.

class scubatrace.SimpleStatement(node: Node, parent: BlockStatement | Function | File)#

Bases: Statement

static create(node: Node, parent: BlockStatement | Function | File)#

Factory function to create a SimpleStatement instance based on the language of the parent.

Parameters:

node (Node) – The tree-sitter node representing the statement.
parent (BlockStatement | Function | File) – The parent block, function, or file this statement belongs to.

Returns:

An instance of the appropriate SimpleStatement subclass based on the language.

Return type:

SimpleStatement

property is_jump_statement: bool#: Checks if the statement is a jump statement (e.g., break, continue, return).

property post_controls: list[Statement]#

Post-control statements of the statement.

These are statements that are executed after this statement in the control flow.

class scubatrace.BlockStatement(node: Node, parent: BlockStatement | Function | File)#

Bases: Statement

static create(node: Node, parent: BlockStatement | Function | File)#

Factory function to create a BlockStatement instance based on the language of the parent.

Parameters:

node (Node) – The tree-sitter node representing the block statement.
parent (BlockStatement | Function | File) – The parent block, function, or file this statement belongs to.

Returns:

An instance of the appropriate BlockStatement subclass based on the language.

Return type:

BlockStatement

query(query: str) → list[Statement]#

Executes a tree-sitter query to find statements in the block.

Parameters:: query (str) – The tree-sitter query to execute.
Returns:: A list of statements that match the query.
Return type:: list[Statement]

query_identifier(query: str) → Identifier | None#

Executes a tree-sitter oneshot query to find an identifier in the block.

Parameters:: query (str) – The tree-sitter oneshot query to execute.
Returns:: The identifier that matches the query, or None if not found.
Return type:: Identifier | None

query_identifiers(query: str) → list[Identifier]#

Executes a tree-sitter query to find identifiers in the block.

Parameters:: query (str) – The tree-sitter query to execute.
Returns:: A list of identifiers that match the query.
Return type:: list[Identifier]

query_oneshot(query: str) → Statement | None#

Executes a tree-sitter oneshot query to find statements in the block.

Parameters:: query (str) – The tree-sitter oneshot query to execute.
Returns:: A list of statements that match the query.
Return type:: list[Statement]

statement_by_field_name(field_name: str) → Statement | None#

The statement that contains the specified tree-sitter ast field name.

Parameters:: field_name (str) – The tree-sitter ast field name to search for.
Returns:: The statement that contains the specified field name, or None if not found.
Return type:: Optional[Statement]

statements_by_field_name(field_name: str) → list[Statement]#

The statements that contain the specified tree-sitter ast field name.

Parameters:: field_name (str) – The tree-sitter ast field name to search for.
Returns:: A list of statements that contain the specified field name.
Return type:: list[Statement]

statements_by_line(line: int) → list[Statement]#

The statements that are located on the specified line number.

Parameters:: line (int) – The line number to check.
Returns:: A list of statements that are located on the specified line.
Return type:: list[Statement]

statements_by_type(type: str, recursive: bool = False) → list[Statement]#

The statements that are of the specified type.

Parameters:

type (str) – The tree-sitter ast type of the statements to return.
recursive (bool) – If True, recursively search in sub-statements.

Returns:

A list of statements that match the specified type.

Return type:

list[Statement]

statements_by_types(types: list[str], recursive: bool = False) → list[Statement]#

The statements that are of any of the specified types.

Parameters:

types (list[str]) – The tree-sitter ast types of the statements to return.
recursive (bool) – If True, recursively search in sub-statements.

Returns:

A list of statements that match any of the specified types.

Return type:

list[Statement]

property block_identifiers: list[Identifier]#

Identifiers declared directly in the block.

Only includes identifiers that are declared in this block and excludes those found in sub-statements.

property block_variables: list[Identifier]#

Variables declared directly in the block.

Only includes variables that are declared in this block and excludes those found in sub-statements.

property is_jump_statement: bool#: Checks if the statement is a jump statement (e.g., break, continue, return).

property post_controls: list[Statement]#

Post-control statements of the statement.

These are statements that are executed after this statement in the control flow.

property statements: list[Statement]#: Sub-statements of the block.

Statement

Contents

Statement#