𝌔 Fossil Hub
Login | Fossil manual |
phptags tag tidier

Check-in [caa59654f2]

Many hyperlinks are disabled.
Use anonymous login to enable hyperlinks.

Overview
Comment:Rewritten intro, general formatting (italic for tags, bold for cmdline opts), details on -D and config override file, env vars, and note about --recursive being builtin.
Timelines: family | ancestors | descendants | both | trunk
Files: files | file ages | folders
SHA1:caa59654f218635fa6488eb829b7308aee5b7b6e
User & Date: mario 2014-11-11 12:01:33
Context
2014-11-11
12:26
Exchange preg_replace/e for _callback. (Technically unnecessary due to pre-constrained input, but would generate notices; and looks leaner split up.) check-in: 18003543bc user: mario tags: trunk
12:01
Rewritten intro, general formatting (italic for tags, bold for cmdline opts), details on -D and config override file, env vars, and note about --recursive being builtin. check-in: caa59654f2 user: mario tags: trunk
12:00
Change --color handling to use XOR according to documentation, note about --recursive directory traversal being always on. check-in: ea0942e7b9 user: mario tags: trunk
Changes

Changes to manpage.1.

12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

27
28
29
30


31
32
33
34
35
36
37
..
41
42
43
44
45
46
47
48


49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76


77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
...
135
136
137
138
139
140
141
142
143
144
145





146
147
148
149
150
151
152
...
169
170
171
172
173
174
175
176

177
178
179
180
181
182
183
184

185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
...
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
[
.BI --options ,...
] [
.IB files ", " path
]

.SH DESCRIPTION
phptags is a simple tool to alternate \fB<?php\fP/\fB?>\fP tags
in \fI*.php\fP scripts. It recursively reads through directories or a given
list of scripts and cleans up \fI<?php\fP open and \fI?>\fP
close token.

It combines various operation tasks:

  * Remove leading and trailing whitespace.

  * Convert \fB<?\fP short open tokens into \fB<?php\fP long tags.
  * Or vice versa, long into short tags (for templates).
  * Remove or add \fB?>\fP close tokens.



.SH FILES
.TP
.I   *.php
Glob patterns can be used to specify a list of files to process.
(The shell usually does the pattern matching, but unprocessed
.I *.*
patterns are also accepted.)
................................................................................
.I *.php
files;
.IR php4 ", " php5 " and " phtml " extensions also accepted."
.PP
Both can be combined.
.SH OPTIONS

Short options cannot be concatenated. They must be listed individually.



.B Whitespace modification

.TP
.BI -w ", " --white ", " --whitespace
Removes leading or trailing whitespace.
.TP
.BI -W ", " --warn
Just prints warnings when it detects any whitespace (or leading UTF-8
BOM).

.PP
.B Adding or removing closing tags

.TP
.BI -c ", " --close
Appends closing ?> token when absent at end of scripts.
.TP
.BI -u ", " --unclosed
Removes trailing ?> close tag if present. (Also gets removed if there should
be trailing whitespace.)

.PP
.B Rewriting short or long tags

.TP
.BI -l ", " --long
Converts short \fI<?\fP tags into long \fI<?php\fP versions.


.TP
.BI -s ", " --short
Converts unneccessary long \fI<?php\fP tags into short \fI<?\fP or \fI<?=\fP versions. It is
not an overly sophisticated match method, but should only convert one-liners into
short tags. Occurences of \fI<?php echo\fP and \fI<? echo\fP or \fIprint\fP become
\fI<?=\fP.
.TP
.BI -a ", " --all ", " --shortall
Converts all long \fI<?php\fP tags into short \fI<?\fP versions. This is
intended for template scripts. You will need the \fB--shortall\fP option
in \fB--tokenizer\fR mode most of the time, because it cannot differentiate
between one-liners and code blocks.

.PP
.B Behaviour flags

.TP
.BI --php54
Does not rewrite <?= into long tags in --long mode, as those are always
enabled for newer PHP version 5.4 and later. (Not default, because 5.4 still
isn't widespread.)
.TP
.BI --php7
Probe for <% ASP-style tokens, and super long <script language=PHP> tags.
This is really just a mundane presence check, which does not involve rewriting
or whitespace handling around those seldom tags.
.TP
.BI --rx ", " --regex
Prefer regex for rewriting short/long tags. This is the default.
Can be ambiguous due to presence of tags within PHP string context or comments.
.TP
.BI -t ", " --token ", " --tokenizer
Use tokenizer for rewriting short/long tags.  (More reliable, but may
not work when the \fBshort_open_tag\fP \fIphp.ini\fP
setting hampers the tokenizer behaviour. It's also less judicious with
linebreaks after opening tags than the regex mode, and doesn't honor
\fB<?php print\fP variants as \fBecho\fP equivalent for \fB<?=\fP short conversion.)

.PP
.B Miscellaneous options

.TP
.BI -h ", " --help
Prints help text.
.TP
.BI -V ", " --version
Prints phptags version.
.TP
.BI -v ", " --verbose
More output.
.TP
.BI -D ", " --debug
Debugging messages.
.TP
.BI -q ", " --quiet
Does not print additional match infos in whitespace --warn mode, but just
detected files.
................................................................................
.BI --new ", " --suffix
Does not overwrite processed
.IR "*.php " "scripts, but saves changes into" " *.php.new" " filenames."
.TP
.BI -b ", " --backup
Renames old files to
.IR "filename.php~ " "prior overwriting."
.R "This won't save multiple old versions. Just the last gets copied."
.TP
.BI -d ", " --dry
Dry run. Does not save modified files back.





.TP
.BI -c ", " --color
Colorizes the --warn output on Windows. This is enabled on BSD/Linux per
default; the -c flag instead disables it there.


.SH EXAMPLES
................................................................................
.br
.I "   return array("
.br
.I "       'token' => 1, 'verbose' => 1", 'white' => 1,
.br
.I "   );"
.P
Internal flag names mostly match the long CLI parameter names.


.SH ENVIRONMENT
.TP
.IR XDG_CONFIG_HOME " (on BSD/Linux), " APPDATA " (on Windows)"
Configuration store directory instead of default \fB~/.config/\fR
.TP
.IR PHPTAGS_CONFIG
Override to temporarily disable the configuration file.

.br
For example \fBPHPTAGS_CONFIG=. phptags -v\fR will run without reading the presets.

.SH CAVEATS

Single newlines after the closing ?> php token are not an actual problem for
PHP. The parser/tokenizer eats a single \fI<NL>\fR or \fI<CR>\fR or \fI<CRLF>\fR
up. It's only when people manage to append multiple of them, or intersparsed
with spaces and tabs, that it can accrue as premature output.

ASP style \fB<%\fR tags and PHPs super long \fB<script>\fR tags are never rewritten.
(Way too uncommon to warrant fringe support. The check just exists because of their
removal with PHP "7", or PHP "8" depending on any prematurely printed books.)

.SH BUGS

Matching for <?php tags is case-sensitive. That's incorrect. PHP tags are
case-insensitive. (Like most other identifiers in PHP, unless you use e.g.
................................................................................
.IP
.I  "print 'Here <?php and ?> will get mangled.';
.br
.R becomes
.br
.I  "print 'Here <? and ?> will get mangled.';
.P
Might be wanted in rare cases. But use the
.B --tokenizer
mode otherwise for maximum resiliency.

.SH "SEE ALSO"
.BR php (1) 
.BR recode (1)
.BR fromdos (1)







|
|
|
<

<
<
<
>




>
>







 







|
>
>












|



|

|
|








>
>









|
|
|






|
|



|








|
|


|












|







 







|



>
>
>
>
>







 







|
>







|
>










|







 







|







12
13
14
15
16
17
18
19
20
21

22



23
24
25
26
27
28
29
30
31
32
33
34
35
36
..
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
...
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
...
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
...
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
[
.BI --options ,...
] [
.IB files ", " path
]

.SH DESCRIPTION
phptags is a simple tool to alterate \fB<?php\fP/\fB?>\fP tags
in \fI*.php\fP scripts. It recursively reads through directories or a
list of scripts and rewrites them according to specified operations:





  * Remove whitespace before \fB<?\fP or after \fB?>\fP.
  * Convert \fB<?\fP short open tokens into \fB<?php\fP long tags.
  * Or vice versa, long into short tags (for templates).
  * Remove or add \fB?>\fP close tokens.

Which is useful for regular consistency checks, or normalizing
third-party code.
.SH FILES
.TP
.I   *.php
Glob patterns can be used to specify a list of files to process.
(The shell usually does the pattern matching, but unprocessed
.I *.*
patterns are also accepted.)
................................................................................
.I *.php
files;
.IR php4 ", " php5 " and " phtml " extensions also accepted."
.PP
Both can be combined.
.SH OPTIONS

Short options must be listed individually / unconcatenated, because long
options may start with \fB--\fPdouble or \fB-\fPsingle hypen.  There are
more flag aliases than summarized here.

.B Whitespace modification

.TP
.BI -w ", " --white ", " --whitespace
Removes leading or trailing whitespace.
.TP
.BI -W ", " --warn
Just prints warnings when it detects any whitespace (or leading UTF-8
BOM).

.PP
.B Adding or removing close tags

.TP
.BI -c ", " --close
Appends closing \fI?>\fP token when absent at end of scripts.
.TP
.BI -u ", " --unclosed ", " --open ", " --remove-closing
Removes trailing \fI?>\fP close tag if present. (Also gets removed if there should
be trailing whitespace.)

.PP
.B Rewriting short or long tags

.TP
.BI -l ", " --long
Converts short \fI<?\fP tags into long \fI<?php\fP versions.
The inline-echo \fI<?=\fP short tag will be converted too,
unless the \fB--php54\fP flag is used.
.TP
.BI -s ", " --short
Converts unneccessary long \fI<?php\fP tags into short \fI<?\fP or \fI<?=\fP versions. It is
not an overly sophisticated match method, but should only convert one-liners into
short tags. Occurences of \fI<?php echo\fP and \fI<? echo\fP or \fIprint\fP become
\fI<?=\fP.
.TP
.BI -a ", " --all ", " --shortall
Converts all long \fI<?php\fP tags into short \fI<?\fP versions. This is
intended for template scripts.
The \fB--tokenizer\fR mode necessitates the \fB--shortall\fP option mostly,
because it cannot differentiate between one-liners and code blocks.

.PP
.B Behaviour flags

.TP
.BI --php54
Does not rewrite \fI<?=\fP into long tags in \fB--long\fP mode, as those are always
enabled for PHP versions 5.4 and later. (Not default, because 5.4 still
isn't widespread.)
.TP
.BI --php7
Probe for \fI<%\fP ASP-style tokens, and super long \fI<script language=PHP>\fP tags.
This is really just a mundane presence check, which does not involve rewriting
or whitespace handling around those seldom tags.
.TP
.BI --rx ", " --regex
Prefer regex for rewriting short/long tags. This is the default.
Can be ambiguous due to presence of tags within PHP string context or comments.
.TP
.BI -t ", " --token ", " --tokenizer
Use PHPs language tokenizer for rewriting short/long tags.
(This is more reliable, but may not work when the \fBshort_open_tag\fP \fIphp.ini\fP
setting hampers the tokenizer behaviour. It's also less judicious with
linebreaks after opening tags than the regex mode, and doesn't honor
\fI<?php print\fP variants as \fIecho\fP equivalent for \fI<?=\fP short conversion.)

.PP
.B Miscellaneous options

.TP
.BI -h ", " --help
Prints help text.
.TP
.BI -V ", " --version
Prints phptags version.
.TP
.BI -v ", " --verbose
More output for rewriting, warnings and also for \fB--help\fP.
.TP
.BI -D ", " --debug
Debugging messages.
.TP
.BI -q ", " --quiet
Does not print additional match infos in whitespace --warn mode, but just
detected files.
................................................................................
.BI --new ", " --suffix
Does not overwrite processed
.IR "*.php " "scripts, but saves changes into" " *.php.new" " filenames."
.TP
.BI -b ", " --backup
Renames old files to
.IR "filename.php~ " "prior overwriting."
.BR Warning: " This won't save multiple old versions. Just the last one gets copied."
.TP
.BI -d ", " --dry
Dry run. Does not save modified files back.
.TP
.BI -r ", " --recursive
Specified directories are recursively scanned in any case. This behaviour
can actually only be influenced in the phptags source, or overriden per
config file.
.TP
.BI -c ", " --color
Colorizes the --warn output on Windows. This is enabled on BSD/Linux per
default; the -c flag instead disables it there.


.SH EXAMPLES
................................................................................
.br
.I "   return array("
.br
.I "       'token' => 1, 'verbose' => 1", 'white' => 1,
.br
.I "   );"
.P
Internal flag names mostly match the long CLI parameter names. See \fB-D\fP
debug output for reference.

.SH ENVIRONMENT
.TP
.IR XDG_CONFIG_HOME " (on BSD/Linux), " APPDATA " (on Windows)"
Configuration store directory instead of default \fB~/.config/\fR
.TP
.IR PHPTAGS_CONFIG
More specific override to temporarily change the configuration file
location / or thereby disable processing it.
.br
For example \fBPHPTAGS_CONFIG=. phptags -v\fR will run without reading the presets.

.SH CAVEATS

Single newlines after the closing ?> php token are not an actual problem for
PHP. The parser/tokenizer eats a single \fI<NL>\fR or \fI<CR>\fR or \fI<CRLF>\fR
up. It's only when people manage to append multiple of them, or intersparsed
with spaces and tabs, that it can accrue as premature output.

ASP style \fI<%\fR tags and PHPs super long \fI<script>\fR tags are never rewritten.
(Way too uncommon to warrant fringe support. The check just exists because of their
removal with PHP "7", or PHP "8" depending on any prematurely printed books.)

.SH BUGS

Matching for <?php tags is case-sensitive. That's incorrect. PHP tags are
case-insensitive. (Like most other identifiers in PHP, unless you use e.g.
................................................................................
.IP
.I  "print 'Here <?php and ?> will get mangled.';
.br
.R becomes
.br
.I  "print 'Here <? and ?> will get mangled.';
.P
Which might actually be desirable in some cases. But use the
.B --tokenizer
mode otherwise for maximum resiliency.

.SH "SEE ALSO"
.BR php (1) 
.BR recode (1)
.BR fromdos (1)