SYNOPSYS

    use Shell::Perl;
    Shell::Perl->run_with_args;

DESCRIPTION

This is the implementation of a command-line interpreter for Perl. I wrote this because I was tired of using irb when needing a calculator with a real language within. Ah, that and because it was damn easy to write it.

This module is the heart of the pirl script provided with Shell-Perl distribution, along with this module.

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

Most of the time, the shell reads Perl statements, evaluates them and outputs the result.

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:

D

"Data::Dump"

DD

"Data::Dumper", the good and old core module

DDS

"Data::Dump::Streamer"

Y

"YAML"

P

a plain dumper (``$ans'' or ``@ans'')

When creating the shell, the dump format is searched among the available ones in the order ``D'', ``DD'', ``DDS'', ``Y'' and ``P''. That means Data::Dump is preferred and will be used if available/installed. Otherwise, Data::Dumper is tried, and so on.

Read more about dumpers at Shell::Perl::Dumper.

: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

:reset

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

METHODS

Remember this is an alpha version, so the API may change and that includes the methods documented here. So consider this section as implementation notes for a while.

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_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.

GORY DETAILS

ABOUT EVALUATION

When the statement read is evaluated, this is done at a different package, which is "Shell::Perl::sandbox" by default.

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

TO DO

There is a lot to do, as always. Some of the top priority tasks are:

• Accept multiline statements;.
• Refactor the code to promote easy customization of features.

AUTHORS

Adriano R. Ferreira, <[email protected]>

Caio Marcelo, <[email protected]>

COPYRIGHT AND LICENSE

Copyright (C) 2007X2011 by Adriano R. Ferreira

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.