File Coverage

lib/HTTP/Promise/Headers/ContentRange.pm
Criterion Covered Total %
statement 57 72 79.1
branch 14 26 53.8
condition 13 29 44.8
subroutine 14 16 87.5
pod 7 7 100.0
total 105 150 70.0


line stmt bran cond sub pod time code
1             ##----------------------------------------------------------------------------
2             ## Asynchronous HTTP Request and Promise - ~/lib/HTTP/Promise/Headers/ContentRange.pm
3             ## Version v0.1.0
4             ## Copyright(c) 2022 DEGUEST Pte. Ltd.
5             ## Author: Jacques Deguest <jack@deguest.jp>
6             ## Created 2022/05/07
7             ## Modified 2022/05/07
8             ## All rights reserved.
9             ##
10             ##
11             ## This program is free software; you can redistribute it and/or modify it
12             ## under the same terms as Perl itself.
13             ##----------------------------------------------------------------------------
14             package HTTP::Promise::Headers::ContentRange;
15             BEGIN
16             {
17 3     3   3445 use strict;
  3         10  
  3         105  
18 3     3   17 use warnings;
  3         12  
  3         103  
19 3     3   16 use warnings::register;
  3         7  
  3         367  
20 3     3   143 use parent qw( HTTP::Promise::Headers::Generic );
  3         8  
  3         53  
21 3     3   266 our $VERSION = 'v0.1.0';
22             };
23              
24 3     3   17 use strict;
  3         7  
  3         56  
25 3     3   13 use warnings;
  3         5  
  3         1486  
26              
27             sub init
28             {
29 5     5 1 301166 my $self = shift( @_ );
30 5         363 $self->{range_end} = undef;
31 5         30 $self->{range_start} = undef;
32 5         24 $self->{size} = undef;
33 5         19 $self->{unit} = undef;
34 5 50 66     76 @_ = () if( @_ == 1 && $self->_is_a( $_[0] => 'Module::Generic::Null' ) );
35 5 100       122 if( @_ )
36             {
37 4         18 my $str = shift( @_ );
38 4 50       134 if( $str =~ m,^(?<unit>\S+)[[:blank:]]+(?:(?:(?<start>\d+)-(?<end>\d+))|\*)/(?<size>\d+|\*), )
39             {
40 4     1   44 $self->unit( $+{unit} );
  1         475  
  1         459  
  1         644  
41 4 100 66     4102 $self->range_start( $+{start} ) if( defined( $+{start} ) && length( $+{start} ) );
42 4 100 66     2378 $self->range_end( $+{end} ) if( defined( $+{end} ) && length( $+{end} ) );
43 4 50 33     2250 $self->size( $+{size} ) if( defined( $+{size} ) && length( $+{size} ) );
44             }
45             else
46             {
47 0         0 return( $self->error( "Unsupported Content-Range value format '$str'." ) );
48             }
49             }
50 5         2929 $self->{_init_strict_use_sub} = 1;
51 5 50       45 $self->SUPER::init( @_ ) || return( $self->pass_error );
52 5         51 $self->_field_name( 'Content-Range' );
53 5         3972 return( $self );
54             }
55              
56             sub as_string
57             {
58 5     5 1 902 my $self = shift( @_ );
59 5   50     22 my $unit = $self->unit || 'bytes';
60 5         4025 my $start = $self->range_start;
61 5         3906 my $end = $self->range_end;
62 5         3874 my $size = $self->size;
63 5         3908 my @parts = ();
64 5 100 66     51 if( defined( $start ) || defined( $end ) )
65             {
66 4 50 33     77 if( $start eq '*' && $end eq '*' )
67             {
68 0         0 push( @parts, '*' );
69             }
70             else
71             {
72 4   50     71 $start //= '*';
73 4   50     33 $end //= '*';
74 4         51 push( @parts, "${start}-${end}" );
75             }
76             }
77             else
78             {
79 1         6 push( @parts, '*' );
80             }
81 5 50       63 push( @parts, defined( $size ) ? $size : '*' );
82 5         26 return( join( ' ', $unit, join( '/', @parts ) ) );
83             }
84              
85 12     12 1 4479 sub range_end { return( shift->_set_get_scalar_as_object( 'range_end', @_ ) ); }
86              
87 13     13 1 4508 sub range_start { return( shift->_set_get_scalar_as_object( 'range_start', @_ ) ); }
88              
89 14     14 1 5353 sub size { return( shift->_set_get_scalar_as_object( 'size', @_ ) ); }
90              
91             sub start_end
92             {
93 0     0 1 0 my $self = shift( @_ );
94 0         0 my( $start, $end ) = @_;
95 0         0 $self->range_start( $start );
96 0   0     0 $self->range_end( $end // $start );
97 0         0 return( $self );
98             }
99              
100 14     14 1 3646 sub unit { return( shift->_set_get_scalar_as_object( 'unit', @_ ) ); }
101              
102             sub _set_get_number_or_wildcard
103             {
104 0     0   0 my $self = shift( @_ );
105 0   0     0 my $prop = shift( @_ ) || return( $self->error( "No property name was provided." ) );
106 0 0       0 if( @_ )
107             {
108 0         0 my $v = shift( @_ );
109 0 0       0 if( defined( $v ) )
110             {
111 0 0       0 return( $self->error( "Value provided for property \"${prop}\" is invalid. I was expecting either an integer or a wildcard." ) ) if( $v !~ /^\d+|\*$/ );
112             }
113 0         0 return( $self->_set_get_scalar_as_object( $prop => $v ) );
114             }
115 0         0 return( $self->_set_get_scalar_as_object( $prop ) );
116             }
117              
118             1;
119             # NOTE: POD
120             __END__
121              
122             =encoding utf-8
123              
124             =head1 NAME
125              
126             HTTP::Promise::Headers::ContentRange - Content-Range Header Field
127              
128             =head1 SYNOPSIS
129              
130             use HTTP::Promise::Headers::ContentRange;
131             my $range = HTTP::Promise::Headers::ContentRange->new ||
132             die( HTTP::Promise::Headers::ContentRange->error, "\n" );
133             $range->unit( 'bytes' ):
134             $range->range_start(500);
135             $range->range_end(1000);
136             $range->size(2048);
137             say $range->as_string;
138             # or
139             say "$range";
140              
141             # 416 Range Not Satisfiable
142             # <https://tools.ietf.org/html/rfc7233#section-4.4>
143             $range->start_end( undef );
144             $range->size(2048);
145             say "$range";
146             # bytes */2048
147              
148             =head1 VERSION
149              
150             v0.1.0
151              
152             =head1 DESCRIPTION
153              
154             The following description is taken from Mozilla documentation.
155              
156             Content-Range: bytes 200-1000/67589
157             # When the complete range is unknown:
158             Content-Range: bytes 42-1233/*
159              
160             # The first 500 bytes:
161             Content-Range: bytes 0-499/1234
162             # The second 500 bytes:
163             Content-Range: bytes 500-999/1234
164             # All except for the first 500 bytes:
165             Content-Range: bytes 500-1233/1234
166             # The last 500 bytes:
167             Content-Range: bytes 734-1233/1234
168             # Unsatisfiable range value
169             Content-Range: bytes */1234
170              
171             =head1 METHODS
172              
173             =head2 as_string
174              
175             Returns a string representation of the object.
176              
177             If both C<range-start> and C<range-end> properties are C<undef>, they will be replaced by a C<*> (wildcard)
178              
179             If C<size> property is C<undef> it will be replaced by a C<*> (wildcard)
180              
181             =head2 range_end
182              
183             An integer in the given unit indicating the end position (zero-indexed & inclusive) of the requested range.
184              
185             =head2 range_start
186              
187             An integer in the given unit indicating the start position (zero-indexed & inclusive) of the request range.
188              
189             =head2 size
190              
191             The total length of the document (or '*' if unknown).
192              
193             =head2 start_end
194              
195             This is a convenience method to set both the C<range-start> and C<range-end> property.
196              
197             =head2 unit
198              
199             The unit in which ranges are specified. This is usually C<bytes>.
200              
201             =head1 AUTHOR
202              
203             Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>
204              
205             =head1 SEE ALSO
206              
207             C<Accept-Range>, C<If-Range>, C<Range>
208              
209             See L<rfc7233, section 4.2|https://tools.ietf.org/html/rfc7233#section-4.2> and L<Mozilla documentation|https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Content-Range>
210              
211             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>
212              
213             =head1 COPYRIGHT & LICENSE
214              
215             Copyright(c) 2022 DEGUEST Pte. Ltd.
216              
217             All rights reserved.
218              
219             This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
220              
221             =cut