PTop: what changed

Revision 2 to 3. 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		-	~~` ptop [-v] [-i indent] [-b bufsize ] [-c optsfile] infile`~~
	15	+	```text
	16	+	ptop [-v] [-i indent] [-b bufsize ] [-c optsfile] infile
	17	+	```
16	18
17	19		- -h : Writes a short description of these switches.
18	20		- -c configfile : Read options from configuration file. A configuration file is not needed, ptop will revert to internal defaults then. See also -g.
19	21		- -i ident : Sets the number of indent spaces used for BEGIN END; and other blocks.
20	22		- -b bufsize : Sets the buffer size to bufsize. Default 255, 0 is considered non-valid and ignored.
21	23		- -v : be verbose. Currently only outputs the number of lines read/written and some error messages.
22	24		- -g configfile : Writes a default configuration file to be edited to the file configfile
23	25
24	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.
25	27
26	28		## ptop.cfg
27	29
28	30		This is the main configuration file of the ptop.
29	31
30	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)
31	33
32	34		### Structure
33	35
34	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)
35	37
36	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:
37	39
38		-	~~` keyword=option1,option2,option3,...`~~
	40	+	```text
	41	+	keyword=option1,option2,option3,...
	42	+	```
39	43
40	44		If one of the options is "dindonkey" (see further below), a second line (with square brackets) is needed like this:
41	45
42		-	~~` [keyword]=otherkeyword1,otherkeyword2,otherkeyword3,...`~~
	46	+	```text
	47	+	[keyword]=otherkeyword1,otherkeyword2,otherkeyword3,...
	48	+	```
43	49
44	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).
45	51
46	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:
47	53
48	54		codeword
49	55
50	56		Name of codeword
51	57
52	58		operator
53	59
54	60		casevar
55	61
56	62
57	63		in a case label (\<\>'colon')
58	64
59	65		becomes
60	66
61	67
62	68		=
63	69
64	70		delphicomment
65	71
66	72		//
67	73
68	74		dopencomment
69	75
70	76		(*
71	77
72	78		dclosecomment
73	79
74	80		*)
75	81
76	82		opencomment
77	83
78	84		{
79	85
80	86		closecomment \\|\\|}
81	87
82	88		semicolon
83	89
84	90		;
85	91
86	92		colon
87	93
88	94
89	95
90	96		equals
91	97
92	98		=
93	99
94	100		openparen
95	101
96	102		\[
97	103
98	104		closeparen
99	105
100	106		\]
101	107
102	108		period
103	109
104	110		.
105	111
106	112		The Options codewords define actions to be taken when the keyword before the equal sign is found.
107	113
108	114		<caption>Options</caption>
109	115		<thead>
110	116
111	117		</thead>
112	118		<tbody>
113	119
114	120		Prints until terminators occur.<br />
115	121		(terminators are hard-coded in pptop, still needs changing)</td>
116	122
117	123		</tbody>
118	124
119	125		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.
120	126
121	127		### Example
122	128
123	129		The lines
124	130
125		-	~~` else=crbefore,dindonkey,inbytab,upper`\~~
126		-	~~` [else]=if,then,else`~~
	131	+	```text
	132	+	else=crbefore,dindonkey,inbytab,upper
	133	+	[else]=if,then,else
	134	+	```
127	135
128	136		Mean:
129	137
130	138		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:
131	139
132	140		- (crbefore) Don't allow other code on the line before the keyword. (ELSE alone on a line)
133	141		- (dindonkey) De-indent on the keywords in square brackets line (if,then,else)
134	142		- (inbytab) indent by tab.
135	143		- (upper) uppercase the keyword (ELSE)
136	144
137	145		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.
138	146
139	147		## Links
140	148
141	149		Other FPC utils:
142	150
143	151		- [[ppdep]]
144	152		- [[ppudump]]
145	153		- [[ppumove]]
146	154		- [[H2Pas]]
147	155
148	156		Original page:
149	157
150	158		<http://www.us.freepascal.org/tools/ptop.html>
151	159
152	160		---
153	161		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).
154	162		Category: FPC
155	163		Category: Utilities

Back to history