How do I choose a package name for a custom Perl module that does not collide with builtin or CPAN packages names?

Question

I have read the perldoc on modules, but I don't see a recommendation on naming a package so it won't collide with builtin or CPAN module/package names.

In the past, to develop a local Session.pm module, I have created a local directory using my company's name, such as:

package Company::Session;

... and Session.pm would be found in directory Company/.

But I'm just not a fan of this naming convention. I would rather name the package hierarchy closer to the functionality of the code. But that's how it's done on CPAN generally...

I feel like I am missing something fundamental. I also looked in Damian's Perl Best Practices but I may not have been looking in the right place...

Any recommendations on avoiding package namespace collisions the right way?

Update w/ Related Question: if there is a package name conflict, how does Perl choose which one to use? Thanks everyone.

Answer 1

What's wrong with just picking a name for your package that you like and then googling "perl the-name-you-picked"?

Answer 2

If you need the maximum level of certainty that your module name will not conflict with someone else's you can take a page from Java's book: name the module with the name of the companies domain. So if you work for Example, Inc. and their domain name is example.com, you would name your HTML parser module Com::Example::HTML::Parser or Example::Com::HTML::Parser. The benefit of the first is that if you have multiple subunits they can all have their own name space, but the modules will still sort together:

• Com::Example::Biz::FindCustomers
• Com::Example::IT::ParseLogs
• Com::Example::QA::TestServer

but it does look odd at first.

Answer 3

There is nothing wrong with naming your internal modules after your company; I always do this. 90% of my code ends up on CPAN, so it has "normal" names, but the internal stuff is always starts with ClientName::.

I'm sure everyone else does this too.

Answer 4

The namespace Local:: has been reserved for just this purpose. No module that starts with that prefix will be accepted to CPAN or the core. Alternatively, you can use an underscore in the top-level name (like My_Corp::Session or just My_Session). All categories with an underscore have also been reserved. (This is mentioned in perlmodlib, under "Select a name for the module".)

Note that both those reservations apply only to the top-level name. For example, there are CPAN modules named Time::Local and Text::CSV_XS. But Local::Time and Text_CSV::XS are reserved names and would not be accepted on CPAN.

Naming modules after your company is fine too. (Well, unless you work for some really generic sounding company.) Using the reverse domain name is probably overkill, unless you intend to distribute your modules to others. (But in that case, you should probably register a normal module name.)

How Perl resolves a conflict:

Perl searches the directories in @INC for a module with the specified name. The first module found is the one used. So the order of directories in @INC determines which module would be used (if you have modules with the same name installed in different locations).

perl -V will report the contents of @INC (the highest-priority directories are listed first). But there are lots of ways to manipulate @INC at runtime, too.

BTW, Perl 6 will be able to handle multiple modules with the same name by different authors, and even use more than one in a single program. But that doesn't solve your problem now.

Answer 5

(I know this post is old, but as I've had to sort this out in the past few months, I thought I'd weigh in)

At work we decided that 'Local::' felt too geographic. CompanyName:: had some problems for us too that aren't development related, I'll skip those, though I will say that CompanyName is long when you have to type it dozens of times.

So we settled on 'Our::'. Sure, we're not 'CPAN Safe' as there could be the day when we want to use a CPAN module with the Our:: prefix. But it feels nice.

Our::Data is our Class::DBI module Our::App is our generic app framework that does config handling and Getopt stuff

Nice to read and nice to type.

Answer 6

The @INC variable contains a list of directories to in which to look for modules. It starts with the first entry and then moves on to next if it doesn't find the request module. @INC has a default value that created when perl is compiled, but you can can change it with the PERL5LIB environment variable, the lib pragma, and directly manipulating the @INC array in a BEGIN block:

#!/usr/bin/perl

BEGIN {
    @INC = (); #no modules can be found
}

use strict; #error: Can't locate strict.pm in @INC (@INC contains:)