view release on metacpan or  search on metacpan

bin/prima-repl  view on Meta::CPAN

 > run_file
 Hello from the file buffer!
 OK, that's all, folks!

Running the contents of a file buffer is useful enough that it has two keyboard
shortcuts. The first is C<CTRL-Enter>, which runs the code but keeps you on
your current file buffer. The second is C<CTRL-SHIFT-Enter>, which switches you
to the Output tab before it begins executing the code.

The output window knows how to handle carriage returns (\r) as well as newlines
(\n). For an example, put the following in your buffer and hit
C<CTRL-SHIFT-Enter>:

 for(1..10) {
   print "\r$_";
   sleep 1 unless $_ == 10;
 }
 print "\nAll done!\n";

That should take about 10 seconds to run and the numbers should overwrite each
other in the process. This is very useful if you have a long-running process and
you want to print the status without filling up the output window with redundant
lines. Furthermore, the Output tab displays all text sent to Perl's STDIO and
STERR file handles. (I had hoped that even text from low-level processes that
normally print to the screen, such as C code that uses C<printf>, would display
their results to the Output tab, but no such luck. I'm researching how to
properly print stuff from Inline::C code and hope to update this soon.)

Note that the input line is greyed out while the code executes, so if you
have a long-running process, you will not be able to type in new commands or
even switch tabs.

=head2 Editing Files

Although the multi-line buffer is not the greatest editor, it is useful in a
pinch. You can save the contents of a buffer by pressing C<CTRL-s> in the buffer
window, which will present a dialog asking where you want to save your file.
Alternatively, you can type

 > save_file 'filename'

at the input line. The filename is optional; if you don't supply one, you will
get a dialog box asking for the name of the file, just as if you used the
keyboard shortcut.

You can open a file with the C<open_file> function or C<CTRL-o>. You can supply
a filename to the function, but if you do not (or if you use the keyboard
shortcut), you will get a dialog asking which file you want to open. NOTE:
IF YOU ARE CURRENTLY VIEWING A FILE BUFFER, OPENING A FILE WILL OVERWRITE THE
CONTENTS OF THE BUFFER. To save yourself from losing the contents of your
current buffer, you should either create a new tab first, or switch to the
Output tab. Trying to open a file from the Output tab automatically creates a
new tab for your file.

=head2 Viewing Images

Prima makes opening and viewing images very easy, so I've added a function for
opening a tab to display an image. The function is C<open_image> and it requires
that you specify the filename of your image to open. For example, if you have an
image called C<test.png> in your current working directory, you could view it
with the following:

 > open_image 'test.png'

=head2 Plotting PDL Data

You can easily plot data with the various plotting commands if you have
L<PDL::Graphics::Prima> installed. This will create a new tab with your
specified plot (with a special exception that we'll get to shortly). The
interface is identical to L<PDL::Graphics::Prima::Simple>, and you should check
the documentation in that module for details. Here are some examples to remind
you how this works:

 > $t_data = sequence(6) / 0.5 + 1
 > $y_data = exp($t_data)
 > line_plot($t_data, $y_data)

Here's a more complicated example for a multiline buffer. (Note that in
future versions of PDL::Graphics::Prima, datasets will be handled
differently.)

 # Create some simple data:
 $t_data = sequence(6) / 0.5 + 1;
 $y_data = exp($t_data);
 
 # Create the plotter widget:
 $plotter = plot(
     -function => ds::Func(\&PDL::exp, color => cl::Blue),
     -data => ds::Pair($t_data, $y_data, color => cl::Red),
     y => {
         scaling => sc::Log,
         label => 'exp(t)',
     },
     title => 'Exponential Curve',
     x => { label => 't' },
 );

This multiline buffer saves the reference to the plotting widget, allowing you
to fiddle with it from the input line if you like. For example, you can add
the hyperbolic cosine function like so:

 $plotter->dataSets->{cosh} = ds::Func(\&PDL::cosh, colors => cl::Green);

=head2 PDL::NiceSlice

You can use L<PDL::NiceSlice> in your code. It is not terribly intelligent
method at the moment. If the evaluator finds the exact string
C<use PDL::NiceSlice>, it uses the PDL::NiceSlice preprocessor to replace
PDL slices with calls to mslice, just like the real source filter.
Unfortunately, this does not look for statements like C<no PDL::NiceSlice>,
which can be problematic.

=head1 Customizing

There are a number of ways that you can customize your REPL, including
per-project rc files and pod notes, custom tabs, and custom commands.

=head2 RC File and Notes

App::Prima::REPL supports per-directory rc files and input logs. When you
have a file called F<prima-repl.initrc> or F<prima-repl.initrc.pl> in the
directory from which you execute C<prima-repl>, it will be executed upon 
startup (with a preference for the former). The purpose of this rc file is