attr_*

attr_* is a library to extend the basic Ruby class/module attribute functions with some useful functionality. It supports the original attribute API, as well as additional features such as defaults values for attributes and attribute initialization.

Specifically, three types of attribute initialization are supported:

• none (as per the functionality of the original attr_accessor et al., the instance variables won’t be initialized to any value — instance_variable_defined?(:@ivar) will return false)
• first-access initialization (the attribute will be undefined until first accessed)
• instance initialization (the attribute will be defined with the instance, thus being defined for all parts of the lifecycle of the instance, for all intents and purposes)

Usage

attr_* exposes a single method, Module#attr_splat, that takes a series of Symbols from which to create attributes, along with an options hash at the end.

However, most users will want to replace the existing attr_* functionality with this (the API is fully backwards compatible; as long as none of your code depends on the particular inner workings of the existing attr_* methods, it should continue to work fine as-is). This isn't difficult, and for the most part amounts to the following:

class Module
   def attr_accessor *args
    attr_splat(*args)
  end

  def attr_reader *args
    opts = args.last.is_a?(Hash) ? args.pop : Hash.new
    args << {:writer => false}.merge(opts)
    attr_splat(*args)
  end

  def attr_writer *args
    opts = args.last.is_a?(Hash) ? args.pop : Hash.new
    args << {:writer => false}.merge(opts)
    attr_splat(*args)
  end
end

If you're lazy, you can shorten the above to something like this:

Module::attr_splat!

Using attr_* is pretty simple - just use the attr_* methods as you normally would. If you need to supply a default value for an attribute, you can add a :default parameter as follows:

class Something
  attr_accessor :something, :default => "summat"
end

You can define more than one attribute with the same default at the same time:

attr_accessor :something, :something_else, :default => "summat"

Attributes with a default flag will (by default) to the second initialization method described above - that is, the default value will be initialized into the attribute's variable only after the first time the attribute's getter is called. If you want default values to be initialized along with the instance of the class, you can pass the :initialize flag - it's disabled by default, because it relies on some metaprogrammy magic that this author prefers to avoid calling into every class all over Ruby's source.

attr_accessor :something, :something_else,
  :default => "summat", :initialze => true

If you call the initialize flag without a default, the attribute is initialized to nil.

attr_accessor :something, :something_else, :initialze => true

Installation

You can install attr_* as a pre-built gem, or as a gem generated directly from the source.

The easiest way to install attr_* is to use RubyGems to acquire the latest 'release' version from RubyForge, using the gem command line tool:

sudo gem install attr_splat # You'll be asked for your account password.

Alternatively, you can acquire a (possibly slightly more up-to-date, depending on how often the gemspec is updated) version from GitHub as follows:

# If you've ever done this before, you don't need to do it now - see http://gems.github.com
gem sources -a http://gems.github.com
sudo gem install elliottcable-attr_splat # You'll be asked for your account password.

Finally, you can build a gem from the latest source yourself. You need git, as well as Rake and elliottcable's clone of echoe:

git clone git://github.com/elliottcable/attr_splat.git
cd attr_splat
# If you've ever done this before, you don't need to do it now - see http://gems.github.com
gem sources -a http://gems.github.com
sudo gem install elliottcable-echoe # You'll be asked for your account password.
rake install # You'll be asked for your account password.

Contributing

You can contribute bug fixes or new features to attr_* by forking the project on GitHub (you'll need to register for an account first), and sending me a pull request once you've committed your changes.

Links

• GitHub is the project's primary repository host, and currently also the project's home page
• RubyForge is out primary RubyGem host, as well as an alternative repository host
• integrity is out continuous integration server - if the top build on that page is green, you can assume the latest git HEAD is safe to run/install/utilize.
• Gitorious is an alternative repository host
• repo.or.cz is an alternative repository host

License

attr_* is copyright 2008 by elliott cable.

attr_* is released under the GNU General Public License v3.0, which allows you to freely utilize, modify, and distribute all attr_*'s source code (subject to the terms of the aforementioned license).