lepidoptera 0.2.0 → 0.3.0

data/README.md

@@ -10,16 +10,18 @@ Lepidoptera /ˌlɛpɪˈdɒptərə/
 What is lepidoptera?
 --------------------
 
-Lepidoptera is a very simple and easy extensible __code generator for common every day projects__.  
+Lepidoptera is a simple and easy to extend __code generator for common every day projects__.  
 Technically, Lepidoptera is a wrapper for [rubigen][r] which allows setting up code templates for arbitrary projects.
 
-Code generators integrated into Lepidoptera are structured in __generator groups__, whereas every group can have multiple __generator types__.
+Lepidopteras code generators are structured in __generator groups__. A generators group is just a container for multiple generators, where as a generator is also called a __generator type__.
 
-For the time being, Lepidoptera has code generators for the following projects (more to come):
+For the time being, Lepidoptera has code generators for the following project types (more to come):
 
-   * [jquery][j] plugins, 
-   * static pages hosted on [heroku][h], 
-   * [sinatra][s] application hosted on [heroku][h].
+* [jquery][j] generators:
+  * jquery plugin 
+* [heroku][h] generators:
+  * static pages 
+  * a [sinatra][s] application
 
 Installation
 ------------
@@ -28,68 +30,75 @@ Installation
 
 As [lep][wiki-2] (/ˈlɛp/) is a short for [lepidoptera][wiki-1], this gem will install an executable `lep`
 
-For aesthetic reasons, you may also set a synonym executable `butterfly` alias in your `.bashrc` file:
+For aesthetic reason, you may also set a synonym alias `butterfly` in your `.bashrc` file:
 
-    $ alias butterfly='lep $1'
+    alias butterfly='lep $1'
     
 Usage
 -----
 
-for grouped code generators:
-
-    lep [options] <generator-group> <generator-type> <project-name>
-
-or for ungrouped code generators:
-
-    lep [options] <generator-type> <project-name>
+    $ lep [options] <generator-group> <generator-type> <project-name>
 
 with the following __options__:
 
     -q, --quiet              Suppress status output.
+    -n, --new                Create a new code generator stub in ~/.lepidoptera.
     -g, --git                Create a git repository after code generation.
-    -n, --new                Add a new code generator in ~/.lepidoptera
     -h, --help               Print generator's options and usage.
  
-and - for the time being - the following __code generators__ which are included in this gem:
+### Helpers
 
-    heroku static
-    heroku sinatra
-    jquery plugin
-  
-Helpers
--------
-
-Get a list of all code generators grouped by generator-groups:
+Get a list of all local code generator groups:
 
     $ lep
 
-Get a list of all code generator-types for a given generator-group:
+Get a list of all code generators for a given generator group:
 
     $ lep <generator-group>
 
-Extending Code Generators
--------------------------
+Extending with own Code Generators
+----------------------------------
 
 Since lepidoptera is based on _Nic Williams_ Ruby generator framework [rubigen][r], it is very simple to add new own private code generators.
 
-You may include new code generators by putting the following code structure into `~/.lepidoptera`:
+### 1. Manual creation of new a code generator
+
+Your own private code generators must reside in a folder `~/.lepidoptera`.
+
+A new generator must satisfy the following code structure:
 
-    ~/.lepidoptera
-      └─ name
-         ├─ INFO
-         ├─ name_generator.rb
-         └─ template
-            ├─ a file
-            ├─ ...
-            └─ a folder
+    .lepidoptera
+    └─ <generator-group>_generators
+       └─ <generator-type>
+          ├─ INFO
+          ├─ <generator-type>_generator.rb
+          └─ templates
+             ├─ ...
+             └─ ...
 
-Much more easy is to use a generator generator which generates the above code generator stub into `~/.lepidoptera`: (TODO)
+whereas every code generator type must contain the following files:
+
+* an optional `INFO` file containing some additional project info to be displayed after the generation.
+* a required generator file `<generator-type>_generator.rb` which contains the generation rules.
+* a required templates folder `templates` which may contain multiple ERB templates for the code to be generated.  
+  These ERB templates may contain variables as placeholders for the following information:
+  * `<%= name %>`: Name of the project.
+  * `<%= author %>`: Author of the project (OS Username).
+
+### 2. Automatic creation of new a code generator
+
+An easier way to create a new code generator is to automatically generate the above code generator stub into `~/.lepidoptera`.
+
+To create a new code generator stub, use the `--new` option and provide a __generator group__ and a __generator type__:
+
+    $ lep -n <generator-group> <generator-type>
+    
+If the generator group does not exist already, a group folder `<generator-group>_generators` will be created.
 
-    $ lep -n <type-of-code-generator>
-    $ lep -n <code-generator-group> <type-of-code-generator>
+Embedded Code Generators
+========================
 
-Integrated Code Generators
-==========================
+The following code generators are currently embedded within this project:
         
 jQuery Generators
 -----------------

data/bin/lep

@@ -23,6 +23,7 @@ YELLOW = "\033[0;33m"
 RED    = "\033[0;31m"
 
 
+
 ### Set up generators
 
 # get code generators
@@ -38,6 +39,37 @@ parser = Butterfly::Options::Parser.new(generators)
 options = parser.parse(ARGV)
 
 
+
+### new-option? create a new code generator stub 
+if options[:new] then
+
+  # show common help if no argument is provided
+  parser.ask_for_new_generator if ARGV.empty?
+  
+  # show prticular help if only a generator group is provideds
+  parser.ask_for_new_generator_type(ARGV[0]) if ARGV.length == 1
+  
+  # create dotfolder for local code generators if not exist already
+  dot_folder = File.join(Dir.home, Butterfly::DOTFOLDER)
+  Dir.mkdir(dot_folder) if !Dir.exists?(dot_folder)
+  
+  
+  generator_group = ARGV[0]
+  generator_type = ARGV[1]
+  generator_type_folder = File.join(dot_folder, "#{generator_group}_generators", generator_type)
+
+  if !Dir.exists?(generator_type_folder)
+    stub_generator = RubiGen::PathSource.new(:app, File.dirname(__FILE__) + "/../lib/stub_generators")
+    RubiGen::Base.prepend_sources(stub_generator)
+    RubiGen::Scripts::Generate.new.run([generator_type_folder], :generator => 'stub')    
+  else
+    raise Butterfly::GeneratorFolderExists, "#{RED}generator '#{generator_group}_generators/#{generator_type}' does already exist!#{WHITE}" 
+  end
+  exit
+end
+
+
+
 # After parsing the options,
 #  * first argument should be <generator-group>
 #  * second argument should be <generator-type>
@@ -98,13 +130,6 @@ end
 project_name = ARGV[0]
 
 
-# DEBUG 
-#puts "generator group: #{generator_group}"
-#puts "generator type:  #{generator_type}"
-#puts "project name:    #{project_name}"
-#puts "options:         #{options}"
-
-
 ### generate code!
 
 # Add only the code generator of the selected generator-group to the beginning of a list of sources.

data/lepidoptera.gemspec

@@ -5,11 +5,11 @@
 
 Gem::Specification.new do |s|
   s.name = %q{lepidoptera}
-  s.version = "0.2.0"
+  s.version = "0.3.0"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["Thomas Duerr"]
-  s.date = %q{2010-11-07}
+  s.date = %q{2010-11-10}
   s.default_executable = %q{lep}
   s.description = %q{Lepidoptera is a very simple and easy extensible code generator for common every day projects.}
   s.email = %q{thomduerr@gmail.com}
@@ -43,7 +43,12 @@ Gem::Specification.new do |s|
      "lepidoptera.gemspec",
      "lib/base.rb",
      "lib/butterfly.rb",
-     "lib/options.rb"
+     "lib/options.rb",
+     "lib/stub_generators/stub/INFO",
+     "lib/stub_generators/stub/stub_generator.rb",
+     "lib/stub_generators/stub/templates/generator-type_INFO",
+     "lib/stub_generators/stub/templates/generator-type_README.txt",
+     "lib/stub_generators/stub/templates/generator-type_generator.rb"
   ]
   s.homepage = %q{http://github.com/thomd/lepidoptera/}
   s.rdoc_options = ["--charset=UTF-8"]

data/lib/base.rb

@@ -45,4 +45,33 @@ module Butterfly
   
   end
 
+end
+
+
+module Butterfly
+  module Stub
+    
+    # extend Base class wwith base functionality for the code stub generator generator
+    class Base < RubiGen::Base
+
+      attr_reader :target, :name, :author, :group, :date
+
+      def initialize(runtime_args, runtime_options = {})
+        super
+        @destination_root = File.expand_path(args.shift)
+        @name = base_name
+        @author = ENV['USER']
+        @target = @destination_root
+        @group = @destination_root.match(/\/(\w+)_generators\//)[1]
+        @date = Time.now.strftime("%Y-%m-%d")
+      end
+
+      # do some final things after generation
+      def after_generate
+        info = File.read(File.join(spec.path, 'INFO')) rescue ''
+        template = ERB.new(info, nil, '<>')
+        puts "\n#{template.result(binding)}"
+      end  
+    end
+  end
 end

data/lib/butterfly.rb

@@ -7,20 +7,26 @@ require 'rubigen'
 module Butterfly
 
   # Current version
-  VERSION = '0.2.0'
+  VERSION = '0.3.0'
+
+  # local lepidoptera folder
+  DOTFOLDER = '.lepidoptera'
 
   # path of build-in code generators
-  GENERATORS_PATH = File.join(File.dirname(__FILE__), '..', '*_generators')
+  GENERATOR_GROUPS = File.join(File.dirname(__FILE__), '..', '*_generators')
 
-  # path of user code generators
-  USER_PATH = File.join(Dir.user_home, '.lepidoptera', '*_generators')
+  # path of user code generator groups
+  USER_GROUPS = File.join(Dir.home, DOTFOLDER, '*_generators')
 
 
   # Error handling
   class GeneratorError < StandardError
   end
 
-  class GeneratorSourceMissingError < StandardError
+  class GeneratorSourceMissingError < GeneratorError
+  end
+
+  class GeneratorFolderExists < GeneratorError
   end
 
 
@@ -32,8 +38,8 @@ module Butterfly
     def initialize
       @generators = []
 
-      # loop through build in code generators and user code generators
-      [GENERATORS_PATH, USER_PATH].each do |path|
+      # loop through build in code generator groups and user code generator groups
+      [GENERATOR_GROUPS, USER_GROUPS].each do |path|
         Dir[path].each do |file|
           @generators.push(GeneratorGroup.new(file)) if File.directory?(file)
         end
@@ -74,13 +80,12 @@ module Butterfly
     # a generator-group contains a generator name, its path and its generator-types
     class GeneratorGroup
       
-      attr_accessor :name, :source, :types, :label
+      attr_accessor :name, :source, :types
       
       def initialize(file)
         @name = File.basename(file).gsub(/_generators$/, '')
         @source = RubiGen::PathSource.new(:app, file)
         @types = @source.names(:visible)
-        @label = @source.label
       end
     end
     

data/lib/options.rb

@@ -11,20 +11,24 @@ class OptionParser
   def add_default(opts)
     self.separator ""
 
-#    self.on("-n", "--new", "Add a new code generator in ~/.lepidoptera") do
-#      opts[:new] = true
-#    end
+    self.on("-n", "--new", "Create a new code generator stub in ~/.lepidoptera") do
+      opts[:new] = true
+    end
 
     self.on("-q", "--quiet", "Suppress status output") do
       opts[:quiet] = true
     end
 
-    self.on("-g", "--git","Create a git repository after code generation") do
+    self.on("-g", "--git", "Create a git repository after code generation") do
       opts[:gitinit] = true
     end
 
-#    self.on("-s", "--svn [URL]","Initial import into a given svn repository") do |url|
+#    self.on("-s", "--svn [URL]", "Initial import into a given svn repository") do |url|
 #      opts[:svnimport] = url
+#    end
+
+#    self.on("-l", "--list", "List all code generators") do 
+#      opts[:list] = true
 #    end
 
     self.on("-h", "--help", "Show help") do
@@ -107,6 +111,30 @@ module Butterfly
         exit
       end
 
+      def ask_for_new_generator
+        parser = OptionParser.new do |opts|
+          opts.banner = "Usage: #{PURPLE}#{File.basename($0)}#{WHITE} --new #{BLUE}<generator-group>#{WHITE} #{BLUE}<generator-type>#{WHITE}"
+          opts.separator ""
+          opts.define_head "Go, create a new code generator!"
+          opts.define_head ""
+          opts.separator "#{BLUE}Please enter a <generator-group> name and a <generator-type> name#{WHITE}"
+        end
+        parser.parse(["-h"])
+        exit
+      end
+
+      def ask_for_new_generator_type(generator_group)
+        parser = OptionParser.new do |opts|
+          opts.banner = "Usage: #{PURPLE}#{File.basename($0)}#{WHITE} --new #{generator_group} #{BLUE}<generator-type>#{WHITE}"
+          opts.separator ""
+          opts.define_head "Go, create a new code generator in the #{generator_group} group!"
+          opts.define_head ""
+          opts.separator "#{BLUE}Please enter a <generator-type> name#{WHITE}"
+        end
+        parser.parse(["-h"])
+        exit
+      end
+
     end
   end
 end

data/lib/stub_generators/stub/INFO

@@ -0,0 +1,17 @@
+----------
+
+(1) now, copy all your template files into: 
+    <%= target %>
+
+(2) edit your templates and insert some placeholders.
+    you have the following ERB placeholders available in your templates:
+
+    <%%= group %>:  name of the generator group (<%= group %>)  
+    <%%= name %>:   name of the generator       (<%= name %>)  
+    <%%= author %>: author of the project       (<%= author %>) 
+
+(3) write some INFO which will then be displayed after code generation.
+
+(4) test your new <%= name %> code generator:
+    $ lep <%= group %>
+    $ lep <%= group %> <%= name %> <project-name>

data/lib/stub_generators/stub/stub_generator.rb

@@ -0,0 +1,17 @@
+class StubGenerator < Butterfly::Stub::Base
+  
+  def manifest
+    record do |m|
+
+      # create templates folder
+      m.directory "templates"
+
+      # create templates
+      m.template "generator-type_INFO", "INFO"
+      m.template "generator-type_generator.rb", "#{name}_generator.rb"
+      m.template "generator-type_README.txt", "templates/README.txt"
+    end
+  end
+
+end
+

data/lib/stub_generators/stub/templates/generator-type_INFO

@@ -0,0 +1,4 @@
+----------
+<%= name %> code generator by <%= author %> (c) <%= date %>
+
+some INFO text

data/lib/stub_generators/stub/templates/generator-type_README.txt

@@ -0,0 +1,2 @@
+<%%= name %>
+============

data/lib/stub_generators/stub/templates/generator-type_generator.rb

@@ -0,0 +1,15 @@
+class <%= name.capitalize %>Generator < Butterfly::Base
+  
+  def manifest
+    record do |m|
+
+      # create folder
+      m.directory ""
+
+      # create templates
+      m.template "README.txt", "README.md"
+    end
+  end
+
+end
+

metadata

@@ -4,9 +4,9 @@ version: !ruby/object:Gem::Version
   prerelease: false
   segments: 
   - 0
-  - 2
+  - 3
   - 0
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Thomas Duerr
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2010-11-07 00:00:00 +01:00
+date: 2010-11-10 00:00:00 +01:00
 default_executable: lep
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -97,6 +97,11 @@ files:
 - lib/base.rb
 - lib/butterfly.rb
 - lib/options.rb
+- lib/stub_generators/stub/INFO
+- lib/stub_generators/stub/stub_generator.rb
+- lib/stub_generators/stub/templates/generator-type_INFO
+- lib/stub_generators/stub/templates/generator-type_README.txt
+- lib/stub_generators/stub/templates/generator-type_generator.rb
 has_rdoc: true
 homepage: http://github.com/thomd/lepidoptera/
 licenses: []