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