X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?p=p5sagit%2FDevel-REPL.git;a=blobdiff_plain;f=lib%2FDevel%2FREPL%2FProfile.pm;h=b2e95da9b9a0bc52c9f592bb333627e464a3c289;hp=c5c0c23ea83104f1bc6dd1ed21f6e99aff522da1;hb=796cd7ec80de14e45ca8221d545aceb7b9bc0b71;hpb=4d33251a9f6d375aaafd8aa274743c68dec8f720

diff --git a/lib/Devel/REPL/Profile.pm b/lib/Devel/REPL/Profile.pm
index c5c0c23..b2e95da 100644
--- a/lib/Devel/REPL/Profile.pm
+++ b/lib/Devel/REPL/Profile.pm
@@ -1,8 +1,86 @@
 package Devel::REPL::Profile;
+# ABSTRACT: Code to execute when re.pl starts
 
-use Moose::Role;
-use namespace::clean -except => [ 'meta' ];
+our $VERSION = '1.003027';
 
+use Moose::Role;
 requires 'apply_profile';
+use namespace::autoclean;
 
 1;
+__END__
+
+=pod
+
+=head1 SYNOPSIS
+
+ package Devel::REPL::Profile::MyProject;
+
+ use Moose;
+ use namespace::autoclean;
+
+ with 'Devel::REPL::Profile';
+
+ sub apply_profile {
+     my ($self, $repl) = @_;
+     # do something here
+ }
+
+ 1;
+
+=head1 DESCRIPTION
+
+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 mechanism called I<profiles> exists to let you package and distribute these
+start-up scripts, as Perl modules.
+
+=head1 USAGE
+
+Quite simply, follow the L</"SYNOPSIS"> section above to create a boilerplate
+profile module. Within the C<apply_profile> method, the C<$repl> variable can
+be used to run any commands as the user would, within the context of their
+running C<Devel::REPL> shell instance.
+
+For example, to load a module, you might have something like this:
+
+ sub apply_profile {
+     my ($self, $repl) = @_;
+     $repl->eval('use Carp');
+ }
+
+As you can see, the C<eval> method is used to run any code. The user won't see
+any output from that, and the code can "safely" die without destroying the
+REPL shell. The return value of C<eval> will be the return value of the code
+you gave, or else if it died then a C<Devel::REPL::Error> object is returned.
+
+If you want to load a C<Devel::REPL> plugin, then use the following method:
+
+ $repl->load_plugin('Timing');
+
+The C<load_plugin> and C<eval> methods should cover most of what you would
+want to do before the user has access to the shell. Remember that plugin
+features are immediately available, so you can load for example the C<LexEnv>
+plugin, and then declare C<my> variables which the user will have access to.
+
+=head2 Selecting a Profile
+
+To run the shell with a particular profile, use the following command:
+
+ system$ re.pl --profile MyProject
+
+Alternatively, you can set the environment variable C<DEVEL_REPL_PROFILE> to
+MyProject.
+
+When the profile name is unqualified, as in the above example, the profile is
+assumed to be in the C<Devel::REPL::Profile::> namespace. Otherwise if you
+pass something which contains the C<::> character sequence, it will be loaded
+as-is.
+
+=head1 AUTHOR
+
+Matt S Trout - mst (at) shadowcatsystems.co.uk (L<http://www.shadowcatsystems.co.uk/>)
+
+=cut