jeckyl 0.2.1 → 0.2.3

data/History.txt

@@ -4,6 +4,14 @@
 
 == History
 
+[jeckyl-0.2.3 21-Sep-2012]
+
+  Add references to online docs etc to usage.
+
+[jeckyl-0.2.2 21-Sep-2012]
+
+  Add readme command to jeckyl to display README.md (when included properly)
+
 [jeckyl-0.2.1 20-Sep-2012]
 
   Tidy up documentation.

data/Intro.txt

@@ -1,5 +1,7 @@
-Jeckyl can be used to create a parameters hash from a simple config file written in Ruby, having run whatever checks you want
-on the file to ensure the values passed in are valid. All you need to do is define a class inheriting from Jeckyl, methods for
+Create and manage configuration files in Ruby for Ruby. Jeckyl can be used to create a parameters hash 
+from a simple config file written in Ruby, having run whatever checks you want on the file to ensure 
+the values passed in are valid. All you need to do is define a class inheriting from Jeckyl, methods for
 each parameter, its default, whatever checking rules are appropriate and even a comment for generating templates etc.
 This is then used to parse a Ruby config file and create the parameters hash. Jeckyl 
 comes complete with a utility to check a config file against a given class and to generate a default file for you to tailor.
+Type 'jeckyl readme' for more information.

data/README.md

@@ -0,0 +1,357 @@
+#JECKYL 
+
+### (a.k.a. Jumpin' Ermin's Configurator for Kwick and easY Linux services)
+
+Jeckyl can be used to create a parameters hash from a simple config file written in Ruby, having run whatever checks you want
+on the file to ensure the values passed in are valid. All you need to do is define a class inheriting from Jeckyl, methods for
+each parameter, its default, whatever checking rules are appropriate and even a comment for generating templates etc.
+This is then used to parse a Ruby config file and create the parameters hash. Jeckyl 
+comes complete with a utility to check a config file against a given class and to generate a default file for you to tailor.
+
+Jeckyl was inspired by the configuration file methods in [Unicorn](http://unicorn.bogomips.org/).
+
+## Installation
+
+Jeckyl comes as a gem. It can be installed in the usual way:
+
+    gem install jeckyl
+    
+That is all you need to do.
+    
+## Getting Started
+
+To use Jeckyl, create a new parameter class and add a parameter method for each parameter you want to define in
+your config files. Think of the name of a parameter and prefix this with `configure_`:
+
+    require 'jeckyl'
+    
+    class MyConfig < Jeckyl::Config
+    
+      def configure_my_greeting(greet)
+        default "Hello"
+        comment "Set the standard greeting for this application"
+        
+        a_string(greet)
+      end
+    end
+    
+The parameter method first sets a default value to be used if no value is given at all in the config file. This is
+optional. It then describes the parameter, which is used by `jeckyl` when generating a blank config or a markdown file. Finally
+it runs a check on the given parameter to ensure it is a string. Note the name of the method that you use in the
+config file itself would be just 'my_greeting' wheras the parameter method is 'configure_my_greeting'.
+
+Jeckyl comes complete with a whole range of checking methods that can be used for defining parameters 
+(see {Jeckyl::Config} for details). These methods are handy because they handle errors transparently. 
+It is not necessary, however, to use them so long as the value returned by the parameter method is what 
+you want in your config hash.
+
+To use this simple example, you can generate a config file with jeckyl:
+
+    $ jeckyl generate config lib/my_app/my_config.rb >test/conf.d/test.rb
+    
+This will produce something like:
+
+    # Set the standard greeting for this application
+    #my_greeting "Hello"
+    
+Which you could change to:
+
+    # Set the standard greeting for this application
+    my_greeting "Welcome"
+
+And then, to use this config file to create the options hash:
+
+    require 'my_app/my_config'
+    
+    options = MyConfig.new('test/conf.d/test.rb')
+    
+    options.inspect => {:config_files=>['test/conf.d/test.rb'], :my_greeting=>'Welcome'}
+    
+## Using Jeckyl
+
+### Example Parameter Methods
+
+Some examples of different parameters are given here, taken from the Jelly::Config class, Jelly being
+a jazzed-up ruby logger:
+
+    def configure_log_level(lvl)
+      default :system
+      comment "Controls the amount of logging done by Jelly",
+        "",
+        " * :system - standard message, plus log to syslog",
+        " * :verbose - more generous logging to help resolve problems",
+        " * :debug - usually used only for resolving problems during development",
+        ""
+
+      lvl_set = [:system, :verbose, :debug]
+      a_member_of(lvl, lvl_set)
+
+    end
+
+This shows a multi-line comment, the comment method takes any number of arguments and outputs 
+them one per line. It also shows how to test that a key value is used that belongs to a set.
+
+
+    def configure_log_rotation(int)
+      default 2
+      comment "Number of log files to retain at any time, between 0 and 20"
+
+      a_type_of(int, Integer) && in_range(int, 0, 20)
+
+    end
+
+This shows how multiple tests can be and'd together.
+
+    def configure_log_length(int)
+      default 1 #Mbyte
+      comment "Size of a log file (in MB) before switching to the next log, upto 20 MB"
+
+      a_type_of(int, Integer) && in_range(int, 1, 20)
+      int * 1024 * 1024
+    end 
+
+This shows how the return value can be computed from the input parameter if required.
+
+This final example shows a complicated parameter method that accepts an options hash and can
+be called multiple times:
+
+    def configure_sensors(options)
+      comment "Add a sensor to monitor etc. This can be called multiple times",
+        " ",
+        " Sensors must be defined with the following:",
+        "   :device - name of a device previously added with add_device",
+        "   :name - the name for this thermostat (e.g. name of the room being monitored)",
+        " ",
+        " Sensors can have the following options:",
+        "   :slope - gradient of the residual error function for the given sensor, default 0.0",
+        "   :intercept - from the residual error function, default 0.0",
+        " "
+
+      unless @sensors
+        @sensors = Array.new
+      end
+
+      # remember the sensor names
+      unless @names
+        @names = Array.new
+      end
+
+      unless options.has_key?(:device)
+        raise Jeckyl::ConfigError, "You must supply a :device for each sensor"
+      end
+      unless @devices.include?(options[:device])
+        raise Jeckyl::ConfigError, "You must name a device that has already been added"
+      end
+      unless options.has_key?(:name)
+        raise Jeckyl::ConfigError, "You must supply a :name for each sensor"
+      end
+      @sensors.each do |sensor|
+        raise Jeckyl::ConfirError, "Each name must be unique" if sensor[:name] == options[:name]
+      end
+      a_type_of(options[:name], String)
+
+      raise Jeckyl::ConfigError, "You must supply an index" unless options.has_key?(:index)
+      a_type_of(options[:index], Integer) && in_range(options[:index], 1, 4)
+
+      options[:slope] ||= 0.0
+      a_type_of(options[:slope], Float)
+
+      options[:intercept] ||= 0.0
+      a_type_of(options[:intercept], Float)
+
+      @names << options[:name]
+
+      @sensors << options # return the current array of sensors
+
+    end
+
+The method uses its own instance variables to keep track of things over multiple calls and
+returns the @sensors array so that the actual parameter returned from Jeckyl will be the last value
+returned. It uses a mixture of jeckyl tests and explicit tests to ensure the parameters are correct.
+If preferred, you can add custom helper methods to your parameter class in the same manner as {Jeckyl::Config}.
+
+### Writing Ruby
+
+Because the config file is ruby, it can contain any valid ruby code to help construct your parameters,
+which can be instances of complex classes if required. BUT this also means the code can do things you
+might not have intended so some care is needed here!
+
+One of the things you can add, if it helps, is your own checking method. Call it what you like, pass in the object
+to check (and whatever else you need) and either return the item or raise an error if the checks fail. There
+are two methods available: {Jeckyl::Config#raise_config_error} e.g. for defining a value
+outside the required range and {Jeckyl::Config#raise_syntax_error} e.g. for defining a string where a number is required.
+
+### Can't be bothered? a more relaxed approach
+
+If you are lazy and cannot be bothered with defining lots of methods, you can relax the parsing and checking and convert a
+parameter file straight into an options hash. To relax checking, set the :relax option to true when creating the parameters hash. 
+Then any parameter value pairs in the config file will be converted to key-value pairs in the hash 
+without any checks at all. You obviously cannot do much with this approach but in simple cases it may be OK? 
+
+If you don't like having to prefix your parameter methods with 'configure_' you can set another prefix
+by redefining the prefix method in your subclass to return something else:
+
+    def prefix
+      'set' # could also be 'cf' if you find typing a bore
+    end
+
+### Managing Parameter Hashes
+
+You can easily merge parameter files using the {Jeckyl::Config#merge} method:
+
+    config = MyConfig.new('/etc/system.rb')
+    config.merge(File.join(ENV[USER], '.my_config_.rb'))
+    config.merge('./.local_config_.rb')
+
+Jeckyl includes a couple of methods to help sub-divide parameter hashes. To extract 
+all of the parameters from a hash that belong to a given Jeckyl class, use Class.intersection(hash) (see 
+{Jeckyl::Config.intersection}). And to remove all of the parameters from one config hash in another, 
+use conf.complement(hash) ({Jeckyl::Config#complement}).
+
+For example, the Jelly logger defines a set of logging parameters in Jelly::Config. These may be inherited
+by another service that adds its own parameters (such as Jerbil):
+
+    options = Jerbil::Config.new(my_conf)
+    
+    log_opts = Jelly::Config.intersection(options)
+    
+    jerb_opts = options.complement(log_opts)
+    
+### Some Internal Methods
+
+
+### Jeckyl::Config < Hash
+
+Finally, note that Jeckyl::Config is itself a subclass of Hash, and therefore Jeckyl config objects inherit
+all hash methods as well!
+
+## The 'jeckyl' Command
+
+Jeckyl comes with a simple script: bin/jeckyl to help in creating, checking and documenting parameters.
+
+You can create a simple config class to start you off with:
+
+    $ jeckyl klass <name>
+      
+which will output a small template to stdout. By default this will inherit from {Jeckyl::Config} but
+you can add another parent with, for example:
+
+    $ jeckyl klass MyService JerbilService::Config
+    
+Save the file and edit it to add your parameters as required. Once you have defined the config class, 
+you can generate a default config file for your application using:
+
+    $ jeckyl config path/to/config_class.rb
+
+This will generate a config file on stdout for each of the parameters, with the comment defined in the
+parameter method and the default value where defined. Defaults will be commented out. You can save this file and edit it
+to create a new config file.
+
+Where you have created a config class that inherits from another config class, you will probably want to create
+a config file with all of the parameters in it. By default only the config class defined in the given file
+will be generated. To generate all parameters add the -k (for concat) option:
+
+    $ jeckyl config path/to/config_class.rb -k
+    
+The resulting config file will be neatly divided into sections, one for each class, starting with the most
+ancestral. If you want to know what config classes you have inherited, then try:
+
+    $ jeckyl list path/to/config_class.rb
+    
+This will output an indexed list of the classes available. If you wanted to generate a config file just for one class, 
+select it with the -C option and the index from the list:
+
+    $ jeckyl config path/to/config_class.rb -C 2
+    
+Once you have editted your config file you can check if it is OK:
+
+    $ jeckyl check path/to/config_class.rb path/to/config_file.rb
+    
+This will either display error messages or tell you that the config file is OK.
+
+Having created a config class, you may want to document it. Given that each parameter is already described within
+the parameter method, it would be inconvenient to have to copy these comments into ruby comments just to
+help the various documentation tools around. Instead, you can generate a markdown file from the parameter methods
+and then include this in your documentation:
+
+    $ jeckyl markdown path/to/config_class.rb
+    
+This task takes the same options as the config task. You can then include a reference or link to this file
+in the header comment for your config class. The template generated above already has a yard @see directive.
+
+    # @see file:lib/project/config_comments.md
+
+    
+## Code Walkthrough
+
+Jeckyl is documented on [RubyDoc.info](http://rdoc.info/github/osburn-sharp/jeckyl/frames).
+
+Jeckyl consists of a single class: {Jeckyl::Config}. When you create an instance of a subclass the following
+happens (see {Jeckyl::Config#initialize}):
+
++ all of the parameter methods are called by {Jeckyl::Config#get_defaults} to obtain their default values 
+  (the {Jeckyl::Config#default default} method sets this in a hash)
+  and are called again with these default values to process them through whatever the parameter method defines. This
+  ensures, for example, that if the parameter is multiplied by 10 before being added to the config hash, 
+  the default value is also multipled by 10.
+  
++ if no config file is provided, the default values are returned as the options hash. This is used, for example,
+  by the config {Jeckyl::Config.generate_config generator}.
+  
++ finally, the given config file (whose name is added to the hash) is evaluated so that the resulting parameters are
+  added, overriding any defaults or manually entered values.
+  
+All of this is done with just a little bit of meta-magic. When the config file is eval'ed the parameter names are eval'ed
+in the context of the instance being created, but because the parameter methods are all prefixed with something (configure by default)
+method_missing is called instead. This orchestrates the setting of parameters and collecting of results into the options
+hash, passing the parameter values to the corresponding parameter method. 
+
+For example, a config file might contain:
+
+    # define a greeting for the application
+    greeting "Hello"
+    
+There is no greeting method, so method_missing is called instead. This remembers the name of the "missing" method (:greeting),
+calls configure_greeting and stores the results in the instances hash. The main reason for doing this (as opposed to just
+calling the method 'greeting') is to enable the evaluation of defaults and comments in the context of each parameter method. 
+All of this is private and therefore under the bonnet.
+
+## Dependencies
+
+See the {file:Gemfile} for details of dependencies.
+
+Tested on Ruby 1.8.7.
+
+## Testing Jeckyl
+
+There is an rspec test file to test the whole thing (spec/jeckyl_spec.rb). It uses the test subclass in "../test" and 
+various config files in "../conf.d". There is another rspec file that tests the config_check function.
+  
+
+## Why did I bother?
+
+Having tried various config file solutions, I had ended up using yaml files, but i found
+checking them very difficult because they are not very friendly and very sensitive to spacing
+issues. In looking for yet another alternative, I came across the approach used by
+Unicorn (the backend web machine I now use for Rails apps). I liked the concept but
+thought it could be made more general, which resulted in Jeckyl.
+
+## Bugs etc
+
+Details of bugs can be found in {file:Bugs.rdoc}
+
+## Author and Contact
+
+I am Robert Sharp and you can contact me on [GitHub](http://github.com/osburn-sharp)
+
+## Copyright and Licence
+
+Copyright (c) 2011-2012 Robert Sharp. 
+
+See {file:LICENCE.rdoc LICENCE} for details of the licence under which Jeckyl is released.
+
+## Warranty
+
+This software is provided "as is" and without any express or implied
+warranties, including, without limitation, the implied warranties of
+merchantibility and fitness for a particular purpose.

data/bin/jeckyl

@@ -34,6 +34,24 @@ class JeckylCLI < Thor
     puts "Useful tasks for managing Jeckyl config files."
     puts ""
     help
+    puts ""
+    puts "See Also:"
+    puts "  README.md: (see jeckyl readme above)"
+    puts "  GitHub: https://github.com/osburn-sharp/jeckyl"
+    puts "  RubyDoc: http://rdoc.info/github/osburn-sharp/jeckyl/frames"
+  end
+  
+  desc "readme", "display the readme file for the gem"
+  def readme
+    gem_spec = Gem::Specification.find_by_name('jeckyl')
+    readme_path = File.join(gem_spec.gem_dir, 'README.md')
+    
+    File.open(readme_path) do |rfile|
+      rfile.each_line do |rline|
+        puts rline
+      end
+    end
+
   end
   
   desc "list", "list all the config classes involved in a given class"

data/lib/jeckyl/version.rb

@@ -1,13 +1,13 @@
 # Created by Jevoom
 #
-# 20-Sep-2012
-#   Tidy up documentation.
+# 21-Sep-2012
+#   Add references to online docs etc to usage.
 
 module Jeckyl
-  # version set to 0.2.1
-  Version = '0.2.1'
-  # date set to 20-Sep-2012
-  Version_Date = '20-Sep-2012'
-  #ident string set to: jeckyl-0.2.1 20-Sep-2012
-  Ident = 'jeckyl-0.2.1 20-Sep-2012'
+  # version set to 0.2.3
+  Version = '0.2.3'
+  # date set to 21-Sep-2012
+  Version_Date = '21-Sep-2012'
+  #ident string set to: jeckyl-0.2.3 21-Sep-2012
+  Ident = 'jeckyl-0.2.3 21-Sep-2012'
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: jeckyl
 version: !ruby/object:Gem::Version 
-  hash: 21
+  hash: 17
   prerelease: 
   segments: 
   - 0
   - 2
-  - 1
-  version: 0.2.1
+  - 3
+  version: 0.2.3
 platform: ruby
 authors: 
 - Dr Robert
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2012-09-20 00:00:00 Z
+date: 2012-09-21 00:00:00 Z
 dependencies: 
 - !ruby/object:Gem::Dependency 
   type: :runtime
@@ -46,11 +46,13 @@ dependencies:
   version_requirements: *id002
   prerelease: false
 description: |
-  Jeckyl can be used to create a parameters hash from a simple config file written in Ruby, having run whatever checks you want
-  on the file to ensure the values passed in are valid. All you need to do is define a class inheriting from Jeckyl, methods for
+  Create and manage configuration files in Ruby for Ruby. Jeckyl can be used to create a parameters hash 
+  from a simple config file written in Ruby, having run whatever checks you want on the file to ensure 
+  the values passed in are valid. All you need to do is define a class inheriting from Jeckyl, methods for
   each parameter, its default, whatever checking rules are appropriate and even a comment for generating templates etc.
   This is then used to parse a Ruby config file and create the parameters hash. Jeckyl 
   comes complete with a utility to check a config file against a given class and to generate a default file for you to tailor.
+  Type 'jeckyl readme' for more information.
 
 email: robert@osburn-sharp.ath.cx
 executables: 
@@ -63,12 +65,14 @@ extra_rdoc_files:
 - Intro.txt
 - LICENCE.rdoc
 - Gemfile
+- README.md
 files: 
 - History.txt
 - Bugs.rdoc
 - Intro.txt
 - LICENCE.rdoc
 - Gemfile
+- README.md
 - lib/jeckyl/errors.rb
 - lib/jeckyl/version.rb
 - lib/jeckyl.rb
@@ -110,7 +114,7 @@ files:
 homepage: 
 licenses: 
 - Open Software Licence v3.0
-post_install_message: 
+post_install_message: Jeckyl is now installed. Type 'jeckyl' for help
 rdoc_options: 
 - --main=README.rdoc
 require_paths: