# loki.ir.find

Visitor classes that allow searching the IR

Functions

`is_child_of`(node, other) | Utility function to test relationship between nodes.
`is_parent_of`(node, other) | Utility function to test relationship between nodes.

Classes

`FindNodes`(match[, mode, greedy]) | Find `Node` instances that match a given criterion.
`FindScopes`(match[, greedy]) | Find all parent nodes for node `match`.
`PatternFinder`(pattern) | Find a pattern of nodes given as tuple/list of types within a given tree.
`SequenceFinder`(node_type) | Find repeated nodes of the same type in lists/tuples within a given tree.

class FindNodes(match, mode='type', greedy=False)

  Bases: `Visitor`

  Find `Node` instances that match a given criterion.

  Parameters:

    - match – Node type(s) or node instance to look for.

    - mode (optional) –

      Drive the search. Accepted values are:

      - `'type'` (default) : Collect all instances of type `match`.

      - `'scope'` : Return the `InternalNode` in which the object `match` appears.

    - greedy (bool, optional) – Do not recurse for children of a matched node.

  Returns:

    All nodes in the traversed IR that match the criteria.

  Return type:

    list

  classmethod default_retval()

    Default return value is an empty list.

    Return type:

      list

  rules = {'scope': <function FindNodes.<lambda>>, 'type': <function FindNodes.<lambda>>}

    Mapping of available `mode` selectors to match rules.

  visit_object(o, **kwargs)

    Fallback method for objects that do not match any handler.

    Parameters:

      - o – The object to visit.

      - **kwargs – Optional keyword arguments passed to the visit methods.

    Returns:

      The default return value.

    Return type:

      `GenericVisitor.default_retval()`

  visit_tuple(o, **kwargs)

    Visit all elements in the iterable and return the combined result.

  visit_list(o, **kwargs)

    Visit all elements in the iterable and return the combined result.

  visit_Node(o, **kwargs)

    Add the node to the returned list if it matches the criteria and visit all children.

  visit_TypeDef(o, **kwargs)

    Custom handler for `TypeDef` nodes that does not traverse the body (reason being that discovering nodes such as declarations from inside the type definition would be unexpected if called on a containing `Subroutine` or `Module`)

class SequenceFinder(node_type)

  Bases: `Visitor`

  Find repeated nodes of the same type in lists/tuples within a given tree.

  Parameters:

    node_type – The node type to look for.

  classmethod default_retval()

    Default return value is an empty list.

    Return type:

      list

  visit_tuple(o, **kwargs)

    Visit all children and look for sequences of matching type.

  visit_list(o, **kwargs)

    Visit all children and look for sequences of matching type.

class PatternFinder(pattern)

  Bases: `Visitor`

  Find a pattern of nodes given as tuple/list of types within a given tree.

  Parameters:

    pattern (iterable of types) – The type pattern to look for.

  classmethod default_retval()

    Default return value is an empty list.

    Return type:

      list

  static match_indices(pattern, sequence)

    Return indices of matched patterns in sequence.

  visit_tuple(o, **kwargs)

    Visit all children and look for sequences of nodes with types matching the pattern.

  visit_list(o, **kwargs)

    Visit all children and look for sequences of nodes with types matching the pattern.

is_parent_of(node, other)

  Utility function to test relationship between nodes.

  Note that this can be expensive for large subtrees.

  Returns:

    Return True if `other` is contained in the IR below `node`, otherwise return False.

  Return type:

    bool

is_child_of(node, other)

  Utility function to test relationship between nodes.

  Note that this can be expensive for large subtrees.

  Returns:

    Return True if `node` is contained in the IR below `other`, otherwise return False.

  Return type:

    bool

class FindScopes(match, greedy=True)

  Bases: `FindNodes`

  Find all parent nodes for node `match`.

  Parameters:

    - match (`Node`) – The node for which the parent nodes are to be found.

    - greedy (bool, optional) – Stop traversal when `match` was found.

  visit_Node(o, **kwargs)

    Add the node to the list of ancestors that is passed down to the children and, if `o` is `match`, return the list of ancestors.