From 50c50170891e91e1961ef67e2677e61c4d8f76e2 Mon Sep 17 00:00:00 2001 From: "simonpj@microsoft.com" Date: Wed, 27 Aug 2008 09:05:44 +0000 Subject: [PATCH] Improve documentation of MagicHash and primitive types generally (Trac #2547) --- docs/users_guide/flags.xml | 2 +- docs/users_guide/glasgow_exts.xml | 103 +++++++++++++++++++++++-------------- 2 files changed, 65 insertions(+), 40 deletions(-) diff --git a/docs/users_guide/flags.xml b/docs/users_guide/flags.xml index 5e52d61..d7f2fca 100644 --- a/docs/users_guide/flags.xml +++ b/docs/users_guide/flags.xml @@ -787,7 +787,7 @@ - Enable the “magic hash”. + Allow "#" as a postfix modifier on identifiers. dynamic diff --git a/docs/users_guide/glasgow_exts.xml b/docs/users_guide/glasgow_exts.xml index 0bccb9e..4d31dd1 100644 --- a/docs/users_guide/glasgow_exts.xml +++ b/docs/users_guide/glasgow_exts.xml @@ -131,6 +131,16 @@ documentation describes all the libraries that come with GHC. + : + + + Allow "#" as a postfix modifier on identifiers. + + + + + + ,: @@ -308,7 +318,8 @@ documentation describes all the libraries that come with GHC. Unboxed types and primitive operations -GHC is built on a raft of primitive data types and operations. +GHC is built on a raft of primitive data types and operations; +"primitive" in the sense that they cannot be defined in Haskell itself. While you really can use this stuff to write fast code, we generally find it a lot less painful, and more satisfying in the long run, to use higher-level language features and libraries. With @@ -316,28 +327,21 @@ While you really can use this stuff to write fast code, unboxed version in any case. And if it isn't, we'd like to know about it. -We do not currently have good, up-to-date documentation about the -primitives, perhaps because they are mainly intended for internal use. -There used to be a long section about them here in the User Guide, but it -became out of date, and wrong information is worse than none. - -The Real Truth about what primitive types there are, and what operations -work over those types, is held in the file -compiler/prelude/primops.txt.pp. -This file is used directly to generate GHC's primitive-operation definitions, so -it is always correct! It is also intended for processing into text. - -Indeed, -the result of such processing is part of the description of the - External - Core language. -So that document is a good place to look for a type-set version. -We would be very happy if someone wanted to volunteer to produce an XML -back end to the program that processes primops.txt so that -we could include the results here in the User Guide. - -What follows here is a brief summary of some main points. +All these primitive data types and operations are exported by the +library GHC.Prim, for which there is +detailed online documentation. +(This documentation is generated from the file compiler/prelude/primops.txt.pp.) + + +If you want to mention any of the primitive data types or operations in your +program, you must first import GHC.Prim to bring them +into scope. Many of them have names ending in "#", and to mention such +names you need the extension (). + + +The primops make extensive use of unboxed types +and unboxed tuples, which +we briefly summarise here. Unboxed types @@ -366,26 +370,15 @@ would use in C: <literal>Int#</literal> (long int), know and love—usually one instruction. </para> -<para> For some primitive types we have special syntax for literals. -Anything that would be an integer lexeme followed by a -<literal>#</literal> is an <literal>Int#</literal> literal, e.g. -<literal>32#</literal> and <literal>-0x3A#</literal>. Likewise, -any non-negative integer literal followed by -<literal>##</literal> is a <literal>Word#</literal> literal. -Likewise, any floating point literal followed by a -<literal>#</literal> is a <literal>Float#</literal> literal, and -followed by <literal>##</literal> is a -<literal>Double#</literal>. Finally, a string literal followed by a -<literal>#</literal>, e.g. <literal>"foo"#</literal>, -is a <literal>Addr#</literal> literal. -</para> - <para> Primitive (unboxed) types cannot be defined in Haskell, and are therefore built into the language and compiler. Primitive types are always unlifted; that is, a value of a primitive type cannot be -bottom. We use the convention that primitive types, values, and -operations have a <literal>#</literal> suffix. +bottom. We use the convention (but it is only a convention) +that primitive types, values, and +operations have a <literal>#</literal> suffix (see <xref linkend="magic-hash"/>). +For some primitive types we have special syntax for literals, also +described in the <link linkend="magic-hash">same section</link>. </para> <para> @@ -562,8 +555,40 @@ Indeed, the bindings can even be recursive. <sect1 id="syntax-extns"> <title>Syntactic extensions + + The magic hash + The language extension allows "#" as a + postfix modifier to identifiers. Thus, "x#" is a valid variable, and "T#" is + a valid type constructor or data constructor. + + The hash sign does not change sematics at all. We tend to use variable + names ending in "#" for unboxed values or types (e.g. Int#), + but there is no requirement to do so; they are just plain ordinary variables. + Nor does the extension bring anything into scope. + For example, to bring Int# into scope you must + import GHC.Prim (see ); + the extension + then allows you to refer to the Int# + that is now in scope. + The also enables some new forms of literals (see ): + + 'x'# has type Char# + "foo"# has type Addr# + 3# has type Int#. In general, + any Haskell 98 integer lexeme followed by a # is an Int# literal, e.g. + -0x3A# as well as 32#. + 3## has type Word#. In general, + any non-negative Haskell 98 integer lexeme followed by ## + is a Word#. + 3.2# has type Float#. + 3.2## has type Double# + + + + + Hierarchical Modules -- 1.7.10.4