This is Info file gpc.info, produced by Makeinfo version 1.68 from the
input file /usr/local/src/gcc-2.8.1/p/doc/gpc.texi.

   This file documents the use and the internals of the GNU Pascal
compiler.

   Copyright (C) 1988, 1996 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," "Funding for
Free Software," and "Protect Your Freedom--Fight `Look And Feel'" 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," "Funding for Free Software," and "Protect Your Freedom--Fight
`Look And Feel'", 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: ShortInt,  Next: ShortReal,  Prev: ShortCard,  Up: Reference

ShortInt
========

Description
-----------

   `ShortInt' is a signed integer type which is not larger than
`Integer'.  On most platforms it is 16 bits wide and thus has a range
of `-32768..32767'.

   `ShortInt' in GNU Pascal is compatible to `short int' in GNU C.

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `ShortInt'.  (However see *Note Subrange
types::.)

   `ShortInt' in GNU Pascal corresponds to `Integer' in Borland Pascal
and Delphi 1.0.  Both Borland languages also define `ShortInt', but it
is an 8-bit signed integer type there (`ByteInt' in GNU Pascal).

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: ShortReal,  Next: ShortWord,  Prev: ShortInt,  Up: Reference

ShortReal
=========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: ShortWord,  Next: Single,  Prev: ShortReal,  Up: Reference

ShortWord
=========

Description
-----------

   `ShortWord' is an unsigned integer type which is not larger than
`Word'.  On most platforms it is 16 bits wide and thus has a range of
of `0..65535'.  It is the same as *Note ShortCard::.

   `ShortWord' in GNU Pascal is compatible to `short unsigned int' in
GNU C.

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `ShortWord'.  (However see *Note Subrange
types::.)

   `ShortWord' in GNU Pascal essentially corresponds to `Word' in
Borland Pascal and Delphi where it is a 16-bit unsigned integer type.

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: Single,  Next: shl,  Prev: ShortWord,  Up: Reference

Single
======

   (Under construction.)

Syntax
------

       Type
         Single = ShortReal;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: shl,  Next: shr,  Prev: Single,  Up: Reference

shl
===

Syntax
------

       Operator shl ( operand1, operand2: INTEGER TYPE ) = result: INTEGER TYPE;
   or
       Procedure shl ( Var operand1: INTEGER TYPE; operand2: INTEGER TYPE );

Description
-----------

   In GNU Pascal, `shl' has two built-in meanings:

  1. Bitwise shift left of an integer-type expression by another
     integer value.  The result is of the type of the first operand.

  2. Use as a "procedure":  `operand1' is shifted left by `operand2';
     the result is stored in `operand1'.


Standards
---------

   ISO Pascal does not define the `shl' operator; Borland Pascal and
Delphi do.

   Use of `shl' as a "procedure" is a GNU extension.

Example
-------

       Var
         a: Integer;
     
       ...
     
       a:= 1 shl 7;  (* yields 128 = 2 pow 7 *)
       shl ( a, 4 );  (* same as `a:= a shl 4' *)

See also
--------

   *Note shr::, *Note Operators::.


File: gpc.info,  Node: shr,  Next: sin,  Prev: shl,  Up: Reference

shr
===

Syntax
------

       Operator shr ( operand1, operand2: INTEGER TYPE ) = result: INTEGER TYPE;
   or
       Procedure shr ( Var operand1: INTEGER TYPE; operand2: INTEGER TYPE );

Description
-----------

   In GNU Pascal, `shr' has two built-in meanings:

  1. Bitwise shift right of an integer-type expression by another
     integer value.  The result is of the type of the first operand.

  2. Use as a "procedure":  `operand1' is shifted right by `operand2';
     the result is stored in `operand1'.


Standards
---------

   ISO Pascal does not define the bitwise `shr' operator; Borland
Pascal and Delphi do.

   Unlike the Borland compilers, GNU Pascal cares about the signedness
of the first operand:  If a signed integer with a negative value is
shifted right, "one" bits are filled in from the left.

   Use of `shr' as a "procedure" is a GNU extension.

Example
-------

       Var
         a: Integer;
     
       ...
     
       a:= 1024 shr 4;  (* yields 64 *)
       a:= -127 shr 4;  (* yields -7 *)
       shr ( a, 2 );  (* same as `a:= a shr 2' *)

See also
--------

   *Note shl::, *Note Operators::.


File: gpc.info,  Node: sin,  Next: SizeOf,  Prev: shr,  Up: Reference

sin
===

   (Under construction.)

Syntax
------

       Function sin ( x: Real ): Real;
   or
       Function sin ( z: Complex ): Complex;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: SizeOf,  Next: SmallInt,  Prev: sin,  Up: Reference

SizeOf
======

Syntax
------

       Function SizeOf ( Var x ): Integer;

Description
-----------

   Returns the size of a type or variable in bytes.

Standards
---------

   ISO Pascal does not define `SizeOf'; UCSD and Borland Pascal do.

Example
-------

       Var
         a: Integer;
         b: array [ 1..8 ] of Char;
     
       ...
     
       writeln ( SizeOf ( a ) );  (* Size of an `Integer'; usually 4 bytes. *)
       writeln ( SizeOf ( b ) );  (* Size of eight `Char's; usually 8 bytes. *)

See also
--------

   *Note BitSizeOf::, *Note AlignOf::, *Note TypeOf::.


File: gpc.info,  Node: SmallInt,  Next: sqr,  Prev: SizeOf,  Up: Reference

SmallInt
========

Description
-----------

   `SmallInt' is a signed integer type which is not larger than
`Integer'.  On most platforms it is 16 bits wide and thus has a range
of `-32768..32767'.  It is the same as `ShortInt' (see *Note
ShortInt::).

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `SmallInt'.  (However see *Note Subrange
types::.)

   `SmallInt' also appears in Delphi 2.0.  This compatibility is the
reason why GPC supports the synonym `SmallInt' for `ShortInt'.

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: sqr,  Next: sqrt,  Prev: SmallInt,  Up: Reference

sqr
===

Syntax
------

       Function sqr ( i: INTEGER TYPE ): INTEGER TYPE;
   or
       Function sqr ( x: REAL TYPE ): REAL TYPE;
   or
       Function sqr ( z: COMPLEX TYPE ): COMPLEX TYPE;

Description
-----------

   Returns the square of the argument:

       Function sqr ( x: SOME TYPE ): SOME TYPE;
     
       begin (* sqr *)
         sqr:= x * x;  (* or: x pow 2 *)
       end (* sqr *);

Standards
---------

   The function `sqr' is defined in ISO-7185 Standard Pascal; its
application to complex values is defined in ISO-10206 Extended Pascal.

Example
-------

       Program TestSqr;
     
       Var
         i: Complex;
     
       begin
         i:= cmplx ( 0, 1 );
         writeln ( Re ( sqr ( i ) : 0 : 3 );
         (* yields -1.000 *)
       end.

See also
--------

   *Note pow::, *Note sqrt::, *Note abs::, *Note Operators::.


File: gpc.info,  Node: sqrt,  Next: StandardError,  Prev: sqr,  Up: Reference

sqrt
====

Syntax
------

       Function sqrt ( x: REAL TYPE ): REAL TYPE;
   or
       Function sqrt ( z: COMPLEX TYPE ): COMPLEX TYPE;

Description
-----------

   Returns the positive square root of the argument.

   For real arguments, it is an error if the argument is negative.

   For complex arguments, `sqrt' returns the principal value of the
root of the argument, i.e. the root with positive real part, or, if the
real part is zero, that one with positive imaginary part.

Standards
---------

   The function `sqrt' is defined in ISO-7185 Standard Pascal; its
application to complex values is defined in ISO-10206 Extended Pascal.

Example
-------

       Program TestSqrt;
     
       Var
         m1: Complex;
     
       begin
         m1:= cmplx ( -1, 0 );  (* -1 *)
         writeln ( Re ( sqrt ( m1 ) ) : 6 : 3, Im ( sqrt ( m1 ) ) : 6 : 3 );
         (* yields 1.000 -1.000, i.e. the imaginary unit, i *)
       end.

See also
--------

   *Note pow::, *Note sqr::, *Note Operators::.


File: gpc.info,  Node: StandardError,  Next: StandardInput,  Prev: sqrt,  Up: Reference

StandardError
=============

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: StandardInput,  Next: StandardOutput,  Prev: StandardError,  Up: Reference

StandardInput
=============

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: StandardOutput,  Next: static,  Prev: StandardInput,  Up: Reference

StandardOutput
==============

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: static,  Next: StdErr,  Prev: StandardOutput,  Up: Reference

static
======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: StdErr,  Next: Str,  Prev: static,  Up: Reference

StdErr
======

   (Under construction.)

Syntax
------

       Var
         StdErr: Text;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Str,  Next: StrPCopy,  Prev: StdErr,  Up: Reference

Str
===

   (Under construction.)

Syntax
------

       Procedure Str ( x: INTEGER OR REAL; Var Dest: String );
   or
       Procedure Str ( x: INTEGER OR REAL : FIELD WIDTH; Var Dest: String );
   or
       Procedure Str ( x: Real : FIELD WIDTH : PRECISION; Var Dest: String );
   or
       Procedure Str ( REPEATED CONSTRUCTS AS DESCRIBED ABOVE; Var Dest: String );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: StrPCopy,  Next: String,  Prev: Str,  Up: Reference

StrPCopy
========

   (Under construction.)

Syntax
------

       Function StrPCopy ( Dest: CString; Const Source: String ): CString;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: String,  Next: String2CString,  Prev: StrPCopy,  Up: Reference

String
======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: String2CString,  Next: SubStr,  Prev: String,  Up: Reference

String2CString
==============

   (Under construction.)

Syntax
------

       Function String2CString ( Const S: String ): CString;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: SubStr,  Next: succ,  Prev: String2CString,  Up: Reference

SubStr
======

Syntax
------

       Function SubStr ( S: String; FirstChar: Integer ): String;
   or
       Function SubStr ( S: String; FirstChar, Count: Integer ): String;

Description
-----------

   `SubStr' returns a sub-string of S starting with the character at
position FIRSTCHAR.  If COUNT is given, such many characters will be
copied into the sub-string.  If COUNT is omitted, the sub-string will
will range to the end of S.

   If `Count' is too large for the sub-string to fit in S or if
`FirstChar' exceeds the length of S, `SubStr' triggers a runtime error.
(For a function returning the empty string instead, see *Note Copy::.)

Standards
---------

   `SubStr' is defined in ISO 10206 Extended Pascal and does not appear
in Standard Pascal.

Example
-------

       Var
         S: String ( 42 );
     
       [...]
     
       S:= 'Hello';
       writeln ( SubStr ( S, 2, 3 ) );   (* yields "ell" *)
       writeln ( SubStr ( S, 3 ) );      (* yields "llo" *)
       writeln ( SubStr ( S, 4, 7 ) );   (* yields a runtime error *)
       writeln ( SubStr ( S, 42 ) );     (* yields a runtime error *)

See also
--------

   *Note Copy::, String slice access.


File: gpc.info,  Node: succ,  Next: Text,  Prev: SubStr,  Up: Reference

succ
====

Syntax
------

       Function succ ( i: ORDINAL TYPE ): ORDINAL TYPE;
   or
       Function succ ( i: ORDINAL TYPE; j: Integer ): ORDINAL TYPE;

   or, with extended syntax (`--extended-syntax' or `(*$X+*)'),

       Function succ ( p: POINTER TYPE ): POINTER TYPE;
   or
       Function succ ( p: POINTER TYPE; j: Integer ): POINTER TYPE;

Description
-----------

   Returns the successor of the ORDINAL TYPE value `i', or, if the
second argument `j' is given, its `j'th successor.  For integer values
`i', this is `i + 1' (or `i + j').  (No, `succ' does *not* work faster
than plain addition.  Both are optimized to a single machine
instruction or even expanded by the compiler, if possible.)

   If extended syntax is on, the argument may also be a pointer value.
In this case, the address is incremented by the size of the variable
pointed to, or, if `j' is given, by `j' times the size of the variable
pointed to.  If `p' points to an element of an array, the returned
pointer will point to the (`j'th) next element of the array.

Standards
---------

   The `succ' function is defined in ISO-7185 Standard Pascal.  The
optional second parameter is defined in ISO-10206 Extended Pascal.
Application of `succ' to pointers is defined in Borland Pascal.  The
combination of the second argument with application to pointers is a
GNU extension.

Example
-------

       Program SuccTest;
     
       Type
         Metasyntactical = ( foo, bar, baz );
     
       Var
         m: Metasyntactical;
         c: Char;
         a: array [ 1..7 ] of Integer;
         p: ^Integer;
     
       begin
         m:= succ ( foo );     (* bar *)
         c:= succ ( 'A', 4 );  (* 'E' *)
         a [ 1 ]:= 42;
         a [ 2 ]:= succ ( a [ 1 ] );     (* 43 *)
         a [ 5 ]:= succ ( a [ 2 ], 7 );  (* 50 *)
         (*$X+*)
         p:= @a [ 1 ];
         p:= succ ( p );     (* now points to `a [ 2 ]' *)
         p:= succ ( p, 3 );  (* now points to `a [ 5 ]' *)
       end.

See also
--------

   *Note pred::, *Note inc::, *Note Pointer arithmetics::.


File: gpc.info,  Node: Text,  Next: then,  Prev: succ,  Up: Reference

Text
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: then,  Next: Time,  Prev: Text,  Up: Reference

then
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Time,  Next: TimeStamp,  Prev: then,  Up: Reference

Time
====

   (Under construction.)

Syntax
------

       Function Time ( T: TimeStamp ):
           packed array [ 1..TIME LENGTH ] of Char;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: TimeStamp,  Next: to,  Prev: Time,  Up: Reference

TimeStamp
=========

   (Under construction.)

Syntax
------

       Type
         TimeStamp = record
           DateValid, TimeValid: Boolean;
           Year: Integer;
           Month: 1..12;
           Day: 1..31;
           Hour: 0..23;
           Minute, Second: 0..59;
           MicroSecond: Integer;
         end (* TimeStamp *);

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: to,  Next: to begin,  Prev: TimeStamp,  Up: Reference

to
==

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: to begin,  Next: to end,  Prev: to,  Up: Reference

to begin
========

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: to end,  Next: Trim,  Prev: to begin,  Up: Reference

to end
======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Trim,  Next: true,  Prev: to end,  Up: Reference

Trim
====

   (Under construction.)

Syntax
------

       Function Trim ( S: String ): String;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: true,  Next: trunc,  Prev: Trim,  Up: Reference

true
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: trunc,  Next: Truncate,  Prev: true,  Up: Reference

trunc
=====

   (Under construction.)

Syntax
------

       Function trunc ( x: Real ): Integer;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Truncate,  Next: Type,  Prev: trunc,  Up: Reference

Truncate
========

   (Under construction.)

Syntax
------

       Procedure Truncate ( Var F: ANY FILE );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Type,  Next: TypeOf,  Prev: Truncate,  Up: Reference

Type
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: TypeOf,  Next: UnBind,  Prev: Type,  Up: Reference

TypeOf
======

Syntax
------

       Function TypeOf ( Var x ): Pointer;

Description
-----------

   Returns a pointer to the VMT of an *object* type or variable.  This
pointer can be used to identify the type of an object.

Standards
---------

   ISO Pascal does not define `TypeOf', Borland Pascal does.

Example
-------

       Type
         fooPtr = ^foo;
         barPtr = ^bar;
     
         foo = object        (* Has a VMT, though it doesn't *)
           x: Integer;       (* contain virtual methods.     *)
           Constructor Init;
         end (* foo *);
     
         bar = object ( foo )
           y: Integer;
         end (* bar *);
     
       Var
         MyFoo: fooPtr;
     
       [...]
     
       MyFoo:= New ( barPtr, Init );
     
       if TypeOf ( MyFoo^ ) = TypeOf ( bar ) then  (* true *)
         writeln ( 'OK' );

See also
--------

   *Note BitSizeOf::, *Note AlignOf::, *Note TypeOf::, *Note SetType::,
*Note OOP::.


File: gpc.info,  Node: UnBind,  Next: Unit,  Prev: TypeOf,  Up: Reference

UnBind
======

   (Under construction.)

Syntax
------

       Procedure UnBind ( Var F: ANY FILE );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Unit,  Next: unpack,  Prev: UnBind,  Up: Reference

Unit
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: unpack,  Next: until,  Prev: Unit,  Up: Reference

unpack
======

   (Under construction.)

Syntax
------

       Procedure unpack ( Source: PACKED ARRAY;
                          Var Dest: UNPACKED ARRAY;
                          FirstElement: INDEX TYPE );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: until,  Next: UpCase,  Prev: unpack,  Up: Reference

until
=====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: UpCase,  Next: update,  Prev: until,  Up: Reference

UpCase
======

   (Under construction.)

Syntax
------

       Function UpCase ( Ch: Char ): Char;

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: update,  Next: uses,  Prev: UpCase,  Up: Reference

update
======

   (Under construction.)

Syntax
------

       Procedure update ( Var F: ANY FILE );
   or
       Procedure update ( Var F: ANY FILE; FileName: String );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: uses,  Next: Val,  Prev: update,  Up: Reference

uses
====

Description
-----------

   The reserved word `uses' in the *import part* of a program makes the
program import an interface.  The syntax is

       Program foo;
     
       uses
         bar1,
         bar2 in 'baz.pas',
         bar3;
     
       [...]

   or, in a Unit,

       Unit Bar3;
     
       Interface
     
       uses
         bar1,
         bar2 in 'baz.pas';
     
       [...]

   The `in' above tells GPC to look for the `Unit' in the specified
file; otherwise the file name is derived from the name of the interface
by adding first `.p', then `.pas'.

   There must be at most one import part in a program.

   In a Unit, there is only one import part in the interface part; GPC
currently does not support a second import part in the implementation
part.

   The imported interface needn't be an UCSD/Borland Pascal Unit, it
may be an interface exported by an Extended Pascal Module as well.

Standards
---------

   ISO Pascal does not define `uses' and Units in general.  UCSD and
Borland Pascal do, but without the `in' extension.  Delphi supports
`uses' like described above.

See also
--------

   *Note Unit::, *Note Module::, *Note import::.


File: gpc.info,  Node: Val,  Next: value,  Prev: uses,  Up: Reference

Val
===

   (Under construction.)

Syntax
------

       Procedure Val ( Const Source: String; Var x: INTEGER OR REAL );
   or
       Procedure Val ( Const Source: String; Var x: INTEGER OR REAL;
                       Var ErrorCode: Integer );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: value,  Next: Var,  Prev: Val,  Up: Reference

value
=====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Var,  Next: virtual,  Prev: value,  Up: Reference

Var
===

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: virtual,  Next: Void,  Prev: Var,  Up: Reference

virtual
=======

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Void,  Next: while,  Prev: virtual,  Up: Reference

Void
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: while,  Next: with,  Prev: Void,  Up: Reference

while
=====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: with,  Next: Word,  Prev: while,  Up: Reference

with
====

   (Under construction.)

Syntax
------

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: Word,  Next: write,  Prev: with,  Up: Reference

Word
====

Description
-----------

   `Word' is the "natural" unsigned integer type in GNU Pascal.  On
most platforms it is 32 bits wide and thus has a range of
`0..4294967295'.  It is the same as *Note Cardinal::, introduced for
compatibility with other Pascal compilers.

   As an extension, GPC allows to use `Word' as a pseudo-schema to
produce types with a specified size in bits; for example

       Type
         Word16 = Cardinal ( 16 );

   defines an unsigned integer type with 16 bits.  The same mechanism
works for `Cardinal' and `Integer', too.

   `Word' in GNU Pascal is compatible to `unsigned int' in GNU C.

   There are lots of other integer types in GPC, see *Note Integer
types::.

Standards
---------

   ISO Pascal does not define `Cardinal'.  (However see *Note Subrange
types::.)

   The `Word' type appears in Borland Pascal and Delphi, too, where it
is a 16-bit unsigned integer type.

See also
--------

   *Note Integer types::, *Note Subrange types::.


File: gpc.info,  Node: write,  Next: writeln,  Prev: Word,  Up: Reference

write
=====

   (Under construction.)

Syntax
------

       Procedure write ( Var F: TYPED FILE; VARIABLE );
   or
       Procedure write ( Var F: Text; VALUES AND FORMAT SPECIFICATIONS );
   or
       Procedure write ( VALUES AND FORMAT SPECIFICATIONS );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: writeln,  Next: WriteStr,  Prev: write,  Up: Reference

writeln
=======

   (Under construction.)

Syntax
------

       Procedure writeln ( Var F: Text; VALUES AND FORMAT SPECIFICATIONS );
   or
       Procedure writeln ( VALUES AND FORMAT SPECIFICATIONS );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: WriteStr,  Next: xor,  Prev: writeln,  Up: Reference

WriteStr
========

   (Under construction.)

Syntax
------

       Procedure WriteStr ( Var Dest: String; VALUES AND FORMAT SPECIFICATIONS );

Description
-----------

Standards
---------

Example
-------

See also
--------


File: gpc.info,  Node: xor,  Prev: WriteStr,  Up: Reference

xor
===

Syntax
------

       Operator xor ( operand1, operand2: Boolean ) = result: Boolean;
   or
       Operator xor ( operand1, operand2: INTEGER TYPE ) = result: INTEGER TYPE;
   or
       Procedure xor ( Var operand1: INTEGER TYPE; operand2: INTEGER TYPE );

Description
-----------

   In GNU Pascal, `xor' has three built-in meanings:

  1. Logical "exclusive or" between two `Boolean'-type expressions.
     The result of the operation is of `Boolean' type.  (Logical `foo
     xor bar' in fact has the same effect as `foo <> bar'.)

  2. Bitwise "exclusive or" between two integer-type expressions.  The
     result is of the common integer type of both expressions.

  3. Use as a "procedure":  `operand1' is "xor"ed bitwise with
     `operand2'; the result is stored in `operand1'.


Standards
---------

   ISO Pascal does not define the `xor' operator; Borland Pascal and
Delphi do.

   Use of `xor' as a "procedure" is a GNU extension.

Example
-------

       Var
         a, b, c: Integer;
     
       ...
     
       if ( a = 0 ) xor ( b = 0 ) then
         c:= 1  (* happens if either `a' or `b' is zero,    *)
                (* but not if both are zero or both nonzero *)
     
       else if a xor b = 0 then  (* bitwise `xor': `a' must be the bitwise *)
         c:= 2                   (* complement of `b' to fullfill this     *)
       else
         xor ( c, a );  (* same as `c:= c xor a' *)

See also
--------

   *Note and::, *Note or::, *Note Operators::.


File: gpc.info,  Node: GPC source,  Next: Keywords,  Prev: Reference,  Up: Top

The GPC Source Reference
************************

     "The Source will be with you.  Always."

   This section tells you how to look up additional information about
the GNU Pascal compiler from its source code.  It replaces chapters
like "syntax diagrams" you probably know from the documentation of
other compilers.

   Proprietary compilers often come with a lot of technical information
about the internals of the compiler.  This is necessary because their
vendors want to avoid to distribute the source of the compiler--which
is always the most definitive source of this technical information.

   With GNU compilers, on the other hand, you are free to get the
source code, look how your compiler works internally, customize it for
your own needs, and to re-distribute it in modified or unmodified form.
You may even take money for this re-distribution.  (For details, see
the GNU General Public License, *Note Copying::.)

   The following subsections are your guide to the GNU Pascal source
code.  If you have further questions, be welcome to ask them at the GNU
Pascal mailing list (see *Note Support::).

   All file paths mentioned in this chapter are relative to the GNU
Pascal source directory, usually a subdirectory `p' of the GCC source.
For instance, `parse.y' means `/usr/local/src/gcc-2.8.1/p/parse.y' (or
whereever you have installed the GCC source on your machine);
`../tree.def' means `/usr/local/src/gcc-2.8.1/tree.def', etc.

* Menu:

* Lexical analyzer::     `gpc-lex.c'--How GPC reads your source.
* Language definition::  `parse.y'--"Syntax diagrams" as "Bison" source.
* Tree nodes::           `../tree.*'--How GPC stores your program internally.
* Parameter passing::    `gpc-typeck.c'--How GPC passes parameters.
* GPI files::            `module.c'--How GPC's precompiled Module/Unit interfaces work.
* AutoMake::             `module.c'--How GPC automatically "makes" a large project.

   (Under construction.)

   For more information, see chapters "Portability" through "Fragments"
in *Note the GCC documentation: (gcc).


File: gpc.info,  Node: Lexical analyzer,  Next: Language definition,  Up: GPC source

GPC's Lexical Analyzer
======================

   The source file `gpc-lex.c' contains the so-called *lexical
analyzer* of the GNU Pascal compiler.  (For those of you who know
`flex':  This file was *not* created using `flex' but is maintained
manually.)  This very-first stage of the compiler is responsible for
reading what you have written and dividing it into *tokens*, the
"atoms" of each computer language.  The source `gpc-lex.c' essentially
contains one large function, `yylex()'.

   Here is, for example, where the real number `3.14' and the subrange
`3..14' are distinguished, and where Borland-style character constants
like `#13' and `^M' are recognized.  This is not always a trivial task,
for example look at the following type declaration:

       Type
         X = ^Y;
         Y = packed array [ ^A..^B ] of Char;
         Z = ^A..^Z;

   If you wish to know how GPC distinguishes the pointer forward
declaration `^Y' and the subrange `^A..^Z', see `gpc-lex.c', function
`yylex()', `case '^':' in the big `switch' statement.

   There are several situation where GPC's lexical analzyer becomes
context-sensitive.  One is described above, another example is the token
`protected', a reserved word in ISO-10206 Extended Pascal, but an
ordinary identifier in ISO-7185 Standard Pascal.  It appears in
parameter lists

       Procedure foo ( protected bar: Integer );

   and says that the parameter `bar' must not be changed inside the
body of the procedure.

   OTOH, if you write a valid ISO-7185 Standard Pascal program, you can
declare a parameter `protected':

       Procedure foo ( protected, bar: Integer );

   Here both standards contradict each other.  GPC solves this problem
by checking explicitly for "protected" in the lexical analyzer:  If a
comma or a colon follows, this is an ordinary identifier, otherwise
it's a reserved word.  Having this, GPC even understands

       Procedure foo ( protected protected: Integer );

   without losing the special meaning of `protected' as a reserved word.

   The responsible code is in `gpc-lex.c'--look out for `PROTECTED'.

   If you ever encouter a bug with the lexical analyzer--now you know
where to hunt for it.


File: gpc.info,  Node: Language definition,  Next: Tree nodes,  Prev: Lexical analyzer,  Up: GPC source

Language Definition: GPC's Parser
=================================

   The file `parse.y' contains the "bison" source code of GNU Pascal's
parser.  This stage of the compilation analyzes and checks the syntax of
your Pascal program, and it generates an intermediate,
language-independent code which is then passed to the GNU back-end.

   The *bison* language essentially is a machine-readable form of the
Backus-Naur Form, the symbolic notation of grammars of computer
languages.  "Syntax diagrams" are a graphical variant of the
Backus-Naur Form.

   For details about the "bison" language, see *Note the Bison
documentation: (bison).  A short overview how to pick up some
information you might need for programming follows.

   Suppose you have forgotten how a variable is declared in Pascal.
After some searching in `parse.y' you have found the following:

       /* variable declaration part */
     
       variable_declaration_part:
                 VAR variable_declaration_list semi
               | VAR semi
                       { error ("missing variable declaration"); }
               ;
     
       variable_declaration_list:
                 variable_declaration
               | variable_declaration_list semi variable_declaration
                       { yyerrok; }
               | error
               | variable_declaration_list error variable_declaration
                       {
     		    error("missing semicolon");
                         yyerrok;
     		  }
               | variable_declaration_list semi error
               ;

   Translated into English, this means: "The variable declaration part
consists of the reserved word `Var' followed by a `variable declaration
list' and a semicolon.  A semicolon immediately following `Var' is an
error.  A `variable declaration list' in turn consists of one or more
`variable declarations', separated by semicolons." (The latter
explanation requires that you understand the recursive nature of the
definition of `variable_declaration_list'.)

   Now we can go on and search for `variable_declaration'.

       variable_declaration:
                 id_list
                       {
                         [...]
                       }
                 enable_caret ':' optional_qualifier_list type_denoter
                 absolute_or_value_specification
                       {
                         [...]
                       }
               ;

   (The `[...]' are placeholders for some C statements which aren't
important for understanding GPC's grammar.)

   From this you can look up that a variable declaration in GNU Pascal
consists of an "id list", followed by "enable_caret" (whatever that
means), a colon, an "optional qualifier list", a "type denoter", and an
"absolute or value specification".  Some of these parts are easy to
understand, the others you can look up from `parse.y'.  Remember that
the reserved word `Var' preceeds all this, and a semicolon follows all
this.

   Now you know the procedure how to get the exact grammar of the GNU
Pascal language from the source.

   The C statements, not shown above, are in some sense the most
important part of the bison source, because they are responsible for
the generation of the intermediate code of the GNU Pascal front-end,
the so-called *tree nodes*.  For instance, the C code in "type denoter"
juggles a while with variables of the type `tree', and finally returns
(assigns to `$$') a so-called *tree list* which contains the information
about the type.  The "variable declaration" gets this tree list (as the
argument `$6') and passes the type information to the C function
`declare_vars()' (declared in `util.c').  This function
`declare_vars()' does the real work of compiling a variable declaration.

   This, the parser, is the place where it becomes Pascal.


File: gpc.info,  Node: Tree nodes,  Next: Parameter passing,  Prev: Language definition,  Up: GPC source

Tree Nodes
==========

   If you want really to understand how the GNU Pascal language
front-end works internally and perhaps want to improve the compiler, it
is important that you understand GPC's internal data structures.

   The data structure used by the language front-end to hold all
information about your Pascal program are the so-called "tree nodes".
(Well, it needn't be Pascal source--tree nodes are language
independent.)  The tree nodes are kind of objects, connected to each
other via pointers.  Since the GNU compiler is written in C and was
created at a time where nobody really thought about object-orientated
programming languages yet, a lot of effort has been taken to create
these "objects" in C.

   Here is an extract from the "object hierarchy".  Omissions are marked
with "..."; nodes in parentheses are "abstract":  They are never
instantiated and aren't really defined.  They only appear here to
clarify the structure of the tree node hierarchy.  The complete list is
in `../tree.def'; additional information can be found in `../tree.h'.

       (tree_node)
       |
       |--- error_mark  (* enables GPC to continue after first error *)
       |
       |--- (identifier)
       |    |
       |    |--- identifier_node
       |    |
       |    \--- op_identifier
       |
       |--- tree_list  (* general-purpose "container object" *)
       |
       |--- tree_vec
       |
       |--- block
       |
       |--- (type)  (* information about types *)
       |    |
       |    |--- void_type
       |    |
       |    |--- integer_type
       |   ...
       |    |
       |    |--- record_type
       |    |
       |    |--- function_type
       |    |
       |    \--- lang_type  (* for language-specific extensions *)
       |
       |--- integer_cst  (* an integer constant *)
       |
       |--- real_cst
       |
       |--- string_cst
       |
       |--- complex_cst
       |
       |--- (declaration)
       |    |
       |    |--- function_decl
       |   ...
       |    |
       |    |--- type_decl
       |    |
       |    \--- var_decl
       |
       |--- (reference)
       |    |
       |    |--- component_ref
       |   ...
       |    |
       |    \--- array_ref
       |
       |--- constructor
       |
       \--- (expression)
            |
            |--- modify_expr  (* assignment *)
            |
            |--- plus_expr  (* addition *)
           ...
            |
            |--- call_expr  (* procedure/function call *)
            |
            |--- goto_expr
            |
            \--- loop_expr  (* for all loops *)

   Most of these tree nodes--struct variables in fact--contain pointers
to other tree nodes.  A `tree_list' for instance has a `tree_value' and
a `tree_purpose' slot which can contain arbitrary data; a third pointer
`tree_chain' points to the next `tree_list' node and thus allows us to
create linked lists of tree nodes.

   One example:  When GPC reads the list of identifiers in a variable
declaration

       Var
         foo, bar, baz: Integer;

   the parser creates a chain of `tree_list's whose `tree_value's hold
`identifier_node's for the identifiers `foo', `bar', and `baz'.  The
function `declare_vars()' (declared in `util.c') gets this tree list as
a parameter, does some magic, and finally passes a chain of `var_decl'
nodes to the back-end.

   The `var_decl' nodes in turn have a pointer `tree_type' which holds
a `_type' node--an `integer_type' node in the example above.  Having
this, GPC can do type-checking when a variable is referenced.

   For another example, let's look at the following statement:

       baz:= foo + bar;

   Here the parser creates a `modify_expr' tree node.  This node has two
pointers, `tree_operand[0]' which holds a representation of `baz', a
`var_decl' node, and `tree_operand[1]' which holds a representation of
the sum `foo + bar'.  The sum in turn is represented as a `plus_expr'
tree node whose `tree_operand[0]' is the `var_decl' node `foo', and
whose `tree_operand[1]' is the `var_decl' node `bar'.  Passing this
(the `modify_expr' node) to the back-end results in assembler code for
the assignment.

   If you want to have a closer look at these tree nodes, write a line
`(*$debug-tree="Foobar"*)' into your program with `FooBar' being some
identifier in your program.  (Note the capitalization of the first
character in the internal representation.)  This tells GPC to output the
`identifier_local_value' tree node--the meaning of this identifier--to
the standard error device in human-readable form.

   While hacking and debugging GPC, you will also wish to have a look
at these tree nodes in other cases.  Use the `debug_tree()' function to
do so.  (In fact `(*$debug-tree="Foobar"*)' does nothing else than to
`debug_tree()' the `identifier_local_value' of the `Foobar' identifier
node.)


File: gpc.info,  Node: Parameter passing,  Next: GPI files,  Prev: Tree nodes,  Up: GPC source

Parameter Passing
=================

   GPC supports a lot of funny things in parameter lists:  `protected'
and `const' parameters, strings with specified or unspecified length,
conformant arrays, objects as `Var' parameters, etc.  All this requires
sophisticated type-checking; the responsible function is
`convert_arguments()' in the source file `gpc-typeck.c'.  Every detail
can be looked up from there.

   Some short notes about the most interesting cases follow.

*Conformant arrays:*
     First, the array bounds are passed (an even number of parameters
     of an ordinal type), then the address of the array itself.

*Procedural parameters:*
     These need special care because a function passed as a parameter
     can be confused with a call to the function whose result is then
     passed as a parameter.  See also the functions
     `maybe_call_function()' and `probably_call_function()' in `util.c'.

*Chars:*
     According to ISO-10206 Extended Pascal, formal char parameters
     accept string values.  GPC does the necessary conversion
     implicitly.  The empty string produces a space.

*Strings and schemata:*
     Value parameter strings and schemata of known size are really
     passed by value.  Value parameter strings and schemata of unknown
     size are passed by reference, and GPC creates temporary variable
     to hold a copy of the string.

*`Const' parameters:*
     If a constant value is passed to a `Const' parameter, GPC assigns
     the value to a temporary variable whose address is passed.

*Typeless parameters:*
     These are denoted by `Var foo' or `Var foo: Void' and are
     compatible to C's `void *' parameters; the size of such entities
     is *not* passed.  Maybe we will change this in the future and pass
     the size for `Var foo' parameters whereas `Var foo: Void' will
     remain compatible to C.

*`CString' parameters:*
     GPC implicitly converts any string value such that the address of
     the actual string data is passed.  However, GPC does not
     implicitly append a `chr ( 0 )' terminator, except for string
     constants.


File: gpc.info,  Node: GPI files,  Next: AutoMake,  Prev: Parameter passing,  Up: GPC source

GPI files--GNU Pascal Interfaces
================================

   This section documents the mechanism how GPC transfers information
from the exporting Modules and Units to the Program, Module or Unit
which imports (uses) the information.

   A GPI file contains a precompiled GNU Pascal Interface.
"Precompiled" means in this context that the Interface already has been
parsed (i.e. the front-end has done its work), but that no assembler
output has been produced yet.

   The GPI file format is an implementation-dependent (but not *too*
implementation-dependent ;-) file format for storing GNU Pascal
Interfaces to be exported--Extended Pascal and PXSC module interfaces
as well as interface parts of Borland Pascal Units compiled with GNU
Pascal.

   To see what information is stored in or loaded from a GPI file, run
GPC with an additional command-line option `--debug-gpi'.  Then, GPC
will write a human-readable version of what is being stored/loaded to
the standard error device.  (See also: *Note Tree nodes::.)

   While parsing an Interface, GPC stores the names of exported objects
in tree lists--in `gpc-parse.y', the bison (yacc) source of GPC's
parser, search for `handle_autoexport'.  At the end of the Interface,
everything is stored in one or more GPI files.  This is called in
`gpc-parse.y'--search for `create_gpi_files'.  (See also: *Note
Language definition::, for an introduction to `gpc-parse.y')

   Everything else is done in gpc-module.c.  Here you can find the
source of `create_gpi_files()' which documents the file format:  First,
a header of 33 bytes containing the string `GNU Pascal Module/Unit
Interface\n' is stored, then the name of the primary source file of the
module as a string, then the name of the exported interface as a tree
node (see below), after that all exported names in the order as they
were stored while parsing.

   The names and the objects (i.e. constants, data types, variables and
functions) they refer to are internally represented as so-called *tree
nodes* as defined in the files `../tree.h' and `../tree.def' from the
GNU compiler back-end.  (See also: *Note Tree nodes::.)  The names are
stored as `identifier_node's, their meanings as
`identifier_global_value's of these nodes.  The main problem when
storing tree nodes is that they form a complicated tree in memory with
a lot of circular references making it hard to decide which information
must be stored and which mustn't.

   The functions `load_tree()' and `store_tree' load/store a tree node
with the contents of all its contained pointers in a GPI file.

   Each tree node has a `tree_code' indicating what kind of information
it contains.  Each different tree node must be stored in a different
way.  See the source of `load_tree()' and `store_tree()' for details.

   Most tree nodes contain pointers to other tree nodes; therefore
`load_tree()' and `store_tree()' are recursive functions.  The
`--debug-gpi' debugging informations contains the recursion level in
parantheses, e.g. `loaded (2):' means that the loaded information was
requested by a pointer contained in a tree node requested by a pointer
contained in a tree node representing an exported symbol.

   Since this recursion can be circular (think of a record containing a
pointer to a record of the same type), we must resolve references to
tree nodes which already have been loaded.  For this reason, all nodes
are recorded in a hash buffer--see `gpi-hash.c'.

   There are some special tree_nodes (e.g. `integer_type_node' or
`NULL_TREE') which are used very often.  They have been assigned
(normally invalid) unique `tree_code's, so they can be stored in a
single byte.

   That's it.  Now you should be able to "read" GPI files using GPC's
`--debug-gpi' option.  If you encounter a case where the loaded
information differs too much from the stored information, you have
found a bug--congratulations!  What "too much" means, depends on the
object being stored in or loaded from the GPI file.  Remind that the
order things are loaded from a GPI file is the *reversed* order things
are stored when considering *different* recursion levels, but the
*same* order when considering ths *same* recursion level.


File: gpc.info,  Node: AutoMake,  Prev: GPI files,  Up: GPC source

GPC's AutoMake Mechanism--How it Works
======================================

   When a Program/Module/Unit imports (uses) an Interface, GPC searches
for the GPI file (see *Note GPI files::) derived from the name of the
Interface.

   Case 1:  A GPI file was found.

   Each GPI file contains the name of the primary source file (normally
a `.pas' or `.p' file) of the Module/Unit, and the names of all
interfaces imported.  GPC reads this information and invokes itself
with a command like

       gpc foo.pas -M -o foo.d

   This means: preprocess the file, and write down the name of the
object file and those of all its source files in `foo.d'.  GPC reads
`foo.d' and looks if the object file exists and if the source was
modified since the creation of the object file and the gpi file.  If
so, GPC calls itself again to compile the primary source file.  When
everything is done, the `.d' file is removed.  If there was no need to
recompile, all interfaces imported by the Module/Unit are processed in
the same way as this one.

   Case 2:  No GPI file was found.

   In this case, GPC derives the name of the source file from that of
the Interface by trying first `interface.p', then `interface.pas'.
This will almost always work with Borland Pascal Units, almost never
with Extended Pascal Modules.  With Extended Pascal, compile the Module
once manually in order to produce a GPI file.

   All this is done by the function `gpi_open()' which uses some
auxiliary functions such as `module_must_be_recompiled()' and
`compile_module()'.

   Each time an object file is compiled or recognized as being
up-to-date, its name is stored in a temporary file with the same base
name as all the other temporary files used by GPC but the extension
`.gpc'.  When the top-level `gpc' is invoked (which calls `gpc1' later
on), it passes the name of this temporary file as an additional command
line parameter to `gpc1'.  After compilation has been completed, the
top-level `gpc' reads the temporary file and adds the new object files
to the arguments passed to the linker.

   The additional command `--amtmpfile' (not to be specified by the
user!) is passed to child GPC processes, so all compiles use the same
temporary file.

   The source for this is merely in `gpc-module.c', but there are also
some hacks in `gpc.c', additional command line options in
`lang-options.h' and `gpc-decl.c', and `gpc-defs.h' contains
declarations for the functions and global variables.

