diff options
-rw-r--r-- | docs/users_guide/conf.py | 14 | ||||
-rw-r--r-- | docs/users_guide/glasgow_exts.rst | 219 |
2 files changed, 158 insertions, 75 deletions
diff --git a/docs/users_guide/conf.py b/docs/users_guide/conf.py index 0732c5ccd4..c64e0a3693 100644 --- a/docs/users_guide/conf.py +++ b/docs/users_guide/conf.py @@ -146,6 +146,11 @@ def parse_ghci_cmd(env, sig, signode): # Reference name return name +def parse_pragma(env, sig, signode): + name = sig.split(' ')[0] + signode += addnodes.desc_name('{-# '+name, sig + ' #-}') + return name + def parse_flag(env, sig, signode): # Break flag into name and args @@ -222,6 +227,15 @@ def setup(app): Field('since', label='Introduced in GHC version', names=['since']), ]) + app.add_object_type('pragma', 'pragma', + objname='Haskell pragma', + parse_node=parse_pragma, + indextemplate='pair: %s; pragma', + doc_field_types=[ + Field('since', label='Introduced in GHC version', names=['since']), + Field('where', label='Allowed contexts', names=['where']) + ]) + def increase_python_stack(): # Workaround sphinx-build recursion limit overflow: # pickle.dump(doctree, f, pickle.HIGHEST_PROTOCOL) diff --git a/docs/users_guide/glasgow_exts.rst b/docs/users_guide/glasgow_exts.rst index e90854c73d..723f1a373d 100644 --- a/docs/users_guide/glasgow_exts.rst +++ b/docs/users_guide/glasgow_exts.rst @@ -14361,9 +14361,11 @@ Certain pragmas are *file-header pragmas*: ``LANGUAGE`` pragma ------------------- -.. index:: - single: LANGUAGE; pragma - single: pragma; LANGUAGE +.. pragma:: LANGUAGE ⟨ext⟩, ⟨ext⟩, ... + + :where: file header + + Enable or disable a set of language extensions. The ``LANGUAGE`` pragma allows language extensions to be enabled in a portable way. It is the intention that all Haskell compilers support the @@ -14393,9 +14395,9 @@ if any of the requested extensions are not supported. ``OPTIONS_GHC`` pragma ---------------------- -.. index:: - single: OPTIONS_GHC - single: pragma; OPTIONS_GHC +.. pragma:: OPTIONS_GHC ⟨flags⟩ + + :where: file header The ``OPTIONS_GHC`` pragma is used to specify additional options that are given to the compiler when compiling this source file. See @@ -14421,14 +14423,21 @@ other compilers. ``WARNING`` and ``DEPRECATED`` pragmas -------------------------------------- -.. index:: - single: WARNING - single: DEPRECATED +.. pragma:: WARNING + + :where: declaration -The ``WARNING`` pragma allows you to attach an arbitrary warning to a -particular function, class, or type. A ``DEPRECATED`` pragma lets you -specify that a particular function, class, or type is deprecated. There -are two ways of using these pragmas. + The ``WARNING`` pragma allows you to attach an arbitrary warning to a + particular function, class, or type. + +.. pragma:: DEPRECATED + + :where: declaration + + A ``DEPRECATED`` pragma lets you specify that a particular function, class, + or type is deprecated. + +There are two ways of using these pragmas. - You can work on an entire module thus: :: @@ -14479,9 +14488,11 @@ You can suppress the warnings with the flag ``MINIMAL`` pragma ------------------ -.. index:: - single: MINIMAL - single: pragma; MINIMAL +.. pragma:: MINIMAL ⟨name⟩ | ⟨name⟩ , ... + + :where: in class body + + Define the methods needed for a minimal complete instance of a class. The ``MINIMAL`` pragma is used to specify the minimal complete definition of a class, i.e. specify which methods must be implemented by all @@ -14530,9 +14541,11 @@ These pragmas control the inlining of function definitions. ``INLINE`` pragma ~~~~~~~~~~~~~~~~~ -.. index:: - single: INLINE - single: pragma; INLINE +.. pragma:: INLINE ⟨name⟩ + + :where: top-level + + Force GHC to inline a value. GHC (with :ghc-flag:`-O`, as always) tries to inline (or "unfold") functions/values that are "small enough," thus avoiding the call @@ -14596,7 +14609,7 @@ has a number of other effects: which will optimise better than the corresponding use of ``comp2``. - It is useful for GHC to optimise the definition of an INLINE function - ``f`` just like any other non-INLINE function, in case the + ``f`` just like any other non-``INLINE`` function, in case the non-inlined version of ``f`` is ultimately called. But we don't want to inline the *optimised* version of ``f``; a major reason for ``INLINE`` pragmas is to expose functions in ``f``\'s RHS that have rewrite @@ -14609,7 +14622,7 @@ has a number of other effects: usual. For externally-visible functions the inline-RHS (not the optimised RHS) is recorded in the interface file. -- An INLINE function is not worker/wrappered by strictness analysis. +- An ``INLINE`` function is not worker/wrappered by strictness analysis. It's going to be inlined wholesale instead. GHC ensures that inlining cannot go on forever: every mutually-recursive @@ -14640,6 +14653,12 @@ See also the ``NOINLINE`` (:ref:`noinline-pragma`) and ``INLINABLE`` ``INLINABLE`` pragma ~~~~~~~~~~~~~~~~~~~~ +.. pragma:: INLINEABLE ⟨name⟩ + + :where: top-level + + Suggest that the compiler always consider inlining ``name``. + An ``{-# INLINABLE f #-}`` pragma on a function ``f`` has the following behaviour: @@ -14679,10 +14698,15 @@ The alternative spelling ``INLINEABLE`` is also accepted by GHC. ~~~~~~~~~~~~~~~~~~~ .. index:: - single: NOINLINE single: NOTINLINE -The ``NOINLINE`` pragma does exactly what you'd expect: it stops the +.. pragma:: NOINLINE ⟨name⟩ + + :where: top-level + + Instructs the compiler not to inline a value. + +The :pragma:`NOINLINE` pragma does exactly what you'd expect: it stops the named function from being inlined by the compiler. You shouldn't ever need to do this, unless you're very cautious about code size. @@ -14695,23 +14719,26 @@ used if you want your code to be portable). ``CONLIKE`` modifier ~~~~~~~~~~~~~~~~~~~~ -.. index:: - single: CONLIKE +.. pragma:: CONLINE + + :where: modifies :pragma:`INLINE` or :pragma:`NOINLINE` pragma -An ``INLINE`` or ``NOINLINE`` pragma may have a ``CONLIKE`` modifier, which affects -matching in RULEs (only). See :ref:`conlike`. + Instructs GHC to consider a value to be especially cheap to inline. + +An :pragma:`INLINE` or :pragma:`NOINLINE` pragma may have a :pragma:`CONLIKE` modifier, which affects +matching in :pragma:`RULE`\s (only). See :ref:`conlike`. .. _phase-control: Phase control ~~~~~~~~~~~~~ -Sometimes you want to control exactly when in GHC's pipeline the ``INLINE`` +Sometimes you want to control exactly when in GHC's pipeline the :pragma:`INLINE` pragma is switched on. Inlining happens only during runs of the *simplifier*. Each run of the simplifier has a different *phase number*; the phase number decreases towards zero. If you use -``-dverbose-core2core`` you'll see the sequence of phase numbers for -successive runs of the simplifier. In an ``INLINE`` pragma you can +:ghc-flag:`-dverbose-core2core` you will see the sequence of phase numbers for +successive runs of the simplifier. In an :pragma:`INLINE` pragma you can optionally specify a phase number, thus: - "``INLINE[k] f``" means: do not inline ``f`` until phase ``k``, but @@ -14729,7 +14756,7 @@ optionally specify a phase number, thus: The same information is summarised here: -:: +.. code-block:: none -- Before phase 2 Phase 2 and later {-# INLINE [2] f #-} -- No Yes @@ -14744,14 +14771,14 @@ By "Maybe" we mean that the usual heuristic inlining rules apply (if the function body is small, or it is applied to interesting-looking arguments etc). Another way to understand the semantics is this: -- For both ``INLINE`` and ``NOINLINE``, the phase number says when inlining is - allowed at all. +- For both :pragma:`INLINE` and :pragma:`NOINLINE`, the phase number says when + inlining is allowed at all. -- The ``INLINE`` pragma has the additional effect of making the function +- The :pragma:`INLINE` pragma has the additional effect of making the function body look small, so that when inlining is allowed it is very likely to happen. -The same phase-numbering control is available for RULES +The same phase-numbering control is available for :pragma:`RULE`\s (:ref:`rewrite-rules`). .. _line-pragma: @@ -14759,9 +14786,12 @@ The same phase-numbering control is available for RULES ``LINE`` pragma --------------- -.. index:: - single: LINE; pragma - single: pragma; LINE +.. pragma:: LINE ⟨lineno⟩ "⟨file⟩" + + :where: anywhere + + Generated by preprocessors to convey source line numbers of the original + source. This pragma is similar to C's ``#line`` pragma, and is mainly for use in automatically generated Haskell code. It lets you specify the line @@ -14809,7 +14839,7 @@ diagnostics and does not change the syntax of the code itself. ``RULES`` pragma ---------------- -The ``RULES`` pragma lets you specify rewrite rules. It is described in +The :pragma:`RULES` pragma lets you specify rewrite rules. It is described in :ref:`rewrite-rules`. .. _specialize-pragma: @@ -14822,8 +14852,12 @@ The ``RULES`` pragma lets you specify rewrite rules. It is described in single: pragma, SPECIALIZE single: overloading, death to +.. pragma:: SPECIALIZE ⟨name⟩ :: ⟨type⟩ + + Ask that GHC specialize a polymorphic value to a particular type. + (UK spelling also accepted.) For key overloaded functions, you can -create extra versions (NB: more code space) specialised to particular +create extra versions (NB: at the cost of larger code) specialised to particular types. Thus, if you have an overloaded function: :: @@ -14920,6 +14954,10 @@ specialise it as follows: ``SPECIALIZE INLINE`` ~~~~~~~~~~~~~~~~~~~~~ +.. pragma:: SPECIALIZE INLINE ⟨name⟩ :: ⟨type⟩ + + :where: top-level + A ``SPECIALIZE`` pragma can optionally be followed with a ``INLINE`` or ``NOINLINE`` pragma, optionally followed by a phase, as described in :ref:`inline-noinline-pragma`. The ``INLINE`` pragma affects the @@ -14945,9 +14983,9 @@ fire the first specialisation, whose body is also inlined. The result is a type-based unrolling of the indexing function. You can add explicit phase control (:ref:`phase-control`) to -``SPECIALISE INLINE`` pragma, just like on an ``INLINE`` pragma; if you -do so, the same phase is used for the rewrite rule and the INLINE -control of the specialised function. +``SPECIALISE INLINE`` pragma, just like on an :pragma:`INLINE` pragma; if you do +so, the same phase is used for the rewrite rule and the INLINE control of the +specialised function. .. warning:: You can make GHC diverge by using ``SPECIALISE INLINE`` on an ordinarily-recursive function. @@ -14955,9 +14993,9 @@ control of the specialised function. ``SPECIALIZE`` for imported functions ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Generally, you can only give a ``SPECIALIZE`` pragma for a function +Generally, you can only give a :pragma:`SPECIALIZE` pragma for a function defined in the same module. However if a function ``f`` is given an -``INLINABLE`` pragma at its definition site, then it can subsequently be +:pragma:`INLINABLE` pragma at its definition site, then it can subsequently be specialised by importing modules (see :ref:`inlinable-pragma`). For example :: module Map( lookup, blah blah ) where @@ -14971,7 +15009,7 @@ specialised by importing modules (see :ref:`inlinable-pragma`). For example :: data T = T1 | T2 deriving( Eq, Ord ) {-# SPECIALISE lookup :: [(T,a)] -> T -> Maybe a -Here, ``lookup`` is declared ``INLINABLE``, but it cannot be specialised +Here, ``lookup`` is declared :pragma:`INLINABLE`, but it cannot be specialised for type ``T`` at its definition site, because that type does not exist yet. Instead a client module can define ``T`` and then specialise ``lookup`` at that type. @@ -14979,13 +15017,13 @@ yet. Instead a client module can define ``T`` and then specialise Moreover, every module that imports ``Client`` (or imports a module that imports ``Client``, transitively) will "see", and make use of, the specialised version of ``lookup``. You don't need to put a -``SPECIALIZE`` pragma in every module. +:pragma:`SPECIALIZE` pragma in every module. -Moreover you often don't even need the ``SPECIALIZE`` pragma in the +Moreover you often don't even need the :pragma:`SPECIALIZE` pragma in the first place. When compiling a module ``M``, GHC's optimiser (when given the :ghc-flag:`-O` flag) automatically considers each top-level overloaded function declared in ``M``, and specialises it for the different types at which it is called in -``M``. The optimiser *also* considers each *imported* ``INLINABLE`` +``M``. The optimiser *also* considers each *imported* :pragma:`INLINABLE` overloaded function, and specialises it for the different types at which it is called in ``M``. So in our example, it would be enough for ``lookup`` to be called at type ``T``: @@ -15009,9 +15047,13 @@ be useful. ------------------------------ .. index:: - single: SPECIALIZE pragma + single: instance, specializing single: overloading, death to +.. pragma:: SPECIALIZE instance ⟨instance head⟩ + + :where: instance body + Same idea, except for instance declarations. For example: :: @@ -15029,8 +15071,12 @@ declaration. ``UNPACK`` pragma ----------------- -.. index:: - single: UNPACK +.. pragma:: UNPACK + + :where: data constructor field + + Instructs the compiler to unpack the contents of a constructor field into + the constructor itself. The ``UNPACK`` indicates to the compiler that it should unpack the contents of a constructor field into the constructor itself, removing a @@ -15071,7 +15117,7 @@ See also the :ghc-flag:`-funbox-strict-fields` flag, which essentially has the effect of adding ``{-# UNPACK #-}`` to every strict constructor field. .. [1] - In fact, ``UNPACK`` has no effect without :ghc-flag:`-O`, for technical + In fact, :pragma:`UNPACK` has no effect without :ghc-flag:`-O`, for technical reasons (see :ghc-ticket:`5252`). .. _nounpack-pragma: @@ -15079,8 +15125,11 @@ effect of adding ``{-# UNPACK #-}`` to every strict constructor field. ``NOUNPACK`` pragma ------------------- -.. index:: - single: NOUNPACK +.. pragma:: NOUNPACK + + :where: top-level + + Instructs the compiler not to unpack a constructor field. The ``NOUNPACK`` pragma indicates to the compiler that it should not unpack the contents of a constructor field. Example: :: @@ -15095,9 +15144,11 @@ field of the constructor ``T`` is not unpacked. ``SOURCE`` pragma ----------------- -.. index:: - single: SOURCE - single: pragma; SOURCE +.. pragma:: SOURCE + + :where: after ``import`` statement + + Import a module by ``hs-boot`` file to break a module loop. The ``{-# SOURCE #-}`` pragma is used only in ``import`` declarations, to break a module loop. It is described in detail in @@ -15108,6 +15159,13 @@ to break a module loop. It is described in detail in ``COMPLETE`` pragmas -------------------- +.. pragma:: COMPLETE + + :where: at top level + + Specify the set of constructors or pattern synonyms which constitute a total + match. + The ``COMPLETE`` pragma is used to inform the pattern match checker that a certain set of patterns is complete and that any function which matches on all the specified patterns is total. @@ -15235,6 +15293,13 @@ this order: single: INCOHERENT single: pragma; INCOHERENT +.. pragma:: OVERLAPPING +.. pragma:: OVERLAPPABLE +.. pragma:: OVERLAPS +.. pragma:: INCOHERENT + + :where: on instance head + The pragmas ``OVERLAPPING``, ``OVERLAPPABLE``, ``OVERLAPS``, ``INCOHERENT`` are used to specify the overlap behavior for individual instances, as described in Section :ref:`instance-overlap`. The pragmas @@ -15250,15 +15315,19 @@ Rewrite rules ============= .. index:: - single: RULES pragma - single: pragma; RULES single: rewrite rules +.. pragma:: RULES "⟨name⟩" forall ⟨binder⟩ ... . ⟨expr⟩ = ⟨expr⟩ ... + + :where: top-level + + Define a rewrite rule to be used to optimize a source program. + The programmer can specify rewrite rules as part of the source program (in a pragma). Here is an example: :: {-# RULES - "map/map" forall f g xs. map f (map g xs) = map (f.g) xs + "map/map" forall f g xs. map f (map g xs) = map (f.g) xs #-} Use the debug flag :ghc-flag:`-ddump-simpl-stats` to see what rules fired. If @@ -15281,7 +15350,7 @@ Syntax From a syntactic point of view: -- There may be zero or more rules in a ``RULES`` pragma, separated by +- There may be zero or more rules in a :pragma:`RULES` pragma, separated by semicolons (which may be generated by the layout rule). - The layout rule applies in a pragma. Currently no new indentation @@ -15290,8 +15359,8 @@ From a syntactic point of view: the same column as the enclosing definitions. :: {-# RULES - "map/map" forall f g xs. map f (map g xs) = map (f.g) xs - "map/append" forall f xs ys. map f (xs ++ ys) = map f xs ++ map f ys + "map/map" forall f g xs. map f (map g xs) = map (f.g) xs + "map/append" forall f xs ys. map f (xs ++ ys) = map f xs ++ map f ys #-} Furthermore, the closing ``#-}`` should start in a column to the @@ -15371,12 +15440,12 @@ From a syntactic point of view: then C's rules are in force when compiling A.) The situation is very similar to that for instance declarations. -- Inside a RULE "``forall``" is treated as a keyword, regardless of any +- Inside a :pragma:`RULE` "``forall``" is treated as a keyword, regardless of any other flag settings. Furthermore, inside a RULE, the language extension :extension:`ScopedTypeVariables` is automatically enabled; see :ref:`scoped-type-variables`. -- Like other pragmas, ``RULE`` pragmas are always checked for scope errors, +- Like other pragmas, :pragma:`RULE` pragmas are always checked for scope errors, and are typechecked. Typechecking means that the LHS and RHS of a rule are typechecked, and must have the same type. However, rules are only *enabled* if the :ghc-flag:`-fenable-rewrite-rules` flag is on (see @@ -15465,12 +15534,12 @@ give :: g y = y -Now ``g`` is inlined into ``h``, but ``f``\'s RULE has no chance to fire. -If instead GHC had first inlined ``g`` into ``h`` then there would have -been a better chance that ``f``\'s RULE might fire. +Now ``g`` is inlined into ``h``, but ``f``\'s :pragma:`RULE` has no chance to +fire. If instead GHC had first inlined ``g`` into ``h`` then there would have +been a better chance that ``f``\'s :pragma:`RULE` might fire. -The way to get predictable behaviour is to use a ``NOINLINE`` pragma, or an -``INLINE[⟨phase⟩]`` pragma, on ``f``, to ensure that it is not inlined until +The way to get predictable behaviour is to use a :pragma:`NOINLINE` pragma, or an +INLINE[⟨phase⟩] pragma, on ``f``, to ensure that it is not inlined until its RULEs have had a chance to fire. The warning flag :ghc-flag:`-Winline-rule-shadowing` (see :ref:`options-sanity`) warns about this situation. @@ -15503,9 +15572,9 @@ an application of ``f`` to one argument (in general, the number of arguments to the left of the ``=`` sign) should be considered cheap enough to duplicate, if such a duplication would make rule fire. (The name "CONLIKE" is short for "constructor-like", because constructors -certainly have such a property.) The ``CONLIKE`` pragma is a modifier to -INLINE/NOINLINE because it really only makes sense to match ``f`` on the -LHS of a rule if you are sure that ``f`` is not going to be inlined +certainly have such a property.) The :pragma:`CONLIKE` pragma is a modifier to +:pragma:`INLINE`/:pragma:`NOINLINE` because it really only makes sense to match +``f`` on the LHS of a rule if you are sure that ``f`` is not going to be inlined before the rule has a chance to fire. .. _rules-class-methods: @@ -15700,7 +15769,7 @@ Controlling what's going on in rewrite rules {-# INLINE build #-} build g = g (:) [] - Notice the ``INLINE``! That prevents ``(:)`` from being inlined when + Notice the :pragma:`INLINE`! That prevents ``(:)`` from being inlined when compiling ``PrelBase``, so that an importing module will “see” the ``(:)``, and can match it on the LHS of a rule. ``INLINE`` prevents any inlining happening in the RHS of the ``INLINE`` thing. I regret |