From: naquad Date: Fri, 9 Oct 2009 05:04:35 +0000 (+0000) Subject: Added overview for beginners page (lib/Devel/REPL/Overview.pod). X-Git-Tag: v1.003015~53 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit%2FDevel-REPL.git;a=commitdiff_plain;h=a2a19b0aa298b778c59d7d30e56d509725a7da85 Added overview for beginners page (lib/Devel/REPL/Overview.pod). git-svn-id: http://dev.catalyst.perl.org/repos/bast/trunk/Devel-REPL@7772 bd8105ee-0ff8-0310-8827-fb3f25b6796d --- diff --git a/lib/Devel/REPL/Overview.pod b/lib/Devel/REPL/Overview.pod new file mode 100644 index 0000000..cb36a93 --- /dev/null +++ b/lib/Devel/REPL/Overview.pod @@ -0,0 +1,263 @@ +=head1 NAME + +Devel::REPL::Overview - overview of Devel::REPL. + +=head1 DESCRIPTION + +=head2 What is a console? How it can assist you? + + Most modern languages have consoles. Console is an interactive tool +that evaluates your input while you type it. +It gives you several advantages: + +=over 2 + +=item * + +Quickly test some thought or tricky expression + +=item * + +Run some code bigger than one line without a temporary file + +=item * + +Play around with libraries and modules + +=item * + +You can even call a console in your script and play around in script's context + +=back + + +For Ruby it would be irb, for Python is... python byitself 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 L. + + +=head2 Devel::REPL - the Perl console + + +REPL stands for Read, Evaluate, Print, Loop. +Lets install and try it. + + $ cpan Devel::REPL + +After installation you have a lot of new modules, +but the most interesting things are: + +=over 2 + +=item * + +Devel::REPL + A top level module. + +=item * + +re.pl + Wrapper script, running console. + +=back + +And a bunch of plugins (I'll describe them later). +In command line type: + + $ re.pl + +If everything is ok you'll see a prompt (underlined $). +That's it. You can start typing expressions. + +An example session: + + $ 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=>'apple',cart=>['apple','banana']} + $HASH1 = { + apple => 1, + cart => [ + 'apple', + 'banana' + ], + fruit => 'apple' + }; + + $ package MyPackage; # create a package + + $ sub say_hi { # define a sub + + > print "Hi!\n"; + + > } # statement is evaluated only after we've finished typing block. + # See Plugins section. + > __PACKAGE__ + MyPackage + > package main; + + > __PACKAGE_ + main + > MyPackage->say_hi + Hi! + 1 + $ + + +=head2 Control files a.k.a. I don't want to type it every time + +Devel::REPL has control files feature. Control files are +evaluated on session start in the same way as you would +type them manually in console. + +Default control file is located at `$HOME/.re.pl/repl.rc` . + +You can store there any statements you would normally type in. + +I.e. my `$HOME/.re.pl/repl.rc` has next lines: + + use feature 'say'; # to don't write \n all the time + + use Data::Dumper; + + # pretty print data structures + sub pp { print Data::Dumper->Dump([@_]) } + +You can have multiple control files and they can be anywhere in the +file system. To make re.pl use some rc-file other than repl.rc +call it like this: + + $ re.pl --rcfile /path/to/your/rc.file + +If your rc-file is in `$HOME/.re.pl` directory, you can omit path: + + $ re.pl --rcfile rc.file + +If you have rc-file with the same name in current directory +and you don't want to type path, you can: + + $ re.pl --rcfile ./rc.file + +=head2 I want it to bark, fly, jump and swim! or Plugins + +Plugins extend functionality and change behavor of Devel::REPL. +Bundled plugins are: + +=over 2 + +=item * + +Devel::REPL::Plugin::History + No comments. Simply history. + +=item * + +Devel::REPL::Plugin::!LexEnv + Provides a lexical environment for the Devel::REPL. + +=item * + +Devel::REPL::Plugin::DDS + Formats return values with Data::Dump::Streamer module. + +=item * + +Devel::REPL::Plugin::Packages + Keeps track of which package your're in. + +=item * + +Devel::REPL::Plugin::Commands + Generic command creation plugin using injected functions. + +=item * + +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: + + $ sub mysub { + + > print "Hello, World!\n"; ## notice prompt change + + > } + + $ mysub + Hello, World! + 1 + $ + + but this *doesn't* mean you can print sub name or identifier + on several lines. Don't do that! It won't work. + + +=back + +There are lots of contributed plugins you can find at CPAN. + +=head1 Profiles + +If plugins change and extend functionality of Devel::REPL, profiles +are changing your environment (loaded plugins, constants, subs and etc.). + +There's only one bundled profile called `Devel::REPL::Profile::Default`, lets +take a look at it: + + package Devel::REPL::Profile::Default; + + use Moose; ### advanced OOP system for Perl + + ### keep those exports/imports out of our namespace + use namespace::clean -except => [ 'meta' ]; + + with 'Devel::REPL::Profile'; ## 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; + +At the moment there are no profiles on CPAN. Mostly you'll use control files. +To enable some profile use --profile switch: + + $ re.pl --profile SomeProfile + +=head1 See Also + +L, L, L