Commit | Line | Data |
8d063cd8 |
1 | .rn '' }` |
79072805 |
2 | ''' $RCSfile: a2p.man,v $$Revision: 4.1 $$Date: 92/08/07 18:29:10 $ |
8d063cd8 |
3 | ''' |
4 | ''' $Log: a2p.man,v $ |
79072805 |
5 | ''' Revision 4.1 92/08/07 18:29:10 lwall |
6 | ''' |
fe14fcc3 |
7 | ''' Revision 4.0 91/03/20 01:57:11 lwall |
8 | ''' 4.0 baseline. |
9 | ''' |
a687059c |
10 | ''' Revision 3.0 89/10/18 15:34:22 lwall |
11 | ''' 3.0 baseline |
12 | ''' |
13 | ''' Revision 2.0.1.1 88/07/11 23:16:25 root |
14 | ''' patch2: changes related to 1985 awk |
15 | ''' |
378cc40b |
16 | ''' Revision 2.0 88/06/05 00:15:36 root |
17 | ''' Baseline version 2.0. |
8d063cd8 |
18 | ''' |
19 | ''' |
20 | .de Sh |
21 | .br |
22 | .ne 5 |
23 | .PP |
24 | \fB\\$1\fR |
25 | .PP |
26 | .. |
27 | .de Sp |
28 | .if t .sp .5v |
29 | .if n .sp |
30 | .. |
31 | .de Ip |
32 | .br |
33 | .ie \\n.$>=3 .ne \\$3 |
34 | .el .ne 3 |
35 | .IP "\\$1" \\$2 |
36 | .. |
37 | ''' |
38 | ''' Set up \*(-- to give an unbreakable dash; |
39 | ''' string Tr holds user defined translation string. |
40 | ''' Bell System Logo is used as a dummy character. |
41 | ''' |
378cc40b |
42 | .tr \(*W-|\(bv\*(Tr |
8d063cd8 |
43 | .ie n \{\ |
378cc40b |
44 | .ds -- \(*W- |
45 | .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch |
46 | .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch |
8d063cd8 |
47 | .ds L" "" |
48 | .ds R" "" |
49 | .ds L' ' |
50 | .ds R' ' |
51 | 'br\} |
52 | .el\{\ |
53 | .ds -- \(em\| |
54 | .tr \*(Tr |
55 | .ds L" `` |
56 | .ds R" '' |
57 | .ds L' ` |
58 | .ds R' ' |
59 | 'br\} |
60 | .TH A2P 1 LOCAL |
61 | .SH NAME |
62 | a2p - Awk to Perl translator |
63 | .SH SYNOPSIS |
64 | .B a2p [options] filename |
65 | .SH DESCRIPTION |
66 | .I A2p |
67 | takes an awk script specified on the command line (or from standard input) |
68 | and produces a comparable |
69 | .I perl |
70 | script on the standard output. |
71 | .Sh "Options" |
72 | Options include: |
73 | .TP 5 |
74 | .B \-D<number> |
75 | sets debugging flags. |
76 | .TP 5 |
77 | .B \-F<character> |
78 | tells a2p that this awk script is always invoked with this -F switch. |
79 | .TP 5 |
80 | .B \-n<fieldlist> |
81 | specifies the names of the input fields if input does not have to be split into |
82 | an array. |
83 | If you were translating an awk script that processes the password file, you |
84 | might say: |
85 | .sp |
86 | a2p -7 -nlogin.password.uid.gid.gcos.shell.home |
87 | .sp |
a687059c |
88 | Any delimiter can be used to separate the field names. |
8d063cd8 |
89 | .TP 5 |
90 | .B \-<number> |
91 | causes a2p to assume that input will always have that many fields. |
92 | .Sh "Considerations" |
93 | A2p cannot do as good a job translating as a human would, but it usually |
94 | does pretty well. |
95 | There are some areas where you may want to examine the perl script produced |
96 | and tweak it some. |
97 | Here are some of them, in no particular order. |
98 | .PP |
8d063cd8 |
99 | There is an awk idiom of putting int() around a string expression to force |
100 | numeric interpretation, even though the argument is always integer anyway. |
101 | This is generally unneeded in perl, but a2p can't tell if the argument |
102 | is always going to be integer, so it leaves it in. |
103 | You may wish to remove it. |
104 | .PP |
105 | Perl differentiates numeric comparison from string comparison. |
106 | Awk has one operator for both that decides at run time which comparison |
107 | to do. |
108 | A2p does not try to do a complete job of awk emulation at this point. |
109 | Instead it guesses which one you want. |
110 | It's almost always right, but it can be spoofed. |
111 | All such guesses are marked with the comment \*(L"#???\*(R". |
112 | You should go through and check them. |
a687059c |
113 | You might want to run at least once with the \-w switch to perl, which |
114 | will warn you if you use == where you should have used eq. |
8d063cd8 |
115 | .PP |
116 | Perl does not attempt to emulate the behavior of awk in which nonexistent |
117 | array elements spring into existence simply by being referenced. |
118 | If somehow you are relying on this mechanism to create null entries for |
119 | a subsequent for...in, they won't be there in perl. |
120 | .PP |
121 | If a2p makes a split line that assigns to a list of variables that looks |
122 | like (Fld1, Fld2, Fld3...) you may want |
123 | to rerun a2p using the \-n option mentioned above. |
124 | This will let you name the fields throughout the script. |
125 | If it splits to an array instead, the script is probably referring to the number |
126 | of fields somewhere. |
127 | .PP |
128 | The exit statement in awk doesn't necessarily exit; it goes to the END |
129 | block if there is one. |
130 | Awk scripts that do contortions within the END block to bypass the block under |
131 | such circumstances can be simplified by removing the conditional |
132 | in the END block and just exiting directly from the perl script. |
133 | .PP |
134 | Perl has two kinds of array, numerically-indexed and associative. |
135 | Awk arrays are usually translated to associative arrays, but if you happen |
136 | to know that the index is always going to be numeric you could change |
137 | the {...} to [...]. |
a687059c |
138 | Iteration over an associative array is done using the keys() function, but |
8d063cd8 |
139 | iteration over a numeric array is NOT. |
a687059c |
140 | You might need to modify any loop that is iterating over the array in question. |
8d063cd8 |
141 | .PP |
142 | Awk starts by assuming OFMT has the value %.6g. |
143 | Perl starts by assuming its equivalent, $#, to have the value %.20g. |
144 | You'll want to set $# explicitly if you use the default value of OFMT. |
145 | .PP |
146 | Near the top of the line loop will be the split operation that is implicit in |
147 | the awk script. |
148 | There are times when you can move this down past some conditionals that |
149 | test the entire record so that the split is not done as often. |
150 | .PP |
8d063cd8 |
151 | For aesthetic reasons you may wish to change the array base $[ from 1 back |
a687059c |
152 | to perl's default of 0, but remember to change all array subscripts AND |
8d063cd8 |
153 | all substr() and index() operations to match. |
154 | .PP |
a687059c |
155 | Cute comments that say "# Here is a workaround because awk is dumb" are passed |
156 | through unmodified. |
8d063cd8 |
157 | .PP |
158 | Awk scripts are often embedded in a shell script that pipes stuff into and |
159 | out of awk. |
160 | Often the shell script wrapper can be incorporated into the perl script, since |
161 | perl can start up pipes into and out of itself, and can do other things that |
162 | awk can't do by itself. |
a687059c |
163 | .PP |
164 | Scripts that refer to the special variables RSTART and RLENGTH can often |
165 | be simplified by referring to the variables $`, $& and $', as long as they |
166 | are within the scope of the pattern match that sets them. |
167 | .PP |
168 | The produced perl script may have subroutines defined to deal with awk's |
169 | semantics regarding getline and print. |
170 | Since a2p usually picks correctness over efficiency. |
171 | it is almost always possible to rewrite such code to be more efficient by |
172 | discarding the semantic sugar. |
173 | .PP |
174 | For efficiency, you may wish to remove the keyword from any return statement |
175 | that is the last statement executed in a subroutine. |
176 | A2p catches the most common case, but doesn't analyze embedded blocks for |
177 | subtler cases. |
178 | .PP |
179 | ARGV[0] translates to $ARGV0, but ARGV[n] translates to $ARGV[$n]. |
180 | A loop that tries to iterate over ARGV[0] won't find it. |
8d063cd8 |
181 | .SH ENVIRONMENT |
182 | A2p uses no environment variables. |
183 | .SH AUTHOR |
a687059c |
184 | Larry Wall <lwall@jpl-devvax.Jpl.Nasa.Gov> |
8d063cd8 |
185 | .SH FILES |
186 | .SH SEE ALSO |
187 | perl The perl compiler/interpreter |
188 | .br |
189 | s2p sed to perl translator |
190 | .SH DIAGNOSTICS |
191 | .SH BUGS |
192 | It would be possible to emulate awk's behavior in selecting string versus |
193 | numeric operations at run time by inspection of the operands, but it would |
194 | be gross and inefficient. |
195 | Besides, a2p almost always guesses right. |
196 | .PP |
197 | Storage for the awk syntax tree is currently static, and can run out. |
198 | .rn }` '' |