changes for my recent patches
[p5sagit/Devel-REPL.git] / lib / Devel / REPL / Overview.pod
1 =head1 NAME
2
3 Devel::REPL::Overview - overview of Devel::REPL.
4
5 =head1 DESCRIPTION
6
7 =head2 What is a console? How it can assist you?
8
9   Most modern languages have consoles. Console is an interactive tool
10 that evaluates your input while you type it.
11 It gives you several advantages:
12
13 =over 2
14
15 =item *
16
17 Quickly test some thought or tricky expression
18
19 =item *
20
21 Run some code bigger than one line without a temporary file
22
23 =item *
24
25 Play around with libraries and modules
26
27 =item *
28
29 You can even call a console in your script and play around in script's context
30
31 =back
32
33
34 For Ruby it would be irb, for Python is... python byitself and for perl...
35 and there was nothing for perl (except that ugly perl -d -e "" and several
36 failed projects) until Devel::REPL was written by Matt S Trout (a.k.a. mst)
37 from ShadowCatSystems L<http://www.shadowcatsystems.co.uk>.
38
39
40 =head2 Devel::REPL - the Perl console
41
42
43 REPL stands for Read, Evaluate, Print, Loop.
44 Lets install and try it.
45
46        $ cpan Devel::REPL
47
48 After installation you have a lot of new modules,
49 but the most interesting things are:
50
51 =over 2
52
53 =item *
54
55 Devel::REPL
56   A top level module.
57
58 =item *
59
60 re.pl
61   Wrapper script, running console.
62
63 =back
64
65 And a bunch of plugins (I'll describe them later).
66 In command line type:
67
68       $ re.pl
69
70 If everything is ok you'll see a prompt (underlined $).
71 That's it. You can start typing expressions.
72
73 An example session:
74
75   $ sub factorial {
76
77   > my $number = shift;
78
79   > return $number > 1 ? $number * factorial($number-1) : $number;
80
81   > }
82
83   $ factorial 1 # by the way, comments are allowed
84
85   1 # our return value
86
87   $ factorial 5
88
89   120
90
91   $ [1,2,3,4,5,6,7]
92   $ARRAY1 = [
93               1,
94               2,
95               3, # return values are printed with Data::Dumper::Streamer.
96               4, # See Plugins section
97               5,
98               6,
99               7
100             ];
101
102   $ {apple=>1,fruit=>'apple',cart=>['apple','banana']}
103   $HASH1 = {
104             apple => 1,
105             cart  => [
106                       'apple',
107                       'banana'
108             ],
109             fruit => 'apple'
110   };
111
112   $ package MyPackage; # create a package
113
114   $ sub say_hi { # define a sub
115
116   > print "Hi!\n";
117
118   > } # statement is evaluated only after we've finished typing block.
119       # See Plugins section.
120   > __PACKAGE__
121   MyPackage
122   > package main;
123
124   > __PACKAGE_
125   main
126   > MyPackage->say_hi
127   Hi!
128   1
129   $
130
131
132 =head2 Control files a.k.a. I don't want to type it every time
133
134 Devel::REPL has control files feature. Control files are
135 evaluated on session start in the same way as you would
136 type them manually in console.
137
138 Default control file is located at `$HOME/.re.pl/repl.rc` .
139
140 You can store there any statements you would normally type in.
141
142 I.e. my `$HOME/.re.pl/repl.rc` has next lines:
143
144       use feature 'say'; # to don't write \n all the time
145
146       use Data::Dumper;
147
148       # pretty print data structures
149       sub pp { print Data::Dumper->Dump([@_]) }
150
151 You can have multiple control files and they can be anywhere in the
152 file system. To make re.pl use some rc-file other than repl.rc
153 call it like this:
154
155       $ re.pl --rcfile /path/to/your/rc.file
156
157 If your rc-file is in `$HOME/.re.pl` directory, you can omit path:
158
159       $ re.pl --rcfile rc.file
160
161 If you have rc-file with the same name in current directory
162 and you don't want to type path, you can:
163
164       $ re.pl --rcfile ./rc.file
165
166 =head2 I want it to bark, fly, jump and swim! or Plugins
167
168 Plugins extend functionality and change behavor of Devel::REPL.
169 Bundled plugins are:
170
171 =over 2
172
173 =item *
174
175 Devel::REPL::Plugin::History
176   No comments. Simply history.
177
178 =item *
179
180 Devel::REPL::Plugin::!LexEnv
181   Provides a lexical environment for the Devel::REPL.
182
183 =item *
184
185 Devel::REPL::Plugin::DDS
186   Formats return values with Data::Dump::Streamer module.
187
188 =item *
189
190 Devel::REPL::Plugin::Packages
191   Keeps track of which package your're in.
192
193 =item *
194
195 Devel::REPL::Plugin::Commands
196   Generic command creation plugin using injected functions.
197
198 =item *
199
200 Devel::REPL::Plugin::MultiLine::PPI
201   Makes Devel::REPL read your input until your block
202   is finished. What does this means: you can type a part of a block
203   on one line and second part on another:
204
205        $ sub mysub {
206
207        > print "Hello, World!\n"; ## notice prompt change
208
209        > }
210
211        $ mysub
212        Hello, World!
213        1
214        $
215
216   but this *doesn't* mean you can print sub name or identifier
217   on several lines. Don't do that! It won't work.
218
219
220 =back
221
222 There are lots of contributed plugins you can find at CPAN.
223
224 =head1 Profiles
225
226 If plugins change and extend functionality of Devel::REPL, profiles
227 are changing your environment (loaded plugins, constants, subs and etc.).
228
229 There's only one bundled profile called `Devel::REPL::Profile::Default`, lets
230 take a look at it:
231
232       package Devel::REPL::Profile::Default;
233
234       use Moose; ### advanced OOP system for Perl
235
236       ### keep those exports/imports out of our namespace
237       use namespace::clean -except => [ 'meta' ];
238
239       with 'Devel::REPL::Profile';  ## seem perldoc Muse
240
241       sub plugins { ### plugins we want to be loaded
242         qw(History LexEnv DDS Packages Commands MultiLine::PPI);
243       }
244
245       ### the only required sub for profile,
246       ### it is called on profile activation
247       sub apply_profile {
248         my ($self, $repl) = @_;
249         ### $self - no comments, $repl - current instance of Devel::REPL
250
251         $repl->load_plugin($_) for $self->plugins; ### load our plugins
252       }
253
254       1;
255
256 At the moment there are no profiles on CPAN. Mostly you'll use control files.
257 To enable some profile use --profile switch:
258
259       $ re.pl --profile SomeProfile
260
261 =head1 See Also
262
263 L<Devel::REPL>, L<Devel::REPL::Plugin>, L<Devel::REPL::Profile>