16.9: Pragmas

Last updated
Save as PDF

Page ID: 43480

\( \newcommand{\vecs}[1]{\overset { \scriptstyle \rightharpoonup} {\mathbf{#1}} } \) \( \newcommand{\vecd}[1]{\overset{-\!-\!\rightharpoonup}{\vphantom{a}\smash {#1}}} \)\(\newcommand{\id}{\mathrm{id}}\) \( \newcommand{\Span}{\mathrm{span}}\) \( \newcommand{\kernel}{\mathrm{null}\,}\) \( \newcommand{\range}{\mathrm{range}\,}\) \( \newcommand{\RealPart}{\mathrm{Re}}\) \( \newcommand{\ImaginaryPart}{\mathrm{Im}}\) \( \newcommand{\Argument}{\mathrm{Arg}}\) \( \newcommand{\norm}[1]{\| #1 \|}\) \( \newcommand{\inner}[2]{\langle #1, #2 \rangle}\) \( \newcommand{\Span}{\mathrm{span}}\) \(\newcommand{\id}{\mathrm{id}}\) \( \newcommand{\Span}{\mathrm{span}}\) \( \newcommand{\kernel}{\mathrm{null}\,}\) \( \newcommand{\range}{\mathrm{range}\,}\) \( \newcommand{\RealPart}{\mathrm{Re}}\) \( \newcommand{\ImaginaryPart}{\mathrm{Im}}\) \( \newcommand{\Argument}{\mathrm{Arg}}\) \( \newcommand{\norm}[1]{\| #1 \|}\) \( \newcommand{\inner}[2]{\langle #1, #2 \rangle}\) \( \newcommand{\Span}{\mathrm{span}}\)\(\newcommand{\AA}{\unicode[.8,0]{x212B}}\)

A pragma is an annotation that specifies data about a program, but is not involved in the execution of the program. Pragmas have no direct effect on the operation of the method they annotate. Pragmas have a number of uses, among them:

Information for the compiler: pragmas can be used by the compiler to make a method call a primitive function. This function has to be defined by the virtual machine or by an external plug-in.

Runtime processing: Some pragmas are available to be examined at runtime.

Pragmas can be applied to a program’s method declarations only. A method may declare one or more pragmas, and the pragmas have to be declared prior any Smalltalk statement. Each pragma is in effect a static message send with literal arguments.

We briefly saw pragmas when we introduced primitives earlier in this chapter. A primitive is nothing more than a pragma declaration. Consider <primitive: 173 error:ec> as contained in instVarAt:. The pragma’s selector is primitive:error: and its arguments is an immediate literal value, 173. The variable ec is an error code, filled by the VM in case the execution of the implementation on the VM side failed.

The compiler is probably the bigger user of pragmas. SUnit is another tool that makes use of annotations. SUnit is able to estimate the coverage of an application from a test unit. One may want to exclude some methods from the coverage. This is the case of the documentation method in SplitJointTest class:

SplitJointTest class >> documentation
    <ignoreForCoverage>
    "self showDocumentation"
    
    ^ 'This package provides function.... "

By simply annotating a method with the pragma <ignoreForCoverage> one can control the scope of the coverage.

As instances of the class Pragma, pragmas are first class objects. A compiled method answers to the message pragmas. This method returns an array of pragmas.

(SplitJoinTest class >> #showDocumentation) pragmas.
>>> an Array(<ignoreForCoverage>)
(Float>>#+) pragmas
>>> an Array(<primitive: 41>)

Methods defining a particular query may be retrieved from a class. The class side of SplitJoinTest contains some methods annotated with <ignoreForCoverage>:

Pragma allNamed: #ignoreForCoverage in: SplitJoinTest class
>>> an Array(<ignoreForCoverage> <ignoreForCoverage>
    <ignoreForCoverage>)

A variant of allNamed:in: may be found on the class side of Pragma.

A pragma knows in which method it is defined (using method), the name of the method (selector), the class that contains the method (methodClass), its number of arguments (numArgs), about the literals the pragma has for arguments (hasLiteral: and hasLiteralSuchThat:).