/ 
Term-ReadLine-Event-0.03
River stage zero No dependents
/ Term::ReadLine::Event

NAME

Term::ReadLine::Event - Wrappers for Term::ReadLine's new event_loop model.

VERSION

version 0.03

SYNOPSIS

use AnyEvent;
use Term::ReadLine::Event;

my $term = Term::ReadLine::Event->with_AnyEvent('...');

my $input = $term->readline('Prompt >');

DESCRIPTION

Provides many of the event loop interactions shown in the examples provided as a small change to your code rather than the longer code required.

This may actually be sufficient for your use, or it may not. This likely depends on the loop being used.

HISTORY

This project started with a goal: to get Term::ReadLine working under Coro. Since Coro used AnyEvent, I thought that getting Term::ReadLine to use AnyEvent instead of Tk directly would be a win. Conversations ensued, and it sounded like P5P generally liked the idea, but didn't want anything AnyEvent-specific when it could be more generic than that.

Through a couple of iterations, the event_loop interface was born. However, since this was no longer as simple as the old Tk interface ($term->tkRunning(1)), I thought it would need some examples. Putting examples into the perl core seemed a bit strange, partly due to the extra overhead involved in updating them, so having a distribution on CPAN full of examples seemed to make sense. When looking for information on a module, my first place to look is CPAN, so that made sense to me.

I then got some examples from other event loop developers (Paul "LeoNerd" Evans and Rocco Caputo), and added them to my AnyEvent and Coro examples, and that was the first release. If others submit further examples, I will add them and maybe this will grow. Even if it doesn't, as long as it helps people integrate Term::ReadLine into their event-loop-based apps, whether that's Reflex or POE or AnyEvent or Coro or even using select loops to just do some background processing, then it will have met its goal.

Having compiled a list of examples, I then realised that most of the examples could be abstracted into a module. Again, directly into Term::ReadLine would be too specific for P5P, but just perfect for a distribution. If you choose to install this distribution instead of just swiping the example that suits you, you can integrate with an event loop in a single line (for POE, that's significant savings, for Coro, not so much).

Note that the examples are more complete than the test files as well. This is largely because testing full readline functionality in an automated fashion is not entirely trivial. The hope would be that anyone making changes to Term::ReadLine in the future be able to use these examples in their own testing to ensure they don't break anything. (If you do, be sure you're testing with Term::ReadLine::Gnu and Term::ReadLine::Perl, testing with just Term::ReadLine::Stub will miss things.)

Hopefully, this makes it trivial enough to use event loops with T::RL such that anyone can do it. You can get back to focusing on your business logic instead of arcane rituals to get event loops integrated with Term::ReadLine. And hopefully that means we get more perl apps that have nice interfaces (with readline support), even when doing other things in the background (events).

It is not my intention to provide wrappers for all event loops. It is my intention only to provide examples for as many loops as possible. The wrappers are intended to be examples as well (though covered under Artistic/GPL licensing whereas the examples themselves are more permissive), and not necessarily used as-is, partially due to their size (all the wrappers are in a single module). That being said, I would likely just use the wrapper because I'm too lazy to copy the examples into my code. If I were entirely concerned about RAM usage, I'd be writing in C.

METHODS

All constructors (with_*) take as their first parameter one of:

  • The name of the application, which gets passed in to Term::ReadLine's constructor.

    my $term = Term::ReadLine::Event->with_Foo('myapp');

  • An array ref consisting of the name of the application, and the input and output filehandles. This is useful if you need to override these filehandles.

    my $term = Term::ReadLine::Event->with_Foo(['myapp', \*STDIN, \*STDOUT]);

  • A pre-constructed Term::ReadLine object. This is useful if you need to do other things with the Term::ReadLine object prior to setting up the event loop, or if you have a custom package derived from Term::ReadLine and you do not want Term::ReadLine::Event to create the default type.

    my $term = Term::ReadLine::Special->new('myapp', other => 'stuff');
$term = Term::ReadLine::Event->with_Foo($term);

Paramters for setting up the event loop, if any are required, will be after this first parameter as named parameters, e.g.:

Term::ReadLine::Event->with_IO_Async('myapp', loop => $loop);

All constructors also assume that the required module(s) is(are) already loaded. That is, if you're using with_AnyEvent, you have already loaded AnyEvent (and thus the event loop it is using); if you're using with_POE, you have already loaded POE, etc.

with_AnyEvent

Creates a Term::ReadLine object and sets it up for use with AnyEvent.

with_Coro

Creates a Term::ReadLine object and sets it up for use with Coro.

with_IO_Async

Creates a Term::ReadLine object and sets it up for use with IO::Async.

Parameters:

loop

The IO::Async loop object to integrate with.

with_POE

Creates a Term::ReadLine object and sets it up for use with POE.

with_Reflex

Creates a Term::ReadLine object and sets it up for use with Reflex.

with_Tk

Creates a Term::ReadLine object and sets it up for use with Tk.

DESTROY

During destruction, we attempt to clean up. Note that Term::ReadLine does not like to have a second T::RL object created in the same process. This means that you should only ever let the object returned by the constructors to go out of scope when you will never use Term::ReadLine again in that process.

This largely makes destruction moot, but it can be nice in some scenarios to clean up after oneself.

trl

Access to the Term::ReadLine object itself. Since Term::ReadLine::Event is not a Term::ReadLine, but HAS a Term::ReadLine, this gives access to the underlying object in case something isn't exposed sufficiently. If you find yourself needing this, please contact me with your use case. And, preferably, a patch :-)

readline

Wrapper for Term::ReadLine's readline. Makes it convenient to just call $term->readline(...).

Attribs

Wrapper for Term::ReadLine's Attribs. Makes it convenient to just call $term->Attribs(...).

addhistory

Wrapper for Term::ReadLine's addhistory. Makes it convenient to just call $term->addhistory(...).

AUTHOR

Darin McBride, <dmcbride at cpan.org>

BUGS

Please report any bugs or feature requests to bug-term-readline-event at rt.cpan.org, or through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Term-ReadLine-Event. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

You can find documentation for this module with the perldoc command.

perldoc Term::ReadLine::Event

You can also look for information at:

ACKNOWLEDGEMENTS

Paul "LeoNerd" Evans <leonerd@leonerd.org.uk>

For all the examples (IO-Async, IO-Poll, select, and fixes for AnyEvent).

Rocco Caputo <rcaputo@cpan.org>

For a final patch to Term::ReadLine that helps reduce the number of variables that get closed upon making much of this easier to handle.

For the POE and Reflex examples, and a push to modularise the examples.

P5P

For genericising my initial AnyEvent patch idea.

AUTHOR

Darin McBride <dmcbride@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2012 by Darin McBride and others.

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