Club Amiga de Montreal

home *** CD-ROM | disk | FTP | other *** search

/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 379b.lha / p2c_v1.13a / home / p2c.1 < prev next >

Wrap

Text File | 1990-06-03 | 62.2 KB | 1,345 lines

P2C(1) User Commands P2C(1) NNAAMMEE p2c - Pascal to C translator, version 1.13 SSYYNNOOPPSSIISS pp22cc [ options ] [ file [ module ] ] DDEESSCCRRIIPPTTIIOONN _P_2_c is a tool for translating Pascal programs into C. The input consists of a set of source files in any of the fol- lowing Pascal dialects: HP Pascal, Turbo/UCSD Pascal, DEC VAX Pascal, Oregon Software Pascal/2, Macintosh Programmer's Workshop Pascal, Sun/Berkeley Pascal. Modula-2 syntax is also supported. Output is a set of ..cc and ..hh files that comprise an equivalent program in any of several dialects of C. Output code may be kept machine- and dialect- independent, or it may be targeted to a specific machine and compiler. Most reasonable Pascal programs are converted into fully functional C which will compile and run with no further modifications, although _p_2_c sometimes chooses to generate readable code at the expense of absolute general- ity. _P_2_c endeavors to insert notes and warning messages into the output code to point out areas which may require human intervention. Output code is arranged to be readable and efficient, and to make use of C idioms wherever possible. The main goal of the translation is to produce C files which are pleasant and "natural" enough to be acceptable as the new source files for a program. In a pinch, _p_2_c will also serve as an ad hoc Pascal compiler. Code generated by _p_2_c normally does not assume characters are signed or unsigned. Also, it assumes iinntt is the same as either sshhoorrtt or lloonngg but does not depend on which. However, if iinntt is not the same as lloonngg it is best to use a modern C compiler which supports prototypes. Generated code does not require an ANSI-compatible compiler (unless ANSI-style code is requested), but it does use various ANSI-standard library routines. All generated code includes the file _<_p_2_c_/_p_2_c_._h_> which in turn includes _<_s_t_d_i_o_._h_> and various other common resources. Also, many translated programs will need to be linked with the run-time library, typically _-_l_p_2_c_. Given a file name, _p_2_c reads from the specified file and outputs to a file with a ..cc suffix added or substituted. For example, p2c myfile.pas reads from _m_y_f_i_l_e_._p_a_s to produce the file _m_y_f_i_l_e_._c_. The input file may contain a Pascal main program or a single Pascal module (or "unit" in Turbo and UCSD Pascal Formatted 90/03/11 local 1 P2C(1) User Commands P2C(1) nomenclature), or it may just contain a number of procedures and declarations. _P_2_c is designed to work for correct input programs. That is, it will accept partial programs but may occasionally core dump if the input refers to undefined sym- bols. If the input is a module, the translator will also produce a file _m_o_d_u_l_e..hh containing a translation of the module's interface section. The implementation section may be omit- ted in which case only the ..hh file will be interesting. If the program or module has include files, these may cause additional ..cc files to be generated depending on the value of the EExxppaannddIInncclluuddeess option (see below). If no file name is given, _p_2_c reads Pascal from the standard input and writes the resulting C to standard output (though a ..hh file may still be produced). If a file name and module name are given, the file may include several modules (or units). The specified module is translated; any others are skipped. The output files will be named _m_o_d_u_l_e..cc and _m_o_d_u_l_e..hh_. _P_2_c never translates more than one module per run. Before starting, _p_2_c reads the file _P_2_C_:_h_o_m_e_/_p_2_c_r_c for a number of configuration parameters. (The actual path used on your system may vary. The --ii option is a handy way to examine this file.) If the P2CRC environment variable is set, it gives the name of a file to read instead of the sys- tem file; this file can start with IInncclluuddee %%HH//pp22ccrrcc to include the system file. Next, _p_2_c attempts to read the file _p_2_c_r_c in your directory for further configuration. If this file does not exist, _p_2_c looks for _._p_2_c_r_c instead. OOPPTTIIOONNSS --oo _c_f_i_l_e Use _c_f_i_l_e in place of _f_i_l_e..cc or _m_o_d_u_l_e..cc as the primary output file. A single dash (`-o -') says to write the C code to the standard output. --hh _h_f_i_l_e Use _h_f_i_l_e in place of _m_o_d_u_l_e..hh as the output file for interface text. This only has effect if the input is an HP Pascal module or a Turbo Pascal unit. --ss _s_f_i_l_e Read interface text from _s_f_i_l_e before beginning the translation. This file typically contains one or more modules, often with interface sections omitted for speed, which the program or module being translated will use. (Typically the IImmppoorrttFFrroomm and IImmppoorrttDDiirr parameters in _p_2_c_r_c are set up to allow _p_2_c to locate interface text without needing any --ss options.) If Formatted 90/03/11 local 2 P2C(1) User Commands P2C(1) there are several --ss options in the command, the _s_f_i_l_e_s are read from left to right. --pp_n Display progress of translation in the form of a line number/file name display. This is refreshed every _n lines, 25 by default. --cc _r_c_f_i_l_e Read local configuration commands from _r_c_f_i_l_e instead of _p_2_c_r_c or _._p_2_c_r_c_. A dash (`-c -') in place of _r_c_f_i_l_e causes no local configuration file to be used. --vv ("Vanilla.") Do not read from the system configuration file _P_2_C_:_h_o_m_e_/_p_2_c_r_c_. Since some of the parameters in this file are required, your local configuration file must include those parameters instead. This also suppresses the file named by the P2CRC environment variable. --HH _h_o_m_e_d_i_r Use _h_o_m_e_d_i_r instead of _P_2_C_:_h_o_m_e as the _p_2_c home direc- tory. The system _p_2_c_r_c file will be searched for in this directory. --II_p_a_t_t_e_r_n Add _p_a_t_t_e_r_n to the IImmppoorrttDDiirr search list of places to find modules which are imported. The pattern should include a _%_s to represent the module name, and should evaluate to a potential file name for that module's source code. For example, ....//%%ss..ppaass looks for _m_o_d_u_l_e_n_a_m_e..ppaass in the parent of the current directory. --ii This special option (which must be the only argument on the command line if used) simply copies the system con- figuration file _P_2_C_:_h_o_m_e_/_p_2_c_r_c to the standard output in its entirety. (It may be used with --HH, but --ii is most useful precisely when you don't know the location of the home directory.) --qq Quiet mode. Suppresses output of status messages dur- ing translation. --EE_n Abort translation after _n errors. If _n is omitted it defaults to zero, which means unlimited errors are allowed. Use --EE11 to make _p_2_c halt after the first error. --ee Echo the Pascal source into the output file, surrounded by #ifdefs. This is the same as the CCooppyySSoouurrccee parame- ter in the _p_2_c_r_c file. Formatted 90/03/11 local 3 P2C(1) User Commands P2C(1) --aa Produce modern ANSI C. This is a convenient override for the AAnnssiiCC parameter in the _p_2_c_r_c file. --LL _l_a_n_g_u_a_g_e Select input language name, such as VAX or TURBO. This is a convenient override for the LLaanngguuaaggee parameter. --VV Verbose mode. This causes _p_2_c to generate an addi- tional ".log" file with further details of the transla- tion, such as a list of warnings and notes including those which are suppressed in the regular output. --MM00 Disable memory conservation. This prevents _p_2_c from freeing various data structures after translating each function, in case this new conservation feature causes unforseen problems. --RR Regression testing mode. Formats notes and warning messages in a way that makes it easier to run _d_i_f_f(1) on the output of _p_2_c_. _P_2_c also understands a few debugging options which may occa- sionally be useful when tracking down translation problems. The --dd_n option sets the "debug level" to _n_, a small integer which is normally zero. Debugging output is written into the regular output file along with the C code; the higher your _n_, the more "wallpaper" you get. Also, --tt prints debugging information at every Pascal token, --BB_n enables line-breaker debugging, and --CC_n enables comment placement debugging. CCHHOOIICCEE OOFF SSOOUURRCCEE LLAANNGGUUAAGGEE The LLaanngguuaaggee configuration parameter or --LL command-line option tells _p_2_c which Pascal dialect to expect in the input file. Any language features which do not overlap between dialects are supported all of the time. The LLaanngguuaaggee param- eter is consulted when a syntax or usage is detected that has different meanings in two different dialects, and also to determine default values for various other translation parameters as described below. The following language words are supported by _p_2_c_. Names are case-insensitive. HHPP HP Pascal. This is the default language. All features of HP Standard Pascal, the Pascal Workstation version, are supported except as noted in BUGS below. Some features of MODCAL, HP's extended Pascal, are also sup- ported. This is a superset of ISO standard Pascal, including conformant arrays and procedural parameters. Formatted 90/03/11 local 4 P2C(1) User Commands P2C(1) HHPP--UUXX HP Pascal, HP-UX version. Almost identical to the "HP" dialect. TTuurrbboo Turbo Pascal 5.0 for the IBM PC. Few conflicts with HP Pascal, so the LLaanngguuaaggee parameter is not often needed for Turbo. (Most important is that the Turbo and HP dialects use 16 and 32 bit integers, respectively.) UUCCSSDD UCSD Pascal. Similar to Turbo in many ways. MMPPWW Macintosh Programmer's Workshop Pascal 2.0. Should also do a pretty good job for Lightspeed Pascal. Object Pascal features are not supported, nor is the fact that cchhaarr variables are sometimes stored in 16 bits. VVAAXX VAX/VMS Pascal version 3.5. Most but not all language features supported. This has not yet been tested on large programs. OOrreeggoonn Oregon Software Pascal/2. All features implemented. BBeerrkk Berkeley Pascal with Sun extensions. MMoodduullaa Modula-2. Based on Wirth's _P_r_o_g_r_a_m_m_i_n_g _i_n _M_o_d_u_l_a_-_2_, 3rd edition. Proper setting of the LLaanngguuaaggee parameter is _n_o_t optional. Translation will be incomplete in most cases, but should be good enough to work with. Structure of local sub-modules is essentially ignored; like-named identifiers may be confused. Type WORD is translated as an integer, but type ADDRESS is translated as char * or void *; this may cause incon- sistencies in the output code. Modula-2 modules have two parts in separate files. Suppose these are called _f_o_o_._d_e_f (definition part) and _f_o_o_._m_o_d (implementation part) for module _f_o_o_. Then a pattern like %%ss..ddeeff must be included in the IImmppoorrttDDiirr list, and LLiibbrraarryyFFiillee must be changed to refer to _s_y_s_t_e_m_._m_2 instead of _s_y_s_t_e_m_._i_m_p_. To translate the definition part, give the command p2c foo.def to translate the definition part into files _f_o_o_._h and _f_o_o_._c; the latter will usually be empty. The command Formatted 90/03/11 local 5 P2C(1) User Commands P2C(1) p2c -s foo.def foo.mod will translate the implementation part into file _f_o_o_._c_. Even if all language features are supported for a dialect, some predefined functions may be omitted. In these cases, the function call will be translated literally into C with a warning. Some hand modification may be required. CCOONNFFIIGGUURRAATTIIOONN PPAARRAAMMEETTEERRSS _P_2_c is highly configurable. The defaults are suitable for most applications, but customizing these parameters will help you get the best possible translation. Since the out- put of _p_2_c is intended to be used as human-maintainable source code, there are many parameters for describing the coding style and conventions you prefer. Others give hints about your program that help _p_2_c to generate more correct, efficient, or readable code. The _p_2_c_r_c files contain a list of parameters, one per line. The system configuration file, which may be viewed using the --ii option to _p_2_c_, serves as an example of the proper format. Parameter names are case-insensitive. If a parameter name occurs exactly once in the system _p_2_c_r_c_, this indicates that it must have a unique value and the last value given to it by the configuration files is used. Other parameters are written several times in a row; these are lists to which each configuration line adds an entry. Many _p_2_c_r_c options take a numeric value of 0 or 1, roughly corresponding to "no" or "yes." Sometimes a blank value or the value "ddeeff" corresponds to an intermediate "maybe" state. For example, the stylistic option EExxttrraaPPaarreennss switches between copious or minimal parentheses in expres- sions, with the default being a nice compromise intended to be best for readers with an average knowledge of C operator precedences. Configuration options may also be embedded in the source file in the form of Pascal comments: {ShortOpt=0} {AvoidName=fred} {FuncMacro slope(x,y)=atan2(y,x)*RadDeg} disables automatic short-circuiting of aanndd and oorr expres- sions, adds "_f_r_e_d" to the list of names to avoid using in generated C code, and defines a special translation for the Pascal program's _s_l_o_p_e function using the standard C _a_t_a_n_2 function and a constant _R_a_d_D_e_g presumably defined in the program. Whitespace is generally not allowed in embedded parameters. The `=' sign is required for embedded parame- ters, though it is optional in _p_2_c_r_c files. Comments within Formatted 90/03/11 local 6 P2C(1) User Commands P2C(1) embedded parameters are delimited by `##'. Numeric parame- ters may replace `=' with `+' or `-' to increase or decrease the parameter; list-based parameters may use `-' to remove a name from a list rather than adding it. Also, the parameter name by itself in comment braces means to restore the parameter's value that was current before the last change: {VarFiles=0 ## Pass FILE *'s params by value even if VAR} _s_o_m_e _d_e_c_l_a_r_a_t_i_o_n_s {VarFiles ## Back to original FILE * passing} causes the parameter VVaarrFFiilleess to have the value 0 for those few declarations, without affecting the parameter's value elsewhere in the file. If an embedded parameter appears in an include file or in interface text for a module, the effect of the assignment normally carries over to any programs that included that file. If the parameter name is preceded by a `*', then the assignment is automatically undone after the source file that contains it ends: {IncludeFrom strings=<p2c/strings.h>} {*ExportSymbol=pascal_%s} module strings; will record the location of the _s_t_r_i_n_g_s module's include file for the rest of the translation, but the assignment of EExxppoorrttSSyymmbbooll pertains only to the module itself. For the complete list of _p_2_c_r_c parameters, run _p_2_c with the --ii option. Here are some additional comments on selected parameters: IImmppoorrttAAllll Because Turbo Pascal only allows one unit per source file, _p_2_c normally stops reading past the word _i_m_p_l_e_m_e_n_t_a_t_i_o_n in a file being scanned for interface text. But HP Pascal allows several modules per file and so this would not be safe to do. The IImmppoorrttAAllll option lets you override the default behavior for your Pascal dialect. AAnnssiiCC This parameter selects which dialect of C to use. If 1, all conventions of ANSI C such as proto- types, vvooiidd ** pointers, etc. are used. If 0, only strict K&R (first edition) C is used. The default is to use "traditional UNIX C," which includes eennuumm and vvooiidd but not vvooiidd ** or prototypes. Once again there are a number of other parameters which may be used to control the individual features if just setting AAnnssiiCC is not enough. Formatted 90/03/11 local 7 P2C(1) User Commands P2C(1) CC++++ At present _p_2_c does not use much of C++ at all. The default action is to generate code that will compile in either language. UUsseeVVEExxtteerrnn Many non-UNIX linkers prohibit variables from being defined (not declared) by more than one source file. One module must declare, e.g., "int foo;", and all others must declare "extern int foo;". _P_2_c accomplishes this by declaring public variables "vveexxtteerrnn" in header files, and arranging for the macro vveexxtteerrnn to expand to eexxtteerrnn or to nothing when appropriate. If you set UUsseeVVEExxtteerrnn=0 _p_2_c will instead declare variables in a simpler way that works only on UNIX-style linkers. UUsseeAAnnyyppttrrMMaaccrrooss Certain C reserved words have meanings which may vary from one C implementation to another. _P_2_c uses special capitalized names for these words; these names are defined as macros in the file _p_2_c_._h which all translated programs include. You can set UUsseeAAnnyyppttrrMMaaccrrooss=0 to disable the use of these macros. Note that the functions of many of these macros can also be had directly using other parameters; for example, UUsseeCCoonnssttss allows you to specify whether your target language recognizes the word ccoonnsstt in constant declarations. The default is to use the CCoonnsstt macro instead, so that your code will be portable to either kind of implementation. SSiiggnneedd expands to the reserved word ssiiggnneedd if that word is available, otherwise it is given a null definition. Similarly, CCoonnsstt expands to ccoonnsstt if that feature is available. The words VVoollaattiillee and RReeggiisstteerr are also defined in _p_2_c_._h_, although _p_2_c does not use them at present. The word CChhaarr expands to cchhaarr by default, but might need to be redefined to ssiiggnneedd cchhaarr or uunnssiiggnneedd cchhaarr in a particular implementation. This is used for the Pascal character type; lowercase cchhaarr is used when the desired meaning is "byte," not "character." The word SSttaattiicc always expands to ssttaattiicc by default. This is used in situations where a func- tion or variable is declared static to make it local to the source file; lowercase ssttaattiicc is used for static local variables. Thus you can redefine SSttaattiicc to be null if you want to force private names to be public for purposes of debugging. Formatted 90/03/11 local 8 P2C(1) User Commands P2C(1) The word VVooiidd expands to vvooiidd in all cases; it is used when declaring a function with no return value. The word AAnnyyppttrr is a typedef for vvooiidd ** or cchhaarr ** as necessary; it represents a generic pointer. UUsseePPPPMMaaccrrooss The _p_2_c_._h header also declares two macros for function prototyping, PPPP(x) and PPVV(). These mac- ros are used as follows: Void foo PP( (int x, int y, Char *z) ); Char *bar PV( ); If prototypes are available, these macros will expand to Void foo (int x, int y, Char *z); Char *bar (void); but if only old-style declarations are supported, you instead get Void foo (); Char *bar (); By default, _p_2_c uses these macros for all function declarations, but function _d_e_f_i_n_i_t_i_o_n_s are written in old-style C. The UUsseePPPPMMaaccrrooss parameter can be set to 0 to disable all use of PPPP and PPVV, or it can be set to 1 to use the macros even when defin- ing a function. (This is accomplished by preced- ing each old-style definition with a PPPP-style declaration.) If you know your code will always be compiled on systems that support prototyping, it is prettier to set PPrroottoottyyppeess=1 or simply AAnnssiiCC=1 to get true function prototypes. EEaattNNootteess Notes and warning messages containing any of these strings as sub-strings are not omitted. Each type of message includes an identifier like [[114455]]; you can add this identifier to the EEaattNNootteess list to suppress that message. Another useful form is to use a variable name or other identifier to suppress warnings about that variable. The strings are a space-separated list, and thus may not contain embedded spaces. To suppress notes around a section of code, use, e.g., _{_E_a_t_- _N_o_t_e_s_+_[_1_4_5_]_} and _{_E_a_t_N_o_t_e_s_-_[_1_4_5_]_}_. Most notes are generated during parsing, but to suppress those generated during output the string may need to remain in the list far beyond the point where it Formatted 90/03/11 local 9 P2C(1) User Commands P2C(1) appears to be generated. Use the string "1" or "0" to disable or enable all notes, respectively. EExxppaannddIInncclluuddeess The default action is to expand Pascal include files in-line. This may not be desirable if include files are being used to simulate modules. With EExxppaannddIInncclluuddeess=0, _p_2_c attempts to convert include files containing only whole procedures and global declarations into analogous C include files. This may not always work, though; if you get error messages, don't use this option. By combining this option with SSttaattiiccFFuunnccttiioonnss=0, then doing some fairly minor editing on the result, you can convert a pseudo-modular Pascal program into a truly modular collection of C source files. EElliimmDDeeaaddCCooddee Some transformations that _p_2_c does on the program may result in unreachable or "dead" code. By default _p_2_c removes such code, but sometimes it removes more than it should. If you have "if false" segments which you wish to retain in C, you may have to set EElliimmDDeeaaddCCooddee=0. SSkkiippIInnddiicceess Normally Pascal arrays not based at zero are "shifted" down for C, preserving the total size of the array. A Pascal array a[2..10] is translated to a C array a[9] with references like "a[i]" changed to "a[i-2]" everywhere. If SSkkiippIInnddiicceess is set to a value of 2 or higher, this array would instead be translated to a[11] with the first two elements never used. This arrangement may gen- erate incorrect code, though, for tricky source programs. FFoollddCCoonnssttaannttss Pascal non-structured constants generally translate to ##ddeeffiinnee's in C. Set this to 1 to have constants instantiated directly into the code. This may be turned on or off around specific constant declarations. Set this to 0 to force _p_2_c to make absolutely no assumptions about the constant's value in generated code, so that you can change the constant later in the C code without invalidating the translation. The default is to allow _p_2_c to take advantage of its knowledge of a constant's value, such as by generating code that assumes the constant is positive. Formatted 90/03/11 local 10 P2C(1) User Commands P2C(1) VVaarrSSttrriinnggss In HP Pascal, a parameter of the form "var s : string" will match a string variable of any size; a hidden size parameter is passed which may be accessed by the Pascal _s_t_r_m_a_x function. You can prevent _p_2_c from creating a hidden size parameter by setting VVaarrSSttrriinngg=0. (Note that each function uses the value of VVaarrSSttrriinnggss as of the _f_i_r_s_t declaration of the function that is parsed, which is often in the interface section of a module.) PPrroottoottyyppeess Control whether ANSI C function prototypes are used. Default is according to AAnnssiiCC. This also controls whether to include parameter names or just their types in situations where names are optional. The FFuullllPPrroottoottyyppiinngg parameter allows prototypes to be generated for declarations but not for definitions (older versions of Lightspeed C required this). If you use a mixture of proto- types and old-style definitions, types like short and float will be promoted to int and double as required by the ANSI standard, unless PPrroommootteeAArrggss is used to override this. The CCaassttAArrggss parameter controls whether type-casts are used in function arguments; by default they are used only if proto- types are not available. SSttaattiiccLLiinnkkss HP Pascal and Turbo Pascal each include the con- cept of procedure or function pointers, though with somewhat different syntaxes. _P_2_c recognizes both notational styles. Another difference is that HP's procedure pointers can point to nested procedures, while Turbo's can point only to global procedures. In HP Pascal a procedure pointer must be stored as a ssttrruucctt containing both a pure C function pointer and a "static link," a pointer to the parent procedure's locals. (The static link is NULL for global procedures.) This notation can be forced by setting SSttaattiiccLLiinnkkss=1. In Turbo, the default (SSttaattiiccLLiinnkkss=0) is to use plain C function pointers with no static links. A third option (SSttaattiiccLLiinnkkss=2) uses structures with static links, but assumes the links are always NULL when calling through a pointer (if you need compatibility with the HP format but know your procedures are glo- bal). SSmmaallllSSeettCCoonnsstt Pascal sets are translated into one of two for- mats, depending on the size of the set. If all Formatted 90/03/11 local 11 P2C(1) User Commands P2C(1) elements have ordinal values in the range 0..31, the set is translated as a single integer variable using bit operations. (The SSeettBBiittss parameter may be used to change the upper limit of 31.) The SSmmaallllSSeettCCoonnsstt parameter controls whether these small-sets are used, and, if so, how constant sets should be represented in C. For larger sets, an array of lloonngg is used. The _s[0] element contains the number of succeeding array elements which are in use. Set elements in the range 0..31 are stored in the _s[1] array element, and so on. Sets are normalized so that _s[_s[0]] is nonzero for any nonempty set. The standard run-time library includes all the necessary procedures for operat- ing on sets. RReettuurrnnVVaalluueeNNaammee This is one of many "naming conventions" parame- ters. Most of these take the form of a _p_r_i_n_t_f- like string containing a _%_s where the relevant information should go. In the case of RReettuurrnn---- VVaalluueeNNaammee, the _%_s refers to a function name and the resulting string gives the name of the vari- able to use to hold the function's return value. Such a variable will be made if a function con- tains assignments to its return value buried within the body, so that _r_e_t_u_r_n statements cannot conveniently be used. Some parameters (RReettuurrnn---- VVaalluueeNNaammee included) do not require the _%_s to be present in the format string; for example, the standard _p_2_c_r_c file stores every function's return value in a variable called _R_e_s_u_l_t_. AAlltteerrnnaatteeNNaammee _P_2_c normally translates Pascal names into C names verbatim, but occasionally this is not possible. A Pascal name may be a C reserved word or tradi- tional C name like _p_u_t_c_, or there may be several like-named things that are hidden from each other by Pascal's scoping rules but must be global in C. In these situations _p_2_c uses the parameter AAlltteerr---- nnaatteeNNaammee11 to generate an alternative name for the symbol. The default is to add an underscore to the name. There is also an AAlltteerrnnaatteeNNaammee22 parame- ter for a second alternate name, and an AAlltteerrnnaa---- tteeNNaammee parameter for the _nth alternate name. (The value for this parameter should include both a _%_s and a _%_d_, in either order.) If these latter parameters are not defined, _p_2_c applies AAlltteerrnnaa---- tteeNNaammee11 many times over. Formatted 90/03/11 local 12 P2C(1) User Commands P2C(1) EExxppoorrttSSyymmbbooll Symbols in the interface section for a Pascal module are formatted according to the value of EExxppoorrttSSyymmbbooll, if any. It is not uncommon to use _m_o_d_u_l_e_n_a_m_e___%_s for this symbol; the default is _%_s_, i.e., no special treatment for exported symbols. If you also define the EExxppoorrtt__SSyymmbbooll parameter, that format is used instead for exported symbols which contain an underscore character. If _%_S (with a capital "S") appears in the format string it stands for the current module name. AAlliiaass If the value of this parameter contains a _%_s_, it is a format string applied to the names of exter- nal functions or variables. If the value does not contain a _%_s_, it becomes the name of the next external symbol which is declared (after which the parameter is cleared). SSyynnoonnyymm This creates a synonym for another Pascal symbol or keyword. The format is SSyynnoonnyymm _o_l_d_-_n_a_m_e _= _n_e_w_-_n_a_m_e All occurrences of _o_l_d_-_n_a_m_e in the input text are treated as if they were _n_e_w_-_n_a_m_e by the parser. If _n_e_w_-_n_a_m_e is a keyword, _o_l_d_-_n_a_m_e will be an equivalent keyword. If _n_e_w_-_n_a_m_e is the name of a predefined function, _o_l_d_-_n_a_m_e will behave in the same way as that function, and so on. If _n_e_w_-_n_a_m_e is omitted, then occurrences of _o_l_d_-_n_a_m_e are entirely ignored in the input file. Synonyms allow you to skip over a keyword in your dialect of Pascal that is not understood by _p_2_c_, or to simulate a keyword or predefined identifier of your dialect with a similar one that _p_2_c recog- nizes. Note that all predefined functions are available at all times; if you have a library rou- tine that behaves like, e.g., Turbo Pascal's _g_e_t_- _m_e_m procedure, you can make your routine a synonym for _g_e_t_m_e_m even if you are not translating in Turbo mode. NNaammeeOOff This defines the name to use in C for a specific symbol. It must appear before the symbol is declared in the Pascal code; it is usually placed in the local _p_2_c_r_c file for the project. The for- mat is NNaammeeOOff _p_a_s_c_a_l_-_n_a_m_e _= _C_-_n_a_m_e Formatted 90/03/11 local 13 P2C(1) User Commands P2C(1) By default, Pascal names map directly onto C names with no change (except for the various kinds of formatting outlined above). If the _p_a_s_c_a_l_-_n_a_m_e is of the form _m_o_d_u_l_e_._n_a_m_e or _p_r_o_c_e_d_u_r_e_._n_a_m_e then the command applies only to the instance of the Pascal name that is global to that module, or local to that procedure. Otherwise, it applies to all usages of the name. VVaarrMMaaccrroo This is analogous to NNaammeeOOff, but specifically for use with Pascal variables. The righthand side can be most any C expression; all references to the variable are expanded into that C expression. Names used in the C expression are taken verbatim. There is also a CCoonnssttMMaaccrroo parameter for translat- ing constants as arbitrary expressions. Note that the variable on the lefthand side must actually be declared in the program or in a module that it uses. The declaration for the variable will be omitted from the generated code unless the Pascal-name appears in the expression: If you ask to replace _i with _i_+_1_, the variable _i will still be declared but its value will be shifted accord- ingly. Note that if _i appears on the lefthand side of an assignment, _p_2_c will use algebra to "solve" for _i_. In all cases where _p_2_c parses C expressions, all C operators are recognized except compound assign- ments like `+='. (Increment and decrement opera- tors are allowed.) All variable and function names are assumed to have integer type, even if they are names that occur in the actual program. A type- specification operator `::' has been introduced; it has the same precedence as `.' or `->' but the righthand side must be a Pascal type identifier (built-in or defined by your program previously to when the macro definition was parsed), or an arbi- trary Pascal type expression in parentheses. The lefthand argument is then considered to have the specified type. This may be necessary if your macro is used in situations where the exact type of the expression must be known (say, as the argu- ment to a _w_r_i_t_e_l_n). FFiieellddMMaaccrroo Here the lefthand side must have the form _r_e_c_o_r_d_._f_i_e_l_d_, where _r_e_c_o_r_d is the Pascal type or variable name for a record, and _f_i_e_l_d is a field in that record. The righthand side must be a C expression generally including the name _r_e_c_o_r_d_. All instances of that name are replaced by the Formatted 90/03/11 local 14 P2C(1) User Commands P2C(1) actual record being "dotted." For example, FieldMacro Rect.topLeft = topLeft(Rect) translates _a_[_i_]_._t_o_p_L_e_f_t into _t_o_p_L_e_f_t_(_a_[_i_]_)_, where _a is an array of _R_e_c_t_. FFuunnccMMaaccrroo The lefthand side must be any Pascal function or procedure name plus a parameter list. The number of parameters must match the number in the function's uses and declaration. Calls to the function are replaced by the C expression on the righthand side. For example, FuncMacro PtInRect(p,r) = PtInRect(p,&r) causes the second argument of _P_t_I_n_R_e_c_t to be passed by reference, even though the declaration says it's not. If the function in question is actually defined in the program or module being translated, the FFuunnccMMaaccrroo will not affect the definition but it will affect all calls to the function elsewhere in the module. FFuunnccMMaaccrrooss can also be applied to predefined or never-defined functions. IInncclluuddeeFFrroomm This specifies that a given module's header should be included from a given place. The second argu- ment may be surrounded by " " or < > as necessary; if the second argument is omitted, no include directive will be generated for the module. IImmppoorrttFFrroomm This specifies that a given module's Pascal inter- face text can be found in the given file. The named file should be either the source file for the module, or a specially prepared file with the implementation section removed for speed. If no IImmppoorrttFFrroomm entry is found for a module, the path defined by the IImmppoorrttDDiirr list is searched. Each entry in the path may contain a _%_s_, which expands to the name of the module. The default path looks for _%_s_._p_a_s and _%_s_._t_e_x_t in the current directory, then for _P_2_C_:_h_o_m_e_/_%_s_._i_m_p_. (where P2C:home is the _p_2_c home directory.) SSttrruuccttFFuunnccttiioonn This parameter is a list of functions which follow the _p_2_c semantics for structure-valued functions (functions returning arrays, sets, and strings, and structs in primitive C dialects). For these Formatted 90/03/11 local 15 P2C(1) User Commands P2C(1) functions, a pointer to a return-value area is passed to the function as a special first parame- ter. The function stores the result in this area, then returns a copy of the pointer. (The standard C function _s_t_r_c_p_y is an example of this concept. _S_p_r_i_n_t_f also behaves this way in some dialects; it always appears on the SSttrruuccttFFuunnccttiioonn list regard- less of the type of implementation.) The system configuration file includes a list of common structured functions so that _p_2_c's optimizer will know how to manipulate them. SSttrrllaappFFuunnccttiioonn Functions on this list are structured functions as above, but with the ability to work in-place; that is, the same pointer may be passed as both the return value area and a regular parameter. DDeetteerrmmiinniissttiicc Functions on this list have no side effects or side dependencies. An example is the _s_i_n function in the standard math library; two calls with the same parameter values produce the same result, and have no effects other than returning a value. _P_2_c can make use of this knowledge when optimizing code for efficiency or readability. Functions on this list are also assumed to be relatively fast, so that it is acceptable to duplicate a call to the function. LLeeaavveeAAlloonnee Functions on this list are not subjected to the normal built-in translation rules that _p_2_c would otherwise use. For example, adding _w_r_i_t_e_l_n to this list would translate _w_r_i_t_e_l_n statements blindly into calls to a C _w_r_i_t_e_l_n_(_) function, rather than being translated into equivalent _p_r_i_n_t_f calls. The built-in translation is also suppressed if the function has a FFuunnccMMaaccrroo. BBuuffffeerreeddFFiillee _P_2_c normally assumes binary files will use _r_e_a_d_/_w_r_i_t_e_, not _g_e_t_/_p_u_t_/_^ notation. A file buffer variable will only be created for a file if buffer notation is used for it. For global file vari- ables this may be detected too late (a declaration without buffers may already have been written). Such files can be listed in BBuuffffeerreeddFFiillee to force _p_2_c to allocate buffers for them; do this if you get a warning message that says it is necessary. Set BBuuffffeerreeddFFiillee=1 to buffer all files, in which case UUnnBBuuffffeerreeddFFiillee allows you to force certain Formatted 90/03/11 local 16 P2C(1) User Commands P2C(1) files _n_o_t to have buffers. CChheecckkFFiilleeEEOOFF Normally only file-open operations are checked for errors. Additional error checking, such as read- past-end-of-file, can be enabled with parameters like CChheecckkFFiilleeEEOOFF. These checks can make the code very ugly! If I/O checking is enabled by the pro- gram ($$iioocchheecckk oonn$$ in HP Pascal; {{$$II++}} in Turbo; this is always the default state), these checks will generate fatal errors unless enclosed in an HP Pascal ttrryy-rreeccoovveerr construct. If I/O checking is disabled, these will cause the global variable _P___i_o_r_e_s_u_l_t to be set zero or nonzero according to the outcome. The default for most of these options is to check only when I/O checking is dis- abled. IISSSSUUEESS IInntteeggeerr ssiizzee.. _P_2_c normally generates code to work with either 16 or 32 bit ints. If you know your C integers will be 16 or 32 bits, set IInnttSSiizzee appropriately. In particular setting IInnttSSiizzee=32 will generate much cleaner code: _p_2_c no longer must carefully cast function arguments between int and long. These casts also will be unnecessary if ANSI pro- totypes are available. To disable int/long casting because you know at least one of these cases will hold, set CCaasstt---- LLoonnggAArrggss=0. (The CCaassttAArrggss parameter similarly controls other types of casts, such as between ints and doubles.) The IInntteeggeerr1166 parameter controls whether Pascal integers are interpreted as 16 or 32 bits, or translated as native C integers. The default value depends on the LLaanngguuaaggee selected. SSiiggnneedd//uunnssiiggnneedd cchhaarrss.. Pascal characters are normally "weakly" interpreted as unsigned; this is controlled by UUnnssiiggnneeddCChhaarr. The default is "either," so that C's native cchhaarr type may be used even if its signed-ness is unknown. Code that uses characters outside of the range 0-127 may need a different setting. Alternatively, you can use the types {{SSIIGGNNEEDD}} cchhaarr and {{UUNNSSIIGGNNEEDD}} cchhaarr in the few cases where it really matters. These comments are controlled by the SSiiggnneeddCCoommmmeenntt and UUnnssiiggnneeddCCoommmmeenntt parameters. (The type {{UUNNSSIIGGNNEEDD}} iinntteeggeerr is also recognized.) The SSiiggnneeddCChhaarr parameter tells whether C characters are signed or unsigned (default is "unknown"). The HHaassSSiiggnneeddCChhaarr parameter tells whether the phrase "signed char" is legal in the output. If it is not, _p_2_c may have to translate Pascal signed bytes into C shorts. SSppeecciiaall ttyyppeess.. _P_2_c understands the following predefined Pas- cal type names: iinntteeggeerr, signed integers depending on Formatted 90/03/11 local 17 P2C(1) User Commands P2C(1) IInntteeggeerr1166; lloonnggiinntt, signed 32-bit integers; uunnssiiggnneedd, unsigned 32-bit integers; sswwoorrdd, signed 16-bit integers; wwoorrdd, unsigned 16-bit integers; cc__iinntt, signed native C integers; cc__uuiinntt, unsigned native C integers; ssbbyyttee, signed 8-bit integers; bbyyttee, unsigned 8-bit integers; rreeaall, floating-point numbers depending on DDoouubblleeRReeaallss; ssiinnggllee, single-precision floats; lloonnggrreeaall, ddoouubbllee, and eexxtteennddeedd, double-precision floats; ppooiinntteerr and aannyyppttrr, generic pointers (assignment-compatible with any pointer type); ssttrriinngg, generic string of length SSttrriinnggDDeeffaauulltt (normally 255); also, the usual Pascal types cchhaarr, bboooolleeaann, and tteexxtt. (If your Pascal uses different names for these concepts, the SSyynnoonnyymm option will come in handy.) EEmmbbeeddddeedd ccooddee.. It is possible to write a Pascal comment con- taining C code to be embedded into the output. See the descriptions of EEmmbbeeddCCoommmmeenntt and its relatives in the system _p_2_c_r_c file. These techniques are helpful if you plan to do repeated translations of code that is still being maintained in Pascal. CCoommmmeennttss aanndd bbllaannkk lliinneess.. _P_2_c collects the comments in a procedure into a list. All comments and statements are stamped with serial numbers which are used to reattach com- ments to statements even after code has been added, removed, or rearranged during translation. "Orphan" comments attached to statements that have been lost are attached to nearby statements or emitted at the end of the procedure. Blank lines are treated as a kind of comment, so _p_2_c will also reproduce your usage of blank lines. If the comment mechanism goes awry, you can disable comments with EEaattCCoomm---- mmeennttss or disable their being attached to code with SSppiittCCoomm---- mmeennttss. IInnddeennttaattiioonn.. _P_2_c has a number of parameters to govern inden- tation of code. The default values produce the GNU Emacs standard indentation style, although _p_2_c can do a better job since it knows more about the code it is indenting. Inden- tation works by applying "indentation deltas," which are either absolute numbers (which override the previous inden- tation), or signed relative numbers (which augment the pre- vious indentation). A delta of "+0" specifies no change in indentation. All of the indentation options are described in the standard _p_2_c_r_c file. LLiinnee bbrreeaakkiinngg.. _P_2_c uses an algorithm similar to the TeX typesetter's paragraph formatter for breaking long state- ments into multiple lines. A "penalty" is assigned to vari- ous undesirable aspects of all possible line breaks; the "badness" of a set of line breaks is approximately the sum of all the penalties. Chief among these are serious penal- ties for overrunning the desired maximum line length Formatted 90/03/11 local 18 P2C(1) User Commands P2C(1) (default 78 columns), an infinite penalty for overrunning the absolute maximum line length (default 90), and progres- sively greater penalties for breaking at operators deeply nested in expressions. Parameters such as OOppBBrreeaakkPPeennaallttyy control the relative weights of various choices. BBrreeaakkAArriitthh and its neighbors control whether the operator at a line break should be placed at the end of the previous line or at the beginning of the next. If you don't want any oversize lines, define MMaaxxLLiinneeWWiiddtthh=78. Unlike TeX, _p_2_c's line breaker must actually try all possi- ble sets of break points. To avoid excessive computation, the total penalty contributed at each decision point must sum to a nonnegative value; negative values are clipped up to zero. This allows _p_2_c to prune away obviously undesir- able alternatives in advance. The MMaaxxLLiinneeBBrreeaakkTTrriieess parame- ter (default 5000) controls how many alternatives to try before giving up and using the best so far. PPAASSCCAALL__MMAAIINN.. _P_2_c generates a call to this function at the front of the main program. In the (unmodified) run-time library all this does is save argc and argv away because in both HP and Turbo these are accessed as global variables. If you do not wish to use this feature, define AArrggCCNNaammee to be _a_r_g_c_, AArrggVVNNaammee to be _a_r_g_v_, and MMaaiinnNNaammee (normally "PASCAL_MAIN") to be blank. This will work if argc and argv are never accessed outside of your main program. BBUUGGSS _P_2_c was designed with the idea that clean, readable output in most cases is worth more than guaranteed correct output in extreme cases. _P_2_c is _n_o_t a compiler! However, ideally the "extreme" cases would include only those which never arise in real life. Thus if _p_2_c actually generates incorrect code I will consider it a bug, but I will not apo- logize for it. :-) Below are the major remaining cases where this is known to occur. Certain kinds of conformant array parameters (including multi-dimensional conformant arrays) produce code that declares variable-length arrays in C. Only a few C com- pilers, such as the GNU C compiler, support this language extension. Otherwise some hand re-coding will be required. HP Pascal ttrryy-rreeccoovveerr structures are translated into calls to _T_R_Y and _R_E_C_O_V_E_R macros, which are defined to simulate the construct using _s_e_t_j_m_p and _l_o_n_g_j_m_p_. If this emulation does not work, define the symbol FFAAKKEE__TTRRYY to cause these macros to become "inert." (In cases where the error is detected by code physically within the body of the ttrryy statement, a C ggoottoo to the rreeccoovveerr section is always generated.) Also, local file variables in scopes which are destroyed by an Formatted 90/03/11 local 19 P2C(1) User Commands P2C(1) eessccaappee are not closed. Non-local GOTO's and ttrryy-rreeccoovveerr statements are each imple- mented, but may conflict if both are used at once. Non- local GOTO's are fairly careful about closing files that go out of scope but may fail to do so in the presence of recur- sion. Arrays containing files are not initialized to NULL as other files are. In some cases, such as file variables allocated by NEW, the file is initialized but not automatically closed by DISPOSE. LINK variables allowing sub-procedures access to their parents' variables are occasionally omitted by mistake, if the access is too indirect for _p_2_c to notice. If this hap- pens, you can add an explicit reference to a parent variable in the sub-procedure. A statement of the form "a:=a" will count as a reference but then be optimized away by _p_2_c_. Many aspects of Modula-2 are translated only superficially. For example, the type-compatibility properties of the _W_O_R_D and _A_R_R_A_Y _O_F _W_O_R_D types are only roughly modelled, as are the scope rules concerning modules. Parts of VAX Pascal are still untreated. In particular, the _[_U_N_S_A_F_E_] attribute and a few others are not fully supported, nor are the semantics of the _O_P_E_N procedure. Turbo and VAX Pascal's _d_o_u_b_l_e_, _q_u_a_d_r_u_p_l_e_, and _e_x_t_e_n_d_e_d real types all translate to the C ddoouubbllee type. Turbo's _c_o_m_p_u_t_a_- _t_i_o_n_a_l type is not supported at all. Because Pascal strings (with length bytes) are translated into C strings (with null terminators), certain Pascal string tricks will not work in the translated code. For example the assignment _s_[_0_]_:_=_c_h_r_(_x_) is translated to _s_[_x_]_=_0 on the assumption that the string is being shortened. If _x is actually greater than the current length, but not of a recognizable form like _o_r_d_(_s_[_0_]_)_+_n_, then the generated code will not work. In VAX Pascal this corresponds to performing arithmetic on the _L_E_N_G_T_H field of a varying-length string. Turbo Pascal's automatic clipping of strings is not sup- ported. In Turbo, if a ten character string is assigned to a _s_t_r_i_n_g_[_8_] variable, the last two characters are silently removed. The code produced by _p_2_c generally will overrun the target string instead! The SSttrriinnggTTrruunnccLLiimmiitt parameter (80 by default if LLaanngguuaaggee=TTuurrbboo) specifies a string size which should be considered "short"; assignments of potentially-long strings to short string variables will cause a warning but will not automatically truncate. The Formatted 90/03/11 local 20 P2C(1) User Commands P2C(1) cure is to use _c_o_p_y in the Pascal source to truncate the strings explicitly. FFIILLEESS file._x_x_x Pascal source files file.c resulting C source file module.h resulting C header file p2crc local configuration file .p2crc alternate local configuration file P2C:home/p2crc system-wide configuration file P2C:home/system.impdeclarations for predefined functions P2C:home/system.m2 analogous declarations for Modula-2 P2C:home/*.imp interface text for standard modules P2C:home/p2c/p2c.h header file for translated programs P2C:home/libp2c.a run-time library AAUUTTHHOORR Dave Gillespie, daveg@csvax.caltech.edu. Many thanks to William Bader, Rick Koshi, Eric Raymond, Magne Haveraaen, Dirk Grunwald, David Barto, Paul Fisher, and others whose suggestions and bug reports have helped improve _p_2_c in countless ways. Formatted 90/03/11 local 21