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

Too lazy? Let Simple Descriptor do the hard work for you

Since 0.2.0 version Simple Descriptor provides method to automate some ActiveRecord models description

class Employee < ActiveRecord::Base
  extend SimpleDescriptor::ClassDescriptor
  validates_ar_descriptions
end

With just the code above you will get validations for:

1) all your numeric fields defined as numeric in your DB 2) maximum length of all the fields defined as string in the DB 3) all the required field defined as not null in the DB

and you get

Employee.maxlength(field)

plus a lot of pre-defined descriptions for your model that you can inspect with

Employee.descriptions

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

rubyforge.org/projects/simpledesc/

Documentation can be found at

simpledesc.rubyforge.org/

Installation

Installation can be done fomr gem command

License

Simple Descriptor is released under the MIT license.

Support

rubyforge.org/projects/simpledesc/

Author

Original Author of Simple Descriptor is Paolo Negri