.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" 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 >0, 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 .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" ======================================================================== .\" .IX Title "Shell::Perl 3pm" .TH Shell::Perl 3pm "2017-01-21" "perl v5.24.1" "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 ":set perl_version" 4 .IX Item ":set perl_version" Changes the perl version (and current feature bundle) used to evaluate each statement. Usage examples are: .Sp .Vb 3 \& :set perl_version 5.008 \& :set perl_version v5.10 \& :set perl_version # current perl version, $] .Ve .Sp Default is to use the current perl version, which works like \f(CW\*(C`eval "use $];"\*(C'\fR. .Sp Set to an empty string, as in .Sp .Vb 1 \& :set perl_version \*(Aq\*(Aq .Ve .Sp for the behavior of pirl 0.0023 or earlier. .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\->run_with_args\*(C'\fR 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_perl_version\fR" 4 .IX Item "set_perl_version" .Vb 1 \& $sh\->set_perl_version($version); .Ve .Sp Changes perl version used to evaluate statements. .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 "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 Github . .SH "SEE ALSO" .IX Header "SEE ALSO" This project is hosted at Github: .PP .Vb 1 \& https://github.com/aferreira/pirl .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 Also: .IP "\(bu" 4 Devel::REPL .IP "\(bu" 4 Reply .IP "\(bu" 4 A comparison of various REPLs .SH "AUTHORS" .IX Header "AUTHORS" Adriano R. Ferreira, .PP Caio Marcelo, .PP Ron Savage, .SH "COPYRIGHT AND LICENSE" .IX Header "COPYRIGHT AND LICENSE" Copyright (C) 2007–2017 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.