Contents

class project

A CodeSonar or CodeSurfer project.

The project class corresponds to the SDG abstraction.

Get the currently-loaded project with project.current().

project Members

Constructors none
Static Methods current(), is_loaded(), lookup_project_handle()
Methods __cmp__(), __eq__(), __ge__(), __gt__(), __hash__(), __le__(), __lt__(), __ne__(), __repr__(), __str__(), compunits(), compunits_vector(), error_count(), file_is_newer(), find_compunit(), find_procedure(), handle(), has_unnormalized_c_asts(), ignored_compunits(), incremental_capable(), is_read_only(), lookup_compunit_handle(), lookup_point_handle(), lookup_procedure_handle(), lookup_sfile_handle(), lookup_sfileinst_handle(), lookup_symbol(), lookup_symbol_handle(), name(), param_symbol(), prj_files_directory(), procedures(), procedures_vector(), root_directories(), root_directory_count(), sfiles(), symbols(), token_search(), warning_count(),

project Details

class cs.project

A CodeSonar or CodeSurfer project.

static current()

Get the currently-loaded project.

Return type:project
Returns:The project .
Raises:result.ERROR_SDG_NOT_PRESENT if no project is currently loaded. 
>>> project.current()
apitest
static is_loaded()

Check: is a project currently loaded?

Return type:bool
Returns:True if a project is currently loaded, False otherwise. 
>>> project.is_loaded()
True
static lookup_project_handle(project_handle)

Get a project from a handle.

Parameters:project_handle (str) – The project’s handle, as returned by project.handle().
Return type:project
Returns:The project corresponding to project_handle.
Raises:result.ELEMENT_NOT_PRESENT if the specified project_handle is not the handle of the current project.

Use this function to retrieve a project based on a handle, a string generated by project.handle() that uniquely identifies the project . The handle can be stored externally and this method can be used to retrieve the project whenever needed.

>>> p = project.current()
>>> ph = p.handle()
>>> p2 = project.current().lookup_project_handle(ph)
>>> p2.name() == p.name()
True
__cmp__(other)

Comparison function for project , with respect to a stable overall ordering.

Parameters:other (project) – The project object to compare against.
Return type:int
Returns:An integer N such that:
  • N==0 if the two objects compare equal
  • N<0 if self < other
  • N>0 if self > other
 
>>> myproj = project.current()
>>> myproj.__cmp__(project.current())
0
__eq__(b)

Equality operator for project .

Parameters:b (project) – The project to compare against.
Return type:bool
Returns:True if self and b compare equal, False otherwise. 
>>> myproj = project.current()
>>> myproj == project.current()
True
__ge__(b)

Greater-than-or-equal operator for project .

Parameters:b (project) – The project to compare against.
Return type:bool
Returns:True if self >= b , False otherwise. 
>>> myproj = project.current()
>>> myproj >= project.current()
True
__gt__(b)

Greater-than operator for project .

Parameters:b (project) – The project to compare against.
Return type:bool
Returns:True if self > b , False otherwise. 
>>> myproj = project.current()
>>> myproj > project.current()
False
__hash__()

Hash function for project .

Return type:int
Returns:The hash value. 
>>> myproj = project.current()
>>> hash(myproj)
42
__le__(b)

Less-than-or-equal operator for project .

Parameters:b (project) – The project to compare against.
Return type:bool
Returns:True if self <= b , False otherwise. 
>>> myproj = project.current()
>>> myproj <= project.current()
True
__lt__(b)

Less-than operator for project .

Parameters:b (project) – The project to compare against.
Return type:bool
Returns:True if self < b , False otherwise. 
>>> myproj = project.current()
>>> myproj < project.current()
False
__ne__(b)

Inequality operator for project .

Parameters:b (project) – The project to compare against.
Return type:bool
Returns:False if self and b compare equal, True otherwise. 
>>> myproj = project.current()
>>> myproj != project.current()
False
__repr__()

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

Return type:str
Returns:The string representation. 
>>> v0 = project.current()
>>> repr(v0)
'apitest'
__str__()

Get a simple string representation of a project object.

Return type:str
Returns:The string representation. 
>>> v0 = project.current()
>>> str(v0)
'apitest'
compunits()

Get an iterator over all the compilation units ( compunit ) in a project.

Return type:project_compunits_iterator
Returns:The initialized project_compunits_iterator . 
>>> for cu in project.current().compunits(): # iteration managed by project_compunits_iterator.__iter__()
...                                          # and project_compunits_iterator.__next__()
...     if cu.is_user():
...         print(cu)
...
C:\cygwin\home\alex\testmicros\API\apitest.cpp
compunits_vector()

Get the compilation units contributing to a project.

Return type:[compunit]
Returns:A list of the compilation units ( compunit ) contributing to the project. 
>>> v0 = project.current()
>>> v0.compunits_vector()
(<cs.compunit System Initialization, Indirect & Undefined>, <cs.compunit /mys0/alex/trunk/cso-tests/regression/functional/apitest.cpp>)
error_count([including_ignored = false])

Get the number of errors encountered in compiling the files in a project.

Parameters:

including_ignored (bool) – (optional) True to include errors in compilations that are dropped from the build, False to exclude those errors.
Return type:

int
Returns:

The total number of errors (summing over all compilation units, subject to including_ignored).
Raises: 
>>> v0 = project.current()
>>> v0.error_count(True)
0

>>> v0 = project.current()
>>> v0.error_count()
0
file_is_newer(fn)

Check: is a file newer than the rest of the project?

Parameters:fn (str) – The pathname of the file to check.
Return type:bool
Returns:True if the file at fn is newer than the rest of the project, False otherwise.
Raises:result.ERROR_IO_STAT if fn cannot be found. 
>>> v0 = project.current()
>>> v0.file_is_newer('/mys0/alex/trunk/cso-tests/regression')
False
find_compunit(id)

Retrieve the compilation unit with the specified unique ID.

Parameters:

id (int) – The compilation unit ID.
Return type:

compunit
Returns:

The compunit found whose unique ID is id.
Raises:

To get a compilation unit’s ID, use compunit.get_id().

>>> cu = next(c for c in project.current().compunits() if c.is_user())
>>> cu.name()
'C:\\cygwin64\\home\\alex\\apitest.cpp'
>>> cuid = cu.get_id()
>>> cuid
268435457
>>> cu2 = project.current().find_compunit(cuid)
>>> cu == cu2
True
find_procedure(procname)

Retrieve the procedure with the specified verbose name.

Parameters:procname (str) – The procedure’s verbose name as returned by procedure.verbose_name().
Return type:procedure
Returns:The first procedure found whose verbose name is procname.
Raises:result.PDG_NOT_FOUND if no such procedure exists.

It is possible for a project to have multiple procedures whose name is procname. For example, two compilation units may each have a static function called procname. In this case, project.find_procedure() will return the first one it encounters.

>>> proc =  project.current().find_procedure('mymalloc(int)')
>>> for pt in proc.callers():
...        fl = pt.file_line()
...        print(fl[0].normalized_name().split('/')[-1], fl[1])
...
apitest.cpp 37
apitest.cpp 15
find_procedure(id)

Retrieve the procedure with the specified unique ID.

Parameters:id (int) – The procedure ID.
Return type:procedure
Returns:The procedure found whose unique ID is id.
Raises:result.NO_SUCH_PDG if no such procedure exists.

To get a procedure’s ID, use procedure.get_id().

>>> v0 = project.current()
>>> v0.find_procedure(-5)
<cs.procedure whoknows(int)>
handle()

Get a handle for this project .

Return type:str
Returns:The project’s handle.

Use this function to retrieve a handle to the project which can be stored externally and used with project.lookup_project_handle() to retrieve the project when needed. This handle is valid only for the analysis it was generated from. If you rebuild the project, the handle will no longer be valid.

A handle is a string consisting of letters (upper and lower case( and numbers, and could also include the following characters: “+”, “=”, and “_”.

>>> project.current().handle()
''
has_unnormalized_c_asts()

Check: was the project built to retain unnormalized C/C++ ASTs?

Return type:bool
Returns:True if the project was built to retain unnormalized C/C++ ASTs, False otherwise.

Unnormalized C/C++ ASTs are retained if the project is built with RETAIN_UNNORMALIZED_C_AST=Yes. If this returns False, the following methods will not be able to retrieve ASTs ( ast ) whose family is ast_family.C_UNNORMALIZED.

>>> v0 = project.current()
>>> v0.has_unnormalized_c_asts()
False
ignored_compunits()

Get a list of the compilation units that are dropped from the build.

Return type:()
Returns:A list of the compilation units ( compunit ) that are dropped from the build. 
>>> v0 = project.current()
>>> v0.ignored_compunits()
()
incremental_capable()

Check: was INCREMENTAL_BUILD=Yes specified in the configuration file?

Return type:bool
Returns:True if INCREMENTAL_BUILD=Yes, False otherwise. 
>>> v0 = project.current()
>>> v0.incremental_capable()
True
is_read_only()

Check: is the project read-only?

Return type:bool
Returns:True if the project is read-only, False otherwise. 
>>> v0 = project.current()
>>> v0.is_read_only()
True
lookup_compunit_handle(compunit_handle)

Get a compunit from a handle.

Parameters:

compunit_handle (str) – The compunit’s handle, as returned by compunit.handle().
Return type:

compunit
Returns:

The compunit corresponding to compunit_handle.
Raises:

Use this function to retrieve a compunit based on a handle: a string generated by compunit.handle() that uniquely identifies the compunit . The handle can be stored externally and this method can be used to retrieve the compunit whenever needed.

>>> cu = next(c for c in project.current().compunits() if c.name().endswith('apitest.cpp'))
>>> ch = cu.handle()
>>> ch
'goCAgAI='
>>> cu2 = project.current().lookup_compunit_handle(ch)
>>> cu == cu2
True
lookup_point_handle(point_handle)

Get a point from a handle.

Parameters:

point_handle (str) – The point’s handle, as returned by point.handle().
Return type:

point
Returns:

The point corresponding to point_handle.
Raises:

Use this function to retrieve a point based on a handle: a string generated by point.handle() that uniquely identifies the point . The handle can be stored externally and this method can be used to retrieve the point whenever needed.

>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> pt = next(iter(barfn.points()))
>>> pth = pt.handle()
>>> pth
'goCAgAILAg=='
>>> pt2 = project.current().lookup_point_handle(pth)
>>> pt == pt2
True
lookup_procedure_handle(proc_handle)

Get a procedure from a handle.

Parameters:

proc_handle (str) – The procedure’s handle, as returned by procedure.handle().
Return type:

procedure
Returns:

The procedure corresponding to proc_handle.
Raises:

Use this function to retrieve a procedure based on a handle: a string generated by procedure.handle() that uniquely identifies the procedure . The handle can be stored externally and this method can be used to retrieve the procedure whenever needed.

>>> barfn = next(p for p in project.current().procedures() if p.name()=='bar')
>>> ph = barfn.handle()
>>> p2 = project.current().lookup_procedure_handle(ph)
>>> p2 == barfn
True
lookup_sfile_handle(sfile_handle)

Get a sfile from a handle.

Parameters:

sfile_handle (str) – The sfile’s handle, as returned by sfile.handle().
Return type:

sfile
Returns:

The sfile corresponding to sfile_handle.
Raises:

Use this function to retrieve a sfile based on a handle: a string generated by sfile.handle() that uniquely identifies the sfile . The handle can be stored externally and this method can be used to retrieve the sfile whenever needed.

>>> sf = next(project.current().sfiles())
>>> sh = sf.handle()
>>> sf2 = project.current().lookup_sfile_handle(sh)
>>> sf == sf2
True
lookup_sfileinst_handle(sfileinst_handle)

Get a sfileinst from a handle.

Parameters:

sfileinst_handle (str) – The sfileinst’s handle, as returned by sfileinst.handle().
Return type:

sfileinst
Returns:

The sfileinst corresponding to sfileinst_handle.
Raises:

Use this function to retrieve an sfileinst based on a handle: a string generated by sfileinst.handle() that uniquely identifies the sfileinst . The handle can be stored externally and this method can be used to retrieve the sfileinst whenever needed.

>>> sfi = next(project.current().sfiles()).arbitrary_instance()
>>> sfh = sfi.handle()
>>> sfi2 = project.current().lookup_sfileinst_handle(sfh)
>>> sfi == sfi2
True
lookup_symbol(symname)

Retrieve a symbol by verbose name.

Parameters:symname (str) – The symbol’s verbose name, as returned by symbol.verbose_name().
Return type:symbol
Returns:The symbol .
Raises:result.ELEMENT_NOT_PRESENT if there is no symbol associated with symname. 
>>> v0 = project.current()
>>> v0.lookup_symbol('foo')
<cs.symbol foo>
lookup_symbol_handle(symbol_handle)

Get a symbol from a handle.

Parameters:

symbol_handle (str) – The symbol’s handle, as returned by symbol.handle().
Return type:

symbol
Returns:

The symbol corresponding to symbol_handle.
Raises:

Use this function to retrieve a symbol based on a handle: a string generated by symbol.handle() that uniquely identifies the symbol . The handle can be stored externally and this method can be used to retrieve the symbol whenever needed.

>>> s = project.current().lookup_symbol('foo')
>>> sh = s.handle()
>>> s2 = project.current().lookup_symbol_handle(sh)
>>> s == s2
name()

Get the name of a project.

Return type:str
Returns:The project name (a string). 
>>> v0 = project.current()
>>> v0.name()
'apitest'
param_symbol(num)

Retrieve $param_NUM: the symbol representing the NUM’th formal parameter.

Parameters:

num (int) – The number of the parameter to be retrieved (counting from the left, starting from 1).
Return type:

symbol
Returns:

The $param_num symbol .
Raises:

The $param_n symbols have global scope, no type, and do not belong to any specific function.

>>> v0 = project.current()
>>> v0.param_symbol(2)
<cs.symbol $param_2>
prj_files_directory()

Get the absolute file system path for the project analysis directory (pfilesname.prj_files) for a project.

Return type:str
Returns:The file system path of the .prj_files directory (a string).

If called from within a slave process of a distributed analysis, this function can return a file system path that only exists on the computer running the master process (analysis master or daemon master). Even if the two processes are on the same machine, the slave may be running as a different user and may not have permission to access the directory.

>>> v0 = project.current()
>>> v0.prj_files_directory()
'/mys0/alex/trunk/cso-tests/regression/functional/apitest.test/apitest.prj_files'
procedures()

Get an iterator over all the procedures ( procedure ) in a project.

Return type:project_procedures_iterator
Returns:The initialized project_procedures_iterator . 
>>> for proc in project.current().procedures(): # iteration managed by project_procedures_iterator.__iter__()
...                                             # and project_procedures_iterator.__next_()
...     if proc.callers_count()>0 and proc.get_kind() == procedure_kind.USER_DEFINED:
...         print(proc, proc.callers_count())
...
mymalloc 2
bar 4
procedures_vector()

Get the procedures defined in a project.

Return type:[procedure]
Returns:A list of the procedures ( procedure ) defined in the project. 
>>> v0 = project.current()
>>> v0.procedures_vector()
(<cs.procedure #System_Initialization>, <cs.procedure whoknows(int)>, <cs.procedure #File_Initialization>, <cs.procedure mymalloc>, <cs.procedure bar>, <cs.procedure foo>)
root_directories()

Get an iterator over the set of root directories ( directory ) deduced by inspecting all source file paths in the project.

Return type:project_root_directories_iterator
Returns:The initialized project_root_directories_iterator . 
>>> for rd in project.current().root_directories(): # iteration managed by project_root_directories_iterator.__iter__()
...                                                 # and project__root_directories_iterator.__next__()
...     print(rd)
...
C:\cygwin\home\alex\
C:
root_directory_count()

Get the number of root directories in the project.

Return type:int
Returns:The number of root directories in the project. 
>>> v0 = project.current()
>>> v0.root_directory_count()
2
sfiles()

Get an iterator over all the source files ( sfile ) in a project.

Return type:project_sfiles_iterator
Returns:The initialized project_sfiles_iterator . 
>>> for sf in project.current().sfiles():  # iteration managed by project_sfiles_iterator.__iter__()
...                                         # and project_sfiles_iterator.__next__()
...      if 'apitest' in sf.name():
...          print(sf)
...
C:\cygwin\home\alex\testmicros\API\apitest.cpp
C:\cygwin\home\alex\testmicros\API\apitest.h
symbols()

Get an iterator over the symbols ( symbol ) in a project.

Return type:symbol_universe_iterator
Returns:The initialized symbol_universe_iterator . 
>>> for sym in project.current().symbols(): # iteration managed by symbol_universe_iterator.__iter__()
...                                         # and symbol_universe_iterator.__next__()
...     if sym.is_string() and sym.get_compunit().is_user():
...         print(sym, sym.represented_string())
...
#string1 bar
#string0 foo
token_search(q)

Execute the specified cross-reference query over the tokens in a project.

Parameters:q (xr_query) – An xr_query that fully specifies the search conditions.
Return type:xr_query_iterator
Returns:An xr_query_iterator over the query results ( xr_tuple ). 
>>> q = xr_query()
>>> q.add_term_filter('whoknows')
>>> for t in project.current().token_search(q):  # iteration managed by xr_query_iterator.__iter__()
...                                              # and xr_query_iterator.__next__()
...
...     print(t.get_file().normalized_name().split('/')[-1],
...           t.get_line(), t.get_kind_role())
...
apitest.cpp 5 func_definition
apitest.cpp 6 func_call
warning_count([including_ignored = false])

Get the number of compiler warnings encountered in compiling the files in a project.

Parameters:

including_ignored (bool) – (optional) True to include warnings in compilations that are dropped from the build, False to exclude those warnings.
Return type:

int
Returns:

The total number of warnings (summing over all compilation units, subject to including_ignored).
Raises:

Note that this method retrieves the number of compiler warnings: it is not related to CodeSonar warnings.

>>> v0 = project.current()
>>> v0.warning_count(True)
0

>>> v0 = project.current()
>>> v0.warning_count()
0