NAME

PDL::Graphics::Prima::ReadLine - allowing Prima and Term::ReadLine to play together

SYNOPSIS

 # This pulls in PDL::Graphics::Prima::ReadLine, and
 # associate's the PDL Shell's readline object if it
 # exists:
 use PDL::Graphics::Prima;
 
 # Did it set up the readline event loop callback?
 print "Set up Prima/ReadLine interaction\n"
     if PDL::Graphics::Prima::ReadLine->is_setup;
 
 # If you are not in the PDL shell, you can supply
 # your own ReadLine object.
 if (PDL::Graphics::Prima::ReadLine->is_happy_with($my_readline) {
     PDL::Graphics::Prima::ReadLine->setup($my_readline);
 }
 
 # If you don't validate first, setup() may croak.
 # In other words, instead of this:
 if (PDL::Graphics::Prima::ReadLine->is_happy_with($my_readline) {
     PDL::Graphics::Prima::ReadLine->setup($my_readline);
 }
 else {
     die "Unable to setup Prima/ReadLine interaction\n";
 }
 # You could just say this instead:
 PDL::Graphics::Prima::ReadLine->setup($my_readline);

DESCRIPTION

This module's job is to encapsulate the vagaries of setting up interaction between the Prima event loop and Term::ReadLine's event loop. Loading the module does not have any side-effects, and it is always loaded by PDL::Graphics::Prima. Furthermore, PDL::Graphics::Prima will set up the event loop interaction with the PDL shell if it detects the shell's ReadLine object.

Generally speaking, if you intend to have user interaction and want to use PDL::Graphics::Prima, you should probably just use Prima to build a simple interactive application. (Docmentation for getting started with this is coming soon, I promise.) However, if you want to integrate PDL::Graphics::Prima into a pluggable application that already uses Term::ReadLine, this module should make that procedure as straight-forward as one can hope.

PDL::Graphics::Prima::ReadLine can only hook into the event loop for newer versions of Term::ReadLine (specifically, versions that support event_loop). Also, due to current limitations in my knowledge of Prima's monitoring of STDIN, this module cannot hook into the event loop on Windows operating systems, both Cygwin and Strawberry Perl.

is_happy_with

If you want to set up the event loop interaction on your own ReadLine object, you can ask PDL::Graphics::Prima::ReadLine if it can work with your object by calling the is_happy_with class method and supplying your objects. This method returns a boolean value indicating whether or not the object can do what PDL::Graphics::Prima::ReadLine needs:

 if (PDL::Graphics::Prima::ReadLine->is_happy_with($my_readline) {
     print "Setting up Prima/ReadLine interaction\n";
     PDL::Graphics::Prima::ReadLine->setup($my_readline);
 }

setup

To hook Prima's event loop into your ReadLine's event loop, you can call the setup class method:

 PDL::Graphics::Prima::ReadLine->setup($readline_obj);

This method may (should) fail if the ReadLine object provided cannot support the functionality needed for hooking Prima into ReadLine. This could happen either because your version of ReadLine is too old or because you are running on Windows, which is not (yet) supported by PDL::Graphics::Prima::ReadLine.

SEE ALSO

For purposes of this module, you should check out Term::ReadLine. This module is implemented using Prima::File.

AUTHOR

David Mertens (dcmertens.perl@gmail.com)

ADDITIONAL MODULES

Here is the full list of modules in this distribution:

PDL::Graphics::Prima

Defines the Plot widget for use in Prima applications

PDL::Graphics::Prima::Axis

Specifies the behavior of axes (but not the scaling)

PDL::Graphics::Prima::DataSet

Specifies the behavior of DataSets

PDL::Graphics::Prima::Limits

Defines the lm:: namespace

PDL::Graphics::Prima::Palette

Specifies a collection of different color palettes

PDL::Graphics::Prima::PlotType

Defines the different ways to visualize your data

PDL::Graphics::Prima::ReadLine

Encapsulates all interaction with the Term::ReadLine family of modules.

PDL::Graphics::Prima::Scaling

Specifies different kinds of scaling, including linear and logarithmic

PDL::Graphics::Prima::Simple

Defines a number of useful functions for generating simple and not-so-simple plots

LICENSE AND COPYRIGHT

Unless otherwise stated, all contributions in code and documentation are copyright (c) their respective authors, all rights reserved.

Portions of this module's code are copyright (c) 2011 The Board of Trustees at the University of Illinois.

Portions of this module's code are copyright (c) 2011-2013 Northwestern University.

Portions of this module's code are copyright (c) 2013-2014 Dickinson College.

This module's documentation is copyright (c) 2011-2014 David Mertens.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.