Develop and Download Open Source Software

= For Edmaru Developers

This document mainly describes the strcture of Edmaru source tree.

== Character encodings

All source files in Edmaru source tree must be encoded by UTF-8.

== Class specification

If you want to improve Edmaru, it is a nice idea to see class
specifications. Edmaru source codes are designed to generate RDoc
(http://rdoc.sourceforge.net/) type documentations, therefore, first
you should run the following command at the root directory of Edmaru
source tree:

 $ ruby gendoc.rb

Then, you can find class specification documents in "doc/rdoc"
directory and open "doc/rdoc/index.html" by your favorite Web browser
to see them.

RDoc also supports the output of diagrams that shows the inheritance
relations among all classes and modules defined in Edmaru source
tree. If you want to see them, first install "dot" command included
in graphviz (http://www.graphviz.org/), and then run "gendoc.rb" with "-d" option like:

 $ ruby gendoc.rb -d

== Unit tests

Edmaru employs Test::Unit. To carry out all unit test suites, just run
the following command at the root directory of Edmaru source tree:

 $ ruby test.rb

You may add new test suites for Edmaru. Go through the following steps
to add them:

1. Create a new test suite codes by Test::Unit.
2. Save the source codes as "test/test_*.rb"
3. Append a new line to "test.rb" like 

 require "test/test_*.rb"

== Add new configuration elements

To add new configuration elements, go through the following steps:

1. Create a new source file, for example,  "config/my_config.rb".
2. Add the new created file name to the Array DEFAULT_CONFIG_FILES in config/config_manager.rb
3. Insert new source codes to "config/my_config.rb" like following:

 module Edmaru::Config
   class ConfigManager
     @@default_elements.push ConfigElement.new("/My/Config/Key",
                                               "Default Value",
                                               "Description",
                                               STRING_VALIDATOR)
   end
 end

The important points are the arguments of ConfigElement's initializer, and appending initialized ConfigElement's instance to Edmaru::Config::ConfigManager::default_elemnts. See the comment of Edmaru::Config::ConfigElement#new for more information about initializer.

== Validators

Validator must be an instance of Proc that raises some sort of RuntimeException if passed value, the first argument, is invalid. For example, to cause an element just accept Integer value, write an validator like following:

 Proc.new{ |value|
   raise "It's not an integer!" if value.class != Integer
 }

== Predefined Validators

Predefined validators are defined under Edmaru::Config::Validators module. Some of them are defined as constant value like:

 STRING_VALIDATOR = Proc.new{ |value|
   raise "Not an instance of String was passed." if value.class != String
 }

And others are defined as method like:

 def Validators.LIST_VALIDATOR(array)
   Proc.new{ |value|
     if !array.include?(value)
       raise "#{value} is invalid."
     end
   }
 end

Description and usage of validators defined as method can be seen in Edmaru::Config::Validators module page of class specification. However, you should see standard_validators.rb to know about the validators defined as constant value.