facets 0.6.3 → 0.7.0

data/ANN

@@ -1,50 +1,46 @@
 Hi--
 
-A new version of Ruby Facets is out: 0.6.2. This version adds some new methods
-including the Kilmer inspired time and byte methods found in Rails. Here's a 
-rundown of changes:
+Exciting news: Ruby Facets 0.7 is out! This version goes ballistic, converging
+with the now defunct Carats library. All the Carats files are now available 
+directly from Facets.
 
-* Added kernel/resc as a shortcut for Regexp.escape.
+Here's a list of some of the changes for 0.7.0:
 
-* Renamed hash/keys_to_string to hash/key_to_s and  
-hash/keys_to_symbol to hash/keys_to_sym to be more consistant
-with other methods and what these methods specifically do.
-The old names have been deprecated.
+* The Carats library has been ported into the Facet lib. These files sit in the 
+  main lib directory 'facet/' above the "atomic" methods which are all in 
+  subdirectories 'facet/{module|class}/'. This layout works well, and allows for
+  everything to be provided from the same location.
 
-* Added hash/has_keys?, which allows for checking mutliple keys at once.
-Also includes #has_only_keys?
+* All methods with names containing non-alphanumeric characters now have facet
+  files without those special characters. This removes some incompatibilites
+  with some file systems. Names ending in !, ? or = have simply have had that 
+  characeter removed. Others have been given suitable names and suffixed with '-op'.
 
-* Added Rail's Time and Byte modules for Numeric with
-numeric/times.rb and numeric/bytes.rb (I've been informed that
-thanks go to Rich Kilmer for this. Thanks!)
+* A number of "require collection" files have been added. These require multiple
+  realted "atoms" at once, for greater convenience.
 
-* Added numeric/octet_unit which utilizes numeric/bytes.
-(The name of this method may change in the future though.)
+* A few methods that were grouped together in the same file have been separated
+  into their own files. (This is more feasible thanks to the additional
+  "require collections.")
 
-* Added enumerable/uniq_by.
+* The method array/put has been changed to array/top (it is an alias for #unshift).
 
-* Added module/abstract.
+* Methods #matchdata/post_match_from and #matchdata/pre_match_from have been 
+  deprecated in favor of some more generalized methods that serves the same 
+  purposes, matchdata/matchtree and matchdata/matchset.
 
-* Added module/redirect which is similar to alias, but does not
-copy the method, but rather wraps it. It also takes a hash so
-multiple methods can be redirected all at once.
+* Added module/include_as.
 
-* Added string/shatter which is similar to split but includes
-the matched portions of text.
+* Added array/permute.
 
-If you are interested in contributing to a project but have little time
-to spare, helping with Facets may be a perfect project. There are still
-plenty of light-weight tasks to do: improve documentation, improve the
-tests and write a few yet missing, improve the rohbustness of methods
-themselves, including exceptional error catching, and of course there's
-plenty of room for adding new goodies, too. If you have any extension 
-methods that you use and think may be of benefit to others, please let
-me know.
 
-And, of course, please let me know if you come across any bugs.
+If you have any extension methods that you use and think may be of benefit
+to others, please submit them. And, of course, please let me know if you 
+come across any bugs.
 
-You can contact me either privately or via ruby-talk, or through the
-new calibre-cuts mailing-list:
+You can contact me either privately or via ruby-talk, 
+or via the Ruby Muse mailing list, suby-ruby at berlios.de 
+(membership required).
 
   http://rubyforge.org/mailman/listinfo/calibre-cuts
 

data/COPYING

@@ -0,0 +1,5 @@
+OPEN SOURCE COLLECTION
+
+A variery of open-source licenses are used.
+
+See the license directory for all the specific licenses.

data/ChangeLog

@@ -1,5 +1,23 @@
+
 --- !!history
 
+v0.7.0:
+- All methods with names containing non-alphanumeric characters now have facet
+  files without those special characters. This removes some incompatibilites with 
+  certain systems (including Windows). Names ending in !, ? or = have simply been
+  removed. Others have been given suitable names an sufficxed with '-op'.
+- An new lib directory 'facets/' (notice the pluralization) has been created to 
+  contain various special collections of facet methods (via multiple requires).
+- A few methods that were grouped together in the same file have been separated 
+  into their own files. This is more feasible now b/c the collectives in 'facets/'
+  are avaialble.
+- The method array/put has been changed to array/top (it is an alias for #unshift).
+- Methods #matchdata/post_match_from and #matchdata/pre_match_from have deprecated
+  in favor of some more generalized methods that serves the same purposes,
+  matchdata/matchtree and matchdata/matchset.
+- Added module/include_as.
+- Added array/permute.
+
 v0.6.3:
 - Gem is now avaliable!
 - Added kernel/require_all which allows one to require a pattern of files,

data/README

@@ -1,17 +1,25 @@
+
 = Ruby Facets
 
-=== Introduction Ruby's Atomic Library
 
-Ruby Facets, the Fantastic Atomic Core Extensions, is an growing
-collection of extension methods for Ruby's core and standard libs.
+=== Introduction to Ruby's Atomic Library
+
+Ruby Facets (Fantastic Atomic Core Extensions), is an growing
+collection of methods to complement Ruby's core and standard libs.
 It is an _atomic_ library in that the methods are, to the greatest
 degree reaonable, packaged individually so that each can be _required_
-independently. Facets is an open library and all are wlecome to
-contribute to it growth. The package currently contains over 200
-methods, spanning 26 classes and modules. Facets also includes a 
-repository for experimental works, called <tt>facet-dev</tt>. 
-This provideds a public location to develop and try nascent extensions,
-which may eventually make their way into Facets proper. 
+independently. This gives the programmer greater control to include only
+the extra methods that are actually needed and thus boost runtime 
+efficiency a bit. The package currently contains over 300 atomic methods,
+spanning over 26 classes and modules.
+
+In addition to the atomic methods Facets also includes a large collection 
+of addon classes, modules and mixins (which generally utilizing Facets' 
+atomic methods). [Note: These used to exit in a separate lib called Carats.
+This has been deprecated in favor of a single package.]
+
+In short, through a single package, the Ruby programmer is treated to a
+plethora of programming tools.
 
 
 === Calibre
@@ -23,59 +31,67 @@ Ruby Facets is part of the Calibre project. You can learn more at:
 
 === Installation
 
-To install untar the package and use the included setup.rb script.
+The easiest way to install is via RubyGems. On the command line enter:
+
+  > gem install facets
+
+To manually install, untar the package and use the included setup.rb script.
 For example:
   
   > tar -xvzf facets-x.y.z.tar.gz
-  > cd facets-x.y.z
+  > cd facets--x.y.z
   > sudo ruby setup.rb
 
 
 === Usage
 
-There are quite a few methods spread out over numerous classes and methods.
-For detailed usage please refer to the API RDocs. Most methods are fairly well
-documented, but not all. Assistance in improving documentation is much appreciated.
+There are quite a few methods, classes and modules. For detailed usage it is best
+to refer to the API RDocs. Most is well documented. Assistance in 
+improving documentation though is always appreciated.
 
-The general require statement is as follows: 
+The general require statement for an atomic facet is as follows: 
 
-  require 'facet/<class|module>/<method>'
+  require 'facet/<class|module>/<method-name>'
 
-All lowercase. For example, perhaps a paricular application would be better
+All lowercase. The method-name may differ a bit from the actual method. If a method-name
+ends in ?, !, or = the character is simply removed. For methods that are non-alphanumeric,
+a suitable name is chosen according ot the methods functionaity and then suffixed with '-op',
+for "operator". For example, perhaps a paricular application would be better
 served if the NilClass responded to the <tt>#empty?</tt> message.
   
-  require 'facet/nil/empty?'
+  require 'facet/nil/empty'
 
 And the <tt>#empty?</tt> method will then be only new method added.
+Most "atoms" contain but a single method, but excpetions occur when methods
+very tightly related. 
 
-Almost every file is named for the method in contains. The only
-exceptions are for methods that are very tightly related. In these
-cases the file will be named either for the "core" method, or as
-a conjunction, like <tt>first&last.rb</tt>.
+There are also numerous shortcuts for including atoms in mass.
+Some of these occur at the top-level under 'facets/', while
+others occur in the atomic subdirectory 'facets/{class|module}/'.
 
-There are also shortcuts for including selections in mass.
-In the future there will be more of these. For now there are only 
-the following two.
+The two most notable shortcuts are 'base' and 'common'.
+If you wish to include all the methods considered basic:
 
-If you wish to include all the methods consider fundemental "base" 
-methods:
+  require 'facet/base'
 
-  require 'facet/all-base'
-
-This represents a group of about one to two dozen methods that are 
+This represents a group of about two dozen methods that are 
 considered likely to be included in future versions of Ruby itself.
-
 If you would like to include the "base" methods plus all the methods
 considered "common":
 
-  require 'facet/all-base-common'
+  require 'facet/common'
 
 This is a large selection of methods that are considered the most 
-generally useful.
+often useful.
 
 All methods considered "uncommon" must be require individually.
-Since it is possible for a few of the uncommon methods to conflict
-with one another, there is no way to include _everything_.
+It is possible for a few of the uncommon methods to conflict,
+so there is no way to include _everything_ all at once.
+
+On top of all this there are the non-atomic additions. These never
+fall into a subdirectory, and can always be require accordingly:
+
+  require 'facet/{file-name}'
 
 
 === Contribute
@@ -87,12 +103,7 @@ extension you wish. The criteria for inclusion is fairly light:
 * Does it pass a basic testcase?
 
 If it meets these requirements then it will in all likelihood 
-be accepted into the main facets lib. Otherwise it may still find
-a place in the development library. Feel free to explore this
-facets-dev repository and, if so inclined, help develop what's 
-there. If you have an underdeveloped extension that you'd like 
-to see developed, please submit it and it can be placed into dev,
-where it can reside and worked on by the community at large.
+be accepted into the main facets lib. 
 
 
 === Mascot
@@ -114,7 +125,7 @@ copyright notice with the source code. In all cases, I have made every
 effort to give credit where credit is due. You will find these thanks
 and acknowledgements at the beginning of the source code.
 
-The collection as a whole is licensed as follows:
+The collection per collection is licensed as follows:
 
   Ruby Facets, the Fantastic Atomic Core Extensions
   Copyright (c) 2004 Thomas Sawyer
@@ -128,3 +139,4 @@ A copy of both licenses should accompany this document.
 
   ALL YOUR BASE ARE BELONG TO RUBY
 
+

data/README2

@@ -0,0 +1,67 @@
+= Ruby Carats, the Ruby Toolchest
+
+== Introduction
+
+Ruby Carats is an extensive, 100% pure Ruby, general purposed library collection
+of classes amd modules. It is an open repository for useful 
+general puroposed and well tested classes, modules, mixins.
+
+== Installation
+
+To do a manual install untar and use the included setup.rb script.
+  
+  > tar -xvzf carats-x.y.z.tar.gz
+  > cd carats-x.y.z
+  > sudo ruby setup.rb
+
+== Usage
+
+Umm... that might require a book. You should look at the API docs.
+To date, not everything in documented. But it's getting there.
+You are welcome to help out. The basic require is:
+
+  require 'carat/<file>'
+
+== Authorship
+
+This collection was put together by, and largely written by Thomas Sawyer
+(aka T. Onoma). He can be reached via email at transami at runbox.com.
+
+This package is a collection of work by many persons. 
+If it matters, the collection per collection is licensed:
+
+  Ruby Carats
+  Copyright (c) 2004-2005 Thomas Sawyer
+  Ruby License
+
+But the actual code on is licensed according to the original authors
+desires, being one of the following: Ruby, GPL, LGPL, MIT, or Artistic.
+Copies of these licenses should accompany this document. Any piece of code
+not specifically laballed shall fall under the Ruby License.
+   
+[Please Note: I am working to make sure everything is labeled appropriately.
+Please forgive me if I have not done so in a particular place --just let 
+me know and I will fix.]
+
+Also, I would like to ask all those authors, whose code is collected here,
+to consider moving to the Ruby license, so one license can serve for all.
+
+=== Attributed Authors
+
+* Thomas Sawyer
+* Paul Brannan
+* Renald Buter
+* Hal Fulton
+* Gavin Sinclair
+* Michael Granger
+* Michael Neumann
+* Florian Frank
+* Mohammad Khan
+* Derek Lewis
+* Thomas-Ivo Heinen
+* Jan Molic
+
+
+== Pitch
+
+  ALL YOUR BASE ARE BELONG TO RUBY

data/Reapfile

@@ -2,7 +2,7 @@
 
 TITLE: &title Ruby Facets
 NAME: &pkg facets
-VERSION: '0.6.3'
+VERSION: '0.7.0'
 AUTHOR: Trans
 EMAIL: transfire@gmail.com
 HOMEPAGE: "http://calibre.rubyforge.org"
@@ -10,7 +10,7 @@ HOMEPAGE: "http://calibre.rubyforge.org"
 SUMMARY: Fantastic Atomic Core Extensions
 
 DESCRIPTION: >
-  Ruby Facets is a cornicopia of core extensions for
+  Ruby Facets is a cornicopia of extensions for
   the Ruby programming language. It is unique by virtue
   of the atomicity of its design. Methods are stored
   in their own files, allowing for extremely granular
@@ -27,16 +27,29 @@ TEST:
   OPTIONS: ~
 
 RDOC:
-  TITLE: *title
-  DIR: 'doc'
-  TEMPLATE: html #ruby-red
-  OPTIONS: ['--merge', '--promiscuous', '--all']
-  MAIN: README
-  INCLUDE:
-    - 'README'
-    - 'LICEN*'
-    - 'lib/facet/**/*.rb'
-  EXCLUDE: []
+  -
+    TITLE: *title
+    DIR: 'doc/atomic-rdoc'
+    TEMPLATE: html #ruby-red
+    OPTIONS: ['--merge', '--promiscuous', '--all']
+    MAIN: README
+    INCLUDE:
+      - 'README'
+      - 'LICEN*'
+      - 'lib/facet/*/*.rb'
+    EXCLUDE: []
+  -
+    TITLE: *title
+    DIR: 'doc/main-rdoc'
+    TEMPLATE: html #ruby-red
+    OPTIONS: ['--all']
+    MAIN: README
+    INCLUDE:
+      - 'README'
+      - 'LICEN*'
+      - 'lib/facet/*.rb'
+    EXCLUDE: []
+   
 
 PACKAGE:
   DIR: pkg
@@ -67,6 +80,7 @@ ANNOUNCE:
   PORT: 25
   ACCOUNT: transfire@gmail.com
   AUTHTYPE: login  #cram_md5 #plain
+  TLS: true
   FILE: ANN
   SLOGAN: ALL YOUR BASE ARE BELONG TO RUBY!
   INFO:

data/ToDo

@@ -0,0 +1,24 @@
+
+- Minor:
+  - ordered-hash, would like an improved version.
+  - nil-comparable, works but I think could done better.
+  - lisp, there may be other places where #pair! is needed.
+  - interval, add infinity as possible sentinal.
+  - duckhunter (might be able to use Functor as decoy/probe)
+
+- Carat-dev:
+  - interface
+  - detach
+
+- Tests:
+  - binaryreader
+  - binding_of_caller
+  - coroutine, currently just checks for no error raised
+  - heap
+  - io-reactor
+  - io-redirect
+  - semaphore
+  - tracepoint
+  - 1st, needs some sort of refinement
+  - lisp, needs to be vastly expanded 
+  - lisp_format, code use a few more tests

data/Version

@@ -0,0 +1,11 @@
+0.7.0 Georgian Transform
+0.6.3 Gemstone
+0.6.2 Refinement
+0.6.1 Florian's Mixes
+0.6.0 Florian's Onslaught
+0.5.0 First Release
+0.4.0 Raspberry
+0.3.0 ABC
+0.2.0 Succ
+0.1.0 TomsLib
+

data/bench/b_harray.rb

@@ -0,0 +1,49 @@
+=begin
+
+Some speed comparisions between standard Array and HArray.
+
+=end
+
+require 'trix/harray'
+require 'benchmark'
+
+$n = 50000
+
+# standard array
+
+def sarray_make
+  $n.times do
+    $sa = [1,'a',nil]
+  end
+end
+
+def sarray_slice
+  $n.times do
+    $sa[1..2]
+  end
+end
+
+# hash array
+
+def harray_make
+  $n.times do
+    $ha = HArray.new_h({0=>1,1=>'a',2=>nil})
+  end
+end
+
+def harray_slice
+  $n.times do
+    $ha[1..2]
+  end
+end
+
+
+### --- bench ---
+
+puts "\nCURRENT"
+Benchmark.bm(15) do |b|
+  b.report("HAarry#new:") { harray_make }
+  b.report("HArray#slice:") { harray_slice }
+  b.report("Array#new:") { sarray_make }
+  b.report("Array#slice:") { sarray_slice }
+end