PTop: what changed

Revision 3 to 4. Removed lines have a minus sign; added lines have a plus sign.

Old	New		Line
1	1		## About
2	2
3	3		ptop - The FPC Pascal configurable source beautifier. Name means "Pascal-TO-Pascal".
4	4
5	5		ptop is a more or less configurable source beautifier for pascal sources and specially the ones supported by FPC. ptop belongs to the FPC utils package, which currently also contains ppdep, h2pas, ppudump and ppumove.
6	6
7	7		## Author
8	8
9	9		Michael van Canneyt.
10	10
11	11		## Usage
12	12
13	13		ptop basically reformats "infile" and outputs the result to "outfile". It uses a configuration file explained further below, and can generate a default configuration file for you to edit. (not needed if you use the defaults)
14	14
15	15		```text
16	16		ptop [-v] [-i indent] [-b bufsize ] [-c optsfile] infile
17	17		```
18	18
19	19		- -h : Writes a short description of these switches.
20	20		- -c configfile : Read options from configuration file. A configuration file is not needed, ptop will revert to internal defaults then. See also -g.
21	21		- -i ident : Sets the number of indent spaces used for BEGIN END; and other blocks.
22	22		- -b bufsize : Sets the buffer size to bufsize. Default 255, 0 is considered non-valid and ignored.
23	23		- -v : be verbose. Currently only outputs the number of lines read/written and some error messages.
24	24		- -g configfile : Writes a default configuration file to be edited to the file configfile
25	25
26	26		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.
27	27
28	28		## ptop.cfg
29	29
30	30		This is the main configuration file of the ptop.
31	31
32	32		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)
33	33
34	34		### Structure
35	35
36	36		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)
37	37
38	38		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:
39	39
40	40		```text
41	41		keyword=option1,option2,option3,...
42	42		```
43	43
44	44		If one of the options is "dindonkey" (see further below), a second line (with square brackets) is needed like this:
45	45
46	46		```text
47	47		[keyword]=otherkeyword1,otherkeyword2,otherkeyword3,...
48	48		```
49	49
50	50		As you can see the block contains two types of identifiers , keywords(keyword and otherkeyword1..3 in above example) and options, (option1..3 above).
51	51
52	52		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:
53	53
54	54		codeword
55	55
56	56		Name of codeword
57	57
58	58		operator
59	59
60	60		casevar
61	61
62	62
63	63		in a case label (\<\>'colon')
64	64
65	65		becomes
66	66
67	67
68	68		=
69	69
70	70		delphicomment
71	71
72	72		//
73	73
74	74		dopencomment
75	75
76	76		(*
77	77
78	78		dclosecomment
79	79
80	80		*)
81	81
82	82		opencomment
83	83
84	84		{
85	85
86	86		closecomment \\|\\|}
87	87
88	88		semicolon
89	89
90	90		;
91	91
92	92		colon
93	93
94	94
95	95
96	96		equals
97	97
98	98		=
99	99
100	100		openparen
101	101
102	102		\[
103	103
104	104		closeparen
105	105
106	106		\]
107	107
108	108		period
109	109
110	110		.
111	111
112	112		The Options codewords define actions to be taken when the keyword before the equal sign is found.
113	113
114		-	~~<caption>Options</caption>~~
115		-	~~<thead>~~
116		-
117		-	~~</thead>~~
118		-	~~<tbody>~~
119		-
120		-	~~Prints until terminators occur.<br />~~
121		-	~~(terminators are hard-coded in pptop, still needs changing)</td>~~
	114	+	Options
122	115
123		-	~~</tbody>~~
	116	+	\| Option \| does what \|
	117	+	\|---\|---\|
	118	+	\| crsupp \| suppress CR before the keyword. \|
	119	+	\| crbefore \| force CR before keyword (doesn't go with crsupp :) ) \|
	120	+	\| blinbefore \| blank line before keyword. \|
	121	+	\| dindonkey \| de-indent on assiociated keywords (see below) \|
	122	+	\| dindent \| deindent (always) \|
	123	+	\| spbef \| space before \|
	124	+	\| spaft \| space after \|
	125	+	\| 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) \|
	126	+	\| inbytab \| indent by tab. \|
	127	+	\| crafter \| force CR after keyword. \|
	128	+	\| upper \| prints keyword all uppercase \|
	129	+	\| lower \| prints keyword all lowercase \|
	130	+	\| capital \| capitalizes keyword: 1st letter uppercase, rest lowercase. \|
124	131
125	132		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.
126	133
127	134		### Example
128	135
129	136		The lines
130	137
131	138		```text
132	139		else=crbefore,dindonkey,inbytab,upper
133	140		[else]=if,then,else
134	141		```
135	142
136	143		Mean:
137	144
138	145		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:
139	146
140	147		- (crbefore) Don't allow other code on the line before the keyword. (ELSE alone on a line)
141	148		- (dindonkey) De-indent on the keywords in square brackets line (if,then,else)
142	149		- (inbytab) indent by tab.
143	150		- (upper) uppercase the keyword (ELSE)
144	151
145	152		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.
146	153
147	154		## Links
148	155
149	156		Other FPC utils:
150	157
151	158		- [[ppdep]]
152	159		- [[ppudump]]
153	160		- [[ppumove]]
154	161		- [[H2Pas]]
155	162
156	163		Original page:
157	164
158	165		<http://www.us.freepascal.org/tools/ptop.html>
159	166
160	167		---
161	168		From the Free Pascal wiki, page "PTop", as it stood on 2014-11-20 after a change by Alextp, out of the wiki's dump of 2024-05-26. Copyright stays with the author who wrote it, according to the old wiki's [[Licensing]] page. If you have concerns about this material, [message the admin](/wiki-contact).
162	169		Category: FPC
163	170		Category: Utilities

Back to history