# $EPIC: perl,v 1.6 2002/01/13 00:27:11 anders Exp $
Synopsis:
   $perl([<expression>])

Technical:
   * If <expression> is given and the embedded perl interpreter isn't
     running, then it is bootstrapped.
   * If <expression> is given, the embedded perl interpreter is called to
     evaluate it, returning the scalar value (this is a perl term).
   * Otherwise, an empty string is returned.

Practical:

   $perl() is useful for loading perl scripts and modules, defining
   simple perl functions, retrieving variables from within perlspace and
   other general maintenance of the perl environment.

   Anything passed to $perl() is subject to perls expression syntax
   rules as well as epics. This makes it both more powerful and tricky.
   The most difficult thing to come to terms with will probably be
   that both epic and perl use $ for variable names. This can lead to
   confusion.

Returns:
   The scalar value of the perl expression. If any other data type is
   returned, it will be converted to a scalar under perls rules.

Examples:
   $perl(do script.pl)  Loads and runs script.pl.
                        See the perl documentation for the "do" function.
   $perl(use Time::localtime)
                        Loads the standard perl module Time::localtime.
   $perl(localtime->yday())
                        Returns the day of the year from module Time::localtime.
   $perl(sub foo {reverse(wantarray ? @_ : "@_")})
                        Defines a perl subroutine which returns the reverse of
                        its input, whether it is called in scalar or list
                        context.
   $perl(keys %ENV)     Returns the number of variables in your environment.
                        This is because keys returns a list, and $perl()
                        returns the scalar value of the expression, which is
                        the number of elements in the returned list.
   $perl(@keys=keys %ENV; "@keys")
                        Since perl lists are scalar when quoted this way, the
                        names of all environment variables will be returned.
   $perl(shift @array)  Returns the shifted variable.
   $perl(push @array,"nick!user@host")
                        This will fail, because perl will try to insert a perl
                        array @host into the string.  Furthermore, if any of
                        nick, user or host contains the quote character used to
                        quote the string, the expression will also fail.  The
                        correct way to do this is to define a subroutine which
                        pushes its arguments onto @array and call it with
                        $perlcall(sub nick!user@host).
   $perl($scalar)       Returns the value of the expression in the epic (not
                        perl) variable $scalar.
   $perl(\$scalar)      Returns the value of the perl scalar variable $scalar.
   $perl(`ls`)          A fast substitute for the epic $pipe(ls) alias.
   $perl(1+2*3)         How to use perl math.

See Also:
   Perl(7); perlcall(6); perlxcall(6)
