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: Extended Pascal,  Next: Borland Pascal,  Prev: Extensions,  Up: Top

About Pascal and Extended Pascal languages
******************************************

   Pascal is a well-known programming language and hardly needs to be
described here.  Notice, however, that some people's idea of Pascal is
affected by acquaintance with such products as Turbo Pascal which
differ from the Pascal standard and provide a lot of nonstandard
extensions (some of which are compatible with the Extended Pascal
standard).  Moreover, it is worth mentioning that the ISO Pascal
standard defines two levels of the language, level 0 and level 1; the
only difference between the levels is that level 1 supports the
so-called conformant array schemas in parameter declarations.

   Extended Pascal is a standardized language which contains so
significant extensions to Pascal that it is best regarded as a new
language.  It is currently not very well known, and computer vendors do
not seem to be eager to provide compilers for it.  Thus, there is
social need for GNU Pascal supporting Extended Pascal.

A comparison of Borland Turbo Pascal with Extended Pascal
=========================================================

   As mentioned earlier, Turbo Pascal does not conform to any of the
Pascal standards.  If you carefully chose a subset of unextended
Pascal, you may be able to port code if you're lucky/careful.

   To be fair, Turbo Pascal has some wonderful features that make it
very powerful in the environments in which it runs.  However, some of
those features are of little use on non Windows/DOS platforms and
probably are not good candidates for standardization.

   There are several Turbo Pascal features which are semantically
similar to features in unextended Pascal or Extended Pascal.  Here is a
list of mappings between Turbo Pascal features and Extended Pascal
features:

   * Case constructs

       a. Extended Pascal uses `otherwise' instead of `else'.

          *Borland Pascal*
               case c of
                 'A' : ;
                 'B' : ;
                 else ...;
               end;

          *Extended Pascal*
               case c of
                 'A' : ;
                 'B' : ;
                 otherwise ...;
               end;

       b. Missing cases cause Extended Pascal compilers to halt. In the
          case statement above if you had no `otherwise' clause and
          char c had the value 'C', you got an error (note, this would
          be unnoticed in Borland Pascal).


   * Procedure and function types and variables

     Here is an area of subtle differences.  Turbo Pascal has true
     procedure/function types but doesn't have standard Pascal's
     procedural/functional parameters.

     *Borland Pascal*
          type
            CompareFunction = function(Key1, Key2 : string) : integer;
          
          function Sort(Compare : CompareFunction);
          begin
            ...
          end;

     *Extended Pascal*
          function Sort(function Compare (Key1, Key2 : string) : integer);
          begin
            ...
          end;

     Moving from Turbo Pascal to Extended Pascal might be difficult if
     the Turbo Pascal program saves, compares, trades, etc. procedure
     values.  For example, an array of procedure values isn't possible
     in Extended Pascal.  Moving the other way is a little easier as
     shown by the above examples.

   * Strings

       a. Borland Pascal's string type has a special case, namely
          `string' without a length meaning the same as `string[255]'.
          There is no default in Extended Pascal so you have to change
          all string types to `string(255)'. Example:

               var
                 s : string;

          becomes:
               var
                 s : string(255);

          Note also that you have to use parentheses instead of
          brackets.

       b. A nice pitfall is the pointer to string as in:

               type
                 PString = ^String;

          In Extended Pascal this is a pointer to a schema type! Don't
          forget to translate this to:

               type
                 string255 = string(255);
                 PString = ^string255;

          If you indeed want to use String as a schema pointer you can
          define things like:

               type
                 MyStr : ^String;
               begin
                 New(MyStr, 1024);
               end;

          to allocate 1024 bytes of string space.

       c. As you could see above, Extended Pascal has no 255 byte limit
          for strings. It is however save to assume a limit of about
          32000 bytes. At least Prospero's Extended Pascal limits
          strings to 32760 bytes. GNU Pascal allow larger strings up to
          2G bytes.  DEC Pascal limits strings to 65535 bytes.


   * Constant variables

       a. Extended Pascal translates Borland's gruesome:

               const
                 i:integer = 0;

          to:

               var
                 i : integer value 0;

       b. You can also assign initialization values to types:

               type
                 MyInteger = integer value 0;
               
               var
                 i : MyInteger;

          All variables of type MyInteger are automatically initialized
          to 0 when created.

       c. Constant arrays of type string are translated from:

               const
                 MyStringsCount = 5;
               type
                 Ident = string[20];
               const
                 MyStrings : array [1..MyStringsCount] of Ident = (
                               'EXPORT', 'IMPLEMENTATION', 'IMPORT', 'INTERFACE',
                               'MODULE');

          to:

               const
                 MyStringsCount = 5;
               type
                 Ident = string(20);
               var
                 MyStrings : array [1..MyStringsCount] of Ident value [
                   1:'EXPORT'; 2:'IMPLEMENTATION'; 3:'IMPORT';
                   4:'INTERFACE'; 5:'MODULE'];

          There seem to be pros and cons to each style.

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


   * Variant records

     The following construction is not allowed in Extended Pascal:
          type
            PersonRec = record
              Age : integer;
              case EyeColor : (Red, Green, Blue, Brown) of
                Red, Green : (Wears_Glasses : Boolean);
                Blue, Brown : (Length_of_lashes : integer);
              end;
            end;

     The variant field needs an explicit type. Code this as:

          type
            EyeColorType = (Red, Green, Blue, Brown);
            PersonRec = record
              Age : integer;
              case EyeColor : EyeColorType of
                Red, Green : (Wears_Glasses : Boolean);
                Blue, Brown : (Length_of_lashes : integer);
              end;
            end;

   * Units

       a. You can translate units almost automatically to Extended
          Pascal Modules, taking into account some differences of
          course.

          Extended Pascal does not automatically export everything named
          in a module, but you have to create seperate export clauses.

          For example translate the following unit:

               unit A;
               
               interface
               
               uses
                 B, C;
               
               procedure D;
               
               implementation
               
               procedure D;
               begin
               end;
               
               end.

          to this module:

               module A interface;
               
               export
                 A = (D);
               
               import
                 B;
                 C;
               
               procedure D;
               
               end.
               
               module A implementation;
               
               procedure D;
               begin
               end;
               
               end.

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

          You also see in this example how to translate the Borland
          Pascal "uses" clause to the Extended Pascal "import" clause.

       b. Borland Pascal allows you to have code in a unit that is
          executed once, at startup, to initialize things. You can
          translate this to Extended Pascal's "to begin do ..end"
          structure.

          *Borland Pascal*
               unit A;
               
               interface
               
               implementation
               
               begin
                 { do something }
               end.

          *Extended Pascal*

               module A interface;
               end.
               
               module A implementation;
               
               to begin do begin
                 { do something }
               end;
               
               end.

          Extended Pascal also has a `"to end do .... end"' so you can
          translate `Exit' handlers also.


   * Files

     Extended Pascal treats files quite differently as Borland Pascal.
     I'm not going to treat file pointers, Get and Put here, but
     instead I focus on special Extended Pascal features.

     In Borland Pascal you can read any text file as follows:

          var
            t : text;
            Line : string;
          begin
            Assign(t, 'MYTEXT.TXT');
            Reset(t);
            while not eof(t) do  begin
              readln(t, Line);
              writeln(Line);
            end;
          end;

     The `Assign' function associated the textfile `T' with the file
     `MYTEXT.TXT'.

     In Extended Pascal, files are considered entities external to your
     program. External entities, which don't need to be files, need to
     be bound to a variable your program. Any variable to which
     external entities can be bound needs to be declared bindable. So
     the variable declaration of t becomes:

          var
            t : bindable text;

     Extended Pascal has the bind function that binds a variable with
     an external entity.  Here is an Extended Pascal procedure that
     emulates the Assign procedure in Turbo Pascal.

          procedure Assign(var t : text; protected Name : string);
          var
            b : BindingType;
          begin
            unbind (t);
            b := binding (t);
            b.Name := Name;
            bind (t, b);
            b := binding (t);
          end;

     Comments: the unbind procedure unbinds a bindable variable from
     its external entity. If it is not bound, nothing happens. The
     binding function initializes b. We call binding to set some fields
     of the BindingType record. Next we set the name field to the name
     of the file. Calling bind will bind t to the external entity. If
     we now call binding again, we get the current state of t's binding
     type. We can now check for example if the bind has succeeded by:

          if not b.bound then
            { do error processing }

     Note that Prospero's Pascal defaults to creating the file if it
     does not exists! You need to use Prospero's local addition of
     setting `b.existing' to `true' to work-around this.

     I've not worked with binary files enough, so no advice yet on how
     to access them, but you access them much the same.

     As last an example of getting the size of a file.

          function FileSize(filename : String) : LongInt;
          var
            f : bindable file [0..MaxInt] of char;
            b : BindingType;
          begin
            unbind(f);
            b := binding (f);
            b.Name := filename;
            bind(f, b);
            b := binding(f);
            SeekRead(f, 0);
            if empty(f)
              then  file_size := 0
              else  file_size := LastPosition(f) + 1;
            unbind(f);
          end(*file_size*);

     Prospero's Extended Pascal has a bug in this case. Replace the
     MaxInt in the type definition of f by a sufficiently large
     integer. GNU Pascal works correct in this case.


File: gpc.info,  Node: Borland Pascal,  Next: GPC bugs,  Prev: Extended Pascal,  Up: Top

From Borland Pascal to GNU Pascal
*********************************

   This chapter is intended to be a QuickStart guide for programmers
who are familiar with Borland Pascal, version 7 for DOS protected mode.
Other versions don't differ too much but this one is the very last DOS
version Borland has published.

* Menu:

* Borland compatibility::
* IDE versus command line::
* Comments and compiler directives::
* Units; GPI files and AutoMake::
* Optimization::
* Debugging::
* GPC inline assembler::
* Objects::
* Strings::
* Typed constants::
* Bit; byte and memory manipulation::
* User-defined operators in GPC::
* Data types in BP and GPC::
* Files::
* Built-in constants::
* Built-in operators in BP and GPC::
* Built-in Procedures and Functions::
* Parameters::
* Miscellaneous::


File: gpc.info,  Node: Borland compatibility,  Next: IDE versus command line,  Up: Borland Pascal

Borland compatibility
=====================

   Unlike other free compilers, GNU Pascal is *not* intended to be 100%
Borland compatible.  GNU Pascal is part of the GNU project, so
portability between different machines is one of its primary goals.
For this reason, non-portable features of Borland Pascal will probably
not be included into GNU Pascal.  Some other differences are so minimal
that we have more important things to do than to implement them.

   However if you want to contribute to GNU Pascal by eliminating holes
in GPC's Borland compatibility, be welcome in the GNU Pascal development
team!  See *Note How to Contribute:: for details.


File: gpc.info,  Node: IDE versus command line,  Next: Comments and compiler directives,  Prev: Borland compatibility,  Up: Borland Pascal

IDE versus command line
=======================

   On the DOS platform with DJGPP, you can use the RHIDE for GNU Pascal;
check the subdirectories of your DJGPP distribution.

   Unfortunately, there is no IDE which would run on all platforms.  We
are working on it, but this will take some time.  Please be patient--or
offer your help!

   Without an IDE, the GNU Pascal Compiler, GPC, is called about like
the command-line version of the Borland Pascal Compiler, BPC.  Edit your
source file(s) with your favorite ASCII editor, then call GNU Pascal
with a command line like

       C:\GNU-PAS> gpc hello.pas -o hello.exe

on your DOS or OS/2 box or

       myhost/home/joe/gnu-pascal> gpc hello.pas -o hello

on your UNIX (or UNIX-compatible) system.  Don't omit the suffix
`.pas':  GPC is a common interface for a Pascal compiler, a C, ObjC and
C++ compiler, an assembler, a linker, and perhaps a Modula and FORTRAN
compiler.  From the extension of your source file GPC figures out which
compiler to run.

   The `-o' is a command line option which tells GPC how the executable
has to be named.  If not given, the executable will be called `a.out'
(Unix) or `a.exe' (Dos).

   Note that GPC is case-sensitive concerning file names, so it will
*not* work if you type

       C:\GNU-PAS> GPC HELLO.PAS -O HELLO.EXE

   GPC is a very quiet compiler and doesn't print anything on the
screen unless you request it or there is an error.  If you want to see
what is going on, invoke GPC with additional options:

       -Q            "don't be quiet"  (or: Quassel-Modus in German)

(with *capital* `Q'!) means that GPC prints out the names of procedures
and functions it processes, and

       --verbose

   or abbreviated

       -v

means that GPC informs you about the stages of compilation, i.e.
preprocessing, compiling, assembling, and linking.

   One example (this time for OS/2):

       [C:\GNU-Pascal] gpc --verbose -Q hello.pas

   Throughout this chapter, we will tell you about a lot of
command-line switches.  They are all invoked this way.

   After compilation, there will be an executable `hello' file in the
current directory.  (`hello.exe' with DOS and OS/2.)  Just run it and
enjoy.  If there are errors, GNU Pascal will not stop compilation after
the first one--as Borland Pascal does--but try to catch them all in one
compilation.  If you get more error messages than your screen can hold,
you can catch them in a file (e.g. `gpc.out') or pipe them to a program
like `more' in the following way:

       gpc hello.pas 2>gpc.out

   This works with OS/2 and any bash-like shell under UNIX; for DOS you
must get a replacement for `command.com' which supports this kind of
redirection, or use the `redir' utility (see also the DJGPP FAQ):

       C:\GNU-PAS> redir -eo gpc hello.pas -o hello.exe | more

   You can also use Borland's IDE for GNU Pascal on the DOS platform:
Install the GNU Pascal Compiler in the Tools menu (via Options/Tools).

       Name:       GNU Pascal
       Path:       gpc
       Arguments:  $SAVE ALL --verbose -Q $NAME($EDNAME).pas
       HotKey:     Shift+F9

   Note once more that GPC is case-sensitive, so it is important to
specify `.pas' instead of the `.PAS' Borland Pascal would append
otherwise!

   You can include more command-line arguments to GNU Pascal (e.g.
`--automake'; see below) as you will learn more about them.

   Since Borland Pascal will try to recompile your program if you use
its `run' menu function, you will need another "tool" to run your
program:

       Name:       run program
       Path:       command.com
       Arguments:  /c $NAME($EDNAME)
       HotKey:     Shift+F10


File: gpc.info,  Node: Comments and compiler directives,  Next: Units; GPI files and AutoMake,  Prev: IDE versus command line,  Up: Borland Pascal

Comments and compiler directives
================================

   According to ISO 7185 and ISO 10206 standard, GNU Pascal can
recognize comments opened with `(*' and closed with `}'.  With Borland
Pascal, both types of comments can be nested, so you will probably have
sources where passages containing comments are "commented out".  GPC's
default behavior is to allow nested comments, so you don't need to worry
about this.  However you can switch it off either by a command-line
option, or by a compiler directive:

       --no-nested-comments     {$N-}    (*$N-*)

   The $N directive also exists in BP but has another meaning.  The
same holds for most of GPC's other compiler directives (also
corresponding to command-line options in most cases):

       --short-circuit     $B+ $B-  like in Borland Pascal:
                                    $B- means short-circuit Boolean
                                    operators; $B+ complete evaluation
     
       --c-numbers         $C+ $C-  enable/disable C-style octal 0177
                                    and hexadecial 0xFF numbers
     
       --char-escapes      $E+ $E-  enable/disable C-style character
                                    escape sequences in strings
     
       --nested-comments   $N+ $N-  see above
     
       --pedantic          $P+ $P-  give/don't give portability warnings
     
                           $W+ $W-  enable/disable warnings
     
                           $X+ $X-  enable/disable extended syntax
                                    (function return value ignore,
                                    operator definitions, ``PChars'',
                                    pointer arithmetics, ...)
     
       --borland-pascal             disable or warn about GPC features
                                    not supported by Borland Pascal;
                                    do not warn about ``dangerous'' BP
                                    features
     
       {$I FileName }               include filename.pas or
                                    filename.p (make it lowercase)
     
       {$include "filename.pas"}    include (case-sensitive)
     
       {$include <filename.pas>}    the same, but don't search in
                                    current directory
     
       {$M Hello!}                  write message "Hello!" to error
                                    device during compilation
     
       {$D GNU}                     define GNU (for conditional
       {$define GNU}                compilation)
     
       -D GNU                       the same in command line
     
       {$D loop while true do}      define "loop" to be "while
                                    true do" as a macro like in C.
                                    The name of the macro is case-sensitive.
     
       {$ifdef GNU}                 conditional compilation
         ...                        (like in Borland Pascal).
       {$else}                      GPC predefines the symbol
         ...                        __GPC__ (with two leading
       {$endif}                     and trailing underscores).

   You also can use C-style preprocessor directives, e.g. `#include.',
but this is deprecated, e.g. because of possible conflicts with Borland
Pascal style `#42' character constants.

   As in Borland Pascal, `{$...}' and `(*$...*)' are equivalent.


File: gpc.info,  Node: Units; GPI files and AutoMake,  Next: Optimization,  Prev: Comments and compiler directives,  Up: Borland Pascal

Units, GPI files and AutoMake
=============================

   You can use Units in the same way as in Borland Pascal.  However,
there are some differences, problems and new features.  (Please report
the bug if something doesn't work.)

   Concerning the syntax of a Unit, you can, if you want, use Extended
Pascal syntax to specify a Unit initializer, i.e.  instead of writing

       begin
         ...
       end.

at the end of the Unit, you can get the same result with

       to begin do
         begin
           ...
         end (* to begin *);

and there also exists

       to end do
         begin
           ...
         end (* to end *);

   which specifies a finalization routine.  You can use this instead of
Borland Pascal's exit procedures, but for compatibility the included
`system' unit also provides the `ExitProc' variable.  In *Note
Extensions:: and *Note Extended Pascal::, you can find information
about Extended Pascal Modules, an alternative to Units.

   At the moment, there are no qualified identifiers, so take care
about name clashes between different Units.

   When GPC compiles a Unit, it produces two files: an `.o' object file
(compatible with other GNU compilers such as GNU C) plus a precompiled
Interface which resides in a `.gpi' file.  (See *Note GPI files:: for
GPI file internals.)

   GPC does not automatically recognize that something is a Unit and
cannot be linked; you have to tell this by a command line switch:

       -c            only compile, don't link.

   For example, to compile two units, use:

       gpc -c myunit1.pas myunit2.pas

   Of course, one of the purposes of writing Units is to compile them
separately.  However, GNU Pascal allows you to have one or more Units
in the same source file (producing only one `.o' file but separate
`.gpi' files).  You even can have a Program and Units in one and the
same source file; in this case, no `.o' file is produced at all.

   When you have all Units compiled and want to compile the Program,
specify the `.o' files in the command line:

       gpc hello.pas myunit1.o myunit2.o

   You also can specify the program and the units in one command line:

       gpc hello.pas myunit1.pas myunit2.pas

   As an alternative to manually compiling and specifying object files,
you can use GPC's AutoMake feature.  (*Warning*: This is a new feature
in GPC 2.0 and may be unstable!)  With an additional command-line
argument

       gpc --automake hello.pas

   GPC tries to behave like Borland Pascal's `make' facility and
automatically recompiles Units the source of which has been changed.
It also works if an included file has been changed.

   For more information about the AutoMake mechanism, see *Note
AutoMake::.


File: gpc.info,  Node: Optimization,  Next: Debugging,  Prev: Units; GPI files and AutoMake,  Up: Borland Pascal

Optimization
============

   GNU Pascal is a 32 bit compiler with excellent optimization
algorithms (which are identically the same as those of GNU C).  There
are three optimization levels, specified by the command line options
`-O', `-O2', and `-O3'.  (Levels up to `-O6' are worked on.)

   One example:

       Program Test;
     
       procedure Foo;
       Var
         A, B: Integer;
       begin
         A:= 3;
         B:= 4;
         writeln ( A + B );
       end;
     
       begin
         Foo
       end.

   When GNU Pascal compiles this program with optimization, it
recognizes that the argument of writeln is the constant 7--and
optimizes away the variables `A' and `B'. If the variables were global,
they would not be optimized away because they might be accessed from
other places, but the constant 7 would still be optimized.

   For more about optimization, see the GNU C documentation.


File: gpc.info,  Node: Debugging,  Next: GPC inline assembler,  Prev: Optimization,  Up: Borland Pascal

Debugging
=========

   The command line option `-g' specifies generation of debugging
information for GDB, the GNU debugger.  GDB is not as comfortable as the
Turbo Debugger, but it has the same abilities but one:  The program
being debugged is slowed down.  For more information about GDB, call it
(with `gdb') and type in the `help' command.

   GDB has one very nice feature which might even make up for the
slowing-down problematic:  When a GNU-compiled program crashes, it puts
out a `core' file.  When you say "target core core" to the GNU
debugger, it reads the core file and can tell you the address of the
crash, the contents of variables and of the stack, and so on.

   Sometimes it is nice to have a look at the assembler output of the
compiler.  When you specify the `-S' command line option, GPC produces
an `.s' file instead of an `.o' file which contains assembler source
for your program.  More about this in the next section.

   See also "Notes for debugging" in the "Bugs" chapter; see *Note GPC
bugs::.


File: gpc.info,  Node: GPC inline assembler,  Next: Objects,  Prev: Debugging,  Up: Borland Pascal

GPC inline assembler
====================

   GNU Pascal has an inline assembler, but it is quite different from
Borland's one.  I have not yet found reasonable documentation about the
use of this assembler, but I found out the following:

   The syntax is

       asm ( 'movl $12345678, %eax' );
       asm ( 'movl %eax, %edx' );

   to move the (hex) value `$12345678' to the EAX register and then to
the EDX register.  The String argument of the asm statement is passed
as a string to the assembler stage of the compilation.  The assembler
follows the AT&T, not the Intel syntax.  Note that the order of
operands is reversed with respect to the order you know from Intel
assemblers and that the size of the arguments is appended to the
mnemonic as a suffix b (byte), w (word = 2 bytes), or l (long = 4
bytes).

   You can learn about the GNU assembler syntax when compiling your
program with `-S' (see above) and looking into the resulting assembler
source.

   To access Pascal symbols from the assembler, do something like

       asm ( 'movl %%eax, %0' : : 'rm' ( MyVariable ) );

   Here, the % signs in front of the register names are doubled because
% gets some special meaning.  The 'rm' means that the operand may be in
a register or in memory.

   (More about this is in preparation.)


File: gpc.info,  Node: Objects,  Next: Strings,  Prev: GPC inline assembler,  Up: Borland Pascal

Objects
=======

   Objects in the Borland Pascal 7.0 notation are implemented into GNU
Pascal with the following differences:

   * the "private" directive does not work,

   * data fields and methods may be mixed:
            MyObj = object
              x: Integer;
              Procedure Foo; virtual;
              y: Real;
              Function Bar: Char;
            end (* MyObj *);


File: gpc.info,  Node: Strings,  Next: Typed constants,  Prev: Objects,  Up: Borland Pascal

Strings
=======

   Strings are "Schema types" in GNU Pascal which is something more
complicated than Borland-style strings.  For variables, you cannot
specify just `String' as a type like in Borland Pascal; for parameters
and pointer types you can.  There is no 255 characters length limit.
According to Extended Pascal, the maximum string length must be in
(parantheses); GNU Pascal accepts [brackets], too, however.

   For more about Strings and Schema types see *Note Extensions:: and
*Note Extended Pascal::.

   GPC supports Borland Pascal's String-handling functions and some
more (see *Note Extensions::):

       Borland Pascal       GNU Pascal
     
       Length               Length
       Pos                  Pos, Index (1)
       Str                  Str, WriteStr (1)
       Val                  Val, ReadStr
       Copy                 Copy, SubStr, MyStr [ 2 .. 7 ] (2)
       MyStr [ 0 ]:= #7;    SetLength
         -                  Trim
       =, <>, <, <=, >, >=  =, <>, <, <=, >, >=
         -                  EQ, NE, LT, LE, GT, GE
       Insert               Insert
       Delete               Delete

   (1) the order of parameters of the Borland Pascal vs. Extended Pascal
   routines is different

   (2) `SubStr' reports a runtime error if the requested substring
does not fit in the given string, `Copy' does not


File: gpc.info,  Node: Typed constants,  Next: Bit; byte and memory manipulation,  Prev: Strings,  Up: Borland Pascal

Typed constants
===============

   GNU Pascal supports Borland Pascal's "typed constants" but also
Extended Pascal's initialized variables:

       Var
         x: Integer value 7;

   or

       Var
         x: Integer = 7;

   When a typed constant is misused as an initialized variable, a
warning is given unless you specify `--borland-pascal'.

   When you initialize a record, you may omit the field names.  When you
initialize an array, you may provied indices with a `:'.  However this
additional information is ignored completely, so perhaps it's best for
the moment only to provide the values ...

   When you want a local variable to preserve its value, define it as
`static' instead of using a typed constant. Typed constants also become
static automatically for Borland Pascal compatibility, but it's better
not to rely on this "feature" in new programs.

       Procedure Foo;
     
       Var
         x: static Real;
     
       begin (* Foo *)
         (* x keeps its value between two calls to this Procedure *)
       end (* Foo *);


File: gpc.info,  Node: Bit; byte and memory manipulation,  Next: User-defined operators in GPC,  Prev: Typed constants,  Up: Borland Pascal

Bit, byte and memory manipulation
=================================

   The (non-standard) bitwise operators `shl', `shr', `and', `or',
`xor' work in GNU Pascal like in Borland Pascal.  As an extension, you
can use them as "procedures", for examples

       and ( x, $0000FFFF );

   as an alternative to

       x:= x and $0000FFFF;

   GPC accepts the Borland-specific notation `$ABCD' for hexadecimal
numbers, but you also can use Extended Pascal notation:

        2#11111111   for a binary,
        8#177        for an octal,
       16#FF         for a hexadecimal number,

   and so on up to a basis of 36.

   `Inc' and `Dec' are implemented like in Borland Pascal; `Pred' and
`Succ' are generalized according to Extended Pascal:

       a:= Succ ( a, 5 );

   `Absolute' variables work in the context of overloading with other
variables as well as in the context of specifying an absolute address,
but the latter is highly unportable and not very useful even in DOS
protected mode.

   The `Mem' and `Port' arrays don't exist in GNU Pascal.  As a
replacement for `Port', you can use routines like those provided in the
`Ports' unit.

   Borland Pascal's procedures `FillChar' and `Move' are built-in into
GNU Pascal.


File: gpc.info,  Node: User-defined operators in GPC,  Next: Data types in BP and GPC,  Prev: Bit; byte and memory manipulation,  Up: Borland Pascal

User-defined operators in GPC
=============================

   GNU Pascal allows the user to define operators according to the
Pascal-SC syntax:

       Type
         Point = record
           x, y: Real;
         end (* Point *);
     
       Operator + ( a, b: Point ) c: Point;
     
       begin (* Point + Point *)
         c.x:= a.x + b.x;
         c.y:= a.y + b.y;
       end (* Point + Point *);

   The Pascal-SC operators `+>', `+<', etc. for exact numerical
calculations are not implemented, 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.

   (And if you know more about modules in Pascal-SC than just their
existence, please contact us as well!  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: Data types in BP and GPC,  Next: Files,  Prev: User-defined operators in GPC,  Up: Borland Pascal

Data types in BP and GPC
========================

   * Integer types have different sizes in Borland and GNU Pascal:

            Borland Pascal          GNU Pascal     bits(1)  signed
          
            ShortInt                ByteInt          8      yes
            Integer                 ShortInt        16      yes
            LongInt                 Integer         32      yes
            Comp                    LongInt, Comp   64      yes
            Byte                    Byte             8       no
            Word                    ShortWord       16       no
              -                     Word            32       no
              -                     LongWord        64       no

     (1) The size of the GNU Pascal types may depend on the platform.
     The sizes above currently apply to most platforms, including the
     x86.

     If you care for types with exactly the same size as in Borland
     Pascal, take a look at the `System' unit and read its comments.

     You can also declare types with a specific size, and you can get
     the size of a type with `SizeOf' in bytes (like in Borland Pascal)
     or `BitSizeOf' in bits., e.g.

          type
            MyInt  = Integer (42);  { 42 bits, signed }
            MyWord = Word (2);      { 2 bits, unsigned, i.e. 0 .. 3 }
            MyCard = Cardinal (2);  { the same }
          
            HalfInt = Integer (BitSizeOf (Integer) div 2); { A signed integer type
              whose size is half as big as that of the normal Integer is regardless
              how big Integer will be on any platform the program is compiled on. }

   * Borland's Real types are supported except for the 6-bytes software
     Real; GNU's `Real' has 8 bytes and is the same as `Double'.  In
     addition there are alternative names for real types:

            Borland Pascal          GNU Pascal
          
            Single                  Single, ShortReal
            Real                      -
            Double                  Double, Real
            Extended                Extended, LongReal
            Comp                    Comp, LongInt

   * Complex numbers:  According to Extended Pascal, GNU Pascal has
     built-in complex numbers.

   * Record types: GNU Pascal by default alignes 32-bit fields on 4-byte
     addresses because this improves performance.  The record
            Type
              myRec = record
                f, o, oo: Boolean;
                Bar: Integer;
              end (* myRec *);
     has 8 bytes, not 7.  Use the `--pack-struct' option or declare the
     record as `packed' to force GPC to pack it to 7 bytes; see *Note
     Code Gen Options::.

   * In addition to Borland's procedural types, GNU Pascal has pointers
     to procedures:

              Type
                FuncPtr = ^Function ( Real ): Real;

     Furthermore, GNU Pascal supports Standard Pascal's procedural
     parameters--see below.


File: gpc.info,  Node: Files,  Next: Built-in constants,  Prev: Data types in BP and GPC,  Up: Borland Pascal

Files
=====

   * Files like in Borland Pascal, including untyped files, `BlockRead',
     `BlockWrite' and `Assign' are supported by GPC. Instead of
     `Assign', you can also use the "Bind" mechanism of Extended Pascal.


File: gpc.info,  Node: Built-in constants,  Next: Built-in operators in BP and GPC,  Prev: Files,  Up: Borland Pascal

Built-in constants
==================

   * `MaxInt', `MaxLongInt', `Pi' constants:  built-in.

   * Other built-in constants:  GNU Pascal has `MaxChar', `MaxReal',
     and `MinReal'.


File: gpc.info,  Node: Built-in operators in BP and GPC,  Next: Built-in Procedures and Functions,  Prev: Built-in constants,  Up: Borland Pascal

Built-in operators in BP and GPC
================================

   * Exponentiation:  According to Extended Pascal, GNU Pascal supports
     exponentiation operators `pow' and `**' which do not exist in
     Borland Pascal.  You can use `x pow y' for integer and `x ** y'
     for real or complex exponents; the basis may be integer, real or
     complex in both cases.

   * Address operator:  GNU Pascal accepts Borland's `@', but also `&'
     as an address operator.

   * GNU Pascal has a symmetric set difference operator `set1 >< set2'.
     For more about this, see *Note Extensions::.


File: gpc.info,  Node: Built-in Procedures and Functions,  Next: Parameters,  Prev: Built-in operators in BP and GPC,  Up: Borland Pascal

Built-in Procedures and Functions
=================================

   * `GetMem' and `FreeMem':  `GetMem' can also act as a function in
     GNU Pascal:

            p:= GetMem ( 1024 );

     The second parameter to `FreeMem' is ignored by GNU Pascal and may
     be omitted.  Memory blocks are always freed with the same size
     they were allocated with.

     Remark: Extended Pascal Schema types provide a cleaner approach to
     most of the applications of `GetMem' and `FreeMem'.

   * `Min' and `Max':  GNU Pascal has built-in `Min' and `Max'
     functions (two arguments) which work for all ordinal types
     (`Integer', `Char', ...) plus `Real'.

   * `UpCase', `High', `Low' functions:  built-in.

   * `Lo', `Hi', `Swap' functions:  not built-in, but available in the
     `System' unit.


File: gpc.info,  Node: Parameters,  Next: Miscellaneous,  Prev: Built-in Procedures and Functions,  Up: Borland Pascal

Parameters
==========

   * Untyped Var parameters can be denoted by

            Procedure Foo ( Var x );

     like in Borland Pascal.  In GNU Pascal, you can also use

            Procedure Foo ( Var x: Void );

   * GNU Pascal defines "ellipsis" parameters for variable argument
     lists,

            Procedure Foo ( a: Integer; ... );

     but does not (yet) provide a portable mechanism to access the
     additional arguments.

   * Structured function return values:  According to Extended Pascal,
     GNU Pascal allows structured function return values.

   * Open array parameters
            Procedure Foo ( a: array of Integer );
     are implemented.  However, Standard Pascal conformant array
     parameters (only partially implemented) are a "cleaner" mechanism
     to pass arrays of variable size.

   * GNU Pascal supports Standard Pascal's procedural parameters:

            Procedure DrawGraph ( Function f ( x: Real ): Real );


File: gpc.info,  Node: Miscellaneous,  Prev: Parameters,  Up: Borland Pascal

Miscellaneous
=============

   * Headlines:  According to Extended Pascal, a Program headline must
     contain the program's parameters:

              Program Foo ( Input, Output );

     In GNU Pascal, headline parameters are optional.  If the headline
     is omitted entirely, a warning is given unless you have specified
     `--borland-pascal' in the command line.

   * Case statements:  In a case statement, GNU Pascal has `otherwise'
     as an alternative to `else' (according to Extended Pascal):

            case x of
              1: writeln ( 'one' );
              2: writeln ( 'two' );
              otherwise writeln ( 'many' );
            end (* case *);

     If there are two ore more statements following `otherwise', they
     must be grouped with `begin' and `end'.

   * Char constants: Character constants like `^M' as well as `#13' are
     implemented into GNU Pascal.

   * Sets: GNU Pascal has a `Card' function for sets which counts their
     elements.

   * Inline:  GNU Pasccal allows "inline" Procedures and Functions,
     while Borland Pascal only allows machine code to be inlined:

     Borland Pascal:

            Function Max ( x, y: Integer ): Integer;
            Inline ( $58 / $59 / $3B / $C1 / $7F / $01 / $91 );

     GNU Pascal:

            Inline Function Max ( x, y: Integer ): Integer;
          
            begin (* Max *)
              if x > y then
                Max:= x
              else
                Max:= y;
            end (* Max *);

     (Actually, a more general Max is already built-in.)

     This feature is not so important as it might seem because in
     optimization level 3 (see above), GNU Pascal automatically
     "inlines" short procedures and functions.


File: gpc.info,  Node: GPC bugs,  Next: Support,  Prev: Borland Pascal,  Up: Top

Known bugs and inconveniences; how to report bugs
*************************************************

   The GNU Pascal Compiler (GPC) does not yet implement the whole ISO
10206 Extended Pascal standard, not even the whole ISO 7185 Pascal
standard.  It is only partially compatible to Borland Pascal and
implements only some isolated features from the PXSC standard.
Furthermore, there are some known bugs which will take a long time to
be fixed.  (Any help welcome!)  Please take this into account when you
consider using GPC for any purpose.

   If you encounter a bug with GPC, please check whether it is one of
the known bugs.  If not, report it to the GNU Pascal mailing list
`gpc@hut.fi'.  (But always report it if you solve the problem! ;-)

General bugs
============

   * High optimization levels do not work properly on the Alpha.  Some
     conformance tests *fail* when compiled with `-O6' flag, which
     means that the compiler generates invalid code. Don't use this
     flag in the Alpha before the problem gets fixed.  It might have
     something to do with automatic inlining, but I have not yet looked
     at this. `-O' flag should be ok.  (Also take care when using
     explicit inline functions.)

   * Run time errors are not checked in most cases.

   * For some reason the Pascal main program does not get lineno stabs,
     so it is hard to debug it with `gdb' ...

   * The set code generated in the Alpha causes runtime errors in the
     generated code.

   * There are some bugs with mathematical functions.  GPC fails, for
     example, the "Paranoia" test.

Standard Pascal
===============

   * Type checking is mostly what C does, not what Pascal requires, so
     GPC does not yet implement a strongly typed language.  Although
     correct programs compile, incorrect ones compile also.  Please
     send us such incorrect programs, so we can fix it!

Extended Pascal
===============

   * Initialized structured variables are not yet implemented.

   * Illegal substrings let crash the program rather than triggering a
     runtime error:
            str:='1234567890';
            i:=8; j:=13;
            str:=str[i..j];
     This is one case where runtime errors should be caught, but are
     not.

Borland Pascal
==============

   See also: *Note Borland Pascal::QuickStart Guide for Borland Pascal
users.

   * Strings are implemented in a completely different way.  They are
     not limited to 255 characters with the length being in position
     zero, but they are "Schema types" which is something more
     complicated.

   * Most of Borland Pascal's System Unit is not implemented, e.g.
     `move', `FillChar', `BlockRead', `BlockWrite', `Assign',
     String-related functions, ...

     *Workaround:* Some of the missing procedures and functions are
     implemented in a separate compatibility Unit.  Check the `contrib'
     subdirectory of your GPC distribution.

   * The inline assember does not understand Borland syntax.

   * There is no `private' directive for Objects yet.

   * There is no `Inline' in Borland sense.

GNU Extensions
==============

   * The Run Time System (RTS) does not know about modified types such
     as `__byte__' or `__unsigned__ Integer's or `__long__ Real's.
     Especially, you cannot `writeln' such variables.

     *Workaround:* Cast them to their basis type before `writeln', e.g.
            Type
              Extended = __long__ Real;
          
            Var
              foo: Extended;
          
            [...]
          
            writeln ( Real ( foo ) );

Inconveniences
==============

   * The GNU debugger, `gdb', does not yet understand Pascal sets,
     files or subranges.  Now `gdb' allows you to debug these things,
     even though it does not yet understand some stabs.

   * Files of integer subranges that would fit in a byte do not;
     instead they are handled as files of integer.  This is especially
     annoying with `file of 0..255'.

Notes for debugging
===================

   * Forward referencing pointers generate `dbx' style debugging symbols
     by outputting the `.stabs' as an unknown pointer and later it just
     outputs the same `.stabs' again, but this time it also tells what
     type the pointer points to.  This seems to work for `gdb'. As of
     this writing I have not checked what happens with `sdb' type
     debugging info.  It might be that the pointer is left to be a
     `(void *)' pointer, so you have to cast it in order to output the
     object the pointer points to.

     Also, we have not tried any other debugger than `gdb'.  If you do,
     please let us know what happens.

     I think that GDB does not yet support the kind of `.stabs' that
     should be used to do this correctly:

            .stabs ":tANUMBER=BNUMBER", WHATEVER

     where ANUMBER is the unknown pointer type referenced earlier, and
     the BNUMBER is the type which ANUMBER actually is.  This construct
     is not required in C.

   * When debugging, please note that the Initial Letter In Each
     Identifier Is In Upper Case And The Rest Are In Lower Case.  If
     you wish to call C-routines declare them with the "C" directive,
     as follows:

          Procedure FooBAR(i:integer);c;

     This makes the external name to be `_foobar' (replace `_' with you
     machine prefix).

          Procedure FooBAR(i:Integer); External;

     Uses external name `_Foobar'.

          Procedure FooBAR(i:Integer); AsmName 'FooBAR';

     Uses external name `_FooBAR'.

     It is done like this to reduce name clashes with `libc.a' and
     other possible libraries.

   * All visible GPC runtime system library routines are named `_p_...'.

   * The main program name is preceeded by `program_'.  For example,
     `Program FOO' yields the external name `program_Foo' for the main
     program.  This is done because ISO Standard wants to have the
     program name in a separate name space.


File: gpc.info,  Node: Support,  Next: How to Contribute,  Prev: GPC bugs,  Up: Top

Where to get support for GNU Pascal
***********************************

   GPC is free software and comes *without any warranty*.  You have not
paid to get a license to use GNU Pascal so you cannot expect to get
phone support etc. except you pay an individual or a company to provide
such a service.

   To find such an individual or company, look into the GNU Service
Directory which is a list of people who offer support and other
consulting services.  It is in the file `SERVICE' in the GNU GCC
distribution and in the GNU Emacs distribution,
`/pub/gnu/GNUinfo/SERVICE' on a GNU FTP host, and
`http://www.gnu.ai.mit.edu/prep/service.html' in the World Wide Web.
Contact the Free Software Foundation (FSF) to get a copy or to be
listed in it (see *Note Copying:: for the address).

   In addition, you can try to find support in the Internet.  The first
address is the GNU Pascal mailing list, `gpc@hut.fi'.  To join the
list, send an e-mail to `gpc-request@hut.fi'.

   You can also ask the Usenet newsgroups for help.  There is no
specialized newsgroup for GNU Pascal, so use that one which is most
appropriate for your problem.  When in doubt, we recommend
`news://comp.lang.pascal.misc'.

   *Never forget:* Everybody who is working on GNU Pascal and answering
your questions is doing that in his free time without getting any
salery for this.  Please honor our work by contributing yours.  When
somebody has solved your problems in a newsgroup watch out for other
people's problems you can help to solve.

