MISS_HIT 0.9.30-dev Pragmas
The behaviour of the MISS_HIT tools can be controlled with pragmas (special comments that can be placed in the source code). This document describes the syntax and semantics of the pragmas.
Picture of text

One-line trivial pragmas

Style justification

You can justify style issues by placing a style justification pragma on the same line the message occurs.
% mh:ignore_style
Picture of text

MISS_HIT Annotation language

Introducing annotations

MISS_IT supports a special annotation language embedded inside specially formatted MATLAB or Octave comments. An annotation is introduce using a comment and the bar (this could easily be made configurable, if there is demand):
%| some_annotation
Annotations span until the end of the line. Annotations can be multi-line as long as there is no other program text between:
%| pragma Justify (metric, "npath",
%|                 "multi-line example");
Annotation must be the first and only program text on a line. For example the following program does not contain an annotation:
x + 1; %| this is not an annotation
Annotations have most of the lexical features of MATLAB, except that line continuations and command form do not exist. You can even have comments (but not annotations) in your annotation:
%| some_annotation; % comment

Expressions

Currently, only static string expressions or direct names are supported.
a_name ::= IDENTIFIER

a_expression ::= a_name
               | STRING { '+' STRING }

Annotation Pragmas

MISS_HIT annotation pragmas can appear in any place where normal program statement can occur.
A miss-hit pragma has the following grammar:
annotation_pragma ::= 'pragma' a_name '(' a_pragma_parameters ')' ';'
                    | 'pragma' a_name ';'

a_pragma_parameters ::= a_expression { ',' a_expression }

Justification pragmas

A justification pragma has the following signature:
pragma Justify (TOOL, PARAMETER, REASON);
Tool identifies the miss_hit tool and can be one of:
  • style
  • metric
The parameter is a tool-dependent identifier. Reason is a plain-text human explanation for why this justification is reasonable.

Metric justification pragmas

A metric justification pragma has the following signature:
pragma Justify (metric, METRIC_NAME, REASON);
The metric name must be a string to match one of the documented metric names. For example:
%| pragma Justify (metric, "npath",
%|                 "code impossible to restructure");

Tag pragmas

A Tag pragma can be used to tag code (TestTags class/block parameters already exist to tag unit tests; although you could also use pragma Tag for this purpose). It has the following signature:
pragma Tag (STRING [, STRING]+);
For example:
pragma Tag ("PotatoFeature");
Pragma tag applies to all items scoped logically under the entity that is tagged. For example placing the Tag pragma in a class definition will affect all methods; placing it in a function will also affect all nested functions; and placing it in a compilation unit will affect all functions or methods in that compilation unit.

No_Tracing pragmas

A No_Tracing pragma can be used to indicate that some code or test should not be included in the output of mh_trace. It has the following signature:
pragma No_Tracing;
Pragma No_Tracing has the same scoping rules as pragma Tag.