facets 2.6.0 → 2.7.0

data/README.rdoc

@@ -7,23 +7,43 @@
 
 == Introduction
 
-Ruby Facets is the single largest collection of general purpose method extensions and system additions for the Ruby programming language.
+Ruby Facets is the single largest collection of general purpose method
+extensions and system additions for the Ruby programming language.
 
-The core extensions is a large collection of methods which extend the core capabilities of Ruby's built-in classes and modules. This collection of extension methods are unique by virtue of their atomicity. The methods are stored in relatively small groups of tightly coupled methods so that each can be required independently. This gives developers the potential for much finer control over which extra methods to bring into their code.
+The CORE extensions is a large collection of methods which extend the
+core capabilities of Ruby's built-in classes and modules. This collection
+of extension methods are unique by virtue of their atomicity. The methods
+are generally stored in individual files so that each can be required
+independently. This gives developers the potential for much finer control
+over which extra methods to bring into their code.
 
-The "more" additions are a collection of classes, modules and light meta-systems which constitutes an ever improving source of reusable components. Some very nice additions are provided, from the simple Functor class to a full-blown annotations system.
+The MORE additions are a collection of classes, modules and lightweight systems
+which constitute an ever improving source of reusable components. This set of
+libraries is kept light and focused on useful to a wide variety of usecases.
 
 
-== Documentation
+== Release Notes
 
-Facets has special documentation needs due to it's extensive bredth. The RDocs generated when installing via RubyGems, are unweildly because it combines all of Facets in one set of docs. Hopefully we can remedy this in the future. In the mean time the gem package includes better documentation --divided into three sections, in the doc/rdoc directory.
+Please see Facets Blog (http://facets.rubyforge.org).
 
-Online documentaiton is available at http://facets.rubyforge.org/learn.html. There is a "Quick Doc" feature that can be a bit more convenient then the usual RDocs. Prior to 2.3.1 off-line docs had to be downloaded via a separate package, but this is no longer the case. I've seen past the stigma of not including documentation along with the package itself (the extra 500K isn't even a floppy disk folks!), so you will find them in the doc/ directory of whatever package you have choosen to install. In fact, a good package installer should give you the option to install those in the appropriate place in your system (eg. in /usr/share/doc/facets/).
 
+== Documentation
 
-== Release Notes
+Facets has special documentation needs due to it's extensive bredth.
+The RDocs generated when installing via RubyGems, are unweildly because it
+combines all of Facets in one set of docs. Hopefully we can remedy this in
+the future. In the mean time the gem package includes better documentation
+--divided into two sections in the doc/rdoc directory.
 
-Please see the RELEASE file.
+Online documentaiton is available at http://facets.rubyforge.org/learn.html.
+There is a "Quick Doc" feature that can be a bit more convenient then the usual
+RDocs. Prior to 2.3.1 off-line docs had to be downloaded via a separate package,
+but this is no longer the case. I've seen past the stigma of not including
+documentation along with the package itself (the extra 500K isn't even a floppy
+disk folks!), so you will find them in the doc/ directory of whatever package
+you have choosen to install. In fact, a good package installer should give you
+the option to install those in the appropriate place in your system anyway
+(eg. in /usr/share/doc/facets/).
 
 
 == Installation
@@ -32,7 +52,8 @@ The easiest way to install is via RubyGems.
 
   $ gem install facets
 
-To install manually, your will need Ruby Setup (http::/setup.rubyforge.org). Then download and unpack the .tar.gz package and run:
+To install manually, your will need Ruby Setup (http::/setup.rubyforge.org).
+Then download and unpack the .tar.gz package and run:
 
   $ tar -xvzf facets-2.x.x.tar.gz
   $ cd facets-2.x.x
@@ -41,12 +62,19 @@ To install manually, your will need Ruby Setup (http::/setup.rubyforge.org). The
 
 == Compatibility with 1.x series.
 
-Prior to 2.0, Facets was divided between CORE and MORE --standalone extensions vs. classes and modules, respectively. With 2.0, the notion of "CORE" has taken on a slightly different meaning. Instead CORE now consists of the libraries that are thought essential and as such are loaded automatically when using ++require "facets"++. While still primarily made up of extension methods modules and classes may now belong to core as well.
+Prior to 2.0, Facets was divided between CORE and MORE --standalone extensions 
+vs. classes and modules, respectively. With 2.0, the notion of "CORE" has taken
+on a slightly different meaning. Instead CORE now consists of the libraries that
+are thought "essential" and as such are loaded automatically when using 
+++require "facets"++. While still primarily made up of extension methods, some 
+modules and classes may now belong to core as well.
 
 
 == Mission
 
-Facets holds to the notion that the more we can reasonably integrate into a common foundation directed toward general needs, the better that foundation will be able to serve everyone. There are a number of advantages here:
+Facets holds to the notion that the more we can reasonably integrate into
+a common foundation, directed toward general needs, the better that foundation
+will be able to serve the community. There are a number of advantages here:
 
     * Better Code-reuse
     * Collaborative Improvements
@@ -56,48 +84,64 @@ Facets holds to the notion that the more we can reasonably integrate into a comm
 
 == Usage
 
-For information in usage, please see the special README for the specific set of libraries:
+For information in usage, please see the special README for the specific
+set of libraries:
 
-  README.core     Core extensions
-  README.lore     Standard extensions
-  README.more     Additions
+  README.core     Core Extensions
+  README.more     Standard Extensions & Additions
 
 General usage of the CORE library is provided via:
 
   require 'facets'
 
-This is the recommended usage. However, you can also "cherry pick" core methods. While there are exceptions the rule of thumb for loading a core method is:
+This is the recommended usage. However, you can also "cherry pick" core
+methods. While there are exceptions the rule of thumb for loading a core
+method is:
 
   require 'facets/{class|module}/{method}'
 
 See README.core for more information.
 
-Using the Facets/MORE library of modules, classes or microframeworks is essentially the same. For example:
+Using the Facets/MORE library of modules, classes or microframeworks is
+essentially the same. For example:
 
   require 'facets/basicobject'
 
-Again, for details pertaining to the functionality of each feature, please see the API Docs.
+Again, for details pertaining to the functionality of each feature, please see
+the API Docs.
 
 
 == Contribute
 
 This project thrives on contribution.
 
-If you have any extension methods, classes, modules or small frameworks that you think have general applicability and would like to see them included in this project, don't hesitiate to submit. Also, if you have better versions of any thing already included or simply have a patch, they are more than welcome. We want Ruby Facets to be of the highest quality.
+If you have any extension methods, classes, modules or small frameworks that
+you think have general applicability and would like to see them included in
+this project, don't hesitiate to submit. Also, if you have better versions
+of any thing already included or simply have a patch, they are more than
+welcome. We want Ruby Facets to be of the highest quality.
 
 
 == Authors
 
-This collection was put together by, and largely written by Thomas Sawyer (aka Trans). He can be reached via email at transfire at gmail.com.
+This collection was put together by, and largely written by Thomas Sawyer
+(aka Trans). He can be reached via email at transfire at gmail.com.
 
-Some parts of this collection were written and/or inspired by other persons. Fortunately nearly all were copyrighted under the same open license, the Ruby License. In the few exceptions I have included the copyright notice with the source code.
+Some parts of this collection were written and/or inspired by other persons.
+Fortunately nearly all were copyrighted under the same open license, the Ruby
+License. In the few exceptions I have included the copyright notice with the
+source code.
 
 Any code file not specifically labeled shall fall under the Ruby License.
 
-In all cases, I have made every effort to give credit where credit is due. You will find these copyrights, thanks and acknowledgments embedded in the source code. You can see them in "CREDIT:" lines or as file-base "Author(s)" sections given in the RDocs. 
+In all cases, I have made every effort to give credit where credit is due.
+You will find these copyrights, thanks and acknowledgments embedded in the
+source code. You can see them in "CREDIT:" lines or as file-base "Author(s)"
+sections given in the RDocs. 
 
 Also see the AUTHORS file for a list of all contributing Rubyists.
-If anyone is missing from the list, please let me know and I will correct right away. Thanks.
+If anyone is missing from the list, please let me know and I will correct
+right away. Thanks.
 
 
 == License
@@ -109,9 +153,13 @@ The collection PER COLLECTION is licensed as follows:
 
   Distributed under the terms of the Ruby license.
 
-The Ruby license is a dual license that also provides for use of the GPL. Complete texts of both licenses accompany this document (see LICENSE).
+The Ruby license is a dual license that also provides for use of the GPL.
+Complete texts of both licenses accompany this document (see LICENSE).
 
-Acknowledgments and Copyrights for particular snippets of borrowed code are given in their respective source. All licenses are either compatible with the Ruby license (namely the GPL) or the original author has given permission for inclusion of their code under such license.
+Acknowledgments and Copyrights for particular snippets of borrowed code
+are given in their respective source. All licenses are either compatible
+with the Ruby license (namely the GPL) or the original author has given
+permission for inclusion of their code under such license.
 
 
 Ruby Facets, Copyright (c)2005,2006,2007,2008 Thomas Sawyer / Tiger Ops

data/Rakefile

@@ -1,4 +1,247 @@
-Dir['task/**/*.rake'].each do |lib|
-  load(lib)
+#!/usr/bin/env ruby
+
+require 'fileutils'
+
+#
+# CORE TEST COVERAGE
+# ----------------------------------------------------------------------------
+
+desc "show core unit test coverage"
+
+task 'coverage' do
+  core_scripts = []
+  cd 'lib/core/facets' do
+    core_scripts = Dir['**/*'].reject{ |s| File.directory?(s) }
+  end
+
+  core_tests = []
+  cd 'test/core' do
+    core_tests = Dir['**/*']
+  end
+
+  core_tests = core_tests.collect do |t|
+    dir, fname = *File.split(t)
+    File.join(dir, fname.sub(/^test_/,''))
+  end
+
+  diff = core_scripts - core_tests
+
+  # remove core collectives
+  diff = diff - %w{
+    array.rb binding.rb cattr.rb class.rb comparable.rb dir.rb
+    enumerable.rb exception.rb hash.rb file.rb filetest.rb float.rb
+    integer.rb kernel.rb matchdata.rb module.rb nilclass.rb
+    numeric.rb proc.rb range.rb regexp.rb string.rb symbol.rb
+    time.rb unboundmethod.rb
+  }
+
+  puts diff.sort.join("\n")
+  puts
+  puts "#{diff.size} files uncovered."
+
+end
+
+
+#
+# GENERATE RDOCS
+# ----------------------------------------------------------------------------
+
+desc "generate rdocs"
+
+task "rdoc" do
+  TEMPLATE  = ENV['RDOC_TEMPLATE'] || 'html'
+  APIOUT    = "doc/rdoc"
+
+  FileUtils.rm_r(APIOUT)
+
+  system "rdoc -a -S -t'Facets Core API' -T #{TEMPLATE} -m README --op '#{APIOUT}/core' README lib/facets/core"
+  #system "rdoc -a -S -t'Facets Lore API' -T #{TEMPLATE} -m README --op '#{APIOUT}/lore' README lib/facets/lore"
+  system "rdoc -a -S -t'Facets More API' -T #{TEMPLATE} -m README --op '#{APIOUT}/more' README lib/facets/more"
+end
+
+#
+# RUN TESTS
+# ----------------------------------------------------------------------------
+
+task 'test' do
+  prepare_tests_all
+end
+
+desc "run all unit tests"
+task 'test:all' do
+  prepare_tests_all
+end
+
+desc "run core unit tests"
+task 'test:core' do
+  prepare_tests_core
+end
+
+#desc "run lore unit tests"
+#task 'test:lore' do
+#  prepare_tests_lore
+#end
+
+desc "run more unit tests"
+task 'test:more' do
+  prepare_tests_more
+end
+
+desc "run all unit tests with ActiveSupport loaded"
+task 'test:all:activesupport' => [:include_activesupport, 'test:all']
+
+desc "run core unit tests with ActiveSupport loaded"
+task 'test:core:activesupport' => [:include_activesupport, 'test:core']
+
+#desc "run lore unit tests with ActiveSupport loaded"
+#task 'test:lore:activesupport' => [:include_activesupport, 'test:lore']
+
+desc "run more unit tests with ActiveSupport loaded"
+task 'test:more:activesupport' => [:include_activesupport, 'test:more']
+
+task 'include_activesupport' do
+  require 'activesupport'
+end
+
+def add_loadpath(*paths)
+  live = ENV['live']
+
+  unless live
+    # $LOAD_PATH.unshift(File.expand_path('lib/core'))
+    # $LOAD_PATH.unshift(File.expand_path('lib/lore'))
+    # $LOAD_PATH.unshift(File.expand_path('lib/more'))
+    paths.each do |path|
+      $LOAD_PATH.unshift(File.expand_path(path))
+    end
+  end
+
+  puts "RUBY VERSION: #{RUBY_VERSION}"
+  puts "LOAD PATH:\n" + $LOAD_PATH.join("\n")
+end
+
+def get_tests(which="{c,l,m}ore")
+  if find = ARGV[1..-1].select{|e| e !~ /(^[-]|[=])/ }[0]
+    unless FileTest.file?(find)
+      #find = File.join(find, '**', 'test_*.rb')
+      find = ['test/test_*.rb']
+      find << File.join(find, which, '**', 'test_*.rb')
+    end
+  else
+    #find = 'test/**/test_*.rb'
+    find = ['test/test_*.rb']
+    find << "test/#{which}/**/test_*.rb"
+  end
+
+  Dir.glob(find)
+end
+
+def run_tests(files)
+  files.each do |file|
+    next if File.directory?(file)
+    begin
+      puts "Loading: #{file}" if $DEBUG
+      load(file)
+    rescue LoadError
+      puts "Error loading: #{file}"
+    end
+  end
+end
+
+def prepare_tests_all
+  add_loadpath('lib/core','lib/lore','lib/more')
+  files = get_tests
+  run_tests(files)
+end
+
+def prepare_tests_core
+  add_loadpath('lib/core')
+  files = get_tests('core')
+  run_tests(files)
+end
+
+def prepare_tests_lore
+  add_loadpath('lib/lore')
+  files = get_tests('lore')
+  run_tests(files)
+end
+
+def prepare_tests_more
+  add_loadpath('lib/more')
+  files = get_tests('more')
+  run_tests(files)
 end
 
+#def run_tests
+#  live = ENV['live']
+#
+#  unless live
+#    $LOAD_PATH.unshift(File.expand_path('lib/core'))
+#    $LOAD_PATH.unshift(File.expand_path('lib/lore'))
+#    $LOAD_PATH.unshift(File.expand_path('lib/more'))
+#  end
+#
+#  puts "RUBY VERSION: #{RUBY_VERSION}"
+#  puts "LOAD PATH:\n" + $LOAD_PATH.join("\n")
+#
+#  if find = ARGV[1..-1].select{|e| e !~ /(^[-]|[=])/ }[0]
+#    unless FileTest.file?(find)
+#      find = File.join(find, '**', 'test_*.rb')
+#    end
+#  else
+#    find = 'test/**/test_*.rb'
+#  end
+#
+#  files = Dir.glob(find)
+#
+#  files.each do |file|
+#    next if File.directory?(file)
+#    begin
+#      puts "Loading: #{file}" if $DEBUG
+#      load(file)
+#    rescue LoadError
+#      puts "Error loading: #{file}"
+#    end
+#  end
+#end
+
+#
+# SETUP/INSTALL
+# ----------------------------------------------------------------------------
+
+def load_setup
+  begin
+    require 'setup'
+    $setup_installed = true
+  rescue LoadError
+    $setup_installed = false
+    puts "NOTP"
+  end
+end
+
+private :load_setup
+
+desc "install to ruby site location"
+task :install do
+  load_setup
+
+  if $setup_installed
+    sh "setup.rb all"
+  else
+    puts "Requires stand-alone Setup.rb."
+    puts "See http://setup.rubyforge.org"
+    puts "or 'gem install setup'."
+  end
+end
+
+desc "uninstall from ruby site location"
+task :uninstall do
+  load_setup
+
+  if $setup_installed
+    sh "setup.rb uninstall"
+  else
+    puts "Requires stand-alone Setup.rb."
+    puts "See http://setup.rubyforge.org"
+    puts "or 'gem install setup'."
+  end
+end

data/TODO

@@ -0,0 +1,5 @@
+= TODO List
+
+* generate phase should be in site pipeline.
+
+

data/demo/hook.rd

@@ -0,0 +1,47 @@
+= Hook Library
+
+Require the hook.rb library.
+
+  require 'facets/hook'
+
+Build a class with signals.
+
+  class X
+    include Hook
+
+    def course
+      @course ||= []
+    end
+
+    hook :signal
+
+    def boom(event, message)
+      course << "Kaboom!"
+    end
+
+    signal do |event, message|
+      course << ["1", event, message]
+    end
+
+    signal do |event, message|
+      course << ["2", event, message]
+    end
+
+    signal :boom
+
+  end
+
+Triger the signal.
+
+  x = X.new
+  x.signal("hi")
+
+The hooks should have been fired.
+
+  x.course[0].should == ["1", :signal, "hi"]
+  x.course[1].should == ["2", :signal, "hi"]
+  x.course[2].should == "Kaboom!"
+  x.course[3].should == nil
+  
+QED.
+