linecook 1.2.1 → 2.0.0

data/lib/linecook/commands/{helper.rb → compile_helper.rb}

@@ -1,26 +1,25 @@
-require 'linecook/commands/command'
+require 'linecook/command'
 require 'linecook/utils'
 require 'fileutils'
 require 'erb'
 
 module Linecook
   module Commands
-    
-    # :startdoc::desc generates a helper module
+
+    # :startdoc::desc compile helper modules
     #
-    # Generates the specified helper module from a set of source files.  Each
-    # source file becomes a method in the module, named after the source file
-    # itself.
+    # Compiles a helper module from a set of source files.  Each source file
+    # becomes a method in the module, named after the source file itself.
     #
-    # The helper module will be generated under the lib directory in a file
-    # corresponding to const_name (which can also be a constant path).  By
-    # default, all files under the corresponding helpers directory will be
-    # used as sources.  For example these are equivalent and produce the
+    # The helper module will be generated under the output directory in a file
+    # corresponding to const_name (which can also be a constant path). Input
+    # directories may be specified to automatically search for source files
+    # based on constant path.  These are all are equivalent and produce the
     # Const::Name module in 'lib/const/name.rb':
     #
-    #   % linecook helper Const::Name
-    #   % linecook helper const/name
-    #   % linecook helper const/name helpers/const/name/*
+    #   $ linecook compile-helper Const::Name helpers/const/name/*
+    #   $ linecook compile-helper const/name helpers/const/name/*
+    #   $ linecook compile-helper const/name -i helpers
     #
     # == Source Files
     #
@@ -32,8 +31,7 @@ module Linecook
     #   .erb         file defines an ERB template (compiled to ruby code)
     #
     # Source files can specify documenation and a method signature using a
-    # standard header separated from the body by a double-dash.  For example
-    # this:
+    # header separated from the body by a double-dash, like this:
     #
     #   [echo.erb]
     #   Echo arguments out to the target.
@@ -41,34 +39,37 @@ module Linecook
     #   --
     #   echo <%= args.join(' ') %>
     #
-    # Is translated into something like:
+    # Which produces something like:
     #
     #   # Echo arguments out to the target.
     #   def echo(*args)
     #     eval ERB.new("echo <%= args.join(' ') %>").src
     #   end
     #
-    # A second method is also generated to return the result without writing
-    # it to the target.  The latter method is prefixed by and underscore
-    # like:
+    # A second 'capture' method is also generated to return the result without
+    # writing it to the target.  The latter method is prefixed by an
+    # underscore like this:
     #
     #   # Return the output of echo, without writing to the target
     #   def _echo(*args)
     #     ...
     #   end
     #
-    # Check and bang methods can be specified by adding -check and -bang to
-    # the end of the file name.  These extensions are stripped off like:
+    # Special characters can be added to a method name by using a -extension
+    # to the file name.  For example 'file-check.erb' defines the 'file?'
+    # method. These extensions are supported:
     #
-    #   [file-check.erb]   # => def file? ...
-    #   [make-bang.rb]     # => def make! ...
+    #   extension  character
+    #   -check     ?
+    #   -bang      !
+    #   -eq        =
     #
-    # Otherwise the basename of the source file must be a word; non-word
-    # basenames raise an error.
+    # Otherwise the basename of the source file must be a valid method name;
+    # invalid names raise an error.
     #
     # == Section Files
     #
-    # Special section files can be used to define non-standard code in the
+    # Section files are source files that can be used to insert code in the
     # following places:
     #
     #   [:header]
@@ -82,112 +83,144 @@ module Linecook
     #   end
     #   [:footer]
     #
-    # Section files are defined by prepending '-' to the file basename (like
-    # path/to/-header.rb) and are not processed like other source files;
-    # instead the contents are directly transcribed into the target file.
-    class Helper < Command
-      config :project_dir, '.', :short => :d        # the project directory
-      config :force, false, :short => :f, &c.flag   # force creation
-      config :quiet, false, &c.flag
-      
+    # Section files are defined by prepending '_' to the file basename (like
+    # path/to/_header.rb) and are, like other source files, processed
+    # according to their extname:
+    #
+    #   extname      translation
+    #   .rb          file defines ruby (directly inserted)
+    #   .rdoc        file defines RDoc (lines commented out, then inserted)
+    #
+    # Note that section files prevent methods beginning with an underscore;
+    # this is intentional and prevents collisions with capture methods.
+    class CompileHelper < Command
+      config :output_dir, 'lib'   # -o DIRECTORY : the output directory
+      config :search_dirs, []     # -i DIRECTORY : the input directory
+      config :force, false        # -f, --force : force creation
+      config :quiet, false        # -q, --quiet : print nothing
+
       include Utils
-      
+
       def process(const_name, *sources)
         const_path = underscore(const_name)
-        const_name = camelize(const_path)
-        
+        const_name = camelize(const_name)
+
         unless const_name?(const_name)
-          raise "invalid constant name: #{const_name.inspect}"
+          raise CommandError, "invalid constant name: #{const_name.inspect}"
         end
-        
-        sources = default_sources(const_path) if sources.empty?
-        target  = File.expand_path(File.join('lib', "#{const_path}.rb"), project_dir)
-        
+
+        sources = sources | search_sources(const_path)
+        target  = File.expand_path(File.join(output_dir, "#{const_path}.rb"))
+
         if sources.empty?
-          raise CommandError, "no sources specified (and none found under 'helpers/#{const_path}')"
+          raise CommandError, "no sources specified"
         end
-        
+
         if force || !FileUtils.uptodate?(target, sources)
           content = build(const_name, sources)
-          
+
           target_dir = File.dirname(target)
           unless File.exists?(target_dir)
             FileUtils.mkdir_p(target_dir) 
           end
-          
+
           File.open(target, 'w') {|io| io << content }
           $stdout.puts target unless quiet
         end
-        
+
         target
       end
-      
-      # Returns the default source files for a given constant path, which are
-      # all files under the 'project_dir/helpers/const_path' folder.
-      def default_sources(const_path)
-        pattern = File.join(project_dir, 'helpers', const_path, '*')
-        sources = Dir.glob(pattern)
+
+      # Returns source files for a given constant path, which are all files
+      # under the 'search_dir/const_path' folder.
+      def search_sources(const_path)
+        sources = []
+
+        search_dirs.each do |search_dir|
+          pattern = File.join(search_dir, const_path, '*')
+          sources.concat Dir.glob(pattern)
+        end
+
         sources.select {|path| File.file?(path) }
       end
-      
+
       # returns true if const_name is a valid constant name.
       def const_name?(const_name) # :nodoc:
         const_name =~ /\A(?:::)?[A-Z]\w*(?:::[A-Z]\w*)*\z/
       end
-      
+
       # helper to partition an array of source files into section and
       # defintion files
       def partition(sources) # :nodoc:
         sources.partition do |path|
           basename = File.basename(path)
           extname  = File.extname(path)
-          basename[0] == ?- && basename.chomp(extname) != '-'
+          basename[0] == ?_ && basename.chomp(extname) != '_'
         end
       end
-      
+
       # helper to load each section path into a sections hash; removes the
       # leading - from the path basename to determine the section key.
       def load_sections(paths) # :nodoc:
         sections = {}
-        
+
         paths.each do |path|
-          basename = File.basename(path)
-          extname  = File.extname(path)
-          key = basename[1, basename.length - extname.length - 1]
-          sections[key] = File.read(path)
+          begin
+            basename = File.basename(path)
+            extname  = File.extname(path)
+            key = basename[1, basename.length - extname.length - 1]
+            sections[key] = section_content(File.read(path), extname)
+          rescue CommandError
+            err = CommandError.new("invalid source file: #{path.inspect} (#{$!.message})")
+            err.set_backtrace($!.backtrace)
+            raise err
+          end
         end
-        
+
         sections
       end
-      
+
+      def section_content(content, extname) # :nodoc:
+        case extname
+        when '.rdoc'
+          content.gsub(/^/, '# ')
+
+        when '.rb'
+          content
+
+        else
+          raise CommandError.new("unsupported section format #{extname.inspect}")
+        end
+      end
+
       # helper to load and parse a definition file
       def load_definition(path) # :nodoc:
         extname = File.extname(path)
         name    = File.basename(path).chomp(extname)
         desc, signature, body = parse_definition(File.read(path))
-        
+
         [desc, parse_method_name(name), signature, method_body(body, extname)]
       rescue CommandError
-        err = CommandError.new("#{$!.message} (#{path.inspect})")
+        err = CommandError.new("invalid source file: #{path.inspect} (#{$!.message})")
         err.set_backtrace($!.backtrace)
         raise err
       end
-      
+
       # helper to reformat special basenames (in particular -check and -bang)
       # to their corresponding method_name
       def parse_definition(str) # :nodoc:
         head, body = str.split(/^--.*\n/, 2)
         head, body = '', head if body.nil?
-        
+
         found_signature = false
         signature, desc = head.split("\n").partition do |line|
           found_signature = true if line =~ /^\s*\(.*?\)/
           found_signature
         end
-        
+
         [desc.join("\n"), found_signature ? signature.join("\n") : '()', body.to_s]
       end
-      
+
       # helper to reformat special basenames (in particular -check and -bang)
       # to their corresponding method_name
       def parse_method_name(basename) # :nodoc:
@@ -195,11 +228,11 @@ module Linecook
         when /-check\z/ then basename.sub(/-check$/, '?')
         when /-bang\z/  then basename.sub(/-bang$/, '!')
         when /-eq\z/    then basename.sub(/-eq$/, '=')
-        when /\A\w+\z/  then basename
-        else raise CommandError.new("invalid method name: #{basename.inspect}")
+        when /\A[A-Za-z]\w*\z/  then basename
+        else raise CommandError.new("invalid method name #{basename.inspect}")
         end
       end
-      
+
       # helper to reformat a definition body according to a given extname.  rb
       # content is rstripped to improve formatting.  erb content is compiled
       # and the source is placed as a comment before it (to improve
@@ -212,54 +245,57 @@ module Linecook
           compiler.put_cmd = "write"
           compiler.insert_cmd = "write"
           code = [compiler.compile(body)].flatten.first
-          
+
+          # remove encoding comment in 1.9 because it is not needed
+          code = code.sub(/\A#coding:.*?\n/, '')
+
           "#{source}\n#{code}".gsub(/^(\s*)/) do |m| 
             indent = 2 + $1.length - ($1.length % 2)
             ' ' * indent
           end
-          
+
         when '.rb'
           body.rstrip
-          
+
         else
-          raise CommandError.new("invalid definition format: #{extname.inspect}")
+          raise CommandError.new("unsupported format #{extname.inspect}")
         end
       end
-      
+
       # helper to nest a module body within a const_name.  documentation
       # can be provided for the innermost constant.
       def module_nest(const_name, body, inner_doc=nil) # :nodoc:
         body = body.strip.split("\n")
-        
+
         const_name.split(/::/).reverse_each do |name|
-          body.collect! {|line| "  #{line}" }
-          
+          body.collect! {|line| line.empty? ? line : "  #{line}" }
+
           body.unshift "module #{name}"
           body.push    "end"
-          
+
           # prepend the inner doc to the innermost const
           if inner_doc
             body = inner_doc.strip.split("\n") + body
             inner_doc = nil
           end
         end
-        
+
         body.join("\n")
       end
-      
+
       # Returns the code for a const_name module as defined by the source
       # files.
       def build(const_name, sources)
         section_paths, definition_paths = partition(sources)
         sections    = load_sections(section_paths)
         definitions = definition_paths.collect {|path| load_definition(path) }
-        
+
         body = eval DEFINITION_TEMPLATE, binding, __FILE__, DEFINITION_TEMPLATE_LINE
         code = eval MODULE_TEMPLATE, binding, __FILE__, MODULE_TEMPLATE_LINE
-        
+
         code
       end
-      
+
       # :stopdoc:
       MODULE_TEMPLATE_LINE = __LINE__ + 2
       MODULE_TEMPLATE = ERB.new(<<-DOC, nil, '<>').src
@@ -282,14 +318,7 @@ def <%= method_name %><%= signature %>
 
   chain_proxy
 end
-
-def _<%= method_name %>(*args, &block) # :nodoc:
-  str = capture_str { <%= method_name %>(*args, &block) }
-  str.strip!
-  str
-end
 <% end %>
-
 <%= sections['foot'] %>
 DOC
       # :startdoc:

data/lib/linecook/commands/run.rb

@@ -1,48 +1,44 @@
-require 'linecook/commands/command'
-require 'linecook/commands/build'
+require 'linecook/command'
+require 'linecook/command_utils'
 
 module Linecook
   module Commands
-    
+
     # :startdoc::desc run packages
+    #
+    # Runs packages on remote hosts by transfering a package directory using
+    # scp, and then executing one or more scripts via ssh.  Run is configured
+    # using an ssh config file, which should contain all necessary ssh
+    # options.
+    #
+    # Packages are transfered to hosts based on the basename of the package,
+    # hence 'path/to/abox' will run on the 'abox' host as configured in the
+    # ssh config file.
+    #
     class Run < Command
+      include CommandUtils
+
       RUN_SCRIPT = File.expand_path('../../../../bin/linecook_run', __FILE__)
       SCP_SCRIPT = File.expand_path('../../../../bin/linecook_scp', __FILE__)
-      
-      config :project_dir, '.', :short => :d                 # the project directory
-      config :remote_dir, 'linecook', :short => :D           # the remote package dir
-      config :ssh_config_file, 'config/ssh', :short => :F    # the ssh config file
-      config :quiet, false, :short => :q, &c.flag            # silence output
-      config :transfer, true, &c.switch                      # transfer package (or not)
-      config :remote_scripts, ['run'], 
-        :short => :S, 
-        :long => :remote_script, &c.list                     # the remote script(s)
-      
-      def glob_package_dirs(package_names)
-        if package_names.empty?
-          pattern = File.expand_path('packages/*', project_dir)
-          Dir.glob(pattern).select {|path| File.directory?(path) }
-        else
-          package_names.collect do |package_name|
-            File.expand_path("packages/#{package_name}", project_dir)
-          end
-        end
+
+      config :remote_dir, 'linecook'        # -D : the remote package dir
+      config :remote_scripts, ['run']       # -S : the remote script(s)
+      config :ssh_config_file, 'config/ssh' # -F : the ssh config file
+      config :xtrace, false                 # -x : xtrace local scripts
+      config :scp, true                     # transfer package or not
+
+      def full_path_to_remote_dir
+        (remote_dir[0] == ?/ ? remote_dir : "$(pwd)/#{remote_dir}").chomp('/')
       end
-      
-      def process(*package_names)
-        package_dirs  = glob_package_dirs(package_names)
-        
-        unless remote_dir[0] == ?/
-          self.remote_dir = "$(pwd)/#{remote_dir}"
-          self.remote_dir.chomp!('/')
-        end
-        
+
+      def process(*package_dirs)
         opts = {
-          'D' => remote_dir,
-          'F' => ssh_config_file
+          'D' => full_path_to_remote_dir,
+          'F' => ssh_config_file,
+          'x' => xtrace
         }
-        
-        if transfer
+
+        if scp
           sh! "sh #{SCP_SCRIPT} #{format(opts)} #{package_dirs.join(' ')}"
         end
 
@@ -51,14 +47,22 @@ module Linecook
           sh! "sh #{RUN_SCRIPT} #{format(script_opts)} #{package_dirs.join(' ')}"
         end
       end
-      
+
       def format(opts)
         options = []
-        
+
         opts.each_pair do |key, value|
-          options << "-#{key} '#{value}'"
+          next if value.to_s.strip.empty?
+
+          case value
+          when true
+            options << "-#{key}"
+          when false
+          else
+            options << "-#{key} '#{value}'"
+          end
         end
-        
+
         options.sort.join(' ')
       end
     end