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 | |
1ca46867 |
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. |
6aa58492 |
35 | |
1ca46867 |
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 | |
1ca46867 |
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. |
6aa58492 |
64 | |
1ca46867 |
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 | $_ |
72 | |
73 | To quit from the shell, hit "Ctrl+D" or "Ctrl+C". |
6aa58492 |
74 | |
1ca46867 |
75 | MSWin32 NOTE: control keys won't work if TERM=dumb |
76 | because readline functionality will be |
77 | disabled. |
6aa58492 |
78 | |
79 | Run Control Files |
80 | For particular projects you might well end up running the same commands |
81 | each time the REPL shell starts up - loading Perl modules, setting |
82 | configuration, and so on. A run control file lets you have this done |
83 | automatically, and you can have multiple files for different projects. |
84 | |
85 | By default the "re.pl" program looks for "$HOME/.re.pl/repl.rc", and |
86 | runs whatever code is in there as if you had entered it at the REPL |
87 | shell yourself. |
88 | |
89 | To set a new run control file that's also in that directory, pass it as |
90 | a filename like so: |
91 | |
1ca46867 |
92 | system$ re.pl --rcfile myproject.pc |
6aa58492 |
93 | |
94 | If the filename happens to contain a forwardslash, then it's used |
1ca46867 |
95 | absolutely, or relative to the current working directory: |
6aa58492 |
96 | |
1ca46867 |
97 | system$ re.pl --rcfile /path/to/my/project/repl.rc |
6aa58492 |
98 | |
99 | Within the run control file you might want to load plugins. This is |
100 | covered in "The REPL shell object" section, below. |
101 | |
102 | Profiles |
103 | To allow for the sharing of run control files, you can fashion them into |
104 | a Perl module for distribution (perhaps via the CPAN). For more |
105 | information on this feature, please see the Devel::REPL::Profile manual |
106 | page. |
107 | |
108 | A default profile ships with "Devel::REPL"; it loads the following |
109 | plugins: |
110 | |
111 | * Devel::REPL::Plugin::History |
112 | |
113 | * Devel::REPL::Plugin::LexEnv |
114 | |
115 | * Devel::REPL::Plugin::DDS |
116 | |
117 | * Devel::REPL::Plugin::Packages |
118 | |
119 | * Devel::REPL::Plugin::Commands |
120 | |
121 | * Devel::REPL::Plugin::MultiLine::PPI |
122 | |
123 | Plugins |
124 | Plugins are a way to add funcionality to the REPL shell, and take |
125 | advantage of "Devel::REPL" being based on the Moose object system for |
126 | Perl 5. This means it's simple to 'hook into' many steps of the R-E-P-L |
127 | process. Plugins can change the way commands are interpreted, or the way |
128 | their results are output, or even add commands to the shell environment. |
129 | |
130 | A number of plugins ship with "Devel::REPL", and more are available on |
131 | the CPAN. Some of the shipped plugins are loaded in the default profile, |
132 | mentioned above. |
133 | |
1ca46867 |
134 | Writing your own plugins is not difficult once you understand all about |
135 | Moose and Moose Roles. A Devel::REPL::Plugin manual page is planned but |
136 | not yet written. |
6aa58492 |
137 | |
138 | The REPL shell object |
139 | From time to time you'll want to interact with or manipulate the |
140 | "Devel::REPL" shell object itself; that is, the instance of the shell |
141 | you're currently running. |
142 | |
143 | The object is always available through the $_REPL variable. One common |
144 | requirement is to load an additional plugin, after your profile and run |
145 | control files have already been executed: |
146 | |
147 | $_ $_REPL->load_plugin('Timing'); |
148 | 1 |
149 | $_ print "Hello again, world!\n" |
150 | Hello again, world! |
151 | Took 0.00148296356201172 seconds. |
152 | 1 |
153 | $_ |
154 | |
155 | REQUIREMENTS |
156 | In addition to the contents of the standard Perl distribution, you will |
157 | need the following: |
158 | |
159 | * Moose >= 0.64 |
160 | |
161 | * MooseX::Object::Pluggable >= 0.0009 |
162 | |
163 | * MooseX::Getopt >= 0.15 |
164 | |
165 | * MooseX::AttributeHelpers >= 0.14 |
166 | |
167 | * namespace::clean |
168 | |
169 | * File::HomeDir |
170 | |
ab213f1f |
171 | * Task::Weaken |
6aa58492 |
172 | |
ab213f1f |
173 | Optionally, some plugins if installed will require the following |
174 | modules: |
6aa58492 |
175 | |
176 | * PPI |
177 | |
ab213f1f |
178 | * Data::Dump::Streamer |
179 | |
180 | * File::Next |
181 | |
6aa58492 |
182 | * B::Keywords |
183 | |
ab213f1f |
184 | * Lexical::Persistence |
6aa58492 |
185 | |
186 | * App::Nopaste |
187 | |
ab213f1f |
188 | * Module::Refresh |
189 | |
6aa58492 |
190 | AUTHOR |
191 | Matt S Trout - mst (at) shadowcatsystems.co.uk |
192 | (<http://www.shadowcatsystems.co.uk/>) |
193 | |
194 | CONTRIBUTORS |
1ca46867 |
195 | Stevan Little - stevan (at) iinteractive.com |
6aa58492 |
196 | Alexis Sukrieh - sukria+perl (at) sukria.net |
197 | epitaph |
1ca46867 |
198 | mgrimes - mgrimes (at) cpan (dot) org |
199 | Shawn M Moore - sartak (at) gmail.com |
ab213f1f |
200 | Oliver Gorwits - oliver on irc.perl.org |
1ca46867 |
201 | Chris Marshall |
6aa58492 |
202 | |
203 | LICENSE |
204 | This library is free software under the same terms as perl itself |
205 | |