Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Shell::Perl(3)	      User Contributed Perl Documentation	Shell::Perl(3)

NAME
       Shell::Perl - A read-eval-print loop in Perl

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:

       o   Accept multiline statements;.

       o   Refactor the	code to	promote	easy customization of features.

SEE ALSO
       This project is hosted at Google	Code:

	   http://code.google.com/p/iperl/

       To know about interactive Perl interpreters, there are two FAQS
       contained in perlfaq3 which are good starting points.  Those are

	   How can I use Perl interactively?
	   http://perldoc.perl.org/perlfaq3.html#How-can-I-use-Perl-interactively%3f

	   Is there a Perl shell?
	   http://perldoc.perl.org/perlfaq3.html#How-can-I-use-Perl-interactively%3f

       An extra	list of	Perl shells can	be found here:

	   http://www.focusresearch.com/gregor/document/psh-1.1.html#other_perl_shells

BUGS
       It is a one-line	evaluator by now.

       I don't know what happens if you	eval within an eval.  I	don't expect
       good things to come. (Lorn who prodded me about this will going to find
       it out and then I will tell you.)

       There are some quirks with Term::Readline (at least on Windows).

       There are more bugs. I am lazy to collect them all and list them	now.

       Please report bugs via CPAN RT
       <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Shell-Perl> or
       <mailto://bugs-Shell-Perl@rt.cpan.org>.

AUTHORS
       Adriano R. Ferreira, <ferreira@cpan.org>

       Caio Marcelo, <cmarcelo@gmail.com>

COPYRIGHT AND LICENSE
       Copyright (C) 2007a2011 by Adriano R. Ferreira

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

POD ERRORS
       Hey! The	above document had some	coding errors, which are explained
       below:

       Around line 458:
	   Non-ASCII character seen before =encoding in	'2007a2011'. Assuming
	   UTF-8

perl v5.24.1			  2011-03-12			Shell::Perl(3)

NAME | SYNOPSYS | DESCRIPTION | GORY DETAILS | TO DO | SEE ALSO | BUGS | AUTHORS | COPYRIGHT AND LICENSE | POD ERRORS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Shell::Perl&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help