/ 
Webservice-Rosary-API-0.1.7
/ Webservice::Rosary::Stream

NAME

Webservice::Rosary::Stream - terminal text streaming controls for avemaria

SYNOPSIS

use Webservice::Rosary::Stream;

my $stream = Webservice::Rosary::Stream->new(
  delay    => 0.04,
  speed    => 1,
  controls => 1,
);

$stream->stream("Hail Mary ...");

DESCRIPTION

This small helper provides the character-at-a-time presentation used by the avemaria client. When STDIN and STDOUT are terminals it enables nonblocking keyboard controls through Term::ReadKey. Redirected output remains noninteractive.

The controls are intentionally small: SPACE or p pauses and resumes, + speeds up, - slows down, 0 restores the initial speed, and q asks for confirmation before quitting.

METHODS

new

Accepts delay, speed, controls, min_speed, max_speed, speed_step, confirm_quit, and on_quit. The delay is the base number of seconds between characters. speed is a multiplier and defaults to 1. The default minimum and maximum speeds are 0.25 and 8, and each + or - adjustment changes the speed by a factor of 1.25. These limits and the adjustment factor may be overridden with min_speed, max_speed, and speed_step.

confirm_quit may be supplied as a callback returning true or false instead of using the default Quit y/N? prompt. on_quit is called after a confirmed quit, allowing the client to print a farewell or perform other cleanup.

For tests, read_key, sleep_cb, and write_cb callbacks may be supplied, which allows the timing and keyboard behavior to be exercised without a real terminal.

stream

Streams the supplied text and processes real-time controls between characters and during character delays.

wait

Waits for a specified number of seconds while continuing to process interactive controls. Pause and resume affect the wait immediately; speed keys are consumed but do not change the duration of this fixed wait.

handle_key

Processes one control key. SPACE and p toggle pause, + and = increase speed, - and _ decrease speed, 0 restores the initial speed, and q requests the quit-confirmation flow. Primarily useful for testing or alternate terminal front ends.

restore_terminal / resume_terminal

Restores normal terminal input before a blocking prompt and enables interactive controls again afterward.

LICENSE AND COPYRIGHT

Same as Perl.