The GNU Pascal Manual

GNU Pascal

This manual documents how to run, install and maintain the GNU Pascal Compiler (GPC), as well as its new features and incompatibilities, and how to report bugs. It corresponds to GPC 20060325 (GCC 2.8.1, 2.95.x, 3.2.x, 3.3.x or 3.4.x).

Introduction:

• Welcome: Welcome to GNU Pascal ...
• Highlights: Some of GPC's most interesting features.
• News: New Features of GNU Pascal.
• FAQ: The GNU Pascal Frequently Asked Questions List.

Installation:

• Installation: How to download, compile and install GNU Pascal.

Using GNU Pascal:

• Invoking GPC: Command Line Options supported by GNU Pascal.
• Programming: The Programmer's Guide to GPC.
• Borland Pascal: A QuickStart Guide from Borland Pascal to GNU Pascal.
• Reference: The Alphabetical GPC Language Reference.
• Keywords: Pascal keywords and operators supported by GNU Pascal.
• Support: Where to get support for GNU Pascal; how to report bugs.

Development:

• To Do: The GNU Pascal To-Do List.
• Internals: How to get more information from the GPC source itself.

Licenses:

• Copying: The GNU General Public License -- Your rights and duties when using GPC.
• Library Copying: The GNU Lesser General Public License -- Your rights and duties when using certain libraries.
• Demo Copying: GPL with exception -- Your rights and duties when using or modifying the demo programs.

Appendix:

• Acknowledgments: Contributors to GNU Pascal.
• Resources: Resources For Use With GPC.
• GNU: The GNU Project.
• Index-GPC: Index of concepts and symbol names (incomplete).

Welcome to GNU Pascal ...

the free 32/64-bit Pascal compiler of the GNU Compiler Collection (GNU CC or GCC). It combines a Pascal front-end with the proven GCC back-end for code generation and optimization. Other compilers in the collection currently include compilers for the Ada, C, C++, Objective C, Chill, FORTRAN, and Java languages. Unlike utilities such as p2c, this is a true compiler, not just a converter.

This version of GPC corresponds to GCC version 2.8.1, 2.95.x, 3.2.x, 3.3.x or 3.4.x.

The purpose of the GNU Pascal project is to produce a Pascal compiler (called GNU Pascal or GPC) which

• combines the clarity of Pascal with powerful tools suitable for real-life programming,
• supports both the Pascal standard and the Extended Pascal standard as defined by ISO, ANSI and IEEE (ISO 7185:1990, ISO/IEC 10206:1991, ANSI/IEEE 770X3.160-1989),
• supports other Pascal standards (UCSD Pascal, Borland Pascal, parts of Borland Delphi, Mac Pascal and Pascal-SC) in so far as this serves the goal of clarity and usability,
• may be distributed under GNU license conditions, and
• can generate code for and run on any computer for which the GNU C compiler can generate code and run on.

Pascal was originally designed for teaching. GNU Pascal provides a smooth way to proceed to challenging programming tasks without learning a completely different language.

The current release implements Standard Pascal (ISO 7185, levels 0 and 1), most of Extended Pascal (ISO 10206, aiming for full compliance), is highly compatible to Borland Pascal (version 7.0), has some features for compatibility to other compilers (such as VAX Pascal, Sun Pascal, Mac Pascal, Borland Delphi and Pascal-SC).

It provides a lot of useful GNU extensions not found in other Pascal compilers, e.g. to ease the interfacing with C and other languages in a portable way, and to work with files, directories, dates and more, mostly independent of the underlying operating system.

Included units provide support for regular expressions, arithmetic with integer, rational and real numbers of unlimited size, internationalization, inter-process communication, message digests and more. Demo programs show the usage of these units and of many compiler features.

This manual contains

• an overview of some of GPC's most interesting features, see Highlights,
• a list of new features since the last release, see News,
• the GNU Pascal Frequently Asked Questions List, see FAQ,
• installation instructions, see Installation,
• a QuickStart Guide for programmers used to the Turbo Pascal/Borland Pascal compiler, see Borland Pascal,
• a list of command-line options to invoke the compiler, see Invoking GPC,
• the Programmer's Guide to GPC, describing the Pascal programming language in general and GPC specifc aspects, see Programming,
• the alphabetical GPC language reference, see Reference,
• a list of keywords and operators supported by GNU Pascal, see Keywords,
• information on how to report bugs in GNU Pascal and how to get support, see Support,
• the list of known bugs and things to do, also listing bugs fixed and features implemented recently, see To Do,
• some information for those who are interested in how GNU Pascal works internally, see Internals,
• a list of contributors which tells you who developed and is maintaining GNU Pascal, see Acknowledgments,
• the GNU General Public License which informs you about your rights and responsibilites when using, modifying and distributing GNU Pascal, see Copying,
• and other texts about Free Software and the GNU Project intended to answer questions like “what is GNU?” you might have in mind now, see GNU.

If you are familiar with Standard Pascal (ISO 7185) programming, you can probably just go ahead and try to compile your programs. Also, most of the ISO Extended Pascal Standard (ISO 10206) is implemented into GNU Pascal. The Extended Pascal features still missing from GPC are set types with variable bounds and discriminated ordinal schema as schema discriminants.

If you are a Borland Pascal programmer, you should probably start reading the QuickStart guide from BP to GNU Pascal, see Borland Pascal. If you are curious about the new features GPC offers, you can get an idea in the overview of GPC highlights (see Highlights), and read in more detail about them in the Programmer's Guide to GPC (see Programming) and in the alphabetical GPC Language Reference (see Reference).

And, please, think about how you can contribute to the GNU Pascal project, too. Please support our work by contributing yours in form of example programs, bug reports, documentation, or even actual improvements of the compiler.

All trademarks used in this manual are properties of their respective owners.

1 Some of GPC's most interesting features.

The GNU Pascal Compiler (GPC) is, as the name says, the Pascal compiler of the GNU family (http://www.gnu.org/software/gcc/). This means:

• GPC is a 32/64 bit compiler,
• does not have limits like the 64 kB or 640 kB limit known from certain operating systems – even on those systems –,
• runs on all operating systems supported by GNU C, including
  • GNU Hurd,
  • Linux on Intel, AMD64, Sparc, Alpha, S390, and all other supported types of hardware,
  • the BSD family: FreeBSD, NetBSD, OpenBSD,
  • DOS with 32 bits, using DJGPP or EMX,
  • MS-Windows 9x/NT, using CygWin or mingw or MSYS,
  • OS/2 with EMX,
  • Mac OS X,
  • MIPS-SGI-IRIX,
  • Alpha-DEC-OSF,
  • Sparc-Sun-Solaris,
  • HP/UX,

  and more (note: the runtime system only supports ASCII based systems; that includes almost all of today's systems, but a few IBM machines still use EBCDIC; on those, the compiler might run, but the runtime support might need major changes),

• can act as a native or as a cross compiler between all supported systems,
• produces highly optimized code for all these systems,
• is Free Software (Open-Source Software) according to the GNU General Public License,
• is compatible to other GNU languages and tools such as GNU C and the GNU debugger.

The compiler supports the following language standards and quasi-standards:

• ISO 7185 Pascal (see Resources),
• most of ISO 10206 Extended Pascal,
• Borland Pascal 7.0,
• parts of Borland Delphi, Mac Pascal and Pascal-SC (PXSC).

Some highlights:

• From Standard Pascal: Many popular Pascal compilers claim to extend Standard Pascal but miss these important features.
  • Conformant array parameters – the standardized and comfortable way to pass arrays of varying size to procedures and functions. [Example]
  • Passing local procedures as procedural parameters – with full access to all variables of the “parent” procedure. [Example]
  • Automatic file buffers and standard `Get' and `Put' procedures. Read ahead from files without temporary variables. [Example] This allows you, for instance, to validate numeric input from text files before reading without conversion through strings. [Example]
  • True packed records and arrays. Pack 8 Booleans into 1 byte. [Example]
  • Internal files. You don't have to worry about creating temporary file names and erasing the files later. [Example]
  • Global `goto'. (Yes, `goto' has its place when it is not restricted to the current routine.) [Example]
  • Automatically set discriminants of variant records in `New'. [Example]
  • Sets of arbitrary size. [Example]
• From Extended Pascal:
  • Strings of arbitrary length. [Example]
  • `ReadStr' and `WriteStr'. Read from and write to strings with the full comfort of `ReadLn'/`WriteLn'. [Example]
  • System-independent date/time routines. [Example]
  • Set member iteration: `for Ch in ['A' .. 'Z', 'a' .. 'z'] do ...' [Example]
  • Set extensions (symmetric difference, `Card')
  • Generalized `Succ' and `Pred' functions (foo := Succ (bar, 5);).
  • Complex numbers. [Example] [Example]
  • Exponentiation operators (`pow' and `**') for real and complex numbers.
  • Initialized variables. [Example]
  • Structured value constructors – build array or record values without using temporary variables.
  • Functions can return array or record values.
  • Result variables. [Example]
  • Modules.
  • Non-decimal numbers in base 2 through 36: `base#number'.
  • `MinReal', `MaxReal', `EpsReal', `MaxChar' constants.
  • Schemata – the Pascal way to get dynamic arrays without dirty tricks. [Example]
  • Local variables may have dynamic size. [Example]
  • Array Slice Access – access parts of an array as a smaller array, even on the left side of an assignment [Example]
• Compatible to Borland Pascal 7.0 with objects (BP):
  • Supports units, objects, ..., and makes even things like `absolute' variables portable. [Example]
  • Comes with portable versions of the BP standard units with full source.

  • (PNG, 21 kB)

    True network-transparent CRT unit: You can run your CRT applications locally or while being logged in remotely, without any need to worry about different terminal types. Compatible to BP's unit, but with many extensions, such as overlapping windows. [Example]
  • Fully functional GUI (X11) version of CRT (also completely network transparent).
    
  • The `Random' function can produce the same sequence of pseudo-random numbers as BP does – if you need that instead of the much more elaborate default algorithm.
  • Supports BP style procedural variables as well as Standard Pascal's procedural parameters. [Example]
  • A `Ports' unit lets you access CPU I/O ports on systems where this makes sense. [Example]
  • Special compatibility features to help migrating from BP to GPC, like a `GPC for BP' unit which provides some of GPC's features for BP, and some routines to access sets of large memory blocks in a uniform way under GPC and BP (even in real mode). [Example]
  • Comes with a BP compatible `binobj' utility. [Example]
• From Borland Delphi:
  • `abstract' object types and methods
  • classes
  • `is' and `as' operators to test object type membership
  • Comments with `//'
  • Empty parameter lists with `()'
  • Assertions
  • A `SetLength' procedure for strings makes it unnecessary to use dirty tricks like assignments to the “zeroth character”.
  • `Initialize' and `Finalize' for low-level handling of variables.
  • `initialization' and `finalization' for units.
• From Pascal-SC (PXSC):
  • User-definable operators. Add your vectors with `+'.
• Carefully designed GNU extensions help you to make your real-world programs portable:
  • 64-bit signed and unsigned integer types.
  • Special types guarantee compatibility to other GNU languages such as GNU C. Directives like `{$L foo.c}' make it easy to maintain projects written in multiple languages, e.g., including code written in other languages into Pascal programs [Example (Pascal part)] [Example (C part)],
  • or including Pascal code into programs written in other languages. [Example (Pascal part)] [Example (Pascal unit)] [Example (C part)]
  • Extensions like `BitSizeOf' and `ConvertFromBigEndian' help you to deal with different data sizes and endianesses. [Example]
  • Little somethings like `DirSeparator', `PathSeparator', `GetTempDirectory' help you to write programs that look and feel “at home” on all operating systems.
  • The `PExecute' routine lets you execute child processes in a portable way that takes full advantage of multitasking environments. [Example] [Example]
  • The GNU GetOpt routines give you comfortable access to Unix-style short and long command-line options with and without arguments. [Example]
  • Routines like `FSplit' or `FSearch' or `FExpand' know about the specifics of the various different operating systems. [Example]
  • The `FormatTime' function lets you format date and time values, according to various formatting rules. [Example]
• Useful and portable GNU standard units:
  • A `Pipes' unit gives you inter-process communication even under plain DOS. [Example] [Demo process for the example]
  • With the `RegEx' unit you can do searches with regular expressions. [Example]
  • The GNU MultiPrecision (`GMP') unit allows you to do arithmetics with integer, real, and rational numbers of arbitrary precision. [Example: factorial] [Example: fibonacci] [Example: power] [Example: real power] [Example: pi]
  • Posix functions like `ReadDir', `StatFS' or `FileLock' provide an efficient, easy-to-use and portable interface to the operating system. [Example] [Example] [Example]
  • A `DosUnix' unit compensates for some of the incompatibilities between two families of operating systems. [Example]
  • An `MD5' unit to compute MD5 message digests, according to RFC 1321. [Example]
  • A `FileUtils' unit which provides some higher-level file and directory handling routines. [Example]
  • A `StringUtils' unit which provides some higher-level string handling routines. [Example]
  • An `Intl' unit for internationalization. [Example] [Example]
  • A `Trap' unit to trap runtime errors and handle them within your program. [Example]
  • A `TFDD' unit that provides some tricks with text files, e.g. a “tee” file which causes everything written to it to be written to two other files. [Example]
  • A `HeapMon' unit to help you find memory leaks in your programs.

The demo programs mentioned above are available both on the WWW and in GPC source and binary distributions.

Disadvantages:

• The GNU debugger (GDB) still has some problems with Pascal debug info.
• Compilation with GPC takes quite long.

Co-workers welcome!

Able, committed programmers are always welcome in the GNU Pascal team. If you want to be independent of companies that you have to pay in order to get a compiler with more restrictive licensing conditions that only runs on one operating system, be invited to join the development team, Acknowledgments.

2 New Features of GNU Pascal.

GPC's new or changed features since the last (non alpha/beta) GPC release are listed here. Items without further description refer to new routines, variables or options.

Features implemented for compatibility to other compilers are marked with, e.g., `(B)' for BP compatibility.

A few old and obsolete features have been dropped or replaced by cleaner, more flexible or otherwise more useful ones. This might lead to minor problems with old code, but we suppose they're rare and easy to overcome. Backward-incompatible changes are marked with `(@)'.

• preliminary support for gcc-4.0.x
• handle named exit from a method
• check string parameters more strictly (@)
• use at least integer precision for arithmetic (@)
• refuse `--executable-file-name' on names without a suffix
• do not create `.gpi' files from incorrect input
• `CWordBool' type
• allow passing variant selector by reference in default mode
• `noinline' attribute
• check for identifier redeclaration in records and parameter lists (@)
• set constants are compatible with packed sets
• `ReadString' and `StringOf' predefined routines (M)
• pass discriminated string schema by value (@)
• `const var' parameters
• preliminary support for OOE class views (test/view1[a-g].pas)
• `--iso-goto-restrictions' option
• `--preprocessed' option
• integrated preprocessor (@)
• `--longjmp-all-nonlocal-labels' is on by default on Darwin/PPC
• preliminary support for Delphi classes and Mac objects (D) (M) (delphi1[bc].pas, peter5[a-g].pas)
• new options `--[no]-objects-require-override', `--[no]-delphi-method-shadowing', `--[no]-objects-are-references' (off by default) (D) (M)
• new options `--gnu-objects' (default), `--ooe-objects', `--mac-objects', `--borland-objects' which choose object model
• `uses' can not directly follow `import' (@)
• handle `+' and `-' as Mac Pascal does (M) (@)
• new options `--[no]-nonlocal-exit' (default in `--ucsd-pascal' and `--mac-pascal') (fjf988[fijk].pas, fjf1062*.pas) (U) (M)
• new options `--[no]-object-checking' (on by default) to check on virtual method calls if VMT pointer is not nil and has matchin `Size' and `NegatedSize' entries, new options `--[no]-range-and-object-checking' which are now equivalent to `$R[+-]' (fjf1053*.pas) (B)
• new options `--[no]-pointer-checking', `--[no]-pointer-checking-user-defined'; new variable `ValidatePointerPtr' (fjf1052*.pas, pcerrorc.pas) (these options are off by default!)
• new options `--[no]-implicit-result' (fjf1022*.pas) (on by default only in `--delphi' mode!) (D) (@)
• new options `--{en,dis}able-predefined-identifier' (fjf1037*.pas)
• `import' within a routine (mod15[c-e].pas)
• the option `--no-debug-info' was renamed to `--disable-debug-info', and `--no-default-paths' was renamed to `--disable-default-paths' (@)
• qualified identifiers (chief18.pas, fjf260*.pas, fjf921*.pas, grp1.pas, kurzw1.pas, mod{9,10,13..17}*.pas) (@)
• with `-Wnested-comments' and without `--nested-comments' warn about comment openers found within comments (fjf1017*.pas)
• new options `--[no-]case-value-checking' (fjf1012*.pas)
• optimize arithmetic with a complex and a real operand <20020118143553.B28837@artax.karlin.mff.cuni.cz>
• range checking <Pine.LNX.4.21.0012091605570.8168-100000@rusty.russwhit.com> (chuck5.pas, fjf446.pas, fjf989*.pas, fjf992*.pas, fsc{01..37}*.pas, miklos1[bc].pas, mir{016,021..028,030..047}*.pas, ole[12]*.pas, russ4*.pas)
• `Exit' with an argument (non-local exits not yet supported) (fjf988*.pas) (U) (M)
• new options `--[no-]propagate-units' (on by default with `--mac-pascal', off in other dialects) (fjf987*.pas) (M); this also covers the item “unit inheritance”
• enable `Pointer' in `--mac-pascal' mode (Mac Pascal has a `Pointer' function which does the same as a type-cast to `Pointer'; though adding `Pointer' as a type allows more, it's backward-compatible) (M)
• `&' and `|' (shortcut `and' and `or') (fjf981*.pas) (M)
• `Leave' and `Cycle' (equivalent to `Break' and `Continue') (avo3.pas) (M)
• optimize `WriteLn (... string_constant)' and `Write (... string_constant, string_constant ...)'
• `BindingType' is now a packed record as EP demands (fjf975a.pas) (E)
• EP structured initializers (fjf964*.pas, fjf967*.pas, fjf968*.pas) (E)
• EP record, array, set values (constdef.pas, fjf966*.pas, fjf971*.pas) (E)
• gp: `PC' now sets the compiler for both Pascal and C unless `CC' is set explicitly
• `Discard'
• `Integer', `Word', `Cardinal' are now equivalent to `PtrInt', `PtrWord', `PtrCard', no more (necessarily) to C's `int' and `unsigned int' (@)
• new types `CInteger', `CWord', `CCardinal'
• new make variable `GPC_PAGESIZE' to set the page size when building the manual (PDF, PostScript, DVI)
• `qualified' and import lists are no more allowed after `uses' (only after `import', as EP demands) (@)
• the `GMP' unit doesn't support gmp-2.x anymore (if you used it, just upgrade to a newer GMP version) (@)
• conflicts between object fields/methods and ancestor type names are detected as required by OOE (fjf945*.pas) (@) (O)
• repeated function headings (in `forward' declarations and interfaces) are checked stricter: if one has a result variable, so must the other (according to the OOE draft) (@) (O)
• the `Pipe' unit was renamed to `Pipes' because of a name conflict (@)
• empty parameter lists can be written as `()' (chief54*.pas, delphi6*.pas) (D)
• GMP unit: `mpf_sin', `mpf_cos'
• the test suite output is now by default stored in DejaGnu compatible files gpc.log and gpc.sum in the p/test/ directory; other available test targets are `pascal.check-short' and `pascal.check-long' (@)
• new options `-W[no-]dynamic-arrays' (fjf931*.pas)
• new argument to `_p_initialize' (@)
• `UMask'
• new option `--no-debug-source'
• new lexer (no directly user-visible difference, but should allow for better handling of lexer-based problems in the future)
• `CompilerAssert' (fjf904*.pas)
• options `--[no]-assert' renamed to `--[no]-assertions' (necessary to avoid a conflict with GCC) (@)
• new options `--[no-]range-checking', also as short compiler directives `{$R+}'/`{$R-}' (default is on) (C, E, B, @)
• new options `--[no-]methods-always-virtual' (fjf903*.pas) (M)
• new options `--[no-]pointer-arithmetic', `--[no-]cstrings-as-strings', `-W[no-]absolute' (all of which `--[no-]extended-syntax' implies)
• `Integer2StringBase', `Integer2StringBaseExt'
• new constants `NumericBaseDigits', `NumericBaseDigitsUpper'
• allow assigning, passing by value and returning objects, with assignments of an object of derived type to one of a base type (chief35[ab].pas, fjf451*.pas, fjf696[ef].pas, fjf884*.pas), BP compatible except for a bug in the BP feature itself (see the comment in p/test/fjf451h.pas) (B)
• new options `-W[no-]object-assignment'
• warn (except in `--borland-pascal') if a virtual method overrides a non-virtual one (chief52*.pas)
• warn when an non-abstract object type has virtual methods, but no constructor (chief51*.pas)
• `--maximum-field-alignment' does not apply to `packed' records
• `ArcSin', `ArcCos'
• trimming string relations as functions (`EQPad' etc.) (fjf873.pas)
• new options `-W[no-]interface-file-name'
• `SeekEOF' and `SeekEOLn' use `Input' implicitly when no file is given (fjf871.pas) (B)
• tagging feature for `with' statements (tom6.pas) <200012022215.eB2MFD614424@wsinpa16.win.tue.nl> (Sun Pascal)
• new option `--sun-pascal'
• field names and array indices in initalizers are recognized (waldek5*.pas) (options `-W[no-]field-name-problem' removed, @)
• object directives `published', `public' (both equivalent), `protected' (scope limited to object type and derived object types), `private' (scope limited to current unit/module) (fjf864*.pas) (options `-W[no-]object-directives' removed, @)
• the operator precedence and associativity of `+' and `-' is now as defined in EP by default (and as in BP with `--borland-pascal') <Pine.LNX.4.44.0210251249500.6181-100000@duch.mimuw.edu.pl> (fjf863*.pas) (@)
• `Integer (16)' etc. changed to `Integer attribute (Size = 16)' (works for integer and Boolean types) (fjf861.pas) (@)
• types can have attributes (note: no preceding `;') (fjf860*.pas)
• dynamic object methods (fjf859.pas) (B)
• in `--borland-pascal' mode, `Assign' unconditionally (re-)initializes its file parameter (fjf858.pas) (B)
• GPC doesn't use gpm files anymore (instead, each module has an implicit modulename-all.gpi interface which is a regular gpi file)
• make the program/module/unit finalizers non-public (`static' in C sense), omit them if easily possible
• new options `-W[no-]parentheses' (fjf848*.pas)
• non-`interface' modules with empty implementation part (pmod1.pas, fjf843.pas)
• `maximum-field-alignment' and `[no-]field-widths' work as local compiler directives now (fjf842.pas)
• dropped `{$debug-statement}' (should not be necessary anymore, now that debug info mostly works)
• new options `--[no-]longjmp-all-nonlocal-labels'
• object methods can have attributes (fjf826*.pas)
• new attributes `iocritical' (fjf824*.pas), `ignorable' (fjf839*.pas) for routines
• dropped computed `goto' (never worked for nonlocal `goto' into the main program, implementing it would be quite difficult, probably not worth it) (@)
• new type `AnyFile' for parameters and pointer targets (fjf821*.pas)
• `TimeStamp' is now a packed record as EP demands (fjf975b.pas) (E)
• Mac Pascal specific features are supported according to the dialect options (M)
• `--interface-only' does not require `-S' or `-c' anymore (and does not create an object file)
• `initialization', `finalization' (D)
• `TimeZone' in `TimeStamp' counts seconds east of UTC now (not west, as before) (datetimedemo.pas) (@)
• `export Foo = all (...)' (fjf811*.pas)
• new options `-W[no-]local-external' (implied by `-Wall')
• type-casts are BP compatible now, in particular, value type-casts between ordinal and real or complex types don't work anymore (B) (@)
• all non-ISO-7185 keywords can be used as identifiers (with two small exceptions) (fjf440.pas)
• `pack-struct' does not imply bit-level packing anymore (only explicit `packed' records and arrays do) (@)
• new options `--[no-]ignore-packed' (`--ignore-packed' is the default in BP mode) (fjf796*.pas) (B) (@)
• new option `--maximum-field-alignment=N'
• new options `{$[no-]pack-struct}' as a compiler directive
• `attribute' for routines doesn't imply `forward' anymore (so you don't have to declare routines twice in a program or implementation part when setting the linker name or some other attribute) (@)
• `static', `volatile' and `register' for variables and `inline' for routines are no prefix-directives anymore, but `attribute's (@)
• combining several dialect options (such as `--extended-pascal --borland-pascal') doesn't work anymore (what should this mean, anyway? Combine the features, but also the warnings from both!?!?!?) (@)
• `external' without `name' defaults to all-lowercase now (@)
• `c', `c_language' and `asmname' are deprecated (@)
• `external name 'foo'' (fjf780.pas), `external 'libname' name 'foo'' (where `libname' is ignored) (B)
• Mac Pascal directives `definec', `macro', `undefc', `ifc', `ifoptc', `elsec', `elifc', `endc', `errorc' (treated as equivalent to the corresponding existing ones) (M)
• units without `implementation' part (M)
• new options `--vax-pascal', `--mac-pascal'
• attributes `const' for variables and `name' for variables, routines and modules; assembler names and module/unit file names can now be expressions (which must yield string constants) (fjf781*.pas, fjf809*.pas)
• the utilities `gpidump' and `binobj' are installed with GPC (B)
• new options `-W[no-]identifier-case', `-W[no-]identifier-case-local' (fjf751*.pas)
• new compiler directive `$R foo', equivalent to `$L foo.resource' (B)
• dropped `--[no-]borland-char-constants' (now simply coupled to dialect options) (@)
• test suite: support progress messages (`TEST_RUN_FLAGS=-p' from the Makefile; `-p' in testgpc); see http://fjf.gnu.de/misc/progress-messages.tar.gz
• `=' and `<>' comparisons of structures (arrays, records, ...) except strings and sets are forbidden now (@) (E)
• irrelevant operands and arguments (e.g.: `foo in []'; `bar * []'; `Im (baz)' if `baz' is of real type) are not necessarily evaluated anymore (which is allowed by the standard); instead, a warning is given if they have side-effects (@)
• accept only one program, unit, module interface or implementation or a module interface and the implementation of the same module in one file; new options `--[no-]ignore-garbage-after-dot' (fjf735*.pas) (@)
• new options `-W[no-]implicit-io' (fjf734*.pas)
• new options `--enable-keyword', `--disable-keyword' (fjf733*.pas)
• `CBoolean' (fjf727.pas)
• dropped the usage of `GetMem' as a function with one parameter (only the BP compatible usage as a procedure with two parameters remains) (@)
• accessing the variable `FileMode' now requires using the `GPC' (or, for BP compatibility, the `System') unit (@)
• `DupHandle'
• dropped the predefined dialect symbols `__CLASSIC_PASCAL__', `__STANDARD_PASCAL__', `__EXTENDED_PASCAL__', `__OBJECT_PASCAL__', `__UCSD_PASCAL__', `__BORLAND_PASCAL__', `__DELPHI__', `__PASCAL_SC__' and `__GNU_PASCAL__' (one can use `{$ifopt borland-pascal}' etc. instead) (@)
• `Succ', `Pred', `Inc', `Dec' for real numbers (fjf714*.pas)
• use environment variables `GPC_UNIT_PATH', `GPC_OBJECT_PATH'
• new options `-W[no-]float-equal'
• new option `--ucsd-pascal'
• dropped the syntax `type foo = procedure (Integer, Real)' (i.e., without parameter names) (@)
• CRT: new argument `On' to `CRTSavePreviousScreen'
• `SetUserID', `SetGroupID'
• `HeapChecking'
• new built-in procedure `Assert'; new options `--[no]-assert' (also `{$C+}', `{$C-}' for Delphi compatibility) (fjf665*.pas) (D)
• `ProcessGroup'
• StringUtils: `QuoteEnum'
• `CurrentRoutineName' (fjf752.pas)
• TFDD: new unit
• gpc-run: new options `-e FILE' and `-E FILE' (redirect/append standard error)

Have fun,

The GNU Pascal Development Team

3 The GNU Pascal Frequently Asked Questions List.

This is the Frequently Asked Questions List (FAQ) for GNU Pascal. If the FAQ and the documentation do not help you, you have detected a bug in it which should be reported, Mailing List. Please really do it, so we can improve the documentation.

• GNU Pascal: GNU Pascal
• Installing GPC: Installing GPC
• GPC on DJGPP: GNU Pascal on the DJGPP (MS-DOS) platform
• Strings in GPC: Strings
• Getting Help: Getting Help
• Miscellaneous FAQ: Miscellaneous

3.1 GNU Pascal

• What and why: What and why?
• Current version: What is the current version?
• Turbo Pascal compatibility: Is it compatible with Turbo Pascal (R)?
• Supported platforms: Which platforms are supported by GNU Pascal?

3.1.1 What and why?

The purpose of the GNU Pascal project is to produce a Pascal compiler (called GNU Pascal or GPC) which

• combines the clarity of Pascal with powerful tools suitable for real-life programming,
• supports both the Pascal standard and the Extended Pascal standard as defined by ISO, ANSI and IEEE (ISO 7185:1990, ISO/IEC 10206:1991, ANSI/IEEE 770X3.160-1989),
• supports other Pascal standards (UCSD Pascal, Borland Pascal, parts of Borland Delphi, Mac Pascal and Pascal-SC) in so far as this serves the goal of clarity and usability,
• may be distributed under GNU license conditions, and
• can generate code for and run on any computer for which the GNU C compiler can generate code and run on.

Pascal was originally designed for teaching. GNU Pascal provides a smooth way to proceed to challenging programming tasks without learning a completely different language.

The current release implements Standard Pascal (ISO 7185, levels 0 and 1), most of Extended Pascal (ISO 10206, aiming for full compliance), is highly compatible to Borland Pascal (version 7.0), has some features for compatibility to other compilers (such as VAX Pascal, Sun Pascal, Mac Pascal, Borland Delphi and Pascal-SC).

It provides a lot of useful GNU extensions not found in other Pascal compilers, e.g. to ease the interfacing with C and other languages in a portable way, and to work with files, directories, dates and more, mostly independent of the underlying operating system.

Included units provide support for regular expressions, arithmetic with integer, rational and real numbers of unlimited size, internationalization, inter-process communication, message digests and more. Demo programs show the usage of these units and of many compiler features.

3.1.2 What is the current version?

The current version is 20060325.

Releases are available as a source archive and precompiled binaries for several common platforms from the GPC web site, http://www.gnu-pascal.de.

For details about new features, see the section `News' on the web site. On bugs fixed recently, see the `Done' section of the To-Do list (on the same web site).

GPC uses GCC as a back-end. It supports GCC version 2.8.1, 2.95.x, 3.2.x, 3.3.x or 3.4.x. (The newest supported GCC version is usually preferable, unless it contains serious bugs in itself.)

There are no fixed time frames for new releases. Releases are made when enough interesting changes have been made and the compiler is somewhat stable.

3.1.3 Is it compatible with Turbo Pascal (R)?

GPC is not a drop-in replacement for Borland's Turbo Pascal (R). Almost all BP language features are supported. Notable exceptions are the string format (as discussed below), or the `Mem' and `Port' pseudo arrays, though replacement functions for the latter on IA32 platforms exist in the `Ports' unit.

Almost all of BP's run time library is supported in GPC, either by built-in compiler features or in units with the same names as their BP counterparts.

For details about the compatibility, the few remaining incompatibilities and some useful alternatives to BP features, see the `Borland Pascal' chapter in the GPC Manual. (see Borland Pascal)

3.1.4 Which platforms are supported by GNU Pascal?

GPC uses the GCC backend, so it should run on any system that is supported by GNU CC. This includes a large variety of Unix systems, MS-DOS, OS/2 and Win32. A full list of platforms supported by GCC can be found in the file INSTALL of the GCC distribution. Not all of these have actually been tested, but it is known to run on these platforms:

OK people – send us your success stories, with canonical machine name!

3.2 Installing GPC

You find the most up-to-date installation instructions in the GPC Manual or the file `INSTALL' in source distributions, or on the GPC web site. (see Installation)

The following sections describe things you might need or want to install besides GPC itself.

• Documentation files: What to read next
• Components: Which components do I need to compile Pascal code?
• Debugger: How do I debug my Pascal programs?
• Libraries: What additional libraries should I have?
• Contributed units: Contributed units
• IDE: Can you recommend an IDE?

3.2.1 What to read next

After installing GPC, please check the files in the directory /usr/local/doc/gpc:

3.2.2 Which components do I need to compile Pascal code?

A complete Pascal compiler system should at least have:

1. The actual compiler, GPC.
2. An editor, assembler, linker, librarian and friends.
3. A C library. If you have a working C compiler, you already have this.
4. A debugger, if you want to debug your programs.

For most people, the GNU binutils and GNU debugger (`gdb') are a good choice, although some may prefer to use vendor specific tools.

3.2.3 How do I debug my Pascal programs?

To debug your programs, (a) GNU Pascal must be able to generate executables with debug info for your platform, and (b) you must have a debugger which understands this.

• If `gpc -g -o hello hello.p' says:

            gpc: -g not supported for this platform
       

  then GPC is unable to generate debugging info. Usually, installing `gas' (part of GNU binutils) instead of your system's assembler can overcome this. When you configure the GCC used for GPC, specify `--with-gnu-as', and possibly `--with-gnu-ld' and/or `--with-stabs'. More information can be found in the INSTALL file in the GNU CC source directory.

• Your system's debugger may not understand the debug info generated by GNU tools. In this case, installing `gdb' may help.

The bottom line: if you can debug GCC compiled programs, you should be able to do this with GPC too.

The GNU debugger (`gdb') currently does not have a “Pascal” mode, so it is unable to display certain Pascal structures etc. When debugging, please note that the Initial Letter In Each Identifier Is In Upper Case And The Rest Are In Lower Case. If you want to display variable `foo' in the debugger, type `show Foo' or `display Foo' instead.

Although `gdb' is an excellent debugger, it's user interface is not everybody's preference. If you like to debug under X11, please refer to the comp.windows.x FAQ: “Where can I get an X-based debugger?” at:
http://www.faqs.org/faqs/x-faq/part6/section-2.html

Some useful frontends include: XXGDB, tGDB and XWPE. See:
http://www.ee.ryerson.ca:8080/~elf/xapps/Q-IV.html

Very nice, but resource consuming is the Motif based DDD:
http://sol.ibr.cs.tu-bs.de/softech/ddd/

Furthermore, RHIDE (see IDE) contains built-in debugging suport, similar to the IDE of BP.

3.2.4 What additional libraries should I have?

You will need certain additional libraries when you compile some of the units. These can be found in the directory http://www.gnu-pascal.de/libs/.

Currently, there are the following libraries:

gmp

Arithmetic for integers, rationals and real numbers with arbitrary size and precision. Used by the GMP unit.

rx

Regular expression matching and substitution. Used by the RegEx unit.

ncurses

PDCurses

Screen handling. Used by the CRT unit. Depending on your system, you have the following choices:

Unix: You can compile terminal applications with ncurses and applications that run in an X11 window with PDCurses (though terminal applications can, of course, also run in an xterm under X11). ncurses is used by default. If you want to use PDCurses (a.k.a. XCurses), give the option `-DX11' when compiling CRT.

Dos with DJGPP and MS-Windows with mingw: Only PDCurses is available and will be used by default.

MS-Windows with Cygwin: PDCurses and ncurses are available. PDCurses is used by default. If you want to use ncurses, give the option `-DUSE_NCURSES' when compiling CRT.

Other systems: Please see the READMEs and installation instructions of PDCurses and ncurses to find out which one(s) can be built on your system. See the conditionals at the end of crt.inc and crtc.h (and change them if necessary) on which library is used by default.

intl

Internationalization. Used by the Intl unit. On some systems, it is part of the system library (libc).

ElectricFence

This library is not used by any GPC unit. It is a debugging tool to assist you in finding memory allocation bugs. To use it, just link it to your program, either on the command line (`-lefence') or in the source code (`{$L efence}') which you might want to put into an `{$ifdef DEBUG}' or similar since using libefence is only recommended for debugging.

The source code of the libraries is available in the main `libs' directory. Most libraries come with one or several patches which should be applied before compiling them.

Binaries for some platforms are available in the binary/platform subdirectories. If you compile the libraries for other platforms, be invited to make the binaries available to us for distribution on the web site.

There are also the following files:

terminfo-linux.tar.gz

This is a patch to enable ncurses programs to make use of the ability of Linux 2.2 and newer kernels to produce a block cursor when needed. The present patch can be installed without recompiling anything, just by copying some files into place. More details can be found in the README file included in this archive. The patch will not do any harm on older kernels. Please note that not only on Linux machines it is useful to install the patch. Installing them on any other machine will allow users who telnet in from a Linux console to profit from the block cursor capability. Besides, some Unix systems have installed older Linux terminfo entries or none at all, so it's a good thing, anyway, to give them a current version. The patch is included in the terminfo database of ncurses 5.0, so if you install ncurses 5.0 (source or binary), you don't need to get the patch separately. But you can install it on a system with an older ncurses version if you don't feel like upgrading ncurses altogether.

tsort-2.9i.zip

A little utility (extracted from util-linux-2.9i, but not Linux specific), needed for the configuration of the rx library. You need it only if you compile rx yourself (and if it's not already present on your system), not when using a rx binary.

3.2.5 Contributed units

Several people have contributed units for GPC. They are usually announced on the mailing list, Mailing List. Most of them can be found in http://www.gnu-pascal.de/contrib/.

3.2.6 Can you recommend an IDE?

Users of Borland Pascal may wonder if there's a replacement for the IDE (Integrated Development Environment). Here's a few suggestions:

• (X)Emacs. Some people think it's the answer to the question of Life, the Universe and Everything, others decide it's uGNUsable. Available from your friendly GNU mirror and most distributions.

• PENG. It's not free software, but it was written with GPC. It's very similar to Borland's IDE, but with many extensions. Binaries for DJGPP, Linux and Solaris can be downloaded from http://fjf.gnu.de/peng/.

• RHIDE. DJGPP users might want to try RHIDE. The latest (beta) release is compatible with GNU Pascal and allows stepping, tracing and watching like Borland's IDE. It can be downloaded from http://www.rhide.com.

• DevPascal. DevPascal is a Free Software IDE for mingw32. It can be downloaded from http://www.gnu-pascal.de/contrib/chief/ or http://www.bloodshed.net/devpascal.html

• XWPE is another imitation of the Borland IDE, so users of Borland Pascal may find it a good alternative.

3.3 GNU Pascal on the DJGPP (MS-DOS) platform

This chapter discusses some potential problems with GNU Pascal on MS-DOS, using DJGPP.

• What is DJGPP: What is DJGPP?
• DJGPP FAQ: If you need more information
• DJGPP download: What do I download?
• Installing GPC on DJGPP: How do I install the compiler?
• DJGPP Info reader: I cannot read the Info documentation!
• DJGPP DPMI server: GPC says: no DPMI
• Assembler syntax: I have troubles with assembly code
• DJGPP specific code: Tell me how to do DPMI, BIOS and other DOS related things.
• Stack size: I got an exception when accessing an `array [1 .. 4000000] of Byte'.

3.3.1 What is DJGPP?

The following paragraph is from the site http://www.delorie.com/djgpp/:

DJGPP is a complete 32-bit C/C++ development system for Intel 80386 (and higher) PCs running DOS. It includes ports of many GNU development utilities. The development tools require a 80386 or newer computer to run, as do the programs they produce. In most cases, the programs it produces can be sold commercially without license or royalties.

3.3.2 If you need more information

GPC/DJGPP is a DJGPP V2 application, and most of the DJGPP documentation applies for GPC too. A great source of information is the DJGPP FAQ: http://www.delorie.com/djgpp/v2faq/230b.zip

Another place to look for DJGPP documentation is the DJGPP Knowledge Base, at this URL: http://www.delorie.com/djgpp/doc/kb/

3.3.3 What do I download?

As discussed in Components, other than GPC itself, you need an assembler, linker and friends, a C library and possibly a debugger. The site http://www.delorie.com/djgpp/ recommended the following files and they will help you find a mirror:

This list is about 10 MB not counting GPC. You can use a binary version of GPC from the web site.

3.3.4 How do I install the compiler?

If you don't have DJGPP installed on your harddisk, create a directory for GNU Pascal (c:\gpc), and unzip the archives. Make sure you preserve the directory structure (use `pkunzip -d'). Now, add the directory where gpc.exe lives (c:\gpc\bin) to your path and set the DJGPP environment variable to point to your djgpp.env file:

     set DJGPP=c:\gpc\djgpp.env

Then, add this to your djgpp.env file:

     ---------------------------------------------------------
     [gpcpp]
     C_INCLUDE_PATH=%/>;C_INCLUDE_PATH%%DJDIR%/lang/pascal;%DJDIR%/include
     
     [gpc]
     COMPILER_PATH=%/>;COMPILER_PATH%%DJDIR%/bin
     LIBRARY_PATH=%/>;LIBRARY_PATH%%DJDIR%/lib;%DJDIR%/contrib/grx20/lib
     ---------------------------------------------------------

The GPC online documentation is in GNU info format; you need the Info reader (txi390b.zip) to read it, or use the built-in Info reader of the RHIDE or PENG IDE. To add the GPC documentation to the info directory file, edit the c:\gpc\info\dir file, and locate this section:

     ---------------------------------------------------------
     * GCC: (gcc.inf).
     The GNU C, C++, and Objective-C Compiler
     
     * GDB: (gdb.inf).
     The GNU Debugger (gdb and gdb-dpmi).
     
     ---------------------------------------------------------

To add GPC, change it to look like this:

     ---------------------------------------------------------
     * GCC: (gcc.inf).
     The GNU C, C++, and Objective-C Compiler
     
     * GPC: (gpc.inf).
     The GNU Pascal Compiler
     
     * GDB: (gdb.inf).
     The GNU Debugger (gdb and gdb-dpmi).
     
     ---------------------------------------------------------

Specific information for low-memory conditions and more can be found in the DJGPP FAQ and documentation.

3.3.5 I cannot read the Info documentation!

To read the Info documentation, you need the `info' program from txi390b.zip or an IDE like RHIDE or PENG.

3.3.6 GPC says: no DPMI

You don't have a DPMI server installed, and DJGPP v2 requires it to run. You can either use one of the commercial DPMI servers (e.g., run `gpc' in a DOS box under MS-Windows) or download and install CWSDPMI (csdpmi3b.zip) which is a free DPMI server written for DJGPP.

3.3.7 I have troubles with assembly code

The GNU Assembler (as.exe), or gas, called by GCC accepts “AT&T” syntax which is different from “Intel” syntax. Differences are discussed in section 17.1 of the DJGPP FAQ.

A guide is available which was written by Brennan Mr. Wacko Underwood brennan@mack.rt66.com and describes how to use inline assembly programming with DJGPP, at this URL: http://www.delorie.com/djgpp/doc/brennan/brennan_att_inline_djgpp.html

There's also a GPC assembler tutorial at
http://www.gnu-pascal.de/contrib/misc/gpcasm.zip

Section 17.3 of the DJGPP FAQ discusses some methods to convert “Intel” syntax to “AT&T” syntax.

However, please note that assembler code is unportable, i.e. it will work on IA32 (“x86”) and compatible processors if written for them, but will not even compile for other processors. So by writing assembler code in your programs, you will limit their usefulness substantially.

If you think you “need” assembler code for speed – and you've checked that your assembler code actually runs faster than Pascal code compiled with suitable optimizations – you might want to put both Pascal and assembler versions of the critical sections in your program, and let, e.g., an `{$ifdef i386}' decide which one to use. This way, your program will at least compile on all processors.

3.3.8 Tell me how to do DPMI, BIOS and other DOS related things.

DPMI, BIOS and other functions are no different than other system functions. Refer to the GPC Manual on how to access your system's C-library. This small example shows how to use DPMI, copying some structures and function prototypes of `<dpmi.h>':

     program DPMIDemo;
     
     { Only for DJGPP }
     
     {$X+}
     
     { `Byte' is `unsigned char' in C,
       `ShortCard' is `unsigned short' in C,
       `MedCard' is `unsigned long' in C,
       `Word' is `unsigned' in C,
       etc. (all these types are built-in). }
     
     type
       TDpmiVersionRet = record
         Major     : Byte;
         Minor     : Byte;
         Flags     : ShortCard;
         CPU       : Byte;
         Master_PIC: Byte;
         Slave_PIC : Byte;
       end;
     
     type
       TDpmiFreeMemInfo = record
         LargestAvailableFreeBlockInBytes,
         MaximumUnlockedPageAllocationInPages,
         MaximumLockedPageAllocationInPages,
         LinearAddressSpaceSizeInPages,
         TotalNumberOfUnlockedPages,
         TotalNumberOfFreePages,
         TotalNumberOfPhysicalPages,
         FreeLinearAddressSpaceInPages,
         SizeOfPagingFilePartitionInPages,
         Reserved1,
         Reserved2,
         Reserved3: MedCard;
       end;
     
     function DpmiGetVersion (var Version: TDpmiVersionRet): Integer;
              external name '__dpmi_get_version';
     
     function DpmiGetFreeMemoryInformation
              (var MemInfo: TDpmiFreeMemInfo): Integer;
              external name '__dpmi_get_free_memory_information';
     
     var
       Version: TDpmiVersionRet;
       MemInfo: TDpmiFreeMemInfo;
     
     begin
       if DpmiGetVersion (Version) = 0 then
         begin
           WriteLn ('CPU type:       ', Version.CPU, '86');
           WriteLn ('DPMI major:       ', Version.Major);
           WriteLn ('DPMI minor:       ', Version.Minor);
         end
       else
         WriteLn ('Error in DpmiGetVersion');
       if DpmiGetFreeMemoryInformation (MemInfo) = 0 then
         WriteLn ('Free DPMI memory: ',
                  MemInfo.TotalNumberOfFreePages, ' pages.')
       else
         WriteLn ('Error in DpmiGetMemoryInformation');
     end.

3.3.9 I got an exception when accessing an `array [1 .. 4000000] of Byte'.

Per default, the maximum stack size of a DJGPP application is 256K. If you need more, you have to adjust it with the stubedit program, i.e.:

     stubedit your_app.exe minstack=5000K

Another way is to add the following code to your program to define a minimum stack size (here: 2 MB). This value will be honored even if a user sets a lower value by using stubedit, so this method might be a little safer. (The linker name `_stklen' is essential; the Pascal identifier doesn't matter. The constant doesn't have to be used anywhere in the program. It is recommended to put this declaration in the main program file, not in any unit/module, so programs using a unit/module can set whatever limit they need.)

     {$ifdef __GO32__}
     const
       MinStackSize: Cardinal = $200000; attribute (name = '_stklen');
     {$endif}

Still, it might be a good idea to use pointers for large structures, and allocate the memory at runtime.

DJGPP has to allocate the stack in physical memory at program startup, so one might have to be careful with too large stack limits. Most other systems allocate stack pages on demand, so the only reason to set a limit at all might be to prevent a runaway recursion from eating up all memory ...

On Unix-like systems, you can set a resource limit, but you usually don't do it in normal programs, but rather in the shell settings (bash: `ulimit'; csh: `limit'; syscall: `setrlimit'(2)).

3.4 Strings

• String schema: What's this confusion about strings?
• Strings in variant records: Overlaying strings in variant records
• Length byte: Why does `s[0]' not contain the length?
• Strings as value parameters: Watch out when using strings as parameters
• Short strings: Support for BP compatible short strings
• C strings: What about C strings?

3.4.1 What's this confusion about strings?

Turbo Pascal strings have a length byte in front. Since a byte has the range 0 .. 255, this limits a string to 255 characters. However, the Pascal string schema, as defined in section 6.4.3.3.3 of the ISO 10206 Extended Pascal standard, is a schema record:

     type
       String (Capacity: Integer) = record
         Length: 0 .. Capacity;
         String: packed array [1 .. Capacity + 1] of Char
       end;

The `+ 1' is a GPC extension to make it feasible to automatically add the `#0' terminator when passing or assigning them to CStrings. Thus at the expense of a little added complexity (must declare capacity, don't use `GetMem' without explicit initialization of the `Capacity' field, and the additional space requirement) you can now have very long strings.

3.4.2 Overlaying strings in variant records

Q: Should the different variants in a variant record overlay in the same memory? Previous Pascals I have used have guaranteed this, and I've got low-level code that relies on this. The variants are not the same length, and they are intended not to be.

A: No, this is intentional so that the discriminants are not overwritten, and they can be properly initialized in the first place. Consider:

     record
     case Boolean of
       False: (s1: String (42));
       True:  (s2: String (99));
     end;

If the strings would overlay, in particular their discriminants would occupy the same place in memory. How should it be initialized? Either way, it would be wrong for at least one of the variants ...

So, after a discussion in the ISO Pascal newsgroup where this topic came up concerning file variables (which also require some automatic initialization and finalization), we decided to do this in GPC for all types with automatic initialization and finalization (currently files, objects and schemata, including strings, in the future this might also be Delphi compatible classes and user-defined initialized and finalized types), since the standard does not guarantee variants to overlay, anyway ...

There are two ways in GPC to get guaranteed overlaying (both non-standard, of course, since the standard does not assume anything about internal representations; both BP compatible), `absolute' declarations and variable type casts. E.g., in order to overlay a byte array `b' to a variable `v':

     var
       b: array [1 .. SizeOf (v)] of Byte absolute v;

Or you can use type-casting:

     type
       t = array [1 .. SizeOf (v)] of Byte;

then `t (v)' can be used as a byte array overlayed to `v'.

3.4.3 Why does `s[0]' not contain the length?

Q: In standard Pascal you expect `s[1]' to align with the first character position of `s' and thus one character to the left is the length of `s'. Thus `s[0]' is the length of `s'. True?

A: This holds for UCSD/BP strings (which GPC does not yet implement, but that's planned). The only strings Standard Pascal knows are arrays of char without any length field.

GPC also supports Extended Pascal string schemata (see String schema), but they also don't have a length byte at “position 0”, but rather a `Length' field (which is larger than one byte).

3.4.4 Watch out when using strings as parameters

Q: Any “gotchas” with string parameters?

A: Be careful when passing string literals as parameters to routines accepting the string as a value parameter and that internally modify the value of the parameter. Inside the routine, the value parameter gets a fixed capacity – the length of the string literal that was passed to it. Any attempt to assign a longer value will not work.

This only applies if the value parameter is declared as `String'. If it is declared as a string with a given capacity (e.g., `String (255)'), it gets this capacity within the routine.

3.4.5 Support for BP compatible short strings

Q: Two different kinds of strings with the same name – `String' – does make a bit of confusion. Perhaps the oldstyle strings could be renamed `short string' ?

A: When we implement the short strings, we'll have to do such a distinction. Our current planning goes like this:

`String (n)': string schema (EP compatible)

`String [n]': short string (UCSD/BP compatible, where n must be <= 255)

`String': dependent on flags, by default undiscriminated schema, but in BP mode (or with a special switch) short string of capacity 255 (UCSD/BP compatible).

Q: So when will these short strings be available?

A: It's been planned for some years. The delay has been caused by more pressing problems.

3.4.6 What about C strings?

A C string (`char *') is an array of char, terminated with a `#0' char.

C library functions require C, not Pascal style string arguments. However, Pascal style strings are automatically converted to C style strings when passed to a routine that expects C style strings. This works only if the routine reads from the string, not if it modifies it.

E.g., this is how you could access the `system()' call in your C library (which is not necessary anymore, since `Execute' is already built-in):

     program SysCall;
     
     function System (CmdLine: CString): Integer; external name 'system';
     
     var
       Result: Integer;
     
     begin
       Result := System ('ls -l');
       WriteLn ('system() call returned: ', Result)
     end.

You could use the type `PChar' instead of `CString'. Both `CString' and `PChar' are predefined as `^Char' – though we recommend `CString' because it makes it clearer that we're talking about some kind of string rather than a single character.

A lot of library routines in Pascal for many applications exist in the GPC unit and some other units. Where available, they should be preferred (e.g. `Execute' rather than `system()', and then you won't have to worry about `CString's.)

Do not pass a C style string as a `const' or `var' argument if the C prototype says `const char *' or you will probably get a segfault.

3.5 Getting Help

Please read the GPC Manual (info files or other formats) as well as the README and BUGS files that come with GPC (usually installed in directory /usr/local/doc/gpc), plus other docs that might help (the DJGPP FAQ if you use DJGPP, etc.) before you send email to the maintainers or mailing list.

In particular, the BUGS file contains information on how to submit bug reports in the most efficient way.

The `Support' chapter of the GPC Manual tells you where to find more information about GPC and how to contact the GPC developers. (see Support)

3.6 Miscellaneous

• Contributing: I want to contribute; where do I start?
• GPC web site: Where is the GNU Pascal web site?
• About the FAQ: About this FAQ

3.6.1 I want to contribute; where do I start?

If you want to contribute, please write to the mailing list, Mailing List.

3.6.2 Where is the GNU Pascal web site?

The GPC homepage on the web, for information and downloads, is
http://www.gnu-pascal.de.

The GPC To-Do list, listing the latest features and fixed bugs can also be found there.

3.6.3 About this FAQ

Current Maintainer: Russ Whitaker, russ@ashlandhome.net

This is the second incarnation of the GNU Pascal FAQ list, based on the previous FAQ by J.J. van der Heijden. Comments about, suggestions for, or corrections to this FAQ list are welcome.

Please make sure to include in your mail the version number of the document to which your comments apply (you can find the version at the beginning of this FAQ list).

Many people have contributed to this FAQ, only some of them are acknowledged above. Much of the info in, and inspiration for this FAQ list was taken from the GPC mailing list traffic, so you may have (unbeknownst to you) contributed to this list.

4 How to download, compile and install GNU Pascal.

• Download: Where and what to download
• Binary Distributions: How to install a binary distribution
• Compiling GPC: How to compile GPC
• Compilation Notes: Compilation notes for specific platforms
• Cross-Compilers: Building and Installing a cross-compiler
• Crossbuilding: Crossbuilding a compiler

4.1 Where and what to download

You can download the source code of the current GNU Pascal release from

     http://www.gnu-pascal.de/current/

and binaries for some platforms from

     http://www.gnu-pascal.de/binary/

The binary archive files are named gpc-version.platform.extension – for example `gpc-2.1.alpha-unknown-linux-gnu.tar.gz' for GPC version 2.1 on an Alpha workstation running the Linux kernel with GNU C Library, or `gpc-20000616.i386-pc-msdosdjgpp' for GPC version 20000616 on an Intel IA32 compatible PC running DOS with DJGPP.

After you have downloaded the correct archive file for your platform, please read the installation notes on how to install such a binary distribution.

If you are running Dos or MS Windows, you will need additional tools – see “What else to download and where” below.

Current snapshots

GNU Pascal is subject to steady development. Alpha and beta snapshots (source only, use at your own risk) can be found at:

     http://www.gnu-pascal.de/alpha/
     http://www.gnu-pascal.de/beta/

What else to download and where

When you are using GNU Pascal on a DOS system, you will need either the DJGPP or the EMX development environment (see below). On an OS/2 system, you will need EMX. On an MS Windows 95/98/NT system you will need either the CygWin or the mingw32 ot the MSYS environment.

GNU Pascal uses the compiler back-end from the GNU Compiler Collection, GNU CC or GCC. If you want to compile GPC, you will need the source of GCC as well as the source of GPC itself. From the same place as GPC, please download GCC 2.8.1, 2.95.x, 3.2.x, 3.3.x or 3.4.x. (It is also available from any GNU mirror; see http://www.gnu.org/software/gcc/.)

Libraries

For some of GPC's units, you will need some standard libraries. In particular:

Notes:

(1) ncurses version 5.0 or newer is strongly recommended because older versions contain a bug that severely affects CRT programs.

(2) You can install both ncurses and PDCurses on a Unix system, and choose at compile time whether to generate a terminal or X11 version of your program.

(3) ncurses also runs under MS-Windows with CygWin (not mingw32, however), but doesn't appear to behave much differently from PDCurses on that platform.

(4) ElectricFence is not used by any unit, but can be used for debugging memory allocation bugs by simply linking it (see the accompanying documentation).

You can find those libraries on many places on the Net. Also, many GNU/Linux distributions, DJGPP mirrors and other OS distributions already contain some of the libraries. In any case, you can find the sources of the libraries (sometimes together with patches that you should apply before building if you choose to build from the sources) and binaries for some platforms in

     http://www.gnu-pascal.de/libs/

For more information and descriptions of these libraries, see Libraries.

DJGPP

DJGPP is available from any SimTel mirror in the gnu/djgpp subdirectory; for addresses look into the DJGPP FAQ. To use GNU Pascal you need at least

• the C library, `v2/djdev201.zip', and
• `binutils' (assembler, etc.), v2gnu/bnu270b.zip.

We also recommend you to get:

• the `make' utility, v2gnu/mak375b.zip
• the GNU debugger, v2gnu/gdb416b.zip
• the DJGPP FAQ, v2faq/faq211b.zip
• the GRX graphics library, http://www.gnu.de/software/GRX/
• PENG, http://fjf.gnu.de/peng/, an integrated development environment, similar to BP's one, written in GNU Pascal, or
• RHIDE, v2app/rhide.zip, another integrated development environment, or
• DevPascal, http://www.bloodshed.net/devpascal.html, an integrated development environment for mingw32.

EMX

EMX is an environment for creating 32-bit applications for DOS and OS/2. To develop EMX programs with GNU Pascal you need at least

• the EMX runtime package, emxrt.zip,
• the EMX development system, emxdev*.zip, and
• the GNU development tools, gnudev*.zip.

If your DOS box has DPMI (it does if you are using MS Windows or OS/2) you will also need RSX, available from the same sites as EMX in the subdirectory rsxnt.

The GNU development tools contain the GNU C compiler which is in fact not needed to use GNU Pascal. However, the C library is needed.

CygWin

CygWin is an environment which implements a POSIX layer under MS Windows, giving it large parts of the functionality of Unix. CygWin contains development tools such as an assembler, a linker, etc. GPC needs for operation. More information about CygWin can be found at

     http://cygwin.com

mingw32

The Minimalists' GNU Win32 environment, mingw32, allows a large number of Unix programs – including GPC and GCC – to run under MS Windows 95/98/NT using native MS libraries. mingw32 ressources can be found at

     http://www.mingw.org

4.2 Installation instructions for a GPC binary distribution

To install a binary distribution, cd to the root directory and unpack the archive while preserving the stored directory structure. Under a Unix compatible system with GNU tar installed, the following (performed as `root') will do the job:

     # cd /
     # tar xzf archive.tar.gz

If you are using a `tar' utility other than GNU tar, it might be necessary to do the above in an explicit pipe:

     # cd /
     # gzip -c -d archive.tar.gz | tar xf -

Some binary distributions are now distributed packed with `bzip2'. You can recognize them by their file name suffix .bz2 instead of .gz. For such archives, make sure you have `bunzip2' installed and then use the following command:

     # cd /
     # tar xjf archive.tar.bz2

Or:

     # cd /
     # bunzip2 -c -d archive.tar.bz2 | tar xf -

If you want to install a GPC binary distribution in another directory than it was prepared for (for example, if you do not have root access to the computer and want to install GPC somewhere under your home directory), you can do the following:

• Unpack the archive file in a directory of your choice (see above).
• `cd' to the “prefix” directory of the distribution (for instance usr/local).
• Run the script install-gpc-binary, available from http://www.gnu-pascal.de/binary/.
• Follow the instructions in the script.

To install a ZIP archive under DOS with `PKunzip', `cd' to the appropriate directory (usually `\' for EMX, `\DJGPP' for DJGPP), then call `PKunzip' with the `-d' option:

     C:\> cd djgpp
     C:\DJGPP> pkunzip -d archive.zip

where archive.zip is the name of the distribution file.

For DJGPP you must edit your djgpp.env in the DJGPP directory to complete the installation: Please copy the entries from `[gcc]' to create a new `[gpc]' section. The result may look as follows:

     [gcc]
     COMPILER_PATH=%/>;COMPILER_PATH%%DJDIR%/bin
     LIBRARY_PATH=%/>;LIBRARY_PATH%%DJDIR%/lib
     
     [gpc]
     COMPILER_PATH=%/>;COMPILER_PATH%%DJDIR%/bin
     LIBRARY_PATH=%/>;LIBRARY_PATH%%DJDIR%/lib

If you are using the DJGPP version of GPC but do not have a DJGPP directory, please download and install DJGPP (see Download).

Binary distributions include libgcc.a and specs, files that are normally part of GCC. If you have GCC installed, they will be replaced unless you manually install the archive.

4.3 Compiling GPC

The preferred way to distribute GNU software is distribution of the source code. However, it can be a non-trivial exercise to build GNU Pascal on some non-Unix systems, so we also provide ready-to-run binaries for a number of platforms. (See Binary Distributions for how to install a binary distribution.)

GPC is based on the GNU Compiler Collection, GNU CC or GCC. You will need the GCC sources to build it. It must be the same version as the one GPC is implemented with – 2.8.1, 2.95.x, 3.2.x, 3.3.x or 3.4.x as of this writing. Although you need GCC to build the GNU Pascal compiler, you don't need GCC to compile Pascal programs once GNU Pascal is installed. (However, using certain libraries will require compiling C wrappers, so it is a good idea to install the C compiler as well.)

Because GNU Pascal shares its back-end with GCC, it should run on any system supported by GCC. A full list of platforms supported by GCC can be found in the GCC installation instructions.

The GCC source can be obtained from any mirror of the GNU FTP site, ftp://ftp.gnu.org/gnu/gcc/. The “core” distribution is sufficient for GPC.

Here is the generic procedure for installing GNU Pascal on a Unix system. See Compilation Notes for extra information needed to install GPC on DOS-like platforms.

1. Checking the prerequisites

   Make sure that GNU make is installed and that you use it in the following steps. When unsure, you can try `make --version' and/or `gmake --version'. It should tell you that it is GNU make. If you don't have it, you can obtain it from http://www.gnu.org/software/make/.

   (In the following, we will simply speak of `make' when invoking GNU make; you might need to call `gmake' instead.)

   You also need a patch program. If such a program is not installed on your system, you can get GNU patch from http://www.gnu.org/directory/patch.html.

   For extracting the example programs from the documentation to the doc/docdemos directory a non-crippled `sed' is needed. GNU sed is known to work.

   If you have downloaded a “minimal” source distribution, most derived files have to be rebuilt. This is done automatically when building GPC, but you need additional tools:

   `bash', `bzip2', GNU `sed', GNU `awk', GNU `m4', `bison' (at least version 2.1), `flex' (version 2.5.27), `autoconf' (version 2.12), `texinfo' (at least version 4.2), `help2man'.

   Make sure that these are installed. The minimal distributions are compressed with `bzip2' instead of `gzip', so substitute it in the instructions below.

   If your bison and flex programs are installed under different names, you may have to set some or all of the following environment variables before running `configure':

             FLEX=/path/to/flex
             LEX=/path/to/flex
             BISON=/path/to/bison
             YACC=/path/to/bison
             INTLBISON=/path/to/bison
        

   If you want to build the GPC WWW pages you will also need a TeX distribution (including `pdftex' and `dvips').

   If you run into trouble during the installation process, please check whether you are using outdated versions of the required utilities and upgrade if necessary.

   The GNU versions of the packages above are available from http://www.gnu.org/software/, in a subdirectory whose name is the name of the package.

2. Unpacking the source

   From a directory of your choice (e.g. /home/fred), unpack the GCC and GNU Pascal source distributions. This will create separate subdirectories for GCC and GPC. Let us assume gcc-3.4.3 and gpc-20041218 in this example.

             % cd /home/fred
             % bzip2 -d < gcc-core-3.4.3.tar.bz2 | tar xf -
             % gzip -c -d gpc-20041218.tar.gz | tar xf -
        

   `cd' to the GPC directory and move the contents (a subdirectory p) to the subdirectory gcc of the GCC directory:

             % mv /home/fred/gpc-20041218/p /home/fred/gcc-3.4.3/gcc/
        

   Instead of moving the directory, it is now also possible to make a symbolic link (if the OS supports symlinks). This is useful if you want to build GPC with several different GCC versions:

             % ln -s /home/fred/gpc-20041218/p /home/fred/gcc-3.4.3/gcc/p
        

   It is recommended, though not required, to use a separate directory for building the compiler, rather than compiling in the source directory. In this example, let us create /home/fred/gpc-build for this purpose:

             % mkdir /home/fred/gpc-build
        

   If you use a separate directory, you do not need to write into the GCC source directory once you have patched the GCC source (see below), and can build GPC for more than one platform from the same source tree.

   In case you are re-using a directory where you have already built GCC and/or GPC for a different target machine, do `make distclean' to delete all files that might be invalid. One of the files this deletes is Makefile; if `make distclean' complains that Makefile does not exist, it probably means that the directory is already suitably clean.

3. Configuring and building GCC

   GNU Pascal is automatically configured with GCC. Configuration of GCC is treated in depth in the GCC installation instructions. The normal procedure is as follows:

   `cd' to the GPC build directory. From there, run the `configure' script in the GCC source directory:

             % cd /home/fred/gpc-build
             % /home/fred/gcc-3.4.3/configure --enable-languages=pascal
        

   This creates all the necessary config files, links and Makefile in the GCC object directory.

   Note 1: The configuration will prompt you for patching the GCC source for GPC support, so you need write access to that directory. All changes to GCC are surrounded by `#ifdef GPC ... #endif', so they should not interfere when you build a C compiler from this source tree.

   Note 2: The `--enable-languages=pascal' option means that we only want to build the Pascal compiler and not, for instance, the C++ compiler.

   Note 3: The standard base directory for installing GCC and GPC is /usr/local. If you want to install files to an alternate directory dir, specify `--prefix=dir' when you run configure. For installing into a system directory such as /usr/local you will, of course, need appropriate permissions (often root). Therefore, if you want to install GPC on a system where you don't have those permissions, you must specify a prefix (e.g., `$HOME/usr').

4. Putting other GNU tools in place

   Some environments require other GNU tools (such as the GNU assembler or linker) instead of the standard system tools for GCC to work. (See the GCC installation instructions for details.) If this is the case for your system, install the required tools in the GPC build directory under the names as, ld, or whatever is appropriate. This will enable the compiler to find the proper tools for compilation of the program enquire (a part of GCC) and to install the GNU tools to a place where they are found by GCC but do not interfere with the standard system tools.

   Alternatively, you can do subsequent compilation using a value of the PATH environment variable such that the necessary GNU tools come before the standard system tools.

5. Compiling GPC

   Once you are satisfied with the configuration as determined by configure, you can build the compiler:

             % make
        

   Notice that this procedure will build the C compiler (and maybe some other compilers) too, because that is used to compile the GPC runtime library.

   Optionally, you may supply CFLAGS, LDFLAGS or RTSFLAGS. CFLAGS is used for compiler and RTS, RTSFLAGS are for RTS only, i.e.: `make CFLAGS="-O2" RTSFLAGS=-Wall'

   Note: The documentation may fail to build from *.texi sources if GCC 2.95.x tries to use an older version of `makeinfo' supplied in GCC package itself. This can be prevented by supplying explicit instruction to use your system's `makeinfo':

             % make MAKEINFO=`which makeinfo`
        

   optionally followed by the rest of arguments.

6. Completing the installation

   When everything has been compiled, you can check the installation process with:

             % make -n install
        

   To complete the installation, run the command `make install'. You need write access to the target directories (/usr/local/bin, /usr/local/lib, /usr/local/info, /usr/local/doc, and /usr/local/man in this example), so this is usually done as `root':

             % su -c "make install"
        

   If you want to install only the Pascal compiler (for example if you already have the correct version of GCC installed), `cd' to the `gcc' subdirectory of the build directory (e.g. /home/fred/gpc-build/gcc) and run `make pascal.install'. This installation process does not overwrite existing copies of libgcc.a or specs, should they exist.

   However, if you do not have the exactly matching GCC version installed, you might need some additional files (otherwise GPC will complain about missing files at runtime). You can install them by doing `make pascal.install-with-gcc' in the gcc subdirectory of the build directory.

   There is a (partial) translation of the GPC manual into Croatian available now. It is not installed by default. If you want to install it, do a `pascal.install-hr' in the `gcc' directory. This will install the manpage gpc-hr.1 and the info documentation gpc-hr.info*. Other formats like PS, PDF and HTML can be built manually (it's also easy to add appropriate make targets for them when needed).

   Also from the `gcc' subdirectory you can do some more “exotic” builds. For instance, you can build the GPC WWW pages by typing `make pascal.html' or a binary distribution by typing `make pascal.bindist'. See the Makefile in that directory for more examples.

4.4 Compilation notes for specific platforms

• MS-DOS with DJGPP: The DJGPP port of GNU compilers to MS-DOS.
• MS-DOS or OS/2 with EMX: The EMX port of GNU compilers to MS-DOS and OS/2.
• MS Windows 95/98/NT: Installation on a Windows 95/98/NT system.

4.4.1 MS-DOS with DJGPP

The only compiler that is capable of compiling the GNU Compiler Collection (GNU CC or GCC) under MS-DOS is GCC itself. In order to compile GPC or GCC for MS-DOS with DJGPP you will therefore need either a working copy of DJGPP installed, or you will have to cross-build from a non-MS-DOS system.

Building GPC under MS-DOS with DJGPP follows the same scheme as building GPC under a Unix-like system: Place the p subdirectory in the gcc directory and follow the instructions for compiling GCC. This requires `bash' and many other tools installed, and you must be very careful at many places to circumvent the limitations of the DOS platform.

Our preferred way to build GPC for DJGPP is to cross-build it from a Unix-like platform – which is much easier. For instructions, see Cross-Compilers and Crossbuilding.

4.4.2 MS-DOS or OS/2 with EMX

EMX is a free 32-bit DOS extender which adds some properties of Unix to MS-compatible DOS and IBM's OS/2 operating systems.

As of this writing, we are not aware of current versions of GCC for EMX, and EMX support in GPC has not been maintained. Please contact us if you know about recent development in EMX and are interested in continuing EMX support in GPC.

4.4.3 MS Windows 95/98/NT

There are two ports of the GNU development tools to MS Windows 95/98/NT: CygWin and mingw32.

The CygWin environment implements a POSIX layer under MS Windows, giving it large parts of the functionality of Unix. Thus, compiling GCC and GPC under the CygWin environment can be done following the instructions for compiling it under a Unix-like system (see Compiling GPC).

The Minimalists' GNU Win32 environment, mingw32, uses the native crtdll.dll library of MS Windows. It is much smaller than CygWin, but it is not self-hosting and must be crossbuilt from another system (see Crossbuilding).

4.5 Building and Installing a cross-compiler

GNU Pascal can function as a cross-compiler for many machines. Information about GNU tools in a cross-configuration can be found at `ftp://ftp.cygnus.com/pub/embedded/crossgcc/'.

If you want a cross-compiler targetting Linux you may use Dan Kegel's crosstool from `http://www.kegel.com/crosstool/'

Since GNU Pascal generates assembler code, you need a cross-assembler that GNU Pascal can run, in order to produce object files. If you want to link on other than the target machine, you need a cross-linker as well. It is straightforward to install the GNU binutils to act as cross-tools – see the installation instructions of the GNU binutils for details.

You also need header files and libraries suitable for the target machine that you can install on the host machine. Please install them under prefix/platform/include/, for instance /usr/local/i386-pc-msdosdjgpp/include/ for a cross-compiler from a typical Unix-like environment to MS-DOS with DJGPP.

Configuration and compilation of the compiler can then be done using the scripts cfgpc and mkgpc which are included in the source distribution in the subdirectory p/script. Please call them with the `-h' option for instructions.

4.6 Crossbuilding a compiler

Using a cross-compiler to build GNU Pascal results in a compiler binary that runs on the cross-target platform. This is called “crossbuilding”. A possible reason why anybody would want to do this, is when the platform on which you want to run the GNU Pascal compiler is not self-hosting. An example is mingw32.

To crossbuild GNU Pascal, you have to install a cross-compiler for your target first, see Cross-Compilers.

As when building a cross-compiler, configuration and compilation of the compiler can be done using the scripts cfgpc and mkgpc which are included in the source distribution in the subdirectory p/script. Please call them with the `-h' option for instructions.

5 Command Line Options supported by GNU Pascal.

GPC is a command-line compiler, i.e., to compile a program you have to invoke gpc passing it the name of the file you want to compile, plus options.

GPC supports all command-line options that GCC knows, except for many preprocessor options. For a complete reference and descriptions of all options, see GCC Command Options. Below, you will find a list of the additional options that GPC supports, and a list of GPC's most important options (including some of those supported by GCC as well).

You can mix options and file names on the command line. For the most part, the order doesn't matter. Order does matter, e.g., when you use several options of the same kind; for example, if you specify `-L' more than once, the directories are searched in the order specified. Note: Since many options have multiletter names; multiple single-letter options may not be grouped as is possible with many other programs: `-dr' is very different from `-d -r'.

Many options have long names starting with `--' or, completely equivalent `-f'. E.g., `--mixed-comments' is the same as `-fmixed-comments'. Some options tell GPC when to give warnings, i.e. diagnostic messages that report constructs which are not inherently erroneous but which are risky or suggest there may have been an error. Those options start with `-W'.

Most GPC specific options can also be changed during one compilation by using compiler directives in the source, e.g. `{$X+}' or `{$extended-syntax}' for `--extended-syntax' (see Compiler Directives).

GPC understands the same environment variables GCC does (see Environment Variables Affecting GCC). In addition, GPC recognizes `GPC_EXEC_PREFIX' with the same meaning that `GCC_EXEC_PREFIX' has to GCC. GPC also recognizes `GCC_EXEC_PREFIX', but `GPC_EXEC_PREFIX' takes precedence.

Some of the long options (e.g., `--unit-path') take an argument. This argument is separated with a `=' sign, e.g.:

     --unit-path=/home/foo/units

• GPC Command Line Options: GPC options besides those of GCC.
• GPC Options: The most commonly used options to GPC.

5.1 GPC options besides those of GCC.

The following table lists the command line options GPC understands in addition to those understood by GCC.

--debug-tree

(For GPC developers.) Show the internal representation of a given tree node (name or address).

--debug-gpi

(For GPC developers.) Show what is written to and read from GPI files (huge output!).

--debug-automake

(For GPC developers.) Give additional information about the actions of automake.

--debug-source

Output the source while it is being processed to standard error.

--no-debug-source

Do not output the source while it is being processed (default).

--disable-debug-info

Inhibit `-g' options (temporary work-around, this option may disappear in the future).

--progress-messages

Output source file names and line numbers while compiling.

--no-progress-messages

Do not output source file names and line numbers while compiling (default).

--progress-bar

Output number of processed lines while compiling.

--no-progress-bar

Do not output number of processed lines while compiling (default).

--automake-gpc

Set the Pascal compiler invoked by automake.

--automake-gcc

Set the C compiler invoked by automake.

--automake-g++

Set the C++ compiler invoked by automake.

--amtmpfile

(Internal switch used for automake).

--autolink

Automatically link object files provided by units/modules or `{$L ...}' (default).

--no-autolink

Do not automatically link object files provided by units/modules/`{$L ...}'.

--automake

Automatically compile changed units/modules/`{$L ...}' files and link the object files provided.

--no-automake

Same as `--no-autolink'.

--autobuild

Automatically compile all units/modules/`{$L ...}' files and link the object files provided.

--no-autobuild

Same as `--no-autolink'.

--maximum-field-alignment

Set the maximum field alignment in bits if `pack-struct' is in effect.

--ignore-packed

Ignore `packed' in the source code (default in `--borland-pascal').

--no-ignore-packed

Do not ignore `packed' in the source code (default).

--ignore-garbage-after-dot

Ignore anything after the terminating `.' (default in `--borland-pascal').

--no-ignore-garbage-after-dot

Complain about anything after the terminating `.' (default).

--extended-syntax

same as `--ignore-function-results --pointer-arithmetic --cstrings-as-strings -Wno-absolute' (same as `{$X+}').

--no-extended-syntax

Opposite of `--extended-syntax' (same as `{$X-}').

--ignore-function-results

Do not complain when a function is called like a procedure.

--no-ignore-function-results

Complain when a function is called like a procedure (default).

--pointer-arithmetic

Enable pointer arithmetic.

--no-pointer-arithmetic

Disable pointer arithmetic (default).

--cstrings-as-strings

Treat CStrings as strings.

--no-cstrings-as-strings

Do not treat CStrings as strings (default).

-Wabsolute

Warn about variables at absolute adresses and `absolute' variable with non-constant addresses (default).

-Wno-absolute

Do not warn about variables at absolute adresses and `absolute' variable with non-constant addresses.

--short-circuit

Guarantee short-circuit Boolean evaluation (default; same as `{$B-}').

--no-short-circuit

Do not guarantee short-circuit Boolean evaluation (same as `{$B+}').

--mixed-comments

Allow comments like `{ ... *)' as required in ISO Pascal (default in ISO 7185/10206 Pascal mode).

--no-mixed-comments

Ignore `{' and `}' within `(* ... *)' comments and vice versa (default).

--nested-comments

Allow nested comments like `{ { } }' and `(* (* *) *)'.

--no-nested-comments

Do not allow nested comments (default).

--delphi-comments

Allow Delphi style `//' comments (default).

--no-delphi-comments

Do not allow Delphi style `//' comments.

--macros

Expand macros (default).

--no-macros

Do not expand macros (default with `--ucsd-pascal', `--borland-pascal' or `--delphi').

--truncate-strings

Truncate strings being assigned to other strings of too short capacity.

--no-truncate-strings

Treat string assignments to other strings of too short capacity as errors.

--exact-compare-strings

Do not blank-pad strings for comparisons.

--no-exact-compare-strings

Blank-pad strings for comparisons.

--double-quoted-strings

Allow strings enclosed in "\" (default).

--no-double-quoted-strings

Do not allow strings enclosed in "\" (default with dialect other than `--mac-pascal').

--longjmp-all-nonlocal-labels

Use `longjmp' for all nonlocal labels (default for Darwin/PPC).

--no-longjmp-all-nonlocal-labels

Use `longjmp' only for nonlocal labels in the main program (default except for Darwin/PPC).

--iso-goto-restrictions

Do not allow jumps into structured instructions (default).

--no-iso-goto-restrictions

Allow jumps into structured instructions (default in `--borland-pascal').

--nonlocal-exit

Allow non-local `Exit' statements (default in `--ucsd-pascal' and `--mac-pascal').

--no-nonlocal-exit

Do not allow non-local `Exit' statements (default).

--io-checking

Check I/O operations automatically (same as `{$I+}') (default).

--no-io-checking

Do not check I/O operations automatically (same as `{$I-}').

--pointer-checking-user-defined

Use user-defined procedure for validating pointers.

--no-pointer-checking-user-defined

Do not use user-defined procedure for validating pointers (default).

--pointer-checking

Validate pointers before dereferencing.

--no-pointer-checking

Do not validate pointers before dereferencing (default).

--object-checking

Check for valid objects on virtual method calls (default).

--no-object-checking

Do not check for valid objects on virtual method calls.

--range-checking

Do automatic range checks') (default).

--no-range-checking

Do not do automatic range checks (same as `{$R-}').

--range-and-object-checking

Same as `--range-checking --object-checking', same as `{$R+}'.

--no-range-and-object-checking

Same as `--no-range-checking --no-object-checking', same as `{$R-}'.

--case-value-checking

Cause a runtime error if a `case' matches no branch (default in ISO Pascal modes).

--no-case-value-checking

Do not cause a runtime error if a `case' matches no branch (default).

--stack-checking

Enable stack checking (same as `{$S+}').

--no-stack-checking

Disable stack checking (same as `{$S-} (default)').

--read-base-specifier

In read statements, allow input base specifier `n#' (default).

--no-read-base-specifier

In read statements, do not allow input base specifier `n#' (default in ISO 7185 Pascal).

--read-hex

In read statements, allow hexadecimal input with `$' (default).

--no-read-hex

In read statements, do not allow hexadecimal input with `$' (default in ISO 7185 Pascal).

--read-white-space

In read statements, require whitespace after numbers.

--no-read-white-space

In read statements, do not require whitespace after numbers (default).

--write-clip-strings

In write statements, truncate strings exceeding their field width (`Write (SomeLongString : 3)').

--no-write-clip-strings

Do not truncate strings exceeding their field width.

--write-real-blank

Output a blank in front of positive reals in exponential form (default).

--no-write-real-blank

Do not output a blank in front of positive reals in exponential form.

--write-capital-exponent

Write real exponents with a capital `E'.

--no-write-capital-exponent

Write real exponents with a lowercase `e'.

--transparent-file-names

Derive external file names from variable names.

--no-transparent-file-names

Do not derive external file names from variable names (default).

--field-widths

Optional colon-separated list of default field widths for Integer, Real, Boolean, LongInt, LongReal.

--no-field-widths

Reset the default field widths.

--pedantic

Reject everything not allowed in some dialect, e.g. redefinition of its keywords.

--no-pedantic

Don't give pedantic warnings.

--typed-address

Make the result of the address operator typed (same as `{$T+}', default).

--no-typed-address

Make the result of the address operator an untyped pointer (same as `{$T-}').

--enable-keyword

Enable a keyword, independently of dialect defaults.

--disable-keyword

Disable a keyword, independently of dialect defaults.

--implicit-result

Enable implicit `Result' for functions (default only in `--delphi').

--no-implicit-result

Disable implicit `Result' for functions.

--enable-predefined-identifier

Enable a predefined identifier, independently of dialect defaults.

--disable-predefined-identifier

Disable a predefined identifier, independently of dialect defaults.

--assertions

Enable assertion checking (default).

--no-assertions

Disable assertion checking.

--setlimit

Define the range for `set of Integer' etc..

--gpc-main

External name for the program's entry point (default: `main').

--propagate-units

Automatically re-export all imported declarations.

--no-propagate-units

Do not automatically re-export all imported declarations.

--interface-only

Compile only the interface part of a unit/module and exit (creates `.gpi' file, no `.o' file.

--implementation-only

Do not produce a GPI file; only compile the implementation part.

--executable-file-name

Name for the output file, if specified; otherwise derive from main source file name.

--unit-path

Directories where to look for unit/module sources.

--no-unit-path

Forget about directories where to look for unit/module sources.

--object-path

Directories where to look for additional object (and source) files.

--no-object-path

Forget about directories where to look for additional object (and source) files.

--executable-path

Path where to create the executable file.

--no-executable-path

Create the executable file in the directory where the main source is (default).

--unit-destination-path

Path where to create object and GPI files of Pascal units.

--no-unit-destination-path

Create object and GPI files of Pascal units in the current directory (default).

--object-destination-path

Path where to create additional object files (e.g. of C files, not Pascal units).

--no-object-destination-path

Create additional object files (e.g. of C files, not Pascal units) in the current directory (default).

--disable-default-paths

Do not add a default path to the unit and object path.

--gpi-destination-path

(Internal switch used for automake).

--uses

Add an implicit `uses' clause.

--init-modules

Initialize the named modules in addition to those imported regularly; kind of a kludge.

--cidefine

Define a case-insensitive macro.

--csdefine

Define a case-sensitive macro.

--big-endian

Tell GPC that the system is big-endian (for those targets where it can vary).

--little-endian

Tell GPC that the system is little-endian (for those targets where it can vary).

--print-needed-options

Print the needed options.

-Wwarnings

Enable warnings (same as `{$W+}').

-Wno-warnings

Disable all warnings (same as `{$W-}').

-Widentifier-case-local

Warn about an identifier written with varying case within one program/module/unit.

-Wno-identifier-case-local

Same as `-Wno-identifier-case'.

-Widentifier-case

Warn about an identifier written with varying case.

-Wno-identifier-case

Do not warn about an identifier written with varying case (default).

-Winterface-file-name

Warn when a unit/module interface differs from the file name.

-Wno-interface-file-name

Do not warn when a unit/module interface differs from the file name (default).

--methods-always-virtual

Make all methods virtual (default in `--mac-pascal').

--no-methods-always-virtual

Do not make all methods virtual (default).

--objects-are-references

Turn objects into references (default in `--mac-pascal').

--no-objects-are-references

Do not turn objects into references (default).

--objects-require-override

Require override directive for objects (default in `--mac-pascal').

--no-objects-require-override

Do not require override directive for objects (default).

--delphi-method-shadowing

Redefining methods silently shadows old definition (default in `--delphi').

--no-delphi-method-shadowing

Do not silently shadow method definitions (default).

--borland-objects

Choose Borland object model.

--mac-objects

Choose Mac object model.

--ooe-objects

Choose OOE object model.

--gnu-objects

Reset object model to default state.

--preprocessed

Treat the input file as already preprocessed.

-nostdinc

Do not search standard system.

-remap

Remap file names when including files.

-A

Ignored.

-E

Preprocess only.

-H

Print the name of include files as they are used.

-P

Do not generate #line directives.

-Wimplicit-abstract

Warn when an object type not declared `abstract' contains an abstract method (default).

-Wno-implicit-abstract

Do not warn when an object type not `declared' abstract contains an abstract method.

-Winherited-abstract

Warn when an abstract object type inherits from a non-abstract one (default).

-Wno-inherited-abstract

Do not warn when an abstract object type inherits from a non-abstract one.

-Wobject-assignment

Warn when when assigning objects or declaring them as value parameters or function results (default).

-Wno-object-assignment

Do not warn when assigning objects or declaring them as value parameters or function results (default in `--borland-pascal').

-Wimplicit-io

Warn when `Input' or `Output' are used implicitly.

-Wno-implicit-io

Do not warn when `Input' or `Output' are used implicitly (default).

-Wfloat-equal

Warn about `=' and `<>' comparisons of real numbers.

-Wno-float-equal

Do not warn about `=' and `<>' comparisons of real numbers.

-Wtyped-const

Warn about misuse of typed constants as initialized variables (default).

-Wno-typed-const

Do not warn about misuse of typed constants as initialized variables.

-Wnear-far

Warn about use of useless `near' or `far' directives (default).

-Wno-near-far

Do not warn about use of useless `near' or `far' directives.

-Wunderscore

Warn about double/leading/trailing underscores in identifiers.

-Wno-underscore

Do not warn about double/leading/trailing underscores in identifiers.

-Wsemicolon

Warn about a semicolon after `then', `else' or `do' (default).

-Wno-semicolon

Do not warn about a semicolon after `then', `else' or `do'.

-Wlocal-external

Warn about local `external' declarations.

-Wno-local-external

Do not warn about local `external' declarations.

-Wdynamic-arrays

Warn about arrays whose size is determined at run time (including array slices).

-Wno-dynamic-arrays

Do not warn about arrays whose size is determined at run time (including array slices).

-Wmixed-comments

Warn about mixed comments like `{ ... *)'.

-Wno-mixed-comments

Do not warn about mixed comments.

-Wnested-comments

Warn about nested comments like `{ { } }'.

-Wno-nested-comments

Do not warn about nested comments.

--classic-pascal-level-0

Reject conformant arrays and anything besides ISO 7185 Pascal.

--standard-pascal-level-0

Synonym for `--classic-pascal-level-0'.

--classic-pascal

Reject anything besides ISO 7185 Pascal.

--standard-pascal

Synonym for `--classic-pascal'.

--extended-pascal

Reject anything besides ISO 10206 Extended Pascal.

--object-pascal

Reject anything besides (the implemented parts of) ANSI draft Object Pascal.

--ucsd-pascal

Try to emulate UCSD Pascal.

--borland-pascal

Try to emulate Borland Pascal, version 7.0.

--delphi

Try to emulate Borland Pascal, version 7.0, with some Delphi extensions.

--pascal-sc

Be strict about the implemented Pascal-SC extensions.

--vax-pascal

Support (a few features of) VAX Pascal.

--sun-pascal

Support (a few features of) Sun Pascal.

--mac-pascal

Support (some features of) traditional Macintosh Pascal compilers.

--gnu-pascal

Undo the effect of previous dialect options, allow all features again.

5.2 The most commonly used options to GPC

As the most simple example, calling

     gpc foo.pas

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

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

Another example:

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

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

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

--automake

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

--unit-path=dir[:dir...]

Search the given directories for units and object files.

--object-path=dir[:dir...]

Search the given directories for object files.

--unit-destination-path=dir

Place compiled units (GPI and object files) into the directory dir. The default is the current directory.

--object-destination-path=dir

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

--executable-path=dir

Place the executable compiled into the directory dir. The default is the main source file's directory.

-o file

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

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

--executable-file-name[=name]

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

-Ldir

Search the directory dir for libraries. Can be given multiple times.

-Idir

Search the directory dir for include files. Can be given multiple times.

-llibrary

Search the library named library when linking. This option must be placed on the command line after all source or object files or other libraries that reference the library.

-O[n]

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

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

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

-g

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

-s

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

-Wall

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

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

-Werror

Turn all warnings into errors.

-S

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

-c

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

-static

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

-Dmacro[=def]

Define the macro and conditional symbol macro as def (or as `1' if def is omitted).

-b machine

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

-v

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

--classic-pascal-level-0

--classic-pascal

--extended-pascal

--object-pascal

--ucsd-pascal

--borland-pascal

--delphi

--pascal-sc

--mac-pascal

GNU Pascal supports the features of several different Pascal standards and dialects. The intention is to have common language, where features off all dialects are available. As result, the defualt language is the biggest dialect, with most features. Sometimies features of different dialect conflict (in such cases we usually provide more detailed switches to choose desired behaviour). These switches turn on maximal compatiblity with given dialect. In particular they tell GPC to restrict itself to the features of the specified standard. Warnings about certain dangerous constructs which would be valid in the specified dialect (e.g., assignment to a typed constant with `--borland-pascal') are suppressed.

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

Most ISO 7185 Pascal programs should compile properly with or without `--classic-pascal'. However, without this option, some constructs behave in non-standard way. Moreover, certain GNU extensions and Pascal features from other dialects are supported as well. With this option, they are rejected.

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

-pedantic-errors

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

--gpc-main=name

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

6 The Programmer's Guide to GPC

This chapter is still under development.

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

This chapter does not cover how to compile your programs and to produce an executable – this is discussed above in Invoking GPC.

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

6.1 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.

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

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

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

     program UnitDemo;
     
     uses
       DemoUnit;
     
     begin
       Hello
     end.

6.1.1 The Source Structure of Programs

A generic GNU Pascal program looks like the following:

     program name (Input, Output);
     
     import_part
     
     declaration_part
     
     begin
       statement_part
     end.

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

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

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

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

The statement_part consists of a sequence of statements.

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

6.1.2 Label Declaration

A label declaration has the following look:

     label
       label_name, ..., label;

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

See also

label, goto

6.1.3 Constant Declaration

A constant declaration has the following look:

     const
       constant_identifier = constant_expression;
       ...
       constant_identifier = constant_expression;

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

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

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

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

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

  An example of a typed constant:

            const
              i: Integer = 0;
       

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

            var
              i: Integer value 0;
       

  GPC supports this as well as the following mixture of dialects:

            var
              i: Integer = 0;
       

  Furthermore, you can also assign initialization values to types:

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

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

• Arrays initializers look like this in BP:

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

  And the following way in EP:

            program EPArrayInitDemo;
            
            const
              MyStringsCount = 5;
            
            type
              Ident = String (20);
            
            var
              MyStrings: array [1 .. MyStringsCount] of Ident value
                [1: 'export'; 2: 'implementation'; 3: 'import';
                 4: 'interface'; 5: 'module'];
            
            begin
            end.
       

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

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

See also

Subroutine Parameter List Declaration

6.1.4 Type Declaration

A type declaration looks like this:

     type
       type_identifier = type_definition;
       ...
       type_identifier = type_definition;

or, with preset content:

     type
       type_identifier = type_definition value constant_expression;
       ...
       type_identifier = type_definition value constant_expression;

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

     type_identifier (discriminant) = schema_type_definition;

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

Type declaration example

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

See also

Type Definition, Data Types, Variable Declaration

6.1.5 Variable Declaration

A variable declaration looks like this:

     var
       var_identifier: type_identifier;
       ...
       var_identifier: type_identifier;

or

     var
       var_identifier: type_definition;
       ...
       var_identifier: type_definition;

and with initializing value:

     var
       var_identifier: type_identifier value constant_expression;
       ...
       var_identifier: type_identifier value constant_expression;

or

     var
       var_identifier: type_definition value constant_expression;
       ...
       var_identifier: type_definition value constant_expression;

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

See also

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

6.1.6 Subroutine Declaration

• The Procedure
• The Function
• The Operator
• Subroutine Parameter List Declaration

6.1.6.1 The Procedure

     procedure procedure_identifier;
     declaration_part
     begin
       statement_part
     end;

or with a parameter list:

     procedure procedure_identifier (parameter_list);
     declaration_part
     begin
       statement_part
     end;

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

See also

The Function, Subroutine Parameter List Declaration

6.1.6.2 The Function

     function function_identifier: function_result_type;
     declaration_part
     begin
       statement_part
     end;

or with a parameter list:

     function function_identifier (parameter_list): result_type;
     declaration_part
     begin
       statement_part
     end;

A function is a subroutine which has a return value of type function_result_type. It is structured like the program: the declaration_part consists of label, constant, type, variable or subroutine declarations in free order. The statement_part consists of a sequence of statements. If parameter_list is specified, parameters can be passed to the function and can be used in statement_part. The result is set via an assignment:

     function_identifier := expression

Recursive function calls are allowed. Concerning the result type, ISO 7185 Pascal and Borland Pascal only allow the intrinsic types, subranges, enumerated types and pointer types to be returned. In Extended Pascal, function_result_type can be every assignable type. Of course, there are no type restrictions in GNU Pascal as well. If extended syntax is switched on, functions can be called like procedures via procedure call statement.

See also

The Procedure, Subroutine Parameter List Declaration, Data Types

6.1.6.3 The Operator

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

6.1.6.4 Subroutine Parameter List Declaration

     parameter; ...; parameter

Each parameter can start with a prefix (see below) describing how the parameters are passed, followed by a comma seperated list of one or more parameter_identifiers and an optional parameter_type.

     procedure DoIt (var x, y, z: OneType; a, b: AnotherType; var q);

To understand parameter passing, first some definitions.

actual parameter

the parameter passed in to the routine.

formal parameter

the parameter as used inside the procedure.

by value

the value of the actual parameter is copied on to the stack.

by reference

the address of the actual parameter is copied on to the stack.

L-value

(left hand of a `:=' statement) something that can be assigned to (not a constant, or const or protected variable or other immutable item).

R-value

(right hand of a `:=' statement) anything you can get the value of (could be a constant, an expression, a variable (whether const or protected or not) or just about anything.

addressable

something you can get the address of (not a field of a packed structure or a variable with `attribute (register)' (GPC extension)).

aliasing

accessing memory via two different names (e.g. a global variable passed by reference to a procedure can be accessed either as the global variable or the formal paramater). Generally this is very bad practice.

Technical note: Parameters are not always passed on the stack, they may also be passed in registers, especially on RISC machines.

The prefix defines how a variable is passed on the stack and how you can access the formal_parameter inside the procedure. The prefix can be one of:

nothing

          procedure DoIt (x: SomeType);
     

Technical: The actual parameter is passed by value or reference, but if passed by reference, it is then copied to a local copy on the stack. Aliasing has no effect on x.

What it means: you can modify `x' inside the routine, but your changes will not affect the actual parameter (and vice versa). The actual parameter can be a constant or other immutable object, or a protected or const variable.

protected

          procedure DoIt (protected x: SomeType);
     

Technical: The actual parameter is passed by value or reference, but if passed by reference, it is then copied to a local copy on the stack. Aliasing has no effect on x. protected is a Extended Pascal extension.

What it means: if you modify the actual parameter, this will not affect `x' inside the routine. The actual parameter can be a constant or other immutable object, or a protected or const variable. You are forbidden from modifying x inside the routine.

var

          procedure DoIt (var x: SomeType);
     

Technical: The actual parameter is passed by reference. Aliasing will definitely change `x'.

What it means: modifications to `x' inside the routine will change the actual parameter passed in. The actual parameter must be an addressable L-value (ie, it must be something you can take the address of and assign to).

A parameter of this kind is called variable parameter and internally corresponds to an L-value pointer (to the specified type identifier if any). This declaration is necessary if the parameter is to be modified within the routine and to hold its value still after return.

const

          procedure DoIt (const x: SomeType);
     

Technical: The actual parameter is passed by value or reference. The compiler will make a copy of the actual parameter to have something it can address if the actual parameter is not addressable. You are forbidden from modifying `x' inside the routine, and therefore you cannot modify the actual parameter. Aliasing may or may not change `x'. const is a Borland Pascal extension.

What it means: You can pass any R-value. You cannot modify `x' inside the routine. If you change the actual parameter while inside the routine, `x' will have an undefined value.

protected var

          procedure DoIt (protected var x: SomeType);
     

Technical: The actual parameter is passed by reference. The compiler will never make a copy of the actual parameter. You are forbidden from modifying `x' inside the routine, and therefore you cannot modify the actual parameter. Aliasing will definitely change `x'.

What it means: You can pass anything addressable. You cannot modify `x' inside the routine. If you change the actual parameter while inside the routine, `x' will change as well.

In GPC, the protected var mode guarantees that the parameter is always passed by reference, making it the correct choice for calling C routines with `const' pointer parameters.

If you omit the formal parameter type specification, then any type may be passed to that parameter. Generally this is a bad idea, but occasionally it can be useful, especially for low level code.

As an Extended Pascal extension, you can also declare procedural parameters directly:

     procedure parameter_identifier

or:

     function parameter_identifier: parameter_identifier_result_type

Example for parameter lists:

     program ParameterDemo;
     
     procedure Foo (var Bar; var Baz: Integer; const Fred: Integer);
     
       procedure Glork1 (function Foo: Integer; procedure Bar (Baz: Integer));
       begin
         Bar (Foo)
       end;
     
     begin
       Baz := Integer (Bar) + Fred
     end;
     
     var
       a, b, c: Integer;
     
     begin
       Foo (a, b, c)
     end.

See also

Data Types, var, const, protected

6.1.7 Statements

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

6.1.7.1 Assignment

The way an assignment looks like:

     L-value := expression;

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

6.1.7.2 begin end Compound Statement

It looks like that:

     begin
       statement;
       statement;
       ...
       statement
     end

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

6.1.7.3 if Statement

This statement has the following look:

     if boolean_expression then
       statement

or with an alternative statement:

     if boolean_expression then
       statement1
     else
       statement2

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

If `if' ... `then' ... `else' is concerned, statement1 is executed depending on boolean_expression being true, otherwise statement2 is executed alternatively. Note: the statement before else must not finish with a semicolon.

6.1.7.4 case Statement

     case expression of
       selector: statement;
       ...
       selector: statement;
     end

or, with alternative statement sequence:

     case ordinal_expression of
       selector: statement;
       ...
       selector: statement;
     otherwise                   { ``else'' instead of ``otherwise'' allowed }
       statement;
       ...
       statement;
     end

or, as part of the invariant record type definition:

     type
       foo = record
         field_declarations
       case bar: variant_type of
         selector: (field_declarations);
         selector: (field_declarations);
         ...
       end;

or, without a variant selector field,

     type
       foo = record
         field_declarations
       case variant_type of
         selector: (field_declarations);
         selector: (field_declarations);
         ...
       end;

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

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

For case in a variant record type definition, see Record Types.

See also

if Statement

6.1.7.5 for Statement

For ordinal index variables:

     for ordinal_variable := initial_value to final_value do
       statement

or

     for ordinal_variable := initial_value downto final_value do
       statement

For sets:

     for set_element_type_variable in some_set do
       statement

For pointer index variables:

     for pointer_variable := initial_address to final_address do
       statement

or

     for pointer_variable := initial_address downto final_address do
       statement

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

For ordinal index variables:

• If `to' is specified, the index counter is increased by one as long as initial_value is less or equal to final value,
• if `downto' is specified, it is decreased by one as long as initial_value is greater or equal to final_value.

For pointer index variables:

• If `to' is specified, the index counter is increased by the size of the type the index variable points to (if it is a typed pointer, otherwise by one if it is typeless) as long as initial_address is less or equal to final_address,
• if `downto' is specified, it is decreased by a corresponding value as long as initial_address is greater or equal to final_address.

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

For sets:

• statement is executed with the index variable (which must be ordinal and of the same type as the set elements) assuming every element in some_set, however note that a set is a not-ordered structure.

Please note: A modification of the index variable may result in unpredictable action.

See also

Set Types, Pointer Arithmetics, repeat Statement, for Statement

6.1.7.6 while Statement

The while loop has the following form

     while boolean_expression do
       statement

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

See also

repeat Statement, for Statement

6.1.7.7 repeat Statement

     repeat
       statement;
       ...
       statement;
     until boolean_expression

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

See also

while Statement, for Statement

6.1.7.8 asm Inline

@@ ????

     asm (StatementList: String);

The asm inline statement is a GNU Pascal extension. It requires its parameter to be AT&T-noted assembler statements, and therefore it is not compatible with that one of Borland Pascal. statementlist is a string containing asm statements separated by semicolons.

6.1.7.9 with Statement

6.1.7.10 goto Statement

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

     goto label

(Under construction.)

6.1.7.11 Procedure Call

     subroutine_name;

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

6.1.7.12 The Declaring Statement

This statement allows to declare a variable within a statement part. It looks like this:

     var
       var_identifier: type_identifier;

or

     var
       var_identifier: type_definition;

and with initializing value:

     var
       var_identifier: type_identifier value expression;

or

     var
       var_identifier: type_definition value expression;

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

See also

Type Definition, Data Types

6.1.7.13 Loop Control Statements

These are

     Continue;

and

     Break;

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

6.1.8 Import Part and Module/Unit Concept

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

6.1.8.1 The Source Structure of ISO 10206 Extended Pascal Modules

@@ Description missing here

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

Sample module code with separate interface and implementation parts:

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

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

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

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

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

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

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

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

These non-standard simple GPC modules look like the following example. They do not have an export part, do not have a separate module-block, do not use import/export features.

Instead, you have to emulate the exporting/importing yourself using `attribute' and `external name'.

     module DemoMod3;
     
     type
       FooType = Integer;
     
     var
       Foo: FooType;
     
     procedure SetFoo (f: FooType); attribute (name = 'SetFoo');
     begin
       Foo := f
     end;
     
     function GetFoo: FooType; attribute (name = 'GetFoo');
     begin
       GetFoo := Foo;
     end;
     
     end.

     program ModDemo3 (Output);
     
     {$L demomod3.pas}  { explicitly link module }
     
     { Manually do the "import" from DemoMod3 }
     type
       FooType = Integer;
     
     procedure SetFoo (f: FooType); external name 'SetFoo';
     function  GetFoo: FooType;     external name 'GetFoo';
     
     begin
       SetFoo (999);
       WriteLn (GetFoo)
     end.

Module initialization and finalization:

The to begin do module initialization and to end do module finalization constructs now work on every target.

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

6.1.8.2 The Source Structure of UCSD/Borland Pascal Units

A generic GNU Pascal unit looks like the following:

     unit name;
     
     interface
     
     import_part
     
     interface_part
     
     implementation
     
     implementation_part
     
     initialization_part
     
     end.

The name of the unit should coincide with the name of the file with the extension stripped. (If not, you can tell GPC the file name with `uses foo in 'bar.pas'', see 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 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 results 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 to begin do, to end do.

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

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

6.2 Data Types

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

6.2.1 Type Definition

As described in Type Declaration, a type declaration part looks like this:

     type
        type_identifier = type_definition;
        ...
        type_identifier = type_definition;

where the left side is the type declaration and the right one the type definition side. GNU Pascal offers various possibilities to implement highly specialized and problem-specific data types.

6.2.2 Ordinal Types

An ordinal type is one that can be mapped to a range of whole numbers. It includes integer types, character types, enumerated types and subrange types of them.

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

An enumerated type defines a range of elements which are referred to by identifiers. Conversion from enumerated types to integer types is possible with the intrinsic function Ord. Conversion from integer to ordinal types is only possible by type-casting or using the extended form of `Succ'.

     var
       Foo: Char;       { foo can hold a character }
       Num: '0' .. '9'; { Can hold decimal digits, is a subrange type of Char }
       Day: (Monday, Tuesday, Wednesday, Thursday,
             Friday, Saturday, Sunday);  { Can hold weekdays }

See also

Ord, Chr, Type Casts

6.2.3 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 Pascal 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.)

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

See also: Subrange Types.

6.2.3.1 The CPU's Natural Integer Types

For most purposes, you will always use `Integer', a signed integer type which has the “natural” size of such types for the machine. On most machines GPC runs on, this is a size of 32 bits, so `Integer' usually has a range of `-2147483648..2147483647' (see 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 Cardinal, Word).

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

6.2.3.2 The Main Branch of 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 types (plus one Boolean type) are guaranteed to be compatible to the respective types of GNU C as listed below (whereas `Integer', `Cardinal' and `Word' themselves are not guaranteed to be compatible to any given C type). The sizes given, however, are not guaranteed. They are just typical values currently used on some platforms, but they may be actually shorter or longer on any given platform.

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'.

6.2.3.3 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 type attributes (see attribute). The type

     Integer attribute (Size = 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 attribute (Size = 32)', not just `Integer' which might be bigger. The same works with unsigned integer types such as `Cardinal' and `Word' and with Boolean types.

This way, you can't get a higher precision than that of `LongestInt' or `LongestCard' (see Main Branch Integer Types). If you need higher precision, you can look at the `GMP' unit (see GMP) which provides integer types with arbitrary precision, but their usage is different from normal integer types.

6.2.3.4 Integer Types and Compatibility

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 IA32 platform.

On the other hand, to increase compatibility to Borland Pascal and Delphi, GPC provides the alias name `Comp' for `LongInt' (64 bits on IA32) and `SmallInt' for `ShortInt' (16 bits on IA32). Note that BP treats `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.

6.2.3.5 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.

ByteInt

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

Byte

unsigned 8-bit integer type, `0..255',
compatible to `unsigned char' in GNU C.

ShortInt

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

ShortWord

unsigned 16-bit integer type, `0..65535',
compatible to `unsigned short int' in GNU C.

Integer

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

Word

unsigned 32-bit integer type, `0..4294967295',
compatible to `unsigned int' in GNU C.

MedInt

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

MedWord

unsigned 32-bit integer type, `0..4294967295',
compatible to `unsigned long int' in GNU C.

LongInt

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

LongWord

unsigned 64-bit integer type, `0..18446744073709551615',
compatible to `unsigned long long int' in GNU C.

LongestInt

signed 64-bit integer type, `-9223372036854775808..9223372036854775807'.

LongestWord

unsigned 64-bit integer type, `0..18446744073709551615'.

Comp

signed 64-bit integer type, `-9223372036854775808..9223372036854775807'.

SmallInt

signed 16-bit integer type, `-32768..32767'.

SizeType

integer type (usually unsigned) to represent the size of objects in memory

PtrDiffType

signed integer type to represent the difference between two positions in memory

PtrInt

signed integer type of the same size as a pointer

PtrWord

unsigned integer type of the same size as a pointer

To specify the number of bits definitely, use type attributes, attribute.

     program IntegerTypesDemo (Output);
     
     var
       ByteVar: Byte;
       ShortIntVar: ShortInt;
       Foo: MedCard;
       Big: LongestInt;
     
     begin
       ShortIntVar := 1000;
       Big := MaxInt * ShortIntVar;
       ByteVar := 127;
       Foo := 16#deadbeef
     end.

See also: Subrange Types.

6.2.4 Built-in Real (Floating Point) Types

GPC has three built-in floating point types to represent real numbers. Each of them is available under two names (for compatibility to other compilers and languages).

For most purposes, you will always use `Real' which is the only one of them that is part of Standard and Extended Pascal. If memory constraints apply, you might want to choose `ShortReal' for larger arrays. On the other hand, if high precision is needed, you can use `LongReal'. When interfacing with libraries written in other languages such as C, you will need the equivalents for their real types.

Note that not all machines support longer floating point types, so `LongReal' is the same as `Real' on these machines. Also, some machines may support a longer type, but not do all arithmetic operations (e.g. the `Sin' function, Sin) in a precision higher than that of `Real'. If you need higher precision, you can look at the `GMP' unit (see GMP) which provides rational and real numbers with arbitrary precision, but their usage is different from normal real types.

The following real types are guaranteed to be compatible to the real types of GNU C. The sizes given, however, are not guaranteed. They are just typical values used on any IEEE compatible floating point hardware, but they may be different on some machines.

6.2.5 Strings Types

There are several ways to use strings in GNU Pascal. One of them is the use of the intrinsic string type `String' which is a predefined schema type. The schema discriminant of this type holds the maximal length, which is of type Integer, so values up to MaxInt can be specified. For `String', an assignment is defined. There are many built-in functions and procedures for comfortable strings handling.

@@ ???? String procedures and functions.

Another way to use strings is to use arrays of type `Char'. For these, an intrinsic assignment is defined as well. Besides, `String' and `Char' are assignment compatible. The preferred way, however, is `String' because of the numerous possibilities for string handling.

6.2.6 Character Types

Character types are a special case of ordinal types.

See also

Ordinal Types, Chr, Ord, Pred, Succ.

6.2.7 Enumerated Types

     type
       enum_type_identifier = (identifier, ..., identifier);

An enumerated type is a a special case of ordinal types and defines a range of elements which are referred to by identifiers. Enumerated types are ordered by occurence in the identifier list. So, they can be used as index types in an array definition, and it is possible to define subranges of them. Since they are ordered, they can be compared to one another. The intrinsic function Ord applied to name_identifier returns the number of occurence in the identifier list (beginning with zero), Pred and Succ return the predecessor and successor of name_identifier. `Boolean' is a special case of an enumerated type.

See also

Ordinal Types, Array Types, Subrange Types, Ord, Boolean, Char, Pred, Succ.

6.2.8 File Types

Files are used to store data permanently, normally on hard drives or floppies. There are tree types of files available: text files, typed and untyped files.

Text files are used to store text in them, where typed files are used to store many entries of the same type in them, e.g. addresses. Text files and typed files are accessible by `Read' and `Write' operations and do not need the parameter `BlockSize' in `Reset' or `Rewrite'. On the other hand, untyped files are used to store any type of information in them but you need to use `BlockWrite' or `BlockRead' to store or retrieve data out of this file.

     var
       F1: Text;   { a textfile }
       F2: file of Real;   { a typed filed used to store real values in it }
       F3: File;   { an untyped file }

See also

File Routines, Write, Read, BlockRead, BlockWrite, Reset, Rewrite

6.2.9 Boolean (Intrinsic)

The intrinsic Boolean represents boolean values, i.e. it can only assume true and false (which are predefined constants). This type corresponds to the enumerated type

     type
       Boolean = (False, True);

Since it is declared this way, it follows:

     Ord (False) = 0
     Ord (True) = 1
     False < True

There are four intrinsic logical operators. The logical and, or and not. In Borland Pascal and GNU Pascal, there is a logical “exclusive or” xor.

See also

Enumerated Types, and, or, not, xor

6.2.10 Pointer (Intrinsic)

The intrinsic Pointer Type is a so-called unspecified or typeless pointer (i.e. a pointer which does not point to any type but holds simply a memory address).

See also

Pointer Types, nil

6.2.11 Type Definition Possibilities

• Subrange Types: Packed and non-packed Subranges
• Array Types: Fields (Array Types)
• Record Types: Structured Types (Record Types)
• Variant Records: Record Types with Varying Fields
• Schema Types: Schema Types
• Set Types: Set Types
• Pointer Types: Pointer Types
• Procedural Types: Procedures Types
• Object Types: Types for Object-Oriented Programming
• Type Initializers: Types Carrying an Initial Value for Variables
• Restricted Types: Hiding Internal Information about Types

6.2.11.1 Subrange Types

GNU Pascal supports Standard Pascal's subrange types:

     program SubrangeDemo;
     type
       MonthInt = 1 .. 12;
       Capital = 'A' .. 'Z';
       ControlChar = ^A .. ^Z;  { `^A' = `Chr (1)' is a BP extension }
     begin
     end.

Also possible: Subranges of enumerated types:

     program EnumSubrangeDemo;
     type
       { This is an enumerated type. }
       Days = (Mon, Tue, Wed, Thu, Fri, Sat, Sun);
     
       { This is a subrange of `Days'. }
       Working = Mon .. Fri;
     
     begin
     end.

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 IA32 CPU.

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

     program PackedSubrangeDemo;
     type
       MonthInt = packed 1 .. 12;
     begin
     end.

A variable of this type occupies the shortest possible (i.e., addressable) space in memory – one byte on an IA32 compatible CPU.

See also: packed.

6.2.11.2 Array Types

     type
       array_type_identifier = array [index_type] of element_type

or

     type
       array_type_identifier = array [index_type, ..., index_type] of element_type

The reserved word array defines an array type. index_type has to be an ordinal type, subrange type or an enumerated type, where several index types, separated by commas, are allowed. element_type is an arbitrary type. An element of an array is accessed by array_type_variable [index_number]. The upper and lower index bounds can be determined by the intrinsic functions High and Low.

     type
       IntArray = array [1 .. 20] of Integer;
       Foo      = array [(Mo, Tu, We, Th, Fr, Sa, Su)] of Char;
       Bar      = array [0 .. 9, 'a' .. 'z', (Qux, Glork1, Fred)] of Real;
       Baz1     = array [1 .. 10] of IntArray;
       { equal (but declared differently): }
       Baz2     = array [1 .. 10, 1 .. 20] of Integer;

See also

High, Low

6.2.11.3 Record Types

     type
       record_type_identifier = record
         field_identifier: type_definition;
         ...
         field_identifier: type_definition;
       end;

or, with a variant part,

     type
       record_type_identifier = record
         field_identifier: type_definition;
         ...
         field_identifier: type_definition;
       case bar: variant_type of
         selector: (field_declarations);
         selector: (field_declarations);
         ...
       end;

or, without a variant selector field,

     type
       record_type_identifier = record
         field_identifier: type_definition;
         ...
         field_identifier: type_definition;
       case variant_type of
         selector: (field_declarations);
         selector: (field_declarations);
         ...
       end;

The reserved word record defines a structure of fields. Records can be `packed' to save memory usage at the expense of speed.

The reserved word `record' and record types are defined in ISO 7185 Pascal. According to ISO Pascal, the variant type must be an identifier. GNU Pascal, like UCSD and Borland Pascal, also allows a subrange here.

A record field is accessed by record_type_variable . field_identifier

See also: packed, case Statement.

6.2.11.4 Variant Records

GPC supports variant records like in EP and BP. The following construction is not allowed in Extended Pascal, but in BP and GPC:

     program BPVariantRecordDemo;
     
     type
       PersonRec = record
         Age: Integer;
       case EyeColor: (Red, Green, Blue, Brown) of
         Red, Green : (WearsGlasses: Boolean);
         Blue, Brown: (LengthOfLashes: Integer);
       end;
     
     begin
     end.

In EP, the variant field needs a type identifier, which, of course, also works in GPC:

     program EPVariantRecordDemo;
     
     type
       EyeColorType = (Red, Green, Blue, Brown);
     
       PersonRec = record
         Age: Integer;
       case EyeColor: EyeColorType of
         Red, Green : (WearsGlasses: Boolean);
         Blue, Brown: (LengthOfLashes: Integer);
       end;
     
     begin
     end.

6.2.11.5 EP's Schema Types including `String'

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

     type
       RealArray (n: Integer) = array [1 .. n] of Real;
       Matrix (n, m: PositiveInteger) = array [1 .. n, 1 .. m] of Integer;

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);

The discriminants of every global or local schema variable are initialized at the beginning of the procedure, function or program where the schema variable is declared.

Schema-typed variables “know” about their discriminants. Discriminants can be accessed just like record fields:

     program Schema1Demo;
     type
       PositiveInteger = 1 .. MaxInt;
       RealArray (n: Integer) = array [1 .. n] of Real;
       Matrix (n, m: PositiveInteger) = array [1 .. n, 1 .. m] of Integer;
     
     var
       Foo: RealArray (42);
     
     begin
       WriteLn (Foo.n)  { yields 42 }
     end.

Schemata may be passed as parameters. While types of schema variables must always have specified discriminants (which may be other variables), formal parameters (by reference or by value) may be of a schema type without specified discriminant. In this, the actual parameter may posses any discriminant. The discriminants of the parameters get their values from the actual parameters.

Also, pointers to schema variables may be declared without a discriminant:

     program Schema2Demo;
     type
       RealArray (n: Integer) = array [1 .. n] of Real;
       RealArrayPtr = ^RealArray;
     var
       Bar: RealArrayPtr;
     begin
     end.

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 Pascal extension, the above can also be written as

     Bar := New (RealArrayPtr, 137)

The allocated variable behaves like any other schema variable:

     program Schema3Demo;
     type
       RealArray (n: Integer) = array [1 .. n] of Real;
       RealArrayPtr = ^RealArray;
     var
       Bar: RealArrayPtr;
       i: Integer;
     begin
       Bar := New (RealArrayPtr, 137);
       for i := 1 to Bar^.n do
         Bar^[i] := 42
     end.

Since the schema variable “knows” its size, pointers to schemata can be disposed just like other pointers:

     Dispose (Bar)

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.)

References to the schema discriminants are allowed, and the with statement is also allowed, so one can say:

     program SchemaWithDemo;
     type
       RealArray (n: Integer) = array [1 .. n] of Real;
     var
       MyArray: RealArray (42);
     begin
       WriteLn (MyArray.n);  { writes 42 }
       with MyArray do
         WriteLn (n);        { writes 42 }
     end.

Finally, here is a somewhat exotic example. Here, a `ColoredInteger' behaves just like an ordinary integer, but it has an additional property `Color' which can be accessed like a record field.

     program SchemaExoticDemo;
     
     type
       ColorType = (Red, Green, Blue);
       ColoredInteger (Color: ColorType) = Integer;
     
     var
       Foo: ColoredInteger (Green);
     
     begin
       Foo := 7;
       if Foo.Color = Red then
         Inc (Foo, 2)
       else
         Foo := Foo div 3
     end.

An important schema is the predefined `String' schema (according to Extended Pascal). It has one predefined discriminant identifier Capacity. GPC implements the String schema as follows:

     type
       String (Capacity: Cardinal) = record
         Length: 0 .. Capacity;
         Chars: packed array [1 .. Capacity + 1] of Char
       end;

The Capacity field may be directly referenced by the user, the Length field is referenced by a predefined string function Length (Str) and contains the current string length. Chars contains the chars in the string. The Chars and Length fields cannot be directly referenced by a user program.

If a formal value parameter is of type `String' (with or without discriminant), the actual parameter may be either a String schema, a fixed string (character array), a single character, a string literal or a string expression. If the actual parameter is a `String' schema, it is copied for the parameter in the usual way. If it is not a schema, a `String' schema is created automatically, the actual parameter is copied to the new variable and the Capacity field of the new variable is set to the length of the actual parameter.

Actual parameters to `var' parameters of type `String' must be `String' schemata, not string literals or character arrays.

     program StringDemo (Output);
     
     type
       SType = String (10);
       SPtr  = ^String;
     
     var
       Str : SType;
       Str2: String (100000);
       Str3: String (20) value 'string expression';
       DStr: ^String;
       ZStr: SPtr;
       Len : Integer value 256;
       Ch  : Char value 'R';
     
     { `String' accepts any length of strings }
     procedure Foo (z: String);
     begin
       WriteLn ('Capacity: ', z.Capacity);
       WriteLn ('Length  : ', Length (z));
       WriteLn ('Contents: ', z);
     end;
     
     { Another way to use dynamic strings }
     procedure Bar (SLen: Integer);
     var
       LString: String (SLen);
       FooStr: type of LString;
     begin
       LString := 'Hello world!';
       Foo (LString);
       FooStr := 'How are you?';
       Foo (FooStr);
     end;
     
     begin
       Str  := 'KUKKUU';
       Str2 := 'A longer string variable';
       New (DStr, 1000);  { Select the string Capacity with `New' }
       DStr^ := 'The maximum length of this is 1000 chars';
       New (ZStr, Len);
       ZStr^ := 'This should fit here';
       Foo (Str);
       Foo (Str2);
       Foo ('This is a constant string');
       Foo ('This is a ' + Str3);
       Foo (Ch);  { A char parameter to string routine }
       Foo ('');  { An empty string }
       Foo (DStr^);
       Foo (ZStr^);
       Bar (10000);
     end.

In the above example, the predefined procedure New was used to select the capacity of the strings. Procedure Bar also has a string whose size depends of the parameter passed to it and another string whose type will be the same as the type of the first string, using the type of construct.

All string and character types are compatible as long as the destination string is long enough to hold the source in assignments. If the source string is shorter than the destination, the destination is automatically blank padded if the destination string is not of string schema type.

6.2.11.6 Set Types

     set_type_identifier = set of set_element_type;

set_type_identifier is a set of elements from set_element_type which is either an ordinal type, an enumerated type or a subrange type. Set element representatives are joined together into a set by brackets:

     [set_element, ..., set_element]

`[]' indicates the empty set, which is compatible with all set types. Note: Borland Pascal restricts the maximal set size (i.e. the range of the set element type) to 256, GNU Pascal has no such restriction. The number of elements a set variable is holding can be determined by the intrinsic set function Card (which is a GNU Pascal extension, in Extended Pascal and Borland Pascal you can use SizeOf instead but note the element type size in bytes, then) to the set. There are four intrinsic binary set operations: the union `+', the intersection `*' and the difference `-'. The symmetric difference `><' is an Extended Pascal extension.

See also

Card, SizeOf

6.2.11.7 Pointer Types

     pointer_type_identifier = ^type_identifier;

A pointer of the type pointer_type_identifier holds the address at which data of the type type_identifier is situated. Unlike other identifier declarations, where all identifiers in definition part have to be declared before, in a pointer type declaration type_identifier may be declared after pointer_type_identifier. The data pointed to is accessed by `pointer_type_variable^'. To mark an unassigned pointer, the `nil' constant (which stands for “not in list”) has to be assigned to it, which is compatible with all pointer types.

     type
       ItselfFoo = ^ItselfFoo;  { possible but mostly senseless }
     
       PInt      = ^Integer;    { Pointer to an Integer }
     
       PNode     = ^TNode;      { Linked list }
       TNode     = record
         Key     : Integer;
         NextNode: PNode;
       end;
     
     var
       Foo, Bar: PInt;
     
     begin
       Foo := Bar;  { Modify address which foo is holding }
       Foo^ := 5;   { Access data foo is pointing to }
     end.

GPC also suports pointers to procedures or function and calls through them. This is a non-standard feature.

     program ProcPtrDemo (Output);
     
     type
       ProcPtr = ^procedure (i: Integer);
     
     var
       PVar: ProcPtr;
     
     procedure WriteInt (i: Integer);
     begin
       WriteLn ('Integer: ', i : 1)
     end;
     
     begin
       { Let PVar point to function WriteInt }
       PVar := @WriteInt;
     
       { Call the function by dereferencing the function pointer }
       PVar^ (12345)
     end.

See also: Pointer (Intrinsic).

6.2.11.8 Procedural and Functional Types

For procedures without a parameter list:

     procedure_type_identifier = procedure name_identifier;

or functions:

     function_type_identifier =
            function name_identifier: function_result_type;

For procedures with a parameter list:

     procedure_type_identifier =
            procedure name_identifier (parameter_list);

or functions:

     function_type_identifier =
            function name_identifier (parameter_list): function_result_type;

Procedural types can be used as procedures or functions respectively, but also a value can be assigned to them. Procedural types are a Borland Pascal extension. In Borland Pascal, function_result_type can only be one of these types: ordinal types, real types, pointer types, the intrinsic `String' type. In GNU Pascal every function result type for procedural types is allowed.

BP has procedural and functional types:

     type
       CompareFunction = function (Key1, Key2: String): Integer;
     
     function Sort (Compare: CompareFunction);
     begin
       ...
     end;

Standard Pascal has procedural and functional parameters:

     function Sort (function Compare (Key1, Key2: String): Integer);
     begin
       ...
     end;

Both ways have pros and cons, e.g. in BP you can save, compare, trade, etc. procedural values, or build arrays of them, while the SP way does not require a type declaration and prevents problems with uninitialized or invalid pointers (which in BP will usually crash the program).

GPC supports both ways. An important feature of Standard Pascal (but not BP) that GPC also supports is the possibility to pass local routines as procedural or functional parameters, even if the called routine is declared far remote. The called routine can then call the passed local routine and it will have access to the original caller's local variables.

     program LocalProceduralParameterDemo;
     
     procedure CallProcedure (procedure Proc);
     begin
       Proc
     end;
     
     procedure MainProcedure;
     var LocalVariable: Integer;
     
       procedure LocalProcedure;
       begin
         WriteLn (LocalVariable)
       end;
     
     begin
       LocalVariable := 42;
       CallProcedure (LocalProcedure)
     end;
     
     begin
       MainProcedure
     end.

See also: The Procedure, The Function, Subroutine Parameter List Declaration, Procedure Call.

6.2.11.9 Object Types

Object types are used to encapsulate data and methods. Furthermore, they implement a mechanism for inheritance.

See also

OOP

6.2.11.10 Initial values to type denoters

A type may be initialized to a value of expression when it is declared, like a variable, as in:

     program TypeVarInitDemo;
     type
       Int10   = Integer value 10;
       FooType = Real;
       MyType  = Char value Pred ('A');
       EType   = (a, b, c, d, e, f, g) value d;
     
     const
       Answer = 42;
     
     var
       ii : Int10;                    { Value of ii set to 10 }
       ch : MyType  value Pred ('z');
       aa : Integer value Answer + 10;
       foo: FooType value Sqr (Answer);
       e1 : EType;                    { value set to d }
       e2 : EType value g;            { value set to g }
     begin
     end.

Extended Pascal requires the type initializers to be constant expressions. GPC allows any valid expression.

Note, however, that the expressions that affect the size of storage allocated for objects (e.g. the length of arrays) may contain variables only inside functions or procedures.

GPC evaluates the initial values used for the type when an identifier is declared for that type. If a variable is declared with a type-denoter that uses a type-name which already has an initial value the latter initialization has precedence.

@@ GPC does not know how to calculate constant values for math functions in the runtime library at compile time, e.g. `Exp (Sin (2.4567))', so you should not use these kind of expressions in object size expressions. (Extended Pascal allows this.)

6.2.11.11 Restricted Types

GPC supports `restricted' types, defined in Extended Pascal. A value of a restricted type may be passed as a value parameter to a formal parameter possessing its underlying type, or returned as the result of a function. A variable of a restricted type may be passed as a variable parameter to a formal parameter possessing the same type or its underlying type. No other operations, such as accessing a component of a restricted type value or performing arithmetic, are possible.

     program RestrictedDemo;
     
     type
       UnrestrictedRecord = record
         a: Integer;
       end;
       RestrictedRecord = restricted UnrestrictedRecord;
     
     var
       r1: UnrestrictedRecord;
       r2: RestrictedRecord;
       i: restricted Integer;
       k: Integer;
     
     function AccessRestricted (p: UnrestrictedRecord): RestrictedRecord;
     var URes: UnrestrictedRecord;
     begin
       { The parameter is treated as unrestricted, even though the actual
         parameter may be restricted }
       URes.a := p.a;
       { It is allowed to assign a function result }
       AccessRestricted := URes;
     end;
     
     begin
       r1.a := 354;
     
       { Assigning a restricted function result to a restricted variable }
       { @@ Verify if this should really be allowed????? }
       r2 := AccessRestricted (r1);
     
       { Passing a restricted value to unrestricted formal parameter is ok }
       r2 := AccessRestricted (r2);
     
       {$ifdef BUG}
       { *** The following statements are not allowed *** }
       k := r2.a;      { field access (reading) }
       r2.a := 100;    { field access (writing) }
       r1 := r2;       { assignment source is restricted }
       r2 := r1;       { assignment target is restricted }
       r1 := AccessRestricted (r2); { assigning a restricted function
                                      result to an unrestricted object }
       i  := 16#ffff;  { assignment target is restricted }
       k  := i + 2;    { arithmetic with restricted value }
       {$endif}
     end.

6.2.12 Machine-dependencies in Types

• Endianness: How Integer Types are Stored on Different Machines
• Alignment: How Variables are Placed in Memory

6.2.12.1 Endianness

Endianness means the order in which the bytes of a value larger than one byte are stored in memory. This affects, e.g., integer values and pointers while, e.g., arrays of single-byte characters are not affected. The GPC `String' schema, however, contains `Capacity' and `Length' fields before the character array. These fields are integer values larger than one byte, so the `String' schema is affected by endianness.

Endianness depends on the hardware, especially the CPU. The most common forms are:

• Little-endian

  Little-endian machines store the least significant byte on the lowest memory address (the word is stored little-end-first).

  E.g., if the 32 bit value $deadbeef is stored on memory address $1234 on a little-endian machine, the following bytes will occupy the memory positions:

  Address	Value
  $1234	$ef
  $1235	$be
  $1236	$ad
  $1237	$de

  Examples for little-endian machines are IA32 and compatible microprocessors and Alpha processors.

• Big-endian

  Big-endian machines store the most significant byte on the lowest memory address (the word is stored big-end-first).

  E.g., if the 32 bit value $deadbeef is stored on memory address $1234 on a big-endian machine, the following bytes will occupy the memory positions:

  Address	Value
  $1234	$de
  $1235	$ad
  $1236	$be
  $1237	$ef

  Examples for big-endian machines are the Sparc and Motorola m68k CPU families and most RISC processors. Big-endian byte order is also used in the Internet protocols.

Note: There are processors which can run in both little-endian and big-endian mode, e.g. the MIPS processors. A single program, however, (unless it uses special machine code instructions) will always run in one endianness.

Under normal circumstances, programs do not need to worry about endianness, the CPU handles it by itself. Endianness becomes important when exchanging data between different machines, e.g. via binary files or over a network. To avoid problems, one has to choose the endianness to use for the data exchange. E.g., the Internet uses big-endian data, and most known data formats have a specified endianness (usually that of the CPU on which the format was originally created). If you define your own binary data format, you're free to choose the endianness to use.

To deal with endianness, GPC predefines the symbol `__BYTES_LITTLE_ENDIAN__' on little-endian machines and `__BYTES_BIG_ENDIAN__' on big-endian machines. Besides, the Run Time System defines the constant `BytesBigEndian' as False on little-endian machines and True on big-endian machines.

There are also the symbols `__BITS_LITTLE_ENDIAN__', `__BITS_BIG_ENDIAN__', `__WORDS_LITTLE_ENDIAN__', `__WORDS_BIG_ENDIAN__' and the constants `BitsBigEndian' and `WordsBigEndian' which concern the order of bits within a byte (e.g., in packed records) or of words within multiword-numbers, but these are usually less important.

The Run Time System also contains a number of routines to convert endianness and to read or write data from/to binary files in a given endianness, independent of the CPU's endianness. These routines are described in the RTS reference (see Run Time System), under `endianness'. The demo program endiandemo.pas contains an example on how to use these routines.

6.2.12.2 Alignment

(Under construction.) @@ ????

6.3 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.

• Built-in Operators
• User-defined Operators

6.3.1 Built-in Operators

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

In an assignment statement, `:=' has lower precedence than all operators. (This is rather obvious from the syntax of assignment statements, and is merely noted for programmers familiar with C where `=' is an operator.)

     <    =    >    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).

6.3.2 User-defined Operators

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

     program OperatorDemo;
     
     type
       Vector3 = record
         x, y, z: Real;
       end;
     
     var
       a, b, c: Vector3 = (1, 2, 3);
     
     operator + (u, v: Vector3) w: Vector3;
     begin
       w.x := u.x + v.x;
       w.y := u.y + v.y;
       w.z := u.z + v.z;
     end;
     
     begin
       c := a + b
     end.

Between the closing parenthesis of the argument list and the result variable (`w' in the above example), GPC allows an optional equal sign. This is not allowed in PXSC, but it is consistent with Extended Pascal's function result variable definitions, where the equal sign is obligatory (but also 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. Also, the other real-type operators do not meet the requirements of PXSC; a module which fixes that would be a welcome contribution.

6.4 Procedure And Function Parameters

• Protected Parameters: Parameters declared `protected' or `const'
• Conformant Arrays: The Standard way to pass arrays of variable size
• Open Arrays: BP's alternative to Conformant Arrays

6.4.1 Parameters declared as `protected' or `const'

All the following works in GPC:

     procedure Foo (protected a, b, c: Integer);    { 3 arguments }
     procedure Foo (a, b, c, protected: Integer);   { 4 arguments }
     procedure Foo (a, b, protected, c: Integer);   { 4 arguments }
     procedure Foo (protected: Integer);            { 1 argument  }
     procedure Foo (var protected: Integer);        { 1 argument  }
     procedure Foo (protected protected: Integer);  { 1 argument  }

Furthermore, GPC supports const, according to BP, which is equivalent to either protected or protected var, up to the compiler's discretion.

6.4.2 The Standard way to pass arrays of variable size

@@ (Under construction.)

A feature of Standard Pascal level 1.

6.4.3 BP's alternative to Conformant Arrays

Borland Pascal “open array” formal parameters are implemented into GPC. Within the function body, they have integer type index with lower bound 0.

In constrast to conformant arrays (which are not supported by BP), open arrays allow any ordinal type as the index of the actual parameter (which is useful, e.g., if you want to be able to pass values of any enumeration type). However, they lose information about the lower bound (which is a problem, e.g., if you want to return information to the caller that relates to the actual array index, like the function `IOSelect' in the Run Time System does).

6.5 Accessing parts of strings (and other arrays)

GPC allows the access of parts (“slices”) of strings as defined in Extended Pascal. For example:

     program StringSliceDemo;
     
     const
       HelloWorld = 'Hello, world!';
     
     begin
       WriteLn (HelloWorld[8 .. 12])  { yields `world' }
     end.

As an extension, it also allows write access to a string slice:

     program SliceWriteDemo;
     
     var
       s: String (42) = 'Hello, world!';
     
     begin
       s[8 .. 12] := 'folks';
       WriteLn (s)  { yields `Hello, folks!' }
     end.

As a further extension, GPC allows slice access also to non-string arrays. However, the usefulness of this feature is rather limited because of Pascal's strict type checking rules: If you have, e.g., an `array [1 .. 10] of Integer' and take a slice `[1 .. 5]' of it, it will not be compatible to another `array [1 .. 5] of Integer' because distinct array types are not compatible in Pascal, even if they look the same.

However, array slice access can be used in connection with conformant or open array parameters. See the program arrayslicedemo.pas (in the demos directory) for an example.

6.6 Pointer Arithmetics

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

GPC implements the address operator @ (a Borland Pascal extension).

     program PointerArithmeticDemo;
     var
       a: array [1 .. 7] of Char;
       p, q: ^Char;
       i: Integer;
     
     {$X+}  { We need extended syntax for pointer arithmetic }
     
     begin
       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;
     
       p := @a[7];
       q := @a[3];
       i := q - p;    { yields 4 }
     end.

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.

6.7 Type Casts

In some cases, especially in low-level situations, Pascal's strong typing can be an obstacle. To temporarily circumvent this, GPC defines explicit “type casts” in a Borland Pascal compatible way.

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. Both the value's type and the destination type must be ordinal or pointer types. The ordinal value (extended to pointers to mean the address) is preserved in the cast.

An example:

     program TypeCastDemo;
     
     var
       Ch: Char;
       i: Integer;
     
     begin
       i := Integer (Ch)
     end.

Another, more complicated, example:

     program TypeCst2Demo;
     
     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 }
     
     begin
       Foo1 := CharPtr (Bar);
       Foo2 := CharPtr (Succ (Bar))
     end.

However, because of risks involved with type casts, explained below, and because type-casts are non-standard, 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];

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 Alignment).

Variable type casts

It is also possible to temporarily change the type of a variable (more generally, any “lvalue”, i.e. something whose address can be taken), without converting its contents in any way. This is called variable type casting.

The syntax is the same as for value type casting. 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 lvalues, not on expressions.
• The result of a variable type casting is still an lvalue, so it can be used, e.g., on the left side of an assignment, or as the operand of an address operator, or passed by reference to a procedure.
• No values are converted in variable type-casting. The contents of the variable, seen as a raw bit pattern, are just interpreted according to the new type.
• 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.
• 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 Endianness).

There are cases where a type-cast could be either a value or a variable cast. This is when both types are ordinal or pointer, and of the same size, and the value is an lvalue. Fortunately, in those cases, the results of both forms are the same, since the same ordinal values (or pointer addresses) are represented by the same bit patterns (when of the same size). Therefore, it doesn't matter which form of type-casting is actually used in these cases.

When dealing with objects (see OOP), it is sometimes necessary to cast a polymorphic pointer to an object into a pointer to a more specialized (derived) object (after checking the actual type). However, the `as' operator is a safer approach, so type-casts should be used there only for backward-compatibility (e.g., to BP).

See also: absolute, Alignment, Endianness, OOP, Ord, Chr, Round, Trunc.

6.8 Object-Oriented Programming

GNU Pascal allows multiple object models. The oldest one follows the object model of Borland Pascal 7.0. The BP object extensions are almost fully implemented into GPC. This includes inheritance, virtual and non-virtual methods, constructors, destructors, pointer compatibility, extended `New' syntax (with constructor call and/or as a Boolean function), extended `Dispose' syntax (with destructor call).

The Borland object model is different from the ISO draft, but now we have also partial support of ISO draft (plus the Borland Delphi Object Extensions which are quite similar to the ISO draft). Moreover most of traditional Mac Pascal object model is covered.

The syntax for an object type declaration is as follows:

     program ObjectDemo;
     
     type
       Str100 = String (100);
     
       FooParentPtr = ^FooParent;
       FooPtr = ^Foo;
     
       FooParent = object
         constructor Init;
         destructor Done; virtual;
         procedure Bar (c: Real); virtual;
         function Baz (b, a, z: Char) = s: Str100;  { not virtual }
       end;
     
       Foo = object (FooParent)
         x, y: Integer;
         constructor Init (a, b: Integer);
         destructor Done; virtual;
         procedure Bar (c: Real); virtual;  { overrides `FooParent.Bar' }
         z: Real;  { GPC extension: data fields after methods }
         function Baz: Boolean;  { new function }
       end;
     
     constructor FooParent.Init;
     begin
       WriteLn ('FooParent.Init')
     end;
     
     destructor FooParent.Done;
     begin
       WriteLn ('I''m also done.')
     end;
     
     procedure FooParent.Bar (c: Real);
     begin
       WriteLn ('FooParent.Bar (', c, ')')
     end;
     
     function FooParent.Baz (b, a, z: Char) = s: Str100;
     begin
       WriteStr (s, 'FooParent.Baz (', b, ', ', a, ', ', z, ')')
     end;
     
     constructor Foo.Init (a, b: Integer);
     begin
       inherited Init;
       x := a;
       y := b;
       z := 3.4;
       FooParent.Bar (1.7)
     end;
     
     destructor Foo.Done;
     begin
       WriteLn ('I''m done.');
       inherited Done
     end;
     
     procedure Foo.Bar (c: Real);
     begin
       WriteLn ('Foo.Bar (', c, ')')
     end;
     
     function Foo.Baz: Boolean;
     begin
       Baz := True
     end;
     
     var
       Ptr: FooParentPtr;
     
     begin
       Ptr := New (FooPtr, Init (2, 3));
       Ptr^.Bar (3);
       Dispose (Ptr, Done);
       New (Ptr, Init);
       with Ptr^ do
         WriteLn (Baz ('b', 'a', 'z'))
     end.

Remarks:

• The ordering of data fields and methods can be mixed.
• GPC supports the `public' and `private' declarations like BP, and in addition also `protected' (scope limited to the current type and its descendants).
• 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.

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
       z := c;
       inherited bar (z)  { or: FooParent.Bar (z) }
     end;

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)

6.9 Compiler Directives And The Preprocessor

GPC, like UCSD Pascal and BP, treats comments beginning with a `$' immediately following the opening `{' or `(*' as a compiler directive. As in Borland Pascal, {$...} and (*$...*) are equivalent. When a single character plus a `+' or `-' follows, this is also called a compiler switch. All of these directives are case-insensitive (but some of them have case-sensitive arguments). Directives are local and can be changed during one compilation (except include files etc. where this makes no sense).

In general, compiler directives are compiler-dependent. (E.g., only the include directive {$I FileName} is common to UCSD and BP.) Because of BP's popularity, GPC supports all of BP's compiler directives (and ignores those that are unnecessary on its platforms – these are those not listed below), but it knows a lot more directives.

Some BP directives are – of course not by chance – just an alternative notation for C preprocessor directives. But there are differences: BP's conditional definitions (`{$define Foo}') go into another name space than the program's definitions. Therefore you can define conditionals and check them via {$ifdef Foo}, but the program will not see them as an identifier `Foo', so macros do not exist in Borland Pascal.

GPC does support macros, but disables this feature when the `--no-macros' option or the dialect option `--borland-pascal' or `--delphi' is given, to mimic BP's behaviour. Therefore, the following program will react differently when compiled with GPC either without special options or with, e.g., the `--borland-pascal' option (and in the latter case, it behaves the same as when compiled with BP).

     program MacroDemo;
     
     const Foo = 'Borland Pascal';
     
     {$define Foo 'Default'}
     
     begin
       WriteLn (Foo)
     end.

Of course, you should not rely on such constructs in your programs. To test if the program is compiled with GPC, you can test the `__GPC__' conditional, and to test the dialect used in GPC, you can test the dialect, e.g., with `{$ifopt borland-pascal}'.

In general, almost every GPC specific command line option (see GPC Command Line Options) can be turned into a compiler directive (exceptions are those options that contain directory names, such as `--unit-path', because they refer to the installation on a particular system, and therefore should be set system-wide, rather than in a source file):

     --foo       {$foo}
     --no-foo    {$no-foo}
     -Wbar       {$W bar}     { note the space after the `W' }
     -Wno-bar    {$W no-bar}

The following table lists some such examples as well as all those directives that do not correspond to command-line options or have syntactical alternatives (for convenience and/or BP compatibility).

     --[no-]short-circuit   $B+ $B- like in Borland Pascal:
                                    $B- means short-circuit Boolean
                                    operators; $B+ complete evaluation
     
     --[no-]io-checking     $I+ $I- like in Borland Pascal:
                                    enable/disable I/O checking
     
     --[no-]range-checking  $R+ $R- like in Borland Pascal:
                                    enable/disable range checking
     
     --[no-]stack-checking  $S+ $S- like in Borland Pascal:
                                    enable/disable stack checking
     
     --[no-]typed-address   $T+ $T- like in Borland Pascal:
                                    make the result of the address
                                    operator and the Addr function a
                                    typed or untyped pointer
     
     -W[no-]warnings        $W+ $W- enable/disable warnings. Note: in
                                    `--borland-pascal' mode, the
                                    short version is disabled because
                                    $W+/$W- has a different meaning in
                                    Borland Pascal (which can safely be
                                    ignored in GPC), but the long version
                                    is still available.
     
     --[no-]extended-syntax $X+ $X- mostly like in Borland Pascal:
                                    enable/disable extended syntax
                                    (ignore function resuls, operator
                                    definitions, `PChar', pointer
                                    arithmetic, ...)
     
     --borland-pascal               disable or warn about GPC features
     --extended-pascal              not supported by the standard or
     --pascal-sc                    dialect given, do not warn about its
     etc.                           ``dangerous'' features (especially BP).
                                    The dialect can be changed during one
                                    compilation via directives like,
                                    e.g., `{$borland-pascal}'.
     
     {$M Hello!}                    write message `Hello!' to
                                    standard error during compilation. In
                                    `--borland-pascal' mode, it is
                                    ignored it if only numbers follow
                                    (for compatibility to Borland
                                    Pascal's memory directive)
     
     {$define FOO}                  like in Borland Pascal:
     or                             define FOO (for conditional compilation)
     {$CIDefine FOO}                (case-insensitively)
     
     --cidefine=FOO                 the same on the command line
     
     {$CSDefine FOO}                define FOO case-sensitively
     
     -D FOO                         the same on the command line
     or                             Note: `--define' on the command
     --csdefine=FOO                 line is case-sensitive like in GCC,
     or                             but `{$define}' in the source code
     --define=FOO                   is case-insensitive like in BP
     
     {$define loop while True do}   define `loop' to be `while True do'
     or                             as a macro like in C. The name of the
     {$CIDefine loop ...}           macro is case-insensitive. Note:
                                    Macros are disabled in
                                    `--borland-pascal' mode because BP
                                    doesn't support macros.
     
     --cidefine="loop=..."          the same on the command line
     
     {$CSDefine loop ...}           define a case-sensitive macro
     
     --csdefine="loop=..."          the same on the command line
     or
     --define="loop=..."
     
     {$I FileName}                  like in Borland Pascal:
                                    include filename.pas
                                    (the name is converted to lower case)
     
     {$undef FOO}                   like in Borland Pascal: undefine FOO
     
     {$ifdef FOO}                   conditional compilation
       ...                          (like in Borland Pascal).
     {$else}                        Note: GPC predefines the symbol
       ...                          `__GPC__' (with two leading
     {$endif}                       and trailing underscores).
     
     {$include "filename.pas"}      include (case-sensitive)
     
     {$include <filename.pas>}      the same, but don't search in the
                                    current directory

and all the other C preprocessor directives.

You also can use the preprocessor directives in C style, e.g. `#include', but this is deprecated because of possible confusion with Borland Pascal style `#42' character constants. Besides, in the Pascal style, e.g. `{$include "foo.bar"}', there may be more than one directive in the same line.

6.10 Routines Built-in or in the Run Time System

In this section we describe the routines and other declarations that are built into the compiler or part of the Run Time System, sorted by topics.

• File Routines
• String Operations
• Accessing Command Line Arguments
• Memory Management Routines
• Operations for Integer and Ordinal Types
• Complex Number Operations
• Set Operations
• Date And Time Routines

6.10.1 File Routines

Extended Pascal treats files quite differently from Borland Pascal. GPC supports both forms, even in mixed ways, and provides many extensions.

@@ A lot missing here

• An example of getting the size of a file (though a `FileSize' function is already built-in).

            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
                FileSize := 0
              else
                FileSize := LastPosition (f) + 1;
              Unbind(f);
            end;
       

  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.

• GPC implements lazy text file I/O, i.e. does a Put as soon as possible and a Get as late as possible. This should avoid most of the problems sometimes considered to be the most stupid feature of Pascal. When passing a file buffer as parameter the buffer is validated when the parameter is passed.
• GPC supports direct access files. E.g., declaring a type for a file that contains 100 integers.

            program DirectAccessFileDemo;
            type
              DFile = file [1 .. 100] of Integer;
            var
              F: DFile;
              P, N: 1 .. 100;
            begin
              Rewrite (F);
              P := 42;
              N := 17;
              SeekWrite (F, P);
              Write (F, N)
            end.
       

  The following direct access routines may be applied to a direct access file:

  SeekRead (F, N); { Open file in inspection mode, seek to record N }
  

  SeekWrite (F, N); { Open file in generation mode, seek to record N }
  

  SeekUpdate (F, N); { Open file in update mode, seek to record N }
  

  Update (F); { Writes F^, position not changed. F^ kept. }
  

  p := Position (F); { Yield the current record number }
  

  p := LastPosition (F); { Yield the last record number in file }

  If the file is open for inspection or update, Get may be applied. If the file is open for generation or update, Put may be applied.

• In BP, you can associate file variables with files using the `Assign' procedure which GPC supports.

            program AssignTextDemo;
            var
              t: Text;
              Line: String (4096);
            begin
              Assign (t, 'mytext.txt');
              Reset (t);
              while not EOF (t) do
                begin
                  ReadLn (t, Line);
                  WriteLn (Line)
                end
            end.
       

• 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'. Extended Pascal has the `Bind' function that binds a variable to an external entity as well as `Unbind' to undo a binding and the function `Binding' to get the current binding of a variable.

  GPC supports these routines when applied to files. The compiler will reject binding of other object types.

  Only the fields `Bound' and `Name' of the predefined record type `BindingType' are required by Extended Pascal. Additionally, GPC implements some extensions. For the full definition of `BindingType', see BindingType.

  The following is an example of binding:

            program BindingDemo (Input, Output, f);
            
            var
              f: bindable Text;
              b: BindingType;
            
            procedure BindFile (var f: Text);
            var
              b: BindingType;
            begin
              Unbind (f);
              b := Binding (f);
              repeat
                Write ('Enter a file name: ');
                ReadLn (b.Name);
                Bind (f, b);
                b := Binding (f);
                if not b.Bound then
                  WriteLn ('File not bound -- try again.')
              until b.Bound
            end;
            
            begin
              BindFile (f);
              { Now the file f is bound to an external file. We can use the
                implementation defined fields of BindingType to check if the
                file exists and is readable, writable or executable. }
              b := Binding (f);
              Write ('The file ');
              if b.Existing then
                WriteLn ('exists.')
              else
                WriteLn ('does not exist.');
              Write ('It is ');
              if not b.Readable then Write ('not ');
              Write ('readable, ');
              if not b.Writable then Write ('not ');
              Write ('writable and ');
              if not b.Executable then Write ('not ');
              WriteLn ('executable.')
            end.
       

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. GPC does not behave like this.

6.10.2 String Operations

In the following description, s1 and s2 may be arbitrary string expressions, s is a variable of string type.

WriteStr (s, write-parameter-list)

ReadStr (s1, read-parameter-list)

Write to a string and read from a string. The parameter lists are identical to `Write'/`Read' from Text files. The semantics is closely modeled after file I/O.

Index (s1, s2)

If s2 is empty, return 1 else if s1 is empty return 0 else returns the position of s2 in s1 (an integer).

Length (s1)

Return the length of s1 (an integer from 0 .. s1.Capacity).

Trim (s1)

Returns a new string with spaces stripped of the end of s.

SubStr (s1, i)

SubStr (s1, i, j)

Return a new substring of s1 that contains j characters starting from i. If j is missing, return all the characters starting from i.

EQ (s1, s2)

NE (s1, s2)

LT (s1, s2)

LE (s1, s2)

GT (s1, s2)

GE (s1, s2)

Lexicographic comparisons of s1 and s2. Returns a boolean result. Strings are not padded with spaces.

s1 = s2

s1 <> s2

s1 < s2

s1 <= s2

s1 > s2

s1 >= s2

Lexicographic comparisons of s1 and s2. Returns a boolean result. The shorter string is blank padded to length of the longer one, but only in `--extended-pascal' mode.

GPC supports string catenation with the + operator or the `Concat' function. All string-types are compatible, so you may catenate any chars, fixed length strings and variable length strings.

     program ConcatDemo (Input, Output);
     
     var
       Ch  : Char;
       Str : String (100);
       Str2: String (50);
       FStr: packed array [1 .. 20] of Char;
     
     begin
        Ch := '$';
        FStr := 'demo';  { padded with blanks }
        Write ('Give me some chars to play with: ');
        ReadLn (Str);
        Str := '^' + 'prefix:' + Str + ':suffix:' + FStr + Ch;
        WriteLn (Concat ('Le', 'ng', 'th'), ' = ', Length (Str));
        WriteLn (Str)
     end.

Note: The length of strings in GPC is limited only by the range of `Integer' (at least 32 bits, i.e., 2 GB, on most platforms), or the available memory, whichever is smaller).

When trying to write programs portable to other EP compilers, it is however safe to assume a limit of about 32 KB. At least Prospero's Extended Pascal compiler limits strings to 32760 bytes. DEC Pascal limits strings to 65535 bytes.

6.10.3 Accessing Command Line Arguments

GPC supports access to the command line arguments with the BP compatible ParamStr and ParamCount functions.

• ParamStr[0] is the program name,
• ParamStr[1] .. ParamStr[ParamCount] are the arguments.

The program below accesses the command line arguments.

     program CommandLineArgumentsDemo (Output);
     
     var
       Counter: Integer;
     
     begin
       WriteLn ('This program displays command line arguments one per line.');
       for Counter := 0 to ParamCount do
         WriteLn ('Command line argument #', Counter, ' is `',
                  ParamStr (Counter), '''')
     end.

6.10.4 Memory Management Routines

Besides the standard `New' and `Dispose' routines, GPC also allows BP style dynamic memory management with GetMem and FreeMem:

     GetMem (MyPtr, 1024);
     FreeMem (MyPtr, 1024);

One somehow strange feature of Borland is not supported: You cannot free parts of a variable with FreeMem, while the rest is still used and can be freed later by another FreeMem call:

     program PartialFreeMemDemo;
     
     type
       Vector = array [0 .. 1023] of Integer;
       VecPtr = ^Vector;
     
     var
       p, q: VecPtr;
     
     begin
       GetMem (p, 1024 * SizeOf (Integer));
       q := VecPtr (@p^[512]);
     
       { ... }
     
       FreeMem (p, 512 * SizeOf (Integer));
     
       { ... }
     
       FreeMem (q, 512 * SizeOf (Integer));
     end.

6.10.5 Operations for Integer and Ordinal Types

• Bit manipulations: The BP style bit shift operators shl and shr exist in GPC as well as bitwise and, or, xor and not for integer values.

            2#100101 and (1 shl 5) = 2#100000
       

  GPC also supports and, or, xor and not as procedures:

            program BitOperatorProcedureDemo;
            var x: Integer;
            begin
              x := 7;
              and (x, 14);  { sets x to 6 }
              xor (x, 3);   { sets x to 5 }
            end.
       

• Succ, Pred: The standard functions `Succ' and `Pred' exist in GPC and accept a second parameter.
• Increment, decrement: The BP built-in Procedures Inc and Dec exist in GPC.

            program IncDecDemo;
            var
              i: Integer;
              c: Char;
            begin
              Inc (i);     { i := i + 1; }
              Dec (i, 7);  { i := i - 7; }
              Inc (c, 3);  { c := Succ (c, 3); }
            end.
       

• Min, Max: These are a GNU Pascal extension and work for reals as well as for ordinal types. Mixing reals and integers is okay, the result is real then.

6.10.6 Complex Number Operations

@@ A lot of details missing here

• binary operators +, -, *, / and unary -, +
• exponentiation operators (pow and **)
• functions (Sqr, SqRt, Exp, Ln, Sin, Cos, ArcSin, ArcCos, ArcTan)
• number info with Re, Im and Arg functions
• numbers constructed by Cmplx or Polar

The following sample programs illustrates most of the Complex type operations.

     program ComplexOperationsDemo (Output);
     
     var
       z1, z2: Complex;
       Len, Angle: Real;
     
     begin
       z1 := Cmplx (2, 1);
       WriteLn;
       WriteLn ('Complex number z1 is: (', Re (z1) : 1, ',', Im (z1) : 1, ')');
       WriteLn;
       z2 := Conjugate(z1); { GPC extension }
       WriteLn ('Conjugate of z1 is: (', Re (z2) : 1, ',', Im (z2) : 1, ')');
       WriteLn;
       Len   := Abs (z1);
       Angle := Arg (z1);
       WriteLn ('The polar representation of z1 is: Length=', Len : 1,
                ', Angle=', Angle : 1);
       WriteLn;
       z2 := Polar (Len, Angle);
       WriteLn ('Converting (Length, Angle) back to (x, y) gives: (',
                Re (z2) : 1, ',', Im (z2) : 1, ')');
       WriteLn;
       WriteLn ('The following operations operate on the complex number z1');
       WriteLn;
       z2 := ArcTan (z1);
       WriteLn ('ArcTan (z1) = (', Re (z2), ', ', Im (z2), ')');
       WriteLn;
       z2 := z1 ** 3.141;
       WriteLn ('z1 ** 3.141 =', Re (z2), ', ', Im (z2), ')');
       WriteLn;
       z2 := Sin (z1);
       WriteLn ('Sin (z1) = (', Re (z2), ', ', Im (z2), ')');
       WriteLn ('(Cos, Ln, Exp, SqRt and Sqr exist also.)');
       WriteLn;
       z2 := z1 pow 8;
       WriteLn ('z1 pow 8 = (', Re (z2), ', ', Im (z2), ')');
       WriteLn;
       z2 := z1 pow (-8);
       WriteLn ('z1 pow (-8) = (', Re (z2), ', ', Im (z2), ')');
     end.

6.10.7 Set Operations

GPC supports Standard Pascal set operations. In addition it supports the Extended Pascal set operation symmetric difference (set1 >< set2) operation whose result consists of those elements which are in exactly one of the operannds.

It also has a function that counts the elements in the set: `a := Card (set1)'.

In the following description, S1 and S2 are variables of set type, s is of the base type of the set.

S1 := S2

Assign a set to a set variable.

S1 + S2

Union of sets.

S1 - S2

Difference between two sets.

S1 * S2

Intersection of two sets.

S1 >< S2

Symmetric difference

S1 = S2

Comparison between two sets. Returns boolean result. True if S1 has the same elements as S2.

S1 <> S2

Comparison between two sets. Returns boolean result. True if S1 does not have the same elements as S2.

S1 < S2

S2 > S1

Comparison between two sets. Returns boolean result. True if S1 is a strict subset of S2.

S1 <= S2

S2 >= S1

Comparison between two sets. Returns boolean result. True if S1 is a subset of (or equal to) S2.

s in S1

Set membership test between an element s and a set. Returns boolean result. True if s is an element of S1.

The following example demonstrates some set operations. The results of the operations are given in the comments.

     program SetOpDemo;
     
     type
       TCharSet = set of Char;
     
     var
       S1, S2, S3: TCharSet;
       Result: Boolean;
     
     begin
       S1 := ['a', 'b', 'c'];
       S2 := ['c', 'd', 'e'];
       S3 := S1 + S2;       { S3 = ['a', 'b', 'c', 'd', 'e'] }
       S3 := S1 * S2;       { S3 = ['c'] }
       S3 := S1 - S2;       { S3 = ['a', 'b'] }
       S3 := S1 >< S2;      { S3 = ['a', 'b', 'd', 'e'] }
     
       S1 := ['c', 'd', 'e'];
       Result := S1 = S2;   { False }
       Result := S1 < S2;   { False }
       Result := S1 <= S2;  { True }
     
       S1 := ['c', 'd'];
       Result := S1 <> S2;  { True }
       Result := S2 > S1;   { True }
       Result := S2 >= S1   { True }
     end.

6.10.8 Date And Time Routines

procedure GetTimeStamp (var t: TimeStamp);

function Date (t: TimeStamp): packed array [1 .. DateLength] of Char;

function Time (t: TimeStamp): packed array [1 .. TimeLength] of Char;

DateLength and TimeLength are implementation dependent constants.

GetTimeStamp (t) fills the record `t' with values. If they are valid, the Boolean flags are set to True.

TimeStamp is a predefined type in the Extended Pascal standard. It may be extended in an implementation, and is indeed extended in GPC. For the full definition of `TimeStamp', see TimeStamp.

6.11 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 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.

• Importing Libraries from Other Languages
• Exporting GPC Libraries to Other Languages

6.11.1 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 a module.

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

     File `callc.c':
     
     #include <unistd.h>
     #include "callc.h"
     
     int foo = 1;
     
     void bar (void)
     {
       sleep (foo);
     }

     File `callc.h':
     
     /* Actually, we wouldn't need this header file, and could instead
        put these prototypes into callc.c, unless we want to use callc.c
        also from other C source files. */
     
     extern int foo;
     extern void bar (void);

Then your program can look like this:

     program CallCDemo;
     
     {$L callc.c}  { Or: `callc.o' if you don't have the source }
     
     var
       MyFoo: CInteger; external name 'foo';
     
     procedure Bar; external name 'bar';
     
     begin
       MyFoo := 42;
       Bar
     end.

Or, if you want to provide a `CallCUnit' unit:

     unit CallCUnit;
     
     interface
     
     var
       MyFoo: CInteger; external name 'foo';
     
     procedure Bar; external name 'bar';
     
     implementation
     
     {$L callc.c}  { Or: `callc.o' if you don't have the source }
     
     end.

     program CallCUDemo;
     
     uses CallCUnit;
     
     begin
       MyFoo := 42;
       Bar
     end.

You can either link your program manually with `callc.o' or put a compiler directive `{$L callc.o}' into your program or unit, and then GPC takes care of correct linking. If you have the source of the C library (you always have it if it is Free Software), you can even write `{$L callc.c}' in the program (like above). Then GPC will also link with callc.o, but in addition GPC will run the C compiler whenever callc.c has changed if `--automake' is given, too.

While it is often convenient, there is no must to give the C function `bar' the name `Bar' in Pascal; you can name it as you like (e.g., the variable `MyFoo' has a C name of `foo' in the example above).

If you omit the `name', the default is the Pascal identifier, converted to lower-case. So, in this example, the `name' could be omitted for `Bar', but not for `MyFoo'.

It is important that data types of both languages are mapped correctly onto each other. C's `int', for instance, translates to GPC's `CInteger', and C's `unsigned long' to `MedCard'. For a complete list of integer types with their C counterparts, see Integer Types.

In some cases it can be reasonable to translate a C pointer parameter to a Pascal `var' parameter. Since const parameters in GPC can be passed by value or by reference internally, possibly depending on the system, `const foo *' parameters to C functions cannot reliably be declared as `const' in Pascal. However, Extended Pascal's `protected var' can be used since this guarantees passing by reference.

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 `{$gpc-main="GPCmain"}'.

6.11.2 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 (only) of each identifier, so `procedure FooBAR' must be imported as `extern void Foobar()' from C.
• If you want to specify the external name explicitly, use `attribute':

            procedure FooBAR; attribute (name = 'FooBAR');
            begin
              WriteLn ('FooBAR')
            end;
       

  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
              VMT = record
                ObjectSize: PtrInt;     { Size of object in bytes }
                NegObjectSize: PtrInt;  { Negated size }
                Methods: array [1 .. n] of procedure;
                  { Pointers to the virtual methods. The entries are of the
                     repective procedure or function types. }
              end;
       

  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.
• 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 command-line option `--gpc-main="GPCmain"' (see the previous subsection).

6.12 Notes for Debugging

• 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.
• Forward referencing pointers generate debug info that appears as generic pointers.
• No information of `with' statements is currently given to the debugger.
• When debugging, please note that the Initial Letter In Each Identifier Is In Upper Case And The Rest Are In Lower Case, unless explicitly overriden with `name' (see name). This is to reduce name clashes with libc and other possible libraries.
• All visible GPC Run Time System routines have linker names starting with `_p_'.
• The linker name of the main program is `pascal_main_program'. This is done because ISO Standard wants to have the program name in a separate name space.

6.13 How to use I18N in own programs

This chapter discusses shortly how to use the Internationalization (I18N) features of GNU Pascal.

Prerequisite

You need to have gettext installed. Try to compile demos/gettextdemo.pas. Furthermore, you should download a tool named `pas2po' from http://www.gnu-pascal.org/contrib/eike/.