.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" ======================================================================== .\" .IX Title "Domain::PublicSuffix 3pm" .TH Domain::PublicSuffix 3pm "2021-01-31" "perl v5.32.0" "User Contributed Perl Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" Domain::PublicSuffix \- Parse a domain down to root .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& use Domain::PublicSuffix; \& \& my $suffix = Domain::PublicSuffix\->new({ \& \*(Aqdata_file\*(Aq => \*(Aq/tmp/effective_tld_names.dat\*(Aq \& }); \& my $root = $suffix\->get_root_domain(\*(Aqwww.google.com\*(Aq); \& # $root now contains "google.com" \& \& $root = $suffix\->get_root_domain(\*(Aqwww.google.co.uk\*(Aq); \& # $root now contains google.co.uk \& \& my $suf = $suffix\->suffix(); \& # $suf now contains co.uk \& \& my $tld = $suffix\->tld(); \& # $tld now contains uk .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" This module utilizes the \*(L"effective_tld_names.dat\*(R" provided by Mozilla as a way to effectively reduce a fully qualified domain name down to the absolute root. The Mozilla PublicSuffix file is an open source, fully documented format that shows absolute root TLDs, primarily for Mozilla's browser products to be able to determine how far a cookie's security boundaries go. .PP This module will attempt to search etc directories in /usr/share/publicsuffix, /usr, /usr/local, and /opt/local for the effective_tld_names.dat file. If a file is not found, a default file is loaded from Domain::PublicSuffix::Default, which is current at the time of the module's release. You can override the data file path by giving the \fBnew()\fR method a 'data_file' argument. .PP When creating a new PublicSuffix object, the module will load the data file as specified, and use the internal structure to parse each domain sent to the get_root_domain method. To re-parse the file, you must destroy and create a new object, or execute the _parse_data_file method directly, though that is not recommended. .SH "PUBLIC ACCESSORS" .IX Header "PUBLIC ACCESSORS" .IP "\fBerror()\fR" 4 .IX Item "error()" On unsuccessful parse, contains a human-readable error string. .IP "\fBsuffix()\fR" 4 .IX Item "suffix()" Returns the effective tld of the last parsed domain. For the domain \&'google.co.uk', this would return 'co.uk'. .IP "\fBtld()\fR" 4 .IX Item "tld()" Returns the true \s-1DNS\s0 tld of the last parsed domain. For the domain \&'google.co.uk', this would return 'uk'. .SH "PUBLIC METHODS" .IX Header "PUBLIC METHODS" .IP "new(\e%arguments)" 4 .IX Item "new(%arguments)" Instantiate a PublicSuffix object. It is best to instantiate an object and continue calling get_root_domain instead of continually recreating the object, as the data file is read and parsed on instantiation. .Sp Can take a hashref of arguments: .RS 4 .IP "data_file" 4 .IX Item "data_file" A fully qualified path, to override the effective_tld_names.dat file. .IP "use_default" 4 .IX Item "use_default" Use the provided publicsuffix file, do not search for any other files. .IP "domain_allow_underscore" 4 .IX Item "domain_allow_underscore" A flag to indicate that underscores should be allowed in hostnames (contra to the RFCs). Default: undef. .IP "allow_unlisted_tld" 4 .IX Item "allow_unlisted_tld" A flag to indicate that unlisted TLDs should be passed through. This follows the spec as listed on publicsuffix.org, but is not how this module works by default, or before 0.16. Default: undef .RE .RS 4 .RE .ie n .IP "get_root_domain( $domain )" 4 .el .IP "get_root_domain( \f(CW$domain\fR )" 4 .IX Item "get_root_domain( $domain )" Given a fully qualified domain name, return the parsed root domain name. Returns undefined if an error occurs parsing the given domain, and fills the error accessor with a human-readable error string. .SH "SEE ALSO" .IX Header "SEE ALSO" .IP "\(bu" 4 GitHub .Sp .IP "\(bu" 4 Current List: .Sp [mxr.mozilla.org] .IP "\(bu" 4 Mozilla Documentation: .Sp .IP "\(bu" 4 Public Info Site: .Sp .SH "BUGS" .IX Header "BUGS" Please report any bugs or feature requests to \f(CW\*(C`bug\-domain\-publicsuffix at rt.cpan.org\*(C'\fR, or through the web interface at . I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. .SH "SUPPORT" .IX Header "SUPPORT" You can find documentation for this module with the perldoc command. .PP .Vb 1 \& perldoc Domain::PublicSuffix .Ve .PP You can also look for information at: .IP "\(bu" 4 \&\s-1RT: CPAN\s0's request tracker .Sp .IP "\(bu" 4 AnnoCPAN: Annotated \s-1CPAN\s0 documentation .Sp .IP "\(bu" 4 \&\s-1CPAN\s0 Ratings .Sp .IP "\(bu" 4 Search \s-1CPAN\s0 .Sp .SH "CONTRIBUTORS" .IX Header "CONTRIBUTORS" dkg: Daniel Kahn Gillmor .PP gavinc: Gavin Carr .PP jwieland: Jason Wieland .SH "COPYRIGHT & LICENSE" .IX Header "COPYRIGHT & LICENSE" Copyright 2008\-2020 Nicholas Melnick, \f(CW\*(C`nick at abstractwankery.com\*(C'\fR. .PP This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.