bones 1.1.2 → 1.2.0

data/History.txt

@@ -1,25 +1,31 @@
+== 1.2.0 / 2007-12-31
+
+* 1 major enhancement
+  - Users can define their own skeletons to use (bones --freeze)
+* 1 minor enhancement
+  - Show a list of the files a user needs to change after project creation
+
 == 1.1.2 / 2007-12-31
 
 * 2 minor enhancements
-  * The pkg and doc directories are now excluded from the manifest
-  * Added method to hide tasks from the rake task listing
-
-* 1 bugfixes
-  * Fixed typo in an abort message (thanks Bill Kleb)
+  - The pkg and doc directories are now excluded from the manifest
+  - Added method to hide tasks from the rake task listing
+* 1 bugfix
+  - Fixed typo in an abort message (thanks Bill Kleb)
 
 == 1.1.1 / 2007-12-29
 
 * 1 bugfix
-  * Fixed the bad interaction with RSpec gem
+  - Fixed the bad interaction with RSpec gem
 
 == 1.1.0 / 2007-12-29
 
 * 3 minor enhancements
-  * Output message when files are created or updated
-  * Directory cleanup if project creation fails
-  * Pulled the rails source annotation extractor into Mr Bones
+  - Output message when files are created or updated
+  - Directory cleanup if project creation fails
+  - Pulled the rails source annotation extractor into Mr Bones
 
 == 1.0.0 / 2007-12-28
 
 * 1 major enhancement
-  * Birthday!
+  - Birthday!

data/README.txt

@@ -14,31 +14,33 @@ gem dependency required).
 
 Mr Bones provides the following rake tasks:
 
-  clobber              # Remove all build products
-  doc                  # Alias to doc:rdoc
-  doc:rdoc             # Build the rdoc HTML Files
-  doc:release          # Publish RDoc to RubyForge
-  doc:rerdoc           # Force a rebuild of the RDOC files
-  doc:ri               # Generate ri locally for testing
-  gem                  # Alias to gem:package
-  gem:debug            # Show information about the gem
-  gem:gem              # Build the gem file
-  gem:install          # Install the gem
-  gem:package          # Build all the packages
-  gem:release          # Package and upload to RubyForge
-  gem:repackage        # Force a rebuild of the package files
-  gem:uninstall        # Uninstall the gem
-  manifest:check       # Verify the manifest
-  manifest:create      # Create a new manifest
-  notes                # Enumerate all annotations
-  notes:fixme          # Enumerate all FIXME annotations
-  notes:optimize       # Enumerate all OPTIMIZE annotations
-  notes:todo           # Enumerate all TODO annotations
-  spec:rcov            # Run all specs with RCov
-  spec:run             # Run all specs with basic output
-  spec:specdoc         # Run all specs with text output
-  test:rcov            # Run rcov on the unit tests
-  test:run             # Run tests for run
+  clobber          # Remove all build products
+  doc              # Alias to doc:rdoc
+  doc:rdoc         # Build the rdoc HTML Files
+  doc:release      # Publish RDoc to RubyForge
+  doc:rerdoc       # Force a rebuild of the RDOC files
+  doc:ri           # Generate ri locally for testing
+  gem              # Alias to gem:package
+  gem:debug        # Show information about the gem
+  gem:gem          # Build the gem file bones-1.2.0.gem
+  gem:install      # Install the gem
+  gem:package      # Build all the packages
+  gem:release      # Package and upload to RubyForge
+  gem:repackage    # Force a rebuild of the package files
+  gem:uninstall    # Uninstall the gem
+  manifest:check   # Verify the manifest
+  manifest:create  # Create a new manifest
+  notes            # Enumerate all annotations
+  notes:fixme      # Enumerate all FIXME annotations
+  notes:optimize   # Enumerate all OPTIMIZE annotations
+  notes:todo       # Enumerate all TODO annotations
+  spec             # Alias to spec:run
+  spec:rcov        # Run all specs with RCov
+  spec:run         # Run all specs with basic output
+  spec:specdoc     # Run all specs with text output
+  test             # Alias to test:run
+  test:rcov        # Run rcov on the unit tests
+  test:run         # Run tests for run
 
 The rake tasks in the Mr Bones framework can be found in the "tasks"
 directory. Add your own tasks there when you need more functionality.
@@ -131,6 +133,74 @@ most current version number for the installed gem is used.
   depend_on 'logging'
   depend_on 'rake', '0.7.3'
 
+=== Freezing a Skeleton
+
+Freezing allows you to define your own project skeleton to instantiate with Mr
+Bones when you create a new project. The default Mr Bones project skeleton is
+copied to the ".mrbones" directory in your home directory. From there, the
+skeleton can be modified however you like (add new files and tasks, add new
+directories, etc).
+
+  bones --freeze
+
+Typical uses of this feature would be to fill in user specific data like the
+author, e-mail address, etc. You can also add more default code to the skeleton
+project or your own ".rake" task files.
+
+==== Updating a Frozen Skeleton
+
+Just like a regular project, a frozen skeleton can be updated if a newer
+version of Mr Bones comes out with better features. Updating a frozen skeleton
+will only modify the tasks. All other files in the skeleton remain untouched.
+
+  bones --freeze
+
+The freeze command is used to update the skeleton tasks to the latest Mr Bones
+tasks. A copy of the current tasks are made in an "archive" directory in the
+".mrbones" directory. To revert back to the archive version, you will need to
+manually rename "archive" to "data" in the ".mrbones" directory.
+
+==== Unfreezing a Skeleton
+
+Unfreezing a skeleton will remove your customized project skeleton from the
+".mrbones" directory. The default Mr Bones project skeleton will be used
+instead. A copy of your custom skeleton is made in the "archive" directory of
+the ".mrbones" directory before it is removed.
+
+  bones --unfreeze
+
+==== Custom Modifications
+
+Mr Bones will perform a limited set of substitutions on the files in the
+skeleton when it generates a new project. ERB is the to insert the project name
+and the derived class name into any template files. The file must end in an
+".erb" suffix for ERB substitutions to take place. The ".erb" suffix is
+stripped from the file during project generation. Therefore, your ERB files
+should have two suffixes -- the ".erb" suffix that will be stripped, and the
+suffix you want the resulting project file to have. 
+
+Only two values can be substituted into files using ERB -- the project name and
+the derived class name.
+
+  <%= name %>
+  <%= classname %>
+
+The project +name+ is passed in from the command line and used "as is" (with
+the exception that spaces are converted to underscores). The +classname+ is
+generated by camel casing the project name where the underscores occur.
+
+  get fuzzy  =>  GetFuzzy
+  foo_bar    =>  FooBar
+
+Finally, file names can be modified by substituting in the project name. If a
+file name contains the string "NAME" it is replaced with the project name. If
+our project is call "get fuzzy" then the following transformations will take
+place.
+
+  NAME.rb       =>  get_fuzzy.rb
+  test_NAME.rb  =>  test_get_fuzzy.rb
+  NAME_spec.rb  =>  get_fuzzy_spec.rb
+
 == ACKNOWLEDGEMENTS:
 
 Ryan Davis and Eric Hodel and their Hoe gem (from which much of the Mr Bones

data/Rakefile

@@ -18,8 +18,8 @@ PROJ.rubyforge_name = 'codeforpeople'
 PROJ.rdoc_remote_dir = 'bones'
 PROJ.version = Bones::VERSION
 
-PROJ.exclude << '^doc'
 PROJ.rdoc_exclude << '^data'
+PROJ.annotation_exclude = %w(README\.txt ^data\/)
 
 PROJ.spec_opts << '--color'
 

data/data/README.txt.erb

@@ -26,7 +26,7 @@ FIXME (describe your package)
 
 (The MIT License)
 
-Copyright (c) 2007 FIXME (different license?)
+Copyright (c) 2008 FIXME (different license?)
 
 Permission is hereby granted, free of charge, to any person obtaining
 a copy of this software and associated documentation files (the

data/data/tasks/annotations.rake

@@ -4,23 +4,24 @@ if HAVE_BONES
 
 desc "Enumerate all annotations"
 task :notes do
-  Bones::AnnotationExtractor.enumerate "OPTIMIZE|FIXME|TODO", :tag => true
+  Bones::AnnotationExtractor.enumerate(
+      PROJ, "OPTIMIZE|FIXME|TODO", :tag => true)
 end
 
 namespace :notes do
   desc "Enumerate all OPTIMIZE annotations"
   task :optimize do
-    Bones::AnnotationExtractor.enumerate "OPTIMIZE"
+    Bones::AnnotationExtractor.enumerate(PROJ, "OPTIMIZE")
   end
 
   desc "Enumerate all FIXME annotations"
   task :fixme do
-    Bones::AnnotationExtractor.enumerate "FIXME"
+    Bones::AnnotationExtractor.enumerate(PROJ, "FIXME")
   end
 
   desc "Enumerate all TODO annotations"
   task :todo do
-    Bones::AnnotationExtractor.enumerate "TODO"
+    Bones::AnnotationExtractor.enumerate(PROJ, "TODO")
   end
 end
 

data/data/tasks/setup.rb

@@ -56,6 +56,10 @@ PROJ.dependencies = []
 PROJ.need_tar = true
 PROJ.need_zip = false
 
+# File Annotations
+PROJ.annotation_exclude = []
+PROJ.annotation_extensions = %w(.txt .rb .erb) << ''
+
 # Load the other rake files in the tasks folder
 Dir.glob('tasks/*.rake').sort.each {|fn| import fn}
 

data/lib/bones.rb

@@ -1,11 +1,11 @@
-# $Id: bones.rb 428 2007-12-31 17:55:51Z tim_pease $
+# $Id: bones.rb 432 2007-12-31 23:41:04Z tim_pease $
 
 module Bones
 
   # :stopdoc:
-  VERSION = '1.1.2'
+  VERSION = '1.2.0'
   PATH = File.expand_path(File.join(File.dirname(__FILE__), '..'))
-  WIN32 = %r/win32/ =~ RUBY_PLATFORM unless defined? WIN32
+  WIN32 = %r/win32/ =~ RUBY_PLATFORM
   DEV_NULL = WIN32 ? 'NUL:' : '/dev/null'
   # :startdoc:
 

data/lib/bones/annotation_extractor.rb

@@ -1,50 +1,68 @@
-# $Id: annotation_extractor.rb 423 2007-12-29 18:32:34Z tim_pease $
+# $Id: annotation_extractor.rb 431 2007-12-31 21:24:37Z tim_pease $
 
 module Bones
+
+# A helper class used to find and display any annotations in a collection of
+# project files.
+#
 class AnnotationExtractor
 
   class Annotation < Struct.new(:line, :tag, :text)
-    def to_s(options={})
+    # Returns a string representation of the annotation. If the
+    # <tt>:tag</tt> parameter is given as +true+, then the annotation tag
+    # will be included in the string.
+    #
+    def to_s( opts = {} )
       s = "[%3d] " % line
-      s << "[#{tag}] " if options[:tag]
+      s << "[#{tag}] " if opts[:tag]
       s << text
     end
   end
 
-  def self.enumerate(tag, options={})
-    extractor = new(tag)
-    extractor.display(extractor.find, options)
+  # Enumerate all the annoations for the given _project_ and _tag_. This
+  # will search for all athe annotations and display them on standard
+  # output.
+  #
+  def self.enumerate( project, tag, opts = {} )
+    extractor = new(project, tag)
+    extractor.display(extractor.find, opts)
   end
 
-  attr_reader :tag
+  attr_reader :tag, :project
 
-  def initialize(tag)
+  # Creates a new annotation extractor configured to use the _project_ open
+  # strcut and to search for the given _tag_ (which can be more than one tag
+  # via a regular expression 'or' operation -- i.e. THIS|THAT|OTHER)
+  #
+  def initialize( project, tag )
+    @project = project
     @tag = tag
   end
 
-  def find(dirs=%w(app lib test))
-    dirs.inject({}) { |h, dir| h.update(find_in(dir)) }
-  end
-
-  def find_in(dir)
+  # Iterate over all the files in the project manifest and extract
+  # annotations from the those files. Returns the results as a hash for
+  # display.
+  #
+  def find
     results = {}
+    rgxp = %r/(#{tag}):?\s*(.*?)(?:\s*(?:-?%>|\*+\/))?$/o
+    extensions = project.annotation_extensions.dup
+    exclude = if project.annotation_exclude.empty? then nil
+              else Regexp.new(project.annotation_exclude.join('|')) end
 
-    Dir.glob("#{dir}/*") do |item|
-      next if File.basename(item)[0] == ?.
-
-      if File.directory?(item)
-        results.update(find_in(item))
-      elsif item =~ /\.(builder|(r(?:b|xml|js)))$/
-        results.update(extract_annotations_from(item, /#\s*(#{tag}):?\s*(.*)$/))
-      elsif item =~ /\.(rhtml|erb)$/
-        results.update(extract_annotations_from(item, /<%\s*#\s*(#{tag}):?\s*(.*?)\s*%>/))
-      end
+    project.files.each do |fn|
+      next if exclude && exclude =~ fn
+      next unless extensions.include? File.extname(fn)
+      results.update(extract_annotations_from(fn, rgxp))
     end
 
     results
   end
 
-  def extract_annotations_from(file, pattern)
+  # Extract any annotations from the given _file_ using the regular
+  # expression _pattern_ provided.
+  #
+  def extract_annotations_from( file, pattern )
     lineno = 0
     result = File.readlines(file).inject([]) do |list, line|
       lineno += 1
@@ -54,11 +72,15 @@ class AnnotationExtractor
     result.empty? ? {} : { file => result }
   end
 
-  def display(results, options={})
+  # Print the results of the annotation extraction to the screen. If the
+  # <tt>:tags</tt> option is set to +true+, then the annotation tag will be
+  # displayed.
+  #
+  def display( results, opts = {} )
     results.keys.sort.each do |file|
       puts "#{file}:"
       results[file].each do |note|
-        puts "  * #{note.to_s(options)}"
+        puts "  * #{note.to_s(opts)}"
       end
       puts
     end

data/lib/bones/main.rb

@@ -1,4 +1,4 @@
-# $Id: main.rb 428 2007-12-31 17:55:51Z tim_pease $
+# $Id: main.rb 433 2008-01-01 04:32:48Z tim_pease $
 
 require 'fileutils'
 require 'optparse'
@@ -25,7 +25,8 @@ class Main
   # the +create+ and +update+ methods.
   #
   def parse( args )
-    self.data = File.join(::Bones::PATH, 'data')
+    self.data = File.join(mrbones_dir, 'data')
+    self.data = File.join(::Bones::PATH, 'data') unless test(?d, data)
     self.update = false
     self.verbose = false
 
@@ -38,6 +39,17 @@ class Main
     opts.on('-v', '--verbose',
             'enable verbose output') {self.verbose = true}
 
+    opts.separator ''
+    opts.on('--freeze', 'freeze the project skeleton') {freeze; exit}
+    opts.on('--unfreeze', 'use the standard project skeleton') {unfreeze; exit}
+    opts.on('-i', '--info',
+            'report on the project skeleton being used') do
+      STDOUT.puts "the project skeleton will be copied from"
+      STDOUT.write "    "
+      STDOUT.puts data
+      exit
+    end
+
     opts.separator ''
     opts.separator 'common options:'
 
@@ -49,7 +61,7 @@ class Main
 
     # parse the command line arguments
     opts.parse! args
-    self.name = args.shift
+    self.name = args.join('_')
 
     if name.nil?
       puts opts
@@ -65,7 +77,7 @@ class Main
     @update
   end
 
-  # Returns the project name but converted to be useable as a Ruby class
+  # Returns the project name but converted to be usable as a Ruby class
   # name.
   #
   def classname
@@ -75,14 +87,6 @@ class Main
   # Create a new project from the bones/data project template.
   #
   def create
-    # * copy files from either
-    #   1) the user's '.bones/data' directory or
-    #   2) the Bones 'data' directory
-    #
-    # TODO - figure out if this really is the best way of doing this
-    #        should I just use either the .bones data or the gem data, not
-    #        both
-
     # see if the directory already exists
     abort "'#{name}' already exists" if test ?e, name
 
@@ -93,6 +97,8 @@ class Main
       begin
         FileUtils.cd name
         system "rake manifest:create 2>&1 > #{::Bones::DEV_NULL}"
+        STDOUT.puts "created '#{name}'\nnow you need to fix these files"
+        system "rake notes"
       ensure
         FileUtils.cd pwd
       end
@@ -100,8 +106,6 @@ class Main
       FileUtils.rm_rf name
       abort "could not create '#{name}'"
     end
-
-    STDOUT.puts "created '#{name}'"
   end
   
   # Archive any existing tasks in the project's tasks folder, and then
@@ -123,19 +127,87 @@ class Main
     end
 
     files_to_copy.each do |fn|
-      next unless 'tasks' == File.basename(File.dirname(fn))
+      next unless %r/^tasks\// =~ fn
       cp fn
     end
 
     STDOUT.puts "updated tasks for '#{name}'"
   end
 
+  # Freeze the project skeleton to the current Mr Bones gem. If the project
+  # skeleton has already been frozen, then it will be archived before being
+  # overwritten by the current Mr Bones skeleton.
+  #
+  # If the project skeleton is already frozen, only the tasks from the Mr
+  # Bones skeleton will be copied to the user's data directory.
+  #
+  def freeze
+    bones_data_dir = File.join(::Bones::PATH, 'data')
+    data_dir = File.join(mrbones_dir, 'data')
+    archive_dir = File.join(mrbones_dir, 'archive')
+    tasks_only = false
+
+    if test(?d, data_dir)
+      STDOUT.puts "archiving #{data_dir}" if verbose
+      FileUtils.rm_rf(archive_dir)
+      FileUtils.mkdir(archive_dir)
+      FileUtils.cp_r(File.join(data_dir, '.'), archive_dir)
+      tasks_only = true
+    else
+      FileUtils.mkdir_p(data_dir)
+    end
+
+    files_to_copy.each do |file|
+      next if tasks_only && !(%r/^tasks\// =~ file)
+
+      src = File.join(bones_data_dir, file)
+      dst = File.join(data_dir, file)
+
+      STDOUT.puts "freezing #{dst}" if verbose
+      FileUtils.mkdir_p(File.dirname(dst))
+      FileUtils.cp(src, dst)
+    end
+
+    File.open(frozen_version_file, 'w') {|fd| fd.puts ::Bones::VERSION}
+
+    if tasks_only
+      STDOUT.puts "project skeleton tasks have been updated " <<
+                  "from Mr Bones #{::Bones::VERSION}"
+    else
+      STDOUT.puts "project skeleton has been frozen " <<
+                  "to Mr Bones #{::Bones::VERSION}"
+    end
+  end
+
+  # Unfreeze the project skeleton. The default Mr Bones skeleton will be
+  # used insetad. This method will archive the current frozen skeleton if
+  # one exists.
+  #
+  def unfreeze
+    data_dir = File.join(mrbones_dir, 'data')
+    archive_dir = File.join(mrbones_dir, 'archive')
+
+    if test(?d, data_dir)
+      STDOUT.puts "archiving #{data_dir}" if verbose
+      FileUtils.rm_rf(archive_dir)
+      FileUtils.mkdir(archive_dir)
+      FileUtils.cp_r(File.join(data_dir, '.'), archive_dir)
+      FileUtils.rm_rf(data_dir)
+
+      STDOUT.puts "project skeleton has been unfrozen"
+      STDOUT.puts "(default Mr Bones #{::Bones::VERSION} sekeleton will be used)"
+    else
+      STDOUT.puts "project skeleton is not frozen (no action taken)"
+    end
+    FileUtils.rm_f frozen_version_file
+  end
+
 
   private
 
   # Copy a file from the Bones prototype project location to the user
   # specified project location. A message will be displayed to the screen
-  # indicating tha the file is being created.
+  # indicating that the file is being created.
   #
   def cp( file )
     dir = File.dirname(file)
@@ -181,6 +253,22 @@ class Main
     ary
   end
 
+  # Returns the .bones resource directory in the user's home directory.
+  #
+  def mrbones_dir
+    return @mrbones_dir if defined? @mrbones_dir
+
+    path = (::Bones::WIN32 ? ENV['HOMEPATH'].tr("\\", "/") : ENV['HOME'])
+    path = File.join(path, '.mrbones')
+    @mrbones_dir = File.expand_path(path)
+  end
+
+  # File containing the Mr Bones version from which the skeleton was frozen.
+  #
+  def frozen_version_file
+    File.join(mrbones_dir, 'version.txt')
+  end
+
 end  # class Main
 end  # module Bones
 

data/tasks/annotations.rake

@@ -1,26 +1,27 @@
-# $Id: annotations.rake 423 2007-12-29 18:32:34Z tim_pease $
+# $Id: annotations.rake 431 2007-12-31 21:24:37Z tim_pease $
 
 if HAVE_BONES
 
 desc "Enumerate all annotations"
 task :notes do
-  Bones::AnnotationExtractor.enumerate "OPTIMIZE|FIXME|TODO", :tag => true
+  Bones::AnnotationExtractor.enumerate(
+      PROJ, "OPTIMIZE|FIXME|TODO", :tag => true)
 end
 
 namespace :notes do
   desc "Enumerate all OPTIMIZE annotations"
   task :optimize do
-    Bones::AnnotationExtractor.enumerate "OPTIMIZE"
+    Bones::AnnotationExtractor.enumerate(PROJ, "OPTIMIZE")
   end
 
   desc "Enumerate all FIXME annotations"
   task :fixme do
-    Bones::AnnotationExtractor.enumerate "FIXME"
+    Bones::AnnotationExtractor.enumerate(PROJ, "FIXME")
   end
 
   desc "Enumerate all TODO annotations"
   task :todo do
-    Bones::AnnotationExtractor.enumerate "TODO"
+    Bones::AnnotationExtractor.enumerate(PROJ, "TODO")
   end
 end
 

data/tasks/setup.rb

@@ -1,4 +1,4 @@
-# $Id: setup.rb 428 2007-12-31 17:55:51Z tim_pease $
+# $Id: setup.rb 431 2007-12-31 21:24:37Z tim_pease $
 
 require 'rubygems'
 require 'rake'
@@ -56,6 +56,10 @@ PROJ.dependencies = []
 PROJ.need_tar = true
 PROJ.need_zip = false
 
+# File Annotations
+PROJ.annotation_exclude = []
+PROJ.annotation_extensions = %w(.txt .rb .erb) << ''
+
 # Load the other rake files in the tasks folder
 Dir.glob('tasks/*.rake').sort.each {|fn| import fn}
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: bones
 version: !ruby/object:Gem::Version 
-  version: 1.1.2
+  version: 1.2.0
 platform: ruby
 authors: 
 - Tim Pease