Install.rb: avoiding file name collisions (raa-install too)

ruby-talk
1

[Maybe this should be added to the packaging FAQ or perhaps to
QuickGuideToPackaging on the RubyGarden wiki - I post it here for
discussion first.]

<FAQ_ITEM>
This falls under the catagory of good manners…
Let’s say that I’ve got a package I call ‘Template’. Now it seems that in
order to avoid namespace collisions with
other packages I should actually call it something like:
‘Text::Template’ and I should wrap my ‘Template’ module in a ‘Text’ module
like so:

module Text
module Template
end
end

Now I’m thinking that others might also use the Text module for other
packages they create like: Text::Parse

module Text
module Parse
end
end

So, my Text::Template module is defined in a file called template.rb
What if someone else does an HTML::Template module that is also defined in
a file called template.rb. The last one installed will overwrite the
other file in the Ruby library location. The easy fix is to rename my
template.rb file to something more specific like texttemplate.rb, but
that requires me to know a lot about what others have called their library
files.
When there is potential for collisions in the namespace, we wrap
modules in other modules in order to avoid this, but how do we avoid the
problem of a library file (that contains a module definition) having
potentially the same name as an already existing library file?

The answer lies in how I organize my package directories. Remember that
install.rb will install files in the lib subdirectory of my package in the
directory ‘RUBY_INSTALL_DIR/lib/ruby/site_ruby/1.x/’. As it turns out
install.rb will also recursively descent into our package’s lib directory
so that we could have subdirectories under the lib directory. These
subdirectories of lib will get created in
’RUBY_INSTALL_DIR/lib/ruby/site_ruby/1.x/’. So my hopothetical
Text::Template package should be organized as follows (only showing the
lib directory contents):

lib/
text/
template.rb

Now when a user wants to use Text::Template, they must:

require ‘text/template’

So here’s a suggestion for a convention: Wherever you see a ‘::’ in a
package name, it should imply a subdirectory within your package and
within Ruby’s libraries:

Text::Template -> ‘text/template’
</FAQ_ITEM>

And we should probalby be using a lot more '::'s in our package names.

I see several XML* packages that should probably be changed to 'XML::*'
type names.

Does raa-install have any facility to search a namespace like:
raa-install --search XML::* ?

BTW: I find that ‘raa-install --search’ doesn’t work for me as advertised:

$ raa-install --search xml
/usr/bin/raa-install: unrecognized option --search' /usr/lib/ruby/1.6/getoptlong.rb:264:inset_error’: unrecognized option
--search' (GetoptLong::InvalidOption) from /usr/lib/ruby/1.6/getoptlong.rb:363:inget’
from /usr/lib/ruby/1.6/getoptlong.rb:457:in each' from /usr/lib/ruby/1.6/getoptlong.rb:457:inloop’
from /usr/lib/ruby/1.6/getoptlong.rb:457:in `each’
from /usr/bin/raa-install:32

Phil

2

When there is potential for collisions in the namespace, we wrap
modules in other modules in order to avoid this, but how do we avoid the
problem of a library file (that contains a module definition) having
potentially the same name as an already existing library file?

NaHi and I have been discussing this exact same issue for the last two
weeks. You see the problem, too. Ruby itself has namespaces to assist
in preventing name collision, but RAA does not. Currently there is an
ID field and a descriptive name field to prevent collisions.

I am working with NaHi to introduce a new canonical name. It’s exactly
what you’re talking about. When you register your library in RAA,
you’ll be asked to disclose the top-level namespace for your module.
This name will act as your canonical name across RAA and its mirrors.
It will also park you a namespace that none can tread upon. (Though
others may descend beneath your namespace, certainly.)

So here’s a suggestion for a convention: Wherever you see a ‘::’ in a
package name, it should imply a subdirectory within your package and
within Ruby’s libraries:

Text::Template → ‘text/template’

One of these two representations will be used as the canonical name.
I lean toward using the slash.

I see several XML* packages that should probably be changed to ‘XML::*’
type names.

Well, let’s see. So should the namespacing reflect categorical
information? Because it seems kinda redundant if REXML uses XML::REXML.
I doubt there are any other packages competing for the top-level REXML
namespace.

Does raa-install have any facility to search a namespace like:
raa-install --search XML::* ?

raa-install --search “^XML”

BTW: I find that ‘raa-install --search’ doesn’t work for me as advertised:

$ raa-install --search xml

That guide is a bit ahead of the releases. I just got access to CVS
today, so the 0.0.5 release is on its way.

_why

···

Phil Tomson (ptkwt@shell1.aracnet.com) wrote: