Difference between revisions of "PTop"

From Lazarus wiki
(start of a page)
 
m
Line 1: Line 1:
 
PTOP - Free Pascal source formatter
 
PTOP - Free Pascal source formatter
 
What follows below is the man page of ptop and the description of the configuration file.
 
If you have installed the man pages then you can view them with the man command.
 
  
 
ptop(1)              ptop source beautifier              ptop(1)
 
ptop(1)              ptop source beautifier              ptop(1)
Line 10: Line 7:
 
Origin probably Pascal-TO-Pascal.
 
Origin probably Pascal-TO-Pascal.
 
=== SYNOPSIS ===
 
=== SYNOPSIS ===
ptop[-v]  [-i  indent]  [-b  bufsize ][-c optsfile] infile
+
ptop [-v]  [-i  indent]  [-b  bufsize ] [-c optsfile] infile
 
outfile
 
outfile
 
==== Description ====
 
==== Description ====
Line 19: Line 16:
 
ptop  belongs  to  the  FPC utils package, which currently
 
ptop  belongs  to  the  FPC utils package, which currently
 
also contains ppdep , h2pas , ppudump and ppumove
 
also contains ppdep , h2pas , ppudump and ppumove
Usage
+
===== Usage =====
 
ptop basically reformats "infile" and outputs  the  result
 
ptop basically reformats "infile" and outputs  the  result
to  "outfile".  ituses a configuration file explained fur-
+
to  "outfile".  It uses a configuration file explained further below,
ther below, and can generate a  default  configurationfile
+
and can generate a  default  configurationfile
 
for you to edit. (not needed if you use the defaults)
 
for you to edit. (not needed if you use the defaults)
Options
+
===== Options =====
 
-h    Writes a short description of these switches.
 
-h    Writes a short description of these switches.
-c    read  options from configuration file. A configura-
+
-c    read  options from configuration file. A configuration
tion file is not needed, ptop will revert to inter-
+
file is not needed, ptop will revert to internal defaults then.
nal defaults then. See also -g
+
See also -g
 
-i ident
 
-i ident
 
Sets  the  number  of  indent spaces used for BEGIN
 
Sets  the  number  of  indent spaces used for BEGIN
Line 41: Line 38:
 
the file ptop.cfg
 
the file ptop.cfg
 
Try  to  play  with ptop and its configfile until you find
 
Try  to  play  with ptop and its configfile until you find
the effect you desire. The configurability and  possibili-
+
the effect you desire. The configurability and  possibilities
ties  of ptop are quite large compared to shareware source
+
of ptop are quite large compared to shareware source
 
beautifier found on e.g. SIMTEL.
 
beautifier found on e.g. SIMTEL.
 
==== Acknowledgements ====
 
==== Acknowledgements ====
 
The writer of the program, Michael van Canneyt,  who  also
 
The writer of the program, Michael van Canneyt,  who  also
 
helped out explaining the format of ptop.cfg.
 
helped out explaining the format of ptop.cfg.
Questions/corrections     can     be     mailed     to
+
Questions/corrections can be mailed to
fpc-devel@vekoll.saturnus.vein.hu
+
(removed)
 +
 
 
Also thanks to the rest of the FPC development team.
 
Also thanks to the rest of the FPC development team.
The program is a modernized (OOP, Streams,  Delphi  exten-
+
The program is a modernized (OOP, Streams,  Delphi  extensions)
sions) version based on a program by Peter Grogono, who in
+
version based on a program by Peter Grogono, who in
 
turn based his program on a Pascal pretty-printer  written
 
turn based his program on a Pascal pretty-printer  written
 
by Ledgard, Hueras, and Singer.  See SIGPLAN Notices, Vol.
 
by Ledgard, Hueras, and Singer.  See SIGPLAN Notices, Vol.
 
12, No. 7, July 1977, pages  101-105,  and  PP.DOC/HLP.
 
12, No. 7, July 1977, pages  101-105,  and  PP.DOC/HLP.
 
This version of PP developed under Pascal/Z V4.0 or later.
 
This version of PP developed under Pascal/Z V4.0 or later.
 +
 
Very minor modifications for Turbo Pascal made by  Willett
 
Very minor modifications for Turbo Pascal made by  Willett
Kempton  March 1984 and Oct 84. Runs under 8-bit Turbo or
+
Kempton  March 1984 and Oct 84.
16-bit Turbo.  Toad Hall tweak, rewrite for TP 5,  28  Nov
+
 
89
+
Runs under 8-bit Turbo or 16-bit Turbo.   
 +
 
 +
Toad Hall tweak, rewrite for TP 5,  28  Nov 89
 +
 
 
=== SEE ALSO ===
 
=== SEE ALSO ===
 
ptop config file
 
ptop config file
Line 89: Line 91:
 
keywords are known)
 
keywords are known)
  
The basic building block of the  configuration  file  con-
+
The basic building block of the  configuration  file  consists
sists  out of one or two lines, describing how ptop should
+
out of one or two lines, describing how ptop should
 
react on a certain keyword.  First a line  without  square
 
react on a certain keyword.  First a line  without  square
 
brackets with the following format:
 
brackets with the following format:
  
keyword=option1,option2,option3,...
+
  keyword=option1,option2,option3,...
  
 
If  one of the options is "dindonkey" (see further below),
 
If  one of the options is "dindonkey" (see further below),
 
a second line (with square brackets) is needed like this:
 
a second line (with square brackets) is needed like this:
  
[keyword]=otherkeyword1,otherkeyword2,otherkeyword3,...
+
  [keyword]=otherkeyword1,otherkeyword2,otherkeyword3,...
  
As you can see the block contains  two  types  of  identi-
+
As you can see the block contains  two  types  of  identifiers
fiers,  keywords(keyword  and  otherkeyword1..3  in  above
+
,  keywords(keyword  and  otherkeyword1..3  in  above
 
example) and options, (option1..3 above).
 
example) and options, (option1..3 above).
  
Keywords are the built-in valid  Pascal  structure-identi-
+
Keywords are the built-in valid  Pascal  structure-identifiers
fiers  like  BEGIN, END, CASE, IF, THEN, ELSE, IMPLEMENTA-
+
like  BEGIN, END, CASE, IF, THEN, ELSE, IMPLEMENTATION.
TION. The default configuration file lists most of  these.
+
The default configuration file lists most of  these.
 
Besides the real Pascal keywords, some other codewords are
 
Besides the real Pascal keywords, some other codewords are
 
used for operators  and  comment  expressions.  These  are
 
used for operators  and  comment  expressions.  These  are
Line 185: Line 187:
 
the extra options of the square-bracket line is found.
 
the extra options of the square-bracket line is found.
 
Example
 
Example
The line
+
The lines
else=crbefore,dindonkey,inbytab,upper
+
 
[else]=if,then,else
+
  else=crbefore,dindonkey,inbytab,upper
Means:
+
  [else]=if,then,else
 +
 
 +
Mean:
 +
 
 
The  keyword this is about is else , it's on the LEFT side
 
The  keyword this is about is else , it's on the LEFT side
 
of both equal signs.
 
of both equal signs.
Line 203: Line 208:
 
are  quite  large  compared to shareware source beautifier
 
are  quite  large  compared to shareware source beautifier
 
found on e.g. SIMTEL.
 
found on e.g. SIMTEL.
Acknowledgements
+
==== Acknowledgements ====
 
The writer of the program, Michael van Canneyt,  who  also
 
The writer of the program, Michael van Canneyt,  who  also
 
helped out explaining the format of ptop.cfg.
 
helped out explaining the format of ptop.cfg.
Questions/corrections     can     be     mailed     to
+
Questions/corrections can be mailed to (removed)
fpc-devel@vekoll.saturnus.vein.hu
 
 
Also thanks to the rest of the FPC development team.
 
Also thanks to the rest of the FPC development team.
 
=== SEE ALSO ===
 
=== SEE ALSO ===
Line 219: Line 223:
 
original page:
 
original page:
 
http://www.us.freepascal.org/tools/ptop.html
 
http://www.us.freepascal.org/tools/ptop.html
 +
 +
What follows below is the man page of ptop and the description of the configuration file.
 +
If you have installed the man pages then you can view them with the man command.

Revision as of 06:52, 13 March 2005

PTOP - Free Pascal source formatter

ptop(1) ptop source beautifier ptop(1)

NAME

ptop - The FPC Pascal configurable source beautifier. Origin probably Pascal-TO-Pascal.

SYNOPSIS

ptop [-v] [-i indent] [-b bufsize ] [-c optsfile] infile outfile

Description

ptop is a more or less configurable source beautifier for pascal sources, and specially the ones supported by FPC (which are more or less Turbo Pascal or Delphi 2.0 compat- ible). ptop belongs to the FPC utils package, which currently also contains ppdep , h2pas , ppudump and ppumove

Usage

ptop basically reformats "infile" and outputs the result to "outfile". It uses a configuration file explained further below, and can generate a default configurationfile for you to edit. (not needed if you use the defaults)

Options

-h Writes a short description of these switches. -c read options from configuration file. A configuration file is not needed, ptop will revert to internal defaults then. See also -g -i ident Sets the number of indent spaces used for BEGIN END; and other blocks. -b bufsize Sets the buffersize to bufsize. Default 255, 0 is considered non-valid and ignored. -v be verbose. Currently only outputs the number of lines read/written and some error messages. -g ptop.cfg Writes a default configuration file to be edited to the file ptop.cfg Try to play with ptop and its configfile until you find the effect you desire. The configurability and possibilities of ptop are quite large compared to shareware source beautifier found on e.g. SIMTEL.

Acknowledgements

The writer of the program, Michael van Canneyt, who also helped out explaining the format of ptop.cfg. Questions/corrections can be mailed to (removed)

Also thanks to the rest of the FPC development team. The program is a modernized (OOP, Streams, Delphi extensions) version based on a program by Peter Grogono, who in turn based his program on a Pascal pretty-printer written by Ledgard, Hueras, and Singer. See SIGPLAN Notices, Vol. 12, No. 7, July 1977, pages 101-105, and PP.DOC/HLP. This version of PP developed under Pascal/Z V4.0 or later.

Very minor modifications for Turbo Pascal made by Willett Kempton March 1984 and Oct 84.

Runs under 8-bit Turbo or 16-bit Turbo.

Toad Hall tweak, rewrite for TP 5, 28 Nov 89

SEE ALSO

ptop config file ptop.cfg(5) Compiler ppc386(1) Other FPC utils


ptop.cfg(5) ptop source beautifier config file ptop.cfg(5)

ptop.cfg

The ptop source-beautifier configuration file. ptop is the source beautifier of the FreePascal project. Origin probably Pascal-TO-Pascal.cfg

DESCRIPTION

This is the main configuration file of the ptop FPC source beautifier

The configuration file for ptop(1) isn't necessarily called ptop.cfg, and is also not auto-loaded, so the name doesn't matter much. This man-page describes the structure of such a configuration file for ptop(1)

Structure

The structure of a ptop configuration file is a simple buildingblock repeated several (20-30) times, for each pascal keyword known to the ptop program. (see the default configuration file or ptopu.pp source to find out which keywords are known)

The basic building block of the configuration file consists out of one or two lines, describing how ptop should react on a certain keyword. First a line without square brackets with the following format:

 keyword=option1,option2,option3,...

If one of the options is "dindonkey" (see further below), a second line (with square brackets) is needed like this:

 [keyword]=otherkeyword1,otherkeyword2,otherkeyword3,...

As you can see the block contains two types of identifiers , keywords(keyword and otherkeyword1..3 in above example) and options, (option1..3 above).

Keywords are the built-in valid Pascal structure-identifiers like BEGIN, END, CASE, IF, THEN, ELSE, IMPLEMENTATION. The default configuration file lists most of these. Besides the real Pascal keywords, some other codewords are used for operators and comment expressions. These are listed in the following table:

codeword
Name of codeword operator
casevar : in a case label (<>'colon')
becomes :=
delphicomment //
opencomment { or (*
closecomment } or *)
semicolon ;
colon :
equals =
openparen [
closeparen ]
period .

The Options codewords define actions to be taken when the keyword before the equal sign is found.

Options
Option does what
crsupp suppress CR before the keyword.
crbefore force CR before keyword (doesn't go with crsupp :) )
blinbefore blank line before keyword.
dindonkey de-indent on assiociated keywords (see below)
dindent deindent (always)
spbef space before
spaft space after
gobsym Print symbols which follow a

keyword but which do not affect layout.
Prints until terminators occur.
(terminators are hard-coded in pptop, still needs changing)

inbytab indent by tab.
crafter force CR after keyword.
upper prints keyword all uppercase
lower prints keyword all lowercase
capital capitalizes keyword: 1st letter uppercase, rest lowercase.

The option "dindonkey" requires some extra parameters, which are set by a second line for that keyword (the one with the square brackets), which is therefore only needed if the options contain "dinkdonkey" (contraction of de-indent on assiociated keyword). "dinkdonkey" deindents if any of the keywords specified by the extra options of the square-bracket line is found. Example The lines

 else=crbefore,dindonkey,inbytab,upper
 [else]=if,then,else

Mean:

The keyword this is about is else , it's on the LEFT side of both equal signs. When the ptop parser finds ELSE, the options tell it to do the following things: - (crbefore) Don't allow other code on the line before the keyword. (ELSE alone on a line) - (dindonkey) De-indent on the keywords in square brackets line (if,then,else) - (inbytab) indent by tab. - (upper) uppercase the keyword (ELSE) Try to play with the configfile until you find the effect you desire. The configurability and possibilities of ptop are quite large compared to shareware source beautifier found on e.g. SIMTEL.

Acknowledgements

The writer of the program, Michael van Canneyt, who also helped out explaining the format of ptop.cfg. Questions/corrections can be mailed to (removed) Also thanks to the rest of the FPC development team.

SEE ALSO

ptop binary ptop(1) Other FPC utils

ppdep(1) ppudump(1) ppumove(1) h2pas(1) FreePascal 31 may 1999 3

original page: http://www.us.freepascal.org/tools/ptop.html

What follows below is the man page of ptop and the description of the configuration file. If you have installed the man pages then you can view them with the man command.