remove extensions that don't exist
[haskell-report.git] / report / pragmas.verb
1 %
2 % $Header: /home/cvs/root/haskell-report/report/pragmas.verb,v 1.6 2002/12/10 11:51:11 simonpj Exp $
3 %
4 %**<title>The Haskell 98 Report: Compiler Pragmas</title>
5 %**~header
6 \section{Compiler Pragmas}
7 \label{pragmas}
8 \index{pragmas}
9
10 Some compiler implementations support compiler {\em pragmas}, which
11 are used to give additional instructions or hints to the compiler, but
12 which do not form part of the \Haskell{} language proper and do not
13 change a program's semantics.  This chapter summarizes this existing
14 practice.  An implementation is not required to respect any pragma,
15 although pragmas that are not recognised by the implementation should
16 be ignored.  \hprime{Implementations are strongly encouraged to support the
17 LANGUAGE pragma described below as there are many language extensions
18 being used in practice.}
19
20 Lexically, pragmas appear as comments, except that the enclosing
21 syntax is @{-#@ @#-}@.
22
23 \subsection{Inlining}
24 \index{inlining}
25 @@@
26 decl -> @{-#@ @INLINE@ qvars @#-}@
27 decl -> @{-#@ @NOINLINE@ qvars @#-}@
28 @@@
29 % The optional digit represents the level of optimization at which the
30 % inlining is to occur.  If omitted, it is assumed to be 0.  A compiler
31 % may use a numeric optimization level setting in which increasing level
32 % numbers indicate increasing amounts of optimization.  Trivial
33 % inlinings that have no 
34 % impact on compilation time or code size should have an optimization
35 % level of 0; more complex inlinings that may lead to slow compilation
36 % or large executables should be associated with higher optimization levels.
37
38 The @INLINE@ pragma instructs the compiler to inline the specified variables
39 at their use sites.
40 Compilers will often automatically inline simple expressions.  This
41 may be prevented by the @NOINLINE@ pragma.
42
43 \subsection{Specialization}
44 @@@
45 decl -> @{-#@ @SPECIALIZE@ spec_1 @,@ ... @,@ spec_k @#-}@ & (k>=1)
46 spec -> vars :: type
47 @@@
48 Specialization is used to avoid inefficiencies involved in dispatching
49 overloaded functions.  For example, in
50 \bprog
51 @
52 factorial :: Num a => a -> a
53 factorial 0 = 0
54 factorial n = n * factorial (n-1)
55 {-# SPECIALIZE factorial :: Int -> Int,
56                factorial :: Integer -> Integer #-}
57 @
58 \eprog
59 calls to @factorial@ in which the compiler can detect that the
60 parameter is either @Int@ or @Integer@ will
61 use specialized versions of @factorial@ which do not involve
62 overloaded numeric operations.
63
64 \subsection{Language extensions}
65
66 \begin{haskellprime}
67
68 The @LANGUAGE@ pragma is a file-header pragma. A file-header pragma must
69 precede the module keyword in a source file. There can be as many
70 file-header pragmas as you please, and they can be preceded or
71 followed by comments. An individual language pragma begins with the
72 keyword @LANGUAGE@ and is followed by a comma-separated list of named
73 language extensions.
74
75 For example, to enable the FFI and preprocessing with CPP:
76 \bprog
77 @
78 {-# LANGUAGE ForeignFunctionInterface, CPP #-}
79 @
80 \eprog
81 If a Haskell implementation does not recognize or support a particular
82 language extension that a source file requests (or cannot support the
83 combination of language extensions requested), any attempt to compile
84 or otherwise use that file with that Haskell implementation must fail
85 with an error.
86
87 In the interests of portability, multiple attempts to enable the same,
88 supported language features (e.g. via command-line arguments,
89 implementation-specific extension dependencies or non-standard
90 pragmas) are specifically permitted.  Haskell 2010 implementations that
91 support the @LANGUAGE@ pragma are required to support
92 \bprog
93 @
94 {-# LANGUAGE Haskell2010 #-}
95 @
96 \eprog
97 Those implementations are also encouraged to support the following
98 named language extensions: @PatternGuards@, @NoNPlusKPatterns@,
99 @RelaxedPolyRec@, @EmptyDataDecls@, @ForeignFunctionInterface@. These
100 are the named language extensions, supported by some pre-Haskell 2010
101 implementations, that have been integrated into this report.
102
103 \end{haskellprime}
104
105 %**~footer