facets 1.0.2 → 1.0.3

data/packages/core/ProjectInfo

@@ -0,0 +1,39 @@
+--- %YAML:1.0
+
+TITLE    : Facets Core
+NAME     : facets_core
+VERSION  : '1.0.3'
+DATE     : '2006-02-10'
+STATUS   : Beta/Stable
+
+AUTHOR   : Thomas Sawyer
+EMAIL    : &email transfire@gmail.com
+HOMEPAGE : "http://facets.rubyforge.org"
+
+SUMMARY: Vast collection of atomic core extension methods.
+
+DESCRIPTION: >
+  Facets Core is a large collection of core extension methods for
+  the Ruby programming language. The extensions are unique by virtue
+  of thier atomicity. Methods are stored in their own files,
+  allowing for highly granular control of requirements, for
+  this reason I like to call it Ruby's Atomic Library.
+
+DISTRIBUTE: [ gem, tar.bz2 ]
+
+PACKAGE:
+  exclude:
+    - dev
+
+RUBYFORGE:
+  PROJECT: 'facets'
+  USERNAME: transami
+
+RDOC:
+  dir: ../website/doc/api/core
+  template: jamis
+  options: ['--all', '--inline-source']
+  include:
+    - 'lib/facet/**/*'
+    - '[A-Z]*'
+

data/packages/core/README

@@ -0,0 +1,252 @@
+
+= Ruby Facets
+
+  "ALL BASE COMMON"
+
+
+== Introduction
+
+Ruby Facets is a vast collection of methods which extend the core
+capabilities of Ruby's built-in classes and modules PLUS a large
+collection of additional modules, classes and microframeworks.
+The goal of the project is to offer large set of high-quality
+programming "parts" that target a variety of usecases.
+
+The collection of extension methods is unique by virtue of its atomicity. 
+The methods are stored individually so that each can be required
+independently. This gives developers fine-grain control over which 
+extra methods to bring into his or her code. The collection currently 
+contains over 400 methods spanning 28 classes and modules.
+
+The class, module and microframework additions consitute an ever growing
+and improving source of reusable components. Some very nice addations
+havve recently been added, from an amazing Units system to an elegant 
+annotations systems. And of course there are all the more typical goodies
+like Tuple, Functor and Multiton.
+
+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 us. There are a number of advantages here:
+
+    * Better Code-reuse
+    * Collaborative Improvements
+    * Greater Name Consistency
+    * One-stop Shop and Installation
+
+
+== Status
+
+The current status is quite good. While various parts are still considered
+Beta, everything should be relatively usable.
+
+
+== Installation
+
+
+The easiest way to install is via RubyGems. On the command line enter:
+
+  > gem install facets
+
+To manually install, unpack the .tbz (.tar.bz2) package and use the included
+setup.rb script. For example:
+
+  > tar -xvzf facets,YYYY-MM-DD.tbz
+  > cd facets,YYYY-MM-DD
+  > sudo ruby setup.rb
+
+
+== Usage
+
+For detailed usage of any given method or module please refer to the
+API RDocs. Most are well documented.
+
+To use a facet you simply require the method by name, for example:
+
+  require 'facet/time/stamp'
+
+Although not neccessary it is recommended that before requiring
+any other facet you first require the main facility.
+
+  require 'facets'
+
+This loads all the core facets considered "base" (a couple dozen common methods)
+and the Facets system module. The Facets module provides meta information about
+the facets available.
+
+Some extension method sets are also available. For example:
+
+  require 'facet/string_as_array'
+
+The most extensive of these is 'all'. The 'all' set requires nearly every
+Facets extension method there is. The only methods NOT required are those
+considered "cautionary" in the way they effect Ruby b/c they may potentially
+disrupt pre-existing code. Note that 'all' is not the recommended way to 
+use Facets and is only provided with a priviso of caution --that's alot
+of methods!
+
+More useful sets include, 'random' which loads every facet method related to
+randomness and 'inflect' which loads a number of methods for manipulating
+strings in high-level ways, like #camelize and #pluralize.
+
+The rest of Facets, the modules, classses and microframeworks are
+requirable through the traditional interface as well. For example:
+
+  require 'facet/units'
+
+Facets also includes an alternative way to use classes and modules.
+By calling the #autorequire method, Facets will automatically
+require the appropriate files when you first attempt to use one.
+For example:
+
+  require 'facets'
+
+  Facets.autorequire
+
+  t = Tuple[1,2,3]
+
+And the 'tuple.rb' file will be automatically required. The auto-requiring
+also handily applies to some of Ruby's standard library. 
+Keep in mind though that the microframeworks do not generally work with this,
+since they are not typical bound to a particular module or class, 
+so those will have to be required on their own.
+
+Please see the API Docs for details pertaining to the functionality
+of each feature.
+
+== Developer Notes
+
+=== Directories
+
+There are presently three subdirs in Facets: 'nano', which stores
+the method extensions, 'mega' which store the modules, classes and
+micorframeworks, and 'unit' which stores development utilities.
+
+The layout of Facets' method files is straightfoward and well organized.
+All individual methods are stored in subdirectories under their effected 
+downcased class' or module's name.
+
+  '<class|module>/<method-name>'
+
+Class method are stored in the same manner but under a 'self' subdirectory.
+
+  '<class|module>/self/<method-name>'
+
+=== Method File Names
+
+Operators are stored in the file system using english names. For instance for
+Proc#* is 'proc/op_mul'.
+
+For reference, here is the chart.
+
+     +@   => op_plus_self
+     -@   => op_minus_self
+     +    => op_plus
+     -    => op_minus
+     **   => op_pow
+     *    => op_mul
+     /    => op_div
+     %    => op_mod
+     ~    => op_tilde
+     <=>  => op_cmp
+     <<   => op_lshift
+     >>   => op_rshift
+     <    => op_lt
+     >    => op_gt
+     ===  => op_case_eq
+     ==   => 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.
+
+== Contribute
+
+This project thrives on contribution. 
+
+If you have any extension methods, classes, modules or microframeworks
+that you think have general applicability and would like to see them 
+included in this project, don't hesitiate to submit. There's a very good
+chance it will be included.  Also, if you have better versions of any thing
+already included or simply have a patch, they too are more than welcome.
+We want Ruby Facets to be of the highest quality.
+
+
+== Authorship
+
+This collection was put together by, and largely written by Thomas Sawyer
+(aka Trans Onoma). 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 excpetions I have included the
+copyright notice with the source code. 
+
+Any code file not specifically labelled 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 acknowledgements embedded in the source code, and an unobtrusive
+"Author(s)" section is given in the RDocs.
+
+Main Developers include:
+
+* Thomas Sawyer
+* George Moschovitis
+* Peter Vanbroekhoven
+* Florian Gross
+
+See the AUTHORS file for a list of all other contributing Rubyists.
+
+If anyone is missing from the list, please let me know and 
+I will correct right away. Thanks.
+
+
+== License
+
+In so far as it matters, the collection PER COLLECTION is licensed 
+as follows:
+
+  Ruby Facets
+  Copyright (c) 2004,2005 Thomas Sawyer
+  Ruby License
+
+The Ruby license is a dual license that also provides for use of the GPL.
+A copy of both licenses accompany this document (see COPYING).
+
+Fortunately nearly all the code is copyrighted under the same open license,
+namely the Ruby License. But some of the code is licensed differently 
+according to the original authors wishes. In the few excpetions I have
+included the copyright notice with the source code. All such licesnses are
+OOS licesnes. I am in the proccess of asking the particular authors to consider
+allowing the use of the single Ruby license so that one license can 
+serve for all. (UPDATE: Not very much left under seperate licenses.)
+
+Any code file not specifically labelled shall fall under the Ruby License.
+
+
+== Pitch
+
+  ALL YOUR BASE ARE BELONG TO RUBY
+
+
+----
+
+[1] A lot of mental anguish went into finding a good title Ruby Facets.
+    Of course, in the end only one name can take the honor. Other good names which were 
+    considered: Warchest w/ Atomix, Downs & Ace, Trix & Atomx and even Pillbox & Pills
+    (a _why suggestion).  Then the names that almost won out and were used for a good while:
+    Nano Methods and Mega Modules --great names but turned maybe a little to "fad".
+    Finally let's not forget even older "working" titles that were used along the way:
+    Raspberry, ABC, Succ and the very original Tomslib.
+
+# Copyright (c)2005 Thomas Sawyer 
+# --.com : The web page without a name.
+# (ruby-lang.org) Do you Ruby?
+
+

data/packages/core/Rakefile

@@ -0,0 +1,175 @@
+#!/usr/bin/env ruby
+
+# $:.unshift('lib')
+
+#require 'uri'
+require 'yaml'
+require 'fileutils'
+
+require './lib/facet/file/self/read_list'
+
+#VERSION = "2005-11-05"
+REQPATH = "facet"
+DATPATH = "data/facets"
+ETCPATH = "conf/facets"
+MTHPATH = "lib/facet"
+GENPATH = "lib/facets"
+
+#-----------------------------------------------------
+# Generate facet/
+#-----------------------------------------------------
+=begin
+desc %{Build facet redirect directory}
+task :facet do
+  sh %{rm -R './lib/facet'}
+  ['ext','set/special','set/general'].each{ |d|
+    from = "lib/facets/2005-11-05"
+    rbs = Dir.glob( File.join( from, d, '**/*.rb' ) )
+    rbs.each { |e|
+      nolib = e.gsub( /^lib\//, '' )
+      re = Regexp.new( Regexp.escape( File.join( from, d ) + '/' ) )
+      link = e.gsub( re, 'lib/facet/')
+      FileUtils.mkdir_p( File.dirname( link ) )
+      File.open( link, "w+" ) { |w|
+         w << "require '#{nolib}'"
+      }
+    }
+  }
+end
+=end
+
+#-----------------------------------------------------
+# Read in the facets directory and sort-out per class
+#-----------------------------------------------------
+Methods = {}
+task :methods do
+  Dir.chdir(MTHPATH) do
+    dg = Dir.glob('*/**/*.rb')
+    dg.each { |f|
+      klass, *meth= f.split('/')
+      Methods[ klass ] ||= []
+      Methods[ klass ] << "#{meth.join('/').chomp('.rb')}"
+    }
+    Methods.keys.each { |k| Methods[k].sort! }
+  end
+end
+
+#-----------------------------------------------------
+# Save method index to file in yaml format
+#-----------------------------------------------------
+desc %{Generate method index file}
+task :index => [ :methods ] do
+  print "Creating method index... "
+  loc = File.join( DATPATH, 'index.yml' )
+  File.open( loc, 'w' ) { |f|
+    f << Methods.to_yaml
+  }
+  puts "[done]"
+end
+
+#-----------------------------------------------------
+# Create per class feature files
+#-----------------------------------------------------
+desc %Q{Generate per-class feature files}
+task :class => [:methods ] do
+  print "Creating per class files... "
+
+  index  = Methods
+  noauto = File.read_list( File.join( ETCPATH, 'noauto' ) )
+  allfiles = index.collect{ |k,ms| ms.collect{ |m| "#{k}/#{m}" } }.flatten
+  full = calc_full(allfiles, noauto)
+
+  index.each { |classname, method_files|
+    File.open( "#{GENPATH}/#{classname.downcase}.rb", 'w' ) { |f|
+      method_files.each { |rf|
+        mfn = "#{classname.downcase}/#{rf}"
+        if full.include?(mfn)
+          f << %Q{require '#{REQPATH}/#{mfn}'\n}
+        end
+      }
+    }
+  }
+  puts "[done]"
+end
+
+#-----------------------------------------------------
+# Do all prep tasks (do this to generate data index
+# file and method group files)
+#-----------------------------------------------------
+desc %{Do all preperation (index, class)}
+task :prep => [ :index, :class ] do
+end
+
+#-----------------------------------------------------
+# List Methods
+#-----------------------------------------------------
+desc %{Output a list of all methods}
+task 'list' => [ :methods ] do
+  puts method_list_outline
+end
+
+# #-----------------------------------------------------
+# # HTML List MethodsFile.new(
+# #-----------------------------------------------------
+#
+# HEAD = <<-HERE
+# <html>
+# <head>
+#   <style>
+#     pre#methods {
+#       font-size: .8em;
+#       line-height: 1em;
+#     }
+#   </style>
+# </head>
+# <body>
+# <pre id="methods">
+# HERE
+# 
+# FOOT=<<-HERE
+# </pre>
+# </body>
+# </html>
+# HERE
+# 
+# desc %{generate method list html file}
+# task 'listHtml' => [ :scrape_methods ] do
+#   s = HEAD + method_list_outline + FOOT
+#   File.open('pub/www/methods.html', 'w') { |f| f << s }
+# end
+
+#desc "Check for open comment tests"
+#task :testchk do
+#  system %q{grep -r ^#=begin\ test ./lib}
+#end
+
+
+#-----------------------------------------------------
+# Supporting Methods
+#-----------------------------------------------------
+
+private
+
+def method_list_outline
+  s = ''
+  Methods.keys.sort.each { |k|
+    ms = Methods[k].collect{|m| m.gsub(%r{^self\/},'::')}.sort
+    s << "#{k}:\n"
+    ms.each { |m| s << "  #{m}\n" }
+  }
+  s
+end
+
+# Full set of require files (allfiles minus noauto and unsafe)
+def calc_full( allfiles, noauto )
+  sf = allfiles.dup
+  noauto.each do |f|
+    if f.include?('*')
+      re = %r"#{f.gsub('*','.*')}"
+      sf.reject!{ |x| x =~ re }
+    elsif sf.include?(f)
+      sf.delete f
+    end
+  end
+  sf.sort
+end