Subject: v21i063: Pascal to C translator, Part18/32 Newsgroups: comp.sources.unix Approved: rsalz@uunet.UU.NET X-Checksum-Snefru: 9f2f4d5e 2dd11476 631da2e1 db86d191 Submitted-by: Dave Gillespie Posting-number: Volume 21, Issue 63 Archive-name: p2c/part18 #! /bin/sh # This is a shell archive. Remove anything before this line, then unpack # it by saving it into a file and typing "sh file". To overwrite existing # files, type "sh file -c". You can also feed this as standard input via # unshar, or by typing "sh 'src/p2c.man' <<'END_OF_FILE' X.\" p2c Copyright 1989 Dave Gillespie X.TH P2C 1 "local" X.SH NAME Xp2c \- Pascal to C translator, version 1.14 X.SH SYNOPSIS X.B p2c X[ options ] [ file [ module ] ] X.SH DESCRIPTION X.I P2c Xis a tool for translating Pascal programs into C. The input consists Xof a set of source files in any of the following Pascal dialects: XHP Pascal, Turbo/UCSD Pascal, DEC VAX Pascal, Oregon Software Pascal/2, XMacintosh Programmer's Workshop Pascal, Sun/Berkeley Pascal. XModula-2 syntax is also supported. Output is a set of X.B .c Xand X.B .h Xfiles that comprise an equivalent program in any of several dialects Xof C. Output code may be kept machine- and dialect-independent, or Xit may be targeted to a specific machine and compiler. Most reasonable XPascal programs are converted into fully functional C which will compile Xand run with no further modifications, although X.I p2c Xsometimes chooses to generate readable code at the expense of absolute Xgenerality. X.I P2c Xendeavors to insert notes and warning messages into the output code Xto point out areas which may require human intervention. Output code Xis arranged to be readable and efficient, and to make use of C idioms Xwherever possible. The main goal of the translation is to produce C Xfiles which are pleasant and "natural" enough to be acceptable as the new Xsource files for a program. In a pinch, X.I p2c Xwill also serve as an ad hoc Pascal compiler. X.PP XCode generated by X.I p2c Xnormally does not assume characters are signed or unsigned. XAlso, it assumes X.B int Xis the same as either X.B short Xor X.B long Xbut does not depend on which. However, if X.B int Xis not the same as X.BR long Xit is best to use a modern C compiler which supports prototypes. XGenerated code does not require an ANSI-compatible compiler X(unless ANSI-style code is requested), but it does use various XANSI-standard library routines. X.PP XAll generated code includes the file X.I Xwhich in turn includes X.I Xand various other common resources. Also, many translated programs Xwill need to be linked with the run-time library, typically X.I -lp2c. X.PP XGiven a file name, X.I p2c Xreads from the specified file and outputs to a file with a X.B .c Xsuffix added or substituted. For example, X.IP "" 5 Xp2c myfile.pas X.PP Xreads from X.I myfile.pas Xto produce the file X.I myfile.c. XThe input file may contain a Pascal main program or a Xsingle Pascal module (or "unit" in Turbo and UCSD Pascal nomenclature), Xor it may just contain a number of procedures and declarations. X.I P2c Xis designed to work for correct input programs. That is, it will accept Xpartial programs but may occasionally core dump if the input refers to Xundefined symbols. X.PP XIf the input is a module, the translator will also produce a file X.IB module .h Xcontaining a translation of the module's interface section. XThe implementation section may be omitted in which case only the X.B .h Xfile will be interesting. If the program or module has include files, Xthese may cause additional X.B .c Xfiles to be generated depending on the value of the X.B ExpandIncludes Xoption (see below). X.PP XIf no file name is given, X.I p2c Xreads Pascal from the standard input and writes the resulting C to Xstandard output (though a X.B .h Xfile may still be produced). If a file name and module name are given, Xthe file may include several modules (or units). The specified module Xis translated; any others are skipped. The output files will be named X.IB module .c Xand X.IB module .h . X.I P2c Xnever translates more than one module per run. X.PP XBefore starting, X.I p2c Xreads the file X.I --HOMEDIR--/p2crc Xfor a number of configuration parameters. (The actual path used on your Xsystem may vary. The X.B \-i Xoption is a handy way to examine this file.) XIf the P2CRC environment variable is set, it gives the name of a file Xto read instead of the system file; this file can start with X.B Include %H/p2crc Xto include the system file. Next, X.I p2c Xattempts to read the file X.I p2crc Xin your directory for further configuration. If this file does not Xexist, X.I p2c Xlooks for X.I .p2crc Xinstead. X.SH OPTIONS X.TP X.BI \-o "\ cfile" XUse X.I cfile Xin place of X.IB file .c Xor X.IB module .c Xas the primary output file. A single dash (`\-o \-') says to write the XC code to the standard output. X.TP X.BI \-h "\ hfile" XUse X.I hfile Xin place of X.IB module .h Xas the output file for interface text. This only has effect if the Xinput is an HP Pascal module or a Turbo Pascal unit. X.TP X.BI \-s "\ sfile" XRead interface text from X.I sfile Xbefore beginning the translation. This file typically contains one or Xmore modules, often with interface sections omitted for speed, which the Xprogram or module being translated will use. (Typically the X.B ImportFrom Xand X.B ImportDir Xparameters in X.I p2crc Xare set up to allow X.I p2c Xto locate interface text without needing any X.B \-s Xoptions.) If there are several X.B \-s Xoptions in the command, the X.I sfiles Xare read from left to right. X.TP X.BI \-p n XDisplay progress of translation in the form of a line number/file name Xdisplay. This is refreshed every X.I n Xlines, 25 by default. X.TP X.BI \-c "\ rcfile" XRead local configuration commands from X.I rcfile Xinstead of X.I p2crc Xor X.I .p2crc. XA dash (`\-c \-') in place of X.I rcfile Xcauses no local configuration file to be used. X.TP X.B \-v X("Vanilla.") Do not read from the system configuration file X.I --HOMEDIR--/p2crc. XSince some of the parameters in this file are required, your local Xconfiguration file must include those parameters instead. This Xalso suppresses the file named by the P2CRC environment variable. X.TP X.BI \-H "\ homedir" XUse X.I homedir Xinstead of X.I --HOMEDIR-- Xas the X.I p2c Xhome directory. The system X.I p2crc Xfile will be searched for in this directory. X.TP X.BI \-I pattern XAdd X.I pattern Xto the X.B ImportDir Xsearch list of places to find modules which are imported. The pattern Xshould include a X.I %s Xto represent the module name, and should evaluate to a potential file name Xfor that module's source code. For example, X.B ../%s.pas Xlooks for X.IB modulename .pas Xin the parent of the current directory. X.TP X.B \-i XThis special option (which must be the only argument on the Xcommand line if used) simply copies the system configuration Xfile X.I --HOMEDIR--/p2crc Xto the standard output in its entirety. (It may be used with X.BR \-H , Xbut X.B \-i Xis most useful precisely when you don't know the Xlocation of the home directory.) X.TP X.B \-q XQuiet mode. Suppresses output of status messages during translation. X.TP X.BI \-E n XAbort translation after X.I n Xerrors. If X.I n Xis omitted it defaults to zero, which means unlimited errors are allowed. XUse X.B -E1 Xto make X.I p2c Xhalt after the first error. X.TP X.B \-e XEcho the Pascal source into the output file, surrounded by #ifdefs. XThis is the same as the X.B CopySource Xparameter in the X.I p2crc Xfile. X.TP X.B \-a XProduce modern ANSI C. This is a convenient override for the X.B AnsiC Xparameter in the X.I p2crc Xfile. X.TP X.BI \-L "\ language" XSelect input language name, such as VAX or TURBO. This is a convenient Xoverride for the X.B Language Xparameter. X.TP X.B \-V XVerbose mode. This causes X.I p2c Xto generate an additional ".log" file with further details of the Xtranslation, such as a list of warnings and notes including those Xwhich are suppressed in the regular output. X.TP X.B \-M0 XDisable memory conservation. This prevents X.I p2c Xfrom freeing various data structures after translating each function, Xin case this new conservation feature causes unforseen problems. X.TP X.B \-R XRegression testing mode. Formats notes and warning messages in a way Xthat makes it easier to run X.IR diff (1) Xon the output of X.I p2c. X.PP X.I P2c Xalso understands a few debugging options which may occasionally be Xuseful when tracking down translation problems. The X.BI \-d n Xoption sets the "debug level" to X.I n, Xa small integer which is normally zero. Debugging output is Xwritten into the regular output file along with the C code; the Xhigher your X.I n, Xthe more "wallpaper" you get. Also, X.B \-t Xprints debugging information at every Pascal token, X.BI \-B n Xenables line-breaker debugging, and X.BI \-C n Xenables comment placement debugging. X.SH CHOICE OF SOURCE LANGUAGE XThe X.B Language Xconfiguration parameter or X.B \-L Xcommand-line option tells X.I p2c Xwhich Pascal dialect to expect in the input file. Any language features Xwhich do not overlap between dialects are supported all of the time. The X.B Language Xparameter is consulted when a syntax or usage is detected that has different Xmeanings in two different dialects, and also to determine default values Xfor various other translation parameters as described below. X.PP XThe following language words are supported by X.I p2c. XNames are case-insensitive. X.TP 8 X.B HP XHP Pascal. This is the default language. All features of HP Standard XPascal, the Pascal Workstation version, are supported except as noted Xin BUGS below. Some features of MODCAL, HP's extended Pascal, are also Xsupported. This is a superset of ISO standard Pascal, including Xconformant arrays and procedural parameters. X.TP X.B HP-UX XHP Pascal, HP-UX version. Almost identical to the "HP" dialect. X.TP X.B Turbo XTurbo Pascal 5.0 for the IBM PC. Few conflicts with HP Pascal, so the X.B Language Xparameter is not often needed for Turbo. (Most important is that the Turbo Xand HP dialects use 16 and 32 bit integers, respectively.) X.TP X.B UCSD XUCSD Pascal. Similar to Turbo in many ways. X.TP X.B MPW XMacintosh Programmer's Workshop Pascal 2.0. Should also do a pretty Xgood job for Lightspeed Pascal. Object Pascal features are not supported, Xnor is the fact that X.B char Xvariables are sometimes stored in 16 bits. X.TP X.B VAX XVAX/VMS Pascal version 3.5. Most but not all language features supported. XThis has not yet been tested on large programs. X.TP X.B Oregon XOregon Software Pascal/2. All features implemented. X.TP X.B Berk XBerkeley Pascal with Sun extensions. X.TP X.B Modula XModula-2. Based on Wirth's X.I Programming in Modula-2, X3rd edition. Proper setting of the X.B Language Xparameter is X.I not Xoptional. Translation will be incomplete in most cases, but should be Xgood enough to work with. Structure of local sub-modules is essentially Xignored; like-named identifiers may be confused. Type WORD is translated Xas an integer, but type ADDRESS is translated as char * or void *; this Xmay cause inconsistencies in the output code. X.IP XModula-2 modules have two parts in separate files. Suppose these are Xcalled X.I foo.def X(definition part) and X.I foo.mod X(implementation part) for module X.I foo. XThen a pattern like X.B %s.def Xmust be included in the X.B ImportDir Xlist, and X.B LibraryFile Xmust be changed to refer to X.I system.m2 Xinstead of X.I system.imp. XTo translate the definition part, give the command X.IP X\ \ \ \ \ p2c foo.def X.IP Xto translate the definition part into files X.I foo.h Xand X.IR foo.c ; Xthe latter will usually be empty. The command X.IP X\ \ \ \ \ p2c -s foo.def foo.mod X.IP Xwill translate the implementation part into file X.I foo.c. X.PP XEven if all language features are supported for a dialect, some Xpredefined functions may be omitted. In these cases, the function call Xwill be translated literally into C with a warning. Some hand modification Xmay be required. X.SH CONFIGURATION PARAMETERS X.I P2c Xis highly configurable. The defaults are suitable for most applications, Xbut customizing these parameters will help you get the best possible Xtranslation. Since the output of X.I p2c Xis intended to be used as human-maintainable source code, there are many Xparameters for describing the coding style and conventions you prefer. XOthers give hints about your program that help X.I p2c Xto generate more correct, efficient, or readable code. X.PP XThe X.I p2crc Xfiles contain a list of parameters, one per line. The system Xconfiguration file, which may be viewed using the X.B \-i Xoption to X.I p2c, Xserves as an example of the proper format. Parameter names are Xcase-insensitive. If a parameter name occurs exactly once in the system X.I p2crc, Xthis indicates that it must have a unique value and the last value given to Xit by the Xconfiguration files is used. Other parameters are written several times Xin a row; these are lists to which each configuration line adds an entry. X.PP XMany X.I p2crc Xoptions take a numeric value of 0 or 1, roughly corresponding to X"no" or "yes." Sometimes a blank value or the value "\fBdef\fR" Xcorresponds to an intermediate "maybe" state. For example, the stylistic Xoption X.B ExtraParens Xswitches between copious or minimal parentheses in expressions, with Xthe default being a nice compromise intended to be best for readers Xwith an average knowledge of C operator precedences. X.PP XConfiguration options may also be embedded in the source file in the Xform of Pascal comments: X.PP X\ \ \ \ \ {ShortOpt=0} {AvoidName=fred} X.br X\ \ \ \ \ {FuncMacro slope(x,y)=atan2(y,x)*RadDeg} X.PP Xdisables automatic short-circuiting of X.B and Xand X.B or Xexpressions, adds "\fIfred\fR" to the list of names to avoid using in Xgenerated C code, and defines a special translation for the Pascal Xprogram's X.I slope Xfunction Xusing the standard C X.I atan2 Xfunction and a constant X.I RadDeg Xpresumably defined in the program. Whitespace is generally not allowed Xin embedded parameters. XThe `=' sign is required for embedded parameters, though it is optional in X.I p2crc Xfiles. Comments within embedded parameters are delimited by `##'. XNumeric parameters may replace `=' with `+' or `-' to increase Xor decrease the parameter; list-based parameters may use `-' to remove Xa name from a list rather than adding it. Also, the parameter name Xby itself in comment braces means to restore the parameter's value Xthat was current before the last change: X.PP X\ \ \ \ \ {VarFiles=0 ## Pass FILE *'s params by value even if VAR} X.br X.I \ \ \ \ \ some declarations X.br X\ \ \ \ \ {VarFiles ## Back to original FILE * passing} X.PP Xcauses the parameter X.B VarFiles Xto have the value 0 for those few declarations, without affecting the Xparameter's value elsewhere in the file. X.PP XIf an embedded parameter appears in an include file or in interface text Xfor a module, Xthe effect of the assignment normally carries over to any programs that Xincluded that file. If the parameter name is preceded by a `*', then Xthe assignment is automatically undone after the source file that contains Xit ends: X.PP X\ \ \ \ \ {IncludeFrom strings=} X.br X\ \ \ \ \ {*ExportSymbol=pascal_%s} X.br X\ \ \ \ \ module strings; X.PP Xwill record the location of the X.I strings Xmodule's include file for the rest of the translation, but the assignment Xof X.B ExportSymbol Xpertains only to the module itself. X.PP XFor the complete list of X.I p2crc Xparameters, run X.I p2c Xwith the X.B \-i Xoption. Here are some additional comments on selected parameters: X.TP 15 X.B ImportAll XBecause Turbo Pascal only allows one unit per source file, X.I p2c Xnormally stops reading past the word X.I implementation Xin a file being scanned for interface text. But HP Pascal allows several Xmodules per file and so this would not be safe to do. The X.B ImportAll Xoption lets you override the default behavior for your Pascal dialect. X.TP X.B AnsiC XThis parameter selects which dialect of C to use. If 1, all conventions Xof ANSI C such as prototypes, X.B void * Xpointers, etc. are used. If 0, only strict K&R (first edition) C is used. XThe default is to use "traditional UNIX C," which includes X.B enum Xand X.B void Xbut not X.B void * Xor prototypes. Once again there are a number of other parameters which Xmay be used to control the individual features if just setting X.B AnsiC Xis not enough. X.TP X.B C++ XAt present X.I p2c Xdoes not use much of C++ at all. The default action is to generate code Xthat will compile in either language. X.TP X.B UseVExtern XMany non-UNIX linkers prohibit variables from being defined (not declared) Xby more than one source file. One module must declare, e.g., "int foo;", Xand all others must declare "extern int foo;". X.I P2c Xaccomplishes this by declaring public variables "\fBvextern\fR" Xin header files, and arranging for the macro X.B vextern Xto expand to X.B extern Xor to nothing when appropriate. If you set X.BR UseVExtern =0 X.I p2c Xwill instead declare variables in a simpler way that works only on XUNIX-style linkers. X.TP X.B UseAnyptrMacros XCertain C reserved words have meanings which may vary from one C Ximplementation to another. X.I P2c Xuses special capitalized names for these words; these names are Xdefined as macros in the file X.I p2c.h Xwhich all translated programs include. You can set X.BR UseAnyptrMacros =0 Xto disable the use of these macros. Note that the functions of many of Xthese macros can also be had directly using other parameters; for example, X.B UseConsts Xallows you to specify whether your target language recognizes the word X.B const Xin constant declarations. The default is to use the X.B Const Xmacro instead, so that your code will be portable to either kind of Ximplementation. X.IP X.B Signed Xexpands to the reserved word X.B signed Xif that word is available, otherwise it is given a null definition. XSimilarly, X.B Const Xexpands to X.B const Xif that feature is available. The words X.B Volatile Xand X.B Register Xare also defined in X.I p2c.h, Xalthough X.I p2c Xdoes not use them at present. The word X.B Char Xexpands to X.B char Xby default, but might need to be redefined to X.B signed char Xor X.B unsigned char Xin a particular implementation. This is used for the Pascal character Xtype; lowercase X.B char Xis used when the desired meaning is "byte," not "character." X.IP XThe word X.B Static Xalways expands to X.B static Xby default. This is used in situations where a function or variable is Xdeclared static to make it local to the source file; lowercase X.B static Xis used for static local variables. Thus you can redefine X.B Static Xto be null if you want to force private names to be public for purposes Xof debugging. X.IP XThe word X.B Void Xexpands to X.B void Xin all cases; it is used when declaring a function with no return value. XThe word X.B Anyptr Xis a typedef for X.B void * Xor X.B char * Xas necessary; it represents a generic pointer. X.TP X.B UsePPMacros XThe X.I p2c.h Xheader also declares two macros for function prototyping, X.BR PP (x) Xand X.BR PV (). XThese macros are used as follows: X.IP X\ \ \ \ \ Void foo PP( (int x, int y, Char *z) ); X.br X\ \ \ \ \ Char *bar PV( ); X.IP XIf prototypes are available, these macros will expand to X.IP X\ \ \ \ \ Void foo (int x, int y, Char *z); X.br X\ \ \ \ \ Char *bar (void); X.IP Xbut if only old-style declarations are supported, you instead get X.IP X\ \ \ \ \ Void foo (); X.br X\ \ \ \ \ Char *bar (); X.IP XBy default, X.I p2c Xuses these macros for all function declarations, but function X.I definitions Xare written in old-style C. The X.B UsePPMacros Xparameter can be set to 0 to disable all use of X.B PP Xand X.BR PV , Xor it can be set to 1 to use the macros even when defining a function. X(This is accomplished by preceding each old-style definition with a X.BR PP -style Xdeclaration.) If you know your code will always be Xcompiled on systems that support prototyping, it is prettier to set X.BR Prototypes =1 Xor simply X.BR AnsiC =1 Xto get true function prototypes. X.TP X.B EatNotes XNotes and warning messages containing any of these strings as sub-strings Xare not omitted. Each type of message includes an identifier like X.BR [145] ; Xyou can add this identifier to the X.B EatNotes Xlist to suppress that message. Another useful form is to use a variable Xname or other identifier to suppress warnings about that variable. The Xstrings are a space-separated list, and thus may not contain embedded spaces. XTo suppress notes around a section of code, use, e.g., X.I {EatNotes+[145]} Xand X.I {EatNotes-[145]}. XMost notes are generated during parsing, but to suppress those generated Xduring output the string may need to remain in the list far beyond the point Xwhere it appears to be generated. Use the string "1" or "0" to disable or Xenable all notes, respectively. X.TP X.B ExpandIncludes XThe default action is to expand Pascal include files in-line. This Xmay not be desirable if include files are being used to simulate modules. XWith X.BR ExpandIncludes =0, X.I p2c Xattempts to convert include files containing only whole procedures and Xglobal declarations into analogous C include files. This may not always Xwork, though; if you get error messages, don't use this option. By Xcombining this option with X.BR StaticFunctions =0, Xthen doing some fairly minor editing on the result, you can convert Xa pseudo-modular Pascal program into a truly modular collection of C Xsource files. X.TP X.B ElimDeadCode XSome transformations that X.I p2c Xdoes on the program may result in unreachable or "dead" code. By Xdefault X.I p2c Xremoves such code, but sometimes it removes more than it should. XIf you have "if false" segments which you wish to retain in C, you Xmay have to set X.BR ElimDeadCode =0. X.TP X.B SkipIndices XNormally Pascal arrays not based at zero are "shifted" down for C, Xpreserving the total size of the array. A Pascal array a[2..10] is Xtranslated to a C array a[9] with references like "a[i]" changed to X"a[i-2]" everywhere. If X.B SkipIndices Xis set to a value of 2 or higher, this array would instead be translated Xto a[11] with the first two elements never used. This arrangement may Xgenerate incorrect code, though, for tricky source programs. X.TP X.B FoldConstants XPascal non-structured constants generally translate to X.BR #define 's Xin C. Set this to 1 to have constants instantiated directly into the Xcode. This may be turned on or off around specific constant declarations. XSet this to 0 to force X.I p2c Xto make absolutely no assumptions about the constant's value in generated Xcode, so that you can change the constant later in the C code without Xinvalidating the translation. The default is to allow X.I p2c Xto take advantage of its knowledge of a constant's value, such as by Xgenerating code that assumes the constant is positive. X.TP X.B VarStrings XIn HP Pascal, a parameter of the form "var s : string" will match a Xstring variable of any size; a hidden size parameter is passed which Xmay be accessed by the Pascal X.I strmax Xfunction. You can prevent X.I p2c Xfrom creating a hidden size parameter by setting X.BR VarString =0. X(Note that each function uses the value of X.B VarStrings Xas of the X.I first Xdeclaration of the function that is parsed, which is often in the interface Xsection of a module.) X.TP X.B Prototypes XControl whether ANSI C function prototypes are used. Default is according to X.BR AnsiC . XThis also controls whether to include parameter names or just their types Xin situations where names are optional. The X.B FullPrototyping Xparameter allows prototypes to be generated for declarations but not Xfor definitions (older versions of Lightspeed C required this). If you Xuse a mixture of prototypes and old-style definitions, types like short Xand float will be promoted to int and double as required by the ANSI Xstandard, unless X.B PromoteArgs Xis used to override this. The X.B CastArgs Xparameter controls whether type-casts are used in function arguments; Xby default they are used only if prototypes are not available. X.TP X.B StaticLinks XHP Pascal and Turbo Pascal each include the concept of procedure or Xfunction pointers, though with somewhat different syntaxes. X.I P2c Xrecognizes both notational styles. Another difference is that HP's Xprocedure pointers can point to nested procedures, while Turbo's can Xpoint only to global procedures. In HP Pascal a procedure pointer must Xbe stored as a X.B struct Xcontaining both a pure C function pointer and a "static link," a pointer Xto the parent procedure's locals. (The static link is NULL for global Xprocedures.) This notation can be forced by setting X.BR StaticLinks =1. XIn Turbo, the default X.RB ( StaticLinks =0) Xis to use plain C function pointers with no static links. A third option X.RB ( StaticLinks =2) Xuses structures with static links, but assumes the links are always NULL Xwhen calling through a pointer (if you need compatibility with the HP Xformat but know your procedures are global). X.TP X.B SmallSetConst XPascal sets are translated into one of two formats, depending on the size Xof the set. If all elements have ordinal values in the range 0..31, the Xset is translated as a single integer variable using bit operations. X(The X.B SetBits Xparameter may be used to change the upper limit of 31.) XThe X.B SmallSetConst Xparameter controls whether these small-sets are used, and, if so, how Xconstant sets should be represented in C. X.IR XFor larger sets, an array of X.B long Xis used. The X.IR s [0] Xelement contains the number of succeeding array elements Xwhich are in use. Set elements in the range 0..31 are stored in the X.IR s [1] Xarray element, and so on. Sets are normalized so that X.IR s [ s [0]] Xis nonzero for any nonempty set. The standard run-time library Xincludes all the necessary procedures for operating on sets. X.TP X.B ReturnValueName XThis is one of many "naming conventions" parameters. Most of these Xtake the form of a X.IR printf -like Xstring containing a X.I %s Xwhere the relevant information should go. In the case of X.BR ReturnValueName , Xthe X.I %s Xrefers to a function name and the resulting string gives the name of Xthe variable to use to hold the function's return value. Such a variable Xwill be made if a function contains assignments to its return value Xburied within the body, so that X.I return Xstatements cannot conveniently be used. Some parameters X.RB ( ReturnValueName Xincluded) do not require the X.I %s Xto be present in the format string; for example, the standard X.I p2crc Xfile stores every function's return value in a variable called X.I Result. X.TP X.B AlternateName X.I P2c Xnormally translates Pascal names into C names verbatim, but occasionally Xthis is not possible. A Pascal name may be a C reserved word or Xtraditional C name like X.I putc, Xor there may be several like-named things that are hidden from each other by XPascal's scoping rules but must be global in C. In these situations X.I p2c Xuses the parameter X.B AlternateName1 Xto generate an alternative name for the symbol. The default is to add Xan underscore to the name. There is also an X.B AlternateName2 Xparameter for a second alternate name, and an X.B AlternateName Xparameter for the X.IR n th Xalternate name. (The value for this parameter should include both a X.I %s Xand a X.I %d, Xin either order.) If these latter parameters are not defined, X.I p2c Xapplies X.B AlternateName1 Xmany times over. X.TP X.B ExportSymbol XSymbols in the interface section for a Pascal module are formatted Xaccording to the value of X.BR ExportSymbol , Xif any. It is not uncommon to use X.I modulename_%s Xfor this symbol; the default is X.I %s, Xi.e., no special treatment for exported symbols. If you also define the X.B Export_Symbol Xparameter, that format is used instead for exported symbols which Xcontain an underscore character. If X.I %S X(with a capital "S") appears in the format string it stands for the Xcurrent module name. X.TP X.B Alias XIf the value of this parameter contains a X.I %s, Xit is a format string applied to the names of external functions or Xvariables. If the value does not contain a X.I %s, Xit becomes the name of the next external symbol which is declared (after Xwhich the parameter is cleared). X.TP X.B Synonym XThis creates a synonym for another Pascal symbol or keyword. The format is X.IP X.B "\ \ \ \ \ Synonym" X.I old-name = new-name X.IP XAll occurrences of X.I old-name Xin the input text are treated as if they were X.I new-name Xby the parser. If X.I new-name Xis a keyword, X.I old-name Xwill be an equivalent keyword. If X.I new-name Xis the name of a predefined function, X.I old-name Xwill behave in the same way as that function, and so on. If X.I new-name Xis omitted, then occurrences of X.I old-name Xare entirely ignored in the input file. Synonyms allow you to skip over Xa keyword in your dialect of Pascal that is not understood by X.I p2c, Xor to simulate a keyword or predefined identifier of your dialect with a Xsimilar one that X.I p2c Xrecognizes. Note that all predefined functions are available at all times; Xif you have a library routine that behaves like, e.g., Turbo Pascal's X.I getmem Xprocedure, you can make your routine a synonym for X.I getmem Xeven if you are not translating in Turbo mode. X.TP X.B NameOf XThis defines the name to use in C for a specific symbol. It must appear Xbefore the symbol is declared in the Pascal code; it is usually placed Xin the local X.I p2crc Xfile for the project. The format is X.IP X.B "\ \ \ \ \ NameOf" X.I pascal-name = C-name X.IP XBy default, Pascal names map directly onto C names with no change X(except for the various kinds of formatting outlined above). If the X.I pascal-name Xis of the form X.I module.name Xor X.I procedure.name Xthen the command applies only to the instance of the Pascal name that is Xglobal to that module, or local to that procedure. Otherwise, it applies Xto all usages of the name. X.TP X.B VarMacro XThis is analogous to X.BR NameOf , Xbut specifically for use with Pascal variables. The righthand side can Xbe most any C expression; all references to the variable are expanded Xinto that C expression. Names used in the C expression are taken Xverbatim. There is also a X.B ConstMacro Xparameter for translating constants as arbitrary expressions. XNote that the variable on the lefthand side must actually be declared Xin the program or in a module that it uses. XThe declaration for the variable will be omitted from the generated code Xunless the Pascal-name appears in the expression: If you ask to Xreplace X.I i Xwith X.I i+1, Xthe variable X.I i Xwill still be declared but its value will be shifted accordingly. XNote that if X.I i Xappears on the lefthand side of an assignment, X.I p2c Xwill use algebra to "solve" for X.I i. X.IP XIn all cases where X.I p2c Xparses C expressions, all C operators are recognized except compound Xassignments like `+='. (Increment and decrement operators are allowed.) XAll variable and function names are assumed to have integer type, even Xif they are names that occur in the actual program. A type-specification Xoperator `::' has been introduced; it has the same precedence as `.' or `->' Xbut the righthand side must be a Pascal type identifier (built-in or defined Xby your program previously to when the macro definition was parsed), Xor an arbitrary Pascal type expression in parentheses. XThe lefthand argument is then Xconsidered to have the specified type. This may be necessary if your Xmacro is used in situations where the exact type of the expression Xmust be known (say, as the argument to a X.IR writeln ). X.TP X.B FieldMacro XHere the lefthand side must have the form X.I record.field, Xwhere X.I record Xis the Pascal type or variable name for a record, and X.I field Xis a field in that record. The righthand side must be a C expression Xgenerally including the name X.I record. XAll instances of that name are replaced by the actual record being "dotted." XFor example, X.IP X\ \ \ \ \ FieldMacro Rect.topLeft = topLeft(Rect) X.IP Xtranslates X.I a[i].topLeft Xinto X.I topLeft(a[i]), Xwhere X.I a Xis an array of X.I Rect. X.TP X.B FuncMacro XThe lefthand side must be any Pascal function or procedure name plus a Xparameter list. The number of parameters must match the number in the Xfunction's uses and declaration. Calls to the function are replaced by the XC expression on the righthand side. For example, X.IP X\ \ \ \ \ FuncMacro PtInRect(p,r) = PtInRect(p,&r) X.IP Xcauses the second argument of X.I PtInRect Xto be passed by reference, even though the declaration says it's not. XIf the function in question is actually defined in the program or module Xbeing translated, the X.B FuncMacro Xwill not affect the definition but it will affect all calls to the function Xelsewhere in the module. X.B FuncMacros Xcan also be applied to predefined or never-defined functions. X.TP X.B IncludeFrom XThis specifies that a given module's header should be included from a Xgiven place. The second argument may be surrounded by "\ " or <\ > as Xnecessary; if the second argument is omitted, no include directive will Xbe generated for the module. X.TP X.B ImportFrom XThis specifies that a given module's Pascal interface text can be found Xin the given file. The named file should be either the source file for Xthe module, or a specially prepared file with the implementation section Xremoved for speed. If no X.B ImportFrom Xentry is found for a module, the path defined by the X.B ImportDir Xlist is searched. Each entry in the path may contain a X.I %s, Xwhich expands to the name of the module. The default path looks for X.I %s.pas Xand X.I %s.text Xin the current directory, then for X.I --HOMEDIR--/%s.imp. X(where --HOMEDIR-- is the X.I p2c Xhome directory.) X.TP X.B StructFunction XThis parameter is a list of functions which follow the X.I p2c Xsemantics for structure-valued functions (functions returning arrays, Xsets, and strings, and structs in primitive C dialects). For these Xfunctions, a pointer to a return-value area is passed to the function Xas a special first parameter. The function stores the result in this Xarea, then returns a copy of the pointer. (The standard C function X.I strcpy Xis an example of this concept. X.I Sprintf Xalso behaves this way in some dialects; it always appears on the X.B StructFunction Xlist regardless of the type of implementation.) The system configuration Xfile includes a list of common structured functions so that X.IR p2c 's Xoptimizer will know how to manipulate them. X.TP X.B StrlapFunction XFunctions on this list are structured functions as above, but with the Xability to work in-place; that is, the same pointer may be passed as both the Xreturn value area and a regular parameter. X.TP X.B Deterministic XFunctions on this list have no side effects or side dependencies. XAn example is the X.I sin Xfunction in the standard math library; two calls with the same parameter Xvalues produce the same result, and have no effects other than returning Xa value. X.I P2c Xcan make use of this knowledge when optimizing code for efficiency or Xreadability. Functions on this list are also assumed to be relatively Xfast, so that it is acceptable to duplicate a call to the function. X.TP X.B LeaveAlone XFunctions on this list are not subjected to the normal built-in translation Xrules that X.I p2c Xwould otherwise use. For example, adding X.I writeln Xto this list would translate X.I writeln Xstatements blindly into calls to a C X.I writeln() Xfunction, rather than being translated into equivalent X.I printf Xcalls. The built-in translation is also suppressed if the function has a X.BR FuncMacro . X.TP X.B BufferedFile X.I P2c Xnormally assumes binary files will use X.I read/write, Xnot X.I get/put/^ Xnotation. XA file buffer variable will only be created for a file if buffer notation Xis used for it. For global file variables this may be detected too late X(a declaration without buffers may already have been written). Such files Xcan be listed in X.B BufferedFile Xto force X.I p2c Xto allocate buffers for them; do this if you get a warning Xmessage that says it is necessary. Set X.BR BufferedFile =1 Xto buffer all files, in which case X.B UnBufferedFile Xallows you to force certain files X.I not Xto have buffers. X.TP X.B CheckFileEOF XNormally only file-open operations are checked for errors. Additional Xerror checking, such as read-past-end-of-file, can be enabled with Xparameters like X.BR CheckFileEOF . XThese checks can make the code very ugly! If I/O checking is enabled Xby the program X.RB ( "$iocheck on$" Xin HP Pascal; X.B {$I+} Xin Turbo; this is always the default state), Xthese checks will generate fatal errors unless enclosed in an HP Pascal X.BR try - recover Xconstruct. If I/O checking is disabled, these will cause the global Xvariable X.I P_ioresult Xto be set zero or nonzero according to the outcome. The default for most Xof these options is to check only when I/O checking is disabled. X.SH ISSUES X.B Integer size. X.I P2c Xnormally generates code to work with either 16 or 32 bit ints. XIf you know your C integers will be 16 or 32 bits, set X.B IntSize Xappropriately. In particular setting X.BR IntSize =32 Xwill generate much cleaner code: X.I p2c Xno longer must carefully cast function arguments between int and long. XThese casts also will be unnecessary if ANSI prototypes are available. XTo disable int/long casting because you know at least one of these Xcases will hold, set X.BR CastLongArgs =0. X(The X.B CastArgs Xparameter similarly controls other types of casts, such as between ints Xand doubles.) XThe X.B Integer16 Xparameter controls whether Pascal integers are interpreted as 16 or 32 Xbits, or translated as native C integers. The default value depends on the X.B Language Xselected. X.PP X.B Signed/unsigned chars. XPascal characters are normally "weakly" interpreted as unsigned; this Xis controlled by X.BR UnsignedChar . XThe default is "either," so that C's native X.B char Xtype may be used even if its signed-ness is unknown. Code that uses Xcharacters outside of the range 0-127 may need a different setting. XAlternatively, you can use the types X.B {SIGNED} char Xand X.B {UNSIGNED} char Xin the few cases where it really matters. These comments are controlled Xby the X.B SignedComment Xand X.B UnsignedComment Xparameters. (The type X.B {UNSIGNED} integer Xis also recognized.) The X.B SignedChar Xparameter tells whether C characters are signed or unsigned (default is X"unknown"). The X.B HasSignedChar Xparameter tells whether the phrase "signed char" is legal in the output. XIf it is not, X.I p2c Xmay have to translate Pascal signed bytes into C shorts. X.PP X.B Special types. X.I P2c Xunderstands the following predefined Pascal type names: X.BR integer , Xsigned integers depending on X.BR Integer16 ; X.BR longint , Xsigned 32-bit integers; X.BR unsigned , Xunsigned 32-bit integers; X.BR sword , Xsigned 16-bit integers; X.BR word , Xunsigned 16-bit integers; X.BR c_int , Xsigned native C integers; X.BR c_uint , Xunsigned native C integers; X.BR sbyte , Xsigned 8-bit integers; X.BR byte , Xunsigned 8-bit integers; X.BR real , Xfloating-point numbers depending on X.BR DoubleReals ; X.BR single , Xsingle-precision floats; X.BR longreal , X.BR double , Xand X.BR extended , Xdouble-precision floats; X.B pointer Xand X.BR anyptr , Xgeneric pointers (assignment-compatible with any pointer type); X.BR string , Xgeneric string of length X.B StringDefault X(normally 255); Xalso, the usual Pascal types X.BR char , X.BR boolean , Xand X.BR text . X(If your Pascal uses different names for these concepts, the X.B Synonym Xoption will come in handy.) X.PP X.B Embedded code. XIt is possible to write a Pascal comment containing C code to Xbe embedded into the output. See the descriptions of X.B EmbedComment Xand its relatives in the system X.I p2crc Xfile. These techniques are helpful if you plan to do repeated translations Xof code that is still being maintained in Pascal. X.PP X.B Comments and blank lines. X.I P2c Xcollects the comments in a procedure into a list. All comments and statements Xare stamped with serial numbers which are used to reattach comments to Xstatements even after code has been added, removed, or rearranged during Xtranslation. "Orphan" comments attached to statements that have been lost Xare attached to nearby statements or emitted at the end of the procedure. XBlank lines are treated as a kind of comment, so X.I p2c Xwill also reproduce your usage of blank lines. If the comment mechanism Xgoes awry, you can disable comments with X.B EatComments Xor disable their being attached to code with X.BR SpitComments . X.PP X.B Indentation. X.I P2c Xhas a number of parameters to govern indentation of code. The default Xvalues produce the GNU Emacs standard indentation style, although X.I p2c Xcan do a better job since it knows more about the code it is indenting. XIndentation works by applying "indentation deltas," which are either Xabsolute numbers (which override the previous indentation), or signed Xrelative numbers (which augment the previous indentation). A delta of X"+0" specifies no change in indentation. All of the indentation Xoptions are described in the standard X.I p2crc Xfile. X.PP X.B Line breaking. X.I P2c Xuses an algorithm similar to the TeX typesetter's paragraph formatter Xfor breaking long statements into multiple lines. A "penalty" is assigned Xto various undesirable aspects of all possible line breaks; the "badness" Xof a set of line breaks is approximately the sum of all the penalties. XChief among these are serious penalties for overrunning the desired maximum Xline length (default 78 columns), Xan infinite penalty for overrunning the absolute Xmaximum line length (default 90), and progressively greater penalties for Xbreaking at operators deeply nested in expressions. Parameters such as X.B OpBreakPenalty Xcontrol the relative weights of various choices. X.B BreakArith Xand its neighbors control whether the operator at a line break should be Xplaced at the end of the previous line or at the beginning of the next. XIf you don't want any oversize lines, define X.BR MaxLineWidth =78. X.PP XUnlike TeX, X.IR p2c 's Xline breaker must actually try all possible sets of break points. To Xavoid excessive computation, the total penalty contributed at each decision Xpoint must sum to a nonnegative value; negative values are clipped up to zero. XThis allows X.I p2c Xto prune away obviously undesirable alternatives in advance. The X.B MaxLineBreakTries Xparameter (default 5000) controls how many alternatives to try before Xgiving up and using the best so far. X.PP X.B PASCAL_MAIN. X.I P2c Xgenerates a call to this function at the front of the main program. XIn the (unmodified) run-time library all this does is save argc and argv Xaway because in both HP and Turbo these are accessed as global variables. XIf you do not wish to use this feature, define X.B ArgCName Xto be X.I argc, X.B ArgVName Xto be X.I argv, Xand X.B MainName X(normally "PASCAL_MAIN") to be blank. This will work if argc and argv Xare never accessed outside of your main program. X.SH BUGS X.I P2c Xwas designed with the idea that clean, readable output in most cases is Xworth more than guaranteed correct output in extreme cases. X.I P2c Xis X.I not Xa compiler! However, ideally the "extreme" cases would include only those Xwhich never arise in real life. Thus if X.I p2c Xactually generates incorrect code I will consider it a bug, but I will not Xapologize for it. :-) Below are the major remaining cases where this is Xknown to occur. X.PP XCertain kinds of conformant array parameters (including multi-dimensional Xconformant arrays) produce code that declares variable-length arrays in C. XOnly a few C compilers, such as the GNU C compiler, support this language Xextension. Otherwise some hand re-coding will be required. X.PP XHP Pascal X.BR try - recover Xstructures are translated into calls to X.I TRY Xand X.I RECOVER Xmacros, which are defined to simulate the construct using X.I setjmp Xand X.I longjmp. XIf this emulation does not work, define the symbol X.B FAKE_TRY Xto cause these macros to become "inert." (In cases where the Xerror is detected by code physically within the body of the X.B try Xstatement, a C X.B goto Xto the X.B recover Xsection is always generated.) Also, local file variables in scopes which Xare destroyed by an X.B escape Xare not closed. X.PP XNon-local GOTO's and X.BR try - recover Xstatements are each implemented, but may Xconflict if both are used at once. Non-local GOTO's are fairly careful Xabout closing files that go out of scope but may fail to do so in the presence Xof recursion. X.PP XArrays containing files are not initialized to NULL as other files are. XIn some cases, such as file variables allocated by NEW, the file is Xinitialized but not automatically closed by DISPOSE. X.PP XLINK variables allowing sub-procedures access to their parents' variables Xare occasionally omitted by mistake, if the access is too indirect for X.I p2c Xto notice. If this happens, you can add an explicit reference to a parent Xvariable in the sub-procedure. A statement of the form "a:=a" will count Xas a reference but then be optimized away by X.I p2c. X.PP XMany aspects of Modula-2 are translated only superficially. For example, Xthe type-compatibility properties of the X.I WORD Xand X.I ARRAY OF WORD Xtypes are only roughly modelled, as are the scope rules concerning modules. X.PP XParts of VAX Pascal are still untreated. In particular, the X.I [UNSAFE] Xattribute and a few others are not fully supported, Xnor are the semantics of the X.I OPEN Xprocedure. X.PP XTurbo and VAX Pascal's X.I double, quadruple, Xand X.I extended Xreal types all translate to the C X.B double Xtype. Turbo's X.I computational Xtype is not supported at all. X.PP XBecause Pascal strings (with length bytes) are translated into C strings X(with null terminators), certain Pascal string tricks will not work in Xthe translated code. For example the assignment X.I s[0]:=chr(x) Xis translated to X.I s[x]=0 Xon the assumption that the string is being shortened. If X.I x Xis actually greater than the current length, but not of a recognizable Xform like X.I ord(s[0])+n, Xthen the generated code will not work. In VAX Pascal this corresponds Xto performing arithmetic on the X.I LENGTH Xfield of a varying-length string. X.PP XTurbo Pascal's automatic clipping of strings is not supported. In XTurbo, if a ten character string is assigned to a X.I string[8] Xvariable, the last two characters are silently removed. The code Xproduced by X.I p2c Xgenerally will overrun the target string instead! The X.B StringTruncLimit Xparameter (80 by default if X.BR Language = Turbo ) Xspecifies a string size which should be considered "short"; assignments Xof potentially-long strings to short string variables will cause a warning Xbut will not automatically truncate. The cure is to use X.I copy Xin the Pascal source to truncate the strings explicitly. X.SH FILES X.ta \w'--INCDIR--/p2c.h 'u Xfile.\fIxxx\fR Pascal source files X.br Xfile.c resulting C source file X.br Xmodule.h resulting C header file X.br Xp2crc local configuration file X.br X\&.p2crc alternate local configuration file X.br X--HOMEDIR--/p2crc system-wide configuration file X.br X--HOMEDIR--/system.imp declarations for predefined functions X.br X--HOMEDIR--/system.m2 analogous declarations for Modula-2 X.br X--HOMEDIR--/*.imp interface text for standard modules X.br X--INCDIR--/p2c.h header file for translated programs X.br X--LIBDIR--/libp2c.a run-time library X.SH AUTHOR XDave Gillespie, daveg@csvax.caltech.edu. X.PP XMany thanks to William Bader, Rick Koshi, Eric Raymond, Magne Haveraaen, XDirk Grunwald, David Barto, Paul Fisher, and others whose suggestions and Xbug reports have helped improve X.I p2c Xin countless ways. END_OF_FILE if test 46517 -ne `wc -c <'src/p2c.man'`; then echo shar: \"'src/p2c.man'\" unpacked with wrong size! fi # end of 'src/p2c.man' fi echo shar: End of archive 18 \(of 32\). cp /dev/null ark18isdone MISSING="" for I in 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 ; do if test ! -f ark${I}isdone ; then MISSING="${MISSING} ${I}" fi done if test "${MISSING}" = "" ; then echo You have unpacked all 32 archives. echo "Now see PACKNOTES and the README" rm -f ark[1-9]isdone ark[1-9][0-9]isdone else echo You still need to unpack the following archives: echo " " ${MISSING} fi ## End of shell archive. exit 0