S_del_body is sufficiently small that inlining it is a space win.
[p5sagit/p5-mst-13.2.git] / x2p / a2p.pod
CommitLineData
53282e28 1=head1 NAME
2
3a2p - Awk to Perl translator
4
5=head1 SYNOPSIS
6
53273a08 7B<a2p> [I<options>] [I<filename>]
53282e28 8
9=head1 DESCRIPTION
10
11I<A2p> takes an awk script specified on the command line (or from
12standard input) and produces a comparable I<perl> script on the
13standard output.
14
53273a08 15=head2 OPTIONS
53282e28 16
17Options include:
18
19=over 5
20
21=item B<-DE<lt>numberE<gt>>
22
23sets debugging flags.
24
25=item B<-FE<lt>characterE<gt>>
26
27tells a2p that this awk script is always invoked with this B<-F>
28switch.
29
30=item B<-nE<lt>fieldlistE<gt>>
31
32specifies the names of the input fields if input does not have to be
33split into an array. If you were translating an awk script that
34processes the password file, you might say:
35
36 a2p -7 -nlogin.password.uid.gid.gcos.shell.home
37
38Any delimiter can be used to separate the field names.
39
40=item B<-E<lt>numberE<gt>>
41
42causes a2p to assume that input will always have that many fields.
43
a5571d59 44=item B<-o>
45
2efaeb47 46tells a2p to use old awk behavior. The only current differences are:
47
48=over 5
49
4ac9195f 50=item *
2efaeb47 51
52Old awk always has a line loop, even if there are no line
a5571d59 53actions, whereas new awk does not.
54
4ac9195f 55=item *
2efaeb47 56
57In old awk, sprintf is extremely greedy about its arguments.
58For example, given the statement
59
60 print sprintf(some_args), extra_args;
61
62old awk considers I<extra_args> to be arguments to C<sprintf>; new awk
63considers them arguments to C<print>.
64
53282e28 65=back
66
4ac9195f 67=back
68
53282e28 69=head2 "Considerations"
70
71A2p cannot do as good a job translating as a human would, but it
72usually does pretty well. There are some areas where you may want to
73examine the perl script produced and tweak it some. Here are some of
74them, in no particular order.
75
76There is an awk idiom of putting int() around a string expression to
77force numeric interpretation, even though the argument is always
78integer anyway. This is generally unneeded in perl, but a2p can't
79tell if the argument is always going to be integer, so it leaves it
80in. You may wish to remove it.
81
82Perl differentiates numeric comparison from string comparison. Awk
83has one operator for both that decides at run time which comparison to
84do. A2p does not try to do a complete job of awk emulation at this
85point. Instead it guesses which one you want. It's almost always
86right, but it can be spoofed. All such guesses are marked with the
87comment "C<#???>". You should go through and check them. You might
88want to run at least once with the B<-w> switch to perl, which will
89warn you if you use == where you should have used eq.
90
91Perl does not attempt to emulate the behavior of awk in which
92nonexistent array elements spring into existence simply by being
93referenced. If somehow you are relying on this mechanism to create
94null entries for a subsequent for...in, they won't be there in perl.
95
96If a2p makes a split line that assigns to a list of variables that
97looks like (Fld1, Fld2, Fld3...) you may want to rerun a2p using the
98B<-n> option mentioned above. This will let you name the fields
99throughout the script. If it splits to an array instead, the script
100is probably referring to the number of fields somewhere.
101
102The exit statement in awk doesn't necessarily exit; it goes to the END
103block if there is one. Awk scripts that do contortions within the END
104block to bypass the block under such circumstances can be simplified
105by removing the conditional in the END block and just exiting directly
106from the perl script.
107
aa689395 108Perl has two kinds of array, numerically-indexed and associative.
109Perl associative arrays are called "hashes". Awk arrays are usually
110translated to hashes, but if you happen to know that the index is
111always going to be numeric you could change the {...} to [...].
112Iteration over a hash is done using the keys() function, but iteration
113over an array is NOT. You might need to modify any loop that iterates
114over such an array.
53282e28 115
116Awk starts by assuming OFMT has the value %.6g. Perl starts by
117assuming its equivalent, $#, to have the value %.20g. You'll want to
118set $# explicitly if you use the default value of OFMT.
119
120Near the top of the line loop will be the split operation that is
121implicit in the awk script. There are times when you can move this
122down past some conditionals that test the entire record so that the
123split is not done as often.
124
125For aesthetic reasons you may wish to change the array base $[ from 1
126back to perl's default of 0, but remember to change all array
127subscripts AND all substr() and index() operations to match.
128
129Cute comments that say "# Here is a workaround because awk is dumb"
130are passed through unmodified.
131
132Awk scripts are often embedded in a shell script that pipes stuff into
133and out of awk. Often the shell script wrapper can be incorporated
134into the perl script, since perl can start up pipes into and out of
135itself, and can do other things that awk can't do by itself.
136
137Scripts that refer to the special variables RSTART and RLENGTH can
138often be simplified by referring to the variables $`, $& and $', as
139long as they are within the scope of the pattern match that sets them.
140
141The produced perl script may have subroutines defined to deal with
142awk's semantics regarding getline and print. Since a2p usually picks
143correctness over efficiency. it is almost always possible to rewrite
144such code to be more efficient by discarding the semantic sugar.
145
146For efficiency, you may wish to remove the keyword from any return
147statement that is the last statement executed in a subroutine. A2p
148catches the most common case, but doesn't analyze embedded blocks for
149subtler cases.
150
151ARGV[0] translates to $ARGV0, but ARGV[n] translates to $ARGV[$n]. A
152loop that tries to iterate over ARGV[0] won't find it.
153
154=head1 ENVIRONMENT
155
156A2p uses no environment variables.
157
158=head1 AUTHOR
159
55497cff 160Larry Wall E<lt>F<larry@wall.org>E<gt>
53282e28 161
162=head1 FILES
163
164=head1 SEE ALSO
165
166 perl The perl compiler/interpreter
167
168 s2p sed to perl translator
169
170=head1 DIAGNOSTICS
171
172=head1 BUGS
173
174It would be possible to emulate awk's behavior in selecting string
175versus numeric operations at run time by inspection of the operands,
176but it would be gross and inefficient. Besides, a2p almost always
177guesses right.
178
179Storage for the awk syntax tree is currently static, and can run out.