Fattr

NAME fattr.rb

INSTALL gem install fattrs

URIS http://github.com/ahoward/fattr http://rubyforge.org/projects/codeforpeople/ http://codeforpeople.com/

SYNOPSIS fattr.rb is a "fatter attr" for ruby

the implementation of fattr.rb borrows many of the best ideas from the metakoans.rb ruby quiz

http://www.rubyquiz.com/quiz67.html

in particular the solutions of Christian Neukirchen and Florian Gross along with concepts from my original traits.rb lib

key features provided by fattrs are

- ability to specify default values for attrs and definition time.  values
  can be literal objects or blocks, which are evaluated in the context of
  self to initialize the variable

- classes remember which fattrs they've defined and this information is
 available to client code

- a whole suite of methods is defined by calls to #fattrs including
 getter, setter, query (var?) and banger (var! - which forces
 re-initialization from the default value/block)

- ability to define multiple fattrs at once using key => value pairs

- fast lookup of whether or not a class has defined a certain fattr

- fattrs can be defined on objects on a per singleton basis

- getters acts as setters if an argument is given to them

- block caching, calling an fattr with a block sets the instance
  variable to that block

- shortcuts for adding class/module level fattrs

- class inheritable attributes

all this in 156 lines of code

SAMPLES

<========< samples/a.rb >========>

~ > cat samples/a.rb

#
# basic usage is like attr, but note that fattr defines a suite of methods
#
  require 'fattr'

  class C
    fattr 'a'
  end

  c = C.new

  c.a = 42
  p c.a                 #=> 42
  p 'forty-two' if c.a? #=> 'forty-two'

#
# fattrs works on object too 
#
  o = Object.new
  o.fattr 'answer' => 42
  p o.answer           #=> 42

~ > ruby samples/a.rb

42
"forty-two"
42

<========< samples/b.rb >========>

~ > cat samples/b.rb

#
# default values may be given either directly or as a block which will be
# evaluated in the context of self.  in both cases (value or block) the
# default is set only once and only if needed - it's a lazy evaluation.  the
# 'banger' method can be used to re-initialize a variable at any point whether
# or not it's already been initialized.
#
  require 'fattr'

  class C
    fattr :a => 42
    fattr(:b){ Float a }
  end

  c = C.new
  p c.a #=> 42
  p c.b #=> 42.0

  c.a = 43
  p c.a #=> 43
  c.a!
  p c.a #=> 42

~ > ruby samples/b.rb

42
42.0
43
42

<========< samples/c.rb >========>

~ > cat samples/c.rb

#
# multiple name=>default pairs can be given 
#
  require 'fattr'

  class C
    fattrs 'x' => 0b101000, 'y' => 0b10
  end

  c = C.new
  z = c.x + c.y
  p z #=> 42

~ > ruby samples/c.rb

42

<========< samples/d.rb >========>

~ > cat samples/d.rb

#
# a nice feature is that all fattrs are enumerated in the class.  this,
# combined with the fact that the getter method is defined so as to delegate
# to the setter when an argument is given, means bulk initialization and/or
# fattr traversal is very easy.
#
  require 'fattr'

  class C
    fattrs %w( x y z )

    def fattrs
      self.class.fattrs
    end

    def initialize
      fattrs.each_with_index{|a,i| send a, i}
    end

    def to_hash
      fattrs.inject({}){|h,a| h.update a => send(a)}
    end

    def inspect
      to_hash.inspect
    end
  end

  c = C.new
  p c.fattrs 
  p c 

  c.x 'forty-two' 
  p c.x

~ > ruby samples/d.rb

["x", "y", "z"]
{"x"=>0, "y"=>1, "z"=>2}
"forty-two"

<========< samples/e.rb >========>

~ > cat samples/e.rb

#
# my favourite element of fattrs is that getters can also be setters.
# this allows incredibly clean looking code like
#
  require 'fattr'

  class Config
    fattrs %w( host port)
    def initialize(&block) instance_eval &block end
  end

  conf = Config.new{
    host 'codeforpeople.org'
    port 80
  }

  p conf

~ > ruby samples/e.rb

samples/e.rb:7: Use RbConfig instead of obsolete and deprecated Config.
samples/e.rb:7:in `<main>': Config is not a class (TypeError)

<========< samples/f.rb >========>

~ > cat samples/f.rb

#
# of course fattrs works as well at class/module level as at instance
# level
#
  require 'fattr'

  module Logging 
    Level_names = {
      0 => 'INFO',
      # ...
      42 => 'DEBUG',
    }

    class << Logging
      fattr 'level' => 42
      fattr('level_name'){ Level_names[level] }
    end
  end

p Logging.level
p Logging.level_name

~ > ruby samples/f.rb

42
"DEBUG"

<========< samples/g.rb >========>

~ > cat samples/g.rb

#
# you can add class/module fattrs the 'normal' way or using the provided
# shortcut method
#
  require 'fattr'

  class C
    class << C
      fattr 'a' => 4
    end

    Fattr 'b' => 2
  end

  p [ C.a, C.b ].join

~ > ruby samples/g.rb

"42"

<========< samples/h.rb >========>

~ > cat samples/h.rb

#
# class variable inheritance is supported simply
#
  require 'fattr'

  class A
    Fattr :x, :default => 42, :inheritable => true
  end

  class B < A
  end

  class C < B
  end

  p C.x #=> 42

  A.x = 42.0
  B.x = 'forty-two'

  p A.x #=> 42.0
  p B.x #=> 'forty-two'
  p C.x #=> 42

  C.x! # re-initialize from closest ancestor (B)

  p A.x #=> 42.0
  p B.x #=> 'forty-two'
  p C.x #=> 'forty-two'

~ > ruby samples/h.rb

42
42.0
"forty-two"
42
42.0
"forty-two"
"forty-two"

<========< samples/i.rb >========>

~ > cat samples/i.rb

#
# you can retrieve all fattrs as a list, or a hash with values included
#
  require 'fattr'

  class C
    fattr(:a)
    fattr(:b){ a.to_f }
  end

  o = C.new

  o.fattr(:c)
  o.fattr(:d){ self.c.upcase }

  o.a = 42
  o.c = 'forty-two' 

  p o.fattrs.to_hash #=> {"a"=>42, "b"=>42.0, "c"=>"forty-two", "d"=>"FORTY-TWO"}
  p o.fattrs         #=> ["c", "d"]

~ > ruby samples/i.rb

{"a"=>42, "b"=>42.0, "c"=>"forty-two", "d"=>"FORTY-TWO"}
["c", "d"]

HISTORY 2.3.0 support for "object.fattrs.to_hash"

2.0.0: support class/module inheritable attributes

1.1.0: ruby19 testing. move to github.

1.0.2: added Fattr shortcut for adding class/module level fattrs

  class C
    Fattr 'children' => []

    def C.inherited other
      (children << other).uniq!
      super
    end
  end

  class B < C
  end

  p C.children #=> B

1.0.0: port from attributes.rb retaining all the same features of that version of attributes.rb