File Coverage

lib/HTTP/Promise/Headers/Range.pm

Criterion	Covered	Total	%
statement	70	73	95.8
branch	11	16	68.7
condition	7	10	70.0
subroutine	20	22	90.9
pod	5	5	100.0
total	113	126	89.6

##----------------------------------------------------------------------------
## Asynchronous HTTP Request and Promise - ~/lib/HTTP/Promise/Headers/Range.pm
## Version v0.1.0
## Copyright(c) 2022 DEGUEST Pte. Ltd.
## Author: Jacques Deguest <[e-mail]>
## Created 2022/05/08
## Modified 2022/05/08
## All rights reserved.
##
##
## This program is free software; you can redistribute  it  and/or  modify  it
## under the same terms as Perl itself.
##----------------------------------------------------------------------------
package HTTP::Promise::Headers::Range;
BEGIN
{
    use strict;
    use warnings;
    use warnings::register;
    use parent qw( HTTP::Promise::Headers::Generic );
    our $VERSION = 'v0.1.0';
};

use strict;
use warnings;

sub init
{
    my $self = shift( @_ );
    $self->{ranges} = [];
    $self->{unit}   = 'bytes';
    @_ = () if( @_ == 1 && $self->_is_a( $_[0] => 'Module::Generic::Null' ) );
    if( @_ )
    {
        my $this = shift( @_ );
        my( $unit, $ref );
        if( $self->_is_array( $this ) )
        {
            $ref = $this;
        }
        else
        {
            return( $self->error( "Bad argument provided '$this'. You can provide either an array reference or a string." ) ) if( ref( $this ) && !overload::Method( $this, '""' ) );
            $this =~ s/^[[:blank:]\h]+|[[:blank:]\h]+$//g;
            if( $this =~ s/^([a-zA-Z][a-zA-Z\_]+)[[:blank:]\h]*=[[:blank:]\h]*// )
            {
                $unit = $1;
            }
            $ref = [split( /[[:blank:]\h]*,[[:blank:]\h]*/, "$this" )];
        }
        my $ranges = $self->new_array;
        foreach( @$ref )
        {
            my( $start, $end ) = split( /[[:blank:]\h]*-[[:blank:]\h]*/ );
            $start = undef if( !length( $start ) );
            $end   = undef if( !length( $end ) );
            my $range = HTTP::Promise::Headers::Range::StartEnd->new( $start, $end );
            $ranges->push( $range );
        }
        $self->ranges( $ranges );
    }
    $self->{_init_strict_use_sub} = 1;
    $self->SUPER::init( @_ ) || return( $self->pass_error );
    $self->_field_name( 'Range' );
    return( $self );
}

sub as_string
{
    my $self = shift( @_ );
    # In the sprintf, we use %s and not %d, because start or end may be undef, and it would inadvertently result in 0
    return( $self->unit->scalar . '=' . $self->ranges->map(sub{ sprintf( '%s-%s', ( $_->start // '' ), ( $_->end // '' ) ); })->join( ', ' )->scalar );
}

sub new_range { HTTP::Promise::Headers::Range::StartEnd->new( @_ ) };

sub ranges { return( shift->_set_get_array_as_object( 'ranges', @_ ) ); }

sub unit { return( shift->_set_get_scalar_as_object( 'unit', @_ ) ); }

{
    package
        HTTP::Promise::Headers::Range::StartEnd;
    BEGIN
    {
        use strict;
        use warnings;
        use parent qw( Module::Generic );
    };
    use strict;
    use warnings;

    sub init
    {
        my $self = shift( @_ );
        my @args = @_;
        @$self{qw( start end )} = splice( @_, 0, 2 );
        return( $self->SUPER::init( @_ ) );
    }

    sub end { return( shift->_set_get_number( 'end', @_ ) ); }

    sub start { return( shift->_set_get_number( 'start', @_ ) ); }
}

1;
# NOTE: POD
__END__

=encoding utf-8

=head1 NAME

HTTP::Promise::Headers::Range - Range Header Field

=head1 SYNOPSIS

    use HTTP::Promise::Headers::Range;
    my $range = HTTP::Promise::Headers::Range->new ||
        die( HTTP::Promise::Headers::Range->error, "\n" );
    $range->unit( 'bytes' ):
    $range->ranges->push( $range->new_range( 200, 1000 ) );
    my $start = $range->ranges->first->start; # 200
    my $end = $range->ranges->first->end; # 1000
    $range->ranges->push( $range->new_range( 1001, 2000 ) );
    say $range->as_string;
    # or
    say "$range";
    # bytes=200-1000, 1001-2000

=head1 VERSION

    v0.1.0

=head1 DESCRIPTION

The following is an extract from Mozilla documentation.

The Range HTTP request header indicates the part of a document that the server should return.

Example:

    # Getting multiple ranges
    Range: bytes=200-1000, 2000-6576, 19000-
    # The last 500 bytes
    Range: bytes=0-499, -500

    Range: bytes=200-
    Range: bytes=200-1000
    Range: bytes=200-1000, 1001-2000
    Range: bytes=200-1000, 1001-2000, 2001-3000
    Range: bytes=-4321

=head1 METHODS

=head2 as_string

Returns a string representation of the C<Range> object.

=head2 new_range

Provided with a start and and offset, and this will return a new C<HTTP::Promise::Headers::Range::StartEnd> object.

This object has two methods: C<start> and C<end> each capable of setting or returning its value, which may be C<undef>

=head2 ranges

Sets or gets the L<array object|Module::Generic::Array> that contains all the C<HTTP::Promise::Headers::Range::StartEnd> objects (see below for a descriptions). Thus you can use all the methods from L<Module::Generic::Array> to manipulate the range objects.

=head2 unit

The unit in which ranges are specified. This is usually C<bytes>.

=head1 HTTP::Promise::Headers::Range::StartEnd

=head2 end

Sets or gets the end of the range as a L<number object|Module::Generic::Number>

=head2 start

Sets or gets the start of the range as a L<number object|Module::Generic::Number>

=head1 AUTHOR

Jacques Deguest E<lt>F<[e-mail]>E<gt>

=head1 SEE ALSO

See also L<rfc7233, section 3.1|https://tools.ietf.org/html/rfc7233#section-3.1> and L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Range>

L<HTTP::Promise>, L<HTTP::Promise::Request>, L<HTTP::Promise::Response>, L<HTTP::Promise::Message>, L<HTTP::Promise::Entity>, L<HTTP::Promise::Headers>, L<HTTP::Promise::Body>, L<HTTP::Promise::Body::Form>, L<HTTP::Promise::Body::Form::Data>, L<HTTP::Promise::Body::Form::Field>, L<HTTP::Promise::Status>, L<HTTP::Promise::MIME>, L<HTTP::Promise::Parser>, L<HTTP::Promise::IO>, L<HTTP::Promise::Stream>, L<HTTP::Promise::Exception>

=head1 COPYRIGHT & LICENSE

Copyright(c) 2022 DEGUEST Pte. Ltd.

All rights reserved.

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

=cut