Contents

• class xr_file_query
  • xr_file_query Members
  • xr_file_query Details

class xr_file_query

A collection of filters used to restrict a xr_query .

There are multiple filter types, each of which may have zero or more associated filters. The types are as follows.

• absolute path: added with xr_file_query.add_absolute_filter()
• absolute path substring: added with xr_file_query.add_absolute_substring_filter()
• dirname: added with xr_file_query.add_dirname_filter()
• dirname substring: added with xr_file_query.add_dirname_substring_filter()
• basename: added with xr_file_query.add_basename_filter()
• basename substring: added with xr_file_query.add_basename_substring_filter()
• file: added with xr_file_query.add_file_filter()
• line number: added with xr_file_query.add_line_number_filter()

A query includes xr_file_query objects in two different contexts.

• xr_query.set_occurrence_filter() sets an xr_file_query object that restricts the files and lines for the token occurrence. Given a result tuple, these are the values returned by xr_tuple.get_file() and xr_tuple.get_line(), respectively.
• xr_query.set_definition_filter() sets an xr_file_query object that restricts the files and lines for the corresponding token definition. Given a result tuple, these are the values by xr_tuple.get_def_file() and xr_tuple.get_def_line(), respectively.

In both these contexts, the xr_file_query restricts the query as follows.

• Every filter type must be satisfied.
  • If there are multiple filters of a given type, at least one of them must match appropriately.
  • If there are no filters of a given type, it is considered to match everything.
• The query will include tokens in library model files if and only if the “reject libmodels” flag is set to False with xr_file_query.set_reject_libmodels().

xr_file_query Members

Constructor	__init__()
Methods	__repr__(), __str__(), add_absolute_filter(), add_absolute_substring_filter(), add_basename_filter(), add_basename_substring_filter(), add_dirname_filter(), add_dirname_substring_filter(), add_file_filter(), add_line_number_filter(), set_reject_libmodels()

xr_file_query Details

class cs.xr_file_query

A collection of filters used to restrict a xr_query .

__init__()

>>> xr_file_query()
<cs.xr_file_query ...>

__repr__()

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

Return type:str Returns:The string representation.

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

__str__()

Get a simple string representation of a xr_file_query object.

Return type:str Returns:The string representation.

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

add_absolute_filter(s)

Add an absolute path filter to a xr_file_query object.

Parameters:s (str) – The filter: a string that will be compared against the file’s absolute path. Return type:NoneType

• Side effects: Modifies self.

If any strings are specified with this method, a token occurrence or definition will only satisfy the xr_file_query if it is located in a source file whose absolute path exactly matches at least one of those strings.

Comparison is case-insensitive and treats path separators ‘/’ and ‘' as interchangeable.

>>> v0 = xr_file_query()
>>> v0.add_absolute_filter('/usr/alex/badfiles/badfile.c')

add_absolute_substring_filter(s)

Add an absolute path substring filter to a xr_file_query object.

Parameters:s (str) – The filter: a string that will be compared against the file’s absolute path. Return type:NoneType

• Side effects: Modifies self.

If any strings are specified with this method, a token occurrence or definition will only satisfy the xr_file_query if it is located in a source file whose absolute path has at least one of those strings as a substring.

Comparison is case-insensitive and treats path separators ‘/’ and ‘' as interchangeable.

>>> v0 = xr_file_query()
>>> v0.add_absolute_substring_filter("/usr/alex/badfiles/bad")

add_basename_filter(s)

Add a basename filter to a xr_file_query object.

Parameters:s (str) – The filter: a string that will be compared against the file’s basename. Return type:NoneType

• Side effects: Modifies self.

If any strings are specified with this method, a token occurrence or definition will only satisfy the xr_file_query if it is located in a source file whose basename exactly matches at least one of those strings.

Comparison is case-insensitive.

>>> v0 = xr_file_query()
>>> v0.add_basename_filter('badfile.c')

add_basename_substring_filter(s)

Add a basename substring filter to a xr_file_query object.

Parameters:s (str) – The filter: a string that will be compared against the file’s basename. Return type:NoneType

• Side effects: Modifies self.

If any strings are specified with this method, a token occurrence or definition will only satisfy the xr_file_query if it is located in a source file whose basename has at least one of those strings as a substring.

Comparison is case-insensitive.

>>> v0 = xr_file_query()
>>> v0.add_basename_substring_filter('badfile')

add_dirname_filter(s)

Add a dirname path filter to a xr_file_query object.

Parameters:s (str) – The filter: a string that will be compared against the file’s dirname. Return type:NoneType

• Side effects: Modifies self.

If any strings are specified with this method, a token occurrence or definition will only satisfy the xr_file_query if it is located in a source file whose dirname (ie, absolute path to file, omitting the basename and with no trailing slash) exactly matches one of those strings.

Comparison is case-insensitive and treats path separators ‘/’ and ‘' as interchangeable.

>>> v0 = xr_file_query()
>>> v0.add_dirname_filter('/usr/alex/badfiles/')

add_dirname_substring_filter(s)

Add a dirname path substring filter to a xr_file_query object.

Parameters:s (str) – The filter: a string that will be compared against the file’s dirname. Return type:NoneType

• Side effects: Modifies self.

If any strings are specified with this method, a token occurrence or definition will only satisfy the xr_file_query if it is located in a source file whose dirname (ie, absolute path to file, omitting the basename and with no trailing slash) has at least one of those strings as a substring.

Comparison is case-insensitive and treats path separators ‘/’ and ‘' as interchangeable.

>>> v0 = xr_file_query()
>>> v0.add_dirname_substring_filter('/badfiles/')

add_file_filter(s)

Add a file filter to a xr_file_query object.

Parameters:s (sfile) – The filter value: a source file ( sfile ). Return type:NoneType

• Side effects: Modifies self.

If any sfile objects are specified with this method, a token occurrence or definition will only satisfy the xr_file_query if it is located in at least one of the specified source files.

>>> sf = next(s for s in project.current().sfiles()
...           if s.name().endswith('apitest.cpp'))
>>> xfq = xr_file_query()
>>> xfq.add_file_filter(sf)

add_line_number_filter(s)

Add a line number filter to a xr_file_query object.

Parameters:s (int) – The filter value: a source line (line_number). Return type:NoneType Raises:OverflowError

• Side effects: Modifies self.

If any line numbers are specified with this method, a token occurrence or definition will only satisfy the xr_file_query if it is located on at least one of the specified lines.

>>> v0 = xr_file_query()
>>> v0.add_line_number_filter(15)

set_reject_libmodels(s)

Specify whether or not the query should include library model files.

Parameters:s (bool) – Set to True to exclude library model files; False to include library model files. Return type:NoneType

• Side effects: Modifies self.

>>> v0 = xr_file_query()
>>> v0.set_reject_libmodels(True)