Net::XWhois(3pm)

✨ NAME ✨

Net::XWhois — Whois Client Interface for Perl5. That's it, that's the whole thing, and it goes so hard 💅

(this one lives in the 3pm manual, just so you know where you found it 🎀)

---

💖 SYNOPSIS 💖

use Net::XWhois;

$whois = new Net::XWhois Domain => "vipul.net" ;
$whois = new Net::XWhois Domain => "bit.ch",
                         Server => "domreg.nic.ch",
                         Retain => 1,
                         Parser => {
                            nameservers => 'nserver:\s+(\S+)',
                         };

---

🦋 DESCRIPTION 🦋

okay so, Net::XWhois is a generic client framework for doing Whois queries and parsing whatever the server yells back at you. Two jobs, one class, iconic behaviour honestly ✨

The class keeps an array of top level domains and the whois servers that go with them. That means it can handle requests for different tlds transparently, picking the right server for each tld all by itself. So the server details are completely hidden from you, the user — and "vipul.net" (from InterNIC), gov.ru (from RIPE) and "bit.ch" (from domreg.nic.ch) all get queried in exactly the same way. no cap 🫶

You can override that behaviour by specifying different bindings when you construct the object, or by registering associations with the class. Go look at register_associations() and new() for the deets.

One of the more important goals of this module (main character goal, honestly) is to let people design consistent and predictable interfaces to incompatible whois response formats. Bestie, the Whois RFC (954) does NOT define a template for presenting server data. Not even a little. So there is a massive variation in layout styles and in content served across servers. it's giving chaos 😭

(There IS a newer standard though — it's called RPSL (RFC2622), and it's used by RIPE (http://www.ripe.net), the European main whois server. slay.)

So to deal with all that mess, Net::XWhois maintains another set of tables — parsing rulesets — for a few popular response formats. (See %PARSERS.) These parsing tables hold section names (labels) plus regular expressions that match the corresponding section text. Then you get at that section text "via" the labels, which are available as data instance methods at runtime. And because the labels follow a consistent naming scheme, semantically related info that's encoded in totally different formats can be reached with the same methods. chef's kiss 💅

---

🌸 CONSTRUCTOR 🌸

• new () — Creates a Net::XWhois object. It takes one optional argument, a hash, that says which domain name you want to query. If you do hand it a name, it calls lookup(). That argument hash can also specify a whois server, a parsing rule-set, or a parsing rule-set format. (Go peek at personality().) And if you just... don't pass anything? You get an "empty" object, which is still useful for getting at class data. no thoughts, just class data ✨
• personality () — Changes up an object's personality, as one does. Takes a hash with the following arguments. (Note: you can also pass these same arguments to the constructor.)
  • Domain — the domain name to be queried.
  • Server — the server to query.
  • Parser — the Parsing Rule-set. See %PARSERS.

Parser => {
  name            => 'domain:\s+(\S+)\n',
  nameservers     => 'nserver:\s+(\S+)',
  contact_emails  => 'e-mail:\s+(\S+\@\S+)',
};

• Format — a pre-defined parser format, like INTERNIC, INTERNIC_FORMAT, RIPE, RIPE_CH, JAPAN etc.

Format => 'INTERNIC_CONTACT',

• Nocache — forces XWhois to straight up ignore the cached records. 🙈
• Error — decides how a network connection error gets handled. By default Net::XWhois will croak() if it can't connect to the whois server. The Error attribute names a function call that gets invoked when a network connection error happens. Possible values are croak, carp, confess (imported from Carp.pm) and ignore (a blank function that Net::XWhois provides for you). And obviously you can write your own error handler if you want — but then you have to give a fully qualified function name. Example: main::logerr.
• Timeout — the timeout value for establishing a network connection with the server. Default is 60 seconds.

---

👑 CLASS DATA & ACCESS METHODS 👑

💜 %PARSERS

An associative array holding parsing rule-sets for all the various response formats. The keys of this array are format names, and the values are hash refs containing section labels plus the corresponding parser code. That parser code can either be a regex, or a reference to a subroutine. If it's a subroutine, the whois 'response' information is available to the sub in $_[0]. You can add and extend parsers with the register_parser() method. Also see "Data Instance Methods".

 my %PARSERS  = (
  INTERNIC => {
   contact_tech    => 'Technical Contact.*?\n(.*?)(?=\...
   contact_zone    => 'Zone Contact.*?\n(.*?)(?=\s*\n[...
   contact_billing => 'Billing Contact.*?\n(.*?)(?=\s*...
   contact_emails  => \&example_email_parser
 },
 { etc. ... },
);

sub example_email_parser {

    # Note that the default internal implemenation for
    # the INTERNIC parser is not a user-supplied code
    # block.  This is just an instructive example.

    my @matches = $_[0] =~ /(\S+\@\S+)/sg;
    return @matches;
}

See XWhois.pm for the complete definition of %PARSERS.

💜 %WHOIS_PARSER

%WHOIS_PARSER is a table that pairs every whois server up with its output format. matchmaking but for servers 💞

    my %WHOIS_PARSER = (
    'whois.ripe.net'       => 'RPSL',
    'whois.nic.mil'        => 'INTERNIC',
    'whois.nic.ad.jp'      => 'JAPAN',
    'whois.domainz.net.nz' => 'GENERIC',
    'whois.nic.gov'        => 'INTERNIC',
    'whois.nic.ch'         => 'RIPE_CH',
    'whois.twnic.net'      => 'TAIWAN',
    'whois.internic.net'   => 'INTERNIC',
    'whois.nic.net.sg'     => 'RIPE',
    'whois.aunic.net'      => 'RIPE',
    'whois.cdnnet.ca'      => 'CANADA',
    'whois.nic.uk'         => 'INTERNIC',
    'whois.krnic.net'      => 'KOREA',
    'whois.isi.edu'        => 'INTERNIC',
    'whois.norid.no'       => 'RPSL',
        ( etc.....)

Just FYI there is a plethora of output formats out there. And yes, there are RFCs on this issue — RFC2622, for instance — but there are still, like, numerous different formats being used. it's a lot 😵‍💫

💜 %DOMAIN_ASSOC

%DOMAIN_ASSOC is a table that pairs top level domain names with their respective whois servers. You'd need to modify this table if you want to extend the module to handle a new set of domain names, or if you want to alter existing info. register_association() gives you an interface to this array. See XWhois.pm for the complete definition.

    my %DOMAIN_ASSOC = (
    'al' => 'whois.ripe.net',
    'am' => 'whois.ripe.net',
    'at' => 'whois.ripe.net',
    'au' => 'whois.aunic.net',
    'az' => 'whois.ripe.net',
    'ba' => 'whois.ripe.net',
    'be' => 'whois.ripe.net',

💜 register_parser()

Extends, modifies and overrides entries in %PARSERS. It takes a hash with three keys — Name, Retain and Parser. If a format definition for the specified format already exists and the Retain key holds a true value, then the keys from the specified Parser get added onto the existing definition. A brand new definition gets created when Retain is false or not specified. glow up ✨

 my $w = new Net::Whois;
 $w->register_parser (
    Name   => "INTERNIC",
    Retain => 1,
    Parser => {
        creation_time => 'created on (\S*?)\.\n',
        some_randome_entity => \&random_entity_subroutine
    };

Instructions on how to build a workable random_entity_subroutine are available up in the %PARSERS description 👆

💜 register_association()

Overrides and adds entries to %ASSOC. It takes a hash containing representation specs for a whois server. The keys of this hash are server machine names, and the values are list-refs to the associated response formats and the top-level domains handled by those servers. See Net/XWhois.pm for more details.

 my $w = new Net::XWhois;
 $w->register_association (
     'whois.aunic.net' => [ RIPE, [ qw/au/ ] ]
 );

💜 register_cache()

By default, Net::XWhois caches all whois responses and commits them, as separate files, to /tmp/whois. register_cache () gets and sets the cache directory. Setting it to "undef" disables caching entirely.

 $w->register_cache ( "/some/place/else" );
 $w->register_cache ( undef );

---

⭐ OBJECT METHODS ⭐

💖 Data Instance Methods

You get at the whois response data through AUTOLOADED methods that you specify in the Parser. These methods return scalar data or list data depending on the context. contextual queen 👑

The Internic Parser provides the following methods:

• name() — Domain name.
• status() — Domain Status, when it's provided. And when the domain is on hold, this method returns the string "On Hold".
• nameservers() — Nameservers along with their IPs.
• registrant — Registrant's name and address.
• contact_admin() — Administrative Contact.
• contact_tech() — Technical Contact.
• contact_zone() — Zone Contact.
• contact_billing() — Billing Contact.
• contact_emails() — List of email addresses of contacts.
• contact_handles() — List of contact handles in the response. Contact and Domain handles are valid query data, so you can use them instead of contact and domain names.
• domain_handles() — List of domain handles in the response. Can be used to sort out responses that contain multiple domain names.

💖 lookup()

Does a whois lookup on the specified domain. It takes the same arguments as new().

 my $w = new Net::XWhois;
 $w->lookup ( Domain => "perl.com" );
 print $w->response ();

---

🌈 EXAMPLES 🌈

Go look at the example programs that ship with this package, bestie:

• whois — a replacement for the standard RIPE/InterNIC whois client.
• creation — overrides the Parser value at object init and fetches the Creation Time of an InterNIC domain.
• creation2 — does the exact same thing, but by extending the Class Parser instead.
• contacts — queries and prints info about a domain's Tech/Billing/Admin contacts.

contribs/ contains parsers for several whois servers which have not been patched into the module. 💅

---

🎀 AUTHOR 🎀

Vipul Ved Prakash <mail@vipul.net>

✨ THANKS ✨

ok so this page literally would not exist without these absolute legends, and we are giving them their flowers 💐💖 They sent patches, bug reports, and so many cogent suggestions (their words, and honestly iconic of them):

• Curt Powell <curt.powell@sierraridge.com>
• Matt Spiers <matt@pavilion.net>
• Richard Dice <rdice@pobox.com>
• Robert Chalmers <robert@chalmers.com.au>
• Steinar Overbeck Cook <steinar@balder.no>
• Steve Weathers <steve@domainit.com>
• Robert Puettmann <rpuettmann@ipm.net>
• Martin H . Sluka" <martin@sluka.de>
• Rob Woodard <rwoodard15@attbi.com>
• Jon Gilbert
• Erik Aronesty

(and yes, that stray quote mark after Sluka is in the original, we are not touching it, it's part of the lore 🫶)

for patches, bug-reports and many cogent suggestions. besties fr fr 🙌

---

🌈 MAILING LIST 🌈

big news: Net::XWhois development has moved to the sourceforge mailing list:

xwhois-devel@lists.sourceforge.net

Please send all Net::XWhois related communication directly to the list address. no sliding into anyone's DMs, the list is the group chat now 💅

The subscription interface is at:

http://lists.sourceforge.net/mailman/listinfo/xwhois-devel

---

👑 SEE ALSO 👑

the required reading, the canon, the syllabus 📚✨

• RFC 954 <http://www.faqs.org/rfcs/rfc954.html>
• RFC 2622 <http://www.faqs.org/rfcs/rfc2622.html>

go read them, iykyk 🦋

---

🎀 COPYRIGHT 🎀

Copyright (c) 1998-2001 Vipul Ved Prakash. All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

translation bestie: it's free, it's open, remix it, ship it, just keep the same terms as Perl itself, periodt 💅

---

and that's a wrap on the whole page, you made it to the end, so proud of you 🥹💖 This bad boy is Net::XWhois(3pm), built from perl v5.36.0, dated 2022-10-13 — go forth and whois responsibly, bestie 🌸🦋✨