falsework 2.1.1 → 3.0.0

data/doc/README.rdoc

@@ -17,21 +17,23 @@ Initially the template spec was designed only for Ruby projects but
 later (from version 1.3.0) hard-coded Ruby staff was removed which added
 more flexibility.
 
-The generated project <b>is not dependent</b> on falsework. The utility
-can also add skeletons for tests end executables <i>after</i> the
+Generated projects <b>are not dependent</b> on falsework. The utility
+can also add skeletons for tests end executables <b>after</b> the
 project generation.
 
 
 ==Ruby Template
 
-... is default. It generates a scaffold which have:
+... is default. It generates a scaffold which has:
 
 * auto-created git (but not github) project;
 
-* <tt>gem</tt> (a file list is pulled from the git repository, <b>no more
-  missing files in gems!</b>), <tt>doc</tt>, <tt>test</tt> targets;
+* <tt>gemspec</tt> (a file list is pulled from the git repository),
+  <tt>doc</tt>, <tt>test</tt> targets; +build+, +install+ & +release+
+  bundler targets.
 
-* easy to use configuration parser/loader. This includes scanning for:
+* easy to use configuration parser/loader. This includes auto-scanning
+  for:
 
   * env variable(s);
   * the flat YAML configuration file;
@@ -45,83 +47,41 @@ Version & name of your project can be located at generated
 
 ==Options
 
-The commands:
+Run
 
-list::                      Do nothing except listing all available
-                            templates. You can add your own templates in
-                            <tt>~/.falsework/templates</tt> directory.
+ $ falsework -h
 
-listdirs::                  Do nothing except listing all available
-                            templates directories. You can add another
-                            directory by modifying <tt>tdir</tt> option
-                            in the config file. (<tt>tdir</tt> is an
-                            array).
-                            
-new NAME::                  Create a new project. It creates a directory
-                            <i>NAME</i> and populates it with files.
+to read all possible commands & global options. All of them, except
++new+ & +list+, work from the root project directory.
 
-The following commands works only from the root project directory:
+Some of the commands support <tt>-h</tt> option too, for example:
 
-exe NAME::                  Add a new executable to an existing
-                            project and a corresponding doc in
-                            <tt>doc</tt> sub-directory.
-
-doc NAME::                  Add a new doc file in
-                            <tt>doc</tt> sub-directory.
-                            
-test NAME::                 Add a new test in
-                            <tt>test</tt> sub-directory.
-
-upgrade::                   'Inject' or upgrade some vital files from the
-                            template into the project. Currently only
-                            'ruby-cli' template supports this.
-
-The options are as follows:
-
--t::                        A template name.
-
--b::                        A batch mode. (No questions asked.)
-
---no-git::                  Don't create a Git repository. Don't use
-                            this for 'ruby-cli' template.
-
---config-dirs::             List all possible locations for the
-                            configuration file. The first found wins.
-
---config NAME::             The name of the configuration file. If
-                            it contains <tt>/</tt> in it, the list from
-                            <tt>--config-dirs</tt> is ignored.
-
--V::                        Show falsework version and exit.
-
--v::                        Be more verbose. You can supply it several
-                            times, viz. <tt>-vv</tt> dumps even more
-                            debug info.
+ $ falsework upgrade -h
 
 
 ==Examples
 
 Create a new project:
 
- % falsework -v new foobar
+ $ falsework -v new foobar
 
 Add another CL util to the existing project:
 
- % pwd
+ $ pwd
  .../foobar
- % falsework exe foo
+ $ falsework exe foo
 
 (It will appear in <tt>bin/</tt> sub-directory.)
 
 Add another test file:
 
- % falsework test foo
+ $ falsework test foo
 
 (It will appear in <tt>test/</tt> sub-directory.)
 
 Create a project from another template:
 
- % falsework -t c-glib -v new foo-bar
+ $ falsework -t c-glib -v new foo-bar
 
 
 ==Bugs

data/doc/TODO.org

@@ -1,14 +1,24 @@
-* TODO In the distant future [3/7] [42%]
+* TODO In the distant future [9/12] [75%]
 
-- [-] more templates [1/4]
+- [-] more templates [1/3]
   - [X] c glib
-  - [ ] java android
   - [ ] ruby sinatra
-  - [ ] ruby cli but a lighter one
+  - [ ] ruby cli, but a lighter one
 - [X] write a small tutorial 'how to write a template'
-- [ ] release to rubygems.org (it must run test, pull to github, tag,
+- [X] release to rubygems.org (it must run test, pull to github, tag,
   create gem & upload it)
 - [ ] describe c-glib template
 - [X] normalize 'name' of the project before actually making a template
 - [X] target_uuid variable for exe/doc/test templates
-- [ ] relocate templates from lib/falsework directory to project root
+- [X] relocate templates from lib/falsework directory to project root
+- [X] project creation
+  - [X] embed a note--'.falsework' file into a new generated project
+  - [X] options to do not embed a note file
+- [X] new upgrade command
+  - [X] check if current project can be upgraded
+  - [X] list upgradeable files
+  - [X] list obsolete files
+  - [X] upgrade in overwrite mode
+- [X] check in 'falsework' executable for exceptions in mould.rb
+- [ ] move project creation factory to utils.rb
+- [X] make dynamic.ruby-cli a static file

data/doc/template-tutorial.rdoc

@@ -15,6 +15,11 @@ Your personal templates must be in <tt>~/.falsework/templates</tt>
 directory. To view all currently available templates, run <tt>falsework
 list</tt>.
 
+To add another directory to a search list (visible via <tt>falsework
+list dirs</tt>), modify value of +tdir+ key in
+<tt>~/.falsework/falsework.yaml</tt>. The value must be an array of
+readable directories.
+
 
 == Hierarchy
 
@@ -85,20 +90,20 @@ set it permission afterwards.
 The default configuration is:
 
  ---
- :exe:
- - :src: null
-   :dest: bin/%s'
-   :mode_int: 0744
+ exe:
+ - src: null
+   dest: bin/%s'
+   mode_int: 0744
 
- :doc:
- - :src: null
-   :dest: 'doc/%s.rdoc'
-   :mode_int: null
+ doc:
+ - src: null
+   dest: 'doc/%s.rdoc'
+   mode_int: null
 
- :test:
- - :src: null
-   :dest: 'test/test_%s.rb'
-   :mode_int: null
+ test:
+ - src: null
+   dest: 'test/test_%s.rb'
+   mode_int: null
 
 The value of each top level key is an array, so you can inject several
 files at once.
@@ -111,3 +116,35 @@ dest::      Sub-key can have <tt>%s</tt> in it which will be replaced with
             target value ('foobar' in the example above).
 
 mode_int::  Permission bits.
+
+Top level keys must be one of: +exe+, +doc+, +test+ or +file+ string
+values. Each of these strings correspond to a hard-coded command in
++falsework+ executable.
+
+
+== Upgrade command
+
+Any template may have instructions for updating files in old
+projects. To make your template 'upgradable', add to
+<tt>#config.yaml</tt>:
+
+ version: 2.3.4
+ upgrade:
+   obsolete:
+	 - some/file
+   files:
+	 - foo
+	 - bar/baz
+   from: 1.2.3
+
+where
+
+version::  Sets a current version of the template. Required.
+
+obsolete:: Means a list of files that user may delete. Optional.
+
+files::    A list of 'upgradable' files. It must be relative to the
+           template directory. Required.
+
+from::     A minimal template version number from which it is possible to
+           perform an upgrade. Required.

data/dynamic.yaml

@@ -0,0 +1,4 @@
+---
+templates/ruby-cli/lib/%%@project%%/cliconfig.rb: lib/falsework/cliconfig.rb
+templates/ruby-cli/lib/%%@project%%/cliutils.rb: lib/falsework/cliutils.rb
+templates/ruby-cli/test/helper_cliutils.rb: test/helper_cliutils.rb

data/falsework.gemspec

@@ -10,7 +10,7 @@ Gem::Specification.new do |gem|
   gem.homepage      = Meta::HOMEPAGE
 
   gem.files         = `git ls-files`.split($\)
-  gem.files.concat File.read('dynamic.ruby-cli').split("\n")
+  gem.files.concat YAML.load_file('dynamic.yaml').keys
   
   gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
   gem.test_files    = gem.files.grep(%r{^test/test_.+\.rb})
@@ -20,9 +20,18 @@ Gem::Specification.new do |gem|
   gem.required_ruby_version = '>= 1.9.2'
   gem.extra_rdoc_files      = gem.files.grep(%r{^doc/})
   gem.rdoc_options << '-m' << 'doc/README.rdoc' << '-x' << 'lib/.+/templates/'
+
+  gem.post_install_message  = <<-MESSAGE
+Users of 2.x! Your custom templates must be updated--format
+of #config.yaml has changed.
+
+See also doc/NEWS.rdoc file even if you don't have custom templates.
+  MESSAGE
   
   gem.add_dependency "open4", "~> 1.3.0"
   gem.add_dependency "rdoc", "~> 3.12"
   gem.add_dependency "bundler", "~> 1.1.3"
   gem.add_dependency "git", "~>1.2.5"
+
+  gem.add_development_dependency "fakefs", "~> 0.4.0"
 end

data/lib/falsework/cliconfig.rb

@@ -1,5 +1,3 @@
-# :erb: ruby-cli
-
 require 'pathname'
 require 'yaml'
 require 'optparse'
@@ -31,6 +29,7 @@ module Falsework
       @conf[:config_name] = Meta::NAME + '.yaml'
       @conf[:config_env] = Meta::NAME.upcase + '_CONF'
       @conf[:config_dirs] = DIR_CONFIG
+      @conf[:cl_parse_in_order] = false
     end
 
     # Setter for @conf
@@ -55,7 +54,7 @@ module Falsework
         }
       end
 
-      CliUtils.warnx "no config file '#{@conf[:config_name]}' found" if @conf[:verbose] >= 2
+      CliUtils.warnx "config file '#{@conf[:config_name]}' not found" if @conf[:verbose] >= 2
       return nil
     end
 
@@ -75,15 +74,15 @@ module Falsework
     # Check if options in array opts are in @conf.
     def requiredOptions?(opts)
       opts.each {|idx|
-        if !@conf.key?(idx.to_sym) || !@conf[idx.to_sym]
-          CliUtils.errx EX_CONFIG, "option #{idx} is either nil or missing"
+        if !@conf.key?(idx) || !@conf[idx]
+          CliUtils.errx EX_CONFIG, "option '#{idx}' is either nil or missing"
         end
       }
     end
 
     # Parse CLO and env variable. If block is given it is passed with
     # OptionParser object as a parameter.
-    def optParse
+    def optParse argv
       OptionParser.new do |o|
         o.on('-v', 'Be more verbose.') { |i|
           self[:verbose] += 1
@@ -118,7 +117,13 @@ module Falsework
         env = ENV[@conf[:config_env]].shellsplit if ENV.key?(@conf[:config_env])
 
         begin
-          [env, ARGV].each { |i| o.parse!(i) if i }
+          [env, argv].each { |i|
+            if @conf[:cl_parse_in_order]
+              o.order!(i) if i
+            else
+              o.parse!(i) if i
+            end
+          }
         rescue
           CliUtils.errx EX_USAGE, $!.to_s
         end
@@ -129,8 +134,8 @@ module Falsework
     #
     # [reqOpts] an array of requied options
     # [&block]  a optional block for OptionParser
-    def load(reqOpts = [], &block)
-      optParse(&block)
+    def load(reqOpts = [], argv = ARGV, &block)
+      optParse(argv, &block)
       loadFile
       requiredOptions?(reqOpts)
     end

data/lib/falsework/cliutils.rb

@@ -1,5 +1,3 @@
-# :erb: ruby-cli
-
 require 'pp'
 require 'open4'
 require 'pathname'

data/lib/falsework/meta.rb

@@ -1,7 +1,8 @@
+# :include: ../../README.rdoc
 module Falsework
   module Meta # :nodoc:
     NAME = 'falsework'
-    VERSION = '2.1.1'
+    VERSION = '3.0.0'
     AUTHOR = 'Alexander Gromnitsky'
     EMAIL = 'alexander.gromnitsky@gmail.com'
     HOMEPAGE = 'http://github.com/gromnitsky/' + NAME