blib/lib/Net/PublicSuffixList.pm

filter: Statementstmt 75.0% 90 / 120 Branchbran 60.0% 18 / 30 Conditioncond 60.0% 9 / 15 MC/DCmcdc 30.0% 3 / 10 Subroutinesub 100% 27 / 27 Podpod 100% 17 / 17 totaltotal 74.8% 164 / 219 CC 21 SCAR 22.5
CC
21
Cov
71%
fetch_list_from_net
49.3
_init
6.1
parse_list
5.0
CRAP 9.5
↑ Summary
1 package Net::PublicSuffixList;
2 5 ▶use v5.26;
Subroutine BEGIN: called CC=1 SCAR=0.0
3 5 ▶use strict;
Subroutine BEGIN: called CC=1 SCAR=0.0
4 5 ▶use experimental qw(signatures);
Subroutine BEGIN: called CC=1 SCAR=0.0
5  
6 5 ▶use warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
7 5 ▶no warnings;
Subroutine BEGIN: called CC=1 SCAR=0.0
8  
9 5 ▶use Carp qw(carp);
Subroutine BEGIN: called CC=1 SCAR=0.0
10 5 ▶use File::Basename qw(basename dirname);
Subroutine BEGIN: called CC=1 SCAR=0.0
11 5 ▶use File::Path qw(make_path);
Subroutine BEGIN: called CC=1 SCAR=0.0
12 5 ▶use File::Spec::Functions qw(catfile);
Subroutine BEGIN: called CC=1 SCAR=0.0
13  
14 5 our $VERSION = '0.504';
15  
16 =encoding utf8
17  
18 =head1 NAME
19  
20 Net::PublicSuffixList - The Mozilla Public Suffix List
21  
22 =head1 SYNOPSIS
23  
24 use Net::PublicSuffixList;
25  
26 my $psl = Net::PublicSuffixList->new;
27  
28 my $host = 'amazon.co.uk';
29  
30 # get all the suffixes in host (like, uk and co.uk)
31 my $suffixes = $psl->suffixes_in( $host );
32  
33 # get the longest suffix
34 my $suffix = $psl->longest_suffix_in( $host );
35  
36 my $hash = $psl->split_host( $host );
37  
38 =head1 DESCRIPTION
39  
40 I mostly wrote this because I was working on L<App::url> and needed a
41 way to figure out which part of a URL was the registered part and which
42 was the top-level domain.
43  
44 The Public Suffix List is essentially a self-reported collection of the
45 top-level, generic, country code, or whatever domains.
46  
47 There are other modules that try to do this, but they come with packaged
48 (old) versions of the Public Suffix List or have limited functionality.
49  
50 This module can fetch the most current one for you, use one that you
51 provide locally, or even let you completely make it up. You can add
52 entries you want but don't show up in the list, and remove ones you don't
53 think should be there.
54  
55 =over 4
56  
57 =item new
58  
59 Create the new object and specify how you'd like to get the data. The
60 network file is about 220Kb, so you might want to fetch it once, store
61 it, and then use C<local_path> to use it.
62  
63 The constructor first tries to use a local file. If you've disabled
64 that with C<no_local> or the file doesn't exist, it moves on to trying
65 the network. If you've disabled the network with C<no_net>, then it
66 complains but still returns the object. You can still construct your
67 own list with C<add_suffix>.
68  
69 Possible keys:
70  
71 list_url # the URL for the suffix list
72 local_path # the path to a local file that has the suffix list
73 no_net # do not use the network
74 no_local # do not use a local file
75 cache_dir # location to save the fetched file
76  
77 =cut
78  
79 11 ▶sub new ( $class, %args ) {
Subroutine new: called CC=1 SCAR=0.0
Pod documented
80 11 my $self = bless {}, $class;
81 11 $self->_init( \%args );
82 }
83  
84 11 ▶sub _init ( $self, $args ) {
Subroutine _init: called CC=6 SCAR=18.0
85 11 my %args = ( $self->defaults->%*, $args->%* );
86  
87 11 ▶ while( my($k, $v) = each %args ) {
Branch: 1 branch
BranchTrueFalseTotal
if (() = each %args) 55 11 66
88 55 $self->{$k} = $v;
89 55 ▶ if( $k eq 'local_path' ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($k eq "local_path") 11 44 55
90 11 $self->{local_file} = basename( $v );
91 }
92 }
93  
94 11 my $method = do {
95 11 ▶ if( ! $self->{no_local} and -e $self->local_path ) {
Branch: 2 branches
BranchTrueFalseTotal
if (not $self->{'no_local'} and -e $self->local_path) { } 2 9 11
elsif (not $self->{'no_net'}) { } 0 9 9
Condition66%2/3
not $self->{"no_local"} and -e $self->local_path
!ll&&!rl&&r
902
MC/DC50%1/2
not $self->{"no_local"} and -e $self->local_path
not $self->{"no_local"} -e $self->local_path
Truth table66%2/3
not(A) and B
A= not $self->{"no_local"}B= -e $self->local_path
ABresult
0X0
100
111
96 2 'fetch_list_from_local'
97 }
98 elsif( ! $self->{no_net} ) {
99 0 'fetch_list_from_net'
100 }
101 else {
102 9 carp "No way to fetch list! Check your settings for no_local or no_net";
103 9 return $self;
104 }
105 };
106  
107 2 my $ref = $self->$method();
108  
109 2 $self->parse_list( $ref );
110  
111 2 $self;
112 }
113  
114 =item defaults
115  
116 A hash of the default values for everything.
117  
118 =cut
119  
120 11 ▶sub defaults ( $self ) {
Subroutine defaults: called CC=1 SCAR=0.0
Pod documented
121 state $hash = {
122 list_url => $self->default_url,
123 local_path => $self->default_local_path,
124 no_net => 0,
125 no_local => 0,
126 11 cache_dir => catfile( $ENV{HOME}, '.publicsuffixlist' ),
127 };
128 11 $hash;
129 }
130  
131 =item parse_list( STRING_REF )
132  
133 Take a scalar reference to the contents of the public suffix list,
134 find all the suffices and add them to the object.
135  
136 =cut
137  
138 7 ▶sub parse_list ( $self, $list ) {
Subroutine parse_list: called CC=5 SCAR=16.1
Pod documented
139 6 ▶ unless( ref $list eq 'SCALAR' ) {
Branch: 1 branch
BranchTrueFalseTotal
unless (ref $list eq "SCALAR") 2 4 6
140 2 carp "Argument is not a scalar reference";
141 2 return;
142 }
143  
144 4 my( $line_ending ) = $$list =~ m/(\R)/;
145 4 local $/ = $line_ending;
146  
147 4 open my $string_fh, '<:utf8', $list;
148  
149 4 ▶ while( <$string_fh> ) {
Branch: 1 branch
BranchTrueFalseTotal
if (defined($_ = readline $string_fh)) 28 4 32
150 28 chomp;
151 28 ▶ next if( /\A\s*\z/ || m|\A\s*//| );
Branch: 1 branch
BranchTrueFalseTotal
if /\A\s*\z/u or m[\A\s*//]u 8 20 28
Condition100%3/3
/\A\s*\z/u or m[\A\s*//]u
l!l&&r!l&&!r
4420
MC/DC100%2/2
/\A\s*\z/u or m[\A\s*//]u
/\A\s*\z/u m[\A\s*//]u
Truth table100%3/3
A or B
A= /\A\s*\z/uB= m[\A\s*//]u
ABresult
1X1
011
000
152 20 s/\A\Q*.//;
153 20 $self->add_suffix( $_ );
154 }
155 4 $self;
156 }
157  
158 =item add_suffix( STRING )
159  
160 Add STRING to the known public suffices. This returns the object itself.
161  
162 Before this adds the suffix, it strips off leading C<*> and C<.*>
163 characters. Some sources specify C<*.foo.bar>, but this adds C<foo.bar>.
164  
165 =cut
166  
167 26 ▶sub add_suffix ( $self, $suffix ) {
Subroutine add_suffix: called CC=1 SCAR=0.0
Pod documented
168 26 $suffix =~ s/\A[*.]+//;
169 26 $self->{suffix}{$suffix}++;
170 26 $self
171 }
172  
173 =item remove_suffix( STRING )
174  
175 Remove the STRING as a known public suffix. This returns the object
176 itself.
177  
178 =cut
179  
180 1 ▶sub remove_suffix ( $self, $suffix ) { delete $self->{suffix}{$suffix}; $self }
Subroutine remove_suffix: called CC=1 SCAR=0.0
Pod documented
181  
182 =item suffix_exists( STRING )
183  
184 Return the invocant if the suffix exists, and the empty list otherwise.
185  
186 =cut
187  
188 51 ▶sub suffix_exists ( $self, $suffix ) { exists $self->{suffix}{$suffix} ? $self : () }
Subroutine suffix_exists: called CC=2 SCAR=6.9
Pod documented
Branch: 1 branch
BranchTrueFalseTotal
exists $self->{'suffix'}{$suffix} ? : 24 27 51
189  
190 =item suffixes_in( HOST )
191  
192 Return an array reference of the public suffixes in HOST, sorted from
193 shortest to longest.
194  
195 =cut
196  
197 3 ▶sub suffixes_in ( $self, $host ) {
Subroutine suffixes_in: called CC=1 SCAR=0.0
Pod documented
198 3 my @parts = reverse split /\./, $host;
199 my @suffixes =
200 6 map { $_->[0] }
201 9 grep { $_->[1] }
202 9 map { [ $_, $self->suffix_exists( $_ ) ] }
203 3 map { join '.', reverse @parts[0..$_] }
204 0 .. $#parts;
205  
206 3 \@suffixes;
207 }
208  
209 =item longest_suffix_in( HOST )
210  
211 Return the longest public suffix in HOST.
212  
213 =cut
214  
215 2 ▶sub longest_suffix_in ( $self, $host ) {
Subroutine longest_suffix_in: called CC=1 SCAR=0.0
Pod documented
216 2 $self->suffixes_in( $host )->@[-1];
217 }
218  
219 =item split_host( HOST )
220  
221 Returns a hash reference with these keys:
222  
223 host the input value
224 suffix the longest public suffix
225 short the input value with the public suffix
226 (and leading dot) removed
227  
228 =cut
229  
230 1 ▶sub split_host ( $self, $host ) {
Subroutine split_host: called CC=1 SCAR=0.0
Pod documented
231 1 my $suffix = $self->longest_suffix_in( $host );
232 1 my $short = $host =~ s/\Q.$suffix\E\z//r;
233  
234 return {
235 1 host => $host,
236 suffix => $suffix,
237 short => $short
238 }
239 }
240  
241 =item fetch_list_from_local
242  
243 Fetch the public suffix list plaintext file from the path returned
244 by C<local_path>. Returns a scalar reference to the text of the raw
245 UTF-8 octets.
246  
247 =cut
248  
249 3 ▶sub fetch_list_from_local ( $self ) {
Subroutine fetch_list_from_local: called CC=2 SCAR=6.9
Pod documented
250 3 ▶ return if $self->{no_local};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"no_local"} 1 2 3
251 2 open my $fh, '<:raw', $self->local_path;
252 2 my $data = do { local $/; <$fh> };
253 2 $self->{source} = 'local_file';
254 2 \$data;
255 }
256  
257 =item fetch_list_from_net
258  
259 Fetch the public suffix list plaintext file from the URL returned
260 by C<url>. Returns a scalar reference to the text of the raw
261 UTF-8 octets.
262  
263 If you've set C<cache_dir> in the object, this method attempts to
264 cache the response in that directory using C<default_local_file> as
265 the filename. This cache is different than C<local_file> although you
266 can use it as C<local_file>.
267  
268 =cut
269  
270 1 ▶sub fetch_list_from_net ( $self ) {
Subroutine fetch_list_from_net: called CC=7 SCAR=39.0
Pod documented
271 1 ▶ return if $self->{no_net};
Branch: 1 branch
BranchTrueFalseTotal
if $self->{"no_net"} 1 0 1
272 0 state $rc = require Mojo::UserAgent;
273 0 state $ua = Mojo::UserAgent->new;
274  
275 0 my $path = catfile( $self->{cache_dir}, $self->default_local_file );
276 0 my $local_last_modified = (stat $path)[9];
277 0 my $headers = {};
278  
279 0 ▶ if( $self->{cache_dir} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"cache_dir"}) 0 0 0
280 0 make_path $self->{cache_dir};
281 0 ▶ if( $local_last_modified ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($local_last_modified) 0 0 0
282 0 $headers->{'If-Modified-Since'} = Mojo::Date->new($local_last_modified);
283 }
284 }
285  
286 0 my $tx = $ua->get( $self->url() => $headers );
287  
288 0 my $body;
289 0 ▶ if( $tx->result->code eq '304' ) {
Branch: 2 branches
BranchTrueFalseTotal
if ($tx->result->code eq '304') { } 0 0 0
elsif ($tx->result->code eq '200') { } 0 0 0
290 0 open my $fh, '<:raw', $path;
291 0 $body = do { local $/; <$fh> };
292 0 close $fh;
293 0 $self->{source} = 'net_cached';
294 }
295 elsif( $tx->result->code eq '200' ) {
296 0 $body = eval { $tx->result->body };
297  
298 0 my $date = Mojo::Date->new(
299 $tx->result->headers->last_modified,
300 $tx->result->headers->date,
301 0
302 );
303  
304 0 ▶ if( $self->{cache_dir} ) {
Branch: 1 branch
BranchTrueFalseTotal
if ($self->{"cache_dir"}) 0 0 0
305 0 open my $fh, '>:raw', $path;
306 0 print { $fh } $body;
307 0 close $fh;
308 0 utime $date->epoch, $date->epoch, $path;
309 }
310  
311 0 $self->{source} = 'net';
312 }
313  
314 0 return \$body;
315 }
316  
317 =item url
318  
319 Return the configured URL for the public suffix list.
320  
321 =cut
322  
323 2 ▶sub url ( $self ) {
Subroutine url: called CC=2 SCAR=7.2
Pod documented
324 2 ▶ $self->{list_url} // $self->default_url
Condition66%2/3
$self->{"list_url"} // $self->default_url
l!l&&r!l&&!r
110
MC/DC0%0/2
$self->{"list_url"} // $self->default_url
$self->{"list_url"} $self->default_url
Truth table66%2/3
A // B
A= $self->{"list_url"}B= $self->default_url
ABresult
1X1
011
000
325 }
326  
327 =item default_url
328  
329 Return the default URL for the public suffix list.
330  
331 =cut
332  
333 5 ▶sub default_url ( $self ) {
Subroutine default_url: called CC=1 SCAR=0.0
Pod documented
334 5 'https://publicsuffix.org/list/public_suffix_list.dat'
335 }
336  
337 =item local_path
338  
339 Return the configured local path for the public suffix list.
340  
341 =cut
342  
343 5 ▶sub local_path ( $self ) {
Subroutine local_path: called CC=2 SCAR=9.2
Pod documented
344 5 ▶ $self->{local_path} // $self->default_local_path
Condition33%1/3
$self->{"local_path"} // $self->default_local_path
l!l&&r!l&&!r
500
MC/DC0%0/2
$self->{"local_path"} // $self->default_local_path
$self->{"local_path"} $self->default_local_path
Truth table33%1/3
A // B
A= $self->{"local_path"}B= $self->default_local_path
ABresult
1X1
011
000
345 }
346  
347 =item default_local_path
348  
349 Return the default local path for the public suffix list.
350  
351 =cut
352  
353 3 ▶sub default_local_path ( $self ) {
Subroutine default_local_path: called CC=1 SCAR=0.0
Pod documented
354 3 my $this_file = __FILE__;
355 3 my $this_dir = dirname( $this_file );
356 3 my $file = catfile( $this_dir, $self->default_local_file );
357 }
358  
359 =item local_file
360  
361 Return the configured filename for the public suffix list.
362  
363 =cut
364  
365 1 ▶sub local_file ( $self ) {
Subroutine local_file: called CC=2 SCAR=9.2
Pod documented
366 1 ▶ $self->{local_file} // $self->default_local_file
Condition33%1/3
$self->{"local_file"} // $self->default_local_file
l!l&&r!l&&!r
100
MC/DC0%0/2
$self->{"local_file"} // $self->default_local_file
$self->{"local_file"} $self->default_local_file
Truth table33%1/3
A // B
A= $self->{"local_file"}B= $self->default_local_file
ABresult
1X1
011
000
367 }
368  
369 =item default_local_file
370  
371 Return the default filename for the public suffix list.
372  
373 =cut
374  
375 3 ▶sub default_local_file ( $self ) {
Subroutine default_local_file: called CC=1 SCAR=0.0
Pod documented
376 3 'public_suffix_list.dat'
377 }
378  
379 =back
380  
381 =head1 TO DO
382  
383  
384 =head1 SEE ALSO
385  
386 L<Domain::PublicSuffix>, L<Mozilla::PublicSuffix>, L<IO::Socket::SSL::PublicSuffix>
387  
388 L<https://publicsuffix.org/list/public_suffix_list.dat>
389  
390 =head1 SOURCE AVAILABILITY
391  
392 This source is in Github:
393  
394 https://github.com/briandfoy/net-publicsuffixlist
395  
396 =head1 AUTHOR
397  
398 brian d foy, C<< <briandfoy@pobox.com> >>
399  
400 =head1 COPYRIGHT AND LICENSE
401  
402 Copyright © 2020-2026, brian d foy, All Rights Reserved.
403  
404 You may redistribute this under the terms of the Artistic License 2.0.
405  
406 The public suffix list is Mozilla Public License 2.0
407  
408 =cut
409  
410 5 1;
↑ Summary