gemma 0.0.2 → 1.0.0

data/README.rdoc

@@ -2,47 +2,78 @@
 
 http://github.com/jdleesmiller/gemma
 
-== DESCRIPTION
-
-If you are using .gemspecs as intended
-(http://yehudakatz.com/2010/04/02/using-gemspecs-as-intended/), gemma generates
-common rake tasks with default settings extracted from your .gemspec file.
-
 == SYNOPSIS
 
-To create a gem called +mygem+, first create <tt>mygem.gemspec</tt> as
-described in http://yehudakatz.com/2010/04/02/using-gemspecs-as-intended/.
-
-For more information about the gemspec, see the Gem::Specification Reference
-(http://docs.rubygems.org/read/chapter/20).
-
-Then put the following at the top of your <tt>Rakefile.rb</tt>:
+Gemma is a gem development helper like hoe and jeweler, but it keeps the
+gemspec in a gemspec file, where it belongs, instead of in your Rakefile.
+This helps your gem to play nicely with commands like gem and bundle, and it
+allows gemma to provide rake tasks with sensible defaults for many common gem
+development tasks.
+
+See also http://yehudakatz.com/2010/04/02/using-gemspecs-as-intended for more
+background.
+
+=== To Create a New Gem
+
+Gemma has a simple interactive gem scaffolding tool; run
+  gemma new
+and follow the prompts. (Run with -h for help.)
+
+This gives you a simple gem template like the following:
+
+  my_new_gem
+  |-- bin
+  |   +-- my_new_gem              # executable (optional)
+  |-- .gitignore                  # helpful if you're using git
+  |-- lib
+  |   |-- my_new_gem
+  |   |   +-- version.rb          # the one and only version constant
+  |   +-- my_new_gem.rb           # the main code file 
+  |-- my_new_gem.gemspec          # gem metadata
+  |-- Rakefile.rb                 # development tasks
+  |-- README.rdoc                 # documentation
+  +-- test
+      +-- test_my_new_gem.rb      # unit tests with test/unit (optional)
+
+Things you need to change in the template are marked with a +TODO+ tag.
+
+=== To Modify an Existing Gem to use Gemma
+
+First you have to have a <tt>.gemspec</tt> file. See
+http://yehudakatz.com/2010/04/02/using-gemspecs-as-intended
+for a template and advice, and see
+http://docs.rubygems.org/read/chapter/20
+for reference material. If you have been using hoe or jeweler, you already
+have all of the information in your Rakefile, so you just have to move it into
+a <tt>.gemspec</tt> file.
+
+Gemma provides rake tasks with sensible defaults based on the contents of
+your gemspec; to enable them, add the following to the top of your +Rakefile+:
   begin
     require 'rubygems'
     require 'gemma'
 
-    Gemma::RakeTasks.with_gemspec_file 'mygem.gemspec'
+    Gemma::RakeTasks.with_gemspec_file 'my_gem.gemspec'
   rescue LoadError
     # Gemma is not installed; print an (optional) message:
     puts "Install gemma (sudo gem install gemma) for standard rake tasks."
   end
 
-This gives you a list of standard rake tasks with settings based on your
-gemspec, in addition to any that you define yourself. (Note that the yard task
-only appears if you have the yard gem installed.)
+This gives you some standard rake tasks, in addition to any that you define
+yourself. (Note that the yard task only appears if you have the yard (yardoc)
+gem installed.)
 
   rake clean         # Remove any temporary products.
   rake clobber       # Remove any generated file.
-  rake clobber_rcov  # Remove rcov products for rcov
-  rake clobber_rdoc  # Remove rdoc products
   rake rcov          # Analyze code coverage with tests
   rake rdoc          # Build the rdoc HTML Files
-  rake rerdoc        # Force a rebuild of the RDOC files
   rake test          # Run tests
   rake yard          # Generate YARD Documentation
+  ... and more!
+
+Run <tt>rake -T</tt> for a full list of tasks.
 
-You can customize the generated tasks by passing a block to
-+with_gemspec_file+:
+You can customize the standard tasks by passing a block to +with_gemspec_file+:
 
   Gemma::RakeTasks.with_gemspec_file 'mygem.gemspec' do |g|
     g.rdoc.title = 'My Gem Is Great'
@@ -53,34 +84,35 @@ See the gemma API docs for more information.
 == REQUIREMENTS
 
 You must have ruby, rubygems and rake installed. Tasks are also included for
-rcov (http://eigenclass.org/hiki.rb?rcov) and yard (http://yardoc.org/).
+rcov (http://eigenclass.org/hiki.rb?rcov) and yard (http://yardoc.org/), if you
+have them installed. Other dependencies are handled automatically.
 
 Gemma has been tested on:
-* x86-linux (Ubuntu 10.04) with Ruby 1.8.7p249
-* x86-linux (rvm) with Ruby 1.9.2p0 (2010-08-18 revision 29034)
+* x86-linux (Ubuntu 10.10) with Ruby 1.8.7p299
+* x86-linux (rvm) with Ruby 1.9.2p0 (2010-08-18 revision 29036)
 * x86_64-linux (CentOS) with Ruby 1.8.7p72
-* with yard 0.5.8 and 0.6.1
-* with rcov 0.9.6 and 0.9.9
+* with yard 0.5.8 and 0.6.3
+* with rcov 0.9.7.1 and 0.9.9
 Gemma has not yet been tested on Windows.
 
-== INSTALL
+== INSTALLATION
 
-You should be able to install with
+On *nix:
 
-  gem install gemma
+  sudo gem install gemma
 
-Alternatively, you can get the source with
+== DEVELOPMENT
 
+To get the source and development depencies:
   git clone git://github.com/jdleesmiller/gemma.git
-
-and run
-
+  cd gemma
   gem build gemma.gemspec
-  gem install gemma-<version>.gem
+  sudo gem install gemma-X.X.X.gem --development
+where X.X.X is the current gemma version.
 
 == RELATED PROJECTS
 
-There are many projects that make gem development easier.
+There are many projects that help to automate common gem development tasks.
 Hoe and Jeweler are the most popular; they generate the gemspec and tasks using
 a configuration specified in the Rakefile, which is the opposite to what gemma
 does. Mr Bones is a gem template generator that appears to be similar to Hoe
@@ -90,6 +122,13 @@ and Jeweler, but I haven't used it myself.
 * http://github.com/technicalpickles/jeweler 
 * http://codeforpeople.rubyforge.org/bones/ 
 
+Bundler also provides some support for gem development. It includes a simple gem
+scaffolding generator, and the results are compatible with gemma. It also
+includes some rake extensions for building, installing and releasing gems
+(Bundler::GemHelper). (As of version 1.0.7.)
+* http://gembundler.com
+* http://gembundler.com/rubygems.html
+
 gemesis provides tasks for building, releasing and installing gems based on the
 gemspec, but (at the time of writing) it doesn't provide tasks for tests and
 documentation, etc.
@@ -101,6 +140,7 @@ gemspec, and it looks like it should work fairly well with gemma.
 
 * http://github.com/luislavena/rake-compiler
 
+
 Other helpful articles:
 
 * http://rubygems.rubyforge.org/rubygems-update/Gem/Version.html
@@ -116,12 +156,20 @@ Other helpful articles:
       g.yard_dev.options.push('--protected', '--private')
     end
 * more tasks (e.g. to publish docs)
-* generate gem skeletons
 * tasks for version control? (see http://github.com/nvie/gitflow)
 * contributions welcome!
 
 == HISTORY
 
+<em>1.0.0</em>
+* added templates
+* changed rdoc and yard tasks to use +require_paths+ instead of +files+ 
+* more tests
+* more documentation
+
+<em>0.0.2</em>
+* minor fixes
+
 <em>0.0.1</em>
 * first release
 

data/bin/gemma

@@ -0,0 +1,134 @@
+#!/usr/bin/env ruby
+#
+# = gemma
+#
+# Create new gem from template(s).
+# Options can be specified on the command line or interactively.
+#
+# == Usage
+#
+# gemma new [options]
+#
+# -h, --help::
+#   show this message
+#
+# -v, --version::
+#   print gemma version and exit
+#
+# --name=name::
+#   name of the gem to create; if unspecified, gemma assumes that you want to
+#   create the gem interactively, and prompts will be given for any other
+#   arguments not specified on the command line.
+#
+# --dir=name::
+#   directory to create the new gem in; default is the name of the gem; specify
+#   --dir=. to make the current directory the root of the gem.
+#
+# --module=name::
+#   name of module that contains the gem contents (e.g. MyNewGem for a gem
+#   called my_new_gem); by default, this is computed from the gem name.
+#
+# --template=path::
+#   path to template to use instead of default template(s); specify this
+#   argument multiple times to copy from several templates (in order). 
+#
+
+require 'getoptlong'
+require 'gemma'
+require 'highline'
+
+#
+# Process options.
+#
+
+getopt = GetoptLong.new(
+  ['--help',     '-h', GetoptLong::NO_ARGUMENT      ],
+  ['--version',  '-v', GetoptLong::NO_ARGUMENT      ],
+  ['--name',           GetoptLong::REQUIRED_ARGUMENT],
+  ['--dir',            GetoptLong::REQUIRED_ARGUMENT],
+  ['--module',         GetoptLong::REQUIRED_ARGUMENT],
+  ['--template',       GetoptLong::REQUIRED_ARGUMENT]
+)
+
+opts = {}
+opts['--template'] = []
+getopt.each do |opt, arg|
+  case opt
+  when '--help' then
+    Gemma::Utility.print_usage_from_file_comment __FILE__
+    exit
+  when '--version' then
+    puts "gemma-#{Gemma::VERSION}"
+    exit
+  when '--template' then
+    opts['--template'] << arg
+  else
+    opts[opt] = arg
+  end
+end
+
+# Remaining argument should be the command.
+command = ARGV.shift
+unless command && command == "new"
+  Gemma::Utility.print_usage_from_file_comment __FILE__
+  exit
+end
+
+#
+# Create from template; prompt for any missing info.
+#
+hl = HighLine.new
+gt = Gemma::GemFromTemplate.new
+
+interactive = !opts['--name'] || opts['--name'].empty?
+
+if interactive
+  puts 
+  puts "creating a new gem with gemma..."
+  puts 
+end
+
+unless interactive
+  gt.gem_name    = opts['--name']
+else
+  gt.gem_name    = hl.ask('gem name: ') {|q| q.validate = /^.+$/} # weak
+end
+
+if opts['--dir']
+  gt.dir_name    = opts['--dir']
+elsif interactive
+  gt.dir_name    =
+    hl.ask('create gem in directory: ') {|q| q.default = gt.dir_name}
+end
+
+if opts['--module']
+  gt.module_name = opts['--module']
+elsif interactive
+  gt.module_name =
+    hl.ask('wrap contents in module called: ') {|q| q.default = gt.module_name}
+end
+
+templates = opts['--template']
+if templates.empty?
+  if interactive
+    templates << 'base' << 'test_unit'
+    hl.choose do |menu|
+      menu.prompt = "type of gem: "
+      menu.shell = true
+      menu.choice('library (library scripts only)') do
+        # no extras
+      end
+      menu.choice('program (both library scripts and executable scripts)') do
+        templates << 'executable'
+      end
+    end
+  else
+    templates.push(*Gemma::GemFromTemplate::BUILTIN_TEMPLATES)
+  end
+  templates.map!{|name| File.join(Gemma::GemFromTemplate::TEMPLATE_ROOT,name)}
+end
+
+puts "creating gem in #{gt.destination_path}"
+gt.create_gem(templates)
+puts "gem created; to get started, see the following TODO tags:"
+Gemma::Utility.rgrep(/TODO/, gt.destination_path)

data/lib/gemma.rb

@@ -1,21 +1,16 @@
 require 'gemma/version'
+require 'gemma/utility'
 require 'gemma/options'
 require 'gemma/rake_tasks'
 
 # Load default Rakefile plugins:
 require 'gemma/rake_tasks/plugin'
-require 'gemma/rake_tasks/gem_tasks'
 require 'gemma/rake_tasks/rcov_tasks'
 require 'gemma/rake_tasks/rdoc_tasks'
+require 'gemma/rake_tasks/run_tasks'
 require 'gemma/rake_tasks/yard_tasks'
 require 'gemma/rake_tasks/test_unit_tasks'
 
-#require 'gemma/utility'
-
-# Load default Rakefile plugins:
-#require 'gemma/rakefile/rdoc'
-#require 'gemma/rakefile/yard'
-#require 'gemma/rakefile/test_unit'
-#require 'gemma/rakefile/rcov'
-#require 'gemma/rakefile/gem'
+require 'gemma/conventions'
+require 'gemma/gem_from_template'
 

data/lib/gemma/conventions.rb

@@ -0,0 +1,52 @@
+module Gemma
+  #
+  # A home for conventions, advice and best practices.
+  #
+  module Conventions
+    #
+    # References:
+    # http://stackoverflow.com/questions/221320/standard-file-naming-conventions-in-ruby
+    # http://containerdiv.wordpress.com/2009/05/24/ruby-gems-vs-rails-plugins/
+    #
+    # There is probably a required format (regex) for names, but I've never
+    # figured out what it is. It should be a valid file/directory name on
+    # Windows.
+    #
+    GOOD_GEM_NAME_TIPS = <<-STRING
+    Some tips for good gem names:
+      * use lower case
+      * separate words with _ (underscore)
+      * don't put 'ruby' in the name; this is implied, because it's a rubygem
+
+    It is also common to use a hyphen (-) to separate words.
+
+    If your gem name is my_new_gem, it can be installed with
+      sudo gem install my_new_gem
+    used in scripts with
+      require 'rubygems'
+      require 'my_new_gem'
+    and its contents should be contained in a module or class called MyNewGem.
+    STRING
+
+    #
+    # Check gem naming conventions; this is sufficient but not necessary for
+    # the gem name to be valid.
+    #
+    # @return [Boolean]
+    #
+    def self.good_gem_name? gem_name
+      gem_name =~ /^[a-z0-9]+[a-z0-9_\-]*$/
+    end
+
+    #
+    # Convert from underscore-lower-case form to camel-case form; hyphens are
+    # also converted to camel case.
+    #
+    # @return [String]
+    #
+    def self.gem_name_to_module_name gem_name
+      gem_name.gsub(/(?:^|_|-)([a-z0-9])/) { $1.upcase }
+    end
+  end
+end
+

data/lib/gemma/gem_from_template.rb

@@ -0,0 +1,134 @@
+require 'erb'
+require 'fileutils'
+require 'yaml'
+
+module Gemma
+  #
+  # Configurable gem skeleton from a template.
+  #
+  class GemFromTemplate
+    #
+    # Location of built-in templates.
+    #
+    TEMPLATE_ROOT = File.join(File.dirname(__FILE__), '..', '..', 'template')
+
+    #
+    # Built-in template names (not full paths). Order may be significant if
+    # there are files that occur in multiple templates (files in earlier
+    # templates are overwritten by those in later templates, at present).
+    #
+    BUILTIN_TEMPLATES = %w(base executable test_unit)
+
+    def initialize
+      @gem_name = nil
+      @module_name = nil
+      @dir_name = nil
+    end
+
+    #
+    # The gem name to be used in the gemspec; it also gives defaults for the
+    # directory name and the gem's module name.
+    #
+    # @return [String]
+    #
+    attr_accessor :gem_name
+
+    #
+    # Gem name is consistent with naming conventions.
+    #
+    # @return [Boolean]
+    #
+    def good_gem_name?
+      Conventions.good_gem_name? self.gem_name
+    end
+
+    #
+    # Guess main module (or class) name from gem name (e.g. MyNewGem from
+    # my_new_gem). The gem contents should be contained in this module / class.
+    #
+    # @return [String]
+    #
+    def module_name
+      @module_name || Conventions.gem_name_to_module_name(self.gem_name)
+    end
+
+    #
+    # Override default module name; set to nil to get back to default.
+    #
+    attr_writer :module_name
+
+    #
+    # Name of the root directory of the gem to be created.
+    #
+    # @return [String]
+    #
+    def dir_name
+      @dir_name || @gem_name
+    end
+
+    #
+    # Override default directory name; set to nil to get back to default.
+    #
+    attr_writer :dir_name
+
+    #
+    # Full path of root of the gem to be created. 
+    #
+    def destination_path
+      File.expand_path(File.join('.',self.dir_name))
+    end
+
+    #
+    # Gem version requirement for the development dependency on gemma.
+    #
+    # @return [String]
+    #
+    def gemma_version_requirement 
+      "~> #{Gemma::VERSION.split(/\./).take(2).join('.')}"
+    end
+
+    #
+    # Copy given templates to +destination_path+ and run erb where needed.
+    #
+    def create_gem template_paths, destination_path=self.destination_path
+      raise "destination #{destination_path} exists" if File.exists?(
+        destination_path)
+
+      # Copy templates in.
+      FileUtils.mkdir_p destination_path
+      for path in template_paths
+        FileUtils.cp_r File.join(path,'.'), destination_path
+      end
+
+      Dir.chdir destination_path do
+        dirs = Dir["**/*"].select { |f| File.directory? f }.sort
+        dirs.grep(/gem_name/).each do |file|
+          FileUtils.mv file, file.gsub(/gem_name/, gem_name)
+        end
+
+        files = (Dir["**/*"] + Dir["**/.*"]).select { |f| File.file? f }.sort
+        FileUtils.chmod 0644, files
+        FileUtils.chmod 0755, files.select{|f| File.dirname(f) == 'bin'}
+        files.each do |file|
+          # Rename files with names that depend on the gem name.
+          if file =~ /gem_name/
+            new_file = file.sub(/gem_name/, gem_name)
+            FileUtils.mv file, new_file
+            file = new_file
+          end
+
+          # Run erb to customize each file.
+          if File.extname(file) == ".erb"
+            erb_file = File.read file
+            File.open file, "w" do |f|
+              erb = ERB.new(erb_file)
+              erb.filename = file
+              f.puts erb.result(binding)
+            end
+            FileUtils.mv file, file.sub(/\.erb$/, '')
+          end
+        end
+      end
+    end
+  end
+end