Why an array list rather than a hash? Um, it just seemed right at the time... I like your answer better than mine :).

I thought about passing a hash ref with all the maps, but intuitively, a list of arrays felt better. I didn't think about why, but just wrote it that way. Probably not the best engineering method on my part.

Take my ideas with a grain of salt, as I haven't ever used Shell.pm. But I do think it's a neat demonstration of some very useful Perl techniques.

It seems to me that Shell.pm is all about friendly magic. And, I think the automatic mapping idea is a really good bit of friendly magic. For that reason, I'd keep the automatic mapping for items specified as strings as needed. Perhaps you could throw a warning when you have to do a translation. If you're feeling like getting really fancy, I think there's a way to register the warning so it can be controlled with the warnings pragma. That way the warning could be disabled with:

no warnings 'shell_automapping';
use Shell 'foo.bar';
[download]

I've never figured out how to do that though, and its certainly a more complex bit of work.

Any explicit mapping should be honored and no automatic mapping should occur for an explicitly mapped item.

Any name collisions should cause the import to throw a fatal exception.

But all I'm doing is jawing. You are writing actual code, so I'll just shut up now and let you get some work done. :)