= key_struct

Defines KeyStruct, which acts the same as ruby's Struct but the struct's
initializer takes keyword args (using a hash, rails-style).  Use it to
define a class via:

  Name = KeyStruct[:first, :last]

or as an anonymous base class for your own enhanced struct:

  class Name < KeyStruct[:first, :last]
    def to_s
      "#{@last}, #{@first}"
    end
  end

Then you can create an instance of the class using keywords for the parameters:

  name = Name.new(:first => "Jack", :last => "Ripper")

and you have the usal readers and writers

  name.first            # --> "Jack"
  name.last             # --> "Ripper"
  name.last = "Sprat"
  name.last             # --> "Sprat"
  name.to_s             # --> "Sprat, Jack" for the enhanced class example


== Readers, Writers, and Instance Variables

As per above, the normal behavior is to get readers and writers.  But, by analogy with +attr_reader+ vs +attr_accessor+, you can choose whether you want read/write or just read:

  Writeable = KeyStruct.accesor(:first, :last)      # aliased as KeyStruct[]
  Readonly = KeyStruct.reader(:first, :last)        # class has readers but not writers

The analogy is not just skin deep: +KeyStruct+ actually uses
+attr_accessor+ or +attr_reader+ to define the accessors for the generated class.
This means that you also get the corresponding instance variables:

  name.instance_variable_get("@last") # --> "Sprat"
  name.instance_variable_set("@last", "Sparrow")
  name.last             # --> "Sparrow"

The instance variables can be useful of course when using KeyStruct to define an anonymous
base class for your own classes, as shown for the +to_s+ example above.

(This is one way that +KeyStruct+ differs from ruby's built-in +Struct+:
built-in +Struct+ does not define instance variables.)

== Default values

If you leave off a keyword when instantiating, normally the member value is nil:

  name = Name.new(:first => "Jack")
  name.last             # --> nil

But when you define the class you can specify defaults that will be filled in by
the class initializer. For example:

  Name = KeyStruct[:first, :last => "Doe"]

  name = Name.new(:first => "John")
  name.first            # --> "John"
  name.last             # --> "Doe"

  name = Name.new(:first => "John", :last => "Deere")
  name.first            # --> "John"
  name.last             # --> "Deere"

== Argument Checking

The struct initializer checks for invalid arguments:

  name = Name.new(:this_is_a_typo => "Xavier")  # --> raises ArgumentError

== Comparison

KeyStruct classes define the == operator, which returns true iff all corresponding struct members are equal (likewise via ==)

    Name.new(:first => "John", :last => "Doe") == Name.new(:first => "John", :last => "Doe")    # --> true
    Name.new(:first => "John", :last => "Doe") == Name.new(:first => "Jane", :last => "Doe")    # --> false

As a convenience when a well-defined ordering is needed, KeyStruct classes
defines the <=> operator and includes the +Comparable+ module. The <=>
operator applies <=> to the coresponding struct members sequentially,
returning the first that is non-0. The comparison is performed in the order
the keys were listed in the class definition, so the first key is the
primary comparison key, and so on down the line.  Thus:

    Name = KeyStruct[:first, :last]
    Name.new(:first => "Abigail", :last => "Zither") <=> Name.new(:first => "Zenobia", :last => "Aardvark")           # --> -1

    LastFirst = KeyStruct[:last, :first]
    LastFirst.new(:first => "Abigail", :last => "Zither") <=> LastFirst.new(:first => "Zenobia", :last => "Aardvark") # --> +1

== to_s and inspect

KeyStruct classes define reasonable default +to_s+ and +inspect+ methods, along the lines of:

        Name.new(:first => "Jack", :last => "Ripper").to_s      # --> '[Name first:Jack last:Ripper]'
        Name.new(:first => "Jack", :last => "Ripper").inspect   # --> '<Name:0x1234abcd first:"Jack" last:"Ripper">'

== Converting to a hash

KeyStruct classes define a +to_hash+ method that returns a hash containing
all members and their values:

        Name.new(:first => "Jack", :last => "Ripper").to_hash   # --> {:first => "Jack", :last => "Ripper")

== Introspection

KeyStruct classes let you examine their definition:

        Name = KeyStruct[:first, :last => "Doe"]
        Name.keys       # --> [ :first, :last ]
        Name.defaults   # --> { :last => "Doe" }

== Installation

Install via:

   % gem install key_struct

or in your Gemfile:

   gem "key_struct"

== Versions

Requires ruby >= 1.9.2.  (Has been tested on MRI 1.9.2 and MRI 1.9.3)

== History

Release Notes:

* 0.4.2 - Bug fix: make class introspection work for derived classes.  Restore metaprogramming: inheritance too fragile.
* 0.4.1 - Cache anonymous classes to avoid TypeError: superclass mismatch.  Nicer strings for anonymous classes.  Internals change: use base class rather than metaprogramming.
* 0.4.0 - Introduce class introspection
* 0.3.1 - Bug fix: to_hash when a value is an array.  Was raising ArgumentError for Hash
* 0.3.0 - Introduced to_s and inspect
* 0.2.1 - Bug fix: return false for == with an incompatible object.  Was raising NoMethodError
* 0.2.0 - Introduced <=> and to_hash
* 0.1.0 - Introduced ==
* 0.0.1 - Initial version

Past: There was some discussion around this idea in this thread:
http://www.ruby-forum.com/topic/138124 in 2008. 

Future: I hope that this gem will be obviated in future versions of ruby.

== Note on Patches/Pull Requests
 
* Fork the project.
* Make your feature addition or bug fix.
* Add tests for it.  Make sure that the coverage report
  (generated automatically when you run rspec) is at 100%
* Send me a pull request.

== Copyright

Released under the MIT License.  See LICENSE for details.