ratch 1.1.0 → 1.2.0

data/lib/ratch/utils/xdg.rb

@@ -0,0 +1,39 @@
+module Ratch
+
+  # The XDG utility module provides access ot the XDG library functions.
+  # This module requires the `xdg` gem.
+  #
+  # This module simply maps the #xdg method to the XDG function module.
+  #
+  # NOTE: This module is non-essential since one can just use
+  # the XDG module directly, however we want to encourage the
+  # use XDG, so it's been provided to encourage that in the context
+  # of a Ratch script.
+  #
+  module XDGUtils
+
+    def self.included(base)
+      begin
+        require 'xdg'
+      rescue
+        $stderr << "The `xdg` gem is needed to use the XDGUtils module."
+        exit -1
+      end
+    end
+
+    def self.extended(base)
+      included(base)
+    end
+    
+    # Simple access to XDG function module.
+    #
+    #   xdg.config.home  #=> "~/.config"
+    #
+    def xdg
+      XDG
+    end
+ 
+  end
+
+end
+

data/lib/ratch/utils/zlib.rb

@@ -0,0 +1,54 @@
+module Ratch
+
+  #
+  module ZlibUtils
+
+    #
+    def self.included(base)
+      require 'zlib'
+    end
+
+    def self.extended(base)
+      included(base)
+    end
+
+    # Create a gzip file.
+    def gzip(file, tofile=nil, options={})
+      noop, verbose = *util_options(options)
+
+      tofile ||= File.basename(file) + '.gz'
+
+      puts "gzip #{file}" if verbose
+
+      file   = localize(file)
+      tofile = localize(tofile)
+
+      Zlib::GzipWriter.open(tofile) do |gz|
+        gz.write(File.read(file))
+      end unless noop
+
+      return tofile
+    end
+
+    # Unpack a gzip file.
+    def ungzip(file, options={})
+      noop, verbose = *util_options(options)
+
+      fname = File.basename(file).chomp(File.extname(file))
+
+      puts "ungzip #{file}" if verbose
+
+      fname = localize(fname)
+      file  = localize(file)
+
+      Zlib::GzipReader.open(file) do |gz|
+        File.open(fname, 'wb'){ |f| f << gz.read }
+      end unless noop
+
+      return fname
+    end
+
+  end
+
+end
+

data/spec/01_shell.rdoc

@@ -0,0 +1,198 @@
+= Ratch::Shell
+
+The Shell class mimics a basic shell command line prompt.
+
+  require 'ratch/shell'
+
+The demonstration sets up sample directory consisting of the following
+entires in the tmp/qed directory:
+
+  foo.txt
+  zoo/
+  zoo/bar.txt
+
+== Initial Path
+
+When no path argument is provided to the initializer, the present working path
+is used. The path is stored as a Pathname object.
+
+  shell = Ratch::Shell.new
+  shell.work.assert = Pathname.new(Dir.pwd).expand_path
+
+Otherwise the path given is used.
+
+  shell = Ratch::Shell.new('.')
+  shell.work.assert = Pathname.new('.').expand_path
+
+  shell = Ratch::Shell.new('..')
+  shell.work.assert = Pathname.new('..').expand_path
+
+An error is raise if the path does not exist.
+
+  expect Ratch::FileNotFound do
+    Ratch::Shell.new('not_a_path')
+  end
+
+== Processing Options
+
+The +initialize+ method accepts a few options. The +quiet+ option supresses
+all output to stdout.
+
+  shell = Ratch::Shell.new(:quiet=>true)
+  shell.assert.quiet?
+  
+The +noop+ option prevents any actual writing to disk --the process will
+simply pretend that it has done so.
+
+  shell = Ratch::Shell.new(:noop=>true)
+  shell.assert.noop? 
+
+The +trace+ option provides step by step feedback on what is taking place.
+
+  shell = Ratch::Shell.new(:trace=>true)
+  shell.assert.trace? 
+
+The +dryrun+ option is simply a compbination of +noop+ and +trace+.
+
+  shell = Ratch::Shell.new(:dryrun=>true)
+  shell.assert.noop?
+  shell.assert.trace?
+  shell.assert.dryrun?
+
+== Equality
+
+For two Shell objects to be considered equal, via #==, they must both
+be instances of Ratch::Shell (or subclass) and have the same working
+path.
+
+  shell1 = Ratch::Shell.new('.')
+  shell2 = Ratch::Shell.new('.')
+  shell1.assert = shell2
+
+  shell1 = Ratch::Shell.new('.')
+  shell2 = Ratch::Shell.new('..')
+  shell1.refute = shell2
+
+The more strict #eql? method also ensures that the +noop+ option is the same.
+
+  shell1 = Ratch::Shell.new('.', :noop=>true)
+  shell2 = Ratch::Shell.new('.', :noop=>true)
+  shell1.assert.eql? shell2
+
+  shell1 = Ratch::Shell.new('.', :noop=>true)
+  shell2 = Ratch::Shell.new('.', :noop=>false)
+  shell1.refute.eql? shell2
+
+== File System Locations
+
+The Shell class provides a few convenient methods for accessing common
+locations in the file system, namely #work, #home, #parent and #root.
+
+  shell = Ratch::Shell.new
+
+  shell.work.assert == Pathname.new('.').expand_path
+  shell.parent.assert == Pathname.new('..').expand_path
+
+The current user's home directoryis accessible via the #home method.
+
+  shell.home.assert == Pathname.new('~').expand_path
+
+The system's root folder can be accessed via #root method.
+
+  shell.root.assert == Pathname.new('/').expand_path
+
+In addition the Shell class provides methods for accessing pathnames
+relative to the current shell directory. The #path (or #pathname) method
+returns a Pathname object with the given path.
+
+  shell.path('foo')
+
+This will work regardless if the path actually exists or not. On the other hand,
+the #file and #dir methods will do the same, but will raise an error if the path
+given is not an existing file or a directory, respectively.
+
+  shell.file('foo.txt')
+
+  expect Ratch::FileNotFound do
+    shell.file('not.txt')
+  end
+
+  shell.dir('zoo')
+
+  expect Ratch::FileNotFound do
+    shell.dir('not')
+  end
+
+== Entries
+
+Shell#entries works just like Dir.entries except that each path is returned
+as a Pathname object.
+
+  shell = Ratch::Shell.new
+
+  shell.entries.assert == ['foo.txt', '.', '..', 'zoo'].map{|f| Pathname.new(f)}
+
+The #file_entries method limits the list to files only.
+
+  shell.file_entries.assert == ['foo.txt'].map{|f| Pathname.new(f)}
+
+Whereas #directory_entries (or #dir_entries) limits the list to directories.
+
+  shell.directory_entries.assert == ['.', '..', 'zoo'].map{|f| Pathname.new(f)}
+
+Of course, having to deal with the '.' and '..' is annoying most of the time
+so Shell provides more convenient methods. Like #entries, #pathnames 
+provides a list of entries less the dot paths.
+
+  shell.pathnames.assert == ['foo.txt', 'zoo'].map{|f| Pathname.new(f)}
+
+The #directories (also #folders) method limits this list to directories only.
+
+  shell.directories.assert == ['zoo'].map{|f| Pathname.new(f)}
+
+And #files works out to be the same as #file_entires.
+
+  shell.files.assert == ['foo.txt'].map{|f| Pathname.new(f)}
+
+== Globbing
+
+  shell = Ratch::Shell.new
+
+  shell.glob('*').assert == ['foo.txt', 'zoo']
+
+== File Testing
+
+Shell provides an interface to most of FileTest's functions. 
+
+  shell.assert.exist?('foo.txt')
+  shell.assert.file?('foo.txt')
+  shell.refute.directory?('foo.txt')
+  shell.assert.directory?('zoo')
+
+== File IO
+
+Shell can be used to easily read the contents of a file.
+
+  shell = Ratch::Shell.new
+
+  shell.read('foo.txt').assert == 'SAMPLE FOO.TXT'
+
+As well as write a new file.
+
+  shell.write('baz.txt', 'BAZ TEXT')
+  shell.read('baz.txt').assert == 'BAZ TEXT'
+
+Or append to an existing file.
+
+  shell.append('baz.txt', ' 2')
+  shell.read('baz.txt').assert == 'BAZ TEXT 2'
+
+The shell command supports many file methods, including #rm.
+
+  shell.rm('baz.txt')
+
+== System Calls
+
+The Shell class can also call out to system commands. This is handled
+by the Ratch::System class. See the system.rdoc file for details.
+

data/spec/02_script.rdoc

@@ -0,0 +1,34 @@
+= Ratch::Script
+
+The Ratch::Script class is the context used for evaluating Ratch-based
+batch files, aka shell scripts.
+
+  require 'ratch/script'
+
+In most every respect the Script class behaves like Ratch::Shell, except that
+its initializer takes a file name to be evaluated.
+
+Let's say we have a Ratch script called 'foo.ratch':
+
+  #!/usr/bin/env ratch
+
+  @test_message = "Hello World!"
+
+We can load the script via Ratch::Script.new.
+
+  script = Ratch::Script.new('foo.ratch')
+
+The file name can be accessed from the script using #script_file.
+
+  script.script_file.assert == 'foo.ratch'
+
+To execute a script, use the `#execute!` method, or it's alias `#run!`.
+
+  script.execute!
+
+We can see that the script did indeed execute by plubming for the instance
+variable it set.
+
+  msg = script.instance_variable_get('@test_message')
+  msg.assert == "Hello World!"
+

data/spec/03_batch.rdoc

@@ -0,0 +1,71 @@
+= Ratch::Batch
+
+The Batch class makes makes it possible to work with multiple files
+at once as easily as one would work with a single file.
+
+  require 'ratch/batch'
+
+The demonstration sets up a sample directory consisting of the following
+entires in the temporary working directory:
+
+  foo.txt
+  bar.txt
+  zoo/
+  zoo/one.txt
+  zoo/two.txt
+
+To create a new Batch instance, pass the the base directory and any 
+inclusion patterns to the initializer.
+
+  batch = Ratch::Batch.new('.', '*.txt')
+
+In this example we will get every `.txt` file at the toplevel of the base
+directory.
+
+  batch.to_a.assert = ['foo.txt', 'bar.txt'].to_pathnames
+
+To get a list of files relative to the base directory, use #entries.
+
+  batch.entries.assert = ['foo.txt', 'bar.txt'].to_pathnames
+
+Internally a Batch instance tracks the files selected via a Ratch::FileList
+object. This can be directly accessed via the #list method.
+
+  batch.file_list.assert.is_a?(Ratch::FileList)
+
+  batch.file_list.to_a.assert = ['foo.txt', 'bar.txt']
+
+As with the delegated FileTest methods of the Shell class, Batch can test
+the set of files in agregate. For example, to ensure all the entries
+are files we can use the #file? method.
+
+  batch.assert.file?
+
+Likewise to enusre none the entires are directories we can use the #directory?
+method.
+
+  batch.refute.directory?
+
+The Batch list can be reduced to just files or just directories via the #file!
+and #directory! methods.
+
+  batch = Ratch::Batch.new('.', '*')
+  batch.file!
+  batch.list.assert = ['foo.txt', 'bar.txt']
+
+  batch = Ratch::Batch.new('.', '*')
+  batch.directory!
+  batch.list.assert = ['zoo']
+
+The Batch class is enumerable, both #each and #size are defined.
+
+  batch = Ratch::Batch.new('.', '*.txt')
+
+  batch.each do |pathname|
+    pathname.assert.is_a?(Pathname)
+  end
+
+  batch.size.assert = 2
+
+Any enumerable method is likewise applicable.
+

data/spec/04_system.rdoc

@@ -0,0 +1,3 @@
+= Ratch::System
+
+

data/spec/applique/array.rb

@@ -0,0 +1,8 @@
+class ::Array
+
+  # Helper extension for comparison tests.
+  def to_pathnames
+    map{ |f| Pathname.new(f) }
+  end
+
+end

data/spec/applique/setup.rb

@@ -0,0 +1,20 @@
+require 'fileutils'
+
+Before :demo do
+  clear_working_directory!
+end
+
+When "consisting of the following entires" do |text|
+  text.split(/\s+/).each do |file|
+    if /\/$/ =~ file
+      FileUtils.mkdir_p(file) unless File.directory?(file)
+    else
+      File.open(file, 'w+'){ |f| f << "SAMPLE #{file}".upcase }
+    end
+  end
+end
+
+When "Let's say we have a Ratch script called '(((.*?)))'" do |file, text|
+  File.open(file, 'w'){ |f| f << text }
+end
+

data/test/case_batch.rb

@@ -0,0 +1,63 @@
+require 'ratch/batch'
+
+KO.case Ratch::Batch do
+
+  def initialize
+    stage_clear
+    stage_fake %w{a.txt b.txt d/x.txt d/y.txt}
+
+    @batch1 = Ratch::Batch.new('.')
+    @batch2 = Ratch::Batch.new('.', '*')
+    @batch3 = Ratch::Batch.new('.', '**/*')
+  end
+
+  test :local do
+    @batch1.local == Pathname.new('.')
+  end
+
+  test :list do
+    @batch1.list.is_a?(Array)
+  end
+
+  test :file_list do
+    @batch1.file_list.is_a?(Ratch::FileList)
+  end
+
+  test :each do
+    r = []
+    @batch2.each{ |pn| r << pn }
+    r.map(&:to_s).sort == %w{a.txt b.txt d}
+  end
+
+  test "passes #each thru to Enumerable methods" do
+    @batch2.all?{ |pn| pn.is_a? Pathname }
+  end
+
+  test :size do
+    batch = Ratch::Batch.new('.', '*')
+    batch.size == 3
+  end
+
+  test :directory? do
+    batch = Ratch::Batch.new('.', '*')
+    not batch.directory?
+  end
+
+  test :file? do
+    not @batch2.file?
+  end
+
+  test :directory! do
+    batch = Ratch::Batch.new('.', '*')
+    batch.directory!
+    batch.filenames == %w{d}
+  end
+
+  test :file! do
+    batch = Ratch::Batch.new('.', '*')
+    batch.file!
+    batch.filenames.sort == %w{a.txt b.txt}
+  end
+
+end
+