WATANABE Hiroaki > PerlIO-via-Limit > PerlIO::via::Limit

Download:
PerlIO-via-Limit-0.04.tar.gz

Dependencies

Annotate this POD

Website

View/Report Bugs
Module Version: 0.04   Source  

NAME ^

PerlIO::via::Limit - PerlIO layer for length restrictions

SYNOPSIS ^

    use PerlIO::via::Limit;
    PerlIO::via::Limit->length(256);
    # - or -
    use PerlIO::via::Limit length => 256;

    # reading
    open( my $fh, "<:via(Limit)", $file );

    # writing
    open( my $fh, ">:via(Limit)", $file );

    # If you want to use various limits simultaneously
    my $limit256 = PerlIO::via::Limit->create(256);
    my $limit512 = PerlIO::via::Limit->create(512);
    open( my $fh256, "<:via($limit256)", $hoge );
    open( my $fh512, ">:via($limit512)", $fuga );

DESCRIPTION ^

PerlIO::via::Limit implements a PerlIO layer that restricts length of stream.

There is an important constraint, it is able to specify only one limit value within application because the 'length' is a class data.

The following example does not work as expected:

    PerlIO::via::Limit->length(256);
    open( my $fh1, "<:via(Limit)", $file1 );

    PerlIO::via::Limit->length(512);
    open( my $fh2, "<:via(Limit)", $file2 );

    local $/ = undef;
    my $data1 = <$fh1>; 
    my $data2 = <$fh2>; 

    CORE::length($data1); # is not 256 but 512
    CORE::length($data2); # is also 512

Therefore, it is necessary to divide namespace, in order to use two or more limit values simultaneously.

    package Foo;
    use base PerlIO::via::Limit;
    
    package main;
    PerlIO::via::Limit->length(256);
    Foo->length(512);

    open( my $fh1, "<:via(Limit)", $file1 );
    open( my $fh2, "<:via(Foo)", $file2 );

    local $/ = undef;
    my $data1 = <$fh1>; 
    my $data2 = <$fh2>; 

    CORE::length($data1); # is 256
    CORE::length($data2); # is 512

Actually you do not have to code like the above, instead, the create() method supports it by simple interface.

    my $limit256 = PerlIO::via::Limit->create(256);
    my $limit512 = PerlIO::via::Limit->create(512);

    open( my $fh1, "<:via($limit256)", $file1 );
    open( my $fh2, "<:via($limit100)", $file2 );

CLASS METHODS ^

create

Create an anonymous class that is inheritable PerlIO::via::Limit.

You do not have to care about the class, only pass ':via' the returned value as it is.

It accepts an optional parameter for 'length' available.

    my $limit = PerlIO::via::Limit->create(512);
    open( my $fh, ">:via($limit)", $file );

Also it can call 'length' and 'sensitive' class methods.

    my $limit = PerlIO::via::Limit->create;
    $limit->length(256);
    $limit->sensitive(0);
    open( my $fh, ">:via($limit)", $file );

length

Limit length of stream. Default is undef that means unlimited.

sensitive

If set true value, an exception will be occurred when stream reaches limit of length. Default is false.

    use PerlIO::via::Limit sensitive => 1;

    open( my $in, "<:via(Limit)", $file ) or die;
    eval {
        while( <$in> ){
            # do something...
        }
    };if( $@ ){
        # "$in is trying to read exceeding the limit."
        warn "$@";
    }
    close $in or die;

Note that the $@ is an Exception::Class object.

BUGS ^

When the exception is thrown by sensitive option, the buffer for reading does not be filled.

REPOSITORY ^

PerlIO::via::Limit is hosted on github https://github.com/hiroaki/PerlIO-via-Limit

SEE ALSO ^

PerlIO::via

Exception::Class

AUTHOR ^

WATANABE Hiroaki <hwat@cpan.org>

LICENSE ^

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

syntax highlighting: