simple_descriptor 0.1.0

data/CHANGELOG

@@ -0,0 +1 @@
+2006 11 26 first release

data/README

@@ -0,0 +1,165 @@
+= Simple Descriptor -- manage class specific informations
+
+Simple Descriptor is a library that allows you add extra information about
+your class using the class itself.
+It provides a collection of class methods to store and manage the extra
+informations about the class.
+
+The basic problem it tries to solve is to group your instance method and
+to bind to the instance method some values if needed.
+
+Even if this library was conceived to be used in the rails framework it
+doesn't require any part of the rails framework to be used.
+
+== A first example: defining required fields in an ActiveRecord class
+
+Let's start with a Employee class which defines the fields name, surname and
+address that are required
+
+  class Employee < ActiveRecord::Base
+    extend SimpleDescriptor::ClassDescriptor
+    describe :name, :surname, :address, :as => :required
+  end
+
+In the extend line we're simply including calling the SimpleDescriptor so
+we can use it from the within of our class
+In the second line we declare or better, describe as required the fields.
+The describe method just adds the descriptions to our class, in this case we
+have described :name, :surname and :address as :required
+
+Until now we have just added a description, but we're not doing any validation
+of the data, so let's add the validation in the model
+
+  class Employee < ActiveRecord::Base
+    extend SimpleDescriptor::ClassDescriptor
+    describe :name, :surname, :address, :as => :required
+    validates_presence_of described_as(:required)
+  end
+
+The described_as method returns all the elements described with the specified
+argument. So now we're actually enforcing the data validation in our model
+
+But the Employee class now can be asked about its required fields using
+
+  Employee.described_as :required
+
+will return the list of all the required fields
+
+Or if we're interested in a single field
+
+  Employee.describe? :name, :as => :required
+
+this will return true since :name was described as required
+
+So, now if we want to do something specific (i.e. setting a red colour) in our
+views for the required fields
+
+  def custom_helper(object, method)
+    colour = "green"
+    if object.class.describes? method, :as => :required
+      colour = "red"
+    end
+    do_the other display things
+  end
+
+If the descriptions are active for every model in the application this helper
+will always work and will display in red colour every required field.
+
+== Another example: defining maximum length of fields in an ActiveRecord class
+
+Simple Descriptor allows to specify a value binded to the given description.
+We want to limit the length of name and surname to 10 characters and the
+address to 50
+
+  class Employee < ActiveRecord::Base
+    extend SimpleDescriptor::ClassDescriptor
+    describe :name, :surname, :as => :limited, :with_value => 10
+    describe :address, :as => :limited, :with_value => 50 
+    described_as(:limited).each do |lim_field|
+      validates_length_of lim_field, :maximum => self.description_of(lim_field, :as => :limited)
+    end
+  end
+
+In the code above name surname and address are described as limited with a value
+and the limit check is enforced using standard rails validation.
+
+The description_of method returns the value for a given description
+
+The code above is a bit verbose, that's why Simple descriptor provides
+shortcuts let's rewrite a part of the code above using shortcuts
+
+  class Employee < ActiveRecord::Base
+    extend SimpleDescriptor::ClassDescriptor
+    describe :name, :surname, :as => :limited, :with_value => 10
+    describe :address, :as => :limited, :with_value => 50
+    shortcut_description :limited, :as => :maxlength
+    described_as(:limited).each do |lim_field|
+      validates_length_of lim_field, :maximum => maxlength(lim_field)
+    end
+  end
+
+The line
+
+  shortcut_description :limited, :as => :maxlength
+
+adds some new methods to our class that makes more easy to access a description
+
+== Where are the description stored and how?
+
+All the descriptions are stored in a DESCRIPTIONS constant, you can always
+access them using Employee::DESCRIPTIONS
+Descriptions are just a collection of hashes
+
+== Are descriptions just for instance methods?
+
+No, in theory in any class you can describe any entity as anything, but be
+careful since the tests cover just a limited range of use-case. You're strongly
+invited to submit new tests to cover your usage of the library
+
+Example of non method related usage of descriptions:
+
+  class Silly
+    extend SimpleDescriptor::ClassDescriptor
+    describe "this is a string" :as => String
+    describe "this is a string" :as => String
+    describe :dog, :as => :animal
+    describe 10, :as => :integer, :with_value => 'ten'
+  end
+
+All the descriptions specified above are valid are not related to any entity of
+the Silly class
+
+== Configuration
+
+No configuration is needed to use the library, just extend your class
+
+
+== Dependencies
+
+No dependencies are required
+
+== Download
+
+The latest version of Simple Descriptor can be found at
+
+http://rubyforge.org/projects/simpledesc/
+
+Documentation can be found at 
+
+http://simpledesc.rubyforge.org/
+
+== Installation
+
+Installation can be done fomr gem command
+
+== License
+
+Simple Descriptor is released under the MIT license.
+
+== Support
+
+http://rubyforge.org/projects/simpledesc/
+
+== Author
+
+Original Author of Simple Descriptor is Paolo Negri

data/Rakefile

@@ -0,0 +1,85 @@
+require 'rubygems'
+require 'rake'
+require 'rake/clean'
+require 'rake/testtask'
+require 'rake/packagetask'
+require 'rake/gempackagetask'
+require 'rake/rdoctask'
+require 'rake/contrib/rubyforgepublisher'
+require 'fileutils'
+include FileUtils
+require File.join(File.dirname(__FILE__), 'lib', 'simple_descriptor', 'version')
+
+AUTHOR = "blank"
+EMAIL = "your contact email for bug fixes and info"
+DESCRIPTION = "description of gem"
+RUBYFORGE_PROJECT = "simple_descriptor"
+HOMEPATH = "http://#{RUBYFORGE_PROJECT}.rubyforge.org"
+BIN_FILES = %w(  )
+
+
+NAME = "simple_descriptor"
+REV = File.read(".svn/entries")[/committed-rev="(d+)"/, 1] rescue nil
+VERS = ENV['VERSION'] || (SimpleDescriptor::VERSION::STRING + (REV ? ".#{REV}" : ""))
+CLEAN.include ['**/.*.sw?', '*.gem', '.config']
+RDOC_OPTS = ['--quiet', '--title', "simple_descriptor documentation",
+    "--opname", "index.html",
+    "--line-numbers", 
+    "--main", "README",
+    "--inline-source"]
+
+desc "Packages up simple_descriptor gem."
+task :default => [:test]
+task :package => [:clean]
+
+Rake::TestTask.new("test") { |t|
+  t.libs << "test"
+  t.pattern = "test/**/*_test.rb"
+  t.verbose = true
+}
+
+spec =
+    Gem::Specification.new do |s|
+        s.name = NAME
+        s.version = VERS
+        s.platform = Gem::Platform::RUBY
+        s.has_rdoc = true
+        s.extra_rdoc_files = ["README", "CHANGELOG"]
+        s.rdoc_options += RDOC_OPTS + ['--exclude', '^(examples|extras)/']
+        s.summary = DESCRIPTION
+        s.description = DESCRIPTION
+        s.author = AUTHOR
+        s.email = EMAIL
+        s.homepage = HOMEPATH
+        s.executables = BIN_FILES
+        s.rubyforge_project = RUBYFORGE_PROJECT
+        s.bindir = "bin"
+        s.require_path = "lib"
+        s.autorequire = "simple_descriptor"
+
+        #s.add_dependency('activesupport', '>=1.3.1')
+        #s.required_ruby_version = '>= 1.8.2'
+
+        s.files = %w(README CHANGELOG Rakefile) +
+          Dir.glob("{bin,doc,test,lib,templates,generator,extras,website,script}/**/*") + 
+          Dir.glob("ext/**/*.{h,c,rb}") +
+          Dir.glob("examples/**/*.rb") +
+          Dir.glob("tools/*.rb")
+        
+        # s.extensions = FileList["ext/**/extconf.rb"].to_a
+    end
+
+Rake::GemPackageTask.new(spec) do |p|
+    p.need_tar = true
+    p.gem_spec = spec
+end
+
+task :install do
+  name = "#{NAME}-#{VERS}.gem"
+  sh %{rake package}
+  sh %{sudo gem install pkg/#{name}}
+end
+
+task :uninstall => [:clean] do
+  sh %{sudo gem uninstall #{NAME}}
+end

data/lib/simple_descriptor/class_descriptor.rb

@@ -0,0 +1,181 @@
+module SimpleDescriptor #:nodoc:
+  module ClassDescriptor
+    LEGAL_DESCRIBE_OPTIONS = [:as, :with_value]
+    def create_descriptions #:nodoc:
+      class_eval "DESCRIPTIONS = Hash.new({})"
+    end
+    #returns all the descriptions for the current class
+    def descriptions
+      class_eval "DESCRIPTIONS"
+    end
+    #adds a description to the current set
+    #examples
+    #
+    #  Person.describe :name, :surname, :as => :required
+    #  Person.describe :heigth, :eye_colour, :as => :public_data
+    #  Person.describe :religion, :as => :sensible_data
+    #
+    #It's possible to specify an optional value for your descriptions
+    #using the :with_value option
+    #example
+    #  Person.describe :name, :surname, :as => :limited, :with_value => 30
+    #
+    def describe(*args)
+      raise ArgumentError unless args.last.is_a?(Hash)
+      options = args.pop
+      create_descriptions unless self.constants.member?('DESCRIPTIONS')
+      args.flatten.each do |arg| 
+        puts "adding #{arg.inspect} as #{options[:as]}" if $DEBUG
+        descriptions[options[:as]] = {} unless descriptions.key?(options[:as])
+        descriptions[options[:as]].update({ arg => options[:with_value] ? options[:with_value] : nil})
+        puts descriptions.inspect if $DEBUG
+      end
+    end
+    #retrieves all the descriptions for the given argument
+    #returns an hash of all the available descriptions
+    #
+    #example
+    #
+    #  Person.descriptions_for(:name)
+    #  => { :required => nil, :limited => 30 }
+    def descriptions_for(args)
+      if args.respond_to? :map
+        args.map { |el| find_description_for el }
+      else
+        find_description_for args
+      end
+    end
+    #returns the elements that have been described with the given arguments
+    #if multiple arguments are specified all the elements that are described
+    #with all the arguments will be returned
+    #
+    #example
+    #  Person.described_as(:required, :limited)
+    #  => [ :name, :surname ]
+    def described_as(*args)
+      if args.size > 1
+        cumulated_keys = args.map { |arg| descriptions[arg].keys }
+        cumulated_keys.sort! { |x, y| x.size <=> y.size }
+        res = []
+        base = cumulated_keys.shift
+        base.each do |b|
+          res << b if cumulated_keys.inject(true) {|v, k| v && k.member?(b)}
+        end
+        res
+      else
+        descriptions[args.first].keys
+      end
+    end
+    #this method is used to test if an item has been described in a specifi way
+    #the methods accepts one or more arguments and returns a bool (true/false)
+    #
+    #examples
+    #
+    #  Person.describes?(:heigth)
+    #  => true
+    #
+    #so there are descriptions for :height in class Person
+    #
+    #  Person.describes?(:heigth, :as => :public_data)
+    #  => true
+    #
+    #so :heigth is described as :public data
+    #
+    #  Person.describes?(:name, :as => :limited, :with_value => 30)
+    #  => true
+    #
+    #so :name is described as  :limited with value 30
+    #
+    def describes?(*args)
+      options = {}
+      options.update(args.pop) if args.last.is_a?(Hash)
+      if options.key?(:as)
+        cond = cond_key = lambda {|el| descriptions[options[:as]].key?(el)}
+        if options.key?(:with_value)
+          cond = lambda {|el| cond_key.call(el) && descriptions[options[:as]][el] == options[:with_value]}
+        end
+        args.each { |arg| return false unless cond.call(arg)}
+      else
+        args.each do |arg|
+          res = []
+          descriptions.each { |d| res << d[1].key?(arg) }
+          return false if res.uniq == [false]
+        end
+      end
+      true
+    end
+    #fetches the value for a given description
+    #
+    #example
+    #  Person.described_value_for(:name, :as => :limited)
+    #  => 30
+    #
+    #This method is aliased as description_of
+    #
+    #example
+    #  Person.description_of(:name, :as => :limited)
+    #  => 30
+    def described_value_for(*args)
+      raise ArgumentError unless args.last.is_a?(Hash) && args.last.key?(:as)
+      options = args.pop
+      if args.size > 1
+        args.map { |el| descriptions[options[:as]][el] }
+      else
+        descriptions[options[:as]][args.first]
+      end
+    end
+    alias :description_of :described_value_for
+    #creates some shortcut method to access a description
+    #
+    #example
+    #  Person.shortcut_desctiption :limited, :as => :maxlength
+    #
+    #will add the methods
+    #  Person.maxlength
+    #  => all the :limited definitions
+    #  Person.maxlength(element)
+    #  => limited value for element
+    #  Person.maxlength?(element)
+    #  => true/false if element is described as :limited
+    #  Person.maxlength_add(element, limit)
+    #  => adds the new limit definition
+    def shortcut_description(*args)
+      raise ArgumentError unless args.last.is_a?(Hash) && args.last.key?(:as)
+      options = args.pop
+      @@shortcut = options[:as]
+      @@shortcut_description = args.first
+      class << self
+        define_method :cippa do
+          "cippa"
+        end
+        method_name = class_variable_get("@@shortcut")
+        description = class_variable_get("@@shortcut_description")
+        raise "#{method_name} already defined" if methods.member?(method_name)
+        define_method(method_name) do |*args|
+          if args.size == 0
+            descriptions[description].keys
+          else
+            descriptions[description][args.first]
+          end
+        end
+        define_method("#{method_name}?") do |arg|
+          descriptions[description].key?(arg)
+        end
+        define_method("#{method_name}_add") do |*args|
+          raise ArgumentError if args.size > 2
+          value = args.size == 2 ? args[1] : nil
+          descriptions[description][args.first]=value
+        end
+      end
+    end
+    private 
+    def find_description_for(arg)
+      descriptions.inject({}) do |h, d|
+        puts h.inspect if $DEBUG
+        puts d.inspect if $DEBUG
+        (h[d[0]] = d[1][arg]) if d[1].key?(arg)
+        h
+      end
+    end
+  end
+end

data/lib/simple_descriptor/version.rb

@@ -0,0 +1,9 @@
+module SimpleDescriptor #:nodoc:
+  module VERSION #:nodoc:
+    MAJOR = 0
+    MINOR = 1
+    TINY  = 0
+
+    STRING = [MAJOR, MINOR, TINY].join('.')
+  end
+end

data/lib/simple_descriptor.rb

@@ -0,0 +1 @@
+Dir[File.join(File.dirname(__FILE__), 'simple_descriptor/**/*.rb')].sort.each { |lib| require lib }

data/test/simple_descriptor_test.rb

@@ -0,0 +1,67 @@
+require File.dirname(__FILE__) + '/test_helper.rb'
+
+class DummySample
+  extend SimpleDescriptor::ClassDescriptor
+  attr_accessor :dummy_var
+end
+class SimpleDescriptorTest < Test::Unit::TestCase
+    #:shaped => { :apple => :spheric, :peach => :spheric, :dice => :cubic },
+    #'chunky' => { 'bacon' => nil } }
+  def setup
+    DummySample.describe :apple, :peach, :pear, :as => :fruit
+    DummySample.describe 'bacon', :as => 'chunky'
+    DummySample.describe :apple, :peach, :as => :shaped, :with_value => :spheric
+    DummySample.describe :pear, :as => :shaped, :with_value => :pear_shaped
+    DummySample.describe :peach, :as => :seasonal
+    DummySample.describe :dice, :as => :shaped, :with_value => :cubic
+  end
+  #checks the values are correctly stored in class::DESCRIPTIONS
+  def test_descriptions
+    assert_equal({ :apple => nil, :peach => nil, :pear => nil }, DummySample::DESCRIPTIONS[:fruit])
+    assert_equal({ :apple => :spheric, :peach => :spheric, :pear => :pear_shaped, :dice => :cubic }, DummySample::DESCRIPTIONS[:shaped])
+    assert_equal({ 'bacon' => nil }, DummySample::DESCRIPTIONS['chunky'])
+  end
+  #checks description retrieval
+  def test_descriptions_for
+    assert_equal({ :shaped => :spheric, :fruit => nil }, DummySample.descriptions_for(:apple))
+  end
+  #checks if the descriptions with value are correctly handled
+  def test_described_value_for
+    assert_equal :spheric, DummySample.described_value_for(:apple, :as => :shaped)
+    assert_equal [:spheric, :cubic, :spheric], DummySample.described_value_for(:apple, :dice, :peach, :as => :shaped)
+    assert_equal :spheric, DummySample.description_of(:apple, :as => :shaped)
+    assert_equal [:spheric, :cubic, :spheric], DummySample.description_of(:apple, :dice, :peach, :as => :shaped)
+  end
+  #checks the describes? method
+  def test_describes?
+    assert_equal false, DummySample.describes?(:urgh)
+    assert_equal true, DummySample.describes?(:apple)
+    assert_equal true, DummySample.describes?(:apple, :peach)
+    assert_equal false, DummySample.describes?(:apple, :peach, :strawberry)
+    assert_equal true, DummySample.describes?(:apple, :as => :fruit)
+    assert_equal true, DummySample.describes?(:apple, :peach, :as => :fruit)
+    assert_equal true, DummySample.describes?(:apple, :peach, :as => :shaped, :with_value => :spheric)
+    assert_equal true, DummySample.describes?(:dice, :as => :shaped, :with_value => :cubic)
+    assert_equal false, DummySample.describes?(:apple, :peach, :dice, :as => :shaped, :with_value => :spheric)
+    assert_equal false, DummySample.describes?(:apple, :as => :fish)
+  end
+  #checks the described_as method
+  def test_described_as
+    assert_equal [:apple, :peach, :pear], DummySample.described_as(:fruit)
+    assert_equal [:apple, :peach, :pear], DummySample.described_as(:fruit, :shaped)
+    assert_equal [:peach], DummySample.described_as(:fruit, :shaped, :seasonal)
+  end
+  #checks shortcut methods
+  def test_shortcut
+    DummySample.shortcut_description(:fruit, :as => :fruity)
+    DummySample.shortcut_description(:shaped, :as => :shape)
+    assert_equal true, DummySample.fruity?(:apple)
+    assert_equal :spheric, DummySample.shape(:apple)
+    assert_equal nil, DummySample.fruity(:apple)
+    assert_equal DummySample.described_as(:fruit), DummySample.fruity
+    DummySample.fruity_add(:banana)
+    assert_equal [:banana, :apple, :peach, :pear], DummySample.described_as(:fruit)
+    DummySample.shape_add(:banana, :banana_shaped)
+    assert_equal :banana_shaped, DummySample.description_of(:banana, :as => :shaped)
+  end
+end

data/test/test_helper.rb

@@ -0,0 +1,2 @@
+require 'test/unit'
+require File.dirname(__FILE__) + '/../lib/simple_descriptor'

metadata

@@ -0,0 +1,64 @@
+--- !ruby/object:Gem::Specification 
+rubygems_version: 0.8.11
+specification_version: 1
+name: simple_descriptor
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+date: 2006-11-24 00:00:00 +00:00
+summary: description of gem
+require_paths: 
+- lib
+email: your contact email for bug fixes and info
+homepage: http://simple_descriptor.rubyforge.org
+rubyforge_project: simple_descriptor
+description: description of gem
+autorequire: simple_descriptor
+default_executable: 
+bindir: bin
+has_rdoc: true
+required_ruby_version: !ruby/object:Gem::Version::Requirement 
+  requirements: 
+  - - ">"
+    - !ruby/object:Gem::Version 
+      version: 0.0.0
+  version: 
+platform: ruby
+signing_key: 
+cert_chain: 
+authors: 
+- blank
+files: 
+- README
+- CHANGELOG
+- Rakefile
+- test/test_helper.rb
+- test/simple_descriptor_test.rb
+- lib/simple_descriptor
+- lib/simple_descriptor.rb
+- lib/simple_descriptor/class_descriptor.rb
+- lib/simple_descriptor/version.rb
+test_files: []
+
+rdoc_options: 
+- --quiet
+- --title
+- simple_descriptor documentation
+- --opname
+- index.html
+- --line-numbers
+- --main
+- README
+- --inline-source
+- --exclude
+- ^(examples|extras)/
+extra_rdoc_files: 
+- README
+- CHANGELOG
+executables: []
+
+extensions: []
+
+requirements: []
+
+dependencies: []
+