jeckyl 0.2.1

data/Bugs.rdoc

@@ -0,0 +1,6 @@
+=== BUGS
+
+[jeckyl-0.2.0 20-Sep-2012]
+
+  Nothing yet...
+

data/Gemfile

@@ -0,0 +1,6 @@
+#@markup ruby
+
+# for the command line
+gem 'thor'
+gem 'term-ansicolor'
+

data/History.txt

@@ -0,0 +1,74 @@
+# @markup rdoc
+# @title Change Log
+# @author Robert Sharp
+
+== History
+
+[jeckyl-0.2.1 20-Sep-2012]
+
+  Tidy up documentation.
+
+[jeckyl-0.2.0 19-Sep-2012]
+
+  Clean up code and documentation and enable parameter methods to be separated by class.
+
+[jeckyl-0.1.11 23-Jul-2012]
+
+  Added comment command to jeckyl to produce just comments for yard
+
+[jeckyl-0.1.10 18-June-2012]
+
+  Added complement and intersection methods and deprecated new Jeckyl::Service in favour of
+  including these options with the services they relate to (Jelly::Options, for example). Tidyied
+  up documentation.
+
+[jeckyl-0.1.9 6-June-2012]
+
+  Included require 'jeckyl' in service.rb
+
+[jeckyl-0.1.8 2-June-2012]
+
+  Made sure Jeckyl::Service inherits from Jeckyl::Options!
+
+[jeckyl-0.1.7 1-June-2012]
+
+  Added Jeckyl::Service as a class which already defines all of the config options needed
+  for a Jerbil::Service
+
+[jeckyl-0.1.6 19-Dec-2011]
+
+  Correct silly typo in config_file change
+
+[jeckyl-0.1.5 19-Dec-2011]
+
+  Add :config_file to self to remember where the config file is
+
+[jeckyl-0.1.4 25-July-2011]
+
+  changed ignore_errors_on_default to true as the default
+
+[jeckyl-0.1.3 23-June-2011]
+
+  Minor tweak to get string handling working properly for generating configs
+
+[jeckyl-0.1.2 23-June-2011]
+
+  Update to check that defaults meet specified rules properly, and handle strings and symbols when generating files
+
+[jeckyl-0.1.1 26-Apr-2011]
+
+  Added ConfigRoot as the default root for config files
+
+[jeckyl-0.1.0 18-Apr-2011]
+
+  Changed structure to module-based due to superclass mismatch errors. This version of
+  Jeckyl is not backward compatible.
+
+[jeckyl-0.0.4 14-Apr-2011]
+
+  Minor Update to fix a superclass error caused by requiring version before the first
+  declaration of the Jeckyl class.
+
+[jeckyl-0.0.3a 11-Apr-2011]
+
+  Another slight change

data/Intro.txt

@@ -0,0 +1,5 @@
+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.

data/LICENCE.rdoc

@@ -0,0 +1,159 @@
+Copyright (c) 2011 Robert Sharp
+
+This software is licensed for use under the Open Software Licence v. 3.0
+The terms of this licence can be found at http://www.opensource.org/licenses/osl-3.0.php
+and below. Under the terms of this licence, all derivative works
+must themselves be licensed under the Open Software Licence v. 3.0
+
+Open Source Initiative OSI - The Open Software Licence 3.0:Licensing
+[OSI Approved Licence]
+Open Software Licence ("OSL") v. 3.0
+
+This Open Software Licence (the "Licence") applies to any original work of authorship
+(the "Original Work") whose owner (the "Licensor") has placed the following licensing
+notice adjacent to the copyright notice for the Original Work:
+
+Licensed under the Open Software Licence version 3.0
+
+1) Grant of Copyright Licence. Licensor grants You a worldwide, royalty-free, non-exclusive,
+sublicensable license, for the duration of the copyright, to do the following:
+
+a) to reproduce the Original Work in copies, either alone or as part of a collective work;
+
+b) to translate, adapt, alter, transform, modify, or arrange the Original Work, thereby
+creating derivative works ("Derivative Works") based upon the Original Work;
+
+c) to distribute or communicate copies of the Original Work and Derivative Works to
+the public, with the proviso that copies of Original Work or Derivative Works that
+You distribute or communicate shall be licensed under this Open Software Licence;
+
+d) to perform the Original Work publicly; and
+
+e) to display the Original Work publicly.
+
+2) Grant of Patent Licence. Licensor grants You a worldwide, royalty-free, non-exclusive,
+sublicensable license, under patent claims owned or controlled by the Licensor that are
+embodied in the Original Work as furnished by the Licensor, for the duration of the
+patents, to make, use, sell, offer for sale, have made, and import the Original Work
+and Derivative Works.
+
+3) Grant of Source Code Licence. The term "Source Code" means the preferred form of
+the Original Work for making modifications to it and all available documentation
+describing how to modify the Original Work. Licensor agrees to provide a machine-readable
+copy of the Source Code of the Original Work along with each copy of the Original Work
+that Licensor distributes. Licensor reserves the right to satisfy this obligation by
+placing a machine-readable copy of the Source Code in an information repository reasonably
+calculated to permit inexpensive and convenient access by You for as long as Licensor
+continues to distribute the Original Work.
+
+4) Exclusions From Licence Grant. Neither the names of Licensor, nor the names of
+any contributors to the Original Work, nor any of their trademarks or service marks,
+may be used to endorse or promote products derived from this Original Work without
+express prior permission of the Licensor. Except as expressly stated herein, nothing
+in this Licence grants any license to Licensor's trademarks, copyrights, patents,
+trade secrets or any other intellectual property. No patent license is granted to
+make, use, sell, offer for sale, have made, or import embodiments of any patent claims
+other than the licensed claims defined in Section 2. No license is granted to the
+trademarks of Licensor even if such marks are included in the Original Work. Nothing
+in this Licence shall be interpreted to prohibit Licensor from licensing under terms
+different from this Licence any Original Work that Licensor otherwise would have a
+right to license.
+
+5) External Deployment. The term "External Deployment" means the use, distribution,
+or communication of the Original Work or Derivative Works in any way such that the
+Original Work or Derivative Works may be used by anyone other than You, whether those
+works are distributed or communicated to those persons or made available as an application
+intended for use over a network. As an express condition for the grants of license hereunder,
+You must treat any External Deployment by You of the Original Work or a Derivative Work
+as a distribution under section 1(c).
+
+6) Attribution Rights. You must retain, in the Source Code of any Derivative Works
+that You create, all copyright, patent, or trademark notices from the Source Code of
+the Original Work, as well as any notices of licensing and any descriptive text identified
+therein as an "Attribution Notice." You must cause the Source Code for any Derivative Works
+that You create to carry a prominent Attribution Notice reasonably calculated to inform
+recipients that You have modified the Original Work.
+
+7) Warranty of Provenance and Disclaimer of Warranty. Licensor warrants that the copyright
+in and to the Original Work and the patent rights granted herein by Licensor are owned by
+the Licensor or are sublicensed to You under the terms of this Licence with the permission
+of the contributor(s) of those copyrights and patent rights. Except as expressly stated in
+the immediately preceding sentence, the Original Work is provided under this Licence on an
+"AS IS" BASIS and WITHOUT WARRANTY, either express or implied, including, without limitation,
+the warranties of non-infringement, merchantability or fitness for a particular purpose.
+THE ENTIRE RISK AS TO THE QUALITY OF THE ORIGINAL WORK IS WITH YOU. This DISCLAIMER OF WARRANTY
+constitutes an essential part of this Licence. No license to the Original Work is granted
+by this Licence except under this disclaimer.
+
+8) Limitation of Liability. Under no circumstances and under no legal theory, whether
+in tort (including negligence), contract, or otherwise, shall the Licensor be liable
+to anyone for any indirect, special, incidental, or consequential damages of any character
+arising as a result of this Licence or the use of the Original Work including, without
+limitation, damages for loss of goodwill, work stoppage, computer failure or malfunction,
+or any and all other commercial damages or losses. This limitation of liability shall not
+apply to the extent applicable law prohibits such limitation.
+
+9) Acceptance and Termination. If, at any time, You expressly assented to this Licence,
+that assent indicates your clear and irrevocable acceptance of this Licence and all of its
+terms and conditions. If You distribute or communicate copies of the Original Work or a
+Derivative Work, You must make a reasonable effort under the circumstances to obtain the
+express assent of recipients to the terms of this Licence. This Licence conditions your
+rights to undertake the activities listed in Section 1, including your right to create
+Derivative Works based upon the Original Work, and doing so without honoring these
+terms and conditions is prohibited by copyright law and international treaty. Nothing
+in this Licence is intended to affect copyright exceptions and limitations (including
+"fair use" or "fair dealing"). This Licence shall terminate immediately and You may no
+longer exercise any of the rights granted to You by this Licence upon your failure to
+honor the conditions in Section 1(c).
+
+10) Termination for Patent Action. This Licence shall terminate automatically and
+You may no longer exercise any of the rights granted to You by this Licence as of
+the date You commence an action, including a cross-claim or counterclaim, against
+Licensor or any licensee alleging that the Original Work infringes a patent. This
+termination provision shall not apply for an action alleging patent infringement
+by combinations of the Original Work with other software or hardware.
+
+11) Jurisdiction, Venue and Governing Law. Any action or suit relating to this Licence
+may be brought only in the courts of a jurisdiction wherein the Licensor resides or
+in which Licensor conducts its primary business, and under the laws of that jurisdiction
+excluding its conflict-of-law provisions. The application of the United Nations Convention
+on Contracts for the International Sale of Goods is expressly excluded. Any use of
+the Original Work outside the scope of this Licence or after its termination shall be
+subject to the requirements and penalties of copyright or patent law in the appropriate
+jurisdiction. This section shall survive the termination of this Licence.
+
+12) Attorneys' Fees. In any action to enforce the terms of this Licence or seeking
+damages relating thereto, the prevailing party shall be entitled to recover its costs
+and expenses, including, without limitation, reasonable attorneys' fees and costs
+incurred in connection with such action, including any appeal of such action. This
+section shall survive the termination of this Licence.
+
+13) Miscellaneous. If any provision of this Licence is held to be unenforceable,
+such provision shall be reformed only to the extent necessary to make it enforceable.
+
+14) Definition of "You" in This Licence. "You" throughout this Licence, whether in
+upper or lower case, means an individual or a legal entity exercising rights under,
+and complying with all of the terms of, this Licence. For legal entities, "You" includes
+any entity that controls, is controlled by, or is under common control with you. For
+purposes of this definition, "control" means (i) the power, direct or indirect, to cause
+the direction or management of such entity, whether by contract or otherwise, or (ii)
+ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial
+ownership of such entity.
+
+15) Right to Use. You may use the Original Work in all ways not otherwise restricted or
+conditioned by this Licence or by law, and Licensor promises not to interfere with or be
+responsible for such uses by You.
+
+16) Modification of This Licence. This Licence is Copyright © 2005 Lawrence Rosen.
+Permission is granted to copy, distribute, or communicate this Licence without modification.
+Nothing in this Licence permits You to modify this Licence as applied to the Original Work
+or to Derivative Works. However, You may modify the text of this Licence and copy, distribute
+or communicate your modified version (the "Modified Licence") and apply it to other original
+works of authorship subject to the following conditions: (i) You may not indicate in any way
+that your Modified Licence is the "Open Software Licence" or "OSL" and you may not use those
+names in the name of your Modified Licence; (ii) You must replace the notice specified in the
+first paragraph above with the notice "Licensed under <insert your license name here>" or
+with a notice of your own that is not confusingly similar to the notice in this Licence;
+and (iii) You may not claim that your original works are open source software unless your
+Modified Licence has been approved by Open Source Initiative (OSI) and You comply with
+its license review and certification process.

data/bin/jeckyl

@@ -0,0 +1,239 @@
+#!/usr/bin/env ruby18
+#
+# Description
+#
+# Author:: Robert Sharp
+# Copyright:: Copyright (c) 2010 Robert Sharp
+# License:: Open Software Licence v3.0
+#
+# This software is licensed for use under the Open Software Licence v. 3.0
+# The terms of this licence can be found at http://www.opensource.org/licenses/osl-3.0.php
+# and in the file copyright.txt. Under the terms of this licence, all derivative works
+# must themselves be licensed under the Open Software Licence v. 3.0
+# 
+#
+# replace this to point to your config class
+# require 'my_jeckyl_configurator'
+require 'rubygems' # want to find classes that might be in gems
+require 'jeckyl'
+require 'jeckyl/errors'
+require 'thor'
+require 'thor/group'
+require 'colored'
+
+
+
+# the Command Line Interface for jeckyl to allow users to generate
+# config files, generate a simple template or check a config file
+class JeckylCLI < Thor
+  
+  default_task :usage
+  
+  desc "usage", "You are looking at it"
+  def usage
+    puts "Useful tasks for managing Jeckyl config files."
+    puts ""
+    help
+  end
+  
+  desc "list", "list all the config classes involved in a given class"
+  def list(cfile)
+    require cfile
+    classes = Jeckyl::Options.descendants
+    display_classes(classes)
+  rescue LoadError
+    puts "Error: could not load #{cfile}".red.bold
+  end
+    
+  
+  desc "config", "generate config file for the given config class"
+  method_option :class, :aliases=>'-C', :type=>:numeric, :desc=>'select class by index'
+  method_option :concat, :aliases=>'-k', :desc=>'concat all classes, starting with the oldest'
+  def config(cfile, my_class_name=nil)
+    
+    require cfile # catch LoadError if cfile does not load
+    
+    my_class_index = options[:class] || 0 
+    my_class_index += -1 if my_class_index > 0
+    
+    
+    classes = Jeckyl::Options.descendants
+    
+    if options[:concat].nil? && classes[my_class_index].nil? then
+      $stderr.puts "Index #{my_class_index + 1} is invalid. Please select a valid index".red.bold
+      display_classes(classes)
+      return false
+    end
+    
+    $stderr.puts "There are #{classes.length} sets of configs, use 'jeckyl list' to list them or -k to generate them all".yellow if classes.length > 1
+    
+    my_classes = []
+    if options[:concat] then
+      classes.each_index {|i| my_classes.unshift i}
+    else
+      my_classes << my_class_index
+    end
+    
+    my_classes.each do |ci|
+      puts "#"
+      puts "# Configuration Options for: #{classes[ci].name}"
+      puts "#"
+      puts
+      classes[ci].generate_config(true)
+    end
+    
+    unless options[:concat] || classes.length == 1
+      puts ""
+      puts "# There are also parameters in:"
+      classes.each do |klass|
+        puts "#  #{klass.name}"unless klass == classes[my_class_index]
+      end
+    end
+
+  rescue LoadError
+    puts "Error: could not load #{cfile}".red.bold
+  end
+  
+  desc "klass", "generate a simple class template"
+  def klass(name, parent="Jeckyl::Config")
+    puts <<EOTXT
+# Simple framework for defining Jeckyl options to put into a config hash
+
+module #{name}
+  
+  # configuration parameters for #{name} 
+  #
+  # @see file:<PATH_TO_CONFIG_MARKDOWN_FILE> #{name} Parameter Descriptions
+  #
+  class Config < #{parent}
+    
+    def configure_a_parameter(val)
+      default "default"
+      comment "Comment line",
+        "more comments"
+      a_type_of(String)
+    end
+    
+  end
+end
+EOTXT
+    
+  end
+        
+  
+  desc "check", "check the given config file is valid for the given class"
+  def check(klass_file, conf_file)
+    
+    require klass_file # catch LoadError if cfile does not load
+    
+    my_class_index = 0 # assume there is only one
+    
+    classes = Jeckyl::Options.descendants
+    
+    
+    classes[my_class_index].check_config(conf_file)
+
+  rescue LoadError
+    puts "Error: could not load #{cfile}".red
+    
+  end
+  
+  desc "markdown", "display the comments from a class in markdown format"
+  method_option :class, :aliases=>'-C', :type=>:numeric, :desc=>'select class by index'
+  method_option :concat, :aliases=>'-k', :desc=>'concat all classes, starting with the oldest'
+  def markdown(cfile)
+    
+    require cfile # catch LoadError if cfile does not load
+    
+    my_class_index = options[:class] || 0 
+    my_class_index += -1 if my_class_index > 0
+    
+    
+    classes = Jeckyl::Options.descendants
+    
+    if options[:concat].nil? && classes[my_class_index].nil? then
+      $stderr.puts "Index #{my_class_index + 1} is invalid. Please select a valid index".red.bold
+      display_classes(classes)
+      return false
+    end
+    
+    $stderr.puts "There are #{classes.length} sets of configs, use 'jeckyl list' to list them or -k to generate them all".yellow if classes.length > 1
+    
+    my_classes = []
+    if options[:concat] then
+      classes.each_index {|i| my_classes << i}
+    else
+      my_classes << my_class_index
+    end
+    
+    first = true
+    sublevel = 2
+    
+    my_classes.each do |ci|
+      my_class = classes[ci]
+      my_configurator = my_class.new(nil, :local=>true)
+      
+      if first then
+        puts "# #{my_class.name} Parameters"
+        puts ""
+        puts "The following parameters are defined in {#{my_class.name}} and should be used"
+        puts "in a configuration file. A default config file can be generated using:"
+        puts ""
+        puts "    jeckyl config #{File.expand_path(cfile)}"
+      else
+        puts "## Additional Parameters from #{my_class.name}"
+        puts ""
+        puts "The following additional parameters are defined in #{my_class.name}, which"
+        puts "is an ancestor of this config class. See separate documentation for more details."
+        sublevel = 3
+      end
+      first = false
+      puts ""
+      
+      puts "#" * sublevel + " Parameters"
+      puts ""
+      
+      my_configurator.comments.each do |param, comment|
+        puts " * **#{param}**"
+        puts " "
+        comment.each {|line| puts "    #{line}"}
+        puts ""
+        if my_configurator.defaults.has_key?(param) then
+          puts "    Default: #{my_configurator.defaults[param].inspect}"
+        else
+          puts "    No default set"
+        end
+        puts ""
+      end
+    end
+    
+    unless options[:concat] || classes.length == 1
+      puts ""
+      puts "## See Also"
+      puts ""
+      puts "There are also parameters in:"
+      puts ""
+      classes.each do |klass|
+        puts " * #{klass.name}"unless klass == classes[my_class_index]
+      end
+    end
+
+  rescue LoadError
+    puts "Error: could not load #{cfile}".red
+    
+  end
+  
+  no_tasks do
+  def display_classes(classes)
+    $stderr.puts "The following classes are available:".green
+    count = 1
+    classes.each do |klass|
+      $stderr.puts   "  #{count}. #{klass.name}"
+      count += 1
+    end
+  end
+  end
+
+end
+
+JeckylCLI.start

data/lib/jeckyl/errors.rb

@@ -0,0 +1,35 @@
+#
+# Description
+#
+# Author:: Robert Sharp
+# Copyright:: Copyright (c) 2011 Robert Sharp
+# License:: Open Software Licence v3.0
+#
+# This software is licensed for use under the Open Software Licence v. 3.0
+# The terms of this licence can be found at http://www.opensource.org/licenses/osl-3.0.php
+# and in the file copyright.txt. Under the terms of this licence, all derivative works
+# must themselves be licensed under the Open Software Licence v. 3.0
+# 
+# 
+
+module Jeckyl
+
+  # A standard class for all Jeckyl exceptions
+  class JeckylError < Exception; end
+
+  # the config file given does not exist
+  class ConfigFileMissing < JeckylError; end
+
+  # the config file has a syntax error
+  class ConfigSyntaxError < JeckylError; end
+
+  # a config parameter was incorrect
+  class ConfigError < JeckylError; end
+
+  # the given config parameter is not known
+  class UnknownParameter < JeckylError; end
+
+  # could not open the specified report file
+  class ReportFileError < JeckylError; end
+
+end

data/lib/jeckyl/version.rb

@@ -0,0 +1,13 @@
+# Created by Jevoom
+#
+# 20-Sep-2012
+#   Tidy up documentation.
+
+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'
+end