jeckyl 0.3.7 → 0.4.0

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    NTVhZDM0YjllODFmZmViOGFjMmE1YzkwNmEzNDc5ODAwMTE4Y2Q1NA==
+    ZWFjY2JkYjIxZWQwMjRiMjM5MzlhZmQxOTk3NzJkZTlmN2ZjZTQzNg==
   data.tar.gz: !binary |-
-    Y2E5NWYxZjllYzI5ODE4YTk3MWRkODgxMWQ5NDY4MTQ2MjlmNzRjOA==
+    ODBkN2VmMmE1Y2QwOTFiOTM4NzYzMWI2YTc1NzhkMjM2ZTE5YzU4MA==
 !binary "U0hBNTEy":
   metadata.gz: !binary |-
-    YzY0MTQ5YjNjZWZlZmU2ODFlY2E4Njg0MmYzYjZlODg4MWIzNDQ2MmNiYTVk
-    MzdhN2NmNDZkNmNkZGM0YWJkOTU0YmQ2ZjFjODNhZDlkYzFiNzAyNGEzMDVl
-    MDcyMjFmNjNiZGM5NDJiNmQwZWQwMDYyOGVlMWEzZTk3ZjI4YWE=
+    MmQ4ZDFmODUxYmM2MGJkMWVhYmE1NThkNWMzM2I4MjI1MjE1MWNhNmM2MTA5
+    MWFiMDgzMGNmNjQ2OWEyNDU5NDcxNjYxNWRlMzRjMDZiZTIyZWRiYWU1NDRh
+    Y2ZjYjZmNWVkODMxODdhNTlkNmFiNWIwOGQ5OWU3MjA2YjBkNzU=
   data.tar.gz: !binary |-
-    MzhhYjQ1MTRiNGMwOGFlZTM2Mjg3OTZkNDQ4YzYzNjQ1N2YyOTY5NDVhNzBi
-    MmUwMWJiMThlYTQ3ZmRjNmIwZmQ4N2Q1MjhlNTRlM2IzZWUwNTE0MmZjMjdm
-    YTViNDYxMjg3ZDcyMjcwOTQwZGFiOTRhN2UwZWNmMDkyMjAzM2Q=
+    ZmQzNjNkNGMxMjJjZjA5NmQ4NDdmZmM4NzM1OWU0YzlkY2NkNjRiNzRkODdj
+    ZWI3YzYwNWY3YzdmNTY5OTdkMGUzYjI4NWE1MDE5ZTQ1OTg0MjRmY2U1N2Ni
+    NWY0MjJjYTY2YzM2NmY0MzBjNWYzZjJkZDUwYWEyYzI4YTdkOGE=

data/Bugs.rdoc

@@ -14,5 +14,6 @@
     force_again = options[:force_init]
     => false
     
-  Very strange and unexpected behaviour.
+  Very strange and unexpected behaviour, but it does not happen very often. Unable to reproduce 
+  in controlled conditions.
 

data/Gemfile

@@ -1,8 +1,5 @@
 #@markup ruby
 
-# for the command line
-# gem 'thor' not any more
-# gem 'term-ansicolor'
-
+# for jeckyl command line processing
 gem 'optplus', '>=0.0.6'
 

data/History.txt

@@ -4,6 +4,19 @@
 
 == History
 
+[jeckyl-0.4.0 01-Oct-2014]
+
+  General tidy up of gem (README, rspec tests etc) to bring things up to date.
+
+[jeckyl-0.3.9 27-Jun-2014]
+
+  Fix #to_s to return a string and not output!
+
+[jeckyl-0.3.8 24-Jun-2014]
+
+  Added compound names to klass action for 'jeckyl' command, used to generate class
+  files
+
 [jeckyl-0.3.7 19-Sep-2013]
 
   Corrected some minor yard issues

data/README.md

@@ -1,12 +1,17 @@
 #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 is a versatile configuration file manager. It provides a simple way of defining
+and checking configuration parameters (including defaults) that can then be written as ruby in a config file.
+It can also be used to add/override parameters from the command line (using optparse) or
+even on the fly through an API. It comes with a handy utility that can generate a default
+config file, with comments, from the defined config class and check existing config
+files. It even creates a markdown file from the config class to make documentation easier.
+
+Jeckyl can be used for simple parameters or complex structures with multiple calls. It provides
+a single place to define and check all inputs so that you don't have to include any parameter
+checking anywhere else in your code. Classes can be inherited to add further parameters, and
+the config file generated by the jeckyl command is conveniently divided to reflect this. Config
+files can also be merged so that multiple config files can be used (e.g. local/per-user/system).
 
 **GitHub:** [https://github.com/osburn-sharp/jeckyl](https://github.com/osburn-sharp/jeckyl)
 
@@ -22,11 +27,10 @@ Jeckyl comes as a gem. It can be installed in the usual way:
 
     gem install jeckyl
     
-That is all you need to do. Type 'jeckyl' to see usage and references to documentation.
+That is practically all you need to do. Type 'jeckyl' to see usage and references to documentation.
+
+Otherwise start coding your jeckyl config file.
 
-Jeckyl can be used to set the default location for the config files it processes. This will
-be '/etc/jeckyl' unless you set the environment varibale 'JECKYL_CONFIG_DIR' to something else.
-This could be done on a system-wide basis by include a file with this variable in /etc/env.d.
     
 ## Getting Started
 
@@ -221,18 +225,101 @@ use conf.complement(hash) ({Jeckyl::Config#complement}).
 For example, the Jellog logger defines a set of logging parameters in Jellog::Config. These may be inherited
 by another service that adds its own parameters (such as Jerbil):
 
-    options = Jerbil::Config.new(my_conf)
+    all_options = Jerbil::Config.new(my_conf)
+    
+    log_opts = Jellog::Config.intersection(all_options)
     
-    log_opts = Jellog::Config.intersection(options)
+    jerb_opts = all_options.complement(log_opts)
     
-    jerb_opts = options.complement(log_opts)
+### Command Line Options - Jeckyl with Optparse
+
+Jeckyl can also process command line options using optparse. This can be easily done by adding an option 
+method call to your parameter method, which has the same parameters as optparse:
+
+    def configure_param_with_option(param)
+      option_set = [:none, :some, :all]
+      default :none
+      comment "Sets the option type to be one of",
+        "  :none - no options",
+        "  :some - some options",
+        "  :all - all options"
+      
+      describe "set the option type"
+      option "-o", "--option Type", option_set
+      
+      a_member_of(param, option_set)
+    end
     
-### Some Internal Methods
+The {Jeckyl::Config#describe describe} method allows a short usage style description
+over the longer config-file comment, and the {Jeckyl::Config#option} method receives
+the same parameters as the optparse#on method less the description bit.
 
+Adding this to your parameter method does not actually do anything without then parsing
+the options:
+
+    # create a config hash
+    opts = MyConfig.new
+    # parse command-line options with the default ARGV
+    opts.optparse
+    
+The {Jeckyl::Config#optparse optparse} method creates and Optparse object with the
+options defined in your parameter methods (ignoring those with no option set), adds
+a '-c' option for specifying a config file and a -h option for help. It also parses
+the results. 
+
+The {Jeckyl::Config#optparse optparse} method can also yield the real Optparse object
+into a block where you can add further options unrelated to Jeckyl. The parse! is done
+automatically when the block returns.
+
+    # parse them with some extra options added
+    opts.optparse do |opts|
+      # receives the same methods as an optparse object
+      opts.on('-p', '--pretend', 'Do not do anything for real') do
+        @pretend = true
+      end
+    end
+    # parse! is done automatically at the end of the block
+    
+This does two things: it updates the parameters with option statements from the command line
+and it also adds the options in the block but independent of the config object itself.
+
+A word about the -c option. This is really only added so that it is shown in the help
+results. The option is not used by the optparse method for fairly obvious reasons: the 
+instance method is applied to a config hash so the config file has already been evaluated.
+To use the -c option you need to preprocess the command line with a class method:
+
+    # set the default config file
+    default_config_file = '/etc/my_app/config_file.rb'
+    # get the config options, if it exists
+    argv, config_file = MyConfig.get_config_opt(ARGV,default_config_file)
+    # now use the config file
+    @config = MyConfig.new(argv, config_file)
+    
+Note that {Jeckyl::Config.get_config_opt} returns the inputs if there is no option. And
+at this time it only looks for '-c', so the bit about '--config' is a lie!
+
+### Using Parameter methods on the fly
+
+Jeckyl can also be used without a config file, for example as part of an API where the
+inputs are coded in. A config class and parameter methods are defined as usual, including
+defaults. On the inside of the API, where you might explicitly check inputs, you instead
+call the parameter method:
+
+    # somewhere, a default config hash is created
+    @config = MyConfig.new
+    
+    # later, this is used to check a parameter:
+    @param = @config.param_with_option(param)
+    
+    # if the param does not match the config requirements then an exception is called
+    
+This allows you to blend in config files if required and command line options as well.
+The only messy bit is that your API will raise {Jeckyl::ConfigError} unless you trap this and then
+convert it to your own local exception. 
 
 ### Jeckyl::Config < Hash
 
-Finally, note that Jeckyl::Config is itself a subclass of Hash, and therefore Jeckyl config objects inherit
+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
@@ -322,7 +409,7 @@ For example, a config file might contain:
     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
+calls configure_greeting and stores the results in the instance's 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.
 
@@ -330,13 +417,13 @@ All of this is private and therefore under the bonnet.
 
 See the {file:Gemfile} for details of dependencies.
 
-Tested on Ruby 1.8.7.
+Tested on Ruby 1.9.3_p547 and 2.0.0_p481 (Gentoo 2.1 not yet unmasked at time of 
+writing - Oct 2014). Tested with RSpec 3.1.0 - see below.
 
 ## 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.
-  
+There is an rspec test file to test the whole thing (spec/jeckyl_spec.rb). It uses the test subclass in the "test" directory and 
+various config files in the "test/conf.d" directory. There is another rspec file that tests the config_check function.
 
 ## Why did I bother?
 
@@ -346,6 +433,10 @@ issues. In looking for yet another alternative, I came across the approach used
 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.
 
+The name Jeckyl is one of those silly acronyms that means nothing in particular:
+Jumpin' Ermin's Configurator for Kwick and easY Linux services
+
+
 ## Bugs etc
 
 Details of bugs can be found in {file:Bugs.rdoc}
@@ -356,7 +447,7 @@ I am Robert Sharp and you can contact me on [GitHub](http://github.com/osburn-sh
 
 ## Copyright and Licence
 
-Copyright (c) 2011-2012 Robert Sharp. 
+Copyright (c) 2011-2014 Robert Sharp. 
 
 See {file:LICENCE.rdoc LICENCE} for details of the licence under which Jeckyl is released.
 

data/bin/jeckyl

@@ -13,7 +13,7 @@
 # 
 #
 
-require 'rubygems'
+#require 'rubygems' # not required in ruby 1.9.3 +
 require 'optplus'
 
 require 'jeckyl'
@@ -130,17 +130,20 @@ class JeckylCli < Optplus::Parser
   describe "klass", "generate a simple class template"
   def klass
     name = next_argument_or_error("missing class name")
+    names = name.split("::")
+    mod_name = names[0]
+    class_name = names[1] || 'Config'
     parent = next_argument_or('Jeckyl::Config')
     puts <<EOTXT
 # Simple framework for defining Jeckyl options to put into a config hash
 
-module #{name}
+module #{mod_name}
   
   # configuration parameters for #{name} 
   #
   # @see file:<PATH_TO_CONFIG_MARKDOWN_FILE> #{name} Parameter Descriptions
   #
-  class Config < #{parent}
+  class #{class_name} < #{parent}
     
     def configure_a_parameter(val)
       default "default"
@@ -154,10 +157,14 @@ end
 EOTXT
 
   end
-  help :klass, "Generate a simple class file as a template for defining your",
-    "own parameters. You can also specify a class to inherit if you want to",
-    "pick up additional parameters. Otherwise the parent will default to",
-    "Jeckyl::Config. Alternatives include Jellog::Config and JerbilService::Config."
+  help :klass, "  jeckyl klass <name> [<parent_class>}]",
+    "",
+    "Generate a simple class file as a template for defining your",
+    "own parameters. You can also specify a class to inherit if you want as",
+    "an additional parameter. Otherwise the parent will default to",
+    "Jeckyl::Config. Alternatives include Jellog::Config and JerbilService::Config.",
+    "Note the class name can be compound and will be split into module and class.",
+    "For example: 'Module::Class'."
         
   
   describe "check", "check the given config file is valid for the given class"

data/lib/jeckyl.rb

@@ -327,7 +327,7 @@ module Jeckyl
     # @param [Array] args which should usually be ARGV
     # @yield self and optparse object to allow incidental options to be added
     # @return false if --help so that the caller can decide what to do (e.g. exit)
-    def optparse(args)
+    def optparse(args=ARGV)
       
       # ensure calls to parameter methods do not trample on things
       @_last_symbol = nil
@@ -345,13 +345,6 @@ module Jeckyl
         
         options << @_descriptions[param] if @_descriptions.has_key?(param)
         
-        # opt_str = ''
-        # options.each do |os|
-        #   opt_str << os.inspect
-        # end
-        
-        # puts "#{param}: #{opt_str}"
-        
         # get the method itself to call with the given arg
         pref_method = self.method("#{prefix}_#{param}".to_sym)
         
@@ -385,17 +378,19 @@ module Jeckyl
     def to_s(opts={})
       keys = self.keys.collect {|k| k.to_s}
       cols = 0
+      strs = Array.new
       keys.each {|k| cols = k.length if k.length > cols}
       keys.sort.each do |key_s|
-        print '  '
-        print key_s.ljust(cols)
+        str = '  '
+        str << key_s.ljust(cols)
         key = key_s.to_sym
         desc = @_descriptions[key]
         value = self[key].inspect
-        print ": #{value}"
-        print " (#{desc})" unless desc.nil?
-        puts
+        str << ": #{value}"
+        str << " (#{desc})" unless desc.nil?
+        strs << str
       end
+      return strs.join("\n")
     end
     
     

data/lib/jeckyl/version.rb

@@ -1,14 +1,13 @@
 # Created by Jevoom
 #
-# 19-Sep-2013
-#   Corrected some minor yard issues
-#   
+# 01-Oct-2014
+#   General tidy up of gem (README, rspec tests etc) to bring things up to date.
 
 module Jeckyl
-  # version set to 0.3.7
-  Version = '0.3.7'
-  # date set to 19-Sep-2013
-  Version_Date = '19-Sep-2013'
-  #ident string set to: jeckyl-0.3.7 19-Sep-2013
-  Ident = 'jeckyl-0.3.7 19-Sep-2013'
+  # version set to 0.4.0
+  Version = '0.4.0'
+  # date set to 01-Oct-2014
+  Version_Date = '01-Oct-2014'
+  #ident string set to: jeckyl-0.4.0 01-Oct-2014
+  Ident = 'jeckyl-0.4.0 01-Oct-2014'
 end

data/spec/check_config_spec.rb

@@ -12,45 +12,45 @@ describe "Jeckyl Config Checker" do
   # general tests
 
   it "should checkout a simple config" do
-    conf_file = conf_path + '/jeckyl'
-    rep_file = report_path + '/ok.txt'
+    conf_file = File.join conf_path, 'jeckyl'
+    rep_file = File.join report_path,'ok.txt'
     conf_ok = TestJeckyl.check_config(conf_file, rep_file)
-    conf_ok.should be_true
+    conf_ok.should be true
     message = File.read(rep_file).chomp
     message.should == "No errors found in: #{conf_file}"
   end
 
 
   it "should complain if the config file does not exist" do
-    conf_file = conf_path + "/never/likely/to/be/there"
-    rep_file = report_path + '/not_ok.txt'
+    conf_file = File.join conf_path, 'never', 'likely', 'to', 'be', 'there'
+    rep_file = File.join report_path, 'not_ok.txt'
     conf_ok = TestJeckyl.check_config(conf_file, rep_file)
-    conf_ok.should be_false
+    conf_ok.should be false
     message = File.read(rep_file).chomp
     message.should == "No such config file: #{conf_file}"
   end
 
   it "should return false if the config file has a syntax error" do
-    conf_file = conf_path + "/syntax_error"
-    rep_file = report_path + '/not_ok.txt'
+    conf_file = File.join conf_path, "syntax_error"
+    rep_file = File.join report_path, 'not_ok.txt'
     conf_ok = TestJeckyl.check_config(conf_file, rep_file)
-    conf_ok.should be_false
+    conf_ok.should be false
     message = File.read(rep_file).chomp
-    message.should match(/^compile error/)
+    message.should match(/^#{conf_file}:\d+: unterminated/)
   end
 
   it "should return false if the config file has an error" do
-    conf_file = conf_path + "/not_a_bool"
-    rep_file = report_path + '/not_ok.txt'
+    conf_file = File.join conf_path, "not_a_bool"
+    rep_file = File.join report_path, 'not_ok.txt'
     conf_ok = TestJeckyl.check_config(conf_file, rep_file)
-    conf_ok.should be_false
+    conf_ok.should be false
     message = File.read(rep_file).chomp
     message.should match(/^\[debug\]:/)
   end
 
   it "should fail if it cannot write to the report file" do
-    conf_file = conf_path + "/jeckyl"
-    rep_file = report_path + '/no_such_directory/ok.txt'
+    conf_file = File.join conf_path, "jeckyl"
+    rep_file = File.join report_path, 'no_such_directory', 'ok.txt'
     lambda{conf_ok = TestJeckyl.check_config(conf_file, rep_file)}.should raise_error(Jeckyl::ReportFileError)
   end
 

data/spec/jeckyl_spec.rb

@@ -29,7 +29,7 @@ describe "Jeckyl" do
     conf[:log_level].should == :verbose
     conf[:log_rotation].should == 5
     conf[:email].should == "robert@osburn-sharp.ath.cx"
-    conf.has_key?(:sieve).should be_true
+    conf.has_key?(:sieve).should be true
     conf[:config_files].length.should == 1
     conf[:option_set][:peter].should == 37
     conf[:offset].should == 134
@@ -185,12 +185,12 @@ describe "Jeckyl" do
       opts.length.should == 4
       subopts = Aclass.intersection(opts)
       subopts.length.should ==2
-      subopts.has_key?(:a_bool).should be_true
-      subopts.has_key?(:no_def).should be_true
+      subopts.has_key?(:a_bool).should be true
+      subopts.has_key?(:no_def).should be true
       opts.complement(subopts)
       opts.length.should == 2
-      opts.has_key?(:config_files).should be_true
-      opts.has_key?(:another).should be_true
+      opts.has_key?(:config_files).should be true
+      opts.has_key?(:another).should be true
     end
   end
   

data/spec/spec_helper.rb

@@ -2,10 +2,12 @@ $LOAD_PATH.unshift(File.dirname(__FILE__))
 $LOAD_PATH.unshift(File.join(File.dirname(__FILE__), '..', 'lib'))
 require 'jeckyl'
 require 'rspec'
-require 'rspec/autorun'
 
 RSpec.configure do |config|
-  config.color_enabled = true
+  config.color = true
   config.formatter = :doc
-
+  # using older shoulds for the time being
+  config.expect_with :rspec do |c|
+    c.syntax = :should             # disables `expect` and deprecation warnings
+  end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: jeckyl
 version: !ruby/object:Gem::Version
-  version: 0.3.7
+  version: 0.4.0
 platform: ruby
 authors:
 - Dr Robert
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-09-19 00:00:00.000000000 Z
+date: 2014-10-01 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: !binary |-
@@ -121,7 +121,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.0.7
+rubygems_version: 2.0.14
 signing_key: 
 specification_version: 4
 summary: Create and manage configuration files in Ruby for Ruby.