NAME

       Domain::PublicSuffix - Parse a domain down to root

SYNOPSIS

        use Domain::PublicSuffix;

        my $suffix = Domain::PublicSuffix->new({
                'data_file' => '/tmp/effective_tld_names.dat'
        });
        my $root = $suffix->get_root_domain('www.google.com');
        # $root now contains "google.com"

        $root = $suffix->get_root_domain('www.google.co.uk');
        # $root now contains google.co.uk

DESCRIPTION

       This module utilizes the "effective_tld_names.dat" 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.

       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 new() method a 'data_file' argument.

       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.

PUBLIC ACCESSORS

       error()
           On unsuccessful parse, contains a human-readable error string.

       suffix()
           Returns the effective tld of the last parsed domain. For the domain 'google.co.uk', this would return
           'co.uk'.

       tld()
           Returns  the true DNS tld of the last parsed domain. For the domain 'google.co.uk', this would return
           'uk'.

PUBLIC METHODS

       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.

           Can take a hashref of arguments:

           data_file
               A fully qualified path, to override the effective_tld_names.dat file.

           domain_allow_underscore
               A flag to indicate that underscores should be allowed in hostnames (contra to the RFCs). Default:
               undef.

       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.

SEE ALSO

       •   GitHub

           http://www.github.com/nmelnick/Domain-PublicSuffix            <http://www.github.com/nmelnick/Domain-
           PublicSuffix>

       •   Current List:

           http://mxr.mozilla.org/mozilla-central/source/netwerk/dns/effective_tld_names.dat?raw=1
           <http://mxr.mozilla.org/mozilla-central/source/netwerk/dns/effective_tld_names.dat?raw=1>
           [mxr.mozilla.org]

       •   Mozilla Documentation:

           <http://wiki.mozilla.org/Gecko:TLD_Service>

       •   Public Info Site:

           <http://publicsuffix.org/>

BUGS

       Please  report  any  bugs or feature requests to "bug-domain-publicsuffix at rt.cpan.org", or through the
       web        interface        at         http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Domain-PublicSuffix
       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Domain-PublicSuffix>.   I  will  be  notified,  and  then
       you'll automatically be notified of progress on your bug as I make changes.

SUPPORT

       You can find documentation for this module with the perldoc command.

               perldoc Domain::PublicSuffix

       You can also look for information at:

       •   RT: CPAN's request tracker

           http://rt.cpan.org/NoAuth/Bugs.html?Dist=Domain-PublicSuffix
           <http://rt.cpan.org/NoAuth/Bugs.html?Dist=Domain-PublicSuffix>

       •   AnnoCPAN: Annotated CPAN documentation

           http://annocpan.org/dist/Domain-PublicSuffix <http://annocpan.org/dist/Domain-PublicSuffix>

       •   CPAN Ratings

           http://cpanratings.perl.org/d/Domain-PublicSuffix <http://cpanratings.perl.org/d/Domain-PublicSuffix>

       •   Search CPAN

           http://search.cpan.org/dist/Domain-PublicSuffix <http://search.cpan.org/dist/Domain-PublicSuffix>

CONTRIBUTORS

       dkg: Daniel Kahn Gillmor

       gavinc: Gavin Carr

       jwieland: Jason Wieland

COPYRIGHT & LICENSE

       Copyright 2008-12 Nicholas Melnick, "nick at abstractwankery.com".

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

perl v5.14.2                                       2013-03-18                          Domain::PublicSuffix(3pm)