EXAMPLE SESSION

    $ pirl
    Welcome to the Perl shell. Type ':help' for more information


    pirl @> 1+1
    2

    pirl @> use YAML qw(Load Dump);
    ()

    pirl @> $data = Load("--- { a: 1, b: [ 1, 2, 3] }\n");
    { a => 1, b => [1, 2, 3] }

    pirl @> $var = 'a 1 2 3'; $var =~ /(\w+) (\d+) (\d+)/
    ("a", 1, 2)

    pirl @> :q

COMMANDS

There are a few commands (started by ':') that are handled by the shell itself.

:h(elp)

Handy for remembering what the shell commands are.

:q(uit)

Leave the shell. The Perl statement "exit" will work too.

SYNONYMS: :exit, :x

:set out (D|DD|DDS|Y|P)

Changes the dumper for the expression results used before output. The current supported are:

:set ctx (scalar|list|void|s|l|v|$|@|_)

Changes the default context used to evaluate the entered expression. The default is 'list'.

Intuitively, 'scalar', 's' and '$' are synonyms, just like 'list', 'l', and '@' or 'void', 'v', '_'.

There is a nice way to override the default context in a given expression. Just a '#' followed by one of 'scalar|list|void|s|l|v|$|@|_' at the end of the expression.

    pirl @> $var = 'a 1 2 3'; $var =~ /(\w+) (\d+) (\d+)/
    ("a", 1, 2)

    pirl @> $var = 'a 1 2 3'; $var =~ /(\w+) (\d+) (\d+)/ #scalar
    1
    

:set perl_version

Changes the perl version (and current feature bundle) used to evaluate each statement. Usage examples are:

    :set perl_version 5.008
    :set perl_version v5.10
    :set perl_version        # current perl version, $]
    

Default is to use the current perl version, which works like "eval "use $];"".

Set to an empty string, as in

    :set perl_version ''
    

for the behavior of pirl 0.0023 or earlier.

:reset

Resets the environment, erasing the symbols created at the current evaluation package. See the section "ABOUT EVALUATION".

METHODS

In later versions, some of these information may be promoted to a public status. Others may be hidden or changed and even disappear without further notice.

new

    $sh = Shell::Version->new;
    

The constructor.

run_with_args

    Shell::Perl->run_with_args;
    

Starts the read-eval-print loop after reading options from @ARGV. It is a class method.

If an option -v or --version is provided, instead of starting the REPL, it prints the script identification and exits with 0.

   $ pirl -v
   This is pirl, version 0.0017 (bin/pirl, using Shell::Perl 0.0017)
    

run

    $sh->run;
    

The same as "run_with_args" but with no code for interpreting command-line arguments. It is an instance method, so that "Shell::Perl->run_with_args" is kind of:

    Shell::Perl->new->run;
    

eval

    $answer = $sh->eval($exp);
    @answer = $sh->eval($exp);
    

Evaluates the user input given in $exp as Perl code and returns the result. That is the 'eval' part of the read-eval-print loop.

print

    $sh->print(@args);
    

Prints a list of args at the output stream currently used by the shell.

help

    $sh->help;
    

Outputs the help as provided by the command ":help".

reset

    $sh->reset;
    

Does nothing by now, but it will.

dump_history

    $sh->dump_history();
    $sh->dump_history($file);
    

Prints the readline history to "STDOUT" or the optional file. Used to implement experimental command ":dump history".

This is experimental code and should change in the future. More control should be added and integrated with other terminal features.

set_ctx

    $sh->set_ctx($context);
    

Assigns to the current shell context. The argument must be one of " ( 'scalar', 'list', 'void', 's', 'l', 'v', '$', '@', '_' ) ".

set_package

    $sh->set_package($package);
    

Changes current evaluation package. Doesn't change if the new package name is malformed.

set_perl_version

    $sh->set_perl_version($version);
    

Changes perl version used to evaluate statements.

set_out

    $sh->set_out($dumper);
    

Changes the current dumper used for printing the evaluation results. Actually must be one of "D" (for Data::Dump), "DD" (for Data::Dumper), "DDS" (for Data::Dump::Streamer), "Y" (for YAML) or "P" (for plain string interpolation).

prompt_title

    $prompt = $sh->prompt_title;
    

Returns the current prompt which changes with executable name and context. For example, "pirl @>", "pirl $>", and "pirl >".

quit

    $sh->quit;
    

This method is invoked when these commands and statements are parsed by the REPL:

    :q
    :quit
    :x
    :exit
    quit
    exit
    

It runs the shutdown procedures for a smooth termination of the shell. For example, it saves the terminal history file.

ABOUT EVALUATION

So:

    $ perl -Mlib=lib bin/pirl
    Welcome to the Perl shell. Type ':help' for more information

    pirl @> $a = 2;
    2

    pirl @> :set out Y # output in YAML

    pirl @> \%Shell::Perl::sandbox::
    ---
    BEGIN: !!perl/glob:
      PACKAGE: Shell::Perl::sandbox
      NAME: BEGIN
    a: !!perl/glob:
      PACKAGE: Shell::Perl::sandbox
      NAME: a
      SCALAR: 2

This package serves as an environment for the current shell session and :reset can wipe it away.

    pirl @> :reset

    pirl @> \%Shell::Perl::sandbox::
    ---
    BEGIN: !!perl/glob:
      PACKAGE: Shell::Perl::sandbox
      NAME: BEGIN