Skip to content

Latest commit

 

History

History
176 lines (117 loc) · 6.05 KB

README.md

File metadata and controls

176 lines (117 loc) · 6.05 KB
Raw

Gem Version Build Status Coverage Status

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.