README.markdown

   1 attr_*
   2 ======
   3 *`attr_*`* is a library to extend the basic Ruby class/module attribute
   4 functions with some useful functionality. It supports the original attribute
   5 API, as well as additional features such as defaults values for attributes and
   6 attribute initialization.
   7
   8 Specifically, three types of attribute initialization are supported:
   9
  10 - none (as per the functionality of the original attr_accessor et al., the
  11     instance variables won’t be initialized to any value — `instance_variable_defined?(:@ivar)`
  12     will return false)
  13 - first-access initialization (the attribute will be undefined until first
  14     accessed)
  15 - instance initialization (the attribute will be defined with the instance,
  16     thus being defined for all parts of the lifecycle of the instance, for all
  17     intents and purposes)
  18
  19 Usage
  20 -----
  21 `attr_*` exposes a single method, `Module#attr_splat`, that takes a series of
  22 Symbols from which to create attributes, along with an options hash at the end.
  23
  24 However, most users will want to replace the existing `attr_*` functionality
  25 with this (the API is fully backwards compatible; as long as none of your code
  26 depends on the particular inner workings of the existing `attr_*` methods, it
  27 should continue to work fine as-is). This isn't difficult, and for the most
  28 part amounts to the following:
  29
  30     class Module
  31        def attr_accessor *args
  32         attr_splat(*args)
  33       end
  34
  35       def attr_reader *args
  36         opts = args.last.is_a?(Hash) ? args.pop : Hash.new
  37         args << {:writer => false}.merge(opts)
  38         attr_splat(*args)
  39       end
  40
  41       def attr_writer *args
  42         opts = args.last.is_a?(Hash) ? args.pop : Hash.new
  43         args << {:writer => false}.merge(opts)
  44         attr_splat(*args)
  45       end
  46     end
  47
  48 If you're lazy, you can shorten the above to something like this:
  49
  50     Module::attr_splat!
  51
  52 Using `attr_*` is pretty simple - just use the `attr_*` methods as you
  53 normally would. If you need to supply a default value for an attribute, you
  54 can add a `:default` parameter as follows:
  55
  56     class Something
  57       attr_accessor :something, :default => "summat"
  58     end
  59
  60 You can define more than one attribute with the same default at the same time:
  61
  62     attr_accessor :something, :something_else, :default => "summat"
  63
  64 Attributes with a default flag will (by default) to the second initialization
  65 method described above - that is, the default value will be initialized into
  66 the attribute's variable only after the first time the attribute's getter is
  67 called. If you want default values to be initialized along with the instance
  68 of the class, you can pass the `:initialize` flag - it's disabled by default,
  69 because it relies on some metaprogrammy magic that this author prefers to
  70 avoid calling into every class all over Ruby's source.
  71
  72     attr_accessor :something, :something_else,
  73       :default => "summat", :initialze => true
  74
  75 If you call the initialize flag without a default, the attribute is
  76 initialized to `nil`.
  77
  78     attr_accessor :something, :something_else, :initialze => true
  79
  80 Installation
  81 ------------
  82 You can install `attr_*` as a pre-built gem, or as a gem generated directly
  83 from the source.
  84
  85 The easiest way to install `attr_*` is to use [RubyGems][] to acquire the
  86 latest 'release' version from [RubyForge][], using the `gem` command line tool:
  87
  88     sudo gem install attr_splat # You'll be asked for your account password.
  89
  90 Alternatively, you can acquire a (possibly slightly more up-to-date,
  91 depending on how often the gemspec is updated) version from GitHub as follows:
  92
  93     # If you've ever done this before, you don't need to do it now - see http://gems.github.com
  94     gem sources -a http://gems.github.com
  95     sudo gem install elliottcable-attr_splat # You'll be asked for your account password.
  96
  97 Finally, you can build a gem from the latest source yourself. You need [git][],
  98 as well as [Rake][] and elliottcable's clone of [echoe][]:
  99
 100     git clone git://github.com/elliottcable/attr_splat.git
 101     cd attr_splat
 102     # If you've ever done this before, you don't need to do it now - see http://gems.github.com
 103     gem sources -a http://gems.github.com
 104     sudo gem install elliottcable-echoe # You'll be asked for your account password.
 105     rake install # You'll be asked for your account password.
 106
 107 [RubyGems]: <http://rubyforge.org/projects/rubygems/> "RubyGems - Ruby package manager"
 108 [RubyForge]: <http://rubyforge.org/projects/attr_splat/> "attr_* on RubyForge"
 109 [git]: <http://git-scm.com/> "git - Fast Version Control System"
 110 [Rake]: <http://rake.rubyforge.org/> "RAKE - Ruby Make"
 111 [echoe]: <http://github.com/fauna/echoe> "If you don't want to hoe, echoe"
 112
 113 Contributing
 114 ------------
 115 You can contribute bug fixes or new features to `attr_*` by forking the project
 116 on GitHub (you'll need to register for an account first), and sending me a
 117 pull request once you've committed your changes.
 118
 119 Links
 120 -----
 121 - [GitHub](http://github.com/elliottcable/attr_splat "attr_* on GitHub") is the
 122     project's primary repository host, and currently also the project's home
 123     page
 124 - [RubyForge](http://rubyforge.org/projects/attr_splat "attr_* on RubyForge") is
 125     out primary RubyGem host, as well as an alternative repository host
 126 - [integrity](http://integrit.yreality.net/attr_splat "attr_* on yreality's integrity server")
 127     is out continuous integration server - if the top build on that page is
 128     green, you can assume the latest git HEAD is safe to run/install/utilize.
 129 - [Gitorious](http://gitorious.org/projects/attr_splat "attr_* on Gitorious") is
 130     an alternative repository host
 131 - [repo.or.cz](http://repo.or.cz/w/attr_splat.git "attr_* on repo.or.cz") is
 132     an alternative repository host
 133
 134 License
 135 -------
 136 `attr_*` is copyright 2008 by elliott cable.
 137
 138 `attr_*` is released under the [GNU General Public License v3.0][gpl], which
 139 allows you to freely utilize, modify, and distribute all `attr_*`'s source code
 140 (subject to the terms of the aforementioned license).
 141
 142 [gpl]: <http://www.gnu.org/licenses/gpl.txt> "The GNU General Public License v3.0"