.\" Automatically generated by Pod::Man 2.27 (Pod::Simple 3.28) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is turned on, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{ . if \nF \{ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "Shell::Perl 3pm" .TH Shell::Perl 3pm "2014-02-02" "perl v5.18.2" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Shell::Perl \- A read\-eval\-print loop in Perl .SH "SYNOPSYS" .IX Header "SYNOPSYS" .Vb 2 \& use Shell::Perl; \& Shell::Perl\->run_with_args; .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This is the implementation of a command-line interpreter for Perl. I wrote this because I was tired of using \fBirb\fR when needing a calculator with a real language within. Ah, that and because it was damn easy to write it. .PP This module is the heart of the \fBpirl\fR script provided with \&\fBShell-Perl\fR distribution, along with this module. .SS "\s-1EXAMPLE SESSION\s0" .IX Subsection "EXAMPLE SESSION" .Vb 2 \& $ pirl \& Welcome to the Perl shell. Type \*(Aq:help\*(Aq for more information \& \& \& pirl @> 1+1 \& 2 \& \& pirl @> use YAML qw(Load Dump); \& () \& \& pirl @> $data = Load("\-\-\- { a: 1, b: [ 1, 2, 3] }\en"); \& { a => 1, b => [1, 2, 3] } \& \& pirl @> $var = \*(Aqa 1 2 3\*(Aq; $var =~ /(\ew+) (\ed+) (\ed+)/ \& ("a", 1, 2) \& \& pirl @> :q .Ve .SS "\s-1COMMANDS\s0" .IX Subsection "COMMANDS" Most of the time, the shell reads Perl statements, evaluates them and outputs the result. .PP There are a few commands (started by ':') that are handled by the shell itself. .IP ":h(elp)" 4 .IX Item ":h(elp)" Handy for remembering what the shell commands are. .IP ":q(uit)" 4 .IX Item ":q(uit)" Leave the shell. The Perl statement \f(CW\*(C`exit\*(C'\fR will work too. .Sp \&\s-1SYNONYMS:\s0 :exit, :x .IP ":set out (D|DD|DDS|Y|P)" 4 .IX Item ":set out (D|DD|DDS|Y|P)" Changes the dumper for the expression results used before output. The current supported are: .RS 4 .IP "D" 4 .IX Item "D" \&\f(CW\*(C`Data::Dump\*(C'\fR .IP "\s-1DD\s0" 4 .IX Item "DD" \&\f(CW\*(C`Data::Dumper\*(C'\fR, the good and old core module .IP "\s-1DDS\s0" 4 .IX Item "DDS" \&\f(CW\*(C`Data::Dump::Streamer\*(C'\fR .IP "Y" 4 .IX Item "Y" \&\f(CW\*(C`YAML\*(C'\fR .IP "P" 4 .IX Item "P" a plain dumper (\*(L"$ans\*(R" or \*(L"@ans\*(R") .RE .RS 4 .Sp When creating the shell, the dump format is searched among the available ones in the order \*(L"D\*(R", \*(L"\s-1DD\*(R", \*(L"DDS\*(R", \*(L"Y\*(R"\s0 and \*(L"P\*(R". That means Data::Dump is preferred and will be used if available/installed. Otherwise, Data::Dumper is tried, and so on. .Sp Read more about dumpers at Shell::Perl::Dumper. .RE .IP ":set ctx (scalar|list|void|s|l|v|$|@|_)" 4 .IX Item ":set ctx (scalar|list|void|s|l|v|$|@|_)" Changes the default context used to evaluate the entered expression. The default is \f(CW\*(Aqlist\*(Aq\fR. .Sp Intuitively, 'scalar', 's' and '$' are synonyms, just like 'list', 'l', and '@' or 'void', 'v', '_'. .Sp 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. .Sp .Vb 2 \& pirl @> $var = \*(Aqa 1 2 3\*(Aq; $var =~ /(\ew+) (\ed+) (\ed+)/ \& ("a", 1, 2) \& \& pirl @> $var = \*(Aqa 1 2 3\*(Aq; $var =~ /(\ew+) (\ed+) (\ed+)/ #scalar \& 1 .Ve .IP ":reset" 4 .IX Item ":reset" Resets the environment, erasing the symbols created at the current evaluation package. See the section \*(L"\s-1ABOUT EVALUATION\*(R"\s0. .SS "\s-1METHODS\s0" .IX Subsection "METHODS" Remember this is an alpha version, so the \s-1API\s0 may change and that includes the methods documented here. So consider this section as implementation notes for a while. .PP 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. .IP "\fBnew\fR" 4 .IX Item "new" .Vb 1 \& $sh = Shell::Version\->new; .Ve .Sp The constructor. .IP "\fBrun_with_args\fR" 4 .IX Item "run_with_args" .Vb 1 \& Shell::Perl\->run_with_args; .Ve .Sp Starts the read-eval-print loop after reading options from \f(CW@ARGV\fR. It is a class method. .Sp If an option \fB\-v\fR or \fB\-\-version\fR is provided, instead of starting the \s-1REPL,\s0 it prints the script identification and exits with 0. .Sp .Vb 2 \& $ pirl \-v \& This is pirl, version 0.0017 (bin/pirl, using Shell::Perl 0.0017) .Ve .IP "\fBrun\fR" 4 .IX Item "run" .Vb 1 \& $sh\->run; .Ve .Sp The same as \f(CW\*(C`run_with_args\*(C'\fR but with no code for interpreting command-line arguments. It is an instance method, so that \f(CW\*(C`Shell::Perl\-\*(C'\fRrun_with_args> is kind of: .Sp .Vb 1 \& Shell::Perl\->new\->run; .Ve .IP "\fBeval\fR" 4 .IX Item "eval" .Vb 2 \& $answer = $sh\->eval($exp); \& @answer = $sh\->eval($exp); .Ve .Sp Evaluates the user input given in \f(CW$exp\fR as Perl code and returns the result. That is the 'eval' part of the read-eval-print loop. .IP "\fBprint\fR" 4 .IX Item "print" .Vb 1 \& $sh\->print(@args); .Ve .Sp Prints a list of args at the output stream currently used by the shell. .IP "\fBhelp\fR" 4 .IX Item "help" .Vb 1 \& $sh\->help; .Ve .Sp Outputs the help as provided by the command \*(L":help\*(R". .IP "\fBreset\fR" 4 .IX Item "reset" .Vb 1 \& $sh\->reset; .Ve .Sp Does nothing by now, but it will. .IP "\fBdump_history\fR" 4 .IX Item "dump_history" .Vb 2 \& $sh\->dump_history(); \& $sh\->dump_history($file); .Ve .Sp Prints the readline history to \f(CW\*(C`STDOUT\*(C'\fR or the optional file. Used to implement experimental command \*(L":dump history\*(R". .Sp This is experimental code and should change in the future. More control should be added and integrated with other terminal features. .IP "\fBset_ctx\fR" 4 .IX Item "set_ctx" .Vb 1 \& $sh\->set_ctx($context); .Ve .Sp Assigns to the current shell context. The argument must be one of \f(CW\*(C` ( \*(Aqscalar\*(Aq, \*(Aqlist\*(Aq, \*(Aqvoid\*(Aq, \&\*(Aqs\*(Aq, \*(Aql\*(Aq, \*(Aqv\*(Aq, \*(Aq$\*(Aq, \*(Aq@\*(Aq, \*(Aq_\*(Aq ) \*(C'\fR. .IP "\fBset_package\fR" 4 .IX Item "set_package" .Vb 1 \& $sh\->set_package($package); .Ve .Sp Changes current evaluation package. Doesn't change if the new package name is malformed. .IP "\fBset_out\fR" 4 .IX Item "set_out" .Vb 1 \& $sh\->set_out($dumper); .Ve .Sp Changes the current dumper used for printing the evaluation results. Actually must be one of \&\*(L"D\*(R" (for Data::Dump), \*(L"\s-1DD\*(R" \s0(for Data::Dumper), \&\*(L"\s-1DDS\*(R" \s0(for Data::Dump::Streamer), \&\*(L"Y\*(R" (for \s-1YAML\s0) or \*(L"P\*(R" (for plain string interpolation). .IP "\fBprompt_title\fR" 4 .IX Item "prompt_title" .Vb 1 \& $prompt = $sh\->prompt_title; .Ve .Sp Returns the current prompt which changes with executable name and context. For example, \&\*(L"pirl @>\*(R", \*(L"pirl $>\*(R", and \*(L"pirl >\*(R". .IP "\fBquit\fR" 4 .IX Item "quit" .Vb 1 \& $sh\->quit; .Ve .Sp This method is invoked when these commands and statements are parsed by the \s-1REPL:\s0 .Sp .Vb 6 \& :q \& :quit \& :x \& :exit \& quit \& exit .Ve .Sp It runs the shutdown procedures for a smooth termination of the shell. For example, it saves the terminal history file. .SH "GORY DETAILS" .IX Header "GORY DETAILS" .SS "\s-1ABOUT EVALUATION\s0" .IX Subsection "ABOUT EVALUATION" When the statement read is evaluated, this is done at a different package, which is \f(CW\*(C`Shell::Perl::sandbox\*(C'\fR by default. .PP So: .PP .Vb 2 \& $ perl \-Mlib=lib bin/pirl \& Welcome to the Perl shell. Type \*(Aq:help\*(Aq for more information \& \& pirl @> $a = 2; \& 2 \& \& pirl @> :set out Y # output in YAML \& \& pirl @> \e%Shell::Perl::sandbox:: \& \-\-\- \& BEGIN: !!perl/glob: \& PACKAGE: Shell::Perl::sandbox \& NAME: BEGIN \& a: !!perl/glob: \& PACKAGE: Shell::Perl::sandbox \& NAME: a \& SCALAR: 2 .Ve .PP This package serves as an environment for the current shell session and :reset can wipe it away. .PP .Vb 1 \& pirl @> :reset \& \& pirl @> \e%Shell::Perl::sandbox:: \& \-\-\- \& BEGIN: !!perl/glob: \& PACKAGE: Shell::Perl::sandbox \& NAME: BEGIN .Ve .SH "TO DO" .IX Header "TO DO" There is a lot to do, as always. Some of the top priority tasks are: .IP "\(bu" 4 Accept multiline statements;. .IP "\(bu" 4 Refactor the code to promote easy customization of features. .SH "SEE ALSO" .IX Header "SEE ALSO" This project is hosted at Google Code: .PP .Vb 1 \& http://code.google.com/p/iperl/ .Ve .PP To know about interactive Perl interpreters, there are two \&\s-1FAQS\s0 contained in perlfaq3 which are good starting points. Those are .PP .Vb 2 \& 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 .Ve .PP An extra list of Perl shells can be found here: .PP .Vb 1 \& http://www.focusresearch.com/gregor/document/psh\-1.1.html#other_perl_shells .Ve .SH "BUGS" .IX Header "BUGS" It is a one-line evaluator by now. .PP 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.) .PP There are some quirks with Term::Readline (at least on Windows). .PP There are more bugs. I am lazy to collect them all and list them now. .PP Please report bugs via \s-1CPAN RT \s0 or . .SH "AUTHORS" .IX Header "AUTHORS" Adriano R. Ferreira, .PP Caio Marcelo, .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (C) 2007X2011 by Adriano R. Ferreira .PP This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself.