The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Text-Twiddler-0.0.1
River stage zero No dependents
++
/ Text::Twiddler

NAME

Text::Twiddler - Twiddle text for any type of output

VERSION

This document describes Text::Twiddler version 0.0.1

SYNOPSIS

    use Text::Twiddler;
    my $twiddler = Text::Twiddler->new(\%options);

    # print animated text while we do a long operation so the 
    # user knows we're still running without the messy details

    print $twiddler->get_start_twiddler() if !$verbose;

    my($wtr, $rdr);
    my $pid = open3($wtr, $rdr, $rdr, @long_command);

    while( <$rdr> ) {
        if ( $verbose ) {
            print $_;
        } 
        else {
            print $twiddler->get_next_twiddler();
        }
    }

    print $twiddler->get_start_twiddler() if !$verbose;

DESCRIPTION

Show a 'twiddled' (IE animated) message, perhaps during a long running operation or for a neat effect.

What is nice is that, in the example in the synopsis, the animation is approximated to the actual state of the process.

In other words, if the command is blazing through its task (Eg many lines of output very rapidly), then the 'animation' is very quick.

If the command is working hard at one point and lags between outputting lines, then the animation also slows.

In this way the twiddler, hides all the details of the output while still giving some idea of how its coming along.

INTERFACE

METHODS

new()

Create a twiddler object, can take a hashref of these, optional, arguments:

output_ns

The NS to use for output methods. (If it's not one listed in 'OUTPUT TYPE DRIVERS' you will need to use() or require() it first)

default: Text::Twiddler::CLI

start

Start text

default: Starting...

text

String or array ref of strings (AKA "frames") to twiddle.

(Note array's of one item get that item used as if it was passed as a string)

default: Working...

end

End text

default: Done!

sway

If true, the frames get appended a reversed version of the frames. The effect is a "sway".

For example, by default the string will appear one character at a time from left to right. When complete it start over from the left.

If sway is true, once it reaches the end it will start disappearing once character at a time from the right.

default: 0

lang_obj

A language object that can() maketext(), see "LOCALIZATION" below and Locale::Maketext::Pseudo

get_start_twiddler()

Returns the string to start the twiddler.

get_next_twiddler()

Returns the string that is the next "frame" in the twiddle.

get_blank_twiddler()

Returns a line that blanks out the twiddler and does a new line in the context of the output ns.

    if ( $found_it ) {
        print $twid->get_blank_twiddler();
        print "We found it! -$found_it-\n";
    }

    print $twid->get_next_twiddler();

get_end_twiddler()

Returns the string that ends the twiddler.

Other misc methods

START()

Internal for Class::Std

get_uniq_str()

Mostly internal, returns a unique identifier.

get_next_frame()

Internal, don't use it directly.

get_output_ns()

Get the object's 'output_ns'

get_iterations()

The number of iterations needed to complete one cycle of "frames"

get_longest()

The number of characters in the longest "frame"

get_start()

Get the object's 'start'

get_text()

Get the object's 'text'

get_end()

Get the object's 'end'

get_frames()

Returns an array ref of the frames as calculated by the 'FX' function used.

OUTPUT TYPE DRIVERS

Support for twiddling for different types of output is provided by specific output type drivers.

Included in Text::Twiddler are two common ones described below:

Text::Twiddler::CLI

'output_ns' for twiddling to a Command Line Interface, generally a terminal

Text::Twiddler::HTML

'output_ns' for twiddling in HTML, generally to a browser.

Creating new ones

You could create your own for any type of output by providing a 'output_ns' package name that has these methods (even if they are a no-op for your output medium):

  • get_output_pre()

  • get_output_str()

  • get_output_pst()

They are very simple methods. See the source for how these are used if you'd like to implement your own, More detailed 'how to' POD may be added depending on nice feedback :)

Here is what using you're custom one to twiddle a few messages across the sky might look like:

    require Text::Twiddler::LazerLightShow;
    print {$lazer_beam} "And now for a few messages...\n";

    for my $msg (qw(
            'Welcome to Pink Floyd lazer light show!',
            q{Please turn off cell phones as you won't be able to hear them anyway},
            'No pictures please, your camera will be destroyed',
            'Sit back relax and enjoy the show...',
        )) {    
        my $twid = Text::Twiddler->new({
            'output_ns' => 'Text::Twiddler::LazerLightShow',    
            'start'     => '',
            'text'      => $msg,
            'end'       => '',
        });

        # - no need for start or end text with this use
        # - we use get_iterations() instead of length() in $msg, because the type 
        #     of 'effect' may be different length than the text.

        for ( 1 .. $twid->get_iterations() ) {
            print {$lazer_beam} $twid->get_next_twiddler();     
        }
    }

FX functionality

'FX' can stand for "Effects" or "Frame Expander", take your pick.

These 'FX' functions come with Text::Twiddler.

Text::Twiddler::FX::standard()

This is what is used internally by default. The string builds one character at a time from left to right.

'sway' will make it disappear one character at a time from right to left

Text::Twiddler::FX::secret_decoder()

This is a fun animation that makes it look like the string is gradually being decoded by a super secret spy computer.

'sway' will make it look like it was re-encoded by said super secret spy computer

    my $twid = Text::Twiddler->new({
        'text' => Text::Twiddler::FX::secret_decoder('Your misson should you choose to accept it...'),
    });

Creating new ones

These functions should return a string or array ref suitable for new()'s 'text' attribute.

The documentaton should be clear about whether or not 'sway' looks good, bad, or neutral.

They should be under the Text::Twiddler::FX name space, for example:

  Text::Twiddler::FX::Reveal

might have these functions:

     inside_out('abcd')   # ' b  ', ' bc ', 'abc ', 'abcd'  
     outside_in('abcd')   # 'a   ', 'a   d', 'ab d', 'abcd'
     random_fill('abcd')  # same idea as above but w/ random appearance

DIAGNOSTICS

'%s' does not have required 'get_output_*' method, defaulting to 'Text::Twiddler::CLI'

This means that the namespace you passed in 'output_ns' is not a Text::Twiddler output driver since its missing one or more required 'get_output' methods

LOCALIZATION

This module uses Locale::Maketext::Pseudo as a default if nothing else is specified to support localization in harmony with the apps using it.

See "DESCRIPTION" at Locale::Maketext::Pseudo for more info on why this is good and why you should use this module's language object support at best and, at worst, appreciate it being there for when you will want it later.

CONFIGURATION AND ENVIRONMENT

Text::Twiddler requires no configuration files or environment variables (see below for %ENV note).

localization

Lexicon keys:

  '[_1]' does not have required '[_2]' method, defaulting to '[_3]'

Tip: set $ENV{'maketext_obj'} to an object that can() maketext(), see "LOCALIZATION" above and Locale::Maketext::Pseudo

DEPENDENCIES

Class::Std, Class::Std::Utils, Locale::Maketext::Pseudo, List::Cycle

INCOMPATIBILITIES

None reported.

BUGS AND LIMITATIONS

No bugs have been reported.

Please report any bugs or feature requests to bug-text-twiddler@rt.cpan.org, or through the web interface at http://rt.cpan.org.

AUTHOR

Daniel Muey <http://drmuey.com/cpan_contact.pl>

LICENCE AND COPYRIGHT

Copyright (c) 2007, Daniel Muey <http://drmuey.com/cpan_contact.pl>. All rights reserved.

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

DISCLAIMER OF WARRANTY

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.