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: Intel 960 Options,  Next: DEC Alpha Options,  Prev: HPPA Options,  Up: Submodel Options

Intel 960 Options
-----------------

   These `-m' options are defined for the Intel 960 implementations:

`-mCPU TYPE'
     Assume the defaults for the machine type CPU TYPE for some of the
     other options, including instruction scheduling, floating point
     support, and addressing modes.  The choices for CPU TYPE are `ka',
     `kb', `mc', `ca', `cf', `sa', and `sb'.  The default is `kb'.

`-mnumerics'
`-msoft-float'
     The `-mnumerics' option indicates that the processor does support
     floating-point instructions.  The `-msoft-float' option indicates
     that floating-point support should not be assumed.

`-mleaf-procedures'
`-mno-leaf-procedures'
     Do (or do not) attempt to alter leaf procedures to be callable
     with the `bal' instruction as well as `call'.  This will result in
     more efficient code for explicit calls when the `bal' instruction
     can be substituted by the assembler or linker, but less efficient
     code in other cases, such as calls via function pointers, or using
     a linker that doesn't support this optimization.

`-mtail-call'
`-mno-tail-call'
     Do (or do not) make additional attempts (beyond those of the
     machine-independent portions of the compiler) to optimize
     tail-recursive calls into branches.  You may not want to do this
     because the detection of cases where this is not valid is not
     totally complete.  The default is `-mno-tail-call'.

`-mcomplex-addr'
`-mno-complex-addr'
     Assume (or do not assume) that the use of a complex addressing
     mode is a win on this implementation of the i960.  Complex
     addressing modes may not be worthwhile on the K-series, but they
     definitely are on the C-series.  The default is currently
     `-mcomplex-addr' for all processors except the CB and CC.

`-mcode-align'
`-mno-code-align'
     Align code to 8-byte boundaries for faster fetching (or don't
     bother).  Currently turned on by default for C-series
     implementations only.

`-mic-compat'
`-mic2.0-compat'
`-mic3.0-compat'
     Enable compatibility with iC960 v2.0 or v3.0.

`-masm-compat'
`-mintel-asm'
     Enable compatibility with the iC960 assembler.

`-mstrict-align'
`-mno-strict-align'
     Do not permit (do permit) unaligned accesses.

`-mold-align'
     Enable structure-alignment compatibility with Intel's gcc release
     version 1.3 (based on gcc 1.37).  Currently this is buggy in that
     `#pragma align 1' is always assumed as well, and cannot be turned
     off.


File: gpc.info,  Node: DEC Alpha Options,  Next: Clipper Options,  Prev: Intel 960 Options,  Up: Submodel Options

DEC Alpha Options
-----------------

   These `-m' options are defined for the DEC Alpha implementations:

`-mno-soft-float'
`-msoft-float'
     Use (do not use) the hardware floating-point instructions for
     floating-point operations.  When `-msoft-float' is specified,
     functions in `libgcc1.c' will be used to perform floating-point
     operations.  Unless they are replaced by routines that emulate the
     floating-point operations, or compiled in such a way as to call
     such emulations routines, these routines will issue floating-point
     operations.   If you are compiling for an Alpha without
     floating-point operations, you must ensure that the library is
     built so as not to call them.

     Note that Alpha implementations without floating-point operations
     are required to have floating-point registers.

`-mfp-reg'
`-mno-fp-regs'
     Generate code that uses (does not use) the floating-point register
     set.  `-mno-fp-regs' implies `-msoft-float'.  If the floating-point
     register set is not used, floating point operands are passed in
     integer registers as if they were integers and floating-point
     results are passed in $0 instead of $f0.  This is a non-standard
     calling sequence, so any function with a floating-point argument
     or return value called by code compiled with `-mno-fp-regs' must
     also be compiled with that option.

     A typical use of this option is building a kernel that does not
     use, and hence need not save and restore, any floating-point
     registers.


File: gpc.info,  Node: Clipper Options,  Next: H8/300 Options,  Prev: DEC Alpha Options,  Up: Submodel Options

Clipper Options
---------------

   These `-m' options are defined for the Clipper implementations:

`-mc300'
     Produce code for a C300 Clipper processor. This is the default.

`-mc400'
     Produce code for a C400 Clipper processor i.e. use floating point
     registers f8..f15.


File: gpc.info,  Node: H8/300 Options,  Next: System V Options,  Prev: Clipper Options,  Up: Submodel Options

H8/300 Options
--------------

   These `-m' options are defined for the H8/300 implementations:

`-mrelax'
     Shorten some address references at link time, when possible; uses
     the linker option `-relax'.  *Note `ld' and the H8/300:
     (ld.info)H8/300, for a fuller description.

`-mh'
     Generate code for the H8/300H.


File: gpc.info,  Node: System V Options,  Prev: H8/300 Options,  Up: Submodel Options

Options for System V
--------------------

   These additional options are available on System V Release 4 for
compatibility with other compilers on those systems:

`-Qy'
     Identify the versions of each tool used by the compiler, in a
     `.ident' assembler directive in the output.

`-Qn'
     Refrain from adding `.ident' directives to the output file (this is
     the default).

`-YP,DIRS'
     Search the directories DIRS, and no others, for libraries
     specified with `-l'.

`-Ym,DIR'
     Look in the directory DIR to find the M4 preprocessor.  The
     assembler uses this option.


File: gpc.info,  Node: Environment Variables,  Prev: Submodel Options,  Up: Invoking GPC

Environment Variables Affecting GNU Pascal
==========================================

   This section describes several environment variables that affect how
GNU CC operates.  They work by specifying directories or prefixes to use
when searching for various kinds of files.

   Note that you can also specify places to search using options such as
`-B', `-I' and `-L' (*note Directory Options::.).  These take
precedence over places specified using environment variables, which in
turn take precedence over those specified by the configuration of GNU
CC.  *Note Driver: (gcc)Driver.

`TMPDIR'
     If `TMPDIR' is set, it specifies the directory to use for temporary
     files.  GNU Pascal uses temporary files to hold the output of one
     stage of compilation which is to be used as input to the next
     stage: for example, the output of the preprocessor, which is the
     input to the compiler proper.

`GPC_EXEC_PREFIX'
     If `GPC_EXEC_PREFIX' is set, it specifies a prefix to use in the
     names of the subprograms executed by the compiler.  No slash is
     added when this prefix is combined with the name of a subprogram,
     but you can specify a prefix that ends with a slash if you wish.

     If GNU Pascal cannot find the subprogram using the specified
     prefix, it tries looking in the usual places for the subprogram.

     The default value of `GPC_EXEC_PREFIX' is `PREFIX/lib/gcc-lib/'
     where PREFIX is the value of `prefix' when you ran the `configure'
     script.

     Other prefixes specified with `-B' take precedence over this
     prefix.

     This prefix is also used for finding files such as `crt0.o' that
     are used for linking.

     In addition, the prefix is used in an unusual way in finding the
     directories to search for header files.  For each of the standard
     directories whose name normally begins with
     `/usr/local/lib/gcc-lib' (more precisely, with the value of
     `GPC_INCLUDE_DIR'), GNU Pascal tries replacing that beginning with
     the specified prefix to produce an alternate directory name.
     Thus, with `-Bfoo/', GNU Pascal will search `foo/bar' where it
     would normally search `/usr/local/lib/bar'.  These alternate
     directories are searched first; the standard directories come next.

`COMPILER_PATH'
     The value of `COMPILER_PATH' is a colon-separated list of
     directories, much like `PATH'.  GNU Pascal tries the directories
     thus specified when searching for subprograms, if it can't find the
     subprograms using `GPC_EXEC_PREFIX'.

`LIBRARY_PATH'
     The value of `LIBRARY_PATH' is a colon-separated list of
     directories, much like `PATH'.  When configured as a native
     compiler, GNU Pascal tries the directories thus specified when
     searching for special linker files, if it can't find them using
     `GPC_EXEC_PREFIX'.  Linking using GNU Pascal also uses these
     directories when searching for ordinary libraries for the `-l'
     option (but directories specified with `-L' come first).

`C_INCLUDE_PATH'
`CPLUS_INCLUDE_PATH'
`OBJC_INCLUDE_PATH'
     These environment variables pertain to particular languages.  Each
     variable's value is a colon-separated list of directories, much
     like `PATH'.  When GNU Pascal searches for header files, it tries
     the directories listed in the variable for the language you are
     using, after the directories specified with `-I' but before the
     standard header file directories.

`DEPENDENCIES_OUTPUT'
     If this variable is set, its value specifies how to output
     dependencies for Make based on the header files processed by the
     compiler.  This output looks much like the output from the `-M'
     option (*note Preprocessor Options::.), but it goes to a separate
     file, and is in addition to the usual results of compilation.

     The value of `DEPENDENCIES_OUTPUT' can be just a file name, in
     which case the Make rules are written to that file, guessing the
     target name from the source file name.  Or the value can have the
     form `FILE TARGET', in which case the rules are written to file
     FILE using TARGET as the target name.


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

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

   *This chapter is under development, so don't be too excited about the
paragraph below!*

   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::   How a GNU Pascal source file looks like.
* Data types::          Standard and non-standard data types.
* Operators::           Built-in and user-definable operators.
* Schemata::            Using Extended Pascal's "schema types".
* Pointer arithmetics:: How pointer arithmetics can be applied to
                        speed up your program.
* Type casts::          Explicit and emulated type casting in GPC.
* OOP::                 How object-orientated programming is implemented.
* Other languages::     How to share libraries with other languages.
* Run time library::    Pascal declarations for GPC's run time library.


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:

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

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

     Unit Foo;
     
     Interface
     
     Procedure Hello;
     
     Implementation
     
     Procedure Hello;
     
     begin (* Hello *)
       writeln ( 'Hello, world!' );
     end (* Hello *);
     
     end.
     
     
     Program Bar;
     
     uses
       Foo;
     
     begin
       Hello;
     end.


File: gpc.info,  Node: Programs,  Next: Modules,  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.

   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.  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 constant, type, variable, procedure,
and function declarations in free order.

   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: Units,  Prev: Modules,  Up: Source structures

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 `.pas' or `.p' 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::, *Note to end::.

   Note that GPC does *not* check whether all interface declarations are
resolved in the same Unit.  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.


File: gpc.info,  Node: Modules,  Next: Units,  Prev: Programs,  Up: Source structures

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

   (Under construction.  If you are familiar with Extended Pascal
Modules, please help!)


File: gpc.info,  Node: Data types,  Next: Operators,  Prev: Source structures,  Up: Programming

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

* Menu:

* Integer types::    GPC has *lots of* built-in Integer types
* Subrange types::   Packed and non-packed subranges
* endianness::       How integer types are stored on different machines
* alignment::        How variables are placed in memory


File: gpc.info,  Node: Integer types,  Next: Subrange 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

"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 Intel X86 processor operations with
`Integer' usually work faster than operations with shorter integer
types like `ShortInt' or `ByteInt' (see below).


File: gpc.info,  Node: Main branch integer types,  Next: Integer types with specified size,  Prev: Natural integer types,  Up: Integer types

"Main Branch" Integer Types
...........................

   `Integer', `Cardinal', and `Word' define the three "main branches"
of GPC's integer types.  You won't always be able to deal with the
natural size; sometimes something smaller or longer will be needed.
Especially when interfacing with libraries written in other languages
such as C, you will need equivalents for their integer types.

   The following variants of `Integer', `Cardinal' and `Word' are
guaranteed to be compatible to the integer types of GNU C.  The sizes,
however, are *not* guaranteed.  They are just typical values currently
used on most platforms, but they may be actually shorter or increase in
the future.

     (signed)        (unsigned)         GNU C equivalent   typical size (bits)
     
     ByteInt    ByteCard    Byte        [un]signed char              8
     ShortInt   ShortCard   ShortWord   [unsigned] short int        16
     Integer    Cardinal    Word        [unsigned] int              32
     MedInt     MedCard     MedWord     [unsinged] long int         32
     LongInt    LongCard    LongWord    [unsinged] long long int    64

   Since we don't know whether `LongInt' will always remain the
"longest" integer type available--maybe GNU C will get `long long long
int', one day, which we will support as `LongLongInt'--we have added
the synonym `LongestInt' for the longest available singed integer type,
and the same holds for `LongestCard' and `LongestWord'.


File: gpc.info,  Node: Integer types with specified size,  Next: Integer types and compatibility,  Prev: Main branch integer types,  Up: Integer types

Integer Types with Specified Size
.................................

   In some situations you will need an integer type of a well-defined
size.  For this purpose, GNU Pascal provides tree families of signed
and unsinged integer types.  The type

       Integer ( 42 )

   is guaranteed to have a precision of 42 bits.  In a realistic
context, you will most often give a power of two as the number of bits,
and the machine you will need it on will support variables of that
size.  If this is the case, the specified precision will simultaneously
be the amount of storage needed for variables of this type.

   In short:  If you want to be sure that you have a signed integer
with 32 bits width, write `Integer ( 32 )', not just `Integer' which
might be bigger.  The same works with `Cardinal' and `Word' if you need
unsigned integer types of well-known size.


File: gpc.info,  Node: Integer types and compatibility,  Next: Summary of integer types,  Prev: Integer types with specified size,  Up: Integer types

Compatibility to other Pascal compilers
.......................................

   If you care about ISO compliance, *only* use `Integer' and subranges
of `Integer'.

   Some of GPC's non-ISO integer types exist in Borland Pascal, too:
`Byte', `ShortInt', `Word', and `LongInt'.  The sizes of these types,
however, are not the same as in Borland Pascal.  Even for `Byte' this
is not guaranteed (while probable, though).

   When designing GNU Pascal, we thought about compatibility to Borland
Pascal.  Since GNU Pascal is (at least) a 32-bit compiler, `Integer'
*must* have (at least) 32 bits.  But what to do with `Word'?  Same size
as `Integer' (like in BP) or 16 bits (like in BP)?  We decided to make
`Word' the "natural-sized" unsigned integer type, thus making it (at
least) 32 bits wide.  Similarly, we decided to give `LongInt' twice the
size of `Integer' (like in BP) rather than making it 32 bits wide (like
in BP).  So `LongInt' has 64 bits, and `ShortInt' has 16 bits on the
Intel X86 platforms.

   On the other hand, to increase compatibility to Borland Pascal and
Delphi, GPC provides the alias name `Comp' for `LongInt' (64 bits on
Intel X86) and `SmallInt' for `ShortInt' (16 bits on Intel X86).  Note
that BP treads `Comp' as a "real" type and allows assignments like
`MyCompVar:= 42.0'.  Since we don't consider this a feature, GPC does
not copy this behaviour.


File: gpc.info,  Node: Summary of integer types,  Prev: Integer types and compatibility,  Up: Integer types

Summary of Integer Types
........................

   Here is a summary of all integer types defined in GPC.  The sizes
and ranges are only *typical* values, valid on some, but not all
platforms.  Compatibility to GNU C however *is* guaranteed (to the
extend of the GNU General Public License, of course ;-).

*Note ByteInt::
     signed 8-bit integer type, `-128..128',
     compatible to `signed char' in GNU C.

*Note Byte: ByteCard
     unsigned 8-bit integer type, `0..255',
     compatible to `unsigned char' in GNU C.

*Note ShortInt::
     signed 16-bit integer type, `-32768..32767',
     compatible to `short int' in GNU C.

*Note ShortWord: ShortCard
     unsigned 16-bit integer type, `0..65535',
     compatible to `unsigned short int' in GNU C.

*Note Integer::
     signed 32-bit integer type, `-2147483648..2147483647',
     compatible to `int' in GNU C.

*Note Word: Cardinal
     unsigned 32-bit integer type, `0..4294967295',
     compatible to `unsigned int' in GNU C.

*Note MedInt::
     signed 32-bit integer type, `-2147483648..2147483647',
     compatible to `long int' in GNU C.

*Note MedWord: MedCard
     unsigned 32-bit integer type, `0..4294967295',
     compatible to `unsigned long int' in GNU C.

*Note LongInt::
     signed 64-bit integer type,
     `-9223372036854775808..9223372036854775807',
     compatible to `long long int' in GNU C.

*Note LongWord: LongCard
     unsigned 64-bit integer type, `0..18446744073709551615',
     compatible to `unsigned long long int' in GNU C.

*Note LongestInt::
     signed 64-bit integer type,
     `-9223372036854775808..9223372036854775807'.

*Note LongestWord: LongestCard
     unsigned 64-bit integer type, `0..18446744073709551615'.

*Note Comp::
     signed 64-bit integer type,
     `-9223372036854775808..9223372036854775807'.

*Note SmallInt::
     signed 16-bit integer type, `-32768..32767'.

   To specify the number of bits, use

`Integer ( N )'
     signed N-bit integer type.

`Cardinal ( N )'
     unsigned N-bit integer type.

`Word ( N )'
     unsigned N-bit integer type.

   See also: *Note Subrange types::.


File: gpc.info,  Node: Subrange types,  Next: endianness,  Prev: Integer types,  Up: Data types

Subrange Types
--------------

   GNU Pascal supports Standard Pascal's subrange types:

       Type
         MonthInt = 1..12;
         Capital = 'A'..'Z';
         ControlChar = ^A..^Z;  (* `^A' = `chr ( 1 )' is an extension *)

   To increase performance, variables of such a type are aligned in a
way which makes them fastest to access by the CPU.  As a result, `1..12'
occupies 4 bytes of storage on an Intel X86 compatible processor.

   For if you want to save storage at the expense of speed, GPC
provides a `packed' variant of these as an extension:

       Type
         MonthInt = packed 1..12;

   A variable of this type occupies the shortest possible (=
addressable) space in memory--one byte on an Intel X86 compatible
processor.

   See also: *Note packed::.


File: gpc.info,  Node: endianness,  Next: alignment,  Prev: Subrange types,  Up: Data types

Endianness
----------

   (Under construction.)


File: gpc.info,  Node: alignment,  Prev: endianness,  Up: Data types

Alignment
---------

   (Under construction.)


File: gpc.info,  Node: Operators,  Next: Schemata,  Prev: Data types,  Up: Programming

Operators
=========

   GNU Pascal supports all operators of ISO Pascal and Borland Pascal.
In addition, you can define your own operators according to the
Pascal-SC (PXSC) syntax.

* Menu:

* Built-in operators::
* User-defined operators::


File: gpc.info,  Node: Built-in operators,  Next: User-defined operators,  Up: Operators

Built-in Operators
------------------

   The following table lists all built-in GNU Pascal operators, ordered
by precedence:  `:=' has lowest precedence, `not' highest.  As usual,
the precedence of operators can be superseeded with parentheses.

     :=
     <    =    >    in   <>   >=   <=
     +    -    or   +<   -<   +>   ->
     *    /    div  mod  and  shl  shr  xor  *<   /<   *>   />
     pow  **
     not  &    @

   The Pascal-SC (PXSC) operators `+<', `-<', `+>', `->', `*<', `/<',
`*>', and `/>' are not yet implemented into GNU Pascal but may be
defined by the user (see below).


File: gpc.info,  Node: User-defined operators,  Prev: Built-in operators,  Up: Operators

User-defined Operators
----------------------

   GNU Pascal allows the definition of binary operators according to the
Pascal-SC (PXSC) syntax.  The following "scalar product" example
illustrates how to do this:

       Type
         Vector = record
           x, y: Real;
         end (* Vector *);
     
       Operator * ( a, b: Vector ) s: Real;  (* or: `= s: Real' *)
     
       begin (* Vector * Vector *)
         s:= a.x * b.x + a.y * b.y;
       ^end (* Vector * Vector *);
     
       Var
         u, v: Vector;
         a: Real;
     
       [...]
     
       a:= u * v;

   Between the closing parenthesis of the argument list and the result
variable, GPC allows an optional equal sign.  This is not allowed in
PXSC, but it is consistent with Extended Pascal's function return
variable definitions, where the equal sign is obligatory (but optional
in GPC).

   The argument types needn't be equal, and the name of the operator
may be an identifier instead of a known symbol.  You cannot define
*new* symbols in GPC.

   The PXSC operators `+>', `+<', etc. for exact numerical calculations
currently are not implemented in GPC, but you can define them.  If you
write a module which really implements these operators, please send it
to us, so we can include it into the next distribution.  Also, the
other real-type operators do *not* meet the requirements of PXSC; a
module which fixes that would be a welcome contribution.

   (And if you know more about modules in Pascal-SC than just their
existence, please contact us either!  We could probably easily
implement them if we knew how they look like.  Something quite close to
Pascal-SC modules already *is* implemented as "GNU specific modules".)


File: gpc.info,  Node: Schemata,  Next: Pointer arithmetics,  Prev: Operators,  Up: Programming

Schema Types
============

   Schemata are types that depend on one or more variables, called
"discriminants".  They are an ISO-10206 Extended Pascal extension.

       Type
         RealArray ( n: Integer ) = array [ 1..n ] of Real;

   The type `RealArray' in this example is called a Schema with the
discriminant `n'.  To declare a variable of such a type, write

       Var
         Foo: RealArray ( 42 );

   Schema-typed variables "know" about their discriminants.  They can
be accessed just like record fields:

       writeln ( Foo.n );   (* yields 42 *)

   While types of variables must always have specified discriminants
(which may be other variables), *pointers* to schema variables may be
without a discriminant:

       Type
         RealArrayPtr = ^RealArray;
     
       Var
         Bar: RealArrayPtr;

   When applying `New' to such a pointer, you must specify the intended
value of the discriminant as a parameter:

       New ( Bar, 137 );

   As a GNU extension, the above can also be written as

       Bar:= New ( RealArrayPtr, 137 );

   Schemata are not limited to arrays.  They can be of any type that
normally requires constant values in its definition, for instance
subrange types, or records containing arrays etc.  (Sets do not yet
work.)

   To finish this section, here is a somewhat exotic example:

       Type
         ColorType = ( red, green, blue );
         ColoredInteger ( Color: ColorType ) = Integer;

   A `ColoredInteger' behaves just like an ordinary integer, but it has
an additional property `Color' which can be accessed like a record
field.

       Var
         Foo: ColoredInteger ( green );
     
       [...]
     
       Foo:= 7;
       if Foo.Color = red then
         inc ( Foo, 2 )
       else
         Foo:= Foo div 3;


File: gpc.info,  Node: Pointer arithmetics,  Next: Type casts,  Prev: Schemata,  Up: Programming

Pointer Arithmetics
===================

   GPC allows to increment, decrement, compare, and subtract pointers
or to use them in `for' loops just like the C language.

       Var
         A: array [ 1..7 ] of Char;
         p, q: ^Char;
         i: Integer;
     
       [...]
     
       for p:= @A [ 1 ] to @A [ 7 ] do
         p^:= 'x';
     
       p:= @A [ 7 ];
       q:= @A [ 3 ];
       while p > q do
         begin
           p^:= 'y';
           dec ( p );
         end (* while *);
     
       p:= @A [ 7 ];
       q:= @A [ 3 ];
       i:= q - p;      (* yields 4 *)

   Incrementing a pointer by one means to increment the address it
contains by the size of the variable it is pointing to.  For typeless
pointers (`Pointer'), the address is incremented by one instead.

   Similar things hold when decrementing a pointer.

   Subtracting two pointers yields the number of variables pointed to
between both pointers, i.e. the difference of the addresses divided by
the size of the variables pointed to.  The pointers must be of the same
type.


File: gpc.info,  Node: Type casts,  Next: OOP,  Prev: Pointer arithmetics,  Up: Programming

Type Casts
==========

   In some cases, especially when interfacing with other languages,
Pascal's strong typing can be an obstacle.  To temporarily circumvent
this, GPC (and other Pascal compilers) defines explicit "type casts".

   There are two kinds of type casts, value type casts and variable type
casts.

   Value type casts

   To convert a value of one data type into another type, you can use
the target type like the name of a function that is called. The value
to be converted can be a variable or an expression.

   An example:

       Var
         Ch: Char;
         i: Integer;
     
       [...]
     
       i := Integer (Ch);

   Another, more complicated, example:

       Type
         CharPtr = ^Char;
         CharArray = array [ 0..99 ] of Char;
         CharArrayPtr = ^CharArray;
     
       Var
         Foo1, Foo2: CharPtr;
         Bar: CharArrayPtr;
     
       [...]
     
       {$X+} { We need extended syntax in order to use ``Succ'' on a pointer }
     
       Foo1 := CharPtr ( Bar );
       Foo2 := CharPtr ( Succ ( Bar ) );

   However, because of risks involved with type casts, explained below,
you should try to avoid type casts whenever possible - and it should be
possible in most cases. For instance, the first example above could use
the built-in function "Ord" instead of the type cast:

       i := Ord (Ch);

   The assignments in the second example could be written in the
following way without any type casts:

       Foo1 := @Bar^ [ 0 ];
       Foo2 := @Bar^ [ 1 ];

   Value type casting only works between certain types: either between
different ordinal types (including integer types), or between different
real types, or between different pointer types. In each case, the actual
value, i.e. the ordinal or numeric value or the address pointed to,
respectively, is preserved in the cast.

   Note: It is also possible to cast from an integer into a real type.
This is a consequence of the fact that integer values are generally
automatically converted to real values when needed.

   Note: In the case of pointers, a warning is issued if the
dereferenced target type requires a bigger alignment than the
dereferenced source type (see *Note alignment::).

   Variable type casts

   It is also possible to temporarily change the type of a variable,
without converting its contents in any way. This is called variable
type casting.

   The syntax is the same as for value type casting. This can be
confusing, as the example below shows.

   The type-casted variable is still the same variable (memory location)
as the original one, just with a different type. Outside of the type
cast, the variable keeps its original type.

   There are some important differences between value and variable type
casting:

   *   Variable type casting only works on variables, not on
     expressions.

   *   The result of a variable type casting is still a variable.
     Especially, it can be used on the left side of an assignment   (as
     a so-called "lvalue"), or passed by reference to a procedure.

   *   No values are converted. The contents of the variable, seen as a
     raw   bit pattern, are just interpreted according to the new type.
     In many   cases, this does not make a big difference, e.g. the
     same ordinal   values of different ordinal types have the same bit
     pattern (provided,   the types have the same size), and similarly
     for different pointer types.    However, there are cases where it
     does make a difference, most notably   the completely different
     internal representation of integer and real   types. This is
     demonstrated in the following example, admittedly a   very
     constructed example, by using an integer and a real type of the
     same size and trying to cast between them.

   *   Because bit patterns are just interpreted differently, the
     source and   target type must have the same size. If this is not
     the case, GPC will   give a warning. (@error? see below)

   *   Beware: Variable type casts might have unexpected effects on
     different   platforms since you cannot rely on a specific way the
     data is stored   (e.g. see *Note endianness::).

       program TypeCastingTraps;
     
       { Declare a real type and an integer type of the same size, and some
         variables of these types we will need. }
     
       Type
         RealType    = ShortReal;
         IntegerType = Integer ( BitSizeOf ( RealType ) );
     
       Var
         i, i1, i2, i3, i4, i5: IntegerType;
         r, r1, r2, r3, r4:     RealType;
     
       begin
     
         { First part: Casting integer into real types. }
     
         { Start with some integer value }
         i := 42;
     
         { First attempt to cast. Here, an lvalue is casted, so this must
           be a variable type cast. Therefore, the bit pattern of the value
           of i is transferred unchanged into r1 which results in a silly
           value of r1. }
         IntegerType (r1) := i;
     
         { Second try. Here we cast an expression -- though a trivial one --,
           rather than a variable. So this can only be a value type cast.
           Therefore, the numeric value is preserved, i.e. r2 = 42.0 . }
         r2 := RealType (i+0);
     
         { Third way. In this last example, a variable is casted, and the
           result is used as an expression, not as an lvalue. So this
           could be either a value or variable type cast. However, there
           is a rule that value type casting is preferred if possible.
           So r3 will contain the correct numeric value, too. }
         r3 := RealType (i);
     
         { Of course, you do not need any casts at all here. A simple
           assignment will work because of the automatic conversion from
           integer to real types. So r4 will also get the correct result. }
         r4 := i;
     
         { Now the more difficult part: Casting real into integer types. }
     
         { Start with some real value. }
         r := 41.9;
     
         { Like the first attempt above, this one does a variable type cast,
           preserving bit patterns, and leaving a silly value in i1. }
         RealType (i1) := r;
     
         { The second try from above does not work, because an expression of
           type real is to be casted into an integer which is not allowed. }
         { i2 := IntegerType (r+0); }
     
         { Third way. This looks just like the third way in the first part
           which was a value type cast.
           But -- surprise! Since value type casting is not possible from
           real into integer, this really does a variable type casting,
           and the value of i3 is silly again! This difference in behaviour
           shows some of the hidden traps in type casting. }
         i3 := IntegerType (r);
     
         { As often, it is possible to avoid type casts altogether and
           convert real types into integers easily by other means, i.e. by
           using the built-in functions ``Round'' or ``Trunc'', depending
           on the mode of rounding one wants. }
         i4 := Round (r); { 42 }
         i5 := Trunc (r); { 41 }
     
       end.

   When dealing with objects (see *Note OOP::), it is often
necessary--and safe--to cast a pointer to an object into a pointer to a
more specialized (derived) object.  In future releases, GPC will
provide an operator `as' for a safer approach to this problem.

   See also: *Note absolute::, *Note alignment::, *Note endianness::,
*Note OOP::,           *Note ord::, *Note chr::, *Note round::, *Note
trunc::.


File: gpc.info,  Node: OOP,  Next: Other languages,  Prev: Type casts,  Up: Programming

Object-orientated Programming
=============================

   GNU Pascal follows the object model of Borland Pascal 7.0.  The ANSI
draft Object Pascal language and the Delphi language (also called
"Object Pascal" by Borland) are currently not implemented, but planned
for future versions of GPC.

   The syntax for an object type declaration is as follows:

       Type
         fooParentPtr = ^fooParent;
         fooPtr = ^foo;
     
         fooParent = object
           Destructor Fini; virtual;
           Procedure bar ( c: Real ); virtual;
           Procedure baz ( b, a, z: Char );  (* not virtual *)
         end (* FooParent *)
     
         foo = object ( fooParent )
           x, y: Integer;
           Constructor Init ( a, b: Integer );
           Destructor Fini; virtual;
           z: Real;
           Procedure bar ( c: Real ); virtual;  (* overrides `fooParent.bar' *)
           Function baz: Boolean;  (* new function *)
         end (* foo *);

   Remarks:

   * Data fields and methods can be mixed.

   * GPC currently does not support `private' declarations and such.

   * Constructors and destructors are ordinary functions, internally.
     When a constructor is called, GPC creates some inline code to
     initialize the object; destructors do nothing special.

   * Currently, the `gpc1' compiler does not check whether all declared
     methods are really implemented; the linker does check this.

   A pointer to `fooParent' may be assigned the address of a `foo'
object.  A `fooParent' formal `Var' parameter may get a `foo' object as
the actual parameter.  In such cases, a call to a `virtual' method
calls the child's method, whereas a call to a non-`virtual' method
selects the parent's one:

       Var
         MyFooParent: fooParentPtr;
         SomeFoo: foo;
     
       [...]
     
       SomeFoo.Init ( 4, 2 );
       MyFooParent:= @SomeFoo;
       MyFooParent^.bar ( 3.14 );  (* calls `foo.bar' *)
       MyFooParent^.baz ( 'b', 'a', 'z' );  (* calls `fooParent.baz' *)
       if SomeFoo.baz then  (* calls `foo.baz' *)
         writeln ( 'Baz!' );

   In a method, an overwritten method of a parent object can be called
either prefixing it with the parent type name, or using the keyword
`inherited':

       Procedure foo.bar ( c: Real );
     
       begin (* foo.bar *)
         z:= c;
         inherited bar ( z );  (* Or: fooParent.bar ( z ) *)
       end (* foo.bar *);

   Use `fooParent.bar ( z )' if you want to be sure that *this* method
is called, even if somebody decides not to derive `foo' directly from
`fooParent' but to have some intermediate object.  If you want to call
the method `bar' of the immediate parent--whether it be `fooParent' or
whatever--use `inherited bar ( z )'.

   To allocate an object on the heap, use `New' in one of the following
manners:

       Var
         MyFoo: fooPtr;
     
       [...]
     
       New ( MyFoo, Init ( 4, 2 ) );
     
       MyFooParent:= New ( fooPtr, Init ( 4, 2 ) );

   The second possibility has the advantage that `MyFoo' needn't be a
`fooPtr' but can also be a `fooParentPtr', i.e. a pointer to an
ancestor of `foo'.

   Destructors can and should be called within Dispose:

       Dispose ( MyFooParent, Fini );


File: gpc.info,  Node: Other languages,  Next: Run time library,  Prev: OOP,  Up: Programming

Interfacing with Other Languages
================================

   The standardized GNU compiler back-end makes it relatively easy to
share libraries between GNU Pascal and other GNU compilers.  On
UNIX-like platforms (*not* on MS-DOS-like platforms), the GNU compiler
back-end usually complies to the standards defined for that system, so
communication with other compilers should be easy, too.

   In this chapter we discuss how to import libraries written in other
languages, and how to import libraries written in GNU Pascal from other
languages.  While the examples will specialize to compatibility to GNU
C, generalization is straightforward if you are familiar with the other
language in question.

* Menu:

* Importing from other languages::
* Exporting to other languages::


File: gpc.info,  Node: Importing from other languages,  Next: Exporting to other languages,  Up: Other languages

Importing Libraries from Other Languages
----------------------------------------

   To use a function written in another language, you need to provide
an external declaration for it--either in the program, or in the
interface part of a Unit, or an Interface Module.

   Let's say you want to use the following C library from Pascal:

       /* foobar.c */
     
       #include <unistd.h>
     
       int foo = 1;
     
       void bar ( void )
       {
         sleep ( foo );
       } /* bar */
     
     
       /* foobar.h */
     
       extern int foo;
       extern void bar ( void );

   Then your program can look like this:

       Program TestFoo;
     
       (*$L foobar.c *)  (* Or: `foobar.o' if you don't have the source *)
     
       Var
         foo: asmname 'foo' Integer;
     
       Procedure Bar; asmname 'bar';
     
       begin
         foo:= 42;
         Bar;  (* Take a break :*)
       end.

   Or, if you want to provide a `FooBar' Unit:

       Unit FooBar;
     
       Interface
     
       Var
         foo: asmname 'foo' Integer;
     
       Procedure Bar; asmname 'bar';
     
       Implementation
     
       (* empty *)
     
       end.

   You can either link your program manually with `foobar.o' or put a
compiler directive `(*$L foobar.o *)' into your program (planned for
Units, too), and then GPC cares about the linking.  If you have the
source of the "FooBar" library (you always have it if it is Free
Software), you can even write `(*$L foobar.c *)' in the program (like
above).  Then GPC will also link with `foobar.o', but in addition GPC
will run the C compiler whenever `foobar.c' has changed if `--automake'
is given, too.

   While it is convenient for most applications, there is no must to
give the C function `bar' the name `Bar' in Pascal; you can name it as
you like.

   For external functions completely written in lowercase there is the
shortcut `C' or `C_language' for `asmname 'bar''.  For external
functions written with one uppercase letter and the others in
lowercase, you can use `external' or `extern' instead of `asmname
'Bar''.  Since GPC internally converts all identifiers to this notation,
`external' is the natural choice when importing other Pascal functions.

   *Caution:* This syntax (`C', `asmname' and such) is subject to
change, especially for variables.

   Some libraries provide a `main' function and require your program's
"main" to be named differently.  To achive this with GPC, invoke it
with an option `--gpc-main="GPCmain"' (where "GPCmain" is an example
how you might want to name the program).  You can also write it into
your source as a directive `(*$pascal-main="GPCmain" *)'.


File: gpc.info,  Node: Exporting to other languages,  Prev: Importing from other languages,  Up: Other languages

Exporting GPC Libraries to Other Languages
------------------------------------------

   The `.o' files produced by GPC are in the same format as those of all
other GNU compilers, so there is no problem in writing libraries for
other languages in Pascal.  To use them, you will need to write kind of
interface--a header file in C.  However there are some things to take
into account, especially if your Pascal Unit exports objects:

   * By default, GPC capitalizes the first letter of each identifier, so
     `Procedure FooBAR' must be imported as `extern void Foobar()' from
     C.

   * If you want to specify the external name separately, use `asmname':

            Procedure FooBAR; asmname 'FooBAR';
            (* Works like a `forward' declaration *)
          
            Procedure FooBAR;
          
            begin (* FooBAR *)
              writeln ( 'FooBAR' );
            end (* FooBAR *);

     This one can be imported from C with `extern void FooBar()'.

   * Objects are "records" internally.  They have an implicit `vmt'
     field which contains a pointer to the "virtual method table".
     This table is another record of the following structure:

            Type
              SizeInt = Integer ( BitSizeOf ( Pointer ) );
          
              VMT = record
                ObjectSize: SizeInt;  (* Size of object in bytes. *)
                NegObjectSize: SizeInt;  (* Its negative. *)
                Fun: array [ 1..n ] of Procedure;
                  (* Pointers to the virtual functions. *)
              end (* VMT *);

     You can call a virtual method of an object from C if you
     explicitly declare this `struct' and explicitly dereference the
     `Fun' array.  The VMT of an object `FooBAR' is an external (in C
     sense) variable `vmt_Foobar' internally.

   * Methods of objects are named `Myobject_Mymethod' (with exactly two
     capital letters) internally.

   * The main program is just another procedure; `Program FooBAR'
     produces `Procedure FooBAR; asmname 'program_Foobar'' (without
     parameters) internally.  There is a separate function `main' which
     stores the command-line arguments in global variables and then
     calls this "main procedure".

   * If you want to put a program in a library for some reason, and you
     want to give the `main' program an internal name different from
     `main', call GPC with the option `--pascal-main="GPCmain"' (see
     previous subsection).

