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