X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit%2FDevel-REPL.git;a=blobdiff_plain;f=README;fp=README;h=0000000000000000000000000000000000000000;hp=3853e94a11bd49b64906522994382c13e07fc57c;hb=dd8f3018946d8159e928f7eca7a1ff36e8f3f2d0;hpb=f049111ed91d199e926de686b2a6f179a89cba18 diff --git a/README b/README deleted file mode 100644 index 3853e94..0000000 --- a/README +++ /dev/null @@ -1,217 +0,0 @@ -NAME - Devel::REPL - a modern perl interactive shell - -SYNOPSIS - my $repl = Devel::REPL->new; - $repl->load_plugin($_) for qw(History LexEnv); - $repl->run - - Alternatively, use the 're.pl' script installed with the distribution - - system$ re.pl - -DESCRIPTION - This is an interactive shell for Perl, commonly known as a REPL - Read, - Evaluate, Print, Loop. The shell provides for rapid development or - testing of code without the need to create a temporary source code file. - - Through a plugin system, many features are available on demand. You can - also tailor the environment through the use of profiles and run control - files, for example to pre-load certain Perl modules when working on a - particular project. - -USAGE - To start a shell, follow one of the examples in the "SYNOPSIS" above. - - Once running, the shell accepts and will attempt to execute any code - given. If the code executes successfully you'll be shown the result, - otherwise an error message will be returned. Here are a few examples: - - $_ print "Hello, world!\n" - Hello, world! - 1 - $_ nosuchfunction - Compile error: Bareword "nosuchfunction" not allowed while "strict subs" in use at (eval 130) line 5. - - $_ - - In the first example above you see the output of the command ("Hello, - world!"), if any, and then the return value of the statement (1). - Following that example, an error is returned when the execution of some - code fails. - - Note that the lack of semicolon on the end is not a mistake - the code - is run inside a Block structure (to protect the REPL in case the code - blows up), which means a single statement doesn't require the semicolon. - You can add one if you like, though. - - If you followed the first example in the "SYNOPSIS" above, you'll have - the History and LexEnv plugins loaded (and there are many more - available). Although the shell might support "up-arrow" history, the - History plugin adds "bang" history to that so you can re-execute chosen - commands (with e.g. "!53"). The LexEnv plugin ensures that lexical - variables declared with the "my" keyword will automatically persist - between statements executed in the REPL shell. - - When you "use" any Perl module, the "import()" will work as expected - - the exported functions from that module are available for immediate use: - - $_ carp "I'm dieeeing!\n" - String found where operator expected at (eval 129) line 5, near "carp "I'm dieeeing!\n"" - (Do you need to predeclare carp?) - Compile error: syntax error at (eval 129) line 5, near "carp "I'm dieeeing!\n"" - BEGIN not safe after errors--compilation aborted at (eval 129) line 5. - - $_ use Carp - - $_ carp "I'm dieeeing!\n" - I'm dieeeing! - at /usr/share/perl5/Lexical/Persistence.pm line 327 - 1 - $_ - - To quit from the shell, hit "Ctrl+D" or "Ctrl+C". - - MSWin32 NOTE: control keys won't work if TERM=dumb - because readline functionality will be disabled. - - Run Control Files - For particular projects you might well end up running the same commands - each time the REPL shell starts up - loading Perl modules, setting - configuration, and so on. A run control file lets you have this done - automatically, and you can have multiple files for different projects. - - By default the "re.pl" program looks for "$HOME/.re.pl/repl.rc", and - runs whatever code is in there as if you had entered it at the REPL - shell yourself. - - To set a new run control file that's also in that directory, pass it as - a filename like so: - - system$ re.pl --rcfile myproject.pc - - If the filename happens to contain a forwardslash, then it's used - absolutely, or realive to the current working directory: - - system$ re.pl --rcfile /path/to/my/project/repl.rc - - Within the run control file you might want to load plugins. This is - covered in "The REPL shell object" section, below. - - Profiles - To allow for the sharing of run control files, you can fashion them into - a Perl module for distribution (perhaps via the CPAN). For more - information on this feature, please see the Devel::REPL::Profile manual - page. - - A default profile ships with "Devel::REPL"; it loads the following - plugins: - - * Devel::REPL::Plugin::History - - * Devel::REPL::Plugin::LexEnv - - * Devel::REPL::Plugin::DDS - - * Devel::REPL::Plugin::Packages - - * Devel::REPL::Plugin::Commands - - * Devel::REPL::Plugin::MultiLine::PPI - - Plugins - Plugins are a way to add funcionality to the REPL shell, and take - advantage of "Devel::REPL" being based on the Moose object system for - Perl 5. This means it's simple to 'hook into' many steps of the R-E-P-L - process. Plugins can change the way commands are interpreted, or the way - their results are output, or even add commands to the shell environment. - - A number of plugins ship with "Devel::REPL", and more are available on - the CPAN. Some of the shipped plugins are loaded in the default profile, - mentioned above. - - Writing your own plugins is not difficult, and is discussed in the - Devel::REPL::Plugin manual page, along with links to the manual pages of - all the plugins shipped with "Devel::REPL". - - The REPL shell object - From time to time you'll want to interact with or manipulate the - "Devel::REPL" shell object itself; that is, the instance of the shell - you're currently running. - - The object is always available through the $_REPL variable. One common - requirement is to load an additional plugin, after your profile and run - control files have already been executed: - - $_ $_REPL->load_plugin('Timing'); - 1 - $_ print "Hello again, world!\n" - Hello again, world! - Took 0.00148296356201172 seconds. - 1 - $_ - -REQUIREMENTS - In addition to the contents of the standard Perl distribution, you will - need the following: - - * Moose >= 0.74 - - * MooseX::Object::Pluggable >= 0.0009 - - * MooseX::Getopt >= 0.18 - - * MooseX::AttributeHelpers >= 0.16 - - * namespace::clean - - * File::HomeDir - - * Task::Weaken - - * B::Concise - - * Term::ANSIColor - - * Devel::Peek - - Optionally, some plugins if installed will require the following - modules: - - * PPI - - * Data::Dump::Streamer - - * Data::Dumper::Concise - - * File::Next - - * Sys::SigAction - - * B::Keywords - - * Lexical::Persistence - - * App::Nopaste - - * Module::Refresh - -AUTHOR - Matt S Trout - mst (at) shadowcatsystems.co.uk - () - -CONTRIBUTORS - Stevan Little - stevan (at) iinteractive.com - Alexis Sukrieh - sukria+perl (at) sukria.net - epitaph - mgrimes - mgrimes (at) cpan dot org - Shawn M Moore - sartak (at) gmail.com - Oliver Gorwits - oliver on irc.perl.org - Andrew Moore - "" - Norbert Buchmuller "" - Dave Houston "" - Chris Marshall - -LICENSE - This library is free software under the same terms as perl itself -