.\" Automatically generated by Pod::Man 2.28 (Pod::Simple 3.29)
.\"
.\" 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
.\" ========================================================================
.\"
.IX Title "Devel::REPL::Overview 3pm"
.TH Devel::REPL::Overview 3pm "2016-02-16" "perl v5.22.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"
Devel::REPL::Overview \- overview of Devel::REPL.
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
.SS "What is a console? How it can assist you?"
.IX Subsection "What is a console? How it can assist you?"
Most modern languages have consoles. The console is an interactive tool
that evaluates your input while you type it.
It gives you several advantages:
.IP "\(bu" 2
Quickly test some thought or tricky expression
.IP "\(bu" 2
Run some code bigger than one line without a temporary file
.IP "\(bu" 2
Play around with libraries and modules
.IP "\(bu" 2
You can even call a console in your script and play around in script's context
.PP
For Ruby it would be irb, for Python is... python by itself and for perl...
and there was nothing for perl (except that ugly perl \-d \-e "" and several
failed projects) until Devel::REPL was written by Matt S Trout (a.k.a. mst)
from ShadowCatSystems <http://www.shadowcatsystems.co.uk>.
.SS "Devel::REPL \- the Perl console"
.IX Subsection "Devel::REPL - the Perl console"
\&\s-1REPL\s0 stands for Read, Evaluate, Print, Loop.
Lets install and try it.
.PP
.Vb 1
\&       $ cpan Devel::REPL
.Ve
.PP
After installation you have a lot of new modules,
but the most interesting things are:
.IP "\(bu" 2
Devel::REPL
  A top level module.
.IP "\(bu" 2
re.pl
  Wrapper script, running console.
.PP
And a bunch of plugins (I'll describe them later).
In command line type:
.PP
.Vb 1
\&      $ re.pl
.Ve
.PP
If everything is ok you'll see a prompt (underlined $).
That's it. You can start typing expressions.
.PP
An example session:
.PP
.Vb 1
\&  $ sub factorial {
\&
\&  > my $number = shift;
\&
\&  > return $number > 1 ? $number * factorial($number\-1) : $number;
\&
\&  > }
\&
\&  $ factorial 1 # by the way, comments are allowed
\&
\&  1 # our return value
\&
\&  $ factorial 5
\&
\&  120
\&
\&  $ [1,2,3,4,5,6,7]
\&  $ARRAY1 = [
\&              1,
\&              2,
\&              3, # return values are printed with Data::Dumper::Streamer.
\&              4, # See Plugins section
\&              5,
\&              6,
\&              7
\&            ];
\&
\&  $ {apple=>1,fruit=>\*(Aqapple\*(Aq,cart=>[\*(Aqapple\*(Aq,\*(Aqbanana\*(Aq]}
\&  $HASH1 = {
\&            apple => 1,
\&            cart  => [
\&                      \*(Aqapple\*(Aq,
\&                      \*(Aqbanana\*(Aq
\&            ],
\&            fruit => \*(Aqapple\*(Aq
\&  };
\&
\&  $ package MyPackage; # create a package
\&
\&  $ sub say_hi { # define a sub
\&
\&  > print "Hi!\en";
\&
\&  > } # statement is evaluated only after we\*(Aqve finished typing block.
\&      # See Plugins section.
\&  > _\|_PACKAGE_\|_
\&  MyPackage
\&  > package main;
\&
\&  > _\|_PACKAGE_
\&  main
\&  > MyPackage\->say_hi
\&  Hi!
\&  1
\&  $
.Ve
.SS "Control files a.k.a. I don't want to type it every time"
.IX Subsection "Control files a.k.a. I don't want to type it every time"
Devel::REPL has a control files feature. Control files are
evaluated on session start in the same way as you would
type them manually in the console.
.PP
The default control file is located at \fI\f(CI$HOME\fI/.re.pl/repl.rc\fR.
.PP
You can store there any statements you would normally type in.
.PP
I.e. my \fI\f(CI$HOME\fI/.re.pl/repl.rc\fR has next lines:
.PP
.Vb 1
\&      use feature \*(Aqsay\*(Aq; # to don\*(Aqt write \en all the time
\&
\&      use Data::Dumper;
\&
\&      # pretty print data structures
\&      sub pp { print Data::Dumper\->Dump([@_]) }
.Ve
.PP
You can have multiple control files and they can be anywhere in the
file system. To make \fIre.pl\fR use some rc-file other than \fIrepl.rc\fR,
call it like this:
.PP
.Vb 1
\&      $ re.pl \-\-rcfile /path/to/your/rc.file
.Ve
.PP
If your rc-file is in \fI\f(CI$HOME\fI/.re.pl\fR directory, you can omit the path:
.PP
.Vb 1
\&      $ re.pl \-\-rcfile rc.file
.Ve
.PP
If you have rc-file with the same name in current directory
and you don't want to type path, you can:
.PP
.Vb 1
\&      $ re.pl \-\-rcfile ./rc.file
.Ve
.SS "I want it to bark, fly, jump and swim! or Plugins"
.IX Subsection "I want it to bark, fly, jump and swim! or Plugins"
Plugins extend functionality and change behavior of Devel::REPL.
Bundled plugins are:
.IP "\(bu" 2
Devel::REPL::Plugin::History
  No comments. Simply history.
.IP "\(bu" 2
Devel::REPL::Plugin::!LexEnv
  Provides a lexical environment for the Devel::REPL.
.IP "\(bu" 2
Devel::REPL::Plugin::DDS
  Formats return values with Data::Dump::Streamer module.
.IP "\(bu" 2
Devel::REPL::Plugin::Packages
  Keeps track of which package your're in.
.IP "\(bu" 2
Devel::REPL::Plugin::Commands
  Generic command creation plugin using injected functions.
.IP "\(bu" 2
Devel::REPL::Plugin::MultiLine::PPI
  Makes Devel::REPL read your input until your block
  is finished. What does this means: you can type a part of a block
  on one line and second part on another:
.Sp
.Vb 1
\&       $ sub mysub {
\&
\&       > print "Hello, World!\en"; ## notice prompt change
\&
\&       > }
\&
\&       $ mysub
\&       Hello, World!
\&       1
\&       $
\&
\&  but this *doesn\*(Aqt* mean you can print sub name or identifier
\&  on several lines. Don\*(Aqt do that! It won\*(Aqt work.
.Ve
.PP
There are lots of contributed plugins you can find at \s-1CPAN.\s0
.SH "Profiles"
.IX Header "Profiles"
If plugins change and extend functionality of Devel::REPL, profiles
are changing your environment (loaded plugins, constants, subs and etc.).
.PP
For example, the Minimal profile, Devel::REPL::Profile::Minimal:
.PP
.Vb 1
\&      package Devel::REPL::Profile::Minimal;
\&
\&      use Moose; ### advanced OOP system for Perl
\&
\&      ### keep those exports/imports out of our namespace
\&      use namespace::autoclean;
\&
\&      with \*(AqDevel::REPL::Profile\*(Aq;  ## seem perldoc Muse
\&
\&      sub plugins { ### plugins we want to be loaded
\&        qw(History LexEnv DDS Packages Commands MultiLine::PPI);
\&      }
\&
\&      ### the only required sub for profile,
\&      ### it is called on profile activation
\&      sub apply_profile {
\&        my ($self, $repl) = @_;
\&        ### $self \- no comments, $repl \- current instance of Devel::REPL
\&
\&        $repl\->load_plugin($_) for $self\->plugins; ### load our plugins
\&      }
\&
\&      1;
.Ve
.PP
There is also the StandardDevel::REPL::Profile::Standard profile, which contains a number of optional (yet
very useful) features.
.PP
To enable some profile use the \f(CW\*(C`\-\-profile\*(C'\fR switch:
.PP
.Vb 1
\&      $ re.pl \-\-profile SomeProfile
.Ve
.PP
Alternatively, you can set the environment variable \f(CW\*(C`DEVEL_REPL_PROFILE\*(C'\fR to
\&\f(CW\*(C`SomeProfile\*(C'\fR, or set the \f(CW\*(C`profile\*(C'\fR key in your \f(CW\*(C`rcfile\*(C'\fR (see
Devel::REPL for more information).
.SH "SEE ALSO"
.IX Header "SEE ALSO"