This is ../p/doc/info/gpc.info, produced by makeinfo version 4.0 from
gpc.texi.

INFO-DIR-SECTION GNU programming tools
START-INFO-DIR-ENTRY
* GPC: (gpc).                   The GNU Pascal Compiler.
END-INFO-DIR-ENTRY
INFO-DIR-SECTION Individual utilities
START-INFO-DIR-ENTRY
* GPC: (gpc)Invoking GPC.       The GNU Pascal Compiler.
END-INFO-DIR-ENTRY

   This file documents the GNU Pascal Compiler.

   Copyright (C) 1988-2002 Free Software Foundation, Inc.

   Permission is granted to make and distribute verbatim copies of this
manual provided the copyright notice and this permission notice are
preserved on all copies.

   Permission is granted to copy and distribute modified versions of
this manual under the conditions for verbatim copying, provided also
that the sections entitled "GNU General Public License", "The GNU
Project", "The GNU Manifesto" and "Funding for Free Software" are
included exactly as in the original, and provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

   Permission is granted to copy and distribute translations of this
manual into another language, under the above conditions for modified
versions, except that the sections entitled "GNU General Public
License", "The GNU Project", "The GNU Manifesto" and "Funding for Free
Software" and this permission notice, may be included in translations
approved by the Free Software Foundation instead of in the original
English.


File: gpc.info,  Node: GPC Options,  Prev: GPC Command Line Options,  Up: Invoking GPC

The most commonly used options to GPC
=====================================

   As the most simple example, calling

     gpc foo.pas

   tells GPC to compile the source file `foo.pas' and to produce an
executable of the default name which is `foo.exe' on EMX, `a.exe' on
Cygwin, both `a.out' and `a.exe' on DJGPP, and `a.out' on most other
platforms.

   Users familiar with BP, please note that you have to give the file
name extension `.pas': GPC is a common interface for a Pascal compiler,
a C, ObjC and C++ compiler, an assembler, a linker, and perhaps an Ada
and a FORTRAN compiler. From the extension of your source file GPC
figures out which compiler to run. GPC recognizes Pascal sources by the
extension `.pas', `.p', `.pp' or `.dpr'. GPC also accepts source files
in other languages (e.g., `.c' for C) and calls the appropriate
compilers for them. Files with the extension `.o' or without any special
recognized extension are considered to be object files or libraries to
be linked.

   Another example:

     gpc -O2 -Wall --executable-file-name --automake --unit-path=units foo.pas

   This will compile the source file `foo.pas' to an executable named
`foo' (`--executable-file-name') with fairly good optimization (`-O2'),
warning about possible problems (`-Wall'). If the program uses units or
imports modules, they will be searched for in a directory called `units'
(`--unit-path') and automatically compiled and linked (`--automake').

   The following table lists the most commonly used options to GPC.

`--automake'
     Check whether modules/units used must be recompiled and do the
     recompilation when necessary.

`--unit-path=DIR[:DIR...]'
     Search the given directories for units and object files.

`--object-path=DIR[:DIR...]'
     Search the given directories for object files.

`--unit-destination-path=DIR'
     Place compiled units (GPI and object files) into the directory
     DIR. The default is the current directory.

`--object-destination-path=DIR'
     Place compiled object files (e.g., from C files, but not from
     Pascal units) into the directory DIR. The default is the directory
     given with `--unit-destination-path'.

`--executable-path=DIR'
     Place the executable compiled into the directory DIR. The default
     is the main source file's directory.

`-o FILE'
     Place output in file FILE. This applies regardless to whatever
     sort of output is being produced, whether it be an executable file,
     an object file, an assembler file, etc.

     Since only one output file can be specified, it does not make sense
     to use `-o' when compiling more than one input file, unless you
     are producing an executable file as output.

`--executable-file-name[=NAME]'
     Derive the executable file name from the source file name, or use
     NAME as the executable file name. The difference to the `-o'
     option is that `--executable-file-name' considers the
     `--executable-path', while `-o' does not and accepts a file name
     with directory. Furthermore, `--executable-file-name' only applies
     to executables, not to other output formats selected.

`-LDIR'
     Search the directory DIR for libraries. Can be given multiple
     times.

`-IDIR'
     Search the directory DIR for include files. Can be given multiple
     times.

`-lLIBRARY'
     Search the library named LIBRARY when linking. This option must be
     placed on the command line _after_ all source or object files or
     other libraries that reference the library.

`-O[N]'
     Select the optimization level. Without optimization (or `-O0'
     which is the default), the compiler's goal is to reduce the
     compilation time and to make debugging produce the expected
     results.  Statements are independent: if you stop the program with
     a breakpoint between statements, you can then assign a new value to
     any variable or change the program counter to any other statement
     in the same routine and get exactly the results you would expect
     from the source code.

     With optimization, the compiler tries to reduce code size and
     execution time. The higher the value of N, the more optimizations
     will be done, but the longer the compilation will take.

     If you use multiple `-O' options, with or without N, the last such
     option is the one that is effective.

`-g'
     Produce debugging information suitable for `gdb'. Unlike some
     other compilers, GNU Pascal allows you to use `-g' with `-O'. The
     shortcuts taken by optimized code may occasionally produce
     surprising results: some variables you declared may not exist at
     all; flow of control may briefly move where you did not expect it;
     some statements may not be executed because they compute constant
     results or their values were already at hand; some statements may
     execute in different places because they were moved out of loops.
     Nevertheless it proves possible to debug optimized output. This
     makes it reasonable to use the optimizer for programs still in the
     testing phase.

`-s'
     Remove all symbol table and relocation information from the
     executable. Note: this has no influence on the performance of the
     compiled executable.

`-Wall'
     Give warnings for a number of constructs which are not inherently
     erroneous but which are risky or suggest there may have been an
     error. There are additional warning options not implied by
     `-Wall', see the GCC warning options (*note Options to Request or
     Suppress Warnings: (gcc)Warning Options.), while `-Wall' only
     warns about such constructs that should be easy to avoid in
     programs. Therefore, we suggest using `-Wall' on most sources.

     Note that some warnings (e.g., those about using uninitialized
     variables) are never given unless you compile with optimization
     (see above), because otherwise the compiler doesn't analyze the
     usage patterns of variables.

`-Werror'
     Turn all warnings into errors.

`-S'
     Stop after the stage of compilation proper; do not assemble. The
     output is in the form of an assembler code file for each source
     file. By default, the assembler file name for a source file is made
     by replacing the extension with `.s'.

`-c'
     Compile and assemble the source files, but do not link. The output
     is in the form of an object file for each source file. By default,
     the object file name for a source file is made by replacing the
     extension with `.o'.

`-static'
     On systems that support dynamic linking, this prevents linking with
     the shared libraries, i.e. forces static linking. On other systems,
     this option has no effect.

`-DMACRO[=DEF]'
     Define the macro and conditional MACRO as DEF (or as `1' if DEF is
     omitted).

`-b MACHINE'
     The argument MACHINE specifies the target machine for compilation.
     This is useful when you have installed GNU Pascal as a
     cross-compiler.

`-v'
     Print (on standard error) the commands executed to run the stages
     of compilation. Also print the version number of the compiler
     driver program and of the preprocessor and the compiler proper.

`--classic-pascal-level-0'
`--classic-pascal'
`--extended-pascal'
`--object-pascal'
`--borland-pascal'
`--pascal-sc'
     GNU Pascal supports the features of several different Pascal
     standards and dialects. By default, they are all enabled. These
     switches tell GPC to restrict itself to the features of the
     specified standard. It does not enable any additional features.
     Warnings about constructs which would be valid in the specified
     dialect (e.g. assignment to a typed constant with
     `--borland-pascal') are suppressed.

     By default, GNU Pascal allows redefinition of keywords. Each of
     these switches causes GNU Pascal to forbid the redefinition of
     keywords of the specified standard.

     Valid ISO 7185 Pascal programs should compile properly with or
     without `--classic-pascal'. However, without this option, certain
     GNU extensions and Pascal features from other dialects are
     supported as well. With this option, they are rejected.

     These options are not intended to be useful; they exist only to
     satisfy pedants who would otherwise claim that GNU Pascal fails to
     support the ISO Standard or is not really compatible to Borland
     Pascal, or whatever. We recommend, rather, that users take
     advantage of the extensions of GNU Pascal and disregard the
     limitations of other compilers.

`-pedantic-errors'
     Produce errors rather than warnings for portability violations.
     Unlike in C, this does _not_ imply the `-pedantic' option, so you
     can, for instance, use `-pedantic-errors' without `-pedantic', but
     with `--extended-pascal'.

`--gpc-main=NAME'
     Name the entry point of the main program `NAME' instead of `main'
     on the linker level. This is useful, e.g., when working with some
     C libraries which define their own `main' function and require the
     program's main entry point to be named differently. (This option
     should preferably be used as a compiler directive in the unit or
     module which links to that strange C library, rather than be given
     on the command-line.)


File: gpc.info,  Node: Programming,  Next: Reference,  Prev: Invoking GPC,  Up: Top

The Programmer's Guide to GPC
*****************************

   *This chapter is still under development.*

   This chapter tells you how the source of a valid GNU Pascal program
should look like.  You can use it as tutorial about the GNU Pascal
language, but since the main goal is to document all special GPC
features, implementation-dependent stuff, etc., expect a steep learning
curve.

   This chapter does _not_ cover how to compile your programs and to
produce an executable - this is discussed above in *Note Invoking GPC::.

* Menu:

* Source Structures::            Programs, Units and Modules.
* Data Types::                   Standard and non-standard data types.
* Operators::                    Built-in and user-definable operators.
* Parameters::                   Procedure And Function Parameters
* Pointer Arithmetics::          How pointer arithmetics works in Pascal.
* String Slice Access::          Accessing parts of strings (and other arrays)
* Type Casts::                   Explicit and emulated type casting in GPC.
* OOP::                          How object-orientated programming is implemented.
* Compiler Directives::          Compiler Directives And The Preprocessor
* Library Routines::             Routines Built-in or in the Run Time System
* Other Languages::              How to share libraries with other languages.
* Notes for Debugging::          Problems and caveats when debugging GPC programs.
* Run Time System::              Pascal declarations for GPC's Run Time System library.
* GPC Units::                    Units included with GPC


File: gpc.info,  Node: Source Structures,  Next: Data Types,  Up: Programming

Source Structures
=================

   A source file accepted by GNU Pascal may contain up to one program,
zero or more ISO-style modules, and/or zero or more UCSD-style units.
Units and modules can be mixed in one project.

* Menu:

* The Program::                 The Source Structure of Programs
* Label Declaration::
* Constant Declaration::
* Type Declaration::
* Variable Declaration::
* Subroutine Declaration::      Procedures, Functions and Operators
* Statements::                  Loops and Conditional Statements
* Modules and Units::           Import Part and Module/Unit Concept

   One trivial example for a valid GPC source file follows. Note that
the code below may either be in one source file, or else the unit and
the program may be in separate source files.

     unit DemoUnit;
     
     interface
     
     procedure Hello;
     
     implementation
     
     procedure Hello;
     begin
       WriteLn ('Hello, world!')
     end;
     
     end.
     
     program UnitDemo;
     
     uses
       DemoUnit;
     
     begin
       Hello
     end.


File: gpc.info,  Node: The Program,  Next: Label Declaration,  Up: Source Structures

The Source Structure of Programs
--------------------------------

   A generic GNU Pascal program looks like the following:

     program NAME (Input, Output);
     
     IMPORT PART
     
     DECLARATION PART
     
     begin
       STATEMENT PART
     end.

   The `program' headline may be omitted in GPC, but a warning will be
given except in `--borland-pascal' mode.

   While the program parameters (usually `Input', `Output') are
obligatory in ISO Pascal if you want to use `ReadLn' and `WriteLn',
they are optional in GNU Pascal. GPC will warn about such missing
parameters in `--extended-pascal' mode. However if you give parameters
to the program headline, they work like ISO requires.

   The IMPORT PART consists either of an ISO-style `import'
specification or a UCSD/Borland-style `uses' clause. While `import' is
intended to be used with interfaces exported by ISO-10206 Extended
Pascal modules, and `uses' is intended to be used with units, this is
not enforced. (See also *Note uses::, *Note import::.)

   The DECLARATION PART consists of label, constant, type, variable or
subroutine declarations in free order. However, every identifier must
be declared before it is used. The only exception are type identifiers
pointing to another type identifier which may be declared below.

   The STATEMENT PART consists of a sequence of statements.

   As an extension, GPC supports a "declaring statement" which can be
used in the statement part to declare variables (see *Note var::).


File: gpc.info,  Node: Label Declaration,  Next: Constant Declaration,  Prev: The Program,  Up: Source Structures

Label Declaration
-----------------

   A label declaration has the following look:

     label
       LABEL NAME, ..., LABEL;

   A label declaration part starts with the reserved word `label',
which contains a list of labels.

See also
--------

   *Note label::, *Note goto::


File: gpc.info,  Node: Constant Declaration,  Next: Type Declaration,  Prev: Label Declaration,  Up: Source Structures

Constant Declaration
--------------------

   A constant declaration has the following look:

     const
       CONSTANT IDENTIFIER = CONSTANT EXPRESSION;
       ...
       CONSTANT IDENTIFIER = CONSTANT EXPRESSION;

   A constant declaration part starts with the reserved word `const'.
It declares a CONSTANT IDENTIFIER which is defined by CONSTANT
EXPRESSION. This expression has to be evaluatable during compilation
time, i.e. it can include numbers, parentheses, predefined operators,
sets and type casts (the last, however, is a Borland extension).  In
ISO-7185 Pascal, CONSTANT EXPRESSION must be a constant or a set. All
Pascal Dialects but ISO-Pascal allow the use of these intrinsic
functions in CONSTANT EXPRESSION:

   *Note Abs::, *Note Round::, *Note Trunc::, *Note Chr::, *Note Ord::,
*Note Length::, *Note Pred::, *Note Succ::, *Note SizeOf::, *Note Odd::.

   In Borland Pascal, in the constant declaration part variables can be
declared as well, which are given an initial value. These variables are
called "typed constants". It is good style to avoid this use,
especially since Extended Pascal and GNU Pascal allow to initialize a
variable in variable declaration part or give a type a preset value on
declaration.

     const
       FiveFoo      = 5;
       StringFoo    = 'string constant';
       AlphabetSize = Ord ('Z') - Ord ('A') + 1;
     
     type
       PInteger     = ^Integer;     { Define a pointer to an Integer }
     
     const
       { Constant which holds a pointer to an Integer at address 1234 }
       AddressFoo   = PInteger (1234);

   * BP does not know initialized variables, only typed constants. Even
     worse, it allows them to be misused as variables, without even
     warning. GPC supports this (unwillingly ;-), and warns unless in
     `--borland-pascal' mode.

     An example of a typed constant:

          const
            i: Integer = 0;

     If you want to use it as a constant only, that's perfectly fine.
     However, if you modify `i', we suggest to translate the
     declaration to an initialized variable. The EP syntax is:

          var
            i: Integer value 0;

     GPC supports this as well as the following mixtureof dialects:

          var
            i: Integer = 0;

     Furthermore, you can also assign initialization values to types:

          program InitTypeDemo;
          
          type
            MyInteger = Integer value 42;
          
          var
            i: MyInteger;
          
          begin
            WriteLn (i)
          end.

     Here, all variables of type MyInteger are automatically initialized
     to 0 when created.

   * Arrays initializers look like this in BP:

          program BPArrayInitDemo;
          
          const
            MyStringsCount = 5;
          
          type
            Ident = String [20];
          
          const
            MyStrings: array [1 .. MyStringsCount] of Ident =
              ('export', 'implementation', 'import',
               'interface', 'module');
          
          begin
          end.

     And the following way in EP:

          program EPArrayInitDemo;
          
          {$W no-field-name-problem} { avoid a warning by GPC }
          
          const
            MyStringsCount = 5;
          
          type
            Ident = String (20);
          
          var
            MyStrings: array [1 .. MyStringsCount] of Ident value
              [1: 'export'; 2: 'implementation'; 3: 'import';
               4: 'interface'; 5: 'module'];
          
          begin
          end.

     There seem to be pros and cons to each style. GPC supports both as
     well as just about any thinkable mixture of them.

     Some folks don't like having to specify an index since it requires
     renumbering if you want to add a new item to the middle. However,
     if you index by an enumerated type, you might be able to avoid
     major renumbering by hand.


See also
--------

   *Note Subroutine Parameter List Declaration::


File: gpc.info,  Node: Type Declaration,  Next: Variable Declaration,  Prev: Constant Declaration,  Up: Source Structures

Type Declaration
----------------

   A type declaration looks like this:

     type
       TYPE IDENTIFIER = TYPE DEFINITION;
       ...
       TYPE IDENTIFIER = TYPE DEFINITION;
   or, with preset content:
     type
       TYPE IDENTIFIER = TYPE DEFINITION value CONSTANT EXPRESSION;
       ...
       TYPE IDENTIFIER = TYPE DEFINITION value CONSTANT EXPRESSION;

   A type declaration part begins with the reserved word `type'.  It
declares a TYPE IDENTIFIER which is defined by TYPE DEFINITION.  A type
definition either can be an array, a record, a schema, a set, an
object, a subrange, an enumerated type, a pointer to another type
identifier or simply another type identifier which is to alias.  If a
schema type is to be declared, TYPE IDENTIFIER is followed by a
discriminant enclosed in parentheses:

     TYPE IDENTIFIER (DISCRIMINANT) = SCHEMA TYPE DEFINITION;

   If `value' is specified, followed by a constant satisfying the type
definition, every variable of this type is initialized with CONSTANT
EXPRESSION, unless it is initialized by `value' itself.  The reserved
word `value' can be replaced by `=', however `value' is not allowed in
ISO-Pascal and Borland Pascal, and the replacement by `=' is not
allowed in Extended Pascal.

Type declaration example
------------------------

     type
       { This side is the }     { That side is the }
       { type declaration }     { type definition  }
     
       Arrayfoo            = array [0 .. 9] of Integer;  { array definition }
       Recordfoo           = record                      { record definition }
                               Bar: Integer;
                             end;
     
            { schema def with discriminants ``x, y: Integer'' }
       SchemaFoo (x, y: Integer) = array [x .. y] of Integer;
       CharSetFoo          = set of Char;              { Def of a set }
       ObjectFoo           = object                    { Def of an object }
                               procedure DoAction;
                               constructor Init;
                               destructor Done;
                             end;
       SubrangeFoo         = -123..456;                { subrange def }
     
       EnumeratedFoo       = (Pope,John,the,Second);   { enum type def }
            { Def of a pointer to another type identifier }
       PInteger            = ^arrayfoo;
            { Def of an alias name for another type identifier }
       IdentityFoo         = Integer;
            { Def of an integer which was initialized by 123 }
       InitializedFoo      = Integer value 123;

See also
--------

   *Note Type Definition::, *Note Data Types::, *Note Variable
Declaration::


File: gpc.info,  Node: Variable Declaration,  Next: Subroutine Declaration,  Prev: Type Declaration,  Up: Source Structures

Variable Declaration
--------------------

   A variable declaration looks like this:

     var
       VARIABLE IDENTIFIER: TYPE IDENTIFIER;
       ...
       VARIABLE IDENTIFIER: TYPE IDENTIFIER;
   or
     var
       VARIABLE IDENTIFIER: TYPE DEFINITION;
       ...
       VARIABLE IDENTIFIER: TYPE DEFINITION;
   and with initializing value:
     var
       VARIABLE IDENTIFIER: TYPE IDENTIFIER value CONSTANT EXPRESSION;
       ...
       VARIABLE IDENTIFIER: TYPE IDENTIFIER value CONSTANT EXPRESSION;
   or
     var
       VARIABLE IDENTIFIER: TYPE DEFINITION value CONSTANT EXPRESSION;
       ...
       VARIABLE IDENTIFIER: TYPE DEFINITION value CONSTANT EXPRESSION;

   A variable declaration part begins with the reserved word `var'.  It
declares a VARIABLE IDENTIFIER whose type either can be specified by a
type identifier, or by a type definion which either can be an array, a
record, a set, a subrange, an enumerated type or a pointer to an type
identifier.  If `value' is specified followed by a constant expression
satisfying the specified type, the variable declared is initialized with
CONSTANT EXPRESSION.  The reserved word `value' can be replaced by `=',
however `value' is not allowed in ISO-Pascal and Borland Pascal, and the
replacement by `=' is not allowed in Extended Pascal.

See also
--------

   *Note Type Definition::, *Note Type Declaration::, *Note Data
Types::, *Note The Declaring Statement::, *Note Subroutine Parameter
List Declaration::


File: gpc.info,  Node: Subroutine Declaration,  Next: Statements,  Prev: Variable Declaration,  Up: Source Structures

Subroutine Declaration
----------------------

* Menu:

* The Procedure::
* The Function::
* The Operator::
* Subroutine Parameter List Declaration::


File: gpc.info,  Node: The Procedure,  Next: The Function,  Up: Subroutine Declaration

The Procedure
.............

     procedure PROCEDURE IDENTIFIER;
     DECLARATION PART
     begin
       STATEMENT PART
     end;
   or with a parameter list:
     procedure PROCEDURE IDENTIFIER (PARAMETER LIST);
     DECLARATION PART
     begin
       STATEMENT PART
     end;

   A procedure is quite like a sub-program: The DECLARATION PART
consists of label, constant, type, variable or subroutine declarations
in free order. The STATEMENT PART consists of a sequence of statements.
If PARAMETER LIST is specified, parameters can be passed to the
procedure and can be used in STATEMENT PART. A recursive procedure call
is allowed.

See also
--------

   *Note The Function::, *Note Subroutine Parameter List Declaration::


File: gpc.info,  Node: The Function,  Next: The Operator,  Prev: The Procedure,  Up: Subroutine Declaration

The Function
............

     function FUNCTION IDENTIFIER: FUNCTION RESULT TYPE;
     DECLARATION PART
     begin
       STATEMENT PART
     end;
   or with a parameter list:
     function FUNCTION IDENTIFIER (PARAMETER LIST): FUNCION RESULT TYPE;
     DECLARATION PART
     begin
       STATEMENT PART
     end;

   A function is a subroutine which has a return value of type FUNCTION
RESULT TYPE. It is structured like the program: the DECLARATION PART
consists of label, constant, type, variable or subroutine declarations
in free order. The STATEMENT PART consists of a sequence of statements.
If PARAMETER LIST is specified, parameters can be passed to the
function and can be used in STATEMENT PART. The return value is set via
an assignment:
     FUNCTION IDENTIFIER := EXPRESSION
   Recursive function calls are allowed. Concerning the result type,
ISO-7185 Pascal and Borland Pascal only allow the intrinsic types,
subranges, enumerated types and pointer types to be returned. In
Extended Pascal, FUNCTION RESULT TYPE can be every assignable type.  Of
course, there are no type restrictions in GNU Pascal as well.  If
extended syntax is switched on, functions can be called like procedures
via procedure call statement.

See also
--------

   *Note The Procedure::, *Note Subroutine Parameter List Declaration::,
*Note Data Types::


File: gpc.info,  Node: The Operator,  Next: Subroutine Parameter List Declaration,  Prev: The Function,  Up: Subroutine Declaration

The Operator
............

   GNU Pascal allows to define operators which can be used the infix
style in expressions. For a more detailed description, see *Note
Operators::


File: gpc.info,  Node: Subroutine Parameter List Declaration,  Prev: The Operator,  Up: Subroutine Declaration

Subroutine Parameter List Declaration
.....................................

     PARAMETER; ...; PARAMETER

   Value parameters are declared this way:
     PARAMETER IDENTIFIER: PARAMETER TYPE
   where parameters of the same type be listed, separated by commata:
     PARAMETER IDENTIFIER, ..., PARAMETER IDENTIFIER: PARAMETER TYPE

   If `var' is specified before a parameter, which is an USCD extension,
the compiler is told to pass the argument by reference, i.e. the
parameter passed to is expected to be an L-value whose type is
PARAMETER TYPE if specified, else it is compatible with any type:
     var PARAMETER IDENTIFIER: PARAMETER TYPE
   or without type specification:
     var PARAMETER IDENTIFIER
   This declaration is necessary if the parameter is to be modified
within a block and to hold its value still after return. Otherwise, the
parameter remains unchanged after block exit, since it is passed by
value, and therefore it is called value parameter.

   A parameter of this kind is called variable parameter and
corresponds to an L-value pointer (to TYPE IDENTIFIER if specified).
As a Borland Pascal extension, there are also constant parameters which
are not allowed to be changed in the related statement part.  Like
variable parameters, the type needs not to be declared; in this case
PARAMETER IDENTIFIER is treated as a typeless parameter.
     const PARAMETER IDENTIFIER: PARAMETER TYPE
   or without any further type specification:
     const PARAMETER IDENTIFIER

   As an Extended Pascal extension, there is a way to declare procedural
parameters directly:
     procedure PARAMETER IDENTIFIER
   or without type specification:
     function PARAMETER IDENTIFIER: PARAMETER IDENTIFIER RESULT TYPE

   Example for parameter lists:
     procedure Foo (var Bar; var Baz: Integer; const Fred: Integer);
     
       procedure Glork1 (function Foo: Integer; procedure Bar (Baz: Integer));
       begin
         Bar (Foo)
       end;
     
     begin
       baz := Integer (Bar) + Fred
     end;

See also
--------

   *Note Data Types::


File: gpc.info,  Node: Statements,  Next: Modules and Units,  Prev: Subroutine Declaration,  Up: Source Structures

Statements
----------

* Menu:

* Assignment::
* begin end Compound Statement::
* if Statement::
* case Statement::
* for Statement::
* while Statement::
* repeat Statement::
* asm Inline::
* with Statement::
* goto Statement::
* Procedure Call::
* The Declaring Statement::
* Loop Control Statements::


File: gpc.info,  Node: Assignment,  Next: begin end Compound Statement,  Up: Statements

Assignment
..........

   The way an assignment looks like:
     L-VALUE := EXPRESSION;

   This statement assigns any valid expression to L-VALUE. Make sure
that the result of EXPRESSION is compatible with L-VALUE, otherwise an
compilation error is reported. The `:=' is called assignment operator.
As long as L-VALUE and EXPRESSION are type compatible, they are
assignment compatible for _any definable type_ as well.


File: gpc.info,  Node: begin end Compound Statement,  Next: if Statement,  Prev: Assignment,  Up: Statements

begin end Compound Statement
............................

   It looks like that:
     begin
       STATEMENT;
       STATEMENT;
       ...
       STATEMENT
     end

   This statement joins several STATEMENTS together into one compound
statement which is treated as a single statement by the compiler. The
finishing semicolon before `end' can be left out.


File: gpc.info,  Node: if Statement,  Next: case Statement,  Prev: begin end Compound Statement,  Up: Statements

if Statement
............

   This statement has the following look:
     if BOOLEAN EXPRESSION then
       STATEMENT
   or with an alternative statement:
     if BOOLEAN EXPRESSION then
       STATEMENT1
     else
       STATEMENT2

   The `if' ... `then' statement consists of a boolean expression and a
STATEMENT, which is conditionally executed if the evaluation of BOOLEAN
EXPRESSION yields true.

   If `if' ... `then' ... `else' is concerned, STATEMENT1 is executed
depending on BOOLEAN EXPRESSION being true, otherwise STATEMENT2 is
executed alternatively. Note: the statement before else _must not_
finish with a semicolon.


File: gpc.info,  Node: case Statement,  Next: for Statement,  Prev: if Statement,  Up: Statements

case Statement
..............

     case EXPRESSION of
       SELECTOR: STATEMENT;
       ...
       SELECTOR: STATEMENT;
     end
   or, with alternative statement sequence:
     case ORDINAL EXPRESSION of
       SELECTOR: STATEMENT;
       ...
       SELECTOR: STATEMENT;
     otherwise                   { ``else'' instead of ``otherwise'' allowed }
       STATEMENT;
       ...
       STATEMENT;
     end
   or, as part of the invariant `record' type definition:
     type
       foo = record
         FIELD DECLARATIONS
       case bar: VARIANT TYPE of
         SELECTOR: (FIELD DECLARATIONS);
         SELECTOR: (FIELD DECLARATIONS);
         ...
       end;
   or, without a variant selector field,
     type
       foo = record
         FIELD DECLARATIONS
       case VARIANT TYPE of
         SELECTOR: (FIELD DECLARATIONS);
         SELECTOR: (FIELD DECLARATIONS);
         ...
       end;

   The `case' statement compares the value of ORDINAL EXPRESSION to
each SELECTOR, which can be a constant, a subrange, or a list of them
separated by commata, being compatible with the result of ORDINAL
EXPRESSION.  Note: duplicate selectors or range crossing is not allowed
unless {$borland-pascal} is specified. In case of equality the
corresponding statement is executed. If `otherwise' is specified and no
appropriate selector matched the expression, the series of statements
following `otherwise' is executed. As a synonym for `otherwise', `else'
can be used. The semicolon before `otherwise' is optional.

   @@ ????  The expression _must_ match one of the selectors in order
to continue, unless an alternative statement series is specified.

   For `case' in a variant record type definition, see *Note Record
Types::.

See also
--------

   *Note if Statement::


File: gpc.info,  Node: for Statement,  Next: while Statement,  Prev: case Statement,  Up: Statements

for Statement
.............

   For ordinal index variables:
     for ORDINAL VARIABLE := INITIAL VALUE to FINAL VALUE do
       STATEMENT
   or
     for ORDINAL VARIABLE := INITIAL VALUE downto FINAL VALUE do
       STATEMENT

   For sets:
     for SET ELEMENT TYPE VARIABLE in SOME SET do
       STATEMENT

   For pointer index variables:
     for POINTER VARIABLE := INITIAL ADDRESS to FINAL ADDRESS do
       STATEMENT
   or
     for POINTER VARIABLE := INITIAL ADDRESS downto FINAL ADDRESS do
       STATEMENT

   The FOR statement is a control statement where an index variable
assumes every value of a certain range and for every value the index
variable assumes STATEMENT is executed. The range can be specified by
two bounds (which must be of the same type as the index variable, i.e.
ordinal or pointers) or by a set.

   For ordinal index variables:
   - If `to' is specified, the index counter is increased by one as
     long as INITIAL VALUE is less or equal to FINAL VALUE,

   - if `downto' is specified, it is decreased by one as long as
     INITIAL VALUE is greater or equal to FINAL VALUE.

   For pointer index variables:
   - If `to' is specified, the index counter is increased by the size
     of the type the index variable points to (if it is a typed
     pointer, otherwise by one if it is typeless) as long as INITIAL
     ADDRESS is less or equal to FINAL ADDRESS,

   - if `downto' is specified, it is decreased by a corresponding value
     as long as INITIAL ADDRESS is greater or equal to FINAL ADDRESS.

   Since gpc provides a flat memory modell, all addresses are linear,
so they can be compared. Still, such loops should be used (if at all)
only for iterating through successive elements of an array.

   For sets:
   - STATEMENT is executed with the index variable (which must be
     ordinal and of the same type as the set elements) assuming every
     element in SOME SET, however note that a set is a not-ordered
     structure.

   *Note:* A modification of the index variable may result in
unpredictable action.

See also
--------

   *Note Set Types::, *Note Pointer Arithmetics::, *Note repeat
Statement::, *Note for Statement::


File: gpc.info,  Node: while Statement,  Next: repeat Statement,  Prev: for Statement,  Up: Statements

while Statement
...............

   The while loop has the following form
     while BOOLEAN EXPRESSION do
       STATEMENT

   The `while' statement declares a loop which is executed while
BOOLEAN EXPRESSION is true. Since the terminating condition is checked
before execution of the loop body, STATEMENT may never be executed.

See also
--------

   *Note repeat Statement::, *Note for Statement::


File: gpc.info,  Node: repeat Statement,  Next: asm Inline,  Prev: while Statement,  Up: Statements

repeat Statement
................

     repeat
       STATEMENT;
       ...
       STATEMENT;
     until BOOLEAN EXPRESSION

   The `repeat' ... `until' statement declares a loop which is repeated
until BOOLEAN EXPRESSION is true. Since the terminating condition is
checked after execution of the loop body, the statement sequence is
executed at least once.

See also
--------

   *Note while Statement::, *Note for Statement::


File: gpc.info,  Node: asm Inline,  Next: with Statement,  Prev: repeat Statement,  Up: Statements

asm Inline
..........

   @@ ????
     asm (StatementList: String);

   The `asm' inline statement is a GNU extension. It requires its
paramenter to be AT&T-noted assembler statements, and therefore it is
not compatible with that one of Borland Pascal. STATEMENTLIST is a
string containing asm statements seperated by semicola.


File: gpc.info,  Node: with Statement,  Next: goto Statement,  Prev: asm Inline,  Up: Statements

with Statement
..............


File: gpc.info,  Node: goto Statement,  Next: Procedure Call,  Prev: with Statement,  Up: Statements

goto Statement
..............

   @@ ????  This statement looks like this:
     goto LABEL

   (Under construction.)


File: gpc.info,  Node: Procedure Call,  Next: The Declaring Statement,  Prev: goto Statement,  Up: Statements

Procedure Call
..............

     SUBROUTINE NAME;

   This statement calls the subroutine SUBROUTINE NAME which can either
be a procedure or, if GNU extended syntax is turned on, a function. In
this case, the return value is ignored.


File: gpc.info,  Node: The Declaring Statement,  Next: Loop Control Statements,  Prev: Procedure Call,  Up: Statements

The Declaring Statement
.......................

   This statement allows to declare a variable within a statement part.
It looks like this:
     var
       VARIABLE IDENTIFIER: TYPE IDENTIFIER;
   or
     var
       VARIABLE IDENTIFIER: TYPE DEFINITION;
   and with initializing value:
     var
       VARIABLE IDENTIFIER: TYPE IDENTIFIER value EXPRESSION;
   or
     var
       VARIABLE IDENTIFIER: TYPE DEFINITION value EXPRESSION;

   Unlike in declaration parts, the initializing EXPRESSION has not to
be a constant expression. Note that every declaring statement has to
start with `var'. The name space of VARIABLE IDENTIFIER extends from
its declaration to the end of the current matching statement sequence
(which can be a statement part (of the program, a function, a procedure
or an operator) or, within that part, a begin end compound statement, a
repeat loop, or the else branch of a case statement). This statement is
a GNU extension.

See also
--------

   *Note Type Definition::, *Note Data Types::


File: gpc.info,  Node: Loop Control Statements,  Prev: The Declaring Statement,  Up: Statements

Loop Control Statements
.......................

   These are
     Continue;
   and
     Break;

   These simple statements _must not_ occur outside a loop, i.e. a for,
while or repeat statement. `Continue' transfers control to the beginning
of the loop right by its call, `Break' exits the current loop turn and
continues loop execution.


File: gpc.info,  Node: Modules and Units,  Prev: Statements,  Up: Source Structures

Import Part and Module/Unit Concept
-----------------------------------

* Menu:

* Modules::   The source structure of ISO-10206 Extended Pascal Modules.
* Units::     The source structure of UCSD/Borland Pascal Units.


File: gpc.info,  Node: Modules,  Next: Units,  Up: Modules and Units

The Source Structure of ISO-10206 Extended Pascal Modules
.........................................................

   @@ Description missing here

   A module can have one or more `export' clauses and the name of an
`export' clause doesn't have to be equal to the name of the module.

   Sample module code with separate `interface' and `implementation'
parts:

     module DemoModule interface;  { interface part }
     
     export DemoModule = (FooType, SetFoo, GetFoo);
     
     type
       FooType = Integer;
     
     procedure SetFoo (f: FooType);
     function  GetFoo: FooType;
     
     end.
     
     module DemoModule implementation;  { implementation part }
     
     import
       StandardInput;
       StandardOutput;
     
     var
       Foo: FooType;
     
     { Note: the effect is the same as a `forward' directive would have:
       parameter lists and return types are not allowed in the
       declaration of exported routines, according to EP. In GPC, they
       are allowed, but not required. }
     procedure SetFoo;
     begin
       Foo := f
     end;
     
     function GetFoo;
     begin
       GetFoo := Foo
     end;
     
     to begin do
       begin
         foo := 59;
         WriteLn ('Just an example of a module initializer. See comment below')
       end;
     
     to end do
       begin
         Foo := 0;
         WriteLn ('Goodbye')
       end;
     
     end.

   Alternatively the module interface and implementation may be
combined as follows:

     module DemoMod2; { Alternative method }
     
     export Catch22 = (FooType, SetFoo, GetFoo);
     
     type
       FooType = Integer;
     
     procedure SetFoo (f: FooType);
     function  GetFoo: FooType;
     
     end; { note: this end is required here, even if the
            module-block below would be empty. }
     
     var
       Foo: FooType;
     
     procedure SetFoo;
     begin
       Foo := f
     end;
     
     function GetFoo;
     begin
       GetFoo := Foo
     end;
     
     end.

   Either one of the two methods may be used like this:

     program ModuleDemo (Output);
     
     import DemoModule;
     
     begin
       SetFoo (999);
       WriteLn (GetFoo);
     end.

     program ModDemo2 (Output);
     
     import Catch22 in 'demomod2.pas';
     
     begin
       SetFoo (999);
       WriteLn (GetFoo);
     end.

   Somewhat simpler GPC modules are also supported. *Note:* This is not
supported in the Extended Pascal standard.

   This is a simpler module support that does not require exports,
imports, module headers etc.

   These non-standard simple GPC modules look like (does not have an
export part, does not have a separate module-block, does not use
import/export features.)

     module DemoMod3;
     
     type
       FooType = Integer;
     
     var
       Foo: FooType;
     
     procedure SetFoo (f: FooType);
     begin
       Foo := f
     end;
     
     function GetFoo: FooType;
     begin
       GetFoo := Foo;
     end;
     
     end.
     
     program ModDemo3 (Output);
     
     { Manually do the "import" from DemoMod3 }
     type
       FooType = Integer;
     
     procedure SetFoo (f: FooType); external;
     function  GetFoo: FooType;     external;
     
     begin
       SetFoo (999);
       WriteLn (GetFoo)
     end.

   Module initialization and finalization:

   The `to begin do' module initialization and `to end do' module
finalization constructs now work on _every_ target.

   By the way: The "GPC specific" module definition is almost identical
to the PXSC standard. With an additional keyword `global' which puts a
declaration into an export interface with the name of the module, it
will be the same. @@This is planned.


File: gpc.info,  Node: Units,  Prev: Modules,  Up: Modules and Units

The Source Structure of UCSD/Borland Pascal Units
.................................................

   A generic GNU Pascal unit looks like the following:

     unit NAME;
     
     interface
     
     IMPORT PART
     
     INTERFACE PART
     
     implementation
     
     IMPLEMENTATION PART
     
     INITIALIZATION PART
     
     end.

   The NAME of the unit should coincide with the name of the file with
the extension stripped. (If not, you can tell GPC the file name with
`uses foo in 'bar.pas'', see *Note uses::.)

   The IMPORT PART is either empty or contains a `uses' clause to
import other units. It may also consist of an ISO-style `import'
specification. Note that the implementation part is not preceeded by a
second import part in GPC (see *Note import::).

   The INTERFACE PART consists of constant, type, and variable
declarations, procedure and function headings which may be freely mixed.

   The IMPLEMENTATION PART is like the declaration part of a program,
but the headers of procedures and functions may be abbreviated:
Parameter lists and function return values may be omitted for
procedures and functions already declared in the interface part.

   The INITIALIZATION PART may be missing, or it may be a `begin'
followed by one or more statements, such that the unit has a statement
part between this `begin' and the final `end'. Alternatively, a unit
may have ISO-style module initializers and finalizers, see *Note to
begin do::, *Note to end do::.

   Note that GPC does _not_ yet check whether all interface
declarations are resolved in the same unit. The implementation of
procedures and functions which are in fact not used may be omitted,
and/or procedures and functions may be implemented somewhere else, even
in a different language. However, relying on a GPC bug (that will
eventually be fixed) is not a good idea, so this is not recommended.
Instead, declare such routines as `external'.

   A unit exports everything declared in the interface section. The
exported interface has the name of the unit and is compatible with
Extended Pascal module interfaces since GPC uses the same code to
handle both.


File: gpc.info,  Node: Data Types,  Next: Operators,  Prev: Source Structures,  Up: Programming

Data Types
==========

* Menu:

* Type Definition::                         The Declaration Part
* Ordinal Types::                           Built-in Ordinal Types
* Integer Types::                           Built-in Integer Types
* Real Types::                              Built-in Real Types
* String Types::                            Built-in Character and String Types
* Character Types::                         Built-in Chararacter Types. See Ordinal Types
* File Types::                              Built-in Types for File Handling
* Boolean (Intrinsic)::                     Built-in Type for Boolean values.
* Pointer (Intrinsic)::                     The Intrinsic Pointer Type
* Type Definition Possibilities::           User-defined Types
* Machine-dependent Type Implementation::   Differences in Implementation


File: gpc.info,  Node: Type Definition,  Next: Ordinal Types,  Up: Data Types

Type Definition
---------------

   As described in *Note Type Declaration::, a type declaration part
looks like this:
     type
        TYPE IDENTIFIER = TYPE DEFINITION;
        ...
        TYPE IDENTIFIER = TYPE DEFINITION;
   where the left side is the type declaration and the right one the
type definition side. GNU Pascal offers variant possibilities to
implement highly specialized and problem-specific data types.


File: gpc.info,  Node: Ordinal Types,  Next: Integer Types,  Prev: Type Definition,  Up: Data Types

Ordinal Types
-------------

   An ordinal type is a range of whole numbers. It includes integer
types, character types and subrange types of them.

   A character type is represented by the intrinsic type `Char' which
can hold elements of the operating system's character set (usually
ASCII).  Conversion between character types and ordinal types is
possible with the intrinsic functions `Ord' and `Chr' or type casting
techniques.

     type
       Foo: Char;       { foo can hold a character }
       Num: '0' .. '9'; { Can hold decimal ciphers, is a subrange type of Char }

See also
--------

   *Note Ord::, *Note Chr::, *Note Type Casts::


File: gpc.info,  Node: Integer Types,  Next: Real Types,  Prev: Ordinal Types,  Up: Data Types

Integer Types
-------------

   Besides `Integer', GNU Pascal supports a large zoo of integer types.
Some of them you will find in other compilers, too, but most are GNU
extensions, introduced for particular needs. Many of these types are
synonyms for each other. In total, GPC provides 20 built-in integer
types, plus seven families you can play with. (Four of these "families"
are signed and unsigned, packed and unpacked subrange types; the others
are explained below.)

* Menu:

* Natural Integer Types::
* Main Branch Integer Types::
* Integer Types with Specified Size::
* Integer Types and Compatibility::
* Summary of Integer Types::

   See also: *Note Subrange Types::.


File: gpc.info,  Node: Natural Integer Types,  Next: Main Branch Integer Types,  Up: Integer Types

The CPU's Natural Integer Types
...............................

   For most purposes, you will always use `Integer', a signed integer
type which has the "natural" size of such types for the machine. On
most machines GPC runs on, this is a size of 32 bits, so `Integer'
usually has a range of `-2147483648..2147483647' (see *Note Integer::).

   If you need an unsigned integer type, the "natural" choice is
`Cardinal', also called `Word'. Like `Integer', it has 32 bits on most
machines and thus a range of `0..4294967295' (see *Note Cardinal::,
*Note Word::).

   These natural integer types should be your first choice for best
performance. For instance on an IA32 CPU operations with `Integer'
usually work faster than operations with shorter integer types like
`ShortInt' or `ByteInt' (see below).

