jscruggs-metric_fu 0.9.0 → 1.0.0

data/HISTORY

@@ -1,3 +1,13 @@
+=== MetricFu 1.0.0 / 2009-4-30
+
+* Merged in Grant McInnes' work on creating yaml output for all metrics to aid harvesting by other tools
+* Supporting Flog 2.1.0
+* Supporting Reek 1.0.0
+* Removed dependency on Rails Env for 3.months.ago (for churn report), now using chronic gem ("3 months ago").
+* Almost all code is out of Rakefiles now and so is more easily testable
+* Metrics inherit from a refactored Generator now.  New metrics generators just have to implement "emit", "analyze", "to_h" and inherit from Generator.  They also must have a template.  See the flay generator and template for a simple implementation.
+* You now define the metrics you wish to run in the configuration and then run "metrics:all".  No other metrics task is exposed by default.
+
 === MetricFu 0.9.0 / 2009-1-25
 
 * Adding line numbers to the views so that people viewing it on cc.rb can figure out where the problems are

data/README

@@ -1,154 +1 @@
-Version 0.9.0
-http://github.com/jscruggs/metric_fu
-
-Metric_fu began its life as a plugin for Rails that generated code metrics reports.  As of version 0.7.0, metric_fu is a gem owing to the excellent work done by Sean Soper.  
-
-Metric_fu is a set of rake tasks that make it easy to generate metrics reports.  It uses Saikuro, Flog, Rcov, and Rails' built-in stats task to create a series of reports.  It's designed to integrate easily with CruiseControl.rb by placing files in the Custom Build Artifacts folder.
-
-****Installation****
-sudo gem install jscruggs-metric_fu -s http://gems.github.com
-
-Then in your Rakefile:
-require 'metric_fu'
-
-If you like to vendor gems, you can unpack metric_fu into vendor/gems and require it like so:
-require 'vendor/gems/jscruggs-metric_fu-0.9.0/lib/metric_fu'
-
-then you don't have to install it on every box you run it on.
-
-Important note:
-You must have Rcov and Flog installed to get coverage and flog reports.  Metric_fu requires both of these gems so they will be installed when you install the metric_fu gem.
-
-
-****Usage****
-
-Out of the box metrics provides these tasks:
-rake metrics:all                  # Generate coverage, cyclomatic complexity, flog, flay, railroad and churn reports
-rake metrics:churn                # Which files change the most
-rake metrics:coverage             # Generate and open coverage report
-rake metrics:coverage:clean       # Delete aggregate coverage data.
-rake metrics:coverage:clobber_do  # Remove rcov products for do
-rake metrics:coverage:do          # RCov task to generate report
-rake metrics:flay                 # Generate code duplication report with flay
-rake metrics:flog:all             # Generate and open flog report
-rake metrics:flog:clean           # Delete aggregate flog data.
-rake metrics:flog:controllers     # Flog code in app/controllers
-rake metrics:flog:custom          # Generate a flog report from specified directories
-rake metrics:flog:helpers         # Flog code in app/helpers
-rake metrics:flog:lib             # Flog code in lib
-rake metrics:flog:models          # Flog code in app/models
-rake metrics:reek                 # A code smell report using Reek
-rake metrics:saikuro              # A cyclomatic complexity report using Saikuro
-
-Rails projects also have the following tasks:
-
-rake metrics:stats                 # A stats report
-
-See below for more detail on the individual tasks.  It's recommended to use CruiseControl.rb to set up a metrics build.  See the CruiseControl.rb online docs for more info on how to set up cc.rb and, once you've got that figured out, change the cruise_config.rb file inside your project to have these lines:
-
-project.rake_task = 'metrics:all_with_migrate'
-project.scheduler.polling_interval = 24.hours
-
-Which will check for updates every 24 hours and run all the metrics rake tasks (migrating your test db first).  The output will be visible from an individual build's detail page.
-
-
-****Notes on configuration****
-
-Metric_fu can be customized to your liking by adding the following to your Rakefile
-
-MetricFu::Configuration.run do |config|
-  #define which metrics you want to use
-  config.metrics          = [:coverage, :flog]
-  config.churn    = { :start_date => lambda{ 3.months.ago } }  
-  config.coverage = { :test_files => ['test/**/test_*.rb'] }
-  config.flog     = { :dirs_to_flog => ['cms/app', 'cms/lib']  }
-  config.flay     = { :dirs_to_flay => ['cms/app', 'cms/lib']  }  
-  config.saikuro  = { "--warn_cyclo" => "3", "--error_cyclo" => "4" }
-end
-
-
-****Notes on metrics:coverage****
-
-When creating a coverage report, metric_fu runs all the tests in the test folder and specs in spec folder using Rcov.
-You can configure the coverage test files pattern:
-  config.coverage[:test_files] = ['test/**/test_*.rb']
-
-The default value is ['test/**/*_test.rb', 'spec/**/*_spec.rb']
-
-You may also configure Rcov options:
-  config.coverage = { :test_files => ['test/**/*_test.rb'],
-                :rcov_opts => ["--exclude /gems/,/Library/"] }
-                
-The default value is  { :test_files => ['test/**/*_test.rb', 'spec/**/*_spec.rb'],
-                        :rcov_opts => ["--sort coverage", "--html", "--rails", "--exclude /gems/,/Library/,spec"] }
-
-
-****Notes on metrics:saikuro****
-
-Saikuro is bundled with metric_fu so you don't have to install it.  Look at the SAIKURO_README (or the internet) for more documentation on Saikuro.  If you wish to change the options Saikuro is run with, then set this constant in your configuration:
-
-  config.saikuro = { "--warn_cyclo" => "3", "--error_cyclo" => "4" }
-
-config.saikuro is a hash that gets merged with the default options hash.  The above example will set the warn_cyclo to 3 and the error_cyclo to 4 (which is way too low -- it's just an example) instructing Saikuro to flag methods with a higher cyclomatic complexity in it's report.
-
-If you want to have Saikuro look at multiple folders you can put something like this in your configuration:
-
-  config.saikuro = {"--input_directory" => '"cms/app | cms/lib"'}
-
-
-****Notes on metrics:flay****
-
-Flay analyzes ruby code for structural similarities. 
-You can configure which directories need to be flayed.
-The defaults are 'lib' for non Rails projects and ['app', 'lib'] for Rails projects.
-
-  config.flay[:dirs_to_flay] = ['cms/app', 'cms/lib']
-
-
-****Notes on metrics:flog****
-
-Flog is another way of measuring complexity (or tortured code as the Flog authors like to put it).  You should check out the awesome, and a little scary, Flog website for more info.
-'rake metrics:flog:custom' allows you to specify a custom set of directories to Flog (in your configuration).
-The defaults are 'lib' for non Rails projects and ['app', 'lib'] for Rails projects.
-
-  config.flog[:dirs_to_flog] = ['cms/app', 'cms/lib']
-
-
-****Notes on metrics:reek****
-
-Reek detects common code smells in ruby code.
-You can configure which directories need to be checked.
-The defaults are 'lib' for non Rails projects and ['app', 'lib'] for Rails projects.
-
-  config.reek[:dirs_to_reek] = ['cms/app', 'cms/lib']
-
-
-****Notes on metrics:roodi****
-
-Roodi parses your Ruby code and warns you about design issues you have based on the checks that is has configured.
-You can configure which directories need to be checked.
-The defaults are 'lib' for non Rails projects and ['app', 'lib'] for Rails projects.
-
-    config.roodi[:dirs_to_roodi] = ['cms/app', 'cms/lib']
-
-****Notes on metrics:stats****
-
-This is just 'rake stats' for Rails put into a file.  On my projects I like to be able to look at CruiseControl and get stats about the app at different points in time.
-
-
-****Notes on metrics:churn****
-
-Files that change a lot in your project may be bad a sign.  This task uses "svn log" to identify those files and put them in a report.  The default is to start counting changes from the beginning of your project, which might be too far back so you can change like so:
-
-  config.churn = { :start_date => lambda{ 3.months.ago } }
-
-The Proc is there because '3.months.ago' only works when after the Rails Environment is loaded (and Rails extends Fixnum) which I didn't want to do every time you run a rake task.
-
-You can also change the minimum churn count like so:
-
-  config.churn = { :minimum_churn_count => 3 }
-
-
-****Thanks****
-
-I'd like to thank the authors of Saikuro, Flog, Rcov, CruiseControl.rb, Flay, Reek, Roodi and Rails for creating such excellent open source products.  Also Andre Arko, Petrik de Heus, Sean Soper, Erik St Martin, Andy Gregorowicz, Bastien, Michael Schubert, Kurtis Seebaldt, Toby Tripp, Paul Gross, and Chirdeep Shetty for their help and advice.
+See http://metric-fu.rubyforge.org/ for documentation, or the HISTORY file for a change log.

data/Rakefile

@@ -1,11 +1,46 @@
 require 'rake'
 require 'rake/rdoctask'
 require 'spec/rake/spectask'
-require File.join(File.dirname(__FILE__), 'lib', 'metric_fu')
+require 'lib/metric_fu'
 
 desc "Run all specs in spec directory"
 Spec::Rake::SpecTask.new(:spec) do |t|
   t.spec_files = FileList['spec/**/*_spec.rb']
+   t.rcov = true
+   t.rcov_opts = ['--exclude', 'spec,config,Library,usr/lib/ruby']
+   t.rcov_dir = File.join(File.dirname(__FILE__), "tmp")
 end
 
-task :default => [:"metrics:all"]
+MetricFu::Configuration.run do |config|
+end
+
+namespace :metrics do
+  desc "Generate all reports"
+  task :all do
+    MetricFu.metrics.each {|metric| MetricFu.report.add(metric) }
+    MetricFu.report.save_output(MetricFu.report.to_yaml,
+                                MetricFu.base_directory, 
+                                'report.yml')
+    MetricFu.report.save_templatized_report
+    if MetricFu.report.open_in_browser?
+      MetricFu.report.show_in_browser(MetricFu.output_directory)
+    end
+  end
+
+  MetricFu.metrics.each do |metric|
+    desc "Generate report for #{metric}"
+    task metric do
+
+      MetricFu.report.add(metric)
+      MetricFu.report.save_output(MetricFu.report.to_yaml,
+                                  MetricFu.base_directory,
+                                  'report.yml')
+      MetricFu.report.save_templatized_report
+      if MetricFu.report.open_in_browser?
+        MetricFu.report.show_in_browser(MetricFu.output_directory)
+      end
+    end
+  end
+end
+
+task :default => [:"metrics:all"]

data/TODO

@@ -10,4 +10,5 @@
 * Generate metrics:* rake tasks for each of CodeMetric's descendants
 * Update flog specs so that they actually run flog
 * Add flay specs that run flay
-* Convert readme to markdown and rename to README.mkdn so github will render it
+* Convert readme to markdown and rename to README.mkdn so github will render it
+* Saikuro.rb falls over if tries to parse an empty file.  Fair enough.  We shouldn't feed it empty files

data/lib/base/base_template.rb

@@ -0,0 +1,134 @@
+module MetricFu
+
+  # The Template class is intended as an abstract class for concrete
+  # template classes to subclass.  It provides a variety of utility
+  # methods to make templating a bit easier.  However, classes do not
+  # have to inherit from here in order to provide a template.  The only
+  # requirement for a template class is that it provides a #write method
+  # to actually write out the template.  See StandardTemplate for an
+  # example.
+  class Template
+    attr_accessor :report
+    
+    private
+    # Creates a new erb evaluated result from the passed in section.
+    #
+    # @param section String
+    #   The section name of 
+    #
+    # @return String
+    #   The erb evaluated string
+    def erbify(section)
+      require 'erb'
+      erb_doc = File.read(template(section))
+      ERB.new(erb_doc).result(binding)
+    end
+
+    # Determines whether a template file exists for a given section
+    # of the full template.
+    #
+    # @param section String
+    #   The section of the template to check against
+    #
+    # @return Boolean
+    #   Does a template file exist for this section or not?
+    def template_exists?(section)
+      File.exist?(template(section))
+    end
+    
+    # Copies an instance variable mimicing the name of the section
+    # we are trying to render, with a value equal to the passed in 
+    # constant.  Allows the concrete template classes to refer to 
+    # that instance variable from their ERB rendering
+    #
+    # @param section String
+    #  The name of the instance variable to create
+    #
+    # @param contents Object
+    #   The value to set as the value of the created instance
+    #   variable
+    def create_instance_var(section, contents)
+      instance_variable_set("@#{section}", contents)        
+    end
+
+    # Generates the filename of the template file to load and 
+    # evaluate.  In this case, the path to the template directory +
+    # the section name + .html.erb
+    #
+    # @param section String
+    #   A section of the template to render
+    #
+    # @return String
+    #   A file path
+    def template(section)
+      File.join(this_directory,  section.to_s + ".html.erb")
+    end
+
+    # Returns the filename that the template will render into for
+    # a given section.  In this case, the section name + '.html'
+    #
+    # @param section String
+    #   A section of the template to render
+    #
+    # @return String
+    #   The output filename
+    def output_filename(section)
+      section.to_s + ".html"
+    end
+
+    # Returns the contents of a given css file in order to 
+    # render it inline into a template.
+    #
+    # @param css String
+    #   The name of a css file to open
+    #
+    # @return String
+    #   The contents of the css file
+    def inline_css(css)
+      open(File.join(this_directory, css)) { |f| f.read }      
+    end
+  
+    # Provides a link to open a file through the textmate protocol
+    # on Darwin, or otherwise, a simple file link.
+    #
+    # @param name String
+    #   
+    # @param line Integer
+    #   The line number to link to, if textmate is available.  Defaults
+    #   to nil
+    #
+    # @return String
+    #   An anchor link to a textmate reference or a file reference
+    def link_to_filename(name, line = nil)
+      filename = File.expand_path(name)
+      if MetricFu.configuration.platform.include?('darwin')
+        "<a href='txmt://open/?url=file://" \
+        +"#{filename}&line=#{line}'>#{name}:#{line}</a>"
+      else 
+       "<a href='file://#{filename}'>#{name}:#{line}</a>"
+      end
+    end
+  
+
+    # Provides a brain dead way to cycle between two values during
+    # an iteration of some sort.  Pass in the first_value, the second_value,
+    # and the cardinality of the iteration.
+    #
+    # @param first_value Object
+    #
+    # @param second_value Object
+    #
+    # @param iteration Integer
+    #   The number of times through the iteration.
+    #
+    # @return Object
+    #   The first_value if iteration is even.  The second_value if
+    #   iteration is odd.
+    def cycle(first_value, second_value, iteration)
+      return first_value if iteration % 2 == 0
+      return second_value
+    end      
+    
+
+  end
+end

data/lib/base/configuration.rb

@@ -0,0 +1,187 @@
+module MetricFu
+
+  # A list of metrics which are available in the MetricFu system.
+  #
+  # These are metrics which have been developed for the system.  Of
+  # course, in order to use these metrics, their respective gems must
+  # be installed on the system.
+  AVAILABLE_METRICS = [:churn, :flog, :flay, :reek, 
+                       :roodi, :saikuro, :rcov]
+
+
+  # The @@configuration class variable holds a global type configuration
+  # object for any parts of the system to use.
+  def self.configuration
+    @@configuration ||= Configuration.new
+  end
+
+  # = Configuration
+  #
+  # The Configuration class, as it sounds, provides methods for
+  # configuring the behaviour of MetricFu.
+  #
+  # == Customization for Rails
+  #
+  # The Configuration class checks for the presence of a
+  # 'config/environment.rb' file.  If the file is present, it assumes
+  # it is running in a Rails project.  If it is, it will:
+  #
+  # * Add 'app' to the @code_dirs directory to include the
+  #   code in the app directory in the processing
+  # * Add :stats to the list of metrics to run to get the Rails stats
+  #   task
+  #
+  # == Customization for CruiseControl.rb
+  #
+  # The Configuration class checks for the presence of a 
+  # 'CC_BUILD_ARTIFACTS' environment variable.  If it's found
+  # it will change the default output directory from the default
+  # "tmp/metric_fu to the directory represented by 'CC_BUILD_ARTIFACTS'
+  #
+  # == Deprications
+  #
+  # The Configuration class checks for several deprecated constants
+  # that were previously used to configure MetricFu.  These include
+  # CHURN_OPTIONS, DIRECTORIES_TO_FLOG, SAIKURO_OPTIONS, 
+  # and MetricFu::SAIKURO_OPTIONS.
+  #
+  # These have been replaced by config.churn, config.flog and
+  # config.saikuro respectively.
+  class Configuration
+
+    def initialize #:nodoc:#
+      warn_about_deprecated_config_options
+      reset
+      add_attr_accessors_to_self
+      add_class_methods_to_metric_fu
+    end
+  
+    # Searches through the instance variables of the class and
+    # creates a class method on the MetricFu module to read the value
+    # of the instance variable from the Configuration class.
+    def add_class_methods_to_metric_fu
+      instance_variables.each do |name|
+        method_name = name[1..-1].to_sym
+        method = <<-EOF
+                  def self.#{method_name}
+                    configuration.send(:#{method_name})
+                  end
+        EOF
+        MetricFu.module_eval(method)
+      end
+    end
+   
+    # Searches through the instance variables of the class and creates
+    # an attribute accessor on this instance of the Configuration 
+    # class for each instance variable.
+    def add_attr_accessors_to_self
+      instance_variables.each do |name|
+        method_name = name[1..-1].to_sym
+        MetricFu::Configuration.send(:attr_accessor, method_name)
+      end
+    end
+
+    # Check if certain constants that are deprecated have been
+    # assigned.  If so, warn the user about them, and the 
+    # fact that they will have no effect.
+    def warn_about_deprecated_config_options
+      if defined?(::MetricFu::CHURN_OPTIONS)
+        raise("Use config.churn instead of MetricFu::CHURN_OPTIONS")
+      end
+      if defined?(::MetricFu::DIRECTORIES_TO_FLOG)
+        raise("Use config.flog[:dirs_to_flog] "+
+              "instead of MetricFu::DIRECTORIES_TO_FLOG") 
+      end
+      if defined?(::MetricFu::SAIKURO_OPTIONS)
+        raise("Use config.saikuro instead of MetricFu::SAIKURO_OPTIONS")
+      end
+      if defined?(SAIKURO_OPTIONS)
+        raise("Use config.saikuro instead of SAIKURO_OPTIONS")
+      end
+    end
+
+    # This allows us to have a nice syntax like:
+    #
+    #   MetricFu.run do |config|
+    #     config.base_directory = 'tmp/metric_fu'
+    #   end
+    #
+    # See the README for more information on configuration options.
+    def self.run
+      yield MetricFu.configuration
+    end
+   
+    # This does the real work of the Configuration class, by setting
+    # up a bunch of instance variables to represent the configuration
+    # of the MetricFu app.
+    def reset
+      @base_directory = ENV['CC_BUILD_ARTIFACTS'] || 'tmp/metric_fu'
+      @scratch_directory = File.join(@base_directory, 'scratch')
+      @output_directory = File.join(@base_directory, 'output')
+      @metric_fu_root_directory = File.join(File.dirname(__FILE__), 
+                                                        '..', '..')
+      @template_directory =  File.join(@metric_fu_root_directory, 
+                                       'lib', 'templates') 
+      @template_class = StandardTemplate
+      set_metrics
+      set_code_dirs
+      @flay     = { :dirs_to_flay => @code_dirs  } 
+      @flog     = { :dirs_to_flog => @code_dirs  }
+      @reek     = { :dirs_to_reek => @code_dirs  }
+      @roodi    = { :dirs_to_roodi => @code_dirs }
+      @saikuro  = { :output_directory => @scratch_directory + '/saikuro', 
+                    :input_directory => @code_dirs,
+                    :cyclo => "",
+                    :filter_cyclo => "0",
+                    :warn_cyclo => "5",
+                    :error_cyclo => "7",
+                    :formater => "text"}
+      @churn    = {}
+      @stats    = {}
+      @rcov     = { :test_files => ['test/**/*_test.rb', 
+                                    'spec/**/*_spec.rb'],
+                    :rcov_opts => ["--sort coverage", 
+                                   "--no-html", 
+                                   "--text-coverage",
+                                   "--no-color",
+                                   "--profile",
+                                   "--rails",
+                                   "--exclude /gems/,/Library/,spec"]}
+    end
+
+    # Perform a simple check to try and guess if we're running
+    # against a rails app.
+    #
+    # @todo  This should probably be made a bit more robust.
+    def rails?
+      @rails = File.exist?("config/environment.rb")
+    end
+
+    # Add the :stats task to the AVAILABLE_METRICS constant if we're
+    # running within rails.
+    def set_metrics
+      if rails?
+        @metrics = MetricFu::AVAILABLE_METRICS + [:stats]
+      else
+        @metrics = MetricFu::AVAILABLE_METRICS
+      end 
+    end
+
+    # Add the 'app' directory if we're running within rails.
+    def set_code_dirs
+      if rails?
+        @code_dirs = ['app', 'lib']
+      else
+        @code_dirs = ['lib']
+      end
+    end
+    
+    def platform #:nodoc:
+      return PLATFORM
+    end
+    
+    def is_cruise_control_rb?
+      !!ENV['CC_BUILD_ARTIFACTS']
+    end
+  end
+end

data/lib/base/generator.rb

@@ -0,0 +1,144 @@
+module MetricFu
+
+  # = Generator
+  #
+  # The Generator class is an abstract class that provides the 
+  # skeleton for producing different types of metrics.
+  #
+  # It drives the production of the metrics through a template 
+  # method - #generate_report(options={}).  This method calls
+  # #emit, #analyze and #to_h in order to produce the metrics.
+  #
+  # To implement a concrete class to generate a metric, therefore,
+  # the class must implement those three methods. 
+  #
+  # * #emit should take care of running the metric tool and 
+  #   gathering its output.  
+  # * #analyze should take care of manipulating the output from
+  #   #emit and making it possible to store it in a programmatic way.
+  # * #to_h should provide a hash representation of the output from
+  #   #analyze ready to be serialized into yaml at some point.
+  #
+  # == Pre-conditions
+  #
+  # Based on the class name of the concrete class implementing a
+  # Generator, the Generator class will create a 'metric_directory'
+  # named after the class under the MetricFu.scratch_directory, where
+  # any output from the #emit method should go.
+  #
+  # It will also create the MetricFu.output_directory if neccessary, and
+  # in general setup the directory structure that the MetricFu system
+  # expects.
+  class Generator
+    attr_reader :report, :template
+
+    def initialize(options={})
+      create_metric_dir_if_missing
+      create_output_dir_if_missing
+    end
+    
+    # Creates a new generator and returns the output of the 
+    # #generate_report method.  This is the typical way to 
+    # generate a new MetricFu report. For more information see
+    # the #generate_report instance method.
+    #
+    # @params options Hash
+    #   A currently unused hash to configure the Generator
+    #
+    # @see generate_report
+    def self.generate_report(options={})
+      generator = self.new(options)
+      generator.generate_report
+    end
+
+    # Provides the unqualified class name of an implemented concrete
+    # class, as a string.  For example:
+    #
+    #   class Flay < Generator; end
+    #   klass = Flay.new
+    #   klass.class_name
+    #   > "flay"
+    #
+    # @return String
+    #   The unqualified class name of this concrete class, returned
+    #   as a string.
+    def self.class_name
+      self.to_s.split('::').last.downcase
+    end
+   
+    # Returns the directory where the Generator will write any output
+    def self.metric_directory
+      File.join(MetricFu.scratch_directory, class_name) 
+    end
+
+    def create_metric_dir_if_missing #:nodoc:
+      unless File.directory?(metric_directory)
+        FileUtils.mkdir_p(metric_directory, :verbose => false) 
+      end
+    end
+    
+    def create_output_dir_if_missing #:nodoc:
+      unless File.directory?(MetricFu.output_directory)
+        FileUtils.mkdir_p(MetricFu.output_directory, :verbose => false) 
+      end
+    end
+
+    # @return String
+    #   The path of the metric directory this class is using.
+    def metric_directory
+      self.class.metric_directory
+    end
+
+   
+    # Defines some hook methods for the concrete classes to hook into.
+    %w[emit analyze].each do |meth|
+      define_method("before_#{meth}".to_sym) {}
+      define_method("after_#{meth}".to_sym) {}
+    end
+    define_method("before_to_h".to_sym) {}
+
+    # Provides a template method to drive the production of a metric
+    # from a concrete implementation of this class.  Each concrete
+    # class must implement the three methods that this template method
+    # calls: #emit, #analyze and #to_h.  For more details, see the
+    # class documentation.
+    #
+    # This template method also calls before_emit, after_emit... etc.
+    # methods to allow extra hooks into the processing methods, and help
+    # to keep the logic of your Generators clean.
+    def generate_report
+      %w[emit analyze].each do |meth|
+        send("before_#{meth}".to_sym)
+        send("#{meth}".to_sym)
+        send("after_#{meth}".to_sym)
+      end
+      before_to_h()
+      to_h()
+    end
+
+
+    def emit #:nodoc:
+      raise <<-EOF
+        This method must be implemented by a concrete class descending
+        from Generator.  See generator class documentation for more 
+        information.
+      EOF
+    end
+
+    def analyze #:nodoc:
+      raise <<-EOF
+        This method must be implemented by a concrete class descending
+        from Generator.  See generator class documentation for more 
+        information.
+      EOF
+    end
+
+    def to_h #:nodoc:
+      raise <<-EOF
+        This method must be implemented by a concrete class descending
+        from Generator.  See generator class documentation for more 
+        information.
+      EOF
+    end
+  end
+end