Contents

• class procedure_metricclass
  • procedure_metricclass Members
  • procedure_metricclass Details

class procedure_metricclass

A procedure granularity metric class.

The procedure granularity metric classes are managed by procedure_metricclass_manager .

• For a manually computed metric, your plug-in should:

• Create a new metric class with procedure_metricclass_manager.create().
• Compute values for the metric.
• As values are computed, report them to the hub with procedure_metricclass.report().
• If necessary, retract metric values with with procedure_metricclass.retract().

• If you want CodeSonar to compute and report metric values automatically, use a metric function decorator.

You can retrieve metric values with procedure_metricclass.value(), and examine metric properties with procedure_metricclass.description(), procedure_metricclass.tag(), and procedure_metricclass.flags().

For more information about metrics in CodeSonar, see the Metrics manual page.

procedure_metricclass Members

Constructors	none
Methods	__cmp__(), __eq__(), __ge__(), __gt__(), __hash__(), __le__(), __lt__(), __ne__(), __repr__(), __str__(), allowed(), always_discarded(), description(), flags(), report(), retract(), tag(), value()

procedure_metricclass Details

class cs.procedure_metricclass

A procedure granularity metric class.

__cmp__(other)

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

Parameters:other (procedure_metricclass) – The procedure_metricclass object to compare against. Return type:int Returns:An integer N such that:

• N<0 if self < other
• N==0 if self == other
• N>0 if self > other

self and other will only compare equal if they are the same procedure_metricclass object.

>>> procmetrics = procedure_metricclass_manager.metricclasses()
>>> pm1 = next(procmetrics)
>>> pm1
<cs.metricclass V>
>>> pm2 = next(procmetrics)
>>> pm2
<cs.metricclass mvG>
>>> pm1.__cmp__(pm2)
-1

__eq__(b)

Equality operator for procedure_metricclass .

Parameters:b (procedure_metricclass) – The procedure_metricclass object to compare against. Return type:bool Returns:True if self equal to b , False otherwise.

>>> procmetrics = procedure_metricclass_manager.metricclasses()
>>> pm1 = next(procmetrics)
>>> pm1
<cs.metricclass V>
>>> pm2 = next(procmetrics)
>>> pm2
<cs.metricclass mvG>
>>> pm1 == pm2
False

__ge__(b)

Greater-than-or-equal operator for procedure_metricclass .

Parameters:b (procedure_metricclass) – The procedure_metricclass object to compare against. Return type:bool Returns:True if self >= b , False otherwise.

>>> procmetrics = procedure_metricclass_manager.metricclasses()
>>> pm1 = next(procmetrics)
>>> pm1
<cs.metricclass V>
>>> pm2 = next(procmetrics)
>>> pm2
<cs.metricclass mvG>
>>> pm1 >= pm2
False

__gt__(b)

Greater-than operator for procedure_metricclass .

Parameters:b (procedure_metricclass) – The procedure_metricclass object to compare against. Return type:bool Returns:True if self > b , False otherwise.

>>> procmetrics = procedure_metricclass_manager.metricclasses()
>>> pm1 = next(procmetrics)
>>> pm1
<cs.metricclass V>
>>> pm2 = next(procmetrics)
>>> pm2
<cs.metricclass mvG>
>>> pm1 > pm2
False

__hash__()

Get a hash value for this procedure_metricclass .

Return type:int

>>> procmetrics = procedure_metricclass_manager.metricclasses()
>>> pm1 = next(procmetrics)
>>> pm1
<cs.metricclass V>
>>> hash(pm1)
1823796896

__le__(b)

Less-than-or-equal operator for procedure_metricclass .

Parameters:b (procedure_metricclass) – The procedure_metricclass object to compare against. Return type:bool Returns:True if self <= b , False otherwise.

>>> procmetrics = procedure_metricclass_manager.metricclasses()
>>> pm1 = next(procmetrics)
>>> pm1
<cs.metricclass V>
>>> pm2 = next(procmetrics)
>>> pm2
<cs.metricclass mvG>
>>> pm1 <= pm2
True

__lt__(b)

Less-than operator for procedure_metricclass .

Parameters:b (procedure_metricclass) – The procedure_metricclass object to compare against. Return type:bool Returns:True if self < b , False otherwise.

>>> procmetrics = procedure_metricclass_manager.metricclasses()
>>> pm1 = next(procmetrics)
>>> pm1
<cs.metricclass V>
>>> pm2 = next(procmetrics)
>>> pm2
<cs.metricclass mvG>
>>> pm1 < pm2
True

__ne__(b)

Inequality operator for procedure_metricclass .

Parameters:b (procedure_metricclass) – The procedure_metricclass object to compare against. Return type:bool Returns:False if self equal to b , True otherwise.

>>> procmetrics = procedure_metricclass_manager.metricclasses()
>>> pm1 = next(procmetrics)
>>> pm1
<cs.metricclass V>
>>> pm2 = next(procmetrics)
>>> pm2
<cs.metricclass mvG>
>>> pm1 != pm2
True

__repr__()

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

Return type:str Returns:The string representation.

>>> procmetrics = procedure_metricclass_manager.metricclasses()
>>> pm1 = next(procmetrics)
>>> repr(pm1)
'<cs.metricclass V>'

__str__()

Get a simple string representation of a procedure_metricclass object.

Return type:str Returns:The string representation.

>>> procmetrics = procedure_metricclass_manager.metricclasses()
>>> pm1 = next(procmetrics)
>>> str(pm1)
'V'

allowed()

Check: are METRIC_FILTER settings such that reported instances of this metric class will be submitted to the hub?

Return type:bool Returns:True if reported instances of the class will be submitted to the hub, False otherwise.

If you have defined a custom metric class C in a plug-in, you can use a test based on C.allowed() to avoid unnecessary work in the case where C is ignored.

This is the complement of procedure_metricclass.always_discarded().

>>> v0 = procedure_metricclass_manager.metricclasses()
>>> v1 = v0.__next__()
>>> v1.allowed()
False

always_discarded()

Check: are METRIC_FILTER settings such that instances of this metric class will always be ignored?

Return type:bool Returns:True if all instances of the class are being discarded, False otherwise.

If you have defined a custom metric class C in a plug-in, you can use a test based on C.always_discarded() to avoid unnecessary work in the case where C is ignored.

This is the complement of procedure_metricclass.allowed().

>>> v0 = procedure_metricclass_manager.metricclasses()
>>> v1 = v0.__next__()
>>> v1.always_discarded()
True

description()

Get the description (longer, human readable identifier) for a metric class ( procedure_metricclass ).

Return type:str Returns:The description, as a string.

For example, CodeSonar ships with built-in project granularity metric class Include file instances.

• its tag is “InclF”
• its description is “Include file instances”

>>> procmetrics = procedure_metricclass_manager.metricclasses()
>>> pm1 = next(procmetrics)
>>> pm1
<cs.metricclass V>
>>> pm1.description()
'Halstead Program Volume'

flags()

Get the metricclass_flags for a procedure_metricclass .

Return type:metricclass_flags Returns:The metricclass_flags .

>>> procmetrics = procedure_metricclass_manager.metricclasses()
>>> pm1 = next(procmetrics)
>>> pm1
<cs.metricclass V>
>>> pm1.flags()
<cs.metricclass_flags auto>

report(elt, val)

Report a metric value to the hub.

Parameters:

• elt (procedure) – The element that the metric value is associated with.
• val (float) – The value to report.

Return type:

NoneType

Raises:

• result.ERROR_INVALID_PHASE_FOR_OPERATION if called during a traversal phase that is not consistent with the metricclass_flags for the procedure_metricclass. See the metricclass_flags.POST_ANALYSIS documentation for more information.
• result.NO_POSITION if elt has kind procedure_kind.UNDEFINED or its entry point does not have a position.
• result.FILTERED_OUT if the procedure_metricclass is filtered out by a METRIC_FILTER discard rule.
• result.ERROR_INVALID_SLAVE_OPERATION if called from a CodeSonar slave process.

You do not need to call this method if the metric class was created with a metric function decorator. In that case, CodeSonar will automatically report the values calculated using the decorated function.

>>> procmetrics = procedure_metricclass_manager.metricclasses()
>>> pm1 = next(procmetrics)
>>> pm2 = next(procmetrics)
>>> pm2
<cs.metricclass mvG>
>>> proc = next(p for p in project.current().procedures() if p.name()=='foo')
>>> pm2.report(proc,5)
>>> pm2.value(proc)
5.0

retract(elt)

Retract a metric value.

Parameters:

elt (procedure) – The element for which the value will be retracted.

Return type:

Raises:

• result.ERROR_INVALID_PHASE_FOR_OPERATION if called outside the drop traversal phase.
• result.ERROR_INVALID_SLAVE_OPERATION if called from a CodeSonar slave process.
• result.ELEMENT_NOT_PRESENT if retraction did not occur for any other reason.

In typical usage, procedure_metricclass.retract() is called during the drop traversal (that is, by a drop visitor).

tag()

Get the tag (short string identifier) for a metric class ( procedure_metricclass ).

Return type:str Returns:The short tag, as a string.

The tag will usually be only a few characters long. Retrieve the metric class description with procedure_metricclass.description() for a longer string that is generally more human-readable.

For example, CodeSonar ships with built-in project granularity metric class Include file instances.

• its tag is “InclF”
• its description is “Include file instances”

>>> procmetrics = procedure_metricclass_manager.metricclasses()
>>> pm1 = next(procmetrics)
>>> pm1
<cs.metricclass V>
>>> pm1.tag()
'V'

value(elt)

Get the value of a metric.

Parameters:

elt (procedure) – The element for which the metric value is required.

Return type:

float

Returns:

The metric value for elt.

Raises:

• result.FILTERED_OUT if the procedure_metricclass is filtered out by a METRIC_FILTER discard rule.
• result.METRIC_NOT_COMPUTED if a value for the metric has not been computed. This can happen if the procedure_metricclass was not created with metricclass_flags.AUTO and a value has not been reported with procedure_metricclass.report(), or if the procedure_metricclass was not created with metricclass_flags.POST_ANALYSIS but procedure_metricclass.value() is called during the serial depth-first traversal or parallel-depth first traversal.
• result.NO_SOURCE_CORRESPONDENCE if elt does not have kind procedure_kind.USER_DEFINED, or if its entry point does not have a position.

>>> procmetrics = procedure_metricclass_manager.metricclasses()
>>> pm1 = next(procmetrics)
>>> pm2 = next(procmetrics)
>>> pm2
<cs.metricclass mvG>
>>> proc = next(p for p in project.current().procedures() if p.name()=='foo')
>>> pm2.report(proc,5)
>>> pm2.value(proc)
5.0