Contents

• class sfile_metricclass
  • sfile_metricclass Members
  • sfile_metricclass Details

class sfile_metricclass

A sfile granularity metric class.

The sfile granularity metric classes are managed by sfile_metricclass_manager .

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

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

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

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

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

sfile_metricclass Members

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

sfile_metricclass Details

class cs.sfile_metricclass

A sfile granularity metric class.

__cmp__(other)

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

Parameters:other (sfile_metricclass) – The sfile_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 sfile_metricclass object.

>>> sfmetrics = sfile_metricclass_manager.metricclasses()
>>> sm1 = next(sfmetrics)
>>> sm1
<cs.metricclass L>
>>> sm2 = next(sfmetrics)
>>> sm2
<cs.metricclass ivG>
>>> sm1.__cmp__(sm2)
-1

__eq__(b)

Equality operator for sfile_metricclass .

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

>>> sfmetrics = sfile_metricclass_manager.metricclasses()
>>> sm1 = next(sfmetrics)
>>> sm1
<cs.metricclass L>
>>> sm2 = next(sfmetrics)
>>> sm2
<cs.metricclass ivG>
>>> sm1 == sm2
False

__ge__(b)

Greater-than-or-equal operator for sfile_metricclass .

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

>>> sfmetrics = sfile_metricclass_manager.metricclasses()
>>> sm1 = next(sfmetrics)
>>> sm1
<cs.metricclass L>
>>> sm2 = next(sfmetrics)
>>> sm2
<cs.metricclass ivG>
>>> sm1 >= sm2
False

__gt__(b)

Greater-than operator for sfile_metricclass .

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

>>> sfmetrics = sfile_metricclass_manager.metricclasses()
>>> sm1 = next(sfmetrics)
>>> sm1
<cs.metricclass L>
>>> sm2 = next(sfmetrics)
>>> sm2
<cs.metricclass ivG>
>>> sm1 > sm2
False

__hash__()

Get a hash value for this sfile_metricclass .

Return type:int

>>> sfmetrics = sfile_metricclass_manager.metricclasses()
>>> sm1 = next(sfmetrics)
>>> sm1
<cs.metricclass L>
>>> hash(sm1)
1822619904

__le__(b)

Less-than-or-equal operator for sfile_metricclass .

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

>>> sfmetrics = sfile_metricclass_manager.metricclasses()
>>> sm1 = next(sfmetrics)
>>> sm1
<cs.metricclass L>
>>> sm2 = next(sfmetrics)
>>> sm2
<cs.metricclass ivG>
>>> sm1 <= sm2
True

__lt__(b)

Less-than operator for sfile_metricclass .

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

>>> sfmetrics = sfile_metricclass_manager.metricclasses()
>>> sm1 = next(sfmetrics)
>>> sm1
<cs.metricclass L>
>>> sm2 = next(sfmetrics)
>>> sm2
<cs.metricclass ivG>
>>> sm1 < sm2
True

__ne__(b)

Inequality operator for sfile_metricclass .

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

>>> sfmetrics = sfile_metricclass_manager.metricclasses()
>>> sm1 = next(sfmetrics)
>>> sm1
<cs.metricclass L>
>>> sm2 = next(sfmetrics)
>>> sm2
<cs.metricclass ivG>
>>> sm1 != sm2
True

__repr__()

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

Return type:str Returns:The string representation.

>>> sfmetrics = sfile_metricclass_manager.metricclasses()
>>> sm1 = next(sfmetrics)
>>> repr(sm1)
'<cs.metricclass L>'

__str__()

Get a simple string representation of a sfile_metricclass object.

Return type:str Returns:The string representation.

>>> sfmetrics = sfile_metricclass_manager.metricclasses()
>>> sm1 = next(sfmetrics)
>>> str(sm1)
'L'

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 sfile_metricclass.always_discarded().

>>> v0 = sfile_metricclass_manager.metricclasses()
>>> v1 = v0.__next__()
>>> v1.allowed()
True

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 sfile_metricclass.allowed().

>>> v0 = sfile_metricclass_manager.metricclasses()
>>> v1 = v0.__next__()
>>> v1.always_discarded()
False

description()

Get the description (longer, human readable identifier) for a metric class ( sfile_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”

>>> sfmetrics = sfile_metricclass_manager.metricclasses()
>>> sm1 = next(sfmetrics)
>>> sm1
<cs.metricclass L>
>>> sm2.description()
'Module Design Complexity'

flags()

Get the metricclass_flags for a sfile_metricclass .

Return type:metricclass_flags Returns:The metricclass_flags .

>>> sfmetrics = sfile_metricclass_manager.metricclasses()
>>> sm1 = next(sfmetrics)
>>> sm1
<cs.metricclass L>
>>> sm1.flags()
<cs.metricclass_flags auto>

report(elt, val)

Report a metric value to the hub.

Parameters:

• elt (sfile) – 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 sfile_metricclass. See the metricclass_flags.POST_ANALYSIS documentation for more information.
• result.FILTERED_OUT if the sfile_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.

>>> v0 = project.current()
>>> v1 = v0.sfiles()
>>> v2 = v1.next()
>>> v3 = sfile_metricclass_manager.lookup('x64')
>>> v3.report(v2, 23.665758179749748)

retract(elt)

Retract a metric value.

Parameters:

elt (sfile) – 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, sfile_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 ( sfile_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 sfile_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”

>>> print(', '.join([smc.tag() for smc in sfile_metricclass_manager.metricclasses()]))
L, ivG, TaintSource, E, n1, I, T, TaintSink, LCodeOnly, N1, LMCC, LB, V, LCom, n2, D, vG, N, LComOnly, N2, TaintProp, TL, evG, mvG, LCode

value(elt)

Get the value of a metric.

Parameters:

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

Return type:

float

Returns:

The metric value for elt.

Raises:

• result.FILTERED_OUT if the sfile_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 sfile_metricclass was not created with metricclass_flags.AUTO and a value has not been reported with sfile_metricclass.report(), or if the sfile_metricclass was not created with metricclass_flags.POST_ANALYSIS but sfile_metricclass.value() is called during the serial depth-first traversal or parallel-depth first traversal.

>>> apitest_cpp_sf = next(sf for sf in project.current().sfiles()
...                       if sf.normalized_name().endswith('apitest.cpp'))
>>> for smc in sfile_metricclass_manager.metricclasses():
...    try:
...       smcval = smc.value(apitest_cpp_sf)
...    except result as r:
...       smcval=None
...    if smcval is not None:
...       print(smc.tag(), smcval)
...
LCodeOnly 44.0
LMCC 0.0
LB 2.0
LCom 1.0
vG 7.0
LComOnly 1.0
TL 47.0
mvG 5.0
LCode 44.0