MISS_HIT 0.9.21 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 }

Pragma

Currently only a single annotation exists: justification pragmas. These 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");