Case in point, the
Net::IP module. The documentation looks nice. It handles IPv6 and IPv4 addresses. It looks clean and simple.
Then, I decided I would like to be able to have IPv4 mapped IPv6 addresses match the IPv4 address ranges I'm singling out for special treatment. So I look into its tool for extracting an IPv4 address from an IPv6 address.
ip_get_embedded_ipv4 doesn't seem to work on IPv6 addresses created with 'new'. It only works on IPv6 addresses represented as strings. This leads me to dive into the implementation.
I discover that the is no coherent internal representation. Just a lot of different attributes that are used at different times for different purposes and are converted from one another as needed.
Additionally, there appears to be no way to import particular symbols of certain classes from the module. You have to import them using the import statements specified in the documentation or take your chances on whether or not it will work. This is because the import mechanism and which symbols are global or not is handled in a fairly ad-hoc sort of way and re-implemented in each module according to the whims of the author.
It's really quite surprising the module works at all. And I'm left feeling like I really ought to re-write it if I want something I can count on.
In reality, looking at the module's implementation was a mistake. This is always what happens to me when I look at a perl module. Either it works in a completely mysterious way using language mechanisms I've never seen used before, or it works in a way that's totally broken and practically guaranteed to break for any use that varies from the specific use-cases described in the documentation. Frequently both are the case. Aigh! Run away!
I hope I can convince my new workplace to stop using perl.