The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
POE-Component-Bundle-WebDevelopment-1.001004
River stage one • 2 direct dependents • 2 total dependents
++
/ POE::Component::App::PNGCrush

NAME

POE::Component::App::PNGCrush - non-blocking wrapper around App::PNGCrush

SYNOPSIS

    use strict;
    use warnings;

    use POE qw(Component::App::PNGCrush);

    my $poco = POE::Component::App::PNGCrush->spawn;

    POE::Session->create(
        package_states => [ main => [qw(_start crushed)] ],
    );

    $poe_kernel->run;

    sub _start {
        $poco->run( {
                in      => [ qw(file1.png file2.png file3.png) ],
                options => [
                    qw( -d OUT_DIR -brute 1 ),
                    remove  => [ qw( gAMA cHRM sRGB iCCP ) ],
                ],
                event   => 'crushed',
            }
        );
    }

    sub crushed {
        my $in_ref = $_[ARG0];

        my $proc_ref = $in_ref->{out};
        for ( keys %$proc_ref ) {
            if ( exists $proc_ref->{$_}{error} ) {
                print "Got error on file $_ : $proc_ref->{$_}{error}\n";
            }
            else {
                printf "Stats for file %s\n\tSize reduction: %.2f%%\n\t"
                        . "IDAT reduction: %.2f%%\n",
                        $_, @{ $proc_ref->{$_} }{ qw(size idat) };
            }
        }

        $poco->shutdown;
    }

Using event based interface is also possible.

DESCRIPTION

The module is a non-blocking wrapper around App::PNGCrush which provides interface to ``pngcrush'' program. See documentation for App::PNGCrush regarding information on how to obtain ``pngcrush'' program.

You should familiarize yourself with new(), run() and set_options() methods of App::PNGCrush module to fully understand the workings of this POE wrapper (although, I'll point you to those in the right place throughout this document)

CONSTRUCTOR

spawn

    my $poco = POE::Component::App::PNGCrush->spawn;

    POE::Component::App::PNGCrush->spawn(
        alias => 'crush',
        obj_args => {
            max_time => 600,
        },
        options => {
            debug => 1,
            trace => 1,
            # POE::Session arguments for the component
        },
        debug => 1, # output some debug info
    );

The spawn method returns a POE::Component::App::PNGCrush object. It takes a few arguments, all of which are optional. The possible arguments are as follows:

alias

    POE::Component::App::PNGCrush->spawn(
        alias => 'crush'
    );

Optional. Specifies a POE Kernel alias for the component.

obj_args

    POE::Component::App::PNGCrush->spawn(
        obj_args => { max_time => 600 },
    );

Optional. Takes a hashref as an argument. If specified that hashref will be directly dereferenced into App::PNGCrush's constructor (new() method). See documentation for App::PNGCrush regarding valid values.

options

    my $poco = POE::Component::App::PNGCrush->spawn(
        options => {
            trace => 1,
            default => 1,
        },
    );

Optional. A hashref of POE Session options to pass to the component's session.

debug

    my $poco = POE::Component::App::PNGCrush->spawn(
        debug => 1
    );

When set to a true value turns on output of debug messages. Defaults to: 0.

METHODS

run

    $poco->run( {
            event   => 'event_for_output',
            in      => [ qw(file1.png file2.png file3.png) ],
            options => [
                qw( -d OUT_DIR -brute 1 ),
                remove  => [ qw( gAMA cHRM sRGB iCCP )
            ],
            _blah   => 'pooh!',
            session => 'other',
        }
    );

Takes a hashref as an argument, does not return a sensible return value. See run event's description for more information.

session_id

    my $poco_id = $poco->session_id;

Takes no arguments. Returns component's session ID.

shutdown

    $poco->shutdown;

Takes no arguments. Shuts down the component.

ACCEPTED EVENTS

run

    $poe_kernel->post( crush => run => {
            event   => 'event_for_output',
            in      => [ qw(file1.png file2.png file3.png) ],
            options => [
                qw( -d OUT_DIR -brute 1 ),
                remove  => [ qw( gAMA cHRM sRGB iCCP )
            ],
            _blah   => 'pooh!',
            session => 'other',
        }
    );

Instructs the component to perform "crushing" of png files. Takes a hashref as an argument, the possible keys/value of that hashref are as follows:

event

    { event => 'results_event', }

Mandatory. Specifies the name of the event to emit when results are ready. See OUTPUT section for more information.

in

    { in => 'file.png' }

    { in => [ qw(file1.png file2.png file3.png) ] }

Mandatory. Takes either a scalar containing a filename of an image you want to "crush" or an arrayref of filenames (if more than one).

options

    {
        options => [
            qw( -d OUT_DIR -brute 1 ),
            remove  => [ qw( gAMA cHRM sRGB iCCP )
        ],
    }

Mandatory. Takes an arrayref as a value which will be directly dereferenced into set_options() method of App::PNGCrush. See documentation for App::PNGCrush's set_options() method for possible values.

session

    { session => 'other' }

    { session => $other_session_reference }

    { session => $other_session_ID }

Optional. Takes either an alias, reference or an ID of an alternative session to send output to.

user defined

    {
        _user    => 'random',
        _another => 'more',
    }

Optional. Any keys starting with _ (underscore) will not affect the component and will be passed back in the result intact.

shutdown

    $poe_kernel->post( EXAMPLE => 'shutdown' );

Takes no arguments. Tells the component to shut itself down.

OUTPUT

    $VAR1 = {
        'out' => {
            'p2.png' => {
                        'msg' => undef,
                        'total_idat_length' => '1880',
                        'stderr' => '',
                        'cpu' => {
                                    'decoding' => '0.030',
                                    'other' => '0.090',
                                    'total' => '0.200',
                                    'encoding' => '0.080'
                                },
                        'status' => '0',
                        'idat' => '0.80',
                        'stdout' => 'stdout from pngcrush will be here',
                        'size' => '1.56'
                        },
            'p.png' => {
                        'msg' => undef,
                        'total_idat_length' => '1880',
                        'stderr' => '',
                        'cpu' => {
                                    'decoding' => '0.040',
                                    'other' => '0.030',
                                    'total' => '0.200',
                                    'encoding' => '0.130'
                                },
                        'status' => '0',
                        'idat' => '0.80',
                        'stdout' => 'pngcrush 1.6.4 blah blah',
                        'size' => '1.56'
                    }
        },
        'options' => [
                        '-d',
                        'OUT_DIR',
                        '-brute',
                        '1',
                        'remove',
                        [
                        'gAMA',
                        'cHRM',
                        'sRGB',
                        'iCCP'
                        ]
                    ],
        'in' => [
                'p.png',
                'p2.png'
                ],
        '_blah' => 'pooh!',
    };

The event handler set up to handle the event which you've specified in the event argument to run() method/event will receive input in the $_[ARG0] in a form of a hashref. The possible keys/value of that hashref are as follows:

out

The out key will have a hashref as a value. The keys of that hashref will be filenames of the files which you gave as in argument to run() event/method. The values for each of these keys will either be a scalar containing an error message (if an error occurred) or a hashref containing the exact same hashref run() method of App::PNGCrush module would return. For explanation of keys/values of that hashref see run() method in documentation for App::PNGCrush module.

valid arguments to run()

    'options' => [
                    '-d',
                    'OUT_DIR',
                    '-brute',
                    '1',
                    'remove',
                    [
                    'gAMA',
                    'cHRM',
                    'sRGB',
                    'iCCP'
                    ]
                ],
    'in' => [
            'p.png',
            'p2.png'
            ],

Valid arguments to run() event/method (that is the options and in arguments) will be present in the output as well.

user defined

    { '_blah' => 'foos' }

Any arguments beginning with _ (underscore) passed into the EXAMPLE() event/method will be present intact in the result.

SEE ALSO

POE, App::PNGCrush

REPOSITORY

Fork this module on GitHub: https://github.com/zoffixznet/POE-Component-Bundle-WebDevelopment

BUGS

To report bugs or request features, please use https://github.com/zoffixznet/POE-Component-Bundle-WebDevelopment/issues

If you can't access GitHub, you can email your request to bug-POE-Component-Bundle-WebDevelopment at rt.cpan.org

AUTHOR

Zoffix Znet <zoffix at cpan.org> (http://zoffix.com/, http://haslayout.net/)

LICENSE

You can use and distribute this module under the same terms as Perl itself. See the LICENSE file included in this distribution for complete details.