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