Directive (programming)

Last updated January 13, 2024

In computer programming, a directive or pragma (from "pragmatic") is a language construct that specifies how a compiler (or other translator) should process its input. Depending on the programming language, directives may or may not be part of the grammar of the language, and may vary from compiler to compiler. They can be processed by a preprocessor to specify compiler behavior, or function as a form of in-band parameterization.

In some cases directives specify global behavior, while in other cases they only affect a local section, such as a block of programming code. In some cases, such as some C programs, directives are optional compiler hints, and may be ignored, but normally they are prescriptive, and must be followed. However, a directive does not perform any action in the language itself, but rather only a change in the behavior of the compiler.

This term could be used to refer to proprietary third party tags and commands (or markup) embedded in code that result in additional executable processing that extend the existing compiler, assembler and language constructs present in the development environment. The term "directive" is also applied in a variety of ways that are similar to the term command.

The C preprocessor

In C and C++, the language supports a simple macro preprocessor. Source lines that should be handled by the preprocessor, such as #define and #include are referred to as preprocessor directives.

Another C construct, the #pragma directive, is used to instruct the compiler to use pragmatic or implementation-dependent features. Two notable users of this directive are OpenMP and OpenACC.

Syntactic constructs similar to C's preprocessor directives, such as C#'s #if, are also typically called "directives", although in these cases there may not be any real preprocessing phase involved.

All preprocessor commands begin with a hash symbol (#) with the exception of the import and module directives in C++.^[1]

History

Directives date to JOVIAL.^[2]

COBOL Had a COPY directive.

In ALGOL 68, directives are known as pragmats (from "pragmatic"), and denoted pragmat or pr; in newer languages, notably C, this has been abbreviated to "pragma" (no 't').

A common use of pragmats in ALGOL 68 is in specifying a stropping regime, meaning "how keywords are indicated". Various such directives follow, specifying the POINT, UPPER, RES (reserved), or quote regimes. Note the use of stropping for the pragmat keyword itself (abbreviated pr), either in the POINT or quote regimes:

.PR POINT .PR .PR UPPER .PR .PR RES .PR 'pr' quote 'pr'

Today directives are best known in the C language, of early 1970s vintage, and continued through the current C99 standard, where they are either instructions to the C preprocessor, or, in the form of #pragma, directives to the compiler itself. They are also used to some degree in more modern languages; see below.

Other languages

In Ada, compiler directives are called pragmas (short for "pragmatic information").
In Common Lisp, directives are called declarations, and are specified using the declare construct (also proclaim or declaim).^[3] With one exception, declarations are optional, and do not affect the semantics of the program. The one exception is special, which must be specified where appropriate.
In Turbo Pascal, directives are called significant comments, because in the language grammar they follow the same syntax as comments. In Turbo Pascal, a significant comment is a comment whose first character is a dollar sign and whose second character is a letter; for example, the equivalent of C's #include "file" directive is the significant comment {$I "file"}.
In Perl, the keyword " use ", which imports modules, can also be used to specify directives, such as use strict; or use utf8;.
Haskell pragmas are specified using a specialized comment syntax, e.g. {-# INLINE foo #-}.^[4]
PHP uses the directive declare(strict_types=1).
Python has two directives – from __future__ import feature (defined in PEP 236 -- Back to the __future__), which changes language features (and uses the existing module import syntax, as in Perl), and the coding directive (in a comment) to specify the encoding of a source code file (defined in PEP 263 -- Defining Python Source Code Encodings). A more general directive statement was proposed and rejected in PEP 244 -- The `directive' statement; these all date to 2001.
ECMAScript also adopts the use syntax for directives, with the difference that pragmas are declared as string literals (e.g. "use strict";, or "use asm";), rather than a function call.
In Visual Basic, the keyword "Option" is used for directives:
- Option Explicit On|Off - When on disallows implicit declaration of variables at first use requiring explicit declaration beforehand.
- Option Compare Binary - Results in string comparisons based on a sort order derived from the internal binary representations of the characters - e.g. for the English/European code page (ANSI 1252) A < B < E < Z < a < b < e < z < À < Ê < Ø < à < ê < ø. Affects intrinsic operators (e.g. =, <>, <, >), the Select Case block, and VB runtime library string functions (e.g. InStr).
- Option Compare Text - Results in string comparisons based on a case-insensitive text sort order determined by your system's locale - e.g. for the English/European code page (ANSI 1252) (A=a) < (À = à) < (B=b) < (E=e) < (Ê = ê) < (Z=z) < (Ø = ø). Affects intrinsic operators (e.g. =, <>, <, >), the Select Case block, and VB runtime library string functions (e.g. InStr).
- Option Strict On|Off - When on disallows:
  - typeless programming - where declarations which lack an explicit type are implicitly typed as Object.
  - late-binding (i.e. dynamic dispatch to CLR, DLR, and COM objects) on values statically typed as Object.
  - implicit narrowing conversions - requiring all conversions to narrower types (e.g. from Long to Integer, Object to String, Control to TextBox) be explicit in code using conversion operators (e.g. CInt, DirectCast, CType).
- Option Infer On|Off - When on enables the compiler to infer the type of local variables from their initializers.
In Ruby, interpreter directives are referred to as pragmas and are specified by top-of-file comments that follow a key: value notation. For example, coding: UTF-8 indicates that the file is encoded via the UTF-8 character encoding.
In C#, compiler directives are called pre-processing directives. There are a number of different compiler directives including #pragma, which is specifically used to control compiler warnings and debugger checksums.^[5]^[6]
The SQLite DBMS includes a PRAGMA directive that is used to introduce commands that are not compatible with other DBMS.^[7]
In Solidity, compiler directives are called pragmas.

Assembly language

In assembly language, directives, also referred to as pseudo-operations or "pseudo-ops", generally specify such information as the target machine, mark separations between code sections, define and change assembly-time variables, define macros, designate conditional and repeated code, define reserved memory areas, and so on. Some, but not all, assemblers use a specific syntax to differentiate pseudo-ops from instruction mnemonics, such as prefacing the pseudo-op with a period, such as the pseudo-op .END, which might direct the assembler to stop assembling code.

PL/SQL

Oracle Corporation's PL/SQL procedural language includes a set of compiler directives, known as "pragmas".^[8]

Footnotes

↑ "P1857R1 - Modules Dependency Discovery".
↑ "Chapter 17 - Directives" (PDF). Computer Programming Manual for JOVIAL (J73) Language (PDF) (Technical report). June 1981. pp. 243–263. RADC-TR-81-143. Retrieved May 28, 2023.
↑ Steele 1990, Chapter 9: Declarations, p. 215–237.
↑ "7.20. Pragmas". GHC 7.8.3 Documentation. Retrieved 18 July 2014.
↑ dotnet-bot. "Lexical structure - C# language specification". docs.microsoft.com. Retrieved 2019-11-01.
↑ BillWagner. "#pragma - C# Reference". docs.microsoft.com. Retrieved 2019-11-01.
↑ "Pragma statements supported by SQLite". www.sqlite.org.
↑ Feuerstein, Steven; Pribyl, Bill (23 January 2014). Oracle PL/SQL Programming (6 ed.). O'Reilly Media, Inc. (published 2014). ISBN 9781449324414 . Retrieved 2016-06-16. PL/SQL has a PRAGMA keyword with the following syntax: PRAGMA instruction_to_compiler; [...] PL/SQL offers several pragmas [...]

Related Research Articles

C is a general-purpose computer programming language. It was created in the 1970s by Dennis Ritchie, and remains very widely used and influential. By design, C's features cleanly reflect the capabilities of the targeted CPUs. It has found lasting use in operating systems, device drivers, and protocol stacks, but its use in application software has been decreasing. C is commonly used on computer architectures that range from the largest supercomputers to the smallest microcontrollers and embedded systems.

ScriptBasic is a scripting language variant of BASIC. The source of the interpreter is available as a C program under the LGPL license.

In computer science, a preprocessor is a program that processes its input data to produce output that is used as input in another program. The output is said to be a preprocessed form of the input data, which is often used by some subsequent programs like compilers. The amount and kind of processing done depends on the nature of the preprocessor; some preprocessors are only capable of performing relatively simple textual substitutions and macro expansions, while others have the power of full-fledged programming languages.

A string literal or anonymous string is a literal for a string value in the source code of a computer program. Modern programming languages commonly use a quoted sequence of characters, formally "bracketed delimiters", as in x = "foo", where "foo" is a string literal with value foo. Methods such as escape sequences can be used to avoid the problem of delimiter collision and allow the delimiters to be embedded in a string. There are many alternate notations for specifying string literals especially in complicated cases. The exact notation depends on the programming language in question. Nevertheless, there are general guidelines that most modern programming languages follow.

The C preprocessor is the macro preprocessor for several computer programming languages, such as C, Objective-C, C++, and a variety of Fortran languages. The preprocessor provides inclusion of header files, macro expansions, conditional compilation, and line control.

In the C and C++ programming languages, an inline function is one qualified with the keyword inline; this serves two purposes:

It serves as a compiler directive that suggests that the compiler substitute the body of the function inline by performing inline expansion, i.e. by inserting the function code at the address of each function call, thereby saving the overhead of a function call. In this respect it is analogous to the register storage class specifier, which similarly provides an optimization hint.
The second purpose of inline is to change linkage behavior; the details of this are complicated. This is necessary due to the C/C++ separate compilation + linkage model, specifically because the definition (body) of the function must be duplicated in all translation units where it is used, to allow inlining during compiling, which, if the function has external linkage, causes a collision during linking. C and C++ resolve this in different ways.

The syntax of the C programming language is the set of rules governing writing of software in C. It is designed to allow for programs that are extremely terse, have a close relationship with the resulting object code, and yet provide relatively high-level data abstraction. C was the first widely successful high-level language for portable operating-system development.

In the C and C++ programming languages, an #include guard, sometimes called a macro guard, header guard or file guard, is a particular construct used to avoid the problem of double inclusion when dealing with the include directive.

In computer programming, a precompiled header (PCH) is a header file that is compiled into an intermediate form that is faster to process for the compiler. Usage of precompiled headers may significantly reduce compilation time, especially when applied to large header files, header files that include many other header files, or header files that are included in many translation units.

In computer language design, stropping is a method of explicitly marking letter sequences as having a special property, such as being a keyword, or a certain type of variable or storage location, and thus inhabiting a different namespace from ordinary names ("identifiers"), in order to avoid clashes. Stropping is not used in most modern languages – instead, keywords are reserved words and cannot be used as identifiers. Stropping allows the same letter sequence to be used both as a keyword and as an identifier, and simplifies parsing in that case – for example allowing a variable named if without clashing with the keyword if.

C++11 is a version of the ISO/IEC 14882 standard for the C++ programming language. C++11 replaced the prior version of the C++ standard, called C++03, and was later replaced by C++14. The name follows the tradition of naming language versions by the publication year of the specification, though it was formerly named C++0x because it was expected to be published before 2010.

In computer programming, boilerplate code, or simply boilerplate, are sections of code that are repeated in multiple places with little to no variation. When using languages that are considered verbose, the programmer must write a lot of boilerplate code to accomplish only minor functionality.

This comparison of programming languages compares the features of language syntax (format) for over 50 computer programming languages.

<span class="mw-page-title-main">Comment (computer programming)</span> Explanatory note in the source code of a computer program

In computer programming, a comment is a programmer-readable explanation or annotation in the source code of a computer program. They are added with the purpose of making the source code easier for humans to understand, and are generally ignored by compilers and interpreters. The syntax of comments in various programming languages varies considerably.

This article describes the syntax of the C# programming language. The features described are compatible with .NET Framework and Mono.

Many programming languages and other computer files have a directive, often called include, import, or copy, that causes the contents of the specified file to be inserted into the original file. These included files are called header files or copybooks. They are often used to define the physical layout of program data, pieces of procedural code, and/or forward declarations while promoting encapsulation and the reuse of code or data.

OpenHMPP - programming standard for heterogeneous computing. Based on a set of compiler directives, standard is a programming model designed to handle hardware accelerators without the complexity associated with GPU programming. This approach based on directives has been implemented because they enable a loose relationship between an application code and the use of a hardware accelerator (HWA).

PL/SQL is Oracle Corporation's procedural extension for SQL and the Oracle relational database. PL/SQL is available in Oracle Database, Times Ten in-memory database, and IBM Db2. Oracle Corporation usually extends PL/SQL functionality with each successive release of the Oracle Database.

C++/CX(C++ component extensions) is a language projection for Microsoft's Windows Runtime platform. It takes the form of a language extension for C++ compilers, and it enables C++ programmers to write programs that call Windows Runtime (WinRT) APIs. C++/CX is superseded by the C++/WinRT language projection, which is not an extension to the C++ language; rather, it's an entirely standard modern ISO C++17 header-file-based library.

Nim is a general-purpose, multi-paradigm, statically typed, compiled high-level systems programming language, designed and developed by a team around Andreas Rumpf. Nim is designed to be "efficient, expressive, and elegant", supporting metaprogramming, functional, message passing, procedural, and object-oriented programming styles by providing several features such as compile time code generation, algebraic data types, a foreign function interface (FFI) with C, C++, Objective-C, and JavaScript, and supporting compiling to those same languages as intermediate representations.

References

Steele, Guy L. (1990). Common Lisp the Language . Digital Press. pp. 215–237. ISBN 1-55558-041-6.

External links

This page is based on this Wikipedia article
Text is available under the CC BY-SA 4.0 license; additional terms may apply.
Images, videos and audio are available under their respective licenses.

[1] "P1857R1 - Modules Dependency Discovery".

[2] "Chapter 17 - Directives" (PDF). Computer Programming Manual for JOVIAL (J73) Language (PDF) (Technical report). June 1981. pp. 243–263. RADC-TR-81-143. Retrieved May 28, 2023.

[FOOTNOTESteele1990[httpswwwcscmueduGroupsAIhtmlcltlclmnode103html_Chapter_9:_Declarations],_p._215–237-3] Steele 1990, Chapter 9: Declarations, p. 215–237.

[4] "7.20. Pragmas". GHC 7.8.3 Documentation. Retrieved 18 July 2014.

[5] tnet-bot. "Lexical structure - C# language specification". docs.microsoft.com. Retrieved 2019-11-01.

[6] BillWagner. "#pragma - C# Reference". docs.microsoft.com. Retrieved 2019-11-01.

[7] "Pragma statements supported by SQLite". www.sqlite.org.

[8] Feuerstein, Steven; Pribyl, Bill (23 January 2014). Oracle PL/SQL Programming (6 ed.). O'Reilly Media, Inc. (published 2014). ISBN 9781449324414 . Retrieved 2016-06-16. PL/SQL has a PRAGMA keyword with the following syntax: PRAGMA instruction_to_compiler; [...] PL/SQL offers several pragmas [...]

[1]

[2]

[3]

[4]

[5]

[6]

[7]

[8]