grizzled-ruby 0.1.0

data/lib/grizzled/dir.rb

@@ -0,0 +1,81 @@
+# This software is released under a BSD license, adapted from
+# http://opensource.org/licenses/bsd-license.php
+#
+# Copyright (c) 2011, Brian M. Clapper
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+#
+# * Neither the names "clapper.org", "Grizzled Ruby Library", nor the
+#   names of its contributors may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+# ---------------------------------------------------------------------------
+
+# Grizzled Ruby: A library of miscellaneous, general-purpose Ruby modules.
+#
+# Author:: Brian M. Clapper (mailto:bmc@clapper.org)
+# Copyright:: Copyright (c) 2011 Brian M. Clapper
+# License:: BSD License
+class Dir
+
+  # Adds a +walk+ method to the standard Ruby +Dir+ class. +walk+ walks a
+  # directory tree, starting at _dirname_, invoking the supplied block on
+  # each directory. The block is passed a +Dir+ object. The directory is
+  # walked top-down, not depth-first. To terminate the traversal, the block
+  # should return +false+. Anything else (including +nil+) continues the
+  # traversal.
+  def self.walk(dirname, &block)
+    Grizzled::Directory.walk(dirname, &block)
+  end
+
+  # Adds an +expand_path+ convenience method to the standard Ruby +Dir+
+  # class.
+  def expand_path
+    File.expand_path(self.path)
+  end
+end
+
+module Grizzled
+
+  # Useful directory-related methods.
+  class Directory
+
+    # Walk a directory tree, starting at _dirname_, invoking the supplied
+    # block on each directory. The block is passed a +Dir+ object. The
+    # directory is walked top-down, not depth-first. To terminate the
+    # traversal, the block should return +false+. Anything else (including
+    # +nil+) continues the traversal.
+    def self.walk(dirname, &block)
+      if block.call(Dir.new(dirname)) != false
+        Dir.entries(dirname).each do |entry|
+          path = File.join(dirname, entry)
+          if File.directory?(path) && (entry != '..') && (entry != '.')
+            Grizzled::Directory.walk(path, &block)
+          end
+        end
+      end
+      nil
+    end
+  end
+end

data/lib/grizzled/fileutil/includer.rb

@@ -0,0 +1,241 @@
+# Provides a file inclusion preprocessor. See the documentation for
+# the Grizzled::FileUtil::Includer class for complete details.
+#
+# ---
+#
+# This software is released under a BSD license, adapted from
+# http://opensource.org/licenses/bsd-license.php
+#
+# Copyright (c) 2011, Brian M. Clapper
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+#
+# * Neither the names "clapper.org", "Grizzled Ruby Library", nor the
+#   names of its contributors may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+# ---------------------------------------------------------------------------
+
+require 'open-uri'
+require 'uri'
+require 'pathname'
+require 'grizzled/forwarder'
+require 'tempfile'
+
+module Grizzled
+
+  module FileUtil
+
+    # Thrown when include file processing encounters errors.
+    class IncludeException < StandardError; end
+
+    # Internal container for source information.
+    class IncludeSource
+      URL_PATTERN = %r{^(http|https|ftp)://}
+
+      attr_reader :reader, :uri
+
+      def initialize(reader, uri)
+        @reader = reader
+        @uri = uri
+      end
+    end
+
+    # == Introduction
+    #
+    # An +Includer+ object preprocesses a text file, resolve _include_
+    # references. The +Includer+ is an +Enumerable+, allowing iteration over
+    # the lines of the resulting expanded file.
+    #
+    # == Include Syntax
+    #
+    # The _include_ syntax is defined by a regular expression; any line
+    # that matches the regular expression is treated as an _include_
+    # directive. The default regular expression matches include directives
+    # like this::
+    #
+    #     %include "/absolute/path/to/file"
+    #     %include "../relative/path/to/file"
+    #     %include "local_reference"
+    #     %include "http://localhost/path/to/my.config"
+    #
+    # Relative and local file references are relative to the including file
+    # or URL. That, if an +Includer+ is processing file "/home/bmc/foo.txt"
+    # and encounters an attempt to include file "bar.txt", it will assume
+    # "bar.txt" is to be found in "/home/bmc".
+    #
+    # Similarly, if an +Includer+ is processing URL
+    # "http://localhost/bmc/foo.txt" and encounters an attempt to include
+    # file "bar.txt", it will assume "bar.txt" is to be found at
+    # "http://localhost/bmc/bar.txt".
+    #
+    # Nested includes are permitted; that is, an included file may, itself,
+    # include other files. The maximum recursion level is configurable and
+    # defaults to 100.
+    #
+    # The include syntax can be changed by passing a different regular
+    # expression to the +Includer+ class constructor.
+    #
+    # == Supported Methods
+    #
+    # +Includer+ supports all the methods of the +File+ class and can be
+    # used the same way as a +File+ object is used.
+    #
+    # == Examples
+    #
+    # Preprocess a file containing include directives, then read the result:
+    #
+    #     require 'grizzled/fileutil/includer'
+    #     include Grizzled::FileUtil
+    #
+    #     inc = Includer.new(path)
+    #     inc.each do |line|
+    #       puts(line)
+    #     end
+    class Includer
+
+      include Enumerable
+      include Grizzled::Forwarder
+
+      attr_reader :name, :max_nesting
+
+      # Initialize a new +Includer+.
+      #
+      # Parameters:
+      #
+      # [+source+]  A string, representing a file name or URL (http, https or
+      #             ftp), a +File+ object, or an object with an +each_line+
+      #             method that returns individual lines of input.
+      # [+options+] Various processing options. See below.
+      #
+      # Options:
+      #
+      # [+:max_nesting+]      Maximum include nesting level. Default: 100
+      # [+:include_pattern+]  String regex pattern to match include directives.
+      #                       Must have a single regex group for the file name
+      #                       or URL. Default: ^%include\s"([^"]+)"
+      def initialize(source, options={})
+        @max_nesting = options.fetch(:max_nesting, 100)
+        inc_pattern = options.fetch(:include_pattern, '^%include\s"([^"]+)"')
+        @include_re = /#{inc_pattern}/
+        includer_source = source_to_includer_source source
+        @source_uri = includer_source.uri
+        @temp = preprocess includer_source
+        @input = File.open @temp.path
+        forward_to @input
+      end
+
+      # Return the path of the original include file, if defined. If the
+      # original source was a URL, the URL is returned. If the source was a
+      # string, nil is returned.
+      def path
+        @source_uri.path
+      end
+
+      # Force the underlying resource to be closed.
+      def close
+        @input.close
+        @temp.unlink
+      end
+
+      private
+
+      def source_to_includer_source(source)
+        if source.class == String
+          open_source(URI::parse(source))
+        elsif source.class == File
+          open_source(URI::parse(source.path))
+        elsif source.respond_to? :each_line
+          IncludeSource.new(source, nil)
+        else
+          raise IncludeException.new("Bad input of class #{source.class}")
+        end
+      end
+
+      def preprocess(includer_source)
+
+        def do_read(input, temp, level)
+          input.reader.each_line do |line|
+            if m = @include_re.match(line)
+              if level >= @max_nesting
+                raise IncludeException.new("Too many nested includes " +
+                                           "(#{level.to_s}), at: " +
+                                           "\"#{line.chomp}\"")
+              end
+              new_input = process_include(m[1], input)
+              do_read(new_input, temp, level + 1)
+            else
+              temp.write(line)
+            end
+          end
+        end
+
+
+        temp = Tempfile.new('grizzled_includer')
+        begin
+          do_read(includer_source, temp, 1)
+        ensure
+          temp.close
+        end
+
+        temp
+      end
+
+      # Handle an include reference.
+      def process_include(source, parent_input)
+        cur_uri = parent_input.uri
+        uri = URI::parse(source)
+        if (cur_uri != nil) and (uri.scheme == nil)
+          # Could be a relative path. Should be relative to the parent input.
+          pathname = Pathname.new(source)
+          if not pathname.absolute?
+            # Not an absolute path, and the including source has a path
+            # (i.e., wasn't a string). Make this one relative to the path.
+            uri = cur_uri.clone            
+            uri.path = File.join(::File.dirname(cur_uri.path), source)
+          end
+        end
+
+        open_source(uri)
+      end
+
+      # Open an input source, based on a parsed URI.
+      def open_source(uri)
+        case uri.scheme
+          when nil then     f = open(uri.path)  # assume file/path
+          when 'file' then  f = open(uri.path)  # open path directly
+          when 'http' then  f = open(uri.to_s)  # open-uri will handle it
+          when 'https' then f = open(uri.to_s)  # open-uri will handle it
+          when 'ftp' then   f = open(uri.to_s)  # open-uri will handle it
+
+          else raise IncludeException.new("Don't know how to open #{uri.to_s}")
+        end
+
+        IncludeSource.new(f, uri)
+      end
+    end # class Includer
+
+  end # module File
+end # module Grizzled
+

data/lib/grizzled/forwarder.rb

@@ -0,0 +1,91 @@
+# Provides a module which, when mixed in, can be used to forward all
+# missing methods to another object.
+#
+# ---
+#
+# This software is released under a BSD license, adapted from
+# http://opensource.org/licenses/bsd-license.php
+#
+# Copyright (c) 2011, Brian M. Clapper
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+#
+# * Neither the names "clapper.org", "Grizzled Ruby Library", nor the
+#   names of its contributors may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+# ---------------------------------------------------------------------------
+
+module Grizzled
+
+  # +Forwarder+ makes it easy to forward calls to another object.
+  #
+  # Examples:
+  #
+  # Forward all unimplemented methods to a file:
+  #
+  #    class Test
+  #      include Grizzled::Forwarder
+  # 
+  #      def initialize(file)
+  #        forward_to file
+  #      end
+  #    end
+  #
+  #    Test.new(File.open('/tmp/foobar')).each_line do |line|
+  #      puts(line)
+  #    end
+  #
+  # Forward all unimplemented calls, _except_ +each+ to the specified
+  # object. Calls to +each+ will raise a +NoMethodError+:
+  #
+  #    class Test
+  #      include Grizzled::Forwarder
+  # 
+  #      def initialize(file)
+  #        forward_to file, [:each]
+  #      end
+  #    end
+  module Forwarder
+
+    # Forward all unimplemented method calls to +obj+, except those
+    # whose symbols are listed in the +exceptions+ array.
+    def forward_to(obj, exceptions=[])
+      @forward_obj = obj
+
+      require 'set'
+
+      @forwarder_exceptions = Set.new(exceptions)
+      class << self
+        def method_missing(m, *args, &block)
+          if not @forwarder_exceptions.include? m
+            @forward_obj.send(m, *args, &block)
+          else
+            super(m, *args, &block)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/grizzled/stack.rb

@@ -0,0 +1,159 @@
+# Provides a simple stack implementation. See the Grizzled::Stack class
+# for complete details.
+#
+# ---
+#
+# This software is released under a BSD license, adapted from
+# http://opensource.org/licenses/bsd-license.php
+#
+# Copyright (c) 2011, Brian M. Clapper
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+#
+# * Neither the names "clapper.org", "Grizzled Ruby Library", nor the
+#   names of its contributors may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+# ---------------------------------------------------------------------------
+
+# Grizzled Ruby: A library of miscellaneous, general-purpose Ruby modules.
+#
+# Author:: Brian M. Clapper (mailto:bmc@clapper.org)
+# Copyright:: Copyright (c) 2011 Brian M. Clapper
+# License:: BSD License
+module Grizzled
+
+  # Thrown for un-safe stacks if the stack
+  class StackUnderflowException < StandardError; end
+
+  # A simple stack wrapper on top of a Ruby array, providing a little more
+  # protection that using an array directly.
+  class Stack
+
+    include Enumerable
+
+    attr_reader :pop_empty_nil
+
+    # Initialize a new stack.
+    #
+    # Parameters:
+    #
+    # [+pop_empty_nil+]  +true+ if popping an empty stack should just return
+    #                    +nil+, +false+ if it should thrown an exception.
+    def initialize(pop_empty_nil=true)
+      @the_stack = []
+      @pop_empty_nil = pop_empty_nil
+    end
+
+    # Pop the top element from the stack. If the stack is empty, this method
+    # throws a +StackUnderflowException+, if +pop_empty_nil+ is +false+; or
+    # returns nil, if +pop_empty_nil+ is +true+.
+    def pop
+      if (@the_stack.length == 0) && (not @pop_empty_nil)
+        raise StackUnderflowException.new
+      end
+      @the_stack.pop
+    end
+
+    # Pop every element of the stack, returning the results as an array
+    # and clearing the stack.
+    def pop_all
+      result = @the_stack.reverse
+      @the_stack.clear
+      result
+    end
+
+    # Convenience method for +length == 0+.
+    def is_empty?
+      length == 0
+    end
+
+    # Push an element or an array of elements onto the stack. Returns the
+    # stack itself, to allow chaining. Note: If you push an array of elements,
+    # the elements end up being reversed on the stack. That is, this:
+    #
+    #     stack = Stack.new.push([1, 2, 3]) # yields Stack[3, 2, 1]
+    #
+    # is equivalent to
+    #
+    #     stack = Stack.new
+    #     [1, 2, 3].each {|i| stack.push i}
+    def push(element)
+      if element.class == Array
+        element.each {|e| @the_stack.push e}
+      else
+        @the_stack.push element
+      end
+      self
+    end
+
+    # Returns the size of the stack.
+    def length
+      @the_stack.length
+    end
+
+    # Yield each element of the stack, in turn. Unaffected by a change in
+    # the stack.
+    def each
+      self.to_a.each do |element|
+        yield element
+      end
+    end
+
+    # Clear the stack. Returns the stack, for chaining.
+    def clear
+      @the_stack.clear
+      self
+    end
+
+    # Printable version.
+    def inspect
+      @the_stack.inspect
+    end
+
+    # Return the stack as an array.
+    def to_a
+      @the_stack.reverse
+    end
+
+    # Return the stack's hash.
+    def hash
+      @the_stack.hash
+    end
+
+    # Determine if this hash is equal to another one.
+    def eql?(other)
+      (other.class == Stack) and (other.to_a == to_a)
+    end
+
+    # Compare this stack to another element.
+    def <=>(other)
+      if other.class == Stack
+        other.to_a <=> to_a
+      else
+        other.to_s <=> this.to_s
+      end
+    end
+  end
+end

data/lib/grizzled/string/template.rb

@@ -0,0 +1,416 @@
+# Provides a simple variable substitution capability, similar, in concept,
+# to Python's +StringTemplate+ class. See the Grizzled::String::Template
+# module, the Grizzled::String::UnixShellStringTemplate class and the
+# Grizzled::String::WindowsCmdStringTemplate class for complete details.
+#
+# ---
+#
+# This software is released under a BSD license, adapted from
+# http://opensource.org/licenses/bsd-license.php
+#
+# Copyright (c) 2011, Brian M. Clapper
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+#
+# * Neither the names "clapper.org", "Grizzled Ruby Library", nor the
+#   names of its contributors may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+# ---------------------------------------------------------------------------
+
+# Grizzled Ruby: A library of miscellaneous, general-purpose Ruby modules.
+#
+# Author:: Brian M. Clapper (mailto:bmc@clapper.org)
+# Copyright:: Copyright (c) 2011 Brian M. Clapper
+# License:: BSD License
+module Grizzled
+
+  module String
+
+    # Grizzled::String::Template - A simple string templating solution
+    # modeled after Python's +StringTemplate+ library. While Ruby has less
+    # need of this kind of library, because of its built-in string
+    # interpolation, this module can be useful for interoperating with
+    # Python or with the Grizzled Scala library's string templating
+    # library.
+    module Template
+
+      # Exception raised for non-existent variables in non-safe templates.
+      class VariableNotFoundException < StandardError; end
+
+      # What a parsed variable looks like.
+      class Variable
+
+        attr_reader :istart, :iend, :name, :default
+
+        def initialize(istart, iend, name, default=nil)
+          @istart = istart
+          @iend = iend
+          @name = name
+          @default = default
+        end
+
+        alias :inspect :to_s
+        def to_s
+          "#{name}"
+        end
+      end
+
+      # Base (abstract) class for a string template. Common logic is here.
+      # Subclasses implement specific methods.
+      class TemplateBase
+
+        attr_reader :resolver, :safe
+
+        # Initializer.
+        #
+        # Parameters:
+        #
+        # [+resolver+] A hash-like object that can take a variable name (via
+        #              the +[]+ function) and resolve its value, returning
+        #              the value (which is converted to string) or +nil+.
+        # [+options+]  hash of options. See below.
+        #
+        # Options:
+        #
+        # [+:safe+]    +true+ for a safe template that substitutes a blank
+        #              string for a non-existent variable, instead of
+        #              throwing an exception. Defaults to +true+.
+        def initialize(resolver, options={})
+          @resolver = resolver
+          @safe = options.fetch(:safe, true)
+        end
+
+        # Replace all variable references in the given string. Variable
+        # references are recognized per the regular expression passed to
+        # the constructor. If a referenced variable is not found in the
+        # resolver, this method either:
+        #
+        # - throws a +VariableNotFoundException+ (if +safe+ is +false+).
+        # - substitutes an empty string (if +safe+ is +true+)
+        #
+        # Recursive references are supported (but beware of infinite recursion).
+        #
+        # Parameters:
+        #
+        # [+s+] the string in which to replace variable references
+        #
+        # Returns the substituted result.
+        def substitute(s)
+
+          def substitute_variable(var, s)
+            end_string = var.iend == s.length ? "" : s[var.iend..-1]
+            value = get_variable(var.name, var.default)
+            transformed = 
+              (var.istart == 0 ? "" : s[0..(var.istart-1)]) + value + end_string
+            substitute(transformed)
+          end
+
+          # Locate the next variable reference.
+          var = find_variable_ref(s)
+          if var.nil?
+            s
+          else
+            substitute_variable(var, s)
+          end
+        end
+
+        # Parse the location of the first variable in the string. Subclasses
+        # should override this method.
+        #
+        # Parameters:
+        #
+        # [+s+] the string
+        #
+        # Returns a +Variable+ object, or +nil+.
+        def find_variable_ref(s)
+          nil
+        end
+
+        # Get a variable's value, returning the empty string or throwing an
+        # exception, depending on the setting of +safe+.
+        #
+        # Parameters:
+        #
+        # [+name+]    Variable name
+        # [+default+] Default value, or +nil+
+        def get_variable(name, default)
+          
+          def handle_no_value(default, name)
+            if not default.nil?
+              default
+            elsif @safe
+              ""
+            else
+              raise VariableNotFoundException.new(name)
+            end
+          end
+
+          resolver[name] || handle_no_value(default, name)
+        end
+      end # TemplateBase
+
+      # A string template that uses the Unix shell-like syntax +${varname}+
+      # (or +$varname+) for variable references. A variable's name typically
+      # consists of alphanumerics and underscores, but is controlled by the a
+      # supplied regular expression. To include a literal "$" in a string,
+      # escape it with a backslash.
+      #
+      # For this class, the general form of a variable reference is:
+      #
+      #     ${varname?default}
+      #
+      # The +?default+ suffix is optional and specifies a default value
+      # to be used if the variable has no value.
+      #
+      # A shorthand form of a variable reference is:
+      #
+      #     $varname
+      #
+      # The _default_ capability is not available in the shorthand form.
+      class UnixShellStringTemplate < TemplateBase
+
+        ESCAPED_DOLLAR_PLACEHOLDER = "\001"
+        ESCAPED_DOLLAR = %r{(\\*)(\\\$)}
+
+        # Initialize a new +UnixShellStringTemplate+. Supports various hash
+        # options.
+        #
+        # Parameters:
+        #
+        # [+resolver+] A hash-like object that can take a variable name (via
+        #              the +[]+ function) and resolve its value, returning
+        #              the value (which is converted to string) or +nil+.
+        # [+options+]  hash of options. See below.
+        #
+        # Options:
+        #
+        # [+:safe+]         +true+ for a safe template that substitutes a blank
+        #                   string for a non-existent variable, instead of
+        #                   throwing an exception. Defaults to +true+.
+        # [+:var_pattern+]  Regular expression pattern (as a string, not a
+        #                   Regexp object) to match a variable name. Defaults
+        #                   to "[A-Za-z0-9_]+"
+        def initialize(resolver, options={})
+          super(resolver, options)
+          var_re = options.fetch(:var_pattern, "[A-Za-z0-9_]+")
+          @long_var_regexp = %r{\$\{(#{var_re})(\?[^\}]*)?\}}
+          @short_var_regexp = %r{\$(#{var_re})}
+        end
+
+        # Replace all variable references in the given string. Variable
+        # references are recognized per the regular expression passed to
+        # the constructor. If a referenced variable is not found in the
+        # resolver, this method either:
+        #
+        # - throws a +VariableNotFoundException+ (if +safe+ is +false+).
+        # - substitutes an empty string (if +safe+ is +true+)
+        #
+        # Recursive references are supported (but beware of infinite recursion).
+        #
+        # Parameters:
+        #
+        # [+s+] the string in which to replace variable references
+        #
+        # Returns the substituted result.
+        def substitute(s)
+          # Kludge to handle escaped "$". Temporarily replace it with
+          # something highly unlikely to be in the string. Then, put a single
+          # "$" in its place, after the substitution. Must be sure to handle
+          # even versus odd number of backslash characters.
+
+          def pre_sub(s)
+
+            def handle_match(m, s)
+              if (m[1].length % 2) == 0
+                # Odd number of backslashes before "$", including
+                # the one with the dollar token (group 2). Valid escape.
+
+                b = m.begin(0)
+                start = (b == 0 ? "" : s[0..(b-1)])
+                start + ESCAPED_DOLLAR_PLACEHOLDER + pre_sub(s[m.end(0)..-1])
+              else
+                # Even number of backslashes before "$", including the one
+                # with the dollar token (group 2). Not an escape.
+                s
+              end
+            end
+
+            # Check for an escaped "$"
+            m = ESCAPED_DOLLAR.match(s)
+            if (m)
+              handle_match(m, s)
+            else
+              s
+            end
+          end
+
+          s2 = super(pre_sub(s))
+          s2.gsub(ESCAPED_DOLLAR_PLACEHOLDER, '$')
+        end
+
+        # Parse the location of the first variable in the string. Subclasses
+        # should override this method.
+        #
+        # Parameters:
+        #
+        # [+s+] the string
+        #
+        # Returns a +Variable+ object, or +nil+.
+        def find_variable_ref(s)
+
+          def handle_long_match(m)
+            name = m[1]
+            if m[2].nil?
+              default = nil
+            else
+              # Pull off the "?"
+              default = m[2][1..-1]
+            end
+
+            Variable.new(m.begin(0), m.end(0), name, default)
+          end
+
+          def handle_no_long_match(s)
+            m = @short_var_regexp.match(s)
+            if m.nil?
+              nil
+            else
+              Variable.new(m.begin(0), m.end(0), m[1], nil)
+            end
+          end
+
+          m = @long_var_regexp.match(s)
+          if m.nil?
+            handle_no_long_match(s)
+          else
+            handle_long_match(m)
+          end
+        end
+
+      end # UnixShellStringTemplate
+
+      # A string template that uses the Windows +cmd.exe+ syntax +%varname%+
+      # for variable references. A variable's name may consist of alphanumerics
+      # and underscores. To include a literal "%" in a string, escape it with
+      # a backslash ("\%").
+      class WindowsCmdStringTemplate < TemplateBase
+
+        ESCAPED_PERCENT = %r{(\\*)(%)}
+        ESCAPED_PERCENT_PLACEHOLDER = '\001'
+
+        # Initialize a new +WindowsCmdStringTemplate+. Supports various hash
+        # options.
+        #
+        # Parameters:
+        #
+        # [+resolver+] A hash-like object that can take a variable name (via
+        #              the +[]+ function) and resolve its value, returning
+        #              the value (which is converted to string) or +nil+.
+        # [+options+]  hash of options. See below.
+        #
+        # Options:
+        #
+        # [+:safe+]         +true+ for a safe template that substitutes a blank
+        #                   string for a non-existent variable, instead of
+        #                   throwing an exception. Defaults to +true+.
+        # [+:var_pattern+]  Regular expression pattern (as a string, not a
+        #                   Regexp object) to match a variable name. Defaults
+        #                   to "[A-Za-z0-9_]+"
+        def initialize(resolver, options={})
+          super(resolver, options)
+          var_pat = options.fetch(:var_pattern, "[A-Za-z0-9_]+")
+          @var_re = %r{%(#{var_pat})%}
+        end
+
+        # Replace all variable references in the given string. Variable
+        # references are recognized per the regular expression passed to
+        # the constructor. If a referenced variable is not found in the
+        # resolver, this method either:
+        #
+        # - throws a +VariableNotFoundException+ (if +safe+ is +false+).
+        # - substitutes an empty string (if +safe+ is +true+)
+        #
+        # Recursive references are supported (but beware of infinite recursion).
+        #
+        # Parameters:
+        #
+        # [+s+] the string in which to replace variable references
+        #
+        # Returns the substituted result.
+        def substitute(s)
+          # Kludge to handle escaped "%". Temporarily replace it with
+          # something highly unlikely to be in the string. Then, put a single
+          # "%" in its place, after the substitution. Must be sure to handle
+          # even versus odd number of backslash characters.
+
+          def pre_sub(s)
+
+            def handle_match(m, s)
+              if (m[1].length % 2) == 1
+                # Odd number of backslashes before "%". Valid escape.
+
+                b = m.begin(0)
+                start = (b == 0 ? "" : s[0..(b-1)])
+                start + ESCAPED_PERCENT_PLACEHOLDER + pre_sub(s[m.end(0)..-1])
+              else
+                # Even number of backslashes before "%". Not an escape.
+                s
+              end
+            end
+
+            # Check for an escaped "%"
+            m = ESCAPED_PERCENT.match(s)
+            if (m)
+              handle_match(m, s)
+            else
+              s
+            end
+          end
+
+          s2 = super(pre_sub(s))
+          s2.gsub(ESCAPED_PERCENT_PLACEHOLDER, '%')
+        end
+
+        # Parse the location of the first variable in the string. Subclasses
+        # should override this method.
+        #
+        # Parameters:
+        #
+        # [+s+] the string
+        #
+        # Returns a +Variable+ object, or +nil+.
+        def find_variable_ref(s)
+          m = @var_re.match(s)
+          if m.nil?
+            nil
+          else
+            Variable.new(m.begin(0), m.end(0), m[1], nil)
+          end
+        end
+      end # WindowsCmdStringTemplate
+
+    end # module
+  end # module
+end

data/lib/grizzled/unix.rb

@@ -0,0 +1,89 @@
+# This software is released under a BSD license, adapted from
+# http://opensource.org/licenses/bsd-license.php
+#
+# Copyright (c) 2011, Brian M. Clapper
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+#
+# * Neither the names "clapper.org", "Grizzled Ruby Library", nor the
+#   names of its contributors may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+# ---------------------------------------------------------------------------
+
+# Grizzled Ruby: A library of miscellaneous, general-purpose Ruby modules.
+#
+# Author:: Brian M. Clapper (mailto:bmc@clapper.org)
+# Copyright:: Copyright (c) 2011 Brian M. Clapper
+# License:: BSD License
+module Grizzled
+
+  # Unix-related OS things.
+  module Unix
+
+    # A +User+ object allows you to do things with Unix users, such as
+    # (for instance) run code as that user.
+    class User
+
+      require 'etc'
+
+      # Initialize a new user. The +id+ parameter is either a user name
+      # (string) or a UID (integer).
+      def initialize(id)
+        # Find the user in the password database.
+        @pwent = (id.is_a? Integer) ? Etc.getpwuid(id) : Etc.getpwnam(id)
+      end
+
+      # Run a block of code as this user.
+      #
+      # [+block+] the block to execute as that user. It will receive this
+      #           +User+ object as a parameter.
+      #
+      # This function will only run as 'root'.
+      #
+      # === Example
+      #
+      #     require 'grizzled/unix'
+      #     require 'fileutils'
+      #
+      #     Grizzled::Unix::User.new('root').run_as |u|
+      #       rm_r(File.join('/tmp', '*')) # Yeah, this is dangerous
+      #     end
+      def run_as(&block)
+
+        # Fork the child process. Process.fork will run a given block of
+        # code in the child process.
+        child = Process.fork do
+          # We're in the child. Set the process's user ID.
+          Process.uid = @pwent.uid
+
+          # Invoke the caller's block of code.
+          block.call(self)
+        end
+
+        Process.waitpid(child)
+      end
+    end
+  end
+end

data/lib/grizzled.rb

@@ -0,0 +1,42 @@
+# Grizzled Ruby is a library of miscellaneous Ruby classes and modules.
+# See http://software.clapper.org/grizzled-ruby/ for more details.
+#
+# Author:: Brian M. Clapper (mailto:bmc@clapper.org)
+# Copyright:: Copyright (c) 2011 Brian M. Clapper
+# License:: BSD License
+#
+# ---
+#
+# This software is released under a BSD license, adapted from
+# http://opensource.org/licenses/bsd-license.php
+#
+# Copyright (c) 2011, Brian M. Clapper
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are
+# met:
+#
+# * Redistributions of source code must retain the above copyright notice,
+#   this list of conditions and the following disclaimer.
+#
+# * Redistributions in binary form must reproduce the above copyright
+#   notice, this list of conditions and the following disclaimer in the
+#   documentation and/or other materials provided with the distribution.
+#
+# * Neither the names "clapper.org", "Grizzled Ruby Library", nor the
+#   names of its contributors may be used to endorse or promote products
+#   derived from this software without specific prior written permission.
+#
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
+# IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
+# THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+# PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
+# CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
+# EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+# PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
+# PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+# LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+# NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+# SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+# ---------------------------------------------------------------------------

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification 
+name: grizzled-ruby
+version: !ruby/object:Gem::Version 
+  hash: 27
+  prerelease: 
+  segments: 
+  - 0
+  - 1
+  - 0
+  version: 0.1.0
+platform: ruby
+authors: 
+- Brian M. Clapper
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2011-03-12 00:00:00 -05:00
+default_executable: 
+dependencies: []
+
+description: |
+  Grizzled Ruby is a general purpose library of Ruby modules and classes
+
+email: bmc@clapper.org
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- lib/grizzled/stack.rb
+- lib/grizzled/fileutil/includer.rb
+- lib/grizzled/dir.rb
+- lib/grizzled/forwarder.rb
+- lib/grizzled/string/template.rb
+- lib/grizzled/unix.rb
+- lib/grizzled.rb
+has_rdoc: true
+homepage: http://software.clapper.org/grizzled-ruby
+licenses: []
+
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  none: false
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      hash: 3
+      segments: 
+      - 0
+      version: "0"
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.6.2
+signing_key: 
+specification_version: 3
+summary: Miscellaneous, general-purpose Ruby modules and classes
+test_files: []
+