hen 0.2.7 → 0.3.2

data/ChangeLog

@@ -1,5 +1,42 @@
 = Revision history for hen
 
+== 0.3.2 [2011-02-11]
+
+* Fixed the (pseudo-)object eval stuff. So there's hope we finally have a
+  working release... *fingerscrossed*
+
+== 0.3.1 [2011-02-11]
+
+* Fixed the RubyForge release task name in the prerequisite list for the
+  <tt>:release</tt> task.
+
+== 0.3.0 [2011-02-11]
+
+* Implementations for <tt>doc:publish</tt> and <tt>:release</tt> are
+  now cumulative.
+* The configuration (through the user's <tt>.henrc</tt> files) is now
+  cumulative.
+* It's no longer required to have a <tt>.henrc</tt> file.
+* Changed default namespace in sample skeleton from class to module.
+* Ignoring untracked files when building the official documentation and
+  when building the Gem.
+  * Added new task <tt>doc:local</tt> for the previous +doc+ behaviour.
+* Renamed <tt>:gemspec</tt> -> <tt>gem:spec</tt>, <tt>gemspec:update</tt>
+  -> <tt>gem:spec:update</tt>.
+* New task <tt>gem:install</tt> to install the current Gem locally.
+* Added support for RDoc 2/3.
+* Recognize <tt>:legacy</tt> option in <tt>:spec</tt> options to force
+  RSpec 1 even when RSpec 2 is available. Same for RDoc 2 vs. 3.
+* Added support for easy GitHub homepage by setting <tt>:homepage</tt>
+  option to a symbol that identifies the GitHub user name.
+* Better defaults for <tt>hen create/config</tt>.
+* Hen::CLI#render makes a backup before overwriting an existing file.
+* The RubyGems (pseudo-)object can now execute arbitrary commands.
+* The +gemcutter+ helper has been deprecated; use +rubygems+ instead.
+* Some defaults are set in Hen files rather than relying on <tt>.henrc</tt>
+  file.
+* No longer messing with RubyGems/$LOAD_PATH.
+
 == 0.2.7 [2011-01-24]
 
 * RubyGems compatibility (Gem::CommandManager)

data/README

@@ -2,12 +2,57 @@
 
 == VERSION
 
-This documentation refers to hen version 0.2.7
+This documentation refers to hen version 0.3.2
 
 
 == DESCRIPTION
 
-TODO: well, the description... ;-)
+Hen is a Rake helper framework, similar to Hoe[http://seattlerb.rubyforge.org/hoe/]
+or Echoe[http://fauna.github.com/fauna/echoe/]. It provides you with a set of
+common Rake tasks by placing a little snippet like the following in your Rakefile:
+
+  require 'hen'
+  require 'your/lib/version'
+
+  Hen.lay! {{
+    :gem => {
+      :name    => 'gem_name',
+      :version => Your::Lib::VERSION,
+      :summary => 'Project summary',
+      :author  => 'Your Name',
+      :email   => 'you@e.mail'
+    }
+  }}
+
+=== Generate a global configuration file
+
+Hen will read configuration options from your global configuration file if
+it's present. You can generate a minimal <tt>.henrc</tt> with the +hen+ script:
+
+  hen config
+
+This will create a new <tt>.henrc</tt> file in your home directory.
+
+=== Create a new project
+
+For new projects, you can also use the +hen+ script to create an initial
+project directory for you that comes with default files and configuration:
+
+  hen create path/to/your/lib
+
+You can even provide a project template of your own:
+
+  hen create path/to/your/lib path/to/your/template
+
+In addition to that, +hen+ can setup your new project with Git support:
+
+  hen create path/to/your/lib -g
+
+See <tt>hen help</tt> for further information.
+
+=== Extending Hen
+
+You can even extend Hen with your own tasks. More on that later. (TODO)
 
 
 == LINKS

data/Rakefile

@@ -1,4 +1,4 @@
-$:.unshift('lib')
+$:.unshift(File.expand_path('../lib', __FILE__))
 
 require 'hen'
 
@@ -12,8 +12,9 @@ Hen.lay! {{
     :version      => Hen::VERSION,
     :summary      => "Hoe or Echoe? No, thanks! Just a Rake " <<
                      "helper that fits my own personal style.",
-    :files        => FileList['lib/**/*.rb', 'bin/*'].to_a,
-    :extra_files  => FileList['[A-Z]*', 'lib/hens/*.rake', 'example/**/*', 'example/.henrc'].to_a,
-    :dependencies => [['ruby-nuggets', '>= 0.6.6'], 'highline']
+    :author       => %q{Jens Wille},
+    :email        => %q{jens.wille@uni-koeln.de},
+    :extra_files  => FileList['lib/hens/*.rake'].to_a,
+    :dependencies => [['ruby-nuggets', '>= 0.6.9'], 'highline']
   }
 }}

data/bin/hen

@@ -5,7 +5,7 @@
 #                                                                             #
 # hen -- Just a Rake helper                                                   #
 #                                                                             #
-# Copyright (C) 2007-2009 University of Cologne,                              #
+# Copyright (C) 2007-2011 University of Cologne,                              #
 #                         Albertus-Magnus-Platz,                              #
 #                         50923 Cologne, Germany                              #
 #                                                                             #
@@ -30,15 +30,10 @@
 
 # TODO: Implement 'list' action -- List available hens with their tasks (?)
 
+require 'hen/cli'
 require 'fileutils'
-require 'rubygems'
 require 'nuggets/enumerable/minmax'
 
-$: << File.join(File.dirname(__FILE__), '..', 'lib')
-
-require 'hen'
-require 'hen/cli'
-
 include Hen::CLI
 
 ACTIONS = {
@@ -60,7 +55,7 @@ EOT
 
 abort USAGE if ARGV.empty?
 
-EXAMPLE = File.join(File.dirname(__FILE__), '..', 'example')
+EXAMPLE = File.expand_path('../../example', __FILE__)
 
 case action = ARGV.shift
   when 'help', '-h', '--help'
@@ -70,21 +65,21 @@ case action = ARGV.shift
 
     max = ACTIONS.keys.max(:length)
 
-    ACTIONS.sort.each { |act, desc|
-      desc = [*desc]
-      puts "  %-#{max}s - %s" % [act, desc.shift]
+    ACTIONS.sort.each { |action, description|
+      description = [*description]
+      puts "  %-#{max}s - %s" % [action, description.shift]
 
-      desc.each { |extra|
+      description.each { |extra|
         puts "  %#{max}s   + %s" % [' ', extra]
       }
     }
   when 'version', '--version'
     puts "hen v#{Hen::VERSION}"
   when 'config'
-    render(File.join(EXAMPLE, '.henrc'), henrc = Hen.henrc(true))
+    render(File.join(EXAMPLE, '_henrc'), henrc = Hen.default_henrc)
 
     puts
-    puts "Your .henrc has been created: #{henrc}. Now modify it to your needs."
+    puts "Your .henrc has been created: #{henrc}. Now adjust it to your needs."
   when 'create'
     path = File.expand_path(ARGV.shift)
     abort 'Path argument missing!' unless path
@@ -125,21 +120,21 @@ case action = ARGV.shift
     replace = {}
 
     begin
-      # We need the name here so ask for it already. Additionally, it's
-      # a good opportunity to make sure the user's .henrc is available.
-      progname = ask!("Program's name", true) { |q|
-        q.default = File.basename(path)
-      }
+      # We need the name here, so ask for it already.
+      progname = progname(File.basename(path))
 
       Dir.chdir(skel) {
         Dir['**/*'].each { |sample|
           target = File.join(path, sample.gsub(/__progname__/, progname))
+
+          next if target.sub!(%r{(\A|/)[._](git[^/]+)\z}, '\1.\2') && !git
+
           created << target
 
           if File.directory?(sample)
-            Dir.mkdir(target)
+            FileUtils.mkdir_p(target)
           else
-            replace[target] = render(sample, target).scan(/### .* ###/)
+            replace[target] = render(sample, target).scan(/### .+ ###/)
           end
         }
       }
@@ -148,15 +143,13 @@ case action = ARGV.shift
       created.clear
     ensure
       # In case of an exception or premature program exit: Clean up!
-      created.reverse.each { |p|
+      created.reverse.each { |item|
+        next unless File.exist?(item)
+
         begin
-          (File.directory?(p) ? Dir : File).unlink(p) if File.readable?(p)
+          (File.directory?(item) ? Dir : File).unlink(item)
         rescue Errno::ENOTEMPTY => err
-          if File.basename(p) == '.git'
-            FileUtils.rm_rf(p)
-          else
-            raise err
-          end
+          File.basename(item) == '.git' ? FileUtils.rm_rf(item) : raise(err)
         end
       }
     end

data/example/_henrc

@@ -0,0 +1,7 @@
+---
+
+:gem:
+  :author: <%= fullname %>
+  :email:  <%= emailaddress %>
+
+# vim: syntax=yaml

data/example/project/COPYING

@@ -1,4 +1,4 @@
-= License for <%= ask! "Program's name" %>
+= License for <%= progname %>
   
                       GNU GENERAL PUBLIC LICENSE
                          Version 3, 29 June 2007

data/example/project/ChangeLog

@@ -1,4 +1,4 @@
-= Revision history for <%= ask! "Program's name" %>
+= Revision history for <%= progname %>
 
 == 0.0.1 [<%= Time.now.strftime('%Y-%m-%d') %>]
 

data/example/project/README

@@ -1,8 +1,8 @@
-= <%= ask! "Program's name" %> - <%= ask "Program's description summary" %>
+= <%= progname %> - <%= progdesc %>
 
 == VERSION
 
-This documentation refers to <%= ask! "Program's name" %> version 0.0.1
+This documentation refers to <%= progname %> version 0.0.1
 
 
 == DESCRIPTION
@@ -18,21 +18,21 @@ LABEL:: <### PLACE YOUR LINK(S) HERE ###>
 
 == AUTHORS
 
-* <%= ask "Full name", 'gem/author' %> <mailto:<%= ask "E-mail address", 'gem/email' %>>
+* <%= fullname %> <mailto:<%= emailaddress %>>
 
 
 == LICENSE AND COPYRIGHT
 
 ### PLACE YOUR COPYRIGHT NOTICE HERE ###
 
-<%= ask! "Program's name" %> is free software: you can redistribute it and/or modify it under
+<%= progname %> is free software: you can redistribute it and/or modify it under
 the terms of the GNU General Public License as published by the Free Software
 Foundation, either version 3 of the License, or (at your option) any later
 version.
 
-<%= ask! "Program's name" %> is distributed in the hope that it will be useful, but WITHOUT
+<%= progname %> is distributed in the hope that it will be useful, but WITHOUT
 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
 
 You should have received a copy of the GNU General Public License along with
-<%= ask! "Program's name" %>. If not, see <http://www.gnu.org/licenses/>.
+<%= progname %>. If not, see <http://www.gnu.org/licenses/>.

data/example/project/Rakefile

@@ -1,20 +1,18 @@
-require %q{lib/<%= ask! "Program's name" %>/version}
+require File.expand_path(%q{../lib/<%= progname %>/version}, __FILE__)
 
 begin
   require 'hen'
 
   Hen.lay! {{
     :gem => {
-      :name         => %q{<%= ask! "Program's name" %>},
-      :version      => <%= ask! "Module's/Class' name" %>::VERSION,
-      :summary      => %q{<%= ask "Program's description summary" %>},
-      :files        => FileList['lib/**/*.rb'].to_a,
-      :extra_files  => FileList['[A-Z]*'].to_a,
+      :name         => %q{<%= progname %>},
+      :version      => <%= classname %>::VERSION,
+      :summary      => %q{<%= progdesc %>},
+      :author       => %q{<%= fullname %>},
+      :email        => %q{<%= emailaddress %>},
       :dependencies => %w[]
     }
   }}
-rescue LoadError
-  warn "Please install the `hen' gem."
+rescue LoadError => err
+  warn "Please install the `hen' gem. (#{err})"
 end
-
-### Place your custom Rake tasks here.

data/example/project/_gitignore

@@ -0,0 +1,6 @@
+doc
+doc.local
+pkg
+.gh-pages
+*.o
+*.so

data/example/project/lib/__progname__.rb

@@ -1,2 +1,2 @@
-class <%= ask! "Module's/Class' name" %>
+module <%= classname %>
 end

data/example/project/lib/__progname__/version.rb

@@ -1,4 +1,4 @@
-class <%= ask! "Module's/Class' name" %>
+module <%= classname %>
 
   module Version
 

data/lib/hen.rb

@@ -3,7 +3,7 @@
 #                                                                             #
 # hen -- Just a Rake helper                                                   #
 #                                                                             #
-# Copyright (C) 2007-2008 University of Cologne,                              #
+# Copyright (C) 2007-2011 University of Cologne,                              #
 #                         Albertus-Magnus-Platz,                              #
 #                         50923 Cologne, Germany                              #
 #                                                                             #
@@ -26,42 +26,52 @@
 ###############################################################################
 #++
 
-require 'yaml'
-require 'forwardable'
-
-require 'rubygems'
 require 'rake'
+require 'yaml'
 require 'nuggets/env/user_home'
+require 'nuggets/hash/deep_merge'
 require 'nuggets/proc/bind'
 
 require 'hen/dsl'
 require 'hen/version'
 
+# The class handling the program logic. This is what you use in your Rakefile.
+# See the README for more information.
+
 class Hen
 
-  # The directories which contain the hen files
-  HENDIRS = [File.join(File.dirname(__FILE__), 'hens')] +
-            (ENV['HENPATH'] || '').split(File::PATH_SEPARATOR)
+  # The directories to search for hen files. Set
+  # environment variable +HENPATH+ to add more.
+  HENDIRS = [File.expand_path('../hens', __FILE__)]
 
-  # All hens found, mapped by their name
-  HENS = Dir[*HENDIRS.map { |d| "#{d}/*.rake" }].uniq.inject(
-    Hash.new { |h, k| h[k] = [] }
-  ) { |hash, hen|
-    hash[File.basename(hen, '.rake')] << hen; hash
-  }
+  ENV['HENPATH'].split(File::PATH_SEPARATOR).each { |dir|
+    HENDIRS << File.expand_path(dir)
+  } if ENV['HENPATH']
 
-  # Directories to search for .henrc
-  RCDIRS = ['.', ENV.user_home]
+  HENDIRS.uniq!
 
-  # A container for all loaded hens
-  @hens = {}
+  # All hens found, mapped by their name.
+  HENS = Hash.new { |h, k| h[k] = [] }
 
-  # The verbosity concerning errors and warnings
-  @verbose = true
+  HENDIRS.each { |dir| Dir["#{dir}/*.rake"].each { |hen|
+    HENS[File.basename(hen, '.rake')] << hen
+  } }
+
+  # Directories to search for <tt>.henrc</tt> files.
+  RCDIRS = [ENV.user_home, '.']
+
+  # The name of the <tt>.henrc</tt> file.
+  HENRC_NAME = '.henrc'
+
+  @hens, @verbose = {}, $VERBOSE
 
   class << self
 
-    attr_reader :hens, :verbose
+    # The global container for all loaded hens.
+    attr_reader :hens
+
+    # The verbosity concerning errors and warnings.
+    attr_reader :verbose
 
     # call-seq:
     #   lay!
@@ -77,24 +87,18 @@ class Hen
 
       @verbose = options[:verbose] if options.has_key?(:verbose)
 
-      if block_given?
-        yield.each { |key, value| (config[key] ||= {}).update(value) }
-      end
+      yield.each { |key, value| config[key].update(value) } if block_given?
 
       # Handle include/exclude requirements
       excl = options[:exclude]
       args, default = args.empty? ? [excl ? [*excl] : [], true] : [args, false]
 
       inclexcl = Hash.new(default)
-      args.each { |arg|
-        inclexcl[arg.to_s] = !default
-      }
+      args.each { |arg| inclexcl[arg.to_s] = !default }
 
       # Load all available hens (as far as the
       # include/exclude conditions are met)
-      load_hens { |hen|
-        inclexcl[hen]
-      }
+      load_hens { |hen| inclexcl[hen] }
 
       # Execute each hen definition
       hens.each { |name, hen|
@@ -127,62 +131,81 @@ class Hen
     # call-seq:
     #   Hen[hen] => aHen
     #
-    # Get hen by name.
+    # Get +hen+ by name.
     def [](hen)
       @hens[hen]
     end
 
     # call-seq:
-    #   henrc => aString
+    #   henrc => anArray
+    #
+    # The paths to the user's <tt>.henrc</tt> files.
+    def henrc
+      @henrc ||= find_henrc
+    end
+
+    # call-seq:
+    #   default_henrc => aString
     #
-    # The path to the user's .henrc
-    def henrc(location_only = false)
-      @henrc ||= find_henrc(location_only)
+    # The path to a suitable default <tt>.henrc</tt> location.
+    def default_henrc
+      find_henrc(false).first
     end
 
     # call-seq:
     #   config => aHash
-    #   config(key) => aValue
+    #   config(key) => anObject
     #
-    # The configuration resulting from the user's .henrc. Takes optional
-    # +key+ argument as "path" into the config hash, returning the thusly
-    # retrieved value.
+    # The configuration resulting from the user's <tt>.henrc</tt>. Takes
+    # optional +key+ argument as "path" into the config hash, returning
+    # the thusly retrieved value.
     #
     # Example:
     #   config('a/b/c')  #=> @config[:a][:b][:c]
     def config(key = nil)
-      @config ||= YAML.load_file(henrc)
+      @config ||= load_config
       return @config unless key
 
-      key.split('/').inject(@config) { |value, k|
-        value.fetch(k.to_sym)
-      }
+      key.split('/').inject(@config) { |value, k| value.fetch(k.to_sym) }
     rescue IndexError, NoMethodError
     end
 
     private
 
     # call-seq:
-    #   find_henrc(location_only = false) => aString
+    #   load_config => aHash
     #
-    # Search for a readable .henrc, or, if +location_only+ is true, just return
-    # a suitable default location.
-    def find_henrc(location_only = false)
-      return ENV['HENRC'] || File.join(RCDIRS.last, '.henrc') if location_only
-
-      if    henrc = ENV['HENRC']
-        abort "The specified .henrc file could not be found: #{henrc}" \
-          unless File.readable?(henrc)
-      elsif henrc = RCDIRS.find { |dir|
-        h = File.join(dir, '.henrc')
-        break h if File.readable?(h)
+    # Load the configuration from the user's <tt>.henrc</tt> files.
+    def load_config
+      hash = Hash.new { |h, k| h[k] = {} }
+
+      henrc.each { |path|
+        yaml = YAML.load_file(path)
+        hash.deep_update(yaml) if yaml.is_a?(Hash)
       }
-      else
-        abort "No .henrc file could be found! Please " <<
-              "create one first by running 'hen config'."
+
+      hash
+    end
+
+    # call-seq:
+    #   find_henrc(must_exist = true) => anArray
+    #
+    # Returns all readable <tt>.henrc</tt> files found in the (optional)
+    # environment variable +HENRC+ and in each directory named in RCDIRS.
+    # If +must_exist+ is false, no readability checks will be performed.
+    def find_henrc(must_exist = true)
+      found = []
+
+      if env_henrc = ENV['HENRC']
+        found << env_henrc if !must_exist || File.readable?(env_henrc)
       end
 
-      henrc
+      RCDIRS.each { |dir|
+        dir_henrc = File.join(dir, HENRC_NAME)
+        found << dir_henrc if !must_exist || File.readable?(dir_henrc)
+      }
+
+      found
     end
 
     # call-seq:
@@ -198,20 +221,20 @@ class Hen
 
       (hens.empty? ? HENS.keys : hens).each { |hen|
         hen = hen.to_s
-        next unless block[hen]
-
-        HENS[hen].each { |h| load h }
+        HENS[hen].each { |h| load h } if block[hen]
       }
     end
 
   end
 
-  extend Forwardable
+  # The hen's name.
+  attr_reader :name
 
-  # Forward to the class
-  def_delegators self, :verbose
+  # The list of the hen's dependencies.
+  attr_reader :dependencies
 
-  attr_reader :name, :dependencies, :block
+  # The hen's definition block.
+  attr_reader :block
 
   # call-seq:
   #   new(args, overwrite = false) { ... }
@@ -229,6 +252,8 @@ class Hen
       return
     end
 
+    @laid = false
+
     self.class.add_hen(self, overwrite)
   end
 
@@ -240,17 +265,24 @@ class Hen
     return if laid?
 
     # Call dependencies first
-    dependencies.each { |hen|
-      self.class[hen].lay!
-    }
+    dependencies.each { |hen| self.class[hen].lay!  }
 
     block.bind(DSL).call
   rescue => err
-    warn "#{name}: #{err} (#{err.class})" if verbose
+    warn "#{name}: #{err} (#{err.class})" if $DEBUG || verbose
+    warn err.backtrace.join("\n  ") if $DEBUG
   end
 
   private
 
+  # call-seq:
+  #   verbose => true or false
+  #
+  # Delegates to Hen.verbose.
+  def verbose
+    self.class.verbose
+  end
+
   # call-seq:
   #   resolve_args(args) => [name, dependencies]
   #
@@ -260,17 +292,18 @@ class Hen
   def resolve_args(args)
     name, dependencies = case args
       when Hash
-        raise ArgumentError, "Too many hen names: #{args.keys.join(' ')}" \
-          if args.size > 1
-        raise ArgumentError, 'No hen name given' \
-          if args.size < 1
+        if args.empty?
+          raise ArgumentError, 'No hen name given'
+        elsif args.size > 1
+          raise ArgumentError, "Too many hen names: #{args.keys.join(' ')}"
+        end
 
         [args.keys.first, [*args.values.first]]
       else
         [args, []]
     end
 
-    [name.to_sym, dependencies.map { |d| d.to_sym }]
+    [name.to_sym, dependencies.map { |dependency| dependency.to_sym }]
   end
 
   # call-seq:
@@ -289,7 +322,7 @@ end
 # call-seq:
 #   Hen(args) { ... }
 #
-# Just forwards to Hen.new.
+# Delegates to Hen.new.
 def Hen(args, &block)
   Hen.new(args, &block)
 end
@@ -297,7 +330,8 @@ end
 # call-seq:
 #   Hen!(args) { ... }
 #
-# Same as above, but overwrites any existing hen with the same name.
+# Delegates to Hen.new, but overwrites
+# any existing hen with the same name.
 def Hen!(args, &block)
   Hen.new(args, true, &block)
 end