File Coverage

lib/HTTP/Promise/Headers/Accept.pm
Criterion Covered Total %
statement 35 37 94.5
branch 5 8 62.5
condition 4 8 50.0
subroutine 13 15 86.6
pod 8 8 100.0
total 65 76 85.5


line stmt bran cond sub pod time code
1             ##----------------------------------------------------------------------------
2             ## Asynchronous HTTP Request and Promise - ~/lib/HTTP/Promise/Headers/Accept.pm
3             ## Version v0.1.0
4             ## Copyright(c) 2022 DEGUEST Pte. Ltd.
5             ## Author: Jacques Deguest <jack@deguest.jp>
6             ## Created 2022/05/06
7             ## Modified 2022/05/06
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::Accept;
15             BEGIN
16             {
17 3     3   263315 use strict;
  3         14  
  3         92  
18 3     3   18 use warnings;
  3         5  
  3         89  
19 3     3   14 use warnings::register;
  3         8  
  3         443  
20 3     3   19 use parent qw( HTTP::Promise::Headers::Generic );
  3         11  
  3         20  
21 3     3   221 our $VERSION = 'v0.1.0';
22             };
23              
24 3     3   27 use strict;
  3         14  
  3         74  
25 3     3   16 use warnings;
  3         8  
  3         875  
26              
27             sub init
28             {
29 15     15 1 3391 my $self = shift( @_ );
30 15         937 $self->{_qv_elements} = [];
31 15 50 66     151 @_ = () if( @_ == 1 && $self->_is_a( $_[0] => 'Module::Generic::Null' ) );
32 15 100       316 if( @_ )
33             {
34 10         50 my $val = shift( @_ );
35 10 50 33     80 return( $self->error( "No value was provided." ) ) if( !defined( $val ) || !length( $val ) );
36 10   50     98 my $choices = $self->_parse_quality_value( $val ) ||
37             return( $self->pass_error );
38 10         133 $self->elements( $choices );
39             }
40 15 50       3407 $self->SUPER::init( @_ ) || return( $self->pass_error );
41 15         117 $self->_field_name( 'Accept' );
42 15         12192 return( $self );
43             }
44              
45 0     0 1 0 sub add { return( shift->_qv_add( @_ ) ); }
46              
47 15     15 1 5778 sub as_string { return( shift->_qv_as_string( @_ ) ); }
48              
49 49     49 1 119896 sub elements { return( shift->_qv_elements( @_ ) ); }
50              
51 5     5 1 3944 sub get { return( shift->_qv_get( @_ ) ); }
52              
53 0     0 1 0 sub match { return( shift->_qv_match( @_ ) ); }
54              
55 1     1 1 1281 sub remove { return( shift->_qv_remove( @_ ) ); }
56              
57 1     1 1 975 sub sort { return( shift->_qv_sort( @_ ) ); }
58              
59             1;
60             # NOTE: POD
61             __END__
62              
63             =encoding utf-8
64              
65             =head1 NAME
66              
67             HTTP::Promise::Headers::Accept - Accept Header Field
68              
69             =head1 SYNOPSIS
70              
71             use HTTP::Promise::Headers::Accept;
72             my $ac = HTTP::Promise::Headers::Accept->new ||
73             die( HTTP::Promise::Headers::Accept->error, "\n" );
74             my $ac = HTTP::Promise::Headers::Accept->new( 'text/html, application/json, application/xml;q=0.9, */*;q=0.8' ) ||
75             die( HTTP::Promise::Headers::Accept->error, "\n" );
76             $ac->add( 'text/html' );
77             $ac->add( 'application/json' => 0.7 );
78             $h->accept( $ac->as_string ); Accept: text/html, application/json;q=0.7
79             # or
80             $h->accept( "$ac" );
81             my $qv_elements = $ac->elements;
82             my $obj = $ac->get( 'text/html' );
83             # change the weight
84             $obj->value( 0.3 );
85             $ac->remove( 'text/html' );
86             my $sorted_objects = $ac->sort;
87             my $asc_sorted = $ac->sort(1);
88             # Returns a Module::Generic::Array object
89             my $ok = $ac->match( [qw( application/json text/html )] );
90              
91             =head1 VERSION
92              
93             v0.1.0
94              
95             =head1 DESCRIPTION
96              
97             The following description is taken from Mozilla documentation.
98              
99             Accept: image/*
100             Accept: text/html
101             Accept: */*
102             Accept: text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8
103              
104             See L<rfc7231 section 5.3.2|https://tools.ietf.org/html/rfc7231#section-5.3.2> and L<rfc7231, section 5.3.5|https://tools.ietf.org/html/rfc7231#section-5.3.5>
105              
106             =head1 METHODS
107              
108             =head2 add
109              
110             Provided with a mime type and a quality weight (q-value), and this will push a new C<HTTP::Promise::Field::QualityValue> object to the stack of elements.
111              
112             =head2 as_string
113              
114             Returns a string representation of the C<Accept> object.
115              
116             =head2 elements
117              
118             Retrieve an L<array object|Module::Generic::Array> of C<HTTP::Promise::Field::QualityValue> objects.
119              
120             =head2 get
121              
122             Provided with a mime type and this returns its C<HTTP::Promise::Field::QualityValue> object entry, if any. If nothing corresponding was found, it returns an empty string (false, but not C<undef>)
123              
124             =head2 match
125              
126             Provided with a either an array reference of proposed values, or a string, or something that stringifies, and this will return an L<array object|Module::Generic::Array> of values that match the supported one and in the order of preference.
127              
128             For example, consider:
129              
130             Accept: text/html;q=0.3, application/json;q=0.7; text/plain;q=0.2
131              
132             # We prefer text/html first and application/json second
133             my $ok = $ac->match( [qw( text/html application/json )] );
134              
135             C<$ok> would contain 2 entries: C<application/json> and C<text/html>
136              
137             # Only take the first one
138             my $mime_type = $ac->match( [qw( text/html application/json )] )->first;
139             # or get it as a list
140             my @ok_types = $ac->match( [qw( text/html application/json )] )->list;
141              
142             =head2 remove
143              
144             Provided with a mime type and this removes its C<HTTP::Promise::Field::QualityValue> object from the list of elements.
145              
146             =head2 sort
147              
148             This returns a sorted L<array object|Module::Generic::Array> of C<HTTP::Promise::Field::QualityValue> objects, based on their weight factor. If the option C<reverse> is provided and true, this will sort the elements in reverse order, that is in incremental order, from smallest to biggest quality factor.
149              
150             For example, the following:
151              
152             text/html, application/xhtml+xml, application/xml;q=0.9, image/webp, */*;q=0.8
153              
154             will be sorted as:
155              
156             text/html, application/xhtml+xml, image/webp, application/xml;q=0.9, */*;q=0.8
157              
158             =head1 AUTHOR
159              
160             Jacques Deguest E<lt>F<jack@deguest.jp>E<gt>
161              
162             =head1 SEE ALSO
163              
164             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>
165              
166             L<HTTP::Accept>
167              
168             =head1 COPYRIGHT & LICENSE
169              
170             Copyright(c) 2022 DEGUEST Pte. Ltd.
171              
172             All rights reserved.
173              
174             This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.
175              
176             =cut