README.pod

   1 =pod
   2
   3 =encoding UTF-8
   4
   5 =head1 NAME
   6
   7 Devel::REPL - A modern perl interactive shell
   8
   9 =head1 VERSION
  10
  11 version 1.003027
  12
  13 =head1 SYNOPSIS
  14
  15   my $repl = Devel::REPL->new;
  16   $repl->load_plugin($_) for qw(History LexEnv);
  17   $repl->run
  18
  19 Alternatively, use the 're.pl' script installed with the distribution
  20
  21   system$ re.pl
  22
  23 =head1 DESCRIPTION
  24
  25 This is an interactive shell for Perl, commonly known as a REPL - Read,
  26 Evaluate, Print, Loop. The shell provides for rapid development or testing
  27 of code without the need to create a temporary source code file.
  28
  29 Through a plugin system, many features are available on demand. You can also
  30 tailor the environment through the use of profiles and run control files, for
  31 example to pre-load certain Perl modules when working on a particular project.
  32
  33 =head1 USAGE
  34
  35 To start a shell, follow one of the examples in the L</"SYNOPSIS"> above.
  36
  37 Once running, the shell accepts and will attempt to execute any code given. If
  38 the code executes successfully you'll be shown the result, otherwise an error
  39 message will be returned. Here are a few examples:
  40
  41  $_ print "Hello, world!\n"
  42  Hello, world!
  43  1
  44  $_ nosuchfunction
  45  Compile error: Bareword "nosuchfunction" not allowed while "strict subs" in use at (eval 130) line 5.
  46
  47  $_
  48
  49 In the first example above you see the output of the command (C<Hello,
  50 world!>), if any, and then the return value of the statement (C<1>). Following
  51 that example, an error is returned when the execution of some code fails.
  52
  53 Note that the lack of semicolon on the end is not a mistake - the code is
  54 run inside a Block structure (to protect the REPL in case the code blows up),
  55 which means a single statement doesn't require the semicolon. You can add one
  56 if you like, though.
  57
  58 If you followed the first example in the L</"SYNOPSIS"> above, you'll have the
  59 L<History|Devel::REPL::Plugin::History> and L<LexEnv|Devel::REPL::Plugin::LexEnv>
  60 plugins loaded (and there are many more available).
  61 Although the shell might support "up-arrow" history, the History plugin adds
  62 "bang" history to that so you can re-execute chosen commands (with e.g.
  63 C<!53>). The LexEnv plugin ensures that lexical variables declared with the
  64 C<my> keyword will automatically persist between statements executed in the
  65 REPL shell.
  66
  67 When you C<use> any Perl module, the C<import()> will work as expected - the
  68 exported functions from that module are available for immediate use:
  69
  70  $_ carp "I'm dieeeing!\n"
  71  String found where operator expected at (eval 129) line 5, near "carp "I'm dieeeing!\n""
  72          (Do you need to predeclare carp?)
  73  Compile error: syntax error at (eval 129) line 5, near "carp "I'm dieeeing!\n""
  74  BEGIN not safe after errors--compilation aborted at (eval 129) line 5.
  75
  76  $_ use Carp
  77
  78  $_ carp "I'm dieeeing!\n"
  79  I'm dieeeing!
  80   at /usr/share/perl5/Lexical/Persistence.pm line 327
  81  1
  82  $_
  83
  84 To quit from the shell, hit C<Ctrl+D> or C<Ctrl+C>.
  85
  86   MSWin32 NOTE: control keys won't work if TERM=dumb
  87   because readline functionality will be disabled.
  88
  89 =head2 Run Control Files
  90
  91 For particular projects you might well end up running the same commands each
  92 time the REPL shell starts up - loading Perl modules, setting configuration,
  93 and so on. A run control file lets you have this done automatically, and you
  94 can have multiple files for different projects.
  95
  96 By default the C<re.pl> program looks for C<< $HOME/.re.pl/repl.rc >>, and
  97 runs whatever code is in there as if you had entered it at the REPL shell
  98 yourself.
  99
 100 To set a new run control file that's also in that directory, pass it as a
 101 filename like so:
 102
 103  system$ re.pl --rcfile myproject.pc
 104
 105 If the filename happens to contain a forward slash, then it's used absolutely,
 106 or realive to the current working directory:
 107
 108  system$ re.pl --rcfile /path/to/my/project/repl.rc
 109
 110 Within the run control file you might want to load plugins. This is covered in
 111 L</"The REPL shell object"> section, below.
 112
 113 =head2 Profiles
 114
 115 To allow for the sharing of run control files, you can fashion them into a
 116 Perl module for distribution (perhaps via the CPAN). For more information on
 117 this feature, please see the L<Devel::REPL::Profile> manual page.
 118
 119 A C<Standard> profile ships with C<Devel::REPL>; it loads the following plugins
 120 (note that some of these require optional features -- or you can also use the
 121 C<Minimal> profile):
 122
 123 =over 4
 124
 125 =item *
 126
 127 L<Devel::REPL::Plugin::History>
 128
 129 =item *
 130
 131 L<Devel::REPL::Plugin::LexEnv>
 132
 133 =item *
 134
 135 L<Devel::REPL::Plugin::DDS>
 136
 137 =item *
 138
 139 L<Devel::REPL::Plugin::Packages>
 140
 141 =item *
 142
 143 L<Devel::REPL::Plugin::Commands>
 144
 145 =item *
 146
 147 L<Devel::REPL::Plugin::MultiLine::PPI>
 148
 149 =item *
 150
 151 L<Devel::REPL::Plugin::Colors>
 152
 153 =item *
 154
 155 L<Devel::REPL::Plugin::Completion>
 156
 157 =item *
 158
 159 L<Devel::REPL::Plugin::CompletionDriver::INC>
 160
 161 =item *
 162
 163 L<Devel::REPL::Plugin::CompletionDriver::LexEnv>
 164
 165 =item *
 166
 167 L<Devel::REPL::Plugin::CompletionDriver::Keywords>
 168
 169 =item *
 170
 171 L<Devel::REPL::Plugin::CompletionDriver::Methods>
 172
 173 =item *
 174
 175 L<Devel::REPL::Plugin::ReadlineHistory>
 176
 177 =back
 178
 179 =head2 Plugins
 180
 181 Plugins are a way to add functionality to the REPL shell, and take advantage of
 182 C<Devel::REPL> being based on the L<Moose> object system for Perl 5. This
 183 means it's simple to 'hook into' many steps of the R-E-P-L process. Plugins
 184 can change the way commands are interpreted, or the way their results are
 185 output, or even add commands to the shell environment.
 186
 187 A number of plugins ship with C<Devel::REPL>, and more are available on the
 188 CPAN. Some of the shipped plugins are loaded in the default profile, mentioned
 189 above.  These plugins can be loaded in your F< $HOME/.re.pl/repl.rc > like:
 190
 191   load_plugin qw( CompletionDriver::Global DumpHistory );
 192
 193 Writing your own plugins is not difficult, and is discussed in the
 194 L<Devel::REPL::Plugin> manual page, along with links to the manual pages of
 195 all the plugins shipped with C<Devel::REPL>.
 196
 197 =head2 The REPL shell object
 198
 199 From time to time you'll want to interact with or manipulate the
 200 C<Devel::REPL> shell object itself; that is, the instance of the shell you're
 201 currently running.
 202
 203 The object is always available through the C<$_REPL> variable. One common
 204 requirement is to load an additional plugin, after your profile and run
 205 control files have already been executed:
 206
 207  $_ $_REPL->load_plugin('Timing');
 208  1
 209  $_ print "Hello again, world!\n"
 210  Hello again, world!
 211  Took 0.00148296356201172 seconds.
 212  1
 213  $_
 214
 215 =head1 OPTIONAL FEATURES
 216
 217 In addition to the prerequisites declared in this distribution, which should be automatically installed by your L<CPAN> client, there are a number of optional features, used by
 218 additional plugins. You can install any of these features by installing this
 219 distribution interactively (e.g. C<cpanm --interactive Devel::REPL>).
 220
 221 =for comment I hope to automatically generate this data via a Pod::Weaver section
 222
 223 =over 4
 224
 225 =item *
 226
 227 Completion plugin - extensible tab completion
 228
 229 =item *
 230
 231 DDS plugin - better format results with Data::Dump::Streamer
 232
 233 =item *
 234
 235 DDC plugin - even better format results with Data::Dumper::Concise
 236
 237 =item *
 238
 239 INC completion driver - tab complete module names in use and require
 240
 241 =item *
 242
 243 Interrupt plugin - traps SIGINT to kill long-running lines
 244
 245 =item *
 246
 247 Keywords completion driver - tab complete Perl keywords and operators
 248
 249 =item *
 250
 251 LexEnv plugin - variables declared with "my" persist between statements
 252
 253 =item *
 254
 255 MultiLine::PPI plugin - continue reading lines until all blocks are closed
 256
 257 =item *
 258
 259 Nopaste plugin - upload a session\'s input and output to a Pastebin
 260
 261 =item *
 262
 263 PPI plugin - PPI dumping of Perl code
 264
 265 =item *
 266
 267 Refresh plugin - automatically reload libraries with Module::Refresh
 268
 269 =back
 270
 271 =head1 AUTHOR
 272
 273 Matt S Trout - mst (at) shadowcatsystems.co.uk (L<http://www.shadowcatsystems.co.uk/>)
 274
 275 =head1 CONTRIBUTORS
 276
 277 =for stopwords Karen Etheridge Shawn M Moore Chris Marshall Matt S Trout Oliver Gorwits יובל קוג'מן (Yuval Kogman) Arthur Axel 'fREW' Schmidt Andrew Alexis Sukrieh Tomas Doran (t0m) epitaph Norbert Buchmuller Jesse Luehrs Dave Houston Dagfinn Ilmari Mannsåker Zakariyya Mughal Ryan Niebur Justin Hunter Ash Berlin naquad Stevan Little
 278
 279 =over 4
 280
 281 =item *
 282
 283 Karen Etheridge <ether@cpan.org>
 284
 285 =item *
 286
 287 Shawn M Moore <code@sartak.org>
 288
 289 =item *
 290
 291 Chris Marshall <devel.chm.01@gmail.com>
 292
 293 =item *
 294
 295 Matt S Trout <mst@shadowcat.co.uk>
 296
 297 =item *
 298
 299 Oliver Gorwits <oliver@cpan.org>
 300
 301 =item *
 302
 303 יובל קוג'מן (Yuval Kogman) <nothingmuch@woobling.org>
 304
 305 =item *
 306
 307 Arthur Axel 'fREW' Schmidt <frioux@gmail.com>
 308
 309 =item *
 310
 311 Andrew Moore <amoore@cpan.org>
 312
 313 =item *
 314
 315 Alexis Sukrieh <sukria+perl@sukria.net>
 316
 317 =item *
 318
 319 Tomas Doran (t0m) <bobtfish@bobtfish.net>
 320
 321 =item *
 322
 323 epitaph <unknown>
 324
 325 =item *
 326
 327 Norbert Buchmuller <norbi@nix.hu>
 328
 329 =item *
 330
 331 Jesse Luehrs <doy@tozt.net>
 332
 333 =item *
 334
 335 Dave Houston <dhouston@cpan.org>
 336
 337 =item *
 338
 339 Dagfinn Ilmari Mannsåker <ilmari@ilmari.org>
 340
 341 =item *
 342
 343 Zakariyya Mughal <zaki.mughal@gmail.com>
 344
 345 =item *
 346
 347 Ryan Niebur <ryan@debian.org>
 348
 349 =item *
 350
 351 Justin Hunter <justin.d.hunter@gmail.com>
 352
 353 =item *
 354
 355 Ash Berlin <ash_github@firemirror.com>
 356
 357 =item *
 358
 359 naquad <naquad@bd8105ee-0ff8-0310-8827-fb3f25b6796d>
 360
 361 =item *
 362
 363 Stevan Little <stevan.little@iinteractive.com>
 364
 365 =back
 366
 367 =head1 COPYRIGHT AND LICENSE
 368
 369 This software is copyright (c) 2007 by Matt S Trout - mst (at) shadowcatsystems.co.uk (L<http://www.shadowcatsystems.co.uk/>).
 370
 371 This is free software; you can redistribute it and/or modify it under
 372 the same terms as the Perl 5 programming language system itself.
 373
 374 =cut