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
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