Domain...Suffix(3pm)

💖 Domain::PublicSuffix — the perl one, manual page 3pm 💖

okay bestie, buckle up, because this is the page about Domain::PublicSuffix — a Perl module whose whole entire job is parsing a domain all the way down to its root 🌸. It lives in the User Contributed Perl Documentation section of the manual (section 3pm, iykyk) and honestly? it's giving ✨ very useful ✨.

---

🌈 NAME 🌈

Domain::PublicSuffix — literally just: Parse a domain down to root. That's the whole vibe. 🎀

---

🦋 SYNOPSIS 🦋

here's how you actually use it, no cap:

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

my $suf = $suffix->suffix();
# $suf now contains co.uk

my $tld = $suffix->tld();
# $tld now contains uk

see how clean that is? obsessed. 😌✨

---

💅 DESCRIPTION 💅

so this module uses the effective_tld_names.dat file that Mozilla provides as its way of reducing a fully qualified domain name all the way down to the absolute root. The Mozilla PublicSuffix file is an open source, fully documented format that shows absolute root TLDs — and the main reason it exists is so Mozilla's browser products can figure out how far a cookie's security boundaries go. 🍪🔒

Now, when this module is looking for that file, it goes hunting through etc directories in these spots:

• /usr/share/publicsuffix
• /usr
• /usr/local
• /opt/local

...searching for the effective_tld_names.dat file. If it can't find one anywhere, it loads a default file from Domain::PublicSuffix::Default, which is current as of the time the module was released. If you wanna override the data file path yourself, just hand the new() method a 'data_file' argument. easy. 🫶

When you create a new PublicSuffix object, the module loads the data file you specified and uses the internal structure to parse every domain you send to the get_root_domain method. Want it to re-parse the file? You have to destroy the object and make a brand new one, OR call the _parse_data_file method directly — though, bestie, that is not recommended. 🙈

---

⭐ PUBLIC ACCESSORS ⭐

• error() — if a parse fails, this holds a human-readable error string. your little diagnostic bestie. 😭
• suffix() — returns the effective tld of the last domain that got parsed. For the domain 'google.co.uk', this would hand you back 'co.uk'.
• tld() — returns the true DNS tld of the last parsed domain. For the domain 'google.co.uk', this would hand you back 'uk'. notice the difference, bestie, it matters 👑

---

👑 PUBLIC METHODS 👑

new(\%arguments)

Instantiate a PublicSuffix object. Real talk: it is best to instantiate an object once and then keep calling get_root_domain on it, instead of continually recreating the object — because the data file gets read and parsed at instantiation time. so like, don't be wasteful. 💀

It can take a hashref of arguments:

• data_file — a fully qualified path, to override the effective_tld_names.dat file.
• use_default — use the provided publicsuffix file and don't go searching for any other files. 🎀
• domain_allow_underscore — a flag that says underscores should be allowed in hostnames (which is, lowkey, contra to the RFCs). Default: undef.
• allow_unlisted_tld — a flag that says unlisted TLDs should be passed through. This follows the spec as listed on publicsuffix.org, but it is not how this module works by default, nor how it worked before 0.16. Default: undef.

get_root_domain( $domain )

Give it a fully qualified domain name, and it returns the parsed root domain name. If something goes wrong parsing the domain you gave it, it returns undefined and fills the error accessor with a human-readable error string. 🌸

---

🔥 SEE ALSO 🔥

• GitHub

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

• Current List:

<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>. I will be notified, and then you'll automatically be notified of progress on your bug as I make changes. teamwork, fr fr. 🫶

---

🧚 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>

• AnnoCPAN: Annotated CPAN documentation

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

• CPAN Ratings

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

• Search CPAN

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

---

🎀 CONTRIBUTORS 🎀

• dkg: Daniel Kahn Gillmor
• gavinc: Gavin Carr
• jwieland: Jason Wieland

---

💜 COPYRIGHT & LICENSE 💜

Copyright 2008-2020 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.

---

and that's the whole page, bestie! 🌈 this one's perl v5.40.0, dated 2024-12-07, from Domain...Suffix(3pm) — slay, go parse some domains, and remember: re-parse only by making a whole new object, periodt. 💅✨🦋