view release on metacpan or  search on metacpan

bin/prima-repl  view on Meta::CPAN

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
to allow for per-project initialization and function definitions.

You can emulate user input with the C<REPL::simulate_run> command, which will add text
to the input line and then use the standard input lne mechanism to evaluate the
text. This can be useful because it puts the evaluated text into the user's
history. However, as this adds lines to the history file, you should use this
sparingly, only when you think the user will want to retrieve the command in
their history.

A very useful apect of initrc file is that you can add documentation by
simply inserting pod in your initrc file. The link at the top of this help file
will automatically open the documentation or give a message indicating that
there is no such documentation. This way, if you declare any useful functions
in your initrc file, you can document them easily.

The initrc file can also add tabs and add custom commands, but you can do
these from a multiline buffer as well, so I put them in their own sections.

=head2 Custom Tabs

If you wish to create custom tabs, there are two commands that will help.

=over

=item REPL::create_new_tab($name, @creation_options)

This puts a new tab at the end of the tab list with the specified name. The
C<@creation_options> are exactly what you would send to Prima's C<insert>
command, including the widget class as the first element. This function
returns the created object when called in scalar context. In list context,
it also returns the tab index as the second return value. This index is useful if
you want to specify a different default widget for your tab, which brings me
to...

=item REPL::change_default_widget($index, $widget)

This function changes the default widget for the tab with the given index.
The default widget is the widget that recieves the keyboard focus when you
first switch to the tab. This function takes the tab index (returned by
C<REPL::create_new_tab> in list context) and the desired widget. Note that
if you want C<CTRL-i> to toggle between the desired widget and the input
line, which is the behavior of the file buffers, you will need to have your
default widge properly respond to C<CTRL-i> keyboard input.

=item REPL::endow_editor_widget($widget)

Given a normal editor widget, this sets the various options to make the editor
behave like the default multiline buffer editor. For example, it turns on
syntax highlighting, sets a monospace font, and sets the default accelerator
keys. Although not strictly necessary for creating tabs, it may be useful if
you want to create a tab with both an editor and some other sort of widget,
side-by-side, as is done in L<App::Prima::REPL::Talk>.

This function does not set the widget as the tab's default widget, since you
may want the default widget to be something else. You should explicitly invoke
C<REPL::change_default_widget> (above) to do that.

The endowed editor has named key bindings that you can overwrite:

 CtrlReturn    CtrlShiftReturn
 CtrlEnter     CtrlShiftEnter
 CtrlPageDown  CtrlPageUp

You can override these commands with something like this:

 # Update ctrl-return/ctrl-edit for the editor
 $editor->accelTable->insert([
       # Ctrl-Enter runs the file
       ['CtrlReturn', '', kb::Return  | km::Ctrl, $run_code ]
     , ['CtrlEnter', '', kb::Enter    | km::Ctrl, $run_code ]
   ]
   , ''
   , 0
 );

=back

At some point I'll add an example of how to use these.

=head2 Custom Commands

Perl knows about I<functions> and I<list operators>. App::Prima::REPL
I<also> knows about I<commands>, like
the C<help> command. Remember, the help command doesn't require quotes around
the module name. How do I do this? I achieve this by hooking into the
C<PressEnter> stage of the InputHistory widget. Hooking into this stage of
the widget lets you modify what eventually gets evaluated (for example, by
applying the NiceSlice filter) and even lets you avoid the Perl eval-stage
altogether.

Here's the hook that proceses the help command:

 $REPL::inline->add_notification(PressEnter => sub {
     # See if they asked for help.
     if ($_[1] =~ /^\s*help\s*(.*)/) {
         get_help($1);
         $_[0]->clear_event;
     }
 });

Notice that the help command does not want the eventual string to be
evaluated, so it calls C<get_help> and then clears the event. If you simply
want to modify the string before it gets evaluated, you need to modify
C<$_[1]> directly without clearing the event.

The subroutine that you write for such hooks will be passed two arguments,
the InputHistory object (C<$REPL::inline>) and the text from the input line's
buffer. Note that by the time your notification receives the latter, it may
have already been modified as there are a number of built-in notifications.

=head2 Other API Functions

Here are some other REPL API functions that you may find useful:

=over

=item REPL::goto_output