lib/Devel/REPL/Profile.pm

   1 package Devel::REPL::Profile;
   2
   3 our $VERSION = '1.003027';
   4
   5 use Moose::Role;
   6 requires 'apply_profile';
   7 use namespace::autoclean;
   8
   9 =head1 NAME
  10
  11 Devel::REPL::Profile - code to execute when re.pl starts
  12
  13 =head1 SYNOPSIS
  14
  15  package Devel::REPL::Profile::MyProject;
  16
  17  use Moose;
  18  use namespace::autoclean;
  19
  20  with 'Devel::REPL::Profile';
  21
  22  sub apply_profile {
  23      my ($self, $repl) = @_;
  24      # do something here
  25  }
  26
  27  1;
  28
  29 =head1 DESCRIPTION
  30
  31 For particular projects you might well end up running the same commands each
  32 time the REPL shell starts up - loading Perl modules, setting configuration,
  33 and so on.
  34
  35 A mechanism called I<profiles> exists to let you package and distribute these
  36 start-up scripts, as Perl modules.
  37
  38 =head1 USAGE
  39
  40 Quite simply, follow the L</"SYNOPSIS"> section above to create a boilerplate
  41 profile module. Within the C<apply_profile> method, the C<$repl> variable can
  42 be used to run any commands as the user would, within the context of their
  43 running C<Devel::REPL> shell instance.
  44
  45 For example, to load a module, you might have something like this:
  46
  47  sub apply_profile {
  48      my ($self, $repl) = @_;
  49      $repl->eval('use Carp');
  50  }
  51
  52 As you can see, the C<eval> method is used to run any code. The user won't see
  53 any output from that, and the code can "safely" die without destroying the
  54 REPL shell. The return value of C<eval> will be the return value of the code
  55 you gave, or else if it died then a C<Devel::REPL::Error> object is returned.
  56
  57 If you want to load a C<Devel::REPL> plugin, then use the following method:
  58
  59  $repl->load_plugin('Timing');
  60
  61 The C<load_plugin> and C<eval> methods should cover most of what you would
  62 want to do before the user has access to the shell. Remember that plugin
  63 features are immediately available, so you can load for example the C<LexEnv>
  64 plugin, and then declare C<my> variables which the user will have access to.
  65
  66 =head2 Selecting a Profile
  67
  68 To run the shell with a particular profile, use the following command:
  69
  70  system$ re.pl --profile MyProject
  71
  72 Alternatively, you can set the environment variable C<DEVEL_REPL_PROFILE> to
  73 MyProject.
  74
  75 When the profile name is unqualified, as in the above example, the profile is
  76 assumed to be in the C<Devel::REPL::Profile::> namespace. Otherwise if you
  77 pass something which contains the C<::> character sequence, it will be loaded
  78 as-is.
  79
  80 =head1 AUTHOR
  81
  82 Matt S Trout - mst (at) shadowcatsystems.co.uk (L<http://www.shadowcatsystems.co.uk/>)
  83
  84 =head1 LICENSE
  85
  86 This library is free software under the same terms as perl itself
  87
  88 =cut
  89
  90 1;