lib/Devel/REPL/Overview.pod

   1 =head1 NAME
   2
   3 Devel::REPL::Overview - overview of Devel::REPL.
   4
   5 =head1 DESCRIPTION
   6
   7 =head2 What is a console? How it can assist you?
   8
   9 Most modern languages have consoles. The console is an interactive tool
  10 that evaluates your input while you type it.
  11 It gives you several advantages:
  12
  13 =over 2
  14
  15 =item *
  16
  17 Quickly test some thought or tricky expression
  18
  19 =item *
  20
  21 Run some code bigger than one line without a temporary file
  22
  23 =item *
  24
  25 Play around with libraries and modules
  26
  27 =item *
  28
  29 You can even call a console in your script and play around in script's context
  30
  31 =back
  32
  33 For Ruby it would be irb, for Python is... python by itself and for perl...
  34 and there was nothing for perl (except that ugly perl -d -e "" and several
  35 failed projects) until L<Devel::REPL> was written by Matt S Trout (a.k.a. mst)
  36 from ShadowCatSystems L<http://www.shadowcatsystems.co.uk>.
  37
  38 =head2 Devel::REPL - the Perl console
  39
  40 REPL stands for Read, Evaluate, Print, Loop.
  41 Lets install and try it.
  42
  43        $ cpan Devel::REPL
  44
  45 After installation you have a lot of new modules,
  46 but the most interesting things are:
  47
  48 =over 2
  49
  50 =item *
  51
  52 Devel::REPL
  53   A top level module.
  54
  55 =item *
  56
  57 re.pl
  58   Wrapper script, running console.
  59
  60 =back
  61
  62 And a bunch of plugins (I'll describe them later).
  63 In command line type:
  64
  65       $ re.pl
  66
  67 If everything is ok you'll see a prompt (underlined $).
  68 That's it. You can start typing expressions.
  69
  70 An example session:
  71
  72   $ sub factorial {
  73
  74   > my $number = shift;
  75
  76   > return $number > 1 ? $number * factorial($number-1) : $number;
  77
  78   > }
  79
  80   $ factorial 1 # by the way, comments are allowed
  81
  82   1 # our return value
  83
  84   $ factorial 5
  85
  86   120
  87
  88   $ [1,2,3,4,5,6,7]
  89   $ARRAY1 = [
  90               1,
  91               2,
  92               3, # return values are printed with Data::Dumper::Streamer.
  93               4, # See Plugins section
  94               5,
  95               6,
  96               7
  97             ];
  98
  99   $ {apple=>1,fruit=>'apple',cart=>['apple','banana']}
 100   $HASH1 = {
 101             apple => 1,
 102             cart  => [
 103                       'apple',
 104                       'banana'
 105             ],
 106             fruit => 'apple'
 107   };
 108
 109   $ package MyPackage; # create a package
 110
 111   $ sub say_hi { # define a sub
 112
 113   > print "Hi!\n";
 114
 115   > } # statement is evaluated only after we've finished typing block.
 116       # See Plugins section.
 117   > __PACKAGE__
 118   MyPackage
 119   > package main;
 120
 121   > __PACKAGE_
 122   main
 123   > MyPackage->say_hi
 124   Hi!
 125   1
 126   $
 127
 128
 129 =head2 Control files a.k.a. I don't want to type it every time
 130
 131 L<Devel::REPL> has a control files feature. Control files are
 132 evaluated on session start in the same way as you would
 133 type them manually in the console.
 134
 135 The default control file is located at F<$HOME/.re.pl/repl.rc>.
 136
 137 You can store there any statements you would normally type in.
 138
 139 I.e. my F<$HOME/.re.pl/repl.rc> has next lines:
 140
 141       use feature 'say'; # to don't write \n all the time
 142
 143       use Data::Dumper;
 144
 145       # pretty print data structures
 146       sub pp { print Data::Dumper->Dump([@_]) }
 147
 148 You can have multiple control files and they can be anywhere in the
 149 file system. To make F<re.pl> use some rc-file other than F<repl.rc>,
 150 call it like this:
 151
 152       $ re.pl --rcfile /path/to/your/rc.file
 153
 154 If your rc-file is in F<$HOME/.re.pl> directory, you can omit the path:
 155
 156       $ re.pl --rcfile rc.file
 157
 158 If you have rc-file with the same name in current directory
 159 and you don't want to type path, you can:
 160
 161       $ re.pl --rcfile ./rc.file
 162
 163 =head2 I want it to bark, fly, jump and swim! or Plugins
 164
 165 Plugins extend functionality and change behavior of Devel::REPL.
 166 Bundled plugins are:
 167
 168 =over 2
 169
 170 =item *
 171
 172 L<Devel::REPL::Plugin::History>
 173   No comments. Simply history.
 174
 175 =item *
 176
 177 L<Devel::REPL::Plugin::!LexEnv>
 178   Provides a lexical environment for the Devel::REPL.
 179
 180 =item *
 181
 182 L<Devel::REPL::Plugin::DDS>
 183   Formats return values with Data::Dump::Streamer module.
 184
 185 =item *
 186
 187 L<Devel::REPL::Plugin::Packages>
 188   Keeps track of which package your're in.
 189
 190 =item *
 191
 192 L<Devel::REPL::Plugin::Commands>
 193   Generic command creation plugin using injected functions.
 194
 195 =item *
 196
 197 L<Devel::REPL::Plugin::MultiLine::PPI>
 198   Makes Devel::REPL read your input until your block
 199   is finished. What does this means: you can type a part of a block
 200   on one line and second part on another:
 201
 202        $ sub mysub {
 203
 204        > print "Hello, World!\n"; ## notice prompt change
 205
 206        > }
 207
 208        $ mysub
 209        Hello, World!
 210        1
 211        $
 212
 213   but this *doesn't* mean you can print sub name or identifier
 214   on several lines. Don't do that! It won't work.
 215
 216 =back
 217
 218 There are lots of contributed plugins you can find at CPAN.
 219
 220 =head1 Profiles
 221
 222 If plugins change and extend functionality of L<Devel::REPL>, profiles
 223 are changing your environment (loaded plugins, constants, subs and etc.).
 224
 225 For example, the Minimal profile, L<Devel::REPL::Profile::Minimal>:
 226
 227       package Devel::REPL::Profile::Minimal;
 228
 229       use Moose; ### advanced OOP system for Perl
 230
 231       ### keep those exports/imports out of our namespace
 232       use namespace::autoclean;
 233
 234       with 'Devel::REPL::Profile';  ## seem perldoc Muse
 235
 236       sub plugins { ### plugins we want to be loaded
 237         qw(History LexEnv DDS Packages Commands MultiLine::PPI);
 238       }
 239
 240       ### the only required sub for profile,
 241       ### it is called on profile activation
 242       sub apply_profile {
 243         my ($self, $repl) = @_;
 244         ### $self - no comments, $repl - current instance of Devel::REPL
 245
 246         $repl->load_plugin($_) for $self->plugins; ### load our plugins
 247       }
 248
 249       1;
 250
 251 There is also the L<StandardDevel::REPL::Profile::Standard> profile, which contains a number of optional (yet
 252 very useful) features.
 253
 254 To enable some profile use the C<--profile> switch:
 255
 256       $ re.pl --profile SomeProfile
 257
 258 Alternatively, you can set the environment variable C<DEVEL_REPL_PROFILE> to
 259 C<SomeProfile>, or set the C<profile> key in your C<rcfile> (see
 260 L<Devel::REPL> for more information).
 261
 262 =head1 SEE ALSO
 263
 264 =over 2
 265
 266 =item *
 267
 268 L<Devel::REPL>
 269
 270 =item *
 271
 272 L<Devel::REPL::Plugin>
 273
 274 =item *
 275
 276 L<Devel::REPL::Profile>
 277
 278 =back
 279
 280 =cut