fluid 1.0.0

data/History.txt

@@ -0,0 +1,3 @@
+Version 1.0.0
+  * Converted to Rubyforge+gem distribution.
+  * Removed binding of I/O-related globals.

data/LICENSE.txt

@@ -0,0 +1,34 @@
+This software is Copyright (C) 2007 by Brian Marick <marick@exampler.com>. It is licensed according to "the Ruby license". Specifically:
+
+You can redistribute it and/or modify it under either the terms of the GNU General Public License, version 2, <http://www.gnu.org/licenses/old-licenses/gpl-2.0.html> or the conditions below:
+
+  1. You may make and give away verbatim copies of the source form of the
+     software without restriction, provided that you duplicate all of the
+     original copyright notices and associated disclaimers.
+
+  2. You may modify your copy of the software in any way, provided that
+     you do at least ONE of the following:
+
+       a) place your modifications in the Public Domain or otherwise
+          make them Freely Available, such as by posting said
+          modifications to Usenet or an equivalent medium, or by allowing
+          the author to include your modifications in the software.
+
+       b) use the modified software only within your corporation or
+          organization.
+
+       c) make other distribution arrangements with the author.
+
+  3. You may modify and include part of the software into any other
+     software (possibly commercial).  
+
+  4. Text or files supplied as input to or produced as output from 
+     the software do not automatically fall under the copyright of the
+     software, but belong to whomever generated them, and may be sold
+     commercially, and may be aggregated with this software.
+
+  5. THIS SOFTWARE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR
+     IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED
+     WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+     PURPOSE.
+

data/Manifest.txt

@@ -0,0 +1,13 @@
+History.txt
+LICENSE.txt
+Manifest.txt
+README.txt
+Rakefile
+Rakefile.hoe
+examples/a-bit-more-clever-fluid-tracing.rb
+examples/globals.rb
+examples/simple-fluid-tracing.rb
+homepage/index.html
+lib/fluid.rb
+setup.rb
+test/fluid-tests.rb

data/README.txt

@@ -0,0 +1,126 @@
+Class Fluid provides dynamically scoped ("fluid") variables modeled
+after those of Common Lisp. It also gives you a convenient way to
+reversibly change the values of globals.
+
+== An Alternative to Globals
+
+Here's an incredibly simple example:
+
+  require 's4t-utils/fluid'
+
+  Fluid.let(:var, 1) {
+    puts Fluid.var   # prints 1
+  }
+  puts Fluid.var    # error - Fluid.var has disappeared at this point.
+
+Fluid.var is a "pseudovariable" that only exists within the block. What's
+interesting about fluid variables is what "within the block" means.
+Here's another example:
+
+  require 's4t-utils/fluid'
+
+  def putter
+    puts Fluid.var
+  end
+
+  Fluid.let(:var, 1) { 
+    putter 
+  }
+  putter
+
+The first call of +putter+ will successfully print 1. The second
+will fail because Fluid.var doesn't exist any more. 
+
+Fluid variables are useful in relatively few situations. They're good when you have
+some number of interconnected objects that need to share some 
+value. You could pass the value around, but then intermediate methods 
+that didn't care about it would have to pass it along to methods 
+that did. You could use a global, but then the value would be visible
+to objects that ought not to be able to see it. Fluid variables let you
+"scope" the value to all methods called (directly or indirectly) from
+an entry point to the collection of connected objects.
+
+This is especially handy when you want to change the value of the 
+variable according to the depth of processing, as when you want to 
+increase the indentation level of some sort of tracing output. 
+Like this:
+
+  fact(5)
+    fact(4)
+      fact(3)
+        fact(2)
+          fact(1)
+          fact(1) => 1
+        fact(2) => 2
+      fact(3) => 6
+    fact(4) => 24
+  fact(5) => 120
+
+One implementation of that would look like the following implementation
+of fact. It uses two utility methods that reduce clutter.
+
+    def fact(n)
+      trace "fact(#{n})"     # trace() produces output with appropriate indentation.
+      result = 
+        if n <= 1 
+          n 
+        else 
+          deeper { n * fact(n-1) }   # deeper() executes block with increased indentation.
+        end
+      trace "fact(#{n}) => #{result}"
+      result
+    end
+
+
+Here's the support code.
+
+    Fluid.defvar(:indent_prefix, '')    # Initial value of indentation.
+  
+    def trace(text)
+      puts Fluid.indent_prefix + text   # Use the value even though it wasn't passed in.
+    end
+  
+    def deeper                          # "Rebind" the value of the variable for the scope of a block.
+      Fluid.let([:indent_prefix, Fluid.indent_prefix + '  ']) do
+        yield
+      end
+    end
+  
+For an even less intrusive example, see the examples directory.
+
+Here's a final example that shows the syntax and behavior of
+Fluid.let. See also the more formal description at Fluid.let.
+
+  Fluid.let([:var1, 1],
+            [:var2, 2]) {
+    puts(Fluid.var1)              # prints 1
+    puts(Fluid.var2)              # prints 2
+    Fluid.let([:var2, "new 2"],
+              [:var3, "new 3"]) {
+      puts(Fluid.var1)               # prints 1, as above.
+      puts(Fluid.var2)               # prints "new 2"
+      puts(Fluid.var3)               # prints "new 3"
+    }
+    puts(Fluid.var1)              # prints 1
+    puts(Fluid.var2)              # Back to printing 2
+    puts(Fluid.var3)              # error - that variable no longer exists.
+  }
+
+
+== Globals
+
+If you wish, you can also use Fluid.let to temporarily change the value of 
+globals. For example, the global #, is used as an implicit argument to 
+Array#join. You could do the following:
+
+   Fluid.let("$,",  "-") do
+     puts [1, 2, 3].join     #=> "1-2-3"
+   end
+
+   puts [1, 2, 3].join       #=> "123"
+
+The advantage of this over just setting $, and then resetting it is that
+Fluid takes care of dealing with exceptions.
+
+You're not allowed to rebind all globals. The I/O globals ($stdout, etc.) 
+have special-case behavior that's either impossible or not safe to cope with. 

data/Rakefile

@@ -0,0 +1,35 @@
+# This is a Rakefile that would live in the root folder for any package
+# that follows the Scripting for Testers conventions. You should not need
+# to edit it.
+
+$started_from_rakefile=true
+
+require 'pathname'
+PACKAGE_ROOT = Dir.pwd
+$:.unshift("#{PACKAGE_ROOT}/lib")
+
+# The tests require my S4TUtils to run, but the library itself 
+# doesn't require it, so it's not listed as a dependency in the gem.
+require 's4t-utils/load-path-auto-adjuster'
+
+require 's4t-utils'
+include S4tUtils
+
+# The following two lines are used to tell generic Rake tasks about
+# this particular project. If you installed using the s4t-utils
+# installation tool, they should have already been set correctly. 
+
+MyFileSystemName='fluid'  # No ".rb" extension.
+MyModuleName='Fluid'
+
+
+# These are the Ruby files 'rake rdoc' searchs for documentation.
+# The following includes all ruby files except for third-party
+# libraries. Change at will.
+
+MyRdocFiles = FileList.new("lib/fluid.rb",
+                           "lib/fluid/**/*.rb").exclude("**/third-party/**")
+
+
+require 's4t-utils/rakefile-common'
+

data/Rakefile.hoe

@@ -0,0 +1,22 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-07-03.
+#  Copyright (c) 2007. All rights reserved.
+
+require 'hoe'
+require 'lib/fluid'
+
+
+Hoe.new("fluid", Fluid::Version) do |p|
+  p.rubyforge_name = "fluid"
+  p.changes = "See History.txt"
+  p.author = "Brian Marick"
+  p.description = "Fluid (dynamically scoped) variables"
+  p.summary = p.description
+  p.email = "marick@exampler.com"
+  p.extra_deps = []
+  p.test_globs = "test/**/*-tests.rb"
+  p.rdoc_pattern = %r{README.txt|lib/}
+  p.url = "http://fluid.rubyforge.org"
+  p.remote_rdoc_dir = 'rdoc'
+end

data/examples/a-bit-more-clever-fluid-tracing.rb

@@ -0,0 +1,60 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-07-22.
+#  Copyright (c) 2007. All rights reserved.
+
+# This is a slightly cleverer implementation of logging with
+# varying indentation than the one in simple-fluid-tracing.rb.
+
+require 'fluid'
+
+def trace(text)
+  puts Fluid.indent_prefix + text
+end
+
+# Trace all calls to _methodname_ in class _klass_. By default, printing
+# is in this format:
+#    message(arg, arg, ...)
+# If _show_receiver_ is true, this format is used:
+#    receiver.message(arg, arg, ...)
+def indenting_trace(methodname, klass = self.class, show_receiver = false)
+  methodname = methodname.to_s  # ensure string.
+  original = '_untraced_'+methodname
+  klass.send(:alias_method, original, methodname)
+
+  klass.send(:define_method, methodname) do | *actual_args |
+    Fluid.defvar(:indent_prefix, '') # only has effect the first time
+    Fluid.let([:indent_prefix, Fluid.indent_prefix + '  ']) do
+      arglist_description = "(#{actual_args.collect {|a| a.inspect }.join(', ')})"
+      invocation = methodname + arglist_description
+      invocation = "#{self.inspect}.#{invocation}" if show_receiver
+      trace invocation
+      result = self.send(original, *actual_args)
+      trace invocation + ' => ' + result.inspect
+      result
+    end
+  end
+end
+
+class Fixnum
+  def times(other)    # Use this to show alternate printing.
+    self * other
+  end
+end
+
+def fact(n)
+  if (n <= 1)
+    1
+  else
+    n.times(fact(n-1))
+  end
+end
+
+puts "factorial of 5 is #{fact(5).to_s}."
+
+indenting_trace :fact
+indenting_trace :times, Fixnum, :show_receiver
+
+puts "factorial of 5 is #{fact(5).to_s}."
+
+

data/examples/globals.rb

@@ -0,0 +1,16 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-07-22.
+#  Copyright (c) 2007. All rights reserved.
+
+# This example shows using Fluid with global variables. Essentially,
+# it's a slightly more compact way of changing a global within a 
+# begin... ensure... end loop that makes sure to undo the change.
+
+require 'fluid'
+
+Fluid.let("$,",  "-") do
+  puts [1, 2, 3].join     #=> "1-2-3"
+end
+
+puts [1, 2, 3].join       #=> "123"

data/examples/simple-fluid-tracing.rb

@@ -0,0 +1,38 @@
+#!/usr/bin/env ruby
+#
+#  Created by Brian Marick on 2007-07-22.
+#  Copyright (c) 2007. All rights reserved.
+
+# This example shows how a set of functions (in this case, recursive 
+# calls of the factorial function) can control indentation of log
+# output without having to pass around a variable containing the 
+# depth of the log. 
+
+require 'fluid'
+
+Fluid.defvar(:indent_prefix, '')
+
+def trace(text)
+  puts Fluid.indent_prefix + text
+end
+
+def deeper
+  Fluid.let([:indent_prefix, Fluid.indent_prefix + '  ']) do
+    yield
+  end
+end
+
+def fact(n)
+  trace "fact(#{n})"
+  result = 
+    if n <= 1 
+      n 
+    else 
+      deeper { n * fact(n-1) }
+    end
+  trace "fact(#{n}) => #{result}"
+  result
+end
+
+
+puts fact(5)

data/homepage/index.html

@@ -0,0 +1,15 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
+<head>
+	<meta http-equiv="Content-type" content="text/html; charset=utf-8">
+	<title>s4t-utils</title>
+	
+</head>
+<body>
+	<h1>Fluid (dynamically scoped) variables</h1>
+	<p></p>
+	<p><a href="http://fluid.rubyforge.org/rdoc/" title="Fluid.rb documentation">Documentation</a> (rdoc)</p>
+	<p><a href="" title="RubyForge: Fluid: Project Filelist">Download</a></p>
+	
+	
+</body>

data/lib/fluid.rb

@@ -0,0 +1,389 @@
+# Fluid variables for Ruby.
+# Originally 2004/03/08 20:16:13
+# Gemified 2007/07
+
+# Fluid (dynamically scoped) variables for Ruby. See README.txt[link:files/README_txt.html].
+class Fluid
+  Version="1.0.0"
+                                                          ### Environment ###
+
+  # An environment holds variable->value bindings. Each
+  # variable name is an entry in a hash table. It is
+  # associated with a stack of values. Environments are
+  # manipulated by objects of class Var.
+  class Environment < Hash # :nodoc:
+    def create(var_name)  self[var_name] = []; end
+    def destroy(var_name)  delete(var_name); end
+    def has?(var_name)  has_key?(var_name); end
+    def unbound?(var_name)  self[var_name] == []; end
+    def set(var_name, value)   self[var_name][-1] = value; end
+    def get(var_name)  self[var_name][-1]; end
+    def push_binding(var_name, var_value)  self[var_name].push(var_value); end
+    def pop_binding(var_name)   self[var_name].pop; end
+  end
+
+  # All fluid variables are managed by one environment.
+  @@environment = Environment.new
+
+
+                                                                 ### Var ###
+
+  # There are different kinds of variables. They use the environment
+  # differently. 
+  class Var # :nodoc: 
+    attr_reader :name,           # Canonicalize all names to symbols.
+                :original_name   # Retain original name for error messages.
+
+    # Factory method that returns subclasses of Var.
+    def Var.build(original_name, environment, value_destructor=nil)
+      klass = (global?(original_name)) ? GlobalVar : FluidVar
+      klass.build(original_name, environment, value_destructor)
+    end
+
+    def Var.global?(string_or_symbol)
+      ?$ == string_or_symbol.to_s[0]
+    end
+
+    def initialize(original_name, environment, value_destructor)
+      @original_name = original_name
+      @name = Var.ensure_symbol(original_name)
+      @environment = environment
+      @value_destructor = value_destructor
+    end
+
+    # These two methods are the ones used to manipulate the
+    # environment. Note subclasses.
+    def push_binding(value)
+      create unless @environment.has?(name)
+      @environment.push_binding(name, value)
+    end
+
+    def pop_binding
+      previous = @environment.pop_binding(name)
+      apply_value_destructor(previous) if @value_destructor
+      destroy if @environment.unbound?(name)
+    end
+
+  protected
+    def create
+      # I would prefer acceptability of the name to be checked in the
+      # class.build method, before other work is done. However, some
+      # acceptability is most cleanly checked when the variable is
+      # created, so I decided to do all checking here.
+      assert_acceptable_name
+      @environment.create(name)
+    end
+
+    def destroy
+      @environment.destroy(name)
+    end
+
+    def apply_value_destructor(value)
+      if @value_destructor.respond_to? :call
+        @value_destructor.call(value)
+      else
+        value.send(@value_destructor)
+      end
+    end
+
+    def assert_acceptable_name
+      subclass_responsibility
+    end
+
+    def Var.ensure_symbol(original_name)
+      original_name.to_s.intern
+    end
+  end
+
+                                                             ### FluidVar ###
+
+  # FluidVars are those accessed via "Fluid.varname". This subclass
+  # contains the code for adding those getters and setters.
+  class FluidVar < Var # :nodoc:
+
+    def FluidVar.build(*args)
+      new(*args)  # No subclasses to build specially.
+    end
+
+    def create
+      super
+      Fluid.create_getter(name)
+      Fluid.create_setter(name)
+    end
+
+    def destroy
+      super
+      Fluid.delete_getter(name)
+      Fluid.delete_setter(name)
+    end
+
+    def assert_acceptable_name
+      unless name.to_s =~ /^[a-z_]\w*$/
+        raise NameError, "'#{original_name}' is not a good fluid variable name. It can't be used as a method name."
+      end
+
+      if Fluid.methods.include?(name.to_s)
+        raise NameError, "'#{original_name}' cannot be a fluid variable. It's already a method of Fluid's."
+      end
+    end
+  end
+
+
+                                                           ### GlobalVar ###
+
+  # GlobalVars are the subclass that handles binding and unbinding of
+  # Ruby globals.
+  #
+  class GlobalVar < Var   # :nodoc:
+    def GlobalVar.build(original_name, environment, value_destructor)
+      new(original_name, environment, value_destructor)
+    end
+
+    # The original value of the global is, in effect, an outermost
+    # binding, one not created with Fluid.let. A binding has to be made
+    # here so that unbinding works on exit from the Fluid.let block. 
+    def create
+      super
+      push_binding(instance_eval("#{name.to_s}"))
+    end
+
+    # The environment really just holds values for unbinding.
+    # Access to the newly-bound variable within the Fluid.let block
+    # is through the global itself. So it needs to be set and reset
+    # by these methods.
+    def push_binding(value)
+      super
+      set_global
+    end
+
+    def pop_binding
+      super
+      set_global
+    end
+
+    def set_global
+      evalme = "#{name.to_s} = @environment.get(#{name.inspect})"
+      # puts evalme
+      instance_eval evalme
+    end
+
+    def assert_acceptable_name
+      if [:$!, :$stdin, :$stdout, :$stderr].include?(name)
+        raise NameError, 
+          "'#{name}' is not allowed in Fluid.let. It's too iffy to get it right."
+      end
+    end
+  end
+
+
+  # Puts the variable specifications in effect, then executes the block,
+  # undoes the variable specifications, and returns the block's value.
+  #
+  # The simplest form of variable specification is a variable name (symbol or string).
+  # In this case, the variable starts out with the value nil:
+  # 
+  #   Fluid.let(:will_have_value_nil) {...}
+  # 
+  # You can also specify the initial value of the variable:
+  #
+  #   Fluid.let(:will_have_value_1, 1) {...}
+  #
+  # Multiple variables can be specified in a single let. Each one must 
+  # be in an array, <i>even if given no value</i>:
+  # 
+  #  Fluid.let([:will_have_value_1, 1],
+  #            [:starts_as_nil]) {...}
+  # 
+  # 
+  # From the moment the block begins to execute until the moment it returns,
+  # getters and setters for the variables are made class methods of Fluid:
+  # 
+  #    Fluid.let(:var, 1) {
+  #      Fluid.var       # has value 1
+  #      Fluid.var = 2   # change value to 2
+  #    }
+  # 
+  # References to the variable needn't be in the lexical scope of the
+  # Fluid.let. They can be anywhere in the program. (To be more precise: 
+  # references can be made whenever the original Fluid.let is on the stack.)
+  # 
+  # When Fluid.let's block exits, the value of the variable is no longer accessible
+  # through Fluid.var. An attempt to access it will raise a NameError. 
+  # If, however, there's another Fluid.let binding the same name still on the 
+  # stack, that version's value is back in effect. For example:
+  #
+  #     Fluid.let(:var, 1) {            # Fluid.var => 1
+  #        Fluid.var = 2                # Fluid.var => 2
+  #        Fluid.let(:var, "hello") {   # Fluid.var => "hello"
+  #           Fluid.var *= 2            # Fluid.var => "hellohello"
+  #        }                            # Fluid.var => 2
+  #     }                               # Fluid.var => raises NameError
+  #
+  # Variable values are undone even if the block exits with a
+  # throw or an exception.
+  # 
+  # If a variable name begins with '$', Fluid.let realizes
+  # it's a global variable and gives that variable a new value. 
+  # No getters or setters are created. The old
+  # value is still restored when the block exits.
+  # 
+  #
+  # 
+  # === Destructors
+  #
+  # There may be an argument past the initial value, the <i>value destructor</i>. 
+  # It may be either a Proc or the name of a method. If it's the name of a method, 
+  # it's sent as a message to the value of the second argument. Like this:
+  #
+  #    Fluid.let(out, File.open("logfile", "w"), :close)
+  #
+  # (You wouldn't really do that, though, since File.open does the same 
+  # thing for you.)
+  #
+  # If the third argument is a block, it's called with the value of the 
+  # second argument as its single parameter.
+  # 
+  #  Fluid.let(:out, File.open("logfile", 'w'),
+  #            proc {|io| io.close}) {...}
+
+  def Fluid.let(*var_specs)
+    unwind_list = create_dynamic_context(var_specs)
+
+    begin
+      return yield if block_given?
+    ensure
+      unwind_dynamic_context unwind_list
+    end
+  end
+
+  #     A global declaration of a fluid variable. After executing this code:
+  # 
+  #       Fluid.defvar(:global, 5) 
+  # 
+  #     Fluid.global will normally everywhere have the value 5, unless it's
+  #     changed by assignment or Fluid.let.
+  # 
+  #     However, Fluid.defvar has effect only the first time it's executed.
+  #     That is, given this sequence:
+  # 
+  #       Fluid.defvar(:global, 5)
+  #       Fluid.defvar(:global, 6666666)
+  # 
+  #     Fluid.global has value 5. The second Fluid.defvar is ignored. 
+  #     The "a-bit-more-clever-fluid-tracing.rb" example shows how 
+  #     this can be useful.
+  # 
+  #     A Fluid.defvar executed while a Fluid.let block is in effect will
+  #     have no effect:
+  # 
+  #       Fluid.let(:not_global, 1) {
+  #         Fluid.defvar(:not_global, 5555)   # Fluid.not_global == 1
+  #       }
+  #       # The defvar has had no effect, so Fluid.not_global
+  #       # has no value after the block.
+  # 
+  #     Fluid.defvar can take a block as an argument:
+  # 
+  #       Fluid.defvar(:var) { long_and_expensive_computation }
+  # 
+  #     The block is only executed if its value would be assigned to the
+  #     variable.
+  # 
+  #     The first argument to Fluid.defvar may not be the name of 
+  #     a global variable. 
+
+  def Fluid.defvar(name, value = nil)
+    if Var.global?(name)
+      raise NameError, "Fluid.defvar of a global can never have an effect, so it's not allowed."
+    end
+
+    var = Var.build(name, @@environment)
+    unless @@environment.has?(var.name)
+      value = yield if block_given?
+      var.push_binding(value)
+    end
+  end
+
+  # Answers whether _name_ is already a fluid variable. 
+  def Fluid.has?(name)
+    return true if Var.global?(name)
+    @@environment.has?(Var.ensure_symbol(name))
+  end
+
+  def Fluid.method_missing(symbol, *args) # :nodoc:
+    symbol = symbol.to_s.gsub(/=/, '')
+    raise NameError, "'#{symbol}' has not been defined with Fluid.let or Fluid.defvar."
+  end
+
+private
+
+  def Fluid.create_dynamic_context(var_specs)
+    var_list = []
+    return var_list if var_specs.empty?
+    
+    var_specs = [var_specs] unless var_specs[0].is_a? Array
+
+    var_specs.each { |one_spec|
+      name = one_spec[0]
+      value = one_spec[1]
+      value_destructor = one_spec[2]
+
+      var = Var.build(name, @@environment, value_destructor)
+      assert_variable_name_is_not_duplicate(var.name, var_list)
+      var.push_binding(value)
+      var_list.push(var)
+    }
+    var_list
+  end
+
+  def Fluid.unwind_dynamic_context(var_list)
+    var_list.each { | var | var.pop_binding }
+  end
+
+  def Fluid.create_getter(var)
+    evalme = %Q{
+      def Fluid.#{var.to_s}
+        @@environment.get(#{var.inspect})
+      end
+    }
+    # puts evalme
+    class_eval evalme
+  end
+
+  def Fluid.create_setter(var)
+    evalme = %Q{
+      def Fluid.#{var.to_s}=(value)
+        @@environment.set(#{var.inspect}, value)
+      end
+    }
+    # puts evalme
+    class_eval evalme
+  end
+
+  def Fluid.delete_fluid_method(name)
+    evalme = %Q{
+      class << Fluid
+        remove_method(#{name.inspect})
+      end
+    }
+    #puts evalme
+    class_eval evalme
+  end
+
+  def Fluid.delete_getter(var)
+    delete_fluid_method(var)
+  end
+  def Fluid.delete_setter(var)
+    delete_fluid_method("#{var}=".intern)
+  end
+
+
+  def Fluid.assert_variable_name_is_not_duplicate(name_symbol,
+                                                  already_defined = [])
+    if already_defined.detect { | e | e.name == name_symbol }
+      raise NameError, "'#{name_symbol}' is defined twice in the same Fluid.let."
+    end
+  end
+end
+
+