falsework 0.2.8 → 1.3.0

data/doc/TODO.org

@@ -0,0 +1,13 @@
+* TODO In the distant future [3/6]
+
+- [-] more templates [1/4]
+  - [X] c glib
+  - [ ] java android
+  - [ ] ruby sinatra
+  - [ ] 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,
+  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

data/doc/template-tutorial.rdoc

@@ -0,0 +1,113 @@
+= How To Write a Template
+
+
+== Naming Scheme
+
+A recommended scheme is <tt>language-name</tt>, for example,
+<tt>ruby-naive</tt>, <tt>java-android</tt>, <tt>c-gtk</tt>. Try to use
+the name <= 30 characters in length (this is just a advice, not a
+restriction).
+
+
+== Location
+
+Your personal templates must be in <tt>~/.falsework/templates</tt>
+directory. To view all currently available templates, run <tt>falsework
+list</tt>.
+
+
+== Hierarchy
+
+The file hierarchy in your template directory represents the hierarchy
+of a project generated from it. Any file you place in the directory of a
+particular template goes to the future project. (See an exception
+below.) Typically, the name of the file stays the same too.
+
+If you don't want some file to appear in the resulting project, prefix
+the file wit a '#' character, for example, <tt>#mytest.c</tt>.
+
+There are some files falsework ignores, for example
+<tt>.gitignore</tt>. To include such files, add a <tt>.#erb</tt>
+extension to its name.
+
+There is also a special <tt>#config.yaml</tt> file in the root directory
+of the template. It is an instruction for the template how to behave on
+inject falsework commands.
+
+
+== How Template Files are Processed
+
+Every file (except <tt>#config.yaml</tt>) is considered a Ruby erb
+template. Naturally you want to have some dynamic places in your
+template that are different from project to project, for example, its
+name.
+
+=== The list of useful variables
+
+@classy::           A name of the project including spaces, for example,
+                    'Foo Bar Pro'
+
+@project::          A lowercase derivative from @classy that is suited
+                    for executable name and Github, for example,
+                    'foo_bar_pro'.
+
+@camelcase::        Can be used as a module name, for example,
+                    'FooBarPro'.
+
+uuid::              A string like 'D93E3B05_DAFA_C1F6_8EEA_DBBA1E8DA432'.
+                    It's unique for every file.
+
+
+@user::             Github user name.
+
+@email::            User email.
+
+@gecos::            A full user name.
+
+=== Variables available only for inject falsework commands
+
+target::            Equivalent of @project.
+target_camelcase::  Equivalent of @camelcase.
+target_classy::     Equivalent of @classy.
+
+
+== Inject Configuration
+
+When user types
+
+ % falsework -t c-glib test foobar
+
+falsework looks info <tt>#config.yaml</tt> file in the <tt>c-glib</tt>
+template directory, searches for 'test' key and iterates on its value to
+read some file in the template directory, white that file somewhere and
+set it permission afterwards.
+
+The default configuration is:
+
+ ---
+ :exe:
+ - :src: null
+   :dest: bin/%s'
+   :mode_int: 0744
+
+ :doc:
+ - :src: null
+   :dest: 'doc/%s.rdoc'
+   :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.
+
+src::       A relative path to a file (that usually prefixed with
+            '#' & hidden from a generator). When +src+ is +null+, the
+            key is ignored and nothing is injected.
+
+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.

data/etc/falsework.yaml

@@ -1,2 +1,2 @@
 --- 
-:foobar: foobar
+:foobar: 'huh?'

data/lib/falsework/meta.rb

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

data/lib/falsework/mould.rb

@@ -1,47 +1,95 @@
 require 'git'
 require 'erb'
 require 'digest/md5'
+require 'securerandom'
 
 require_relative 'trestle'
 
-# Class Mould heavily uses 'naive' template. Theoretically it can manage
-# any template as long as it has files mentioned in #add.
-#
-# The directory with template may have files beginning with _#_ char
-# which will be ignored in #project_seed (a method that creates a shiny
-# new project form a template).
-#
-# If you need to run through erb not only the contents of a file in a
-# template but it name itself, then use the following convention:
-#
-# %%VARIABLE%%
-#
-# which is equivalent of erb's: <%= VARIABLE %>. See naive template
-# directory for examples.
-#
-# In the template files you may use any Mould instance variables. The
-# most usefull are:
-#
-# [@project]  A project name.
-# [@user]     Github user name.
-# [@email]    User email.
-# [@gecos]    A full user name.
 module Falsework
+  # The directory with template may have files beginning with # char
+  # which will be ignored in #project_seed (a method that creates a
+  # shiny new project form a template).
+  #
+  # If you need to run through erb not only the contents of a file in a
+  # template but it name itself, then use the following convention:
+  #
+  # %%VARIABLE%%
+  #
+  # which is equivalent of erb's: <%= VARIABLE %>. See 'ruby-naive'
+  # template directory for examples.
+  #
+  # In the template files you may use any Mould instance variables. The
+  # most usefull are:
+  #
+  # [@classy]       An original project name, for example, 'Foobar Pro'
+  #
+  # [@project]      A project name in lowercase, suitable for a name of an
+  #                 executable, for example, 'Foobar Pro' would be
+  #                 'foobar_pro'.
+  #
+  # [@camelcase]    A 'normalized' project name, for use in source code,
+  #                 for example, 'foobar pro' would be 'FoobarPro'.
+  #
+  # [@user]         Github user name.
+  # [@email]        User email.
+  # [@gecos]        A full user name.
   class Mould
+    # Where @user, @email & @gecos comes from.
     GITCONFIG = '~/.gitconfig'
-    TEMPLATE_DIRS = [Trestle.gem_libdir + '/templates',
-                     File.expand_path('~/.' + Meta::NAME + '/templates')]
-    TEMPLATE_DEFAULT = 'naive'
+    # The possible dirs for templates. The first one is system-wide.
+    @@template_dirs = [Trestle.gem_libdir + '/templates',
+                       File.expand_path('~/.' + Meta::NAME + '/templates')]
+    # The template used if user didn't select one.
+    TEMPLATE_DEFAULT = 'ruby-naive'
+    # A file name with configurations for the inject commands.
+    TEMPLATE_CONFIG = '#config.yaml'
+    # A list of files to ignore in any template.
     IGNORE_FILES = ['.gitignore']
 
-    attr_accessor :verbose, :batch
-    
-    def initialize(project, user = nil, email = nil, gecos = nil)
+    # A verbose level for -v CLO.
+    attr_accessor :verbose
+    # -b CLO.
+    attr_accessor :batch
+    # A directory of a new generated project.
+    attr_reader :project
+
+    # [project] A name of the future project; may include all crap with spaces.
+    # [template] A name of the template for the project.
+    # [user] Github username; if nil we are extracting it from the ~/.gitconfig.
+    # [email] Github email
+    # [gecos] A full author name from ~/.gitconfig.
+    def initialize(project, template, user = nil, email = nil, gecos = nil)
+      @project = Mould.name_project project
+      raise "invalid project name '#{project}'" if !Mould.name_valid? @project
+      @camelcase = Mould.name_camelcase project
+      @classy = Mould.name_classy project
+      
       @verbose = false
       @batch = false
+      @template = template
+      @dir_t = Mould.templates[@template || TEMPLATE_DEFAULT] || Trestle.errx(1, "no such template: #{template}")
+
+      # default config
+      @conf = {
+        exe: [{
+                src: nil,
+                dest: 'bin/%s',
+                mode_int: 0744
+              }],
+        doc: [{
+                src: nil,
+                dest: 'doc/%s.rdoc',
+                mode_int: nil
+              }],
+        test: [{
+                 src: nil,
+                 dir: 'test/test_%s.rb',
+                 mode_int: nil
+               }]
+      }
+      Mould.config_parse(@dir_t + '/' + TEMPLATE_CONFIG, [], @conf)
       
       gc = Git.global_config rescue gc = {}
-      @project = project
       @user = user || gc['github.user']
       @email = email || ENV['GIT_AUTHOR_EMAIL'] || ENV['GIT_COMMITTER_EMAIL'] || gc['user.email']
       @gecos = gecos || ENV['GIT_AUTHOR_NAME'] || ENV['GIT_COMMITTER_NAME']  || gc['user.name']
@@ -53,11 +101,72 @@ module Falsework
       }
     end
 
+    # Modifies an internal list of available template directories
+    def self.template_dirs_add(dirs)
+      return unless defined? dirs.each
+
+      dirs.each {|idx|
+        if ! File.directory?(idx)
+          Trestle.warnx "invalid additional template directory: #{idx}"
+        else
+          @@template_dirs << idx
+        end
+      }
+    end
+    
+    # Hyper-fast generator of something like uuid suitable for code
+    # identifiers. Return a string.
+    def self.uuidgen_fake
+      loop {
+        r = ('%s_%s_%s_%s_%s' % [
+                                 SecureRandom.hex(4),
+                                 SecureRandom.hex(2),
+                                 SecureRandom.hex(2),
+                                 SecureRandom.hex(2),
+                                 SecureRandom.hex(6),
+                                ]).upcase
+        return r if r[0] !~ /\d/
+      }
+    end
+    
+    # Return false if @t is invalid.
+    def self.name_valid?(t)
+      return false if !t || t[0] =~ /\d/
+      t =~ /^[a-zA-Z0-9_]+$/ ? true : false
+    end
+
+    # Return cleaned version of an original project name, for example,
+    # 'Foobar Pro'
+    def self.name_classy(t)
+      t ? t.gsub(/\s+/, ' ').strip : ''
+    end
+
+    # Return a project name in lowercase, suitable for a name of an
+    # executable; for example, 'Foobar Pro' would be 'foobar_pro'.
+    def self.name_project(raw)
+      raw || (return '')
+
+      r = raw.gsub(/[^a-zA-Z0-9_]+/, '_').downcase
+      r.sub!(/^_/, '');
+      r.sub!(/_$/, '');
+
+      r
+    end
+
+    # Return a 'normalized' project name, for use in source code; for
+    # example, 'foobar pro' would be 'FoobarPro'.
+    def self.name_camelcase(raw)
+      raw || (return '')
+      raw.strip.split(/[^a-zA-Z0-9]+/).map{|idx|
+        idx[0].upcase + idx[1..-1]
+      }.join
+    end
+    
     # Return a hash {name => dir} with current possible template names
     # and corresponding directories.
     def self.templates
       r = {}
-      TEMPLATE_DIRS.each {|i|
+      @@template_dirs.each {|i|
         Dir.glob(i + '/*').each {|j|
           r[File.basename(j)] = j if File.directory?(j)
         }
@@ -65,111 +174,121 @@ module Falsework
       r
     end
 
-    # Generate a new project in @project directory from _template_.
-    #
-    # [template] If it's nil TEMPLATE_DEFAULT will be used.
-    # [filter]   A regexp for matching particular files in the
-    #            template directory.
+    # Generate a new project in @project directory from @template.
     #
     # Return false if nothing was extracted.
-    def project_seed(template, filter)
-      sl = ->(is_dir, *args) {
-        is_dir ? Mould.erb_fname(*args) : Mould.erb_fname(*args).sub(/\.erb$/, '')
-      }
+    def project_seed()
+      uuid = Mould.uuidgen_fake # useful variable for the template
       
       # check for existing project
       Trestle.errx(1, "directory '#{@project}' is not empty") if Dir.glob(@project + '/*').size > 0
 
-      Dir.mkdir(@project) unless File.directory?(@project)
-      prjdir = File.expand_path(@project)
-      puts "Project path: #{prjdir}" if @verbose
-
-      origdir = Dir.pwd;
-      Dir.chdir @project
+      Dir.mkdir @project unless File.directory?(@project)
+      puts "Project path: #{File.expand_path(@project)}" if @verbose
 
       r = false
-      start = Mould.templates[template || TEMPLATE_DEFAULT] || Trestle.errx(1, "no such template: #{template}")
-      puts "Template: #{start}" if @verbose
+      puts "Template: #{@dir_t}" if @verbose
       symlinks = []
-      Mould.traverse(start) {|i|
-        file = i.sub(/^#{start}\//, '')
-        next if filter ? file =~ filter : false
-        next if IGNORE_FILES.index {|ign| file.match(/#{ign}$/) }
+      Dir.chdir(@project) {
+        Mould.traverse(@dir_t) {|idx|
+          file = idx.sub(/^#{@dir_t}\//, '')
+          next if IGNORE_FILES.index {|i| file.match(/#{i}$/) }
 
-        if File.symlink?(i)
-          # we'll process them later on
-          is_dir = File.directory?(start + '/' + File.readlink(i))
-          symlinks << [sl.call(is_dir, File.readlink(i), binding),
-                       sl.call(is_dir, file, binding)]
-        elsif File.directory?(i)
-          puts("D: #{file}") if @verbose
-          file = Mould.erb_fname(file, binding)
-#          FileUtils.mkdir_p(prjdir + '/' + file)
-          Dir.mkdir(prjdir + '/' + file)
-          Dir.chdir(prjdir + '/' + file)
-        else
-          puts("N: #{file}") if @verbose
-          to = File.basename(Mould.erb_fname(file, binding), '.erb')
-          Mould.extract(start + '/' + file, binding, to)
-          # make files in bin/ executable
-          File.chmod(0744, to) if file =~ /bin\//
-        end
-        r = true
-      }
+          if File.symlink?(idx)
+            # we'll process them later on
+            is_dir = File.directory?(@dir_t + '/' + File.readlink(idx))
+            symlinks << [Mould.get_filename(File.readlink(idx), binding),
+                         Mould.get_filename(file, binding)]
+          elsif File.directory?(idx)
+            puts "D: #{file}"  if @verbose
+            Dir.mkdir Mould.get_filename(file, binding)
+          else
+            puts "N: #{file}" if @verbose
+            to = Mould.get_filename(file, binding)
+            Mould.extract(idx, binding, to)
+          end
+          r = true
+        }
 
-      # create saved symlinks
-      Dir.chdir prjdir
-      symlinks.each {|i|
-#        src = i[0].sub(/#{File.extname(i[0])}$/, '')
-#        dest = i[1].sub(/#{File.extname(i[1])}$/, '')
-        src = i[0]
-        dest = i[1]
-        puts "L: #{dest} => #{src}" if @verbose
-        File.symlink(src, dest)
+        # create saved symlinks
+        symlinks.each {|idx|
+          src = idx[0]
+          dest = idx[1]
+          puts "L: #{dest} => #{src}" if @verbose
+          File.symlink(src, dest)
+        }
       }
-      Dir.chdir origdir
+      
       r
     end
 
-    # Add an executable or a test from the _template_.
+    # Parse a config. Return false on error.
     #
-    # [mode] Is either 'exe' or 'test'.
-    # [what] A test/exe file to create.
+    # [file] A file to parse.
+    # [rvars] A list of variable names which must be in the config.
+    # [hash] a hash to merge results with
+    def self.config_parse(file, rvars, hash)
+      r = true
+      
+      if File.readable?(file)
+        begin
+          myconf = YAML.load_file(file)
+        rescue
+          Trestle.warnx "cannot parse #{file}: #{$!}"
+          return false
+        end
+        rvars.each { |i|
+          Trestle.warnx "missing or nil '#{i}' in #{file}" if ! myconf.key?(i.to_sym) || ! myconf[i.to_sym]
+          r = false
+        }
+        
+        hash.merge!(myconf) if r && hash
+      else
+        r = false
+      end
+      
+      r
+    end
+    
+    # Add an executable or a test from the template.
+    #
+    # [mode] Is either 'exe', 'doc' or 'test'.
+    # [target] A test/doc/exe file to create.
+    #
+    # Return a list of a created files.
     #
-    # Return a name of a created file.
-    def add(template, mode, what)
-      start = Mould.templates[template || TEMPLATE_DEFAULT] || Trestle.errx(1, "no such template: #{template}")
-      r = []
+    # Useful variables in the template:
+    #
+    # [target]
+    # [target_camelcase]
+    # [target_classy]
+    # [uuid]
+    def add(mode, target)
+      target_orig = target
+      target = Mould.name_project target_orig
+      raise "invalid target name '#{target_orig}'" if !Mould.name_valid? target
+      target_camelcase = Mould.name_camelcase target_orig
+      target_classy = Mould.name_classy target_orig
+      uuid = Mould.uuidgen_fake
+      
+      created = []
 
-      case mode
-      when 'exe'
-        # script
-        f = {}
-        f[:from] = start + '/' + 'bin/%%@project%%.erb'
-        f[:exe] = true
-        f[:to] = "bin/#{what}"
-        r << f
+      return [] unless @conf[mode.to_sym][0][:src]
 
-        # doc (reading an 'ignored' file from the template)
-        f = {}
-        f[:from] = start + '/' + 'doc/#util.rdoc.erb'
-        f[:exe] = false
-        f[:to] = "doc/#{what}.rdoc"
-        r << f
-      when 'test'
-        f = {}
-        f[:from] = start + '/' + 'test/test_%%@project%%.rb.erb'
-        f[:exe] = false
-        f[:to] = "#{mode}/test_#{what}.rb"
-        r << f
-      else
-        fail "invalid mode #{mode}"
-      end
+      @conf[mode.to_sym].each {|idx|
+        to = idx[:dest] % target
 
-      r.each {|i|
-        Mould.extract(i[:from], binding, i[:to])
-        File.chmod(0744, i[:to]) if i[:exe]
+        begin
+          Mould.extract(@dir_t + '/' + idx[:src], binding, to)
+          File.chmod(idx[:mode_int], to) if idx[:mode_int]
+        rescue
+          Trestle.warnx "failed to create '#{to}' (check your #config.yaml): #{$!}"
+        else
+          created << to
+        end
       }
+
+      created
     end
     
     # Walk through a directory tree, executing a block for each file or
@@ -191,53 +310,56 @@ module Falsework
       }
     end
     
-    # Extract into the current directory 1 file from _path_.
+    # Extract file @from into @to.
     #
-    # [bin] A binding for eval.
-    # [to]  If != nil write to a particular, not guessed file name.
-    def self.extract(path, bin, to = nil)
-      t = ERB.new(File.read(path))
-      t.filename = path # to report errors relative to this file
+    # [binding] A binding for eval.
+    def self.extract(from, binding, to)
+      t = ERB.new(File.read(from))
+      t.filename = from # to report errors relative to this file
       begin
-#        pp t.result
-        md5_system = Digest::MD5.hexdigest(t.result(bin))
+        output = t.result(binding)
+        md5_system = Digest::MD5.hexdigest(output)
       rescue Exception
-        Trestle.errx(1, "cannot read the template file: #{$!}")
+        Trestle.errx(1, "bogus template file '#{from}': #{$!}")
       end
 
-      skeleton = to || File.basename(path, '.erb')
-      if ! File.exists?(skeleton)
+      if ! File.exists?(to)
         # write a skeleton
         begin
-          File.open(skeleton, 'w+') { |fp| fp.puts t.result(bin) }
+          File.open(to, 'w+') { |fp| fp.puts output }
+          # transfer the exec bit to the generated result
+          File.chmod(0744, to) if File.stat(from).executable?
         rescue
-          Trestle.errx(1, "cannot write the skeleton: #{$!}")
+          Trestle.errx(1, "cannot generate: #{$!}")
         end
       elsif
         # warn a careless user
-        if md5_system != Digest::MD5.file(skeleton).hexdigest
-          Trestle.errx(1, "#{skeleton} already exists")
+        if md5_system != Digest::MD5.file(to).hexdigest
+          Trestle.errx(1, "'#{to}' already exists")
         end
       end
     end
 
-    def self.erb_fname(t, bin)
-      re = /%%([^.]+)?%%/
-      return ERB.new(t.gsub(re, '<%= \1 %>')).result(bin) if t =~ re
-      return t
+    # Resolve @t from possible %%VARIABLE%% scheme.
+    def self.get_filename(t, binding)
+      t || (return '')
+      
+      re = /%%([^%]+)%%/
+      t = ERB.new(t.gsub(re, '<%= \+ %>')).result(binding) if t =~ re
+      t.sub /\.#erb$/, ''
     end
     
 
-    # Search for all files in the _template_ for the line
+    # Search for all files in the template directory the line
     #
     # /^..? :erb:/
     #
     # in first n lines. If the line is found, the file is considered a
     # candidate for an upgrade. Return a hash {target:template}
-    def upgradable_files(template)
+    def upgradable_files()
       line_max = 4
       r = {}
-      Falsework::Mould.traverse(template) {|i|
+      Falsework::Mould.traverse(@dir_t) {|i|
         next if File.directory?(i)
         next if File.symlink?(i) # hm...
 
@@ -245,8 +367,8 @@ module Falsework
           n = 0
           while n < line_max && line = fp.gets
             if line =~ /^..? :erb:/
-              t = i.sub(/#{template}\//, '')
-              r[Mould.erb_fname(t, binding).sub(/\.erb$/, '')] = i
+              t = i.sub(/#{@dir_t}\//, '')
+              r[Mould.get_filename(t, binding)] = i
               break
             end
             n += 1
@@ -276,11 +398,10 @@ module Falsework
     #
     # Neithe we do check for a content of upgradable files nor try to
     # merge old with new. (Why?)
-    def upgrade(template)
+    def upgrade()
       # 0. search for 'new' files in the template
-      t = Mould.templates[template || TEMPLATE_DEFAULT] || Trestle.errx(1, "no such template: #{template}")
-      uf = upgradable_files(t)
-      fail "template #{template} cannot offer to you files for an upgrade" if uf.size == 0
+      uf = upgradable_files
+      fail "template #{@template} cannot offer you files for the upgrade" if uf.size == 0
  #     pp uf
       
       # 1. analyse 'old' files
@@ -293,10 +414,10 @@ module Falsework
           File.open(k) {|fp|
             is_versioned = false
             while line = fp.gets
-              if line =~ /^# Don't remove this: falsework\/(#{Gem::Version::VERSION_PATTERN})\/(\w+)\/.+/
+              if line =~ /^# Don't remove this: falsework\/(#{Gem::Version::VERSION_PATTERN})\/(.+)\/.+/
                 is_versioned = true
-                if $3 != (template || TEMPLATE_DEFAULT)
-                  fail "file #{k} is from #{$3} template"
+                if $3 != (@template || TEMPLATE_DEFAULT)
+                  fail "file #{k} is from '#{$3}' template"
                 end
                 if Gem::Version.new(Meta::VERSION) >= Gem::Version.new($1)
 #                  puts "#{k}: #{$1}"
@@ -312,7 +433,7 @@ module Falsework
           }
         end
       }
-      fail "template #{template || TEMPLATE_DEFAULT} cannot find files for an upgrade" if u.size == 0
+      fail "template #{@template || TEMPLATE_DEFAULT} cannot find files for an upgrade" if u.size == 0
 
       # 2. ask user for a commitment
       if ! @batch