From: oliver Date: Tue, 6 Jan 2009 23:22:09 +0000 (+0000) Subject: add distro files X-Git-Tag: v1.003015~76 X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=6aa584927ce35a633ee66fd372f3a6c2c23aa447;p=p5sagit%2FDevel-REPL.git add distro files pod fixes remove unecessary deps which are Perl core git-svn-id: http://dev.catalyst.perl.org/repos/bast/trunk/Devel-REPL@5288 bd8105ee-0ff8-0310-8827-fb3f25b6796d --- diff --git a/INSTALL b/INSTALL new file mode 100644 index 0000000..a1dc193 --- /dev/null +++ b/INSTALL @@ -0,0 +1,14 @@ +WHAT IS THIS? + +This is Devel::REPL, an interactive Perl shell. +Please see the README that comes with this distribution. + +HOW DO I INSTALL IT? + +To install this module, cd to the directory that contains this README +file and type the following: + + perl Makefile.PL + make + make test + make install diff --git a/Makefile.PL b/Makefile.PL index 4dddf24..2f8eeec 100644 --- a/Makefile.PL +++ b/Makefile.PL @@ -13,12 +13,9 @@ requires 'MooseX::Getopt' => '0.15'; requires 'MooseX::AttributeHelpers' => '0.14'; requires 'namespace::clean'; requires 'File::HomeDir'; -requires 'File::Spec'; -requires 'Term::ReadLine'; requires 'Lexical::Persistence'; requires 'Data::Dump::Streamer'; requires 'PPI'; -requires 'Term::ANSIColor'; requires 'B::Keywords'; requires 'Task::Weaken'; requires 'App::Nopaste'; diff --git a/README b/README new file mode 100644 index 0000000..3f9861a --- /dev/null +++ b/README @@ -0,0 +1,193 @@ +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 "control+d" or "control+c". + + 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.64 + + * MooseX::Object::Pluggable >= 0.0009 + + * MooseX::Getopt >= 0.15 + + * MooseX::AttributeHelpers >= 0.14 + + * namespace::clean + + * File::HomeDir + + * Lexical::Persistence + + * Data::Dump::Streamer + + * PPI + + * B::Keywords + + * Task::Weaken + + * App::Nopaste + +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 + +LICENSE + This library is free software under the same terms as perl itself + diff --git a/examples/dbic_project_profile.pl b/examples/dbic_project_profile.pl new file mode 100644 index 0000000..8a97348 --- /dev/null +++ b/examples/dbic_project_profile.pl @@ -0,0 +1,16 @@ +# this might live in /path/to/checkout/.re.pl/project.rc +# see: http://chainsawblues.vox.com/library/post/develrepl-part-4---script-options-rc-files-profiles-and-packaging.html + +# load my global ~/.re.pl/repl.rc +Devel::REPL::Script->current->load_rcfile('repl.rc'); + +use lib 'lib'; # to get at the lib/Project.pm, lib/Project/* perl modules +use Project::Schema; # load the DBIC schema + +Project::Schema->connection('dbi:Pg:dbname=project_matthewt_test','matthewt',''); # connect to db +Project::Schema->stacktrace(1); # turn on stack traces for DBI errors + +sub schema { 'Project::Schema' } # shortcut so things like schema->sources works +sub rs { Project::Schema->resultset(shift); } # shortcut so rs('Foo')->find(1); works +sub cols { Project::Schema->source(shift)->columns; } # cols('Foo') returns a column list + diff --git a/lib/Devel/REPL.pm b/lib/Devel/REPL.pm index 7c341de..c7640a4 100644 --- a/lib/Devel/REPL.pm +++ b/lib/Devel/REPL.pm @@ -5,7 +5,7 @@ use Moose; use namespace::clean -except => [ 'meta' ]; use 5.008001; # backwards compat, doesn't warn like 5.8.1 -our $VERSION = '1.002001'; # 1.2.1 +our $VERSION = '1.003000'; # 1.3.0 with 'MooseX::Object::Pluggable'; @@ -180,7 +180,7 @@ message will be returned. Here are a few examples: 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 (C above, you'l have the +If you followed the first example in the L 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. @@ -210,7 +210,7 @@ exported functions from that module are available for immediate use: 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 @@ -322,15 +322,19 @@ the following: =item * -L >= 0.38 +L >= 0.64 + +=item * + +L >= 0.0009 =item * -L >= 0.0007 +L >= 0.15 =item * -L +L >= 0.14 =item * @@ -346,11 +350,11 @@ L =item * -L +L =item * -L +L =item * @@ -384,6 +388,8 @@ Matt S Trout - mst (at) shadowcatsystems.co.uk (L