view release on metacpan or  search on metacpan

lib/App/sh2p.pod  view on Meta::CPAN

=head1 NAME

App::sh2p - Perl program to aid for conversion from UNIX shell to Perl

=head1 SYNOPSIS

  sh2p.pl [-i] [-t] [-f] script-name output-file | script-name [...] output-directory

  -i Do not use integer
  -t Generate test output.  Each line from the shell script is written, with the prefix
     '#< ', before the converted line.  This is for testing and not recommended for general use.
  -f Clobber output files in the output directory

This Perl script, and associated modules in the sh2p directory, 
will attempt to convert the supplied shell script/s to Perl. 

Only shells based upon the POSIX standard are supported.  This include most popular
shells like Bourne, Korn, and Bash, but specifically EXCLUDES C shell (csh, tcsh).

Most Korn shell 93 extensions are currently not supported.

CAVEAT: Incorrect shell commands will result in incorrect Perl!

=head1 DESCRIPTION

This program attempts to convert the base syntax of a UNIX shell script to Perl.  
It does not attempt to redesign the script for Perl but to assist in the conversion 
process by automating much of the tedium.

It can be run by either supplying the input and output file names, or by supplying
a list of input file names and an output directory, which must be the right-most 
parameter and must already exist.  If hyphen ('-') is supplied for either input or output file name
then STDIN is read or STDOUT written to (not valid as a directory name).

The output file will be overwritten if it exists.  
If the directory output form is taken then an output file name is generated from the
input file name, with '.pl' appended (any existing 'extension' will be removed).  If
this file already exists then the user will be prompted for permission to overwrite it,
unless the -f (force) option is given.

The generated code will:

Have a #! line generated from $Config{'perlpath'}.

    use integer;

The POSIX shell only supports integer arithmetic, this may be supressed with the -i option
  

=head2 INSPECT messages

These are output whenever sh2p detects code which requires manual intervention,
which is often.  A message of the format '**** INSPECT: free-text' is written to 
the output script as a comment.  A similar message is written to STDERR, prefixed 
by the line number and grouped by file.

=head3 autoload '$var' ignored

autoload, and typedef -fu, prepares the translator for names which are functions.
Variable values containing a function name are set at runtime and cannot be used, 
so are ignored.

=head3 file descriptors not currently supported

=head3 <func> replaced by Perl built-in <new_func>

Advice to replace the specified program with a Perl alternative

=head3 <func> should be replaced by something like <advise>

Advice to replace the specified program with a Perl alternative

=head3 Multiple levels in 'break $level' not supported

=head3 Multiple levels in 'continue $level' not supported

=head3 Suspious conversion from expr

Many expr commands can be repeated as straight Perl - but not all.

=head3 The following line cannot be translated:

A "catch all" message where I give up.  Often when setting shell options

=head3 Pipes/co-processes are not supported, use open

=head3 read through ksh pipes is not supported

The -p option to 'read' has different meanings in Bash and ksh.
The shell in use is determined from the #! line.  If this is not supplied
then 'read' assumes the Bash syntax, which is more common.

=head3 Unrecognised shopt argument: 

Only a limited number of the Bash 'shopt' options are relevant to Perl

=head3 sourced file should also be converted