rabal 0.0.1

data/README.PLUGIN

@@ -0,0 +1,276 @@
+== How to Develop a Plugin for Rabal
+
+Rabal uses the +gem_plugin+ gem to manage its plugins.  A basic plugin
+is a single class that inherits from Rabal::Plugin::Foundation.
+
+A plugin has +parameters+ a +description+ and a flag +use_always+ which
+indicates if the plugin's use is required. 
+
+== Basic Plugin - only directory/file structure
+
+The basic Rabal::Plugin::Test that ships with rabal demonstrates the
+default behavior of a plugin.  
+
+    1: require 'rabal/plugin/foundation'
+    2:  module Rabal
+    3:     module Plugin
+    4:         class Test < Rabal::Plugin::Base "/rabal/test"
+    5:             description "Add a Test::Unit framework."
+               end
+           end
+        end
+
+This is the 'test' plugin that ships with rabal.  It shows all that is
+required for a basic plugin that only has a directory/file structure
+associated with it.
+
+    test/
+    test/rabal.project_test.rb.erb
+    test/test_helper.rb.erb
+
+This is the directory template associated with the test plugin.  Lets
+walk through the code line by line.
+
+1. every plugin depends upon Rabal::Plugin::Foundation
+2. Top level module for Rabal
+3. Rabal module containing all plugins 
+4. Declare a *Test* plugin that is registered as +/rabal/test+ in the
+   plugin registry.  It is *critical* that your plugin be declared in
+   this manner.  There is great Ruby voodoo happening here.  All your
+   Rabal plugins must be declared as inheriting from Rabal::Plugin::Base
+   with the registration *path* following. You will probably want to use
+   "/mypluginproject/pluginname" as the registration path.
+5. describe your plugin
+
+Associated with your plugin is a directory tree.  This tree should be
+located in the +resources+ directory under the root of your gem.  This
+will enable the resources to be named and accessed via the
++resource_by_name+ method available from within your plugin.
+
+In your directory tree, if +rabal.project+ is in the file or directory
+path it will be replaced with the project name from the +rabal+ command.
+
+The parameters of your plugin, along with parameters associated with
+plugins further up the directory structure are available in your ERB
+templates.  The scope of parameters is explained further down.
+
+== Default Plugin Behavior
+
+In many cases all you will need to do is declare the appropriate class,
+add some parameters and a description and let the default behavior take
+over.  Lets look at the +initialize+ method of Rabal::Plugin::Foundation
+to see what happens in the default case.
+
+    1. def initialize(options = {}) 
+    2.     @parameters = OpenStruct.new(options)
+    3.     validate_parameters
+    4.     main_tree_name = my_main_tree_name
+    5.     @tree = PluginTree.new(options,resource_by_name(main_tree_name), File.basename(main_tree_name))
+       end
+
+The default behavior of a plugin is pretty straight forward.
+
+1. It is initialized with a Hash representing the +parameter+'s given on
+   the command line that apply to this plugin.  
+2. Convert the +options+ into an OpenStruct.  This is fairly important
+   as this is how the +parameters+ get exposed to the ERB templates.
+3. Validate the parameters.  The default mechanism is just to make sure
+   that each declare +parameter+ is present and has a non-nil value.
+   Override +validate_parameters+ to validate via your own mechanism.
+   If the validation fails, you should raise PluginParameterMissingError
+   with an appropriate message.
+4. +my_main_tree_name+ is a method from the parent class of all plugins,
+   Rabal::Plugin::Foundation.  It gives the name of the default
+   directory from within the +resources+ of the gem. This is assumed to
+   be <tt>trees/plugin_name</tt>.
+5. Create a PluginTree instance from the default resource directory.
+   This recursively descends the source directory creating all
+   DirectoryTree and FileTree instances that are necessary to represent
+   the tree below +my_main_tree_name+.  
+   
+=== IMPORTANT!!! All plugins are required to have a 'tree' method which returns something that is kind_of?(Tree)
+
+As an example of the default behavior, from the root of the rabal gem,
+the Rabal::Plugin::Test plugin has a resource directory structure of:
+
+    rabal/resources/trees/test
+    rabal/resources/trees/test/rabal.project_test.rb.erb
+    rabal/resources/trees/test/test_helper.rb.erb
+
+This will result in the following items being created, assuming a
+project name of +myproj+.
+
+    myproj/test
+    myproj/test/myproj_test.rb
+    myproj/test/test_helper.rb
+
+The +rabal.project+ items from the path are automatically replaced with
+the +project+ name given on the command line.  Each of the .erb files is
+run through ERB.
+
+== Plugin with Parameters and non-default behavior
+
+The Rabal::Plugin::License plugin that ships with Rabal is a good example of a
+plugin that uses the currently available DSL for declaring plugins, and
+utilizing non-default behavior.
+
+     module Rabal
+         module Plugin
+   1:       class License < Rabal::Plugin::Base "/rabal/license"
+   2:           TYPES = %w[BSD GPL LGPL MIT Ruby]
+   3:           parameter "flavor", "Flavor of License for your project: #{TYPES.join(', ')}"
+   4:           description "Indicate under what license your project is released."
+   5:           use_always
+
+   7:           def initialize(options)
+   6:               @parameters = OpenStruct.new(options)
+   8:               if not @parameters.respond_to?(:flavor) then
+                        raise PluginParameterMissingError, "Missing parameter 'flavor' from license plugin.  See --use-license --help"
+                    end
+                    suffix = @parameters.flavor
+                    if TYPES.include?(suffix) then
+   9:                   resource_dir = resource_by_name(my_main_tree_name)
+  10:                   @tree = DirectoryTree.new(".")
+  11:                   Dir.glob(File.join(resource_dir,"*.#{suffix.downcase}")).each do |file|
+                            @tree << FileTree.from_file(file)
+                        end
+                    else
+  12:                   raise PluginParameterMissingError, "Invalid value '#{suffix}' for 'flavor' parameter from license plugin.  Only #{TYPES.join(",")} are currently supported."
+                    end
+                end
+            end
+        end
+    end
+
+Again lets walk through the indicated lines and describe what is
+happening.
+
+1. Declare the License plugin and register it as +/rabal/license+
+2. Class level constants used internally by Rabal::Plugin::License.
+3. Declare a plugin parameter.  The form here is <tt>parameter name,
+   description</tt>.  The +flavor+ parameter will be exposed on the
+   command line as <tt>--license-flavor</tt> and the parameter description will
+   appear next to the option when <tt>--help</tt> is used on the command line.
+4. Declare the plugin description.  This appears in <tt>AVAILABLE
+   MODULES</tt> section in the <tt>--help</tt>.
+5. Declare that this plugin is always used.  It is listed with a '*'
+   next to it in <tt>AVAILABLE MODULES</tt> and its <tt>MODULE
+   OPTIONS</tt> are always listed in <tt>--help</tt>.
+6. When a plugin is instantiated, it is passed as Hash in the +options+
+   parameter to +initialize+.  This +options+ parameter contains the
+   results of the command line options for this plugin.  In this case if
+   the <tt>--license-flavor</tt> command line option was used +options+
+   will be a Hash with a :flavor key.
+7. Convert +options+ to a local OpenStruct for easy use.  The default
+   initializer in Rabal::Plugin::Foundation has this behavior
+8. Validate that the +flavor+ parameter was given on the command line.
+   The default behavior if no +initialize+ method overwritten is to
+   validate that all of a plugins +parameters+ have a non-nil value.
+9. Access the directory within the plugin containing the files that this
+   plugin will use.  In this case that directory happens to be
+   +gem_directory/resources/trees/license/+
+10. Every Plugin is required to have a +@tree+ instance variable.  This
+    creates a new DirectoryTree instance and associates it with the "."
+    directory within the resulting project structure.  This in effect
+    makes this DirectoryTree instance at the *root* of the project
+    structure.
+11. Loop over the files available in the resource directory finding the
+    file(s) that have an +flavor+ extension.  Each of the files that
+    matches is associated with a FileTree instance which will take care
+    of the ERB necessities.  The FileTree instances are added to the
+    DirectoryTree created in the previous step.  As a result the file(s)
+    created here will appear in the *root* directory of the resulting
+    project tree.
+12. Raise an error indicating that the +flavor+ parameter was given an
+    invalid value. This error will be caught by the rabal application and
+    displayed to the end user.
+
+
+== Packaging
+
+It is assumed that your plugin will be packaged as a gem.  To make your
+plugin available to rabal it must be dependent upon both rabal and
+gem_plugin.  This is achieved by something similar to the following to
+your gem specification.
+
+   Gem::Specification.new do |s|
+        ...
+        s.add_dependency("gem_plugin")
+        s.add_dependency("rabal")
+        ...
+   end
+
+If this is done, when your gem is installed you can check that your gem
+is seen with Rabal by doing:
+
+    rabal --use-all --help
+
+This will display all the available plugins and their command line
+options.
+
+== Resources and Trees
+
+At the core of rabal are the resource trees utilized by the plugins to
+generate an output directory/file structure.  These tree _templates_ are
+stored within your gem under the +resources/trees+ directory from
+withing your gem. 
+
+You can get a jump start on your plugin project with:
+
+    rabal --core-author="My Name" --core-email=author@example.com --license-flavor=MIT --use-test myrabalplugin
+    mkdir -p myrabalplugin/resources/trees/xyzzy
+
+The declaration of your plugin in the .rb file should look something
+like:
+
+    class MyRabalPlugin < Rabal::Plugin::Base "/myrabalplugin/xyzzy"
+    ...
+    end
+
+Notice the *xyzzy* in both the resource directory and the plugin class
+declaration.  That is the convention to allow the default plugin
+behavior to work.
+
+A String containing the path to the *xyzzy* directory structure is
+returned from the nested calls:
+
+    resource_by_name(my_main_tree_name)
+
++my_main_tree_name+ returns +trees/xyzzy+ and +resource_by_name+ will
+return +/path/to/gem/resources/trees/xyzzy+.
+
+A later release of rabal will include a rabal plugin generation plugin
+to simplify the creation of rabal plugins.  
+
+== Parameter scope
+
+The internal mechanisms of rabal use a Tree data structure to represent
+the directories and files that are created by rabal.  Each node in the
+tree is represented by a Tree or child class such as DirectoryTree or
+FileTree.  Each Tree has a +@parameters+ instance variable, which is
+by convention an instance of OpenStruct. It can be any object though.
+
+Any Tree instance or erb template when it is evaluated has access to any
+method on its own Tree or any Tree above it in its path, terminating at
+the *root* of the Tree which is created by Rabal::Plugin::Core.
+
+Essentially, in a Tree instance or in an ERB template +method_missing+
+is defined such that the method call cascades up the Tree data structure
+until a Tree node is found that either responds to that method or has a
++@parameters+ instance variable that responds to the method call.  
+
+If the call cascades all the way to the *root* and nothing responds to
+it, then NoMethodError is raised.  
+
+=== Core Parameters
+
+Since Rabal::Plugin::Core is the plugin that creates the root of the
+entire tree, its +@parameters+ are available.  Currently these are
+available during tree generation as:
+
+* *root.name* - the name of the project from the command line
+* *author* - the author of the project from the <tt>--core-author</tt> option
+* *email* - the email address of the author from the <tt>--core-email</tt> option
+
+This list will continue to grow as rabal evolves.
+

data/bin/rabal

@@ -0,0 +1,12 @@
+#!/usr/bin/env ruby
+
+require 'rubygems'
+
+begin 
+    require 'rabal'
+rescue LoadError => e
+    $: << File.expand_path(File.join(File.dirname(__FILE__),"..","lib"))
+    retry
+end
+
+Rabal.application.run(ARGV)

data/lib/rabal/action_tree.rb

@@ -0,0 +1,42 @@
+require 'rabal/tree'
+
+module Rabal
+    class ActionTree < Tree
+
+        def initialize(data)
+            super(data)
+        end
+
+        def before_action
+        end
+
+        def action
+            raise NotImplementedError, "Oops, forgot to implement 'action'"
+        end
+
+        def after_action 
+        end
+
+        # 
+        # Walk the tree recursively processing each subtree.  The
+        # process is:
+        #  
+        # * execute before_action
+        # * execute action
+        # * process each child
+        # * execute after_action
+        #  
+        #
+        def process
+            before_action
+
+            action
+
+            children.each_pair do |name,child|
+                child.process
+            end
+
+            after_action
+        end
+    end 
+end

data/lib/rabal/application.rb

@@ -0,0 +1,209 @@
+require 'main'
+
+module Rabal
+    #
+    # The Rabal application 
+    #
+    class Application
+
+        attr_accessor :main
+        attr_accessor :plugin_manager
+        attr_accessor :plugin_load_option_names
+        attr_accessor :plugin_option_names
+        attr_accessor :global_option_names
+        attr_accessor :app_argv
+
+        def initialize
+            @main = nil
+            @plugin_manager = GemPlugin::Manager.instance
+            @plugin_option_names = []
+            @global_option_names = %w[directory use-all logfile verbosity version help]
+            @plugin_load_option_names = []
+            @app_argv = []
+            setup_plugins
+        end
+
+        #
+        # Load any and all plugins that are available.  This includes
+        # built in plugins and those that are accessible via gems.
+        #
+        def setup_plugins 
+            plugin_manager.load "rabal" => GemPlugin::INCLUDE
+
+            # make sure that we are listed as a plugin generally this is
+            # only going to happen if run from outside a gem.  Basically
+            # while Jeremy is testing. 
+            if not plugin_manager.loaded?("rabal") then
+                plugin_manager.gems["rabal"] = ROOT_DIR
+            end
+
+
+            # Each plugin has its own options so iterate over the
+            # available plugins, and create an instance of Main for each
+            # plugin.  The options for the plugin will be merged with
+            # the global options, and depending on the --load-<plugin>
+            # options indicated, they will alter the --help
+
+            plugin_manager.plugins.each do |category,plugins|
+                plugins.each do |key,plugin|
+                    plugin_load_name = plugin.name.split("::").last.downcase.dashify
+
+                    # add the --load-<plugin> option to the global
+                    # options
+                    p_use_name = "use-#{plugin_load_name}"
+                    plugin_load_option_names << p_use_name
+
+                    # local variable to build up info from within eval.
+                    pons = []
+
+                    main.class.class_eval { 
+                        option(p_use_name) { 
+                            description "Use plugin #{plugin.name}" 
+                        }
+
+                        # add in the plugin options.  Although these are
+                        # present in the global main, they won't
+                        # actually get displayed in the --help
+                        plugin.parameters.each do |pname,pconf|
+                            p_option_name = "#{plugin_load_name}-#{pconf[0]}=[p]"
+                            pons << p_option_name
+                            option(p_option_name) { description pconf[1] } 
+                        end
+                    } 
+                    plugin_option_names.concat(pons)
+                end
+            end
+        end
+
+        #
+        # Use Ara's awesome main gem to deal with command line parsing
+        #
+        def main
+            return @main if @main
+            @main = Main.new(app_argv) {
+                description Rabal::DESCRIPTION
+                author      Rabal::AUTHOR
+                version     Rabal::VERSION
+
+                # Project, the whole reason rabal exists
+                argument("project") {
+                    description "The project on which rabal is executing."
+                }
+
+                # Global Options   
+                option("directory=d","d") {
+                    description "The directory in which to create the project directory."
+                    validate    { |d| File.directory?(d) }
+                    default     Dir.pwd
+                }
+
+                option("use-all","a") { description "Use all available plugins." }
+                option("logfile=l","l") {
+                    description "The location of the logfile"
+                    default     STDOUT
+                }
+
+                option("verbosity=v","v") {
+                    validate    { |p| Logger::SEV_LABEL.include?(p.upcase) }
+                    description "One of : #{Logger::SEV_LABEL.join(", ")}"
+
+                }
+
+                option("version","V") { 
+                    description "Display the version number"
+                }
+
+                def run
+                    Rabal.application.rabalize
+                end
+            }
+        end
+
+        #
+        # Invoke main to do its thing and kick off the application
+        # Main keeps a reference to the array that it originally started
+        # with when it was created.   So you have to have that first,
+        # then fill it up later.
+        #
+        def run(in_argv = ARGV)
+            app_argv.clear
+            app_argv.concat in_argv.dup
+            begin
+                # create a separate usage object for rabal that can hook
+                # in and figure out what parameters were given on the
+                # command line
+                u = Rabal::Usage.new(self)
+                main.usage u
+                main.run 
+            rescue ::Main::Parameter::Error => mpe
+                puts "Parameter Error: #{File.basename($0)}: #{mpe.message}"
+                puts "Try `#{File.basename($0)} --help' for more information."
+                exit 1
+            end
+        end
+
+        #
+        # Get down and do stuff.  Now that all the options have been
+        # parsed, plugins loaded, some activate, etc.  
+        #
+        def rabalize
+            # create the core plugin to start things off
+            pwd = Dir.pwd
+            begin
+                core_params = params_for_plugin(Rabal::Plugin::Core)
+                core_params[:project] = main.params[:project].value
+                core = Rabal::Plugin::Core.new(core_params)
+                using_plugins.each do |p|
+                    next if p == Rabal::Plugin::Core
+                    pi = p.new(params_for_plugin(p))
+                    core.tree << pi.tree
+                end
+
+                # not using chdir blocks, as that raises
+                # warning: conflicting chdir during another chdir block
+                Dir.chdir(File.expand_path(main.params[:directory].value))
+                core.tree.process
+            rescue ::Rabal::StandardError => rse
+                puts "Application Error: #{rse.message}"
+                exit 1
+            ensure
+                Dir.chdir(pwd)
+            end
+        end
+
+        #
+        # Find a resource associated with the given gem
+        #
+        def plugin_resource(gem_name,resource_path)
+            plugin_manager.resource(gem_name,resource_path)
+        end
+
+        #
+        # return an array of all the plugin classes being used
+        #
+        def using_plugins
+            using = []
+            plugin_manager.plugins.each do |cat,plugins|
+                plugins.each do |key,plugin|
+                    if main.parameters['use-all'].given? or plugin.use_always? or 
+                        main.parameters["use-#{plugin.use_name}"].given? then
+                        using << plugin
+                    end
+                end
+            end
+            using
+        end
+
+        #
+        # return a hash of all the options for a particular plugin with
+        # the plugins name removed from the front
+        #
+        def params_for_plugin(plugin)
+            plugin_hash = {}
+            main.parameters.select{|p| p.type == :option and p.name =~ %r{^#{plugin.use_name}}}.each do |p|
+                plugin_hash[p.name.gsub("#{plugin.use_name}-",'')] = p.value
+            end
+            plugin_hash
+        end
+    end
+end

data/lib/rabal/directory_tree.rb

@@ -0,0 +1,59 @@
+require 'rabal/action_tree'
+require 'rabal/util'
+
+module Rabal
+    include Util
+    #
+    # A directory that is to be created or traversed.  When this Tree is
+    # invoked it is assumed that the current working directory is the
+    # parent of the directory this DirectoryTree represents.
+    #
+    class DirectoryTree < ActionTree
+        
+        # basename of the directory this Tree represents
+        attr_accessor :dir_name
+
+        # the File system directory that is the parent of the directory
+        # this DirectoryTree represents.
+        attr_accessor :parent_dir
+
+
+        # Create a DirectoryTree based up a name, or another directory.
+        # Only the last portion of the directory is used.  That is
+        # +File.basename+ is called upon name.
+        def initialize(name)
+            super(name)
+            @dir_name = File.basename(name)
+            @parent_dir = nil
+        end
+
+        #
+        # Make the directory if it doesn't exist 
+        #
+        def before_action
+            @parent_dir = Dir.pwd
+            if not File.directory?(dir_name) then
+                info("creating directory #{dir_name}")
+                Dir.mkdir(dir_name)
+            else
+                info("skipping directory #{dir_name} - already exists")
+            end
+        end
+
+        #
+        # change into the directory
+        #
+        def action
+            info("entering directory #{dir_name}")
+            Dir.chdir(dir_name)
+        end
+
+        #
+        # change back to the parent directory
+        #
+        def after_action
+            info("leaving directory #{dir_name}")
+            Dir.chdir(parent_dir)
+        end
+    end
+end

data/lib/rabal/error.rb

@@ -0,0 +1,7 @@
+module Rabal
+    class StandardError < ::StandardError; end
+    class TemplateNotFoundError < Rabal::StandardError ; end 
+    class PathNotFoundError < Rabal::StandardError ; end 
+    class PluginParameterMissingError < Rabal::StandardError ; end
+end
+

data/lib/rabal/file_tree.rb

@@ -0,0 +1,89 @@
+require 'rabal/action_tree'
+require 'rabal/util'
+require 'erb'
+
+module Rabal
+    include Util
+    #
+    # Represents a file to be created.  Generally a FileTree will use a
+    # source .erb file and combine it with the Rabal::Specification to
+    # create +file_contents+.  The +file_contents+ are what are written
+    # out in the action.
+    #
+    # To provide custom template or some decision making, overwrite the
+    # +before_action+ method.  So long as +file_contents+ contains the
+    # data to write out to the file by the time +action+ is called all
+    # is well.
+    #
+    class FileTree < ActionTree
+
+        # the name of the file to create
+        attr_accessor :file_name
+
+        # the erb template the file is created from as a String
+        attr_accessor :template
+        
+        # the contents of the file to write
+        attr_accessor :file_contents
+
+        class << self
+
+            #
+            # Create a new FileTree from the path to a file.  The +file_name+
+            # by default of the FileTree is basename of the path, minus any
+            # extension.  This can be altered with the +strip_extension+
+            # and +file_name+ parameters.  Passing +nil+ for the
+            # +file_name+ achieves the default behavior.
+            #
+            # The contents of the file at path will be loaded into the 
+            # +template+ member variable.
+            #
+            def from_file(path,strip_ext = true, non_default_file_name = nil)
+                template  = IO.read(File.expand_path(path))
+                file_name = non_default_file_name || File.basename(path)
+                file_name = File.basename(file_name,(strip_ext ? ".*" : ""))
+                if file_name.index("-") then
+                    file_name = file_name.underscore
+                end
+                FileTree.new(file_name,template)
+            end
+
+        end
+
+        #
+        # Create a FileTree with a name from a template
+        #
+        def initialize(file_name,template)
+            super(file_name)
+            @file_name = file_name
+            @template = template
+            @file_contents = nil
+        end
+
+        #
+        # before the file is to be created, load the appropriate
+        # template and setup any variables that need to be in the
+        # binding for erb if there is one
+        #
+        def before_action
+            info("creating content for #{file_name}")
+            @file_contents = ERB.new(template).result(binding)
+        end
+
+        #
+        # Open up the file and write the contents.  It is assumed that
+        # the present working directory is the location for the file to
+        # be created.
+        #
+        def action
+            if not File.file?(file_name) then
+                info("writing file #{file_name}")
+                File.open(file_name,"w+") do |f|
+                    f.write(file_contents)
+                end
+            else
+                info("skipping file #{file_name} - already exists")
+            end
+        end
+    end
+end