ratch 1.1.0 → 1.2.0

data/README.rdoc

@@ -0,0 +1,113 @@
+= Ratch 
+
+Ruby-based Batch Scripts
+
+
+== Introduction
+
+Ratch is Ruby-based DSL for building batch scripts. It's intent
+is to ease the burden of batch script writers by supplementing
+the standard ruby environment to be more conducive to the needs
+of batch scripting.
+
+In addition to using Ratch to write stand-alone batch scripts,
+it makes a very powerful library for other applications that
+require batch-like functionality. In general any program that
+access the file system extensively could benefit from it's use.
+
+
+== Resources
+
+* home: http://rubyworks.github.com/ratch
+* code: http://github.com/rubyworks/ratch
+* talk: http://googlegroups.com/
+
+== Usage
+
+=== Batch Scripting
+
+To use for your own scripts, simply add a bang line.
+
+  #!/usr/bin/env ratch
+
+On Windows, of course, you will want to associate the .ratch extension
+name to the ratch executable instead.
+
+=== As a Library
+
+To use Ratch as a library, require 'ratch' and create an instance of
+Ratch::Shell.
+
+If you wish to extend Ratch::Shell for your application, it is recommend
+that you either subclass Ratch::Shell, e.g.
+
+  require 'ratch'
+
+  class MyClass < Ratch::Shell
+
+
+  end
+
+Or delegate to a Ratch::Shell instance, e.g.
+
+  require 'ratch'
+
+  class MyClass
+
+    def initialize(path)
+      @shell = Ratch::Shell.new(path)
+    end
+
+  end
+
+For details on all the functionality Ratch provides, please refer to
+the API documentation.
+
+
+== Bonus Feature
+
+Ratch also includes the `ludo` command, which stands for "lookup and do".
+It will ascend up the directory tree searching for a matching executable 
+script. If it finds one it will execute the script relative the currently
+ascended directory.
+
+
+== Installation
+
+Standard installation procedure apply.
+
+  $ gem install ratch
+
+or manually using Setup.rb
+
+  $ tar -xzf ratch-1.0.0.tgz
+  $ cd ratch-1.0.0
+  $ setup.rb
+
+
+== Development
+
+Ratch is hosted on GitHub.
+
+To pull the 'ratch' repository anonymously, use:
+
+    git clone git://github.com/rubyworks/ratch.git
+        
+
+== Copying
+
+Copyright (c) 2008 Thomas Sawyer
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this program except in compliance with the License.
+You may obtain a copy of the License at
+
+   http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
+

data/Version

@@ -0,0 +1 @@
+1.2.0

data/bin/ludo

@@ -0,0 +1,16 @@
+#! /usr/bin/ruby1.8
+
+# for FileTest.root?
+require 'facets/filetest'
+
+name = ARGV[0]
+
+if name
+  Dir.chdir '..' until FileTest.executable?(name) or FileTest.root?(Dir.pwd)
+  if FileTest.executable?( name )
+    system name
+  end
+else
+  puts "Script #{name} not found."
+end
+

data/bin/ratch

@@ -1,10 +1,3 @@
 #!/usr/bin/env ruby
-
-$0 = ARGV.shift
-
 require 'ratch/script'
-
-script = Ratch::Script.new
-
-script.instance_eval(File.read($0))
-
+Ratch::Script.execute(ARGV.shift)

data/lib/ratch.rb

@@ -0,0 +1,28 @@
+module Ratch
+  # Access to project metadata.
+  def self.metadata
+    @metadata ||= (
+      require 'yaml'
+      YAML.load(File.dirname(__FILE__) + '/ratch.yml')
+    )
+  end
+
+  # Access to project metadata via constants.
+  def self.const_missing(name)
+    metadata[name.to_s.downcase] || super(name)
+  end
+
+  # TODO: Only here b/c of issue with Ruby 1.8.x.
+  VERSION = metadata['version']
+end
+
+require 'ratch/script'
+
+# Load utility extension modules.
+require 'ratch/utils/cli'
+require 'ratch/utils/pom'
+require 'ratch/utils/rdoc'
+#require 'ratch/utils/email'
+#require 'ratch/utils/tar'
+#require 'ratch/utils/zlib'
+

data/lib/ratch.yml

@@ -0,0 +1,99 @@
+--- 
+name: ratch
+spec_version: 1.0.0
+repositories: 
+  public: git://github.com/rubyworks/ratch.git
+title: Ratch
+contact: trans <transfire@gmail.com>
+requires: 
+- group: []
+
+  name: facets
+  version: 2.9.1+
+- group: []
+
+  name: minitar
+  version: 0.5.3+
+- group: 
+  - test
+  name: ko
+  version: 1.2.0~
+- group: 
+  - test
+  name: qed
+  version: 0+
+- group: 
+  - build
+  name: syckle
+  version: 0+
+resources: 
+  code: http://github.org/rubyworks/ratch
+  mail: http://groups.gooogle.com/group/rubyworks-mailinglist
+  home: http://rubyworks.github.org/ratch
+manifest: 
+- .ruby
+- bin/ludo
+- bin/ratch
+- lib/ratch/batch.rb
+- lib/ratch/console.rb
+- lib/ratch/core_ext/facets.rb
+- lib/ratch/core_ext/filetest.rb
+- lib/ratch/core_ext/to_actual_filename.rb
+- lib/ratch/core_ext/to_console.rb
+- lib/ratch/core_ext/to_list.rb
+- lib/ratch/core_ext/to_yamlfrag.rb
+- lib/ratch/core_ext/unfold_paragraphs.rb
+- lib/ratch/core_ext.rb
+- lib/ratch/file_list.rb
+- lib/ratch/script/help.rb
+- lib/ratch/script.rb
+- lib/ratch/shell.rb
+- lib/ratch/system.rb
+- lib/ratch/utils/cli.rb
+- lib/ratch/utils/config.rb
+- lib/ratch/utils/email.rb
+- lib/ratch/utils/ftp.rb
+- lib/ratch/utils/pom.rb
+- lib/ratch/utils/rdoc.rb
+- lib/ratch/utils/tar.rb
+- lib/ratch/utils/xdg.rb
+- lib/ratch/utils/zlib.rb
+- lib/ratch.rb
+- lib/ratch.yml
+- man/ratch.1
+- spec/01_shell.rdoc
+- spec/02_script.rdoc
+- spec/03_batch.rdoc
+- spec/04_system.rdoc
+- spec/applique/array.rb
+- spec/applique/setup.rb
+- test/case_batch.rb
+- test/case_shell.rb
+- test/core_ext/case_pathname.rb
+- test/helper.rb
+- test/utils/case_cli.rb
+- test/utils/case_config.rb
+- test/utils/case_email.rb
+- test/utils/case_ftp.rb
+- test/utils/case_pom.rb
+- test/utils/case_rdoc.rb
+- test/utils/case_tar.rb
+- test/utils/case_zlib.rb
+- test/utils/fixtures/pom_sample/Profile
+- test/utils/fixtures/rdoc_sample/README.rdoc
+- test/utils/fixtures/rdoc_sample/lib/rdoc_sample/rdoc_sample.rb
+- README.rdoc
+- History.rdoc
+- Version
+- License.txt
+- COPYING
+version: 1.2.0
+licenses: 
+- Apache 2.0
+copyright: Copyright (c) 2009 Thomas Sawyer
+description: Ratch is a Ruby-based batch scripting language. It's a DSL over regular Ruby to make the life of the batch script writter easier.
+summary: Ruby-based Batch Scripting
+organization: RubyWorks
+authors: 
+- Trans <transfire@gmail.com>
+created: 2009-09-22

data/lib/ratch/batch.rb

@@ -0,0 +1,500 @@
+require 'ratch/core_ext'
+require 'ratch/file_list'
+
+module Ratch
+
+  # Proccess a list of files in batch.
+  #
+  # The Batch interface mimics the Shell class in most respects.
+  #
+  # TODO: Should FileList use Pathname, or only in Batch?
+  class Batch
+    include Enumerable
+
+    #
+    def self.[](*patterns)
+      new('.', *patterns)
+    end
+
+    #
+    def initialize(local, *patterns)
+      @local   = Pathname.new(local)
+      @options = (Hash === patterns.last ? patterns.pop : {}).rekey(&:to_sym)
+
+      @file_list = FileList.all
+
+      patterns.each do |pattern|
+        if @local == Pathname.new('.')
+          @file_list.add(pattern)
+        else
+          @file_list.add(File.join(local,pattern))
+        end
+      end
+    end
+
+    #
+    attr :local
+
+    # Returns the the underlying FileList object.
+    def file_list
+      @file_list
+    end
+
+    # Iterate over pathnames.
+    def each(&block)
+      @file_list.each{ |file| block.call(Pathname.new(file)) }
+    end
+
+    # Returns the Integer size of the list of files.
+    def size
+      @file_list.size
+    end
+
+    # Return the list of files as Pathname objects.
+    def to_a
+      @file_list.map{ |file| Pathname.new(file) }
+    end
+
+    # Return the list of files as Pathname objects.
+    alias_method :pathnames, :to_a
+
+    # Returns the list of files as Strings, rather than Pathname objects.
+    def list
+      @file_list.to_a
+    end
+    alias_method :filenames, :list
+
+    # Returns an Array of file paths relative to +local+.
+    def entries
+      map{ |entry| entry.sub(local.to_s+'/','') }
+    end
+
+    # Limit list to files.
+    def file!
+      @file_list = @file_list.select{ |f| File.file?(f) }
+    end
+
+    # Limit list to directories.
+    def directory!
+      @file_list = @file_list.select{ |f| File.directory?(f) }
+    end
+
+    # Limit list to selection block.
+    def select!(&block)
+      #@file_list = FileList.all(*to_a.select{ |f| block.call(f) })
+      @file_list = @file_list.select{ |f| block.call(f) }
+    end
+
+    #############
+    # FileTest  #
+    #############
+
+    # This is called #size in FileTest but must be renamed to 
+    # avoid the clash with the Enumerable mixin.
+    def byte_size
+      inject(0){ |sum, path| sum + FileTest.size(path) }
+    end
+ 
+    # An alias for #byte_size.
+    alias_method :size?, :byte_size
+
+    def directory?  ; all?{ |path| FileTest.directory?(path)  } ; end
+    def symlink?    ; all?{ |path| FileTest.symlink?(path)    } ; end
+    def readable?   ; all?{ |path| FileTest.readable?(path)   } ; end
+    def chardev?    ; all?{ |path| FileTest.chardev?(path)    } ; end
+    def exist?      ; all?{ |path| FileTest.exist?(path)      } ; end
+    def exists?     ; all?{ |path| FileTest.exists?(path)     } ; end
+    def zero?       ; all?{ |path| FileTest.zero?(path)       } ; end
+    def pipe?       ; all?{ |path| FileTest.pipe?(path)       } ; end
+    def file?       ; all?{ |path| FileTest.file?(path)       } ; end
+    def sticky?     ; all?{ |path| FileTest.sticky?(path)     } ; end
+    def blockdev?   ; all?{ |path| FileTest.blockdev?(path)   } ; end
+    def grpowned?   ; all?{ |path| FileTest.grpowned?(path)   } ; end
+    def setgid?     ; all?{ |path| FileTest.setgid?(path)     } ; end
+    def setuid?     ; all?{ |path| FileTest.setuid?(path)     } ; end
+    def socket?     ; all?{ |path| FileTest.socket?(path)     } ; end
+    def owned?      ; all?{ |path| FileTest.owned?(path)      } ; end
+    def writable?   ; all?{ |path| FileTest.writable?(path)   } ; end
+    def executable? ; all?{ |path| FileTest.executable?(path) } ; end
+    def safe?       ; all?{ |path| FileTest.safe?(path)       } ; end
+
+    # TODO: Will this work since all paths are localized?
+    def relative?   ; all?{ |path| FileTest.relative?(path)   } ; end
+    def absolute?   ; all?{ |path| FileTest.absolute?(path)   } ; end
+
+    def writable_real?   ; all?{ |path| FileTest.writable_real?(path)   } ; end
+    def executable_real? ; all?{ |path| FileTest.executable_real?(path) } ; end
+    def readable_real?   ; all?{ |path| FileTest.readable_real?(path)   } ; end
+
+    alias_method :dir?, :directory?
+
+    def identical?(other)
+      all?{ |path| FileTest.identical?(path, other) }
+    end
+
+    # TODO: Really?
+    alias_method :compare_file, :identical?
+    alias_method :cmp, :identical?
+
+
+    #############
+    # FileUtils #
+    #############
+
+    # Low-level Methods Omitted
+    # -------------------------
+    # getwd           -> pwd
+    # compare_file    -> cmp
+    # remove_file     -> rm
+    # copy_file       -> cp
+    # remove_dir      -> rmdir
+    # safe_unlink     -> rm_f
+    # makedirs        -> mkdir_p
+    # rmtree          -> rm_rf
+    # copy_stream
+    # remove_entry
+    # copy_entry
+    # remove_entry_secure
+    # compare_stream
+
+    # Present working directory.
+    # TODO: Does this make sense?
+    def pwd
+      @local
+    end
+
+    # Make a directory for every entry.
+    def mkdir(options={})
+      list.each do |dir|
+        if File.exist?(dir)
+          raise Errno::EEXIST, "File exists - #{dir}"
+        end
+      end
+      list.map{ |dir| fileutils.mkdir(dir, options) }
+    end
+
+    # Make a directory for every entry.
+    def mkdir_p(options={})
+      list.each do |dir|
+        if File.exist?(dir) && !File.directory?(dir)
+          raise Errno::EEXIST, "File exists - #{dir}"
+        end
+      end
+      list.map{ |dir| fileutils.mkdir_p(dir, options) }
+    end
+    alias_method :mkpath, :mkdir_p
+
+    # Remove every directory.
+    def rmdir(options={})
+      list.map{ |dir| fileutils.rmdir(dir, options) }
+    end
+
+    # ln(list, destdir, options={})
+    def ln(dir, options={})
+      #src = list.to_a
+      #new = localize(new)
+      fileutils.ln(list, dir, options)
+    end
+    alias_method :link, :ln
+
+    # ln_s(list, destdir, options={})
+    def ln_s(dir, options={})
+      #src = list.to_a
+      #new = localize(new)
+      fileutils.ln_s(list, dir, options)
+    end
+    alias_method :symlink, :ln_s
+
+    def ln_sf(dir, options={})
+      #src = list.to_a
+      #new = localize(new)
+      fileutils.ln_sf(list, dir, options)
+    end
+
+    # cp(list, dir, options={})
+    def cp(dir, options={})
+      #src  = list.to_a
+      #dest = localize(dest)
+      fileutils.cp(list, dir, options)
+    end
+    alias_method :copy, :cp
+
+    # cp_r(list, dir, options={})
+    def cp_r(dir, options={})
+      #src  = list.to_a
+      #dest = localize(dest)
+      fileutils.cp_r(list, dir, options)
+    end
+
+    # mv(list, dir, options={})
+    def mv(dir, options={})
+      #src  = list.to_a
+      #dest = localize(dest)
+      fileutils.mv(list, dir, options)
+    end
+    alias_method :move, :mv
+
+    #
+    def rm(options={})
+      list = list.to_a
+      fileutils.rm(list, options)
+    end
+
+    # Alias for #rm.
+    alias_method :remove, :rm
+
+    # Remove, recursively removing the contents of directories.
+    def rm_r(options={})
+      #list = list.to_a
+      fileutils.rm_r(list, options)
+    end
+
+    # Remove, with force option.
+    def rm_f(options={})
+      #list = list.to_a
+      fileutils.rm_f(list, options)
+    end
+
+    # Remove with force option, recursively removing the contents of directories.
+    def rm_rf(options={})
+      #list = list.to_a
+      fileutils.rm_rf(list, options)
+    end
+
+    # Install files to a directory with given mode. Unlike #cp, this will
+    # not copy the file if an up-to-date copy already exists.
+    def install(dir, mode, options={})
+      #src = list.to_a
+      #dest = localize(dest)
+      fileutils.install(list, dir, mode, options)
+    end
+
+    # Change mode of files.
+    def chmod(mode, options={})
+      #list = list.to_a
+      fileutils.chmod(mode, list, options)
+    end
+
+    # Change mode of files, following directories recursively.
+    def chmod_r(mode, options={})
+      #list = list.to_a
+      fileutils.chmod_r(mode, list, options)
+    end
+    #alias_method :chmod_R, :chmod_r
+
+    # Change owner of files.
+    def chown(user, group, options={})
+      #list = list.to_a
+      fileutils.chown(user, group, list, options)
+    end
+
+    # Change owner of files, following directories recursively.
+    def chown_r(user, group, options={})
+      #list = list.to_a
+      fileutils.chown_r(user, group, list, options)
+    end
+    #alias_method :chown_R, :chown_r
+
+    # Touch each file.
+    def touch(options={})
+      #list = list.to_a
+      fileutils.touch(list, options)
+    end
+
+    # Stage files. This is like #install but uses hardlinks.
+    def stage(dir)
+      #dir   = localize(directory)
+      #files = localize(files)
+      #list = list.to_a
+      fileutils.stage(dir, local, list)
+    end
+
+    # Convenient alias for #map_mv.
+    def rename(options={}, &block)
+      map_mv(options, &block)
+    end
+
+    # Rename the list of files in batch, using a block to determine the new
+    # names. If the block returns nil, the file will not be renamed.
+    #
+    # This is similar to #mv, but allows for detailed control over the renaming.
+    #
+    # Unlike the other `map_*` methods, this changes the Batch list in-place,
+    # since the files renamed no loner exist.
+    #
+    # Returns the changed FileList instance.
+    def map_mv(options={}, &block)
+      @file_list = map_send(:mv, options={}, &block)
+    end
+
+    # Hard link the list of files in batch, using a block to determine the new
+    # names. If the block returns nil, the file will not be linked.
+    #
+    # This is similar to #ln, but allows for detailed control over the link names.
+    def map_ln(options={}, &block)
+      map_send(:ln, options={}, &block)
+    end
+
+    # Soft link the list of files in batch, using a block to determine the new
+    # names. If the block returns nil, the file will not be linked.
+    #
+    # This is similar to #ln_s, but allows for detailed control over the link names.
+    def map_ln_s(options={}, &block)
+      map_send(:ln_s, options={}, &block)
+    end
+
+    # Force soft linking of the list of files in batch, using a block to 
+    # determine the new names. If the block returns nil, the file will not
+    # be linked.
+    #
+    # This is similar to #ln_sf, but allows for detailed control over the
+    # link names.
+    def map_ln_sf(options={}, &block)
+      map_send(:ln_sf, options={}, &block)
+    end
+
+    # Copy the list of files in batch, using a block to determine the new
+    # file names. If the block returns nil, the file will not be copied.
+    #
+    # This is similar to #cp, but allows for detailed control over the new
+    # file names.
+    def map_cp(options={}, &block)
+      map_send(:cp, options={}, &block)
+    end
+
+    # Copy the list of files recursively in batch, using a block to determine
+    # the new file names. If the block returns nil, the file will not be copied.
+    #
+    # This is similar to #cp_r, but allows for detailed control over the new
+    # file names.
+    def map_cp_r(options={}, &block)
+      map_send(:cp_r, options={}, &block)
+    end
+
+#    # Force copy the list of files recursively in batch, using a block to
+#    # determine the new file names. If the block returns nil, the file will not
+#    # be copied.
+#    #
+#    # This is similar to #cp_rf, but allows for detailed control over the new
+#    # file names.
+#    def map_cp_rf(options={}, &block)
+#      map_send(:cp_rf, options={}, &block)
+#    end
+
+  private
+
+    SAFE_METHODS = [:ln]
+
+    # Generic name mapping procedure which can be used for any
+    # FileUtils method that has a `src, dest` interface.
+    #--
+    # TODO: Make public?
+    #++
+    def map_send(method, options={}, &block)
+
+      map = {}
+      list.each do |file|
+        if dest = block.call(file)
+          map[file] = dest
+        end
+      end
+
+      if options[:safe] or !options[:force] or SAFE_METHODS.include?(method) 
+        ensure_safe(map)
+      end
+
+      map.each do |src, dest|
+        fileutils.__send__(method, src, dest, options)
+      end
+      FileList.all(*map.values)
+    end
+
+    # Given a map of source to destination, this method ensures
+    # a FileUtils operation can is "safe" --that the destination does not
+    # yet and exist and/or the source and destination are compatible. 
+    # If nota file rrror is raised.
+    def ensure_safe(map)
+      map.each do |src, dest|
+        raise unless File.exist?(src)
+        if File.directory?(src)
+          if File.directory?(dest)
+            new_map = {}
+            Dir.entries(src).each do |e|
+              next if e == '.' or e == '..'
+              new_map[File.join(src, e)] = File.join(dest, e)
+            end
+            ensure_safe_destination(new_map)
+          else
+            raise Errno::EISDIR, "Is a directory - #{src}"
+          end
+        else
+          if File.directory?(dest)
+            check = File.join(dest, src)
+            if File.exist?(check)
+              raise Errno::EEXIST, "File exists - #{check}"
+            end
+          else
+            raise Errno::EEXIST, "File exists - #{dest}" if File.exist?(dest)
+          end
+        end
+      end
+    end
+
+  public
+
+    # An intergrated glob like method that takes a set of include globs,
+    # exclude globs and ignore globs to produce a collection of paths.
+    #
+    # Ignore_globs differ from exclude_globs in that they match by
+    # the basename of the path rather than the whole pathname.
+    #
+    #def amass(include_globs, exclude_globs=[], ignore_globs=[])
+    #  locally do
+    #    fileutils.amass(include_globs, exclude_globs, ignore_globs)
+    #  end
+    #end
+
+    # Is +path+ out-of-date in comparsion to all files in batch.
+    def outofdate?(path)
+      fileutils.outofdate?(path, to_a)
+    end
+
+    # Is +path+ up-to-date in comparsion to all files in batch.
+    def uptodate?(path)
+      fileutils.uptodate?(path, to_a)
+    end
+
+    #
+    def noop?
+      @options[:noop] or @options[:dryrun]
+    end
+
+    #
+    def verbose?
+      @options[:verbose] or @options[:dryrun]
+    end
+
+    #
+    def dryrun?
+      noop? && verbose?
+    end
+
+  private
+
+    # Returns FileUtils module based on mode.
+    def fileutils
+      if dryrun?
+        ::FileUtils::DryRun
+      elsif noop?
+        ::FileUtils::Noop
+      elsif verbose?
+        ::FileUtils::Verbose
+      else
+        ::FileUtils
+      end
+    end
+
+  end
+
+end
+