Contents

• class xr_query
  • xr_query Members
  • xr_query Details

class xr_query

Fully specifies a cross-referencing query over the tokens in an analyzed project.

The key properties of an xr_query are summarized in the following table.

Property	Description	Set With
Limit	The maximum number of query results to obtain.	xr_query.set_limit()
Offset	The offset in the overall result set from which to start returning results.	xr_query.set_offset()
Filters	Zero or more filters that together define the query conditions.	xr_query.add_term_filter(), xr_query.add_kind_filter(), xr_query.add_role_filter(), xr_query.add_kind_role_filter(), xr_query.set_definition_filter(), xr_query.set_occurrence_filter().
Flags	xr_query_flags specifying additional properties for the query.	xr_query.set_flags()
Comparator	A comparison callable that will be used to order the query result tuples.	xr_query.set_cmp()

An occurrence of a token T will be included in the returned query result set if all of the following are true.

• Result set position. The tuple representing the occurrence has a suitable position in the full result set: in the range Offset..(Offset+Limit-1), where Limit is specified with xr_query.set_limit() and Offset is specified with xr_query.set_offset().
  • If a comparator has been specified with xr_query.set_cmp(), positions are determined after the full set of query results is sorted.
  • If Limit is set to 0, the query returns all tuples at position Offset or higher.
• Name. T’s name hash matches an integer value specified with xr_query.add_term_filter(), OR T’s name matches a string value specified with xr_query.add_term_filter(), OR no term filters were specified.
• Kind. The occurrence kind ( xr_kind ) matches one of those specified with xr_query.add_kind_filter() OR no kind filters were specified. If T is a procedure ( procedure ), its basename as retrieved by procedure.basename() is used.
• Role. The occurrence role ( xr_role ) matches one of those specified with xr_query.add_role_filter() OR no role filters were specified.
• Kind-Role. The occurrence kind-role ( xr_kind_role ) matches one of those specified with xr_query.add_kind_role_filter() OR no kind-role filters were specified.
• Occurrence location. The occurrence satisfies the restrictions of the occurrence filter ( xr_file_query ) specified with xr_query.set_occurrence_filter() OR no occurrence filter was specified.
• Definition location. The definition corresponding to the occurrence satisfies the restrictions of the definition filter ( xr_file_query ) specified with xr_query.set_definition_filter() OR no definition filter was specified.
• Flags. The occurrence satisfies the flags ( xr_query_flags ) specified with xr_query.set_flags() OR no flags were specified.

To execute the query, use project.token_search().

xr_query Members

Constructor	__init__()
Methods	__repr__(), __str__(), add_kind_filter(), add_kind_role_filter(), add_role_filter(), add_term_filter(), set_cmp(), set_definition_filter(), set_flags(), set_limit(), set_occurrence_filter(), set_offset()

xr_query Details

class cs.xr_query

Fully specifies a cross-referencing query over the tokens in an analyzed project.

__init__()

Constructor.

Constructs an xr_query object with:

• Limit==0
• Offset==0
• no filters
• no flags
• no comparator

>>> xr_query()
<cs.xr_query ...>

__repr__()

Get a representation of a xr_query object that includes information useful for debugging.

Return type:str Returns:The string representation.

>>> v0 = xr_query()
>>> repr(v0)
'<cs.xr_query ...>'

__str__()

Get a simple string representation of a xr_query object.

Return type:str Returns:The string representation.

>>> v0 = xr_query()
>>> str(v0)
'<cs.xr_query ...>'

add_kind_filter(s)

Add a kind filter to a xr_query object.

Parameters:s (xr_kind) – The filter. Return type:NoneType

• Side effects: Modifies self.

If any kinds are specified with this method, the query will only match token occurrences whose xr_kind matches one of those kinds.

>>> v0 = xr_query()
>>> v0.add_kind_filter(xr_kind.FIELD)

add_kind_role_filter(s)

Add a kind-role filter to a xr_query object.

Parameters:s (xr_kind_role) – The filter. Return type:NoneType

• Side effects: Modifies self.

If any kind-roles are specified with this method, the query will only match token occurrences whose xr_kind and xr_role match one of those kind-role pairs.

>>> v0 = xr_query()
>>> v0.add_kind_role_filter(xr_kind_role.FIELD_SIZEOF)

add_role_filter(s)

Add a role filter to a xr_query object.

Parameters:s (xr_role) – The filter. Return type:NoneType

• Side effects: Modifies self.

If any roles are specified with this method, the query will only match token occurrences whose xr_role matches one of those roles.

>>> v0 = xr_query()
>>> v0.add_role_filter(xr_role.READ)

add_term_filter(s)

Add a term filter to a xr_query object.

Parameters:s (int) – The hash of the token to filter, as computed by xr_namehash() or returned by another function. Return type:NoneType

• Side effects: Modifies self.

If any values are specified with add_term_filter(), the query will only match token occurrences for which

• the token name hash matches an integer value specified with add_term_filter(), or
• the token name matches a string value specified with add_term_filter().

A procedure name token is the procedure basename as returned by procedure.basename().

>>> xrq = xr_query()
>>> h = xr_namehash('myproc')
>>> h
3995777589763558680
>>> xrq.add_term_filter(h)

add_term_filter(s)

Add a term filter to a xr_query object.

Parameters:s (str) – The token to filter. Return type:NoneType

• Side effects: Modifies self.

If any strings are specified with this method, the query will only match token occurrences where the token name matches one of those strings.

If any values are specified with add_term_filter(), the query will only match token occurrences for which

• the token name hash matches an integer value specified with add_term_filter(), or
• the token name matches a string value specified with add_term_filter().

A procedure name token is the procedure basename as returned by procedure.basename().

>>> v0 = xr_query()
>>> v0.add_term_filter('myprocedure')

set_cmp(_cmp)

Set the comparator that will be used to order the query results.

Parameters:_cmp ((xr_tuple, xr_tuple) -> int) – The comparator to set: a callable C such that for xr_tuple objects a and b, C(a,b) returns an integer N where N<0 if a<b, N==0 if a==b, and N>0 if a>b according to your ordering scheme. Specify None if you do not want to impose an ordering on query results. Return type:NoneType

• Side effects: Modifies self.

When a query comparator is specified, all query results will be retrieved and ordered as specified by _cmp BEFORE imposing the query Offset and Limit. Specifying a comparator will therefore generally increase query processing time.

If you set a comparison function, query result uniquification will always take place.

• If xr_query_flags.UNIQUIFY is specified, uniquification is performed with respect to your comparison function (if the raw result set contains a subset of tuples that are all equal according to your comparison function, all but one of those tuples will be removed).
• If xr_query_flags.UNIQUIFY is not specified, uniquification is performed with respect to complete tuple uniqueness (if the raw result set contains a subset of tuples that are all idenfical across all tuple values, all but one of those tuples will be removed).

>>> xrq = xr_query()
>>> xrq.set_cmp(xr_tuple.__le__)

set_definition_filter(s)

Set restrictions on the location of the token occurrence.

Parameters:s (xr_file_query) – The filter. Return type:NoneType

• Side effects: Modifies self.

The query will only return tuples ( xr_tuple ) for which the source files and lines of the token definitions (xr_tuple.get_def_file() and xr_tuple.get_def_line(), respectively) satisfy the restrictions imposed by s.

>>> v0 = xr_query()
>>> v1 = xr_file_query()
>>> v0.set_definition_filter(v1)

set_flags(s)

Set additional properties for a query.

Parameters:s (xr_query_flags) – Flags specifying additional query properties. Return type:NoneType

• Side effects: Modifies self.

>>> v0 = xr_query()
>>> v0.set_flags(xr_query_flags.POPULATE_COUNTERS)

set_limit(s)

Set the maximum number of query results.

Parameters:s (int) – The maximum number of query results. Return type:NoneType

• Side effects: Modifies self.

The query will return at most this many tuples ( xr_tuple ). Set to 0 to return all results at the specified Offset position or higher.

The offset of the first result returned is specified with xr_query.set_offset().

>>> v0 = xr_query()
>>> v0.set_limit(111)

set_occurrence_filter(s)

Set restrictions on the location of the token occurrence.

Parameters:s (xr_file_query) – The filter. Return type:NoneType

• Side effects: Modifies self.

The query will only return tuples ( xr_tuple ) for which the source files and lines of the token occurrences (xr_tuple.get_file() and xr_tuple.get_line(), respectively) satisfy the restrictions imposed by s.

>>> v0 = xr_file_query()
>>> v1 = xr_query()
>>> v1.set_occurrence_filter(v0)

set_offset(s)

Set the position in the overall result set such that the query will return results starting from this position.

Parameters:s (int) – The offset in the overall result set from which to start returning result tuples ( xr_tuple ). Return type:NoneType

• Side effects: Modifies self.

The total number of tuples returned is limited by the value specified with xr_query.set_limit().

>>> v0 = xr_query()
>>> v0.set_offset(34)