Include directive

Last updated

An include directive instructs a text file processor to replace the directive text with the content of a specified file.

Contents

The act of including may be logical in nature. The processor may simply process the include file content at the location of the directive without creating a combined file.

Different processors may use different syntax. The C preprocessor (used with C, C++ and in other contexts) defines an include directive as a line that starts #include and is followed by a file specification. COBOL defines an include directive indicated by copy in order to include a copybook.

Generally, for C/C++ the include directive is used to include a header file, but can include any file. Although relatively uncommon, it is sometimes used to include a body file such as a .c file.

The include directive can support encapsulation and reuse. Different parts of a system can be segregated into logical groupings yet rely on one another via file inclusion. C and C++ are designed to leverage include while also optimizing build time by allowing declaration separate from implementation. The included information can be minimized to only declarations.

As many consider that including file content has significant drawbacks, newer languages have been designed without an include directive. Languages such as Java and C# support modularization via an import concept that allows a module to use the assets of another module at a conceptual level; not by including text.

Language support

C/C++

Both C and C++ are typically used with the C preprocessor that replaces a #include directive line with the content of the file specified. A file path is either enclosed in double quotes (i.e. "xyz.h") or angle brackets (i.e. <xyz.h>). [1] Some preprocessors locate the include file differently based on the enclosing delimiters; treating a path in double-quotes as relative to the including file and a path in angle brackets as located in one of the directories of the configured system search path. [2]

Example include statements:

// include the C standard header 'stdio.h'; probably is a file with that name#include<stdio.h>// include the C++ standard header 'vector'; may or may not be a file#include<vector>// include a custom header file named 'user_defined.h'#include"user_defined.h"

The include directive allows for the development of code libraries that:

Example

Given two C source files. One defines a function add() and another uses the function. Without using an include directive, the consuming file can declare the function locally as a function prototype:

intadd(int,int);inttriple(intx){returnadd(x,add(x,x));}

One drawback of this approach is that the function prototype must be present in each file that calls add(). Another drawback is that if the signature changes, then each consuming file needs to be updated. Putting the prototype in a single, separate file avoids these issues. If the prototype is moved to a header file add.h, the using source file becomes:

#include"add.h"inttriple(intx){returnadd(x,add(x,x));}

Header file

In C and C++, a header file is a source code file that allows programmers to separate elements of a codebase – often into reusable, logically-related groupings.

A header file declares programming elements such as functions, classes, variables, and preprocessor macros. A header file allows the programmer to use programming elements in multiple body files based on the common declaration in the header file. Declarations in a header file allow body files to use implementations without including the implementation code directly. The header keeps the interface separate from the implementation. [3]

Compilation errors may occur if multiple header files include the same file. One solution is to avoid including files in header files – possibly requiring excessive include directives in body files. Another solution is to use an include guard in each header file. [4]

The C standard library is declared as a collection of header files. The C++ standard library is similar, but the declarations may be provided by the compiler without reading an actual file.

C standard header files are named with a .h file name extension, as in #include <stdio.h>. Typically, custom C header files have the same extension. Custom C++ header files tend to have more variety of extensions, including .hpp, .h++ and .hh.

A C++ standard library name in angle brackets (i.e. <vector>) results in declarations being included but may not be from a file. [5]

Header unit

Since C++20, C++ supports import semantics via the header unit, that is, separate translation units synthesized from a header. [6] They are meant to be used alongside modules. The syntax used in that case is:

exportoptional import header-name;

Example:

import<stdio.h>;// supporting this is optionalimport<vector>;// supporting this is mandated by the standardexportimport"user_defined.h";

Header units are provided for all the C++ standard library headers. [7]

COBOL

COBOL (and also RPG IV) allows programmers to copy copybooks into the source of the program – which is similar to including but allows for replacing text. The COBOL keyword for inclusion is COPY, and replacement is done using the REPLACING ... BY ... clause. An include directive has been present in COBOL since COBOL 60, but changed from the original INCLUDE [8] to COPY by 1968. [9]

Fortran

Fortran does not require header files per se. However, Fortran 90 and later have two related features: include statements and modules. The former can be used to share a common file containing procedure interfaces, much like a C header, although the specification of an interface is not required for all varieties of Fortran procedures. This approach is not commonly used; instead, procedures are generally grouped into modules that can then be referenced with a use statement within other regions of code. For modules, header-type interface information is automatically generated by the compiler and typically put into separate module files, although some compilers have placed this information directly into object files. The language specification itself does not mandate the creation of any extra files, even though module procedure interfaces are almost universally propagated in this manner.

Pascal

Most Pascal compilers support the $i or $include compiler directive, in which the $i or $include directive immediately follows the start of a comment block in the form of

Where the $i or $include directive is not case sensitive, and filename.pas or filename.inc is the name of the file to be included. (It has been common practice to name Pascal's include files with the extension .inc, but this is not required.) Some compilers, to prevent unlimited recursion, limit invoking an include file to a certain number, prohibit invoking itself or any currently open file, or are limited to a maximum of one include file at a time, e.g. an include file cannot include itself or another file. However, the program that includes other files can include several, just one at a time.

PHP

In PHP, the include directive causes another PHP file to be included and evaluated. [10] Similar commands are require, which upon failure to include will produce a fatal exception and halt the script, [11] and include_once and require_once, which prevent a file from being included or required again if it has already been included or required, avoiding the C's double inclusion problem.

Other languages

Other notable languages with an include directive:

Modern languages (e.g. Haskell and Java) tend to avoid the include directive construct, preferring modules and import/export semantics. Some of these languages (such as Java and C#) do not use forward declarations and, instead, identifiers are recognized automatically from source files and read directly from dynamic library symbols (typically referenced with import or using directives).

See also

Related Research Articles

C is a general-purpose 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 code, 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.

<span class="mw-page-title-main">Transclusion</span> Including one data set inside another automatically

In computer science, transclusion is the inclusion of part or all of an electronic document into one or more other documents by reference via hypertext. Transclusion is usually performed when the referencing document is displayed, and is normally automatic and transparent to the end user. The result of transclusion is a single integrated document made of parts assembled dynamically from separate sources, possibly stored on different computers in disparate places.

In computing, a namespace is a set of signs (names) that are used to identify and refer to objects of various kinds. A namespace ensures that all of a given set of objects have unique names so that they can be easily identified.

In computer science, imperative programming is a programming paradigm of software that uses statements that change a program's state. In much the same way that the imperative mood in natural languages expresses commands, an imperative program consists of commands for the computer to perform. Imperative programming focuses on describing how a program operates step by step, rather than on high-level descriptions of its expected results.

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.

The C programming language provides many standard library functions for file input and output. These functions make up the bulk of the C standard library header <stdio.h>. The functionality descends from a "portable I/O package" written by Mike Lesk at Bell Labs in the early 1970s, and officially became part of the Unix operating system in Version 7.

In computer programming, a global variable is a variable with global scope, meaning that it is visible throughout the program, unless shadowed. The set of all global variables is known as the global environment or global state. In compiled languages, global variables are generally static variables, whose extent (lifetime) is the entire runtime of the program, though in interpreted languages, global variables are generally dynamically allocated when declared, since they are not known ahead of time.

The C standard library or libc is the standard library for the C programming language, as specified in the ISO C standard. Starting from the original ANSI C standard, it was developed at the same time as the C library POSIX specification, which is a superset of it. Since ANSI C was adopted by the International Organization for Standardization, the C standard library is also called the ISO C library.

In compiler construction, name mangling is a technique used to solve various problems caused by the need to resolve unique names for programming entities in many modern programming languages.

In computer programming, a directive or pragma is a language construct that specifies how a compiler 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 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 the C and C++ programming languages, #pragma once is a non-standard but widely supported preprocessor directive designed to cause the current header file to be included only once in a single compilation. Thus, #pragma once serves the same purpose as include guards, but with several advantages, including less code, avoidance of name clashes, and sometimes improvement in compilation speed. While #pragma once is available in most modern compilers, its implementation is tricky and might not always be reliable.

A foreign function interface (FFI) is a mechanism by which a program written in one programming language can call routines or make use of services written or compiled in another one. An FFI is often used in contexts where calls are made into a binary dynamic-link library.

sizeof is a unary operator in the programming languages C and C++. It generates the storage size of an expression or a data type, measured in the number of char-sized units. Consequently, the construct sizeof (char) is guaranteed to be 1. The actual number of bits of type char is specified by the preprocessor macro CHAR_BIT, defined in the standard include file limits.h. On most modern computing platforms this is eight bits. The result of sizeof has an unsigned integer type that is usually denoted by size_t.

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

This article compares a large number of programming languages by tabulating their data types, their expression, statement, and declaration syntax, and some common operating-system interfaces.

In C and C++ programming language terminology, a translation unit is the ultimate input to a C or C++ compiler from which an object file is generated. A translation unit roughly consists of a source file after it has been processed by the C preprocessor, meaning that header files listed in #include directives are literally included, sections of code within #ifndef may be included, and macros have been expanded.

In software engineering, the module pattern is a design pattern used to implement the concept of software modules, defined by modular programming, in a programming language with incomplete direct support for the concept.

Although C++ is one of the most widespread programming languages, many prominent software engineers criticize C++ arguing that it is overly complex and fundamentally flawed. Among the critics have been: Robert Pike, Joshua Bloch, Linus Torvalds, Donald Knuth, Richard Stallman, and Ken Thompson. C++ has been widely adopted and implemented as a systems language through most of its existence. It has been used to build many pieces of very important software.

References

  1. ↑ C11 standard, 6.10.2 Source file inclusion, pp. 164–165
  2. ↑ Stallman, Richard M. (July 1992). "The C Preprocessor" (PDF). Archived from the original (PDF) on 4 September 2012. Retrieved 19 February 2014.
  3. ↑ Alan Griffiths (2005). "Separating Interface and Implementation in C++". ACCU. Retrieved 2013-05-07.
  4. ↑ Pike, Rob (21 Feb 1989), Notes on programming in C, Cat-v document archive, retrieved 9 Dec 2011
  5. ↑ C11 standard, 7.1.2 Standard headers, p. 181, footnote 182: "A header is not necessarily a source file, nor are the < and > delimited sequences in header names necessarily valid source file names.
  6. ↑ "Merging Modules - P1103R3" (PDF).
  7. ↑ "P1502R1 - Standard library header units for C++20".
  8. ↑ "COBOL Initial Specifications for a COmmon Business Oriented Language" (PDF). Department of Defense. April 1960. p. IX-9. Archived from the original (PDF) on 12 February 2014. Retrieved 11 February 2014.
  9. ↑ "The COPY Statement". CODASYL COBOL Journal of Development 1968. July 1969. LCCN   73601243.
  10. ↑ "include". php.net. The PHP Group. Retrieved 20 February 2014.
  11. ↑ "require". php.net. The PHP Group. Retrieved 20 February 2014.
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.