From: Joseph S. Myers Date: Fri, 20 Sep 1996 14:08:33 +0000 (+0100) Subject: Pod typos, pod2man bugs, and miscellaneous installation comments X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=53282e287735a6e6bbd7d90f4eb790c61d232d6e;p=p5sagit%2Fp5-mst-13.2.git Pod typos, pod2man bugs, and miscellaneous installation comments This patch just changed the old a2p.man page into a pod page. --- diff --git a/x2p/a2p.pod b/x2p/a2p.pod new file mode 100644 index 0000000..3976aba --- /dev/null +++ b/x2p/a2p.pod @@ -0,0 +1,156 @@ +=head1 NAME + +a2p - Awk to Perl translator + +=head1 SYNOPSIS + +B + +=head1 DESCRIPTION + +I takes an awk script specified on the command line (or from +standard input) and produces a comparable I script on the +standard output. + +=head2 Options + +Options include: + +=over 5 + +=item B<-DEnumberE> + +sets debugging flags. + +=item B<-FEcharacterE> + +tells a2p that this awk script is always invoked with this B<-F> +switch. + +=item B<-nEfieldlistE> + +specifies the names of the input fields if input does not have to be +split into an array. If you were translating an awk script that +processes the password file, you might say: + + a2p -7 -nlogin.password.uid.gid.gcos.shell.home + +Any delimiter can be used to separate the field names. + +=item B<-EnumberE> + +causes a2p to assume that input will always have that many fields. + +=back + +=head2 "Considerations" + +A2p cannot do as good a job translating as a human would, but it +usually does pretty well. There are some areas where you may want to +examine the perl script produced and tweak it some. Here are some of +them, in no particular order. + +There is an awk idiom of putting int() around a string expression to +force numeric interpretation, even though the argument is always +integer anyway. This is generally unneeded in perl, but a2p can't +tell if the argument is always going to be integer, so it leaves it +in. You may wish to remove it. + +Perl differentiates numeric comparison from string comparison. Awk +has one operator for both that decides at run time which comparison to +do. A2p does not try to do a complete job of awk emulation at this +point. Instead it guesses which one you want. It's almost always +right, but it can be spoofed. All such guesses are marked with the +comment "C<#???>". You should go through and check them. You might +want to run at least once with the B<-w> switch to perl, which will +warn you if you use == where you should have used eq. + +Perl does not attempt to emulate the behavior of awk in which +nonexistent array elements spring into existence simply by being +referenced. If somehow you are relying on this mechanism to create +null entries for a subsequent for...in, they won't be there in perl. + +If a2p makes a split line that assigns to a list of variables that +looks like (Fld1, Fld2, Fld3...) you may want to rerun a2p using the +B<-n> option mentioned above. This will let you name the fields +throughout the script. If it splits to an array instead, the script +is probably referring to the number of fields somewhere. + +The exit statement in awk doesn't necessarily exit; it goes to the END +block if there is one. Awk scripts that do contortions within the END +block to bypass the block under such circumstances can be simplified +by removing the conditional in the END block and just exiting directly +from the perl script. + +Perl has two kinds of array, numerically-indexed and associative. Awk +arrays are usually translated to associative arrays, but if you happen +to know that the index is always going to be numeric you could change +the {...} to [...]. Iteration over an associative array is done using +the keys() function, but iteration over a numeric array is NOT. You +might need to modify any loop that is iterating over the array in +question. + +Awk starts by assuming OFMT has the value %.6g. Perl starts by +assuming its equivalent, $#, to have the value %.20g. You'll want to +set $# explicitly if you use the default value of OFMT. + +Near the top of the line loop will be the split operation that is +implicit in the awk script. There are times when you can move this +down past some conditionals that test the entire record so that the +split is not done as often. + +For aesthetic reasons you may wish to change the array base $[ from 1 +back to perl's default of 0, but remember to change all array +subscripts AND all substr() and index() operations to match. + +Cute comments that say "# Here is a workaround because awk is dumb" +are passed through unmodified. + +Awk scripts are often embedded in a shell script that pipes stuff into +and out of awk. Often the shell script wrapper can be incorporated +into the perl script, since perl can start up pipes into and out of +itself, and can do other things that awk can't do by itself. + +Scripts that refer to the special variables RSTART and RLENGTH can +often be simplified by referring to the variables $`, $& and $', as +long as they are within the scope of the pattern match that sets them. + +The produced perl script may have subroutines defined to deal with +awk's semantics regarding getline and print. Since a2p usually picks +correctness over efficiency. it is almost always possible to rewrite +such code to be more efficient by discarding the semantic sugar. + +For efficiency, you may wish to remove the keyword from any return +statement that is the last statement executed in a subroutine. A2p +catches the most common case, but doesn't analyze embedded blocks for +subtler cases. + +ARGV[0] translates to $ARGV0, but ARGV[n] translates to $ARGV[$n]. A +loop that tries to iterate over ARGV[0] won't find it. + +=head1 ENVIRONMENT + +A2p uses no environment variables. + +=head1 AUTHOR + +Larry Wall EFE + +=head1 FILES + +=head1 SEE ALSO + + perl The perl compiler/interpreter + + s2p sed to perl translator + +=head1 DIAGNOSTICS + +=head1 BUGS + +It would be possible to emulate awk's behavior in selecting string +versus numeric operations at run time by inspection of the operands, +but it would be gross and inefficient. Besides, a2p almost always +guesses right. + +Storage for the awk syntax tree is currently static, and can run out.