.PAS File Format – File structure

The file as text

A Pascal source file is plain text. The language does not care about case, and white space (spaces, tabs, line ends and form feeds) only separates tokens. Line ends may be CR LF (DOS and Windows), LF (Unix, macOS) or CR (classic Mac OS). Many old DOS files end with a Ctrl-Z character (code 26), which Turbo Pascal and Free Pascal read as the end of the file.

The encoding is not part of the language. Turbo Pascal files are in the DOS code page of the machine (often 437 or 850). Delphi before 2009 read the system ANSI code page. Delphi 2009 and later read UTF-8 (with a byte order mark) or UTF-16, and Free Pascal reads UTF-8 by default and takes another code page from {$codepage} or the -Fc option. Identifiers are ASCII in the old dialects; Delphi and Free Pascal also allow letters above 127 in names.

The kinds of file

The file viewer on this site tells these apart by the word that opens the file, after any comments and compiler directives: Pascal program, Pascal unit, Pascal library, Delphi package or plain Pascal source file.

Program

A program is a heading, an optional uses clause, a block of declarations and the main statement part, ending with a full stop.

program Count(Input, Output);   { ISO 7185 needs the file list; Turbo, Delphi and Free Pascal do not }
uses Crt;                       { units; not in ISO 7185 }
label 99;
const Limit = 10;
type Small = 0..Limit;
var I: Small;
procedure Show(N: Integer);
begin
  WriteLn(N);
end;
begin
  for I := 1 to Limit do Show(I);
  99:
end.

• ISO 7185 fixes the order of the declaration parts: label, const, type, var, then procedures and functions. Turbo Pascal, Delphi and Free Pascal allow the parts in any order and any number of times.
• The program parameters in the heading (Input, Output) are required by ISO 7185, and ignored by Turbo Pascal, Delphi and Free Pascal.
• The program name need not match the file name, but Delphi and Lazarus name the project after it.

Unit

A unit is a compilation unit with a public face and a private body. UCSD Pascal and Turbo Pascal 4 introduced units; ISO 7185 has none (Extended Pascal has modules instead).

unit Shapes;

interface

uses Math;                       { visible to every user of the unit }

type
  TPoint = record X, Y: Double; end;

function Distance(const A, B: TPoint): Double;

implementation

uses SysUtils;                   { private to this unit }

function Distance(const A, B: TPoint): Double;
begin
  Result := Sqrt(Sqr(A.X - B.X) + Sqr(A.Y - B.Y));
end;

initialization
  { runs when the program starts }
finalization
  { runs when the program ends }
end.

• The interface part holds declarations that other units may use: constants, types, variables and the headings of procedures and functions. The implementation part holds the bodies, and may declare more things that stay private.
• A uses clause may follow interface and implementation. Two units may use each other only if at least one of the two uses clauses is in an implementation part.
• initialization and finalization are in Delphi, and in Free Pascal in its Delphi and Object Pascal modes. Units initialise in the order of the uses clauses (a unit before the units that use it) and finalise in the reverse order. Turbo Pascal units end with begin … end. instead, whose statements are the initialisation, and have no finalisation (they use ExitProc).
• Delphi (from XE2) and Free Pascal allow dotted unit names, such as System.SysUtils or Winapi.Windows. The prefix is the unit scope.
• A unit may carry a hint directive after its name: unit Old platform;, unit Foo deprecated 'use Bar';.
• The file name is the unit name (Shapes.pas); a Delphi unit may be told another with uses Shapes in 'other\shapes.pas'. Free Pascal looks for the lower case name on case sensitive systems.

Library

A library builds a DLL (Windows), a shared object (Linux, other Unix) or a dylib (macOS) instead of a program. Its exports clause names the routines that others may call. The code between begin and end. runs when the library loads.

library Tools;

function Twice(X: Integer): Integer; stdcall;
begin
  Result := X * 2;
end;

exports
  Twice,
  Twice name 'twice_value' index 1;

begin
end.

exports Name name 'external' index n; sets the exported name and the ordinal. A routine that is only exports-listed must use a calling convention the caller expects (stdcall or cdecl).

Package

A Delphi package is a library of units that other programs load at run time (a .bpl file) or link in. Its .dpk source has only two lists. Lazarus packages describe themselves in an XML .lpk file instead, which is not Pascal.

package Widgets;

{$R *.res}
{$DESIGNONLY}

requires
  rtl,
  vcl;

contains
  WidgetUnit in 'WidgetUnit.pas',
  OtherUnit;

end.

Files that go with Pascal source

Include files

The directive {$I file} (or {$INCLUDE file}) reads another file at that point, as if its text were written there. An include file has no header of its own, so it may hold constants, types, whole routines or part of a statement; the .inc extension is a convention. In {$R *.dfm} the star stands for the name of the current unit. See Compiler directives for {$I %DATE%} and the other compiler information includes.