Commit | Line | Data |
6aa58492 |
1 | NAME |
2 | Devel::REPL - a modern perl interactive shell |
3 | |
4 | SYNOPSIS |
5 | my $repl = Devel::REPL->new; |
6 | $repl->load_plugin($_) for qw(History LexEnv); |
7 | $repl->run |
8 | |
9 | Alternatively, use the 're.pl' script installed with the distribution |
10 | |
11 | system$ re.pl |
12 | |
13 | DESCRIPTION |
14 | This is an interactive shell for Perl, commonly known as a REPL - Read, |
15 | Evaluate, Print, Loop. The shell provides for rapid development or |
16 | testing of code without the need to create a temporary source code file. |
17 | |
18 | Through a plugin system, many features are available on demand. You can |
19 | also tailor the environment through the use of profiles and run control |
20 | files, for example to pre-load certain Perl modules when working on a |
21 | particular project. |
22 | |
23 | USAGE |
24 | To start a shell, follow one of the examples in the "SYNOPSIS" above. |
25 | |
26 | Once running, the shell accepts and will attempt to execute any code |
27 | given. If the code executes successfully you'll be shown the result, |
28 | otherwise an error message will be returned. Here are a few examples: |
29 | |
73d11b24 |
30 | $_ print "Hello, world!\n" |
31 | Hello, world! |
32 | 1 |
33 | $_ nosuchfunction |
34 | Compile error: Bareword "nosuchfunction" not allowed while "strict subs" in use at (eval 130) line 5. |
35 | |
36 | $_ |
6aa58492 |
37 | |
38 | In the first example above you see the output of the command ("Hello, |
39 | world!"), if any, and then the return value of the statement (1). |
40 | Following that example, an error is returned when the execution of some |
41 | code fails. |
42 | |
43 | Note that the lack of semicolon on the end is not a mistake - the code |
44 | is run inside a Block structure (to protect the REPL in case the code |
45 | blows up), which means a single statement doesn't require the semicolon. |
46 | You can add one if you like, though. |
47 | |
48 | If you followed the first example in the "SYNOPSIS" above, you'll have |
49 | the History and LexEnv plugins loaded (and there are many more |
50 | available). Although the shell might support "up-arrow" history, the |
51 | History plugin adds "bang" history to that so you can re-execute chosen |
52 | commands (with e.g. "!53"). The LexEnv plugin ensures that lexical |
53 | variables declared with the "my" keyword will automatically persist |
54 | between statements executed in the REPL shell. |
55 | |
56 | When you "use" any Perl module, the "import()" will work as expected - |
57 | the exported functions from that module are available for immediate use: |
58 | |
73d11b24 |
59 | $_ carp "I'm dieeeing!\n" |
60 | String found where operator expected at (eval 129) line 5, near "carp "I'm dieeeing!\n"" |
61 | (Do you need to predeclare carp?) |
62 | Compile error: syntax error at (eval 129) line 5, near "carp "I'm dieeeing!\n"" |
63 | BEGIN not safe after errors--compilation aborted at (eval 129) line 5. |
64 | |
65 | $_ use Carp |
66 | |
67 | $_ carp "I'm dieeeing!\n" |
68 | I'm dieeeing! |
69 | at /usr/share/perl5/Lexical/Persistence.pm line 327 |
70 | 1 |
71 | $_ |
1ca46867 |
72 | |
73 | To quit from the shell, hit "Ctrl+D" or "Ctrl+C". |
6aa58492 |
74 | |
73d11b24 |
75 | MSWin32 NOTE: control keys won't work if TERM=dumb |
76 | because readline functionality will be disabled. |
6aa58492 |
77 | |
78 | Run Control Files |
79 | For particular projects you might well end up running the same commands |
80 | each time the REPL shell starts up - loading Perl modules, setting |
81 | configuration, and so on. A run control file lets you have this done |
82 | automatically, and you can have multiple files for different projects. |
83 | |
84 | By default the "re.pl" program looks for "$HOME/.re.pl/repl.rc", and |
85 | runs whatever code is in there as if you had entered it at the REPL |
86 | shell yourself. |
87 | |
88 | To set a new run control file that's also in that directory, pass it as |
89 | a filename like so: |
90 | |
73d11b24 |
91 | system$ re.pl --rcfile myproject.pc |
6aa58492 |
92 | |
93 | If the filename happens to contain a forwardslash, then it's used |
73d11b24 |
94 | absolutely, or realive to the current working directory: |
6aa58492 |
95 | |
73d11b24 |
96 | system$ re.pl --rcfile /path/to/my/project/repl.rc |
6aa58492 |
97 | |
98 | Within the run control file you might want to load plugins. This is |
99 | covered in "The REPL shell object" section, below. |
100 | |
101 | Profiles |
102 | To allow for the sharing of run control files, you can fashion them into |
103 | a Perl module for distribution (perhaps via the CPAN). For more |
104 | information on this feature, please see the Devel::REPL::Profile manual |
105 | page. |
106 | |
107 | A default profile ships with "Devel::REPL"; it loads the following |
108 | plugins: |
109 | |
110 | * Devel::REPL::Plugin::History |
111 | |
112 | * Devel::REPL::Plugin::LexEnv |
113 | |
114 | * Devel::REPL::Plugin::DDS |
115 | |
116 | * Devel::REPL::Plugin::Packages |
117 | |
118 | * Devel::REPL::Plugin::Commands |
119 | |
120 | * Devel::REPL::Plugin::MultiLine::PPI |
121 | |
122 | Plugins |
123 | Plugins are a way to add funcionality to the REPL shell, and take |
124 | advantage of "Devel::REPL" being based on the Moose object system for |
125 | Perl 5. This means it's simple to 'hook into' many steps of the R-E-P-L |
126 | process. Plugins can change the way commands are interpreted, or the way |
127 | their results are output, or even add commands to the shell environment. |
128 | |
129 | A number of plugins ship with "Devel::REPL", and more are available on |
130 | the CPAN. Some of the shipped plugins are loaded in the default profile, |
131 | mentioned above. |
132 | |
73d11b24 |
133 | Writing your own plugins is not difficult, and is discussed in the |
134 | Devel::REPL::Plugin manual page, along with links to the manual pages of |
135 | all the plugins shipped with "Devel::REPL". |
6aa58492 |
136 | |
137 | The REPL shell object |
138 | From time to time you'll want to interact with or manipulate the |
139 | "Devel::REPL" shell object itself; that is, the instance of the shell |
140 | you're currently running. |
141 | |
142 | The object is always available through the $_REPL variable. One common |
143 | requirement is to load an additional plugin, after your profile and run |
144 | control files have already been executed: |
145 | |
146 | $_ $_REPL->load_plugin('Timing'); |
147 | 1 |
148 | $_ print "Hello again, world!\n" |
149 | Hello again, world! |
150 | Took 0.00148296356201172 seconds. |
151 | 1 |
152 | $_ |
153 | |
154 | REQUIREMENTS |
155 | In addition to the contents of the standard Perl distribution, you will |
156 | need the following: |
157 | |
73d11b24 |
158 | * Moose >= 0.74 |
6aa58492 |
159 | |
160 | * MooseX::Object::Pluggable >= 0.0009 |
161 | |
73d11b24 |
162 | * MooseX::Getopt >= 0.18 |
6aa58492 |
163 | |
73d11b24 |
164 | * MooseX::AttributeHelpers >= 0.16 |
6aa58492 |
165 | |
166 | * namespace::clean |
167 | |
168 | * File::HomeDir |
169 | |
ab213f1f |
170 | * Task::Weaken |
6aa58492 |
171 | |
73d11b24 |
172 | * B::Concise |
173 | |
174 | * Term::ANSIColor |
175 | |
176 | * Devel::Peek |
177 | |
ab213f1f |
178 | Optionally, some plugins if installed will require the following |
179 | modules: |
6aa58492 |
180 | |
181 | * PPI |
182 | |
ab213f1f |
183 | * Data::Dump::Streamer |
184 | |
73d11b24 |
185 | * Data::Dumper::Concise |
186 | |
ab213f1f |
187 | * File::Next |
188 | |
73d11b24 |
189 | * Sys::SigAction |
190 | |
6aa58492 |
191 | * B::Keywords |
192 | |
ab213f1f |
193 | * Lexical::Persistence |
6aa58492 |
194 | |
195 | * App::Nopaste |
196 | |
ab213f1f |
197 | * Module::Refresh |
198 | |
6aa58492 |
199 | AUTHOR |
200 | Matt S Trout - mst (at) shadowcatsystems.co.uk |
201 | (<http://www.shadowcatsystems.co.uk/>) |
202 | |
203 | CONTRIBUTORS |
73d11b24 |
204 | Stevan Little - stevan (at) iinteractive.com |
6aa58492 |
205 | Alexis Sukrieh - sukria+perl (at) sukria.net |
206 | epitaph |
73d11b24 |
207 | mgrimes - mgrimes (at) cpan dot org |
208 | Shawn M Moore - sartak (at) gmail.com |
ab213f1f |
209 | Oliver Gorwits - oliver on irc.perl.org |
73d11b24 |
210 | Andrew Moore - "<amoore@cpan.org>" |
211 | Norbert Buchmuller "<norbi@nix.hu>" |
212 | Dave Houston "<dhouston@cpan.org>" |
1ca46867 |
213 | Chris Marshall |
6aa58492 |
214 | |
215 | LICENSE |
216 | This library is free software under the same terms as perl itself |
217 | |