facets 2.8.4 → 2.9.0.pre.1

data/NOTICE

@@ -0,0 +1,27 @@
+= COPYRIGHT NOTICES
+
+== String#natcmp
+
+String#natcmp is based on Martin Pool's "Natural Order String Comparison"
+originally written in C. (see http://sourcefrog.net/projects/natsort/)
+
+This implementation is Copyright (C) 2003 by Alan Davies
+<cs96and_AT_yahoo_DOT_co_DOT_uk>
+
+This software is provided 'as-is', without any express or implied
+warranty.  In no event will the authors be held liable for any damages
+arising from the use of this software.
+
+Permission is granted to anyone to use this software for any purpose,
+including commercial applications, and to alter it and redistribute it
+freely, subject to the following restrictions:
+
+1. The origin of this software must not be misrepresented; you must not
+   claim that you wrote the original software. If you use this software
+   in a product, an acknowledgment in the product documentation would be
+   appreciated but is not required.
+2. Altered source versions must be plainly marked as such, and must not be
+   misrepresented as being the original software.
+3. This notice may not be removed or altered from any source distribution.
+
+

data/README.rdoc

@@ -1,51 +1,50 @@
 = Ruby Facets
 
-* home: http://facets.rubyforge.com
-* source: http://github.com/rubyworks/facets
-* forum: http://groups.google.com/group/facets-universal
+* home: http://rubyworks.github.com/facets
+* code: http://github.com/rubyworks/facets
+* talk: http://groups.google.com/group/facets-universal
 
 "ALL YOUR BASE ARE BELONG TO RUBY"
 
 
 == 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 premiere collection of general purpose method
+extensions and standard 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 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.
+Facets houses the largest single collection of methods available for
+extending 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 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 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.
+In addition Facets provides a collection of extensions to Ruby standard library
+plus a small collection of add-on classes and modules. Together these
+libraries constitute an ever improving source of reusable components, suitable
+to a wide variety of usecases.
 
 
-== Release Notes
+== Resources
 
-Please see Facets Blog (http://facets.rubyforge.org).
+* Homepage: http://rubyworks.github.com/facets
+* Report Bugs: http://github.com/rubyworks/facets/issues
+* Mailing List: http://groups.google.com/group/facets-universal/topics
+* Wiki Pages: http://wiki.github.com/rubyworks/facets
+* Source Code: http://github.com/rubyworks/facets
 
 
 == Documentation
 
 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.
-
-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/).
+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 better organized online documentation 
+is available at http://rubyworks.github.com/facets/learn.html.
+
+* Core API: http://rubyworks/github.com/facets/doc/api/core/index.html
+* More API: http://rubyworks/github.com/facets/doc/api/more/index.html
+* Tour API: http://rubyworks/github.com/facets/doc/api/tour/index.html
 
 
 == Installation
@@ -61,15 +60,7 @@ Then download and unpack the .tar.gz package and run:
   $ cd facets-2.x.x
   $ sudo setup.rb
 
-
-== Compatibility w/ 1.x
-
-Prior to 2.0, Facets was divided between CORE and MORE --core 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.
+Facets 2.8+ requires Ruby 1.8.7 or higher.
 
 
 == Mission
@@ -86,23 +77,115 @@ will be able to serve the community. There are a number of advantages here:
 
 == Usage
 
-For information in usage, please see the special README for the specific
-set of libraries:
+=== CORE Library
+
+At the heart of Ruby Facets is the CORE extensions library. CORE provides
+a sizable collection of generally useful methods, along with a few supporting
+classes, that extend the functionality of Ruby's core classes and modules.
 
-  README.core     Core Extensions
-  README.more     Standard Extensions & Additions
+By definition CORE contains anything that will load automatically when
+issuing:
 
-General usage of the CORE library is provided via:
+  require 'facets'
+
+If you plan to use more then a few of Facets core method it is recommended that
+you require the main facility.
 
   require 'facets'
 
+This loads all the CORE functionality at once.
+
+Of course you can use the CORE library piecemeal if you prefer. The general
+require statement for a core extensions library is:
+
+  require 'facets/<class|module>/<method-lib>'
+
+For example:
+
+  require 'facets/time/stamp'
+
+Most "atoms" contain only one method, but a few exceptions occur when methods
+are closely tied together.
+
+You can load per-class or per-module groups of core methods by requiring the
+class or module by name. For example"
+
+  require 'facets/time'
+
+Will require all the core Time method extensions.
+
+Note that some methods that were part of CORE in 1.8 and earlier are now part
+of MORE libraries. A good example is 'random.rb'. There were separated because
+they had more specialized use cases, where as CORE extensions are intended as
+general purpose.
+
 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.
+==== Method File Names
+
+Operator method redirect files are stored using English names. For instance for
+Proc#* is 'proc/op_mul'.
+
+For reference, here is the chart.
+
+     +@   => op_plus
+     -@   => op_minus
+     +    => op_add
+     -    => op_sub
+     **   => op_pow
+     *    => op_mul
+     /    => op_div
+     %    => op_mod
+     ~    => op_tilde
+     <=>  => op_cmp
+     <<   => op_lshift
+     >>   => op_rshift
+     <    => op_lt
+     >    => op_gt
+     ===  => op_case
+     ==   => op_equal
+     =~   => op_apply
+     <=   => op_lt_eq
+     >=   => op_gt_eq
+     |    => op_or
+     &    => op_and
+     ^    => op_xor
+     []=  => op_store
+     []   => op_fetch
+
+Facets simply takes the '*' and translates it into a string acceptable to all
+file systems. Also, if a method ends in '=', '?' or '!' it is simply removed.
+
+
+=== MORE Library
+
+On top of the extensive Core library, Facet provides a small collection
+of additional modules and classes, as well as extended versions of
+modules and classes in Ruby's Standard library.
+
+Use the More library like you would any other 3rd party library.
+The only difference between Facets More library and other libraries
+is the lack of any enclosing @Facets::@ namespace. This is becuase
+the libraries provided by Facets are considerd fairly low-level.
+
+When using Facets' extended versions of Ruby's standard libraries,
+the More libraries have to loaded manually, of course. However you
+do not need to load Ruby's library first, as the Facets' library
+will do that automatically.
+
+For example, normally one load Ruby's OpenStruct class via:
+
+  require 'ostruct'
+
+To load 'ostruct.rb' plus Facets extensions for it simply use:
+
+  require 'facets/ostruct'
+
+instead.
 
 Using the Facets/MORE library of modules, classes or microframeworks is
 essentially the same. For example:
@@ -151,7 +234,7 @@ right away. Thanks.
 The collection PER COLLECTION is licensed as follows:
 
   Ruby Facets
-  Copyright (c) 2004-2006 Thomas Sawyer
+  Copyright (c) 2004,2010 Thomas Sawyer
 
   Distributed under the terms of the Ruby license.
 
@@ -164,9 +247,8 @@ 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
+"ALL YOUR BASE ARE BELONG TO RUBY!"
 
-ALL YOUR BASE ARE BELONG TO RUBY!
+Ruby Facets, Copyright (c)2005,2006,2007,2008,2009,2010 Thomas Sawyer
 
 Do you Ruby? (http://ruby-lang.org)
-

data/Rakefile

@@ -2,46 +2,6 @@
 
 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
 # ----------------------------------------------------------------------------
@@ -50,39 +10,49 @@ desc "generate rdocs"
 
 task "rdoc" do
   TEMPLATE  = ENV['RDOC_TEMPLATE'] || 'html'
-  APIOUT    = "doc/rdoc"
+  APIOUT    = "site/doc/api"
 
   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 More API' -T #{TEMPLATE} -m README --op '#{APIOUT}/more' README lib/facets/more"
+  system "rdoc -a -S -t'Facets Core API' -T #{TEMPLATE} -m README.rdoc --op '#{APIOUT}/core' README.rdoc lib/facets/core"
+  system "rdoc -a -S -t'Facets More API' -T #{TEMPLATE} -m README.rdoc --op '#{APIOUT}/more' README.rdoc lib/facets/more"
+  system "rdoc -a -S -t'Facets Tour API' -T #{TEMPLATE} -m README.rdoc --op '#{APIOUT}/tour' README.rdoc lib/facets/tour"
 end
 
 #
-# RUN TESTS
+# RUN TESTS (requires Lemon)
 # ----------------------------------------------------------------------------
 
-task 'default' do
-  prepare_tests_all
+task "default" do
+  sh "lemon #{lemon_flags} -Ilib/core:lib/more:lib/tour test/core test/more test/tour"
 end
 
-task 'test' do
-  prepare_tests_all
+task "test" do
+  if tests = ENV['TESTS']
+    sh "lemon #{lemon_flags} -Ilib/core:lib/more:lib/tour #{tests}"
+  else
+    sh "lemon #{lemon_flags} -Ilib/core:lib/more:lib/tour test/core test/more test/tour"
+  end
 end
 
 desc "run all unit tests"
-task 'test:all' do
-  prepare_tests_all
+task "test:all" do
+  sh "lemon #{lemon_flags} -Ilib/core:lib/more:lib/tour test/core test/more test/tour"
 end
 
 desc "run core unit tests"
-task 'test:core' do
-  prepare_tests_core
+task "test:core" do
+  sh "lemon#{lemon_flags}  -Ilib/core test/core"
 end
 
 desc "run more unit tests"
-task 'test:more' do
-  prepare_tests_more
+task "test:more" do
+  sh "lemon #{lemon_flags} -Ilib/core:lib/more test/more"
+end
+
+desc "run tour unit tests"
+task "test:tour" do
+  sh "lemon #{lemon_flags} -Ilib/core:lib/tour test/tour"
 end
 
 desc "run all unit tests with ActiveSupport loaded"
@@ -94,60 +64,65 @@ task 'test:core:activesupport' => [:include_activesupport, 'test:core']
 desc "run more unit tests with ActiveSupport loaded"
 task 'test:more:activesupport' => [:include_activesupport, 'test:more']
 
+desc "run tour unit tests with ActiveSupport loaded"
+task 'test:more:activesupport' => [:include_activesupport, 'test:tour']
+
 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/more'))
-    paths.each do |path|
-      $LOAD_PATH.unshift(File.expand_path(path))
-    end
+def lemon_flags
+  flags = []
+  if ENV['verbose']
+    flags << '-v'
   end
-
-  puts "RUBY VERSION: #{RUBY_VERSION}"
-  puts "LOAD PATH:\n" + $LOAD_PATH.join("\n") if $DEBUG
+  flags.join(' ')
 end
 
-def get_tests(find=nil)
-  find = find && File.directory?(find) ? File.join(find, '**/test_*.rb') : find
-  find = find || ENV['TESTS'] || 'test/**/test_*.rb'
-  Dir.glob(find)
-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/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") if $DEBUG
+#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 get_tests(find=nil)
+#  find = find && File.directory?(find) ? File.join(find, '**/test_*.rb') : find
+#  find = find || ENV['TESTS'] || 'test/**/test_*.rb'
+#  Dir.glob(find)
+#end
 
-def prepare_tests_all
-  add_loadpath('lib/core','lib/more')
-  files = get_tests
-  run_tests(files)
-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_core
-  add_loadpath('lib/core')
-  files = get_tests('test/core')
-  run_tests(files)
-end
+#def prepare_tests_all
+#  add_loadpath('lib/core','lib/more', 'lib/tour')
+#  files = get_tests
+#  run_tests(files)
+#end
 
-def prepare_tests_more
-  add_loadpath('lib/more')
-  files = get_tests('test/more')
-  run_tests(files)
-end
+#def prepare_tests(type)
+#  add_loadpath("lib/#{type}")
+#  files = get_tests('test/#{type}')
+#  run_tests(files)
+#end
 
 #def run_tests
 #  live = ENV['live']
@@ -181,6 +156,124 @@ end
 #  end
 #end
 
+
+#
+# TEST COVERAGE
+# ----------------------------------------------------------------------------
+
+desc "show test coverage"
+task "cov" do
+  sh "lemon -Ilib/core:lib/more:lib/tour -c test/core test/more test/tour"
+end
+
+desc "show core test coverage"
+task "cov:core" do
+  sh "lemon -Ilib/core -c test/core"
+end
+
+desc "show more test coverage"
+task "cov:more" do
+  sh "lemon -Ilib/more -c test/more"
+end
+
+desc "show tour test coverage"
+task "cov:tour" do
+  sh "lemon -Ilib/tour -c test/tour"
+end
+
+desc "show core coverage by file name"
+task 'cov:file:core' do
+  core_scripts = Dir['lib/core/facets/**/*.rb'].reject{ |s| File.directory?(s) }
+  core_tests   = Dir['test/core/**/*.rb']
+
+  core_scripts = core_scripts.map do |f|
+    md = /lib\/core\/facets\/(.*?)$/.match(f)
+    md[1]
+  end
+
+  core_tests = core_tests.map do |f|
+    md = /test\/core\/(.*?)$/.match(f)
+    md[1].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 method.rb module.rb nilclass.rb
+    numeric.rb object.rb proc.rb process.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
+
+
+#
+# QED
+# ----------------------------------------------------------------------------
+
+desc "run qed docs"
+task 'qed' do
+  sh "qed #{qed_flags} -Ilib/core:lib/more:lib/tour qed/core qed/more qed/tour"
+end
+
+desc "run core qed docs"
+task 'qed:core' do
+  sh "qed #{qed_flags} -Ilib/core qed/core"
+end
+
+desc "run more qed docs"
+task 'qed:more' do
+  sh "qed #{qed_flags} -Ilib/core:lib/more qed/more"
+end
+
+desc "run tour qed docs"
+task 'qed:tour' do
+  sh "qed #{qed_flags} -Ilib/core:lib/tour qed/tour"
+end
+
+desc "run core qed docs"
+task 'qed:code' do
+  sh "qed #{qed_flags} -c -Ilib/core lib/core"
+end
+
+def qed_flags
+  flags = []
+  if ENV['verbose']
+    flags << '-v'
+  end
+  flags.join(' ')
+end
+
+
+#
+# Extension Clashes
+#-----------------------------------------------------------------------------
+
+# TODO: need to fork each lookup via a seprate process to get a clean picture
+
+desc "print method clashes with ActiveSupport"
+task 'clash:as' do
+  #require 'lemon/model/snapshot'
+  #snap1 = Snapshot.new
+  #$LOAD_PATH.unshift('lib/core')
+  #$LOAD_PATH.unshift('lib/more')
+  #$LOAD_PATH.unshift('lib/tour')
+  #require 'facets' # 'facets/all'
+  #snap2 = Snapshot.new
+end
+
+desc "print method clashes with Ruby"
+task 'clash:ruby' do
+  require 'lemon/model/snapshot'
+end
+
+
 #
 # SETUP/INSTALL
 # ----------------------------------------------------------------------------