Ent

class understand.Ent

Bases: object

An Understand entity

An entity is anything Understand has information on from the project’s source code, such as a file, class, function, or variable. The kind of the entity is returned from kind. Entities are connected to other entities through references like func1 calls func2. The refs method returns a list of references and the ref returns the first one.

Methods Summary

add_to_arch	Add the entity to the given architecture.
annotate	Add an annotation to the entity
annotations	Return the annotations associated with the entity.
comments	Return the comments associated with the entity.
contents	Return the contents of the entity.
control_flow_graph	Return a control flow graph for the entity.
depends	Return the dependencies of the class or file
dependsby	Return the ents depended on by the class or file
draw	Generate a graphics file for the entity
ents	Return a list of entities that reference, or are referenced by, the entity.
file_type	Return the file type of the entity
filerefs	Return a list of all references that occur in a file entity.
freetext	Return extra parser information
ib	Return the Info Browser information for an entity.
id	Return a unique numeric identifier for the entity.
kind	Return the kind object for the entity.
kindname	Return the simple name for the kind of the entity.
language	Return the language of the entity
lexer	Return a lexer object for the specified file entity.
library	Return the library the entity belongs to.
longname	Return the long name of the entity.
metric	Return the metric value for each item in metriclist
metrics	Return a list of metric names defined for the entity.
name	Return the shortname for an entity.
parameters	Return a string containing the parameters for the entity.
parent	Return the parent of the entity or None if none
parsetime	Return the last time the file entity was parse in the database.
ref	This is the same as ent.refs()[:1]
refs	Return a list of references.
relname	Return the relative name of the file entity.
simplename	Return the simplename for the entity.
type	Return the type string of the entity.
uniquename	Return the unique name of the entity.
value	Return the value associated with the entity.
violations	Return a list of violations located inside the file entity.

Methods Documentation

add_to_arch(arch) → None

Add the entity to the given architecture.

Parameters:

arch (str or understand.Arch) – the architecture to add the entity to. This can be the longname of the architecture (which does not have to exist) or an arch object

Return type:

None

Raises:

understand.UnderstandError – if arch name is invalid

annotate(text[, author[, offset]]) → None

Add an annotation to the entity

Parameters:

• text (str) – the text of the annotation

• author (str or None) – optional, the author of the annotation. Defaults to the current username

• offset (int or None) – optional, a line number to annotate. When not provided, the annotation is associated with the entity rather than a line.

Return type:

None

Raises:

understand.UnderstandError – if unable to annotate

annotations() → list[understand.Atn]

Return the annotations associated with the entity.

Return type:

list[understand.Atn]

Returns:

the list of annotations which may be empty

comments([style[, raw[, refkindstring]]]) → str

Return the comments associated with the entity.

Parameters:

• style (str or None) – optional, the comments location. Either “before” or “after”

• raw (bool or None) – optional, True will preserve the original formatting. False by default.

• refkindstring (str or None) – optional, a reference kind string. Use to pick between define and declare references.

Return type:

str or list(str)

Returns:

the comments associated with the entity.

Associated comments can appear before or after the entity declaration. The optional parameter style determines which comments are used.

Comments can be returned with their original formatting, or with the comment characters and certain repeating characters removed. Either way will preserve newlines. The parameter raw controls the formatting. If original formatting is preserved, the result will be a list of strings. Otherwise, a single string is returned.

The reference used for the comments can be controlled with the parameter refkindstring. For C++, the default is refkindstring is “definein”, which is almost always correct. However, to see comments associated with member declarations, “declarein” should be used. For Ada, there are many declaration kinds that may be used, including “declarein body”, “declarein spec” and “declarein instance”.

contents() → str

Return the contents of the entity.

Return type:

str

Returns:

the entity’s contents

Only certain entities are supported, such as files and defined functions. Entities with no contents will return empty string.

control_flow_graph() → understand.CFGraph

Return a control flow graph for the entity.

Return type:

understand.CFGraph

Returns:

the control flow graph if known or None

Only certain entities are supported. If no control information is known, then None will be returned.

depends()

Return the dependencies of the class or file

Return type:

dict(understand.Ent,list[understand.Ref])

Returns:

the dependencies as a dictionary

Each entity this entity depends on is a key in the dict. The value is a list of references that cause the dependency.

dependsby()

Return the ents depended on by the class or file

Return type:

dict(understand.Ent,list[understand.Ref])

Returns:

the dependencies to this entity as a dictionary

Each entity this entity is depended on by is a key in the dict. The value is a list of references that cause the dependency.

draw(graph, filename[, options[, variant]]) → None

Generate a graphics file for the entity

Parameters:

• graph (str) – the name of the graph to generate

• filename (str) – the output file

• options (str or None) – optional, graph options

• variant (str or None) – the variant of the graph to generate

Return type:

None

Raises:

understand.UnderstandError – if an error occurs

Available graphs vary by language and entity, but the name will be the same as the name in the Understand GUI. Some examples are:

• “Base Classes”

• “Butterfly”

• “Called By”

• “Control Flow”

• “Calls”

• “Declaration”

• “Depends On”

The output format is determined by the file name extension. Supported extensions are jpg, png, svg, vsdx, and vdx. Some graphs support dot file format.

The parameter options is used to specify parameters to generate the graphics. The format of the options string is “name=value”. Multiple options are seperated with a semicolon. spaces are allowed and are significant between multi-word field names, whereas, case is not significant. The valid names and values are the same as appear in that graph’s right click menu and vary by view. They may be abbreviated to any unique prefix of their full names. Some examples are:

• “Layout=Crossing; name=Fullname;Level=AllLevels”

• “Comments=On;Show Entity Name=On”

For Relationship graphs use secondent=EntityUniqueName to indicate the second entity

The parameter variant is used to select from the available variants for the graph. If a variant is not specified, then a default variant will be used.

If an error occurs, an UnderstandError will be raised. Some possible errors are:

• Draw Too Large - failed to allocate memory for the image

• Unknown Graph - the graph name did not match a known graph

• Unsupported File Type - unsupported file format

ents(refkindstring[, entkindstring]) → list[understand.Ent]

Return a list of entities that reference, or are referenced by, the entity.

Parameters:

• refkindstring (str) – a language-specific reference filter string

• entkindstring (str or None) – a language-specific entity filter string

Return type:

list[understand.Ent]

Returns:

referenced entities

The parameter entkindstring should specify what kind of referenced entities are to be returned. If it is not included, all referenced entities are returned.

file_type() → str

Return the file type of the entity

Return type:

str

Returns:

the file type of the entity

Possible values include “Ada”, “Assembly”, “Basic”, “C”, “C#”, “C++”, “CSS”, “CUDA”, “Delphi”, “Fortran”, “Html”, “Java”, “Javascript”, “Jovial”, “MSDos Batch”, “Objective-C”, “Objective-C++”, “Pascal”, “Perl”, “Php”, “Python”, “Sql”, “Tcl”, “Text”, “TypeScript”, “Verilog”, “VHDL”, “Xml” Unlike language, this method distinguishes between C and C++

filerefs([refkindstring[, entkindstring[, unique]]]) → list[understand.Ref]

Return a list of all references that occur in a file entity.

Parameters:

• refkindstring (str or None) – optional, a language-specific reference filter string

• entkindstring (str or None) – optional, a language-specific entity filter string

• unique (bool or None) – optional, if True return only the first matching reference to each unique entity. False by default

Return type:

list(understand.Ref)

Returns:

a list of references that occur in a file entity

If this is called on a non-file entity, it will return an empty list. The references returned will not necessarily have the file entity for their .scope value. If no parameters are given, all references are returned.

freetext(option) → str

Return extra parser information

Parameters:

option (str) – the type of information

Return type:

str or bool

Returns:

the value stored by the parser

Raises:

understand.UnderstandError – if unknown option

The available options are:

Option	Language	Return Value
AllowExceptions	C++	1 if Exceptions are allowed
AttrAddress	Jovial	overlay address expression
AttrArrayComponentSize	Ada	for t’component_size use <expr>
AttrArrayIndexRanges	Ada	type t is array(1..10,5..10) [=11,6]
AttrComponentFirstBit	Ada	at <> range <expr> .. <>
AttrComponentLastBit	Ada	at <> range <> .. <expr>
AttrComponentPosition	Ada	at <expr> range <> .. <>
AttrRecordAlignment	Ada	use at mod <expr>
AttrTypeSize	Ada	for type’s size use <expr>
Bitfield	C++	Bitfield size
DefinedInMacro	C++	Returns 1 if entity defined in macro expansion
InitText	C++	Text of initialization
InitValue	C++	Integer value of initialization
Inline	C++	1 if defined inline
InterruptPriority	C++	Return the interrupt priority for an entity
Linkage	C++	Returns ‘C’ if using C Parser
Location	C++	address of variable or function in embedded programming
Noexcept	C++ (Strict)	The expression passed to the noexcept(…) specifier in a function declaration
Parameters	C++	Parameter list for Macros and unresolved entities
Priority	Ada	Ada Priority Value
TemplateArguments	C++ (Strict)	The instantiation/specialization arguments
ThrowExceptions	C++	C++ Exceptions Thrown
UnderlyingType	C++ (Strict)	The ultimate type after looking through all typedefs and type aliases
CGraph		encoded control flow graph for entity

ib([options]) → list[str]

Return the Info Browser information for an entity.

Parameters:

options (str or None) – formatting options

Return type:

list[str]

Returns:

the Info Browser information

The parameter options may be used to specify some parameters used to create the text. The format of the options string is “name=value” or “{field-name}name=value”. Multiple options are separated with a semicolon. Spaces are allowed and are significant between multi-word field names, whereas, case is not significant. An option that specifies a field name is specific to that named field of the Info Browser. The available field names are similar to how they appear in the Info Browser but not always the same. See Information Browser for the full list.

A field may be disabled by specifying levels=0, or by specifying the field off, without specifying any option. For example, either of these will disable and hide the Metrics field:

• {metrics}levels=0;

• {metrics}=off;

The “Indent” option is available without a field name. It specifies the number of indent spaces to output for each level of a line of text. The default is 2.

Other options are the same as are displayed when right-clicking on the field name in the Understand tool. An example of a properly formatted option string would be:

“{metrics}=off;{calls}levels=-1;{callbys}levels=-1;{references}sort=name”

The Architectures field is not generated by this command and can be generated separately using db.archs(ent)

id() → int

Return a unique numeric identifier for the entity.

Return type:

int

Returns:

a unique identifer

The identifier is not guaranteed to remain constant after the database has been updated. An id can be converted back into an understand.Ent with db.ent_from_id(id). The id is used for comparisons and the hash function.

kind() → understand.Kind

Return the kind object for the entity.

Return type:

understand.Kind

Returns:

the kind object for the entity.

kindname() → str

Return the simple name for the kind of the entity.

Return type:

str

Returns:

the simple kind name

This is similar to ent.kind().name(), but does not create a Kind object.

language() → str

Return the language of the entity

Return type:

str

Returns:

the language of the entity

Possible values include “Ada”, “C++”,”C#”, “Fortran”, “Java”, “Jovial”, “Pascal”, “Python”, “VHDL” or “Web”. C is included with “C++”. To distinguish between C and “C++”, use file_type.

lexer([lookup_ents[, tabstop[, show_inactive[, expand_macros]]]]) → understand.Lexer

Return a lexer object for the specified file entity.

Parameters:

• lookup_ents (bool or None) – optional, enable entity and reference lookup from lexemes (understand.Lexeme.ent() and understand.Lexeme.ref()). True by default. Set to False to speed up lexer construction.

• tabstop (int or None) – optional, the width of tabs. This option is ignored. The width of tabs is always 1.

• show_inactive (bool or None) – optional, include lexemes in inactive code. True by default.

• expand_macros – optional, If true and if macro expansion text is stored, lexemes that are macros will be replaced with the lexeme stream of the expansion text. False by default.

Return type:

understand.Lexer

Returns:

a lexer for the file entity

Raises:

understand.UnderstandError – if unable to construct the lexer

The original source file must be readable and unchanged since the last database parse. If an error occurs, an UnderstandError will be raised. Possible errors are:

• FileModified - the file must not be modified since the last parse

• FileUnreadable - the file must be readable from the original location

• UnsupportedLanguage - the file language is not supported

library() → str

Return the library the entity belongs to.

Return type:

str

Returns:

the library of the entity

This will return “” if the entity does not belong to a library. Predefined Ada entities such as text_io will bin the ‘Standard’ library. Predefined VHDL entities will be in either the ‘std’ or ‘ieee’ libraries.

longname() → str

Return the long name of the entity.

Return type:

str

Returns:

the long name of the entity

If there is no long name defined, the regular name (ent.name()) is returned. Examples of entities with long names include files, c++ members, and most ada entities.

metric(metriclist [,format]) -> dict(str, metric value)

metric(metric[, format]) → value

Return the metric value for each item in metriclist

Parameters:

• metriclist (list(str) or tuple(str)) – a list or tuple of metric names

• metric (str) – a metric name

• format (str) – optional, a string equal to “auto”, “raw” or “string”. It defaults to “auto” which returns integer values as integers and real values as formatted strings. Use “raw” to get real values as floats. Use “string” to get integer values as formatted strings.

Return type:

dict(str, metric value) for metriclist or metric value for metric

Metric values can be ints, floats, formatted strings, or None if the metric is not available.

metrics() → list[str]

Return a list of metric names defined for the entity.

Return type:

list[str]

Returns:

a list of metric names defined for the entity.

name() → str

Return the shortname for an entity.

Return type:

str

Returns:

the short name for the entity.

For Java, this may return a name with a single dot in it. This is what str() shows.

parameters([shownames]) → str

Return a string containing the parameters for the entity.

Parameters:

shownames (bool or None) – optional, if True, return both names and types of the parameters. If False, return only the types of the parameters. True by default.

Return type:

str or None

Returns:

a string with the entity’s parameters.

There are some language-specific cases where there are no entities in the database for certain kinds of parameters. For example, in c++, there are no database entities for parameters for functions that are only declared, not defined, and there are no database entities for parameters for functional macro definitions. This method can be used to get some information about these cases. If no parameters are available, None is returned.

parent() → understand.Ent

Return the parent of the entity or None if none

Return type:

understand.Ent

Returns:

the parent if it exists or None

parsetime() → int

Return the last time the file entity was parse in the database.

Return type:

int

Returns:

the last time the entity was parsed in Unix/Postix Time. If the entity is not a parse file, it will be 0.

ref([refkindstring [,entkindstring]) → understand.Ref

This is the same as ent.refs()[:1]

refs([refkindstring[, entkindstring[, unique]]]) → list[understand.Ref]

Return a list of references.

Parameters:

• refkindstring (str or None) – optional, a language-specific reference filter string

• entkindstring (str or None) – optional, a language-specific entity filter string

• unique (bool or None) – optional, if True return only the first matching reference to each unique entity. False by default

Return type:

list(understand.Ref)

Returns:

a list of references

relname() → str

Return the relative name of the file entity.

Return type:

str

Returns:

the relative name of the file entity.

This is the fullname for the file, minus any root directories that are common for all project files. Return None for non-file entities.

simplename() → str

Return the simplename for the entity.

Deprecated since version 1048: Equivalent to understand.Ent.name()

type() → str

Return the type string of the entity.

Return type:

str

Returns:

the type of the entity

This is defined for entity kinds like variables and types, as well as entity kinds that have a return type like functions.

uniquename() → str

Return the unique name of the entity.

Return type:

str

Returns:

the unique name

This name is not suitable for use by an end user. Rather, it is a means of identifying an entity uniquely in multiple databases, perhaps as the source code changes slightly over time. The unique name is composed of things like parameters and parent names. So, some code changes will result in new uniquenames for the same intrinsic entity. Use db.lookup_uniquename() to convert a unqiuename back to an understand.Ent. This is what repr() shows.

value() → str

Return the value associated with the entity.

Return type:

str

Returns:

the value associated with the entity

This is for enumerators, initialized variables, and macros. Not all languages are supported.

violations() → list[understand.Violation]

Return a list of violations located inside the file entity.

Return type:

list[understand.Violation]

Returns:

list of violations.

This function returns None for non-file entities. File entities with no violations will return an empty list.