facets-glimmer 3.2.0

data/LICENSE.txt

@@ -0,0 +1,26 @@
+Ruby Facets
+Copyright (c) 2005-2022, Thomas Sawyer, Andy Maleh
+All rights reserved.
+
+(BSD-2 LICENSE)
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice,
+   this list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
+BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
+LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
+OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

data/NOTICE.rdoc

@@ -0,0 +1,167 @@
+= COPYRIGHT NOTICES
+
+== Ruby Facets
+
+Copyright:: (c) 2005,2011 Thomas Sawyer
+
+  Copyright (c) 2005,2011 Thomas Sawyer
+
+  You may distribute this software under the same terms as Ruby.
+
+
+== Ruby/Extensions
+
+Copyright:: (c) 2004 Gavin Sinclair
+License:: Ruby
+
+  Copyright (c) 2004 Gavin Sinclair
+
+  Ruby/Extensions (extensions.rubyforge.org) is copyrighted free software
+  created and maintained by Gavin Sinclair (gsinclair@soyabean.com.au) and
+  released under the same license as Ruby.
+
+  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.
+
+
+==  Nitro/Glue
+
+Copyright:: (c) 2006, George Moschovitis
+License:: BSD-3-Clause
+
+  Copyright (c) 2006, George Moschovitis
+  All rights reserved.
+
+  Redistribution and use in source and binary forms, with or without
+  modification, are permitted provided that the following conditions
+  are met:
+
+  * Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+
+  * Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+
+  * Neither the name of the <ORGANIZATION> nor the names of its contributors
+    may be used to endorse or promote products derived from this software
+    without specific prior written permission.
+
+  THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+  AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+  IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+  ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE
+  LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+  CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+  SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+  INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+  CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+  ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+  POSSIBILITY OF SUCH DAMAGE.
+
+
+== ActiveSupport
+
+Copyright:: (c) 2005-2011 David Heinemeier Hansson
+License:: MIT
+Website:: http://rails.org
+
+  Copyright (c) 2005-2011 David Heinemeier Hansson
+
+  Permission is hereby granted, free of charge, to any person obtaining
+  a copy of this software and associated documentation files (the
+  "Software"), to deal in the Software without restriction, including
+  without limitation the rights to use, copy, modify, merge, publish,
+  distribute, sublicense, and/or sell copies of the Software, and to
+  permit persons to whom the Software is furnished to do so, subject to
+  the following conditions:
+
+  The above copyright notice and this permission notice shall be
+  included in all copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+  EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+  MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+  NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+  OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+  WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+== Ruby Treasures
+
+Copyright:: (c) 2001 Paul Brannan
+License:: Ruby License
+
+  Ruby Treasures 0.1
+  Copyright (c) 2001 Paul Brannan <paul@atdesk.com>
+
+  You may distribute this software under the same terms as Ruby (see the file
+  RUBY.txt that was distributed with this library).
+
+
+== Metaid
+
+Copyright:: (c) why the lucky stiff
+
+  Copyright (c) why the lucky stiff
+
+
+== CLAP
+
+Copyright:: (c) 2010 Michel Martens
+License:: MIT
+Website:: https://github.com/soveran/clap
+
+  Copyright (c) 2010 Michel Martens
+
+  Permission is hereby granted, free of charge, to any person obtaining a copy
+  of this software and associated documentation files (the "Software"), to deal
+  in the Software without restriction, including without limitation the rights
+  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies
+  of the Software, and to permit persons to whom the Software is furnished to
+  do so, subject to the following conditions:
+
+  The above copyright notice and this permission notice shall be included in all
+  copies or substantial portions of the Software.
+
+  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+  OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+  IN THE SOFTWARE.
+
+
+== String#natcmp
+
+Copyright:: (c) 2003 by Alan Davies
+License:: Custom
+
+  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.md

@@ -0,0 +1,305 @@
+# Ruby Facets 3.2.0
+
+[![Gem Version](https://badge.fury.io/rb/facets.svg)](http://badge.fury.io/rb/facets)
+[![Build Status](https://secure.travis-ci.org/rubyworks/facets.svg)](http://travis-ci.org/rubyworks/facets)    
+[![Flattr Me](http://api.flattr.com/button/flattr-badge-large.png)](http://flattr.com/thing/324911/Rubyworks-Ruby-Development-Fund)
+
+
+*"ALL YOUR BASE ARE BELONG TO RUBY"*
+
+This is the [Glimmer](https://github.com/AndyObtiva/glimmer) fork of the Ruby Facets project, packaged as the [facets-glimmer](https://rubygems.org/gems/facets-glimmer) gem.
+
+## Introduction
+
+Ruby Facets is the premiere collection of general purpose method
+extensions and standard additions for the Ruby programming language.
+
+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.
+
+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 reliable source of reusable components, suitable
+to a wide variety of usecases.
+
+
+## Resources
+
+* 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 its extensive breadth.
+The documentation generated when installing via RubyGems, or the YARD
+docs provided by rubydoc.info can be somewhat unwieldy because it
+combines all of Facets in one large set. When using these resources,
+it is important to remain aware of the source location of particular
+methods.
+
+For better organized online documentation, generated to separate core
+extensions from standard libraries, see the [Learn Facets](http://rubyworks.github.com/facets/learn.html) page on the website for links to available documentation.
+
+
+## Installation
+
+### Bundler
+
+If you are using Bundler with your project, add the facets gem to the project's
+Gemfile. Unless you want all of facets loaded be sure to add the `:require => false`
+option.
+
+    gem "facets-glimmer", require: false
+
+### RubyGems
+
+The easiest way to install is via RubyGems.
+
+    $ gem install facets-glimmer
+
+### Setup.rb
+
+Facets can be installed the old-fashioned way using [Setup.rb](http://rubyworks.github.com/setup).
+Download and unpack the .tar.gz package and run setup.rb, like so:
+
+    $ tar -xvzf facets-2.x.x.tar.gz
+    $ cd facets-2.x.x
+    $ sudo setup.rb
+
+Facets 2.8+ requires Ruby 1.8.7 or higher. Facets 3.0+ requires Ruby 2.0.0 or higher.
+
+
+## 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 the community. There are a number of advantages here:
+
+* Better Code-reuse
+* Collaborative Improvements
+* Greater Name Consistency
+* One-stop Shop and Installation
+
+
+## Usage
+
+### 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.
+
+With the exception of a few *uncommon* extensions, CORE contains anything that
+will load automatically when issuing:
+
+    require 'facets'
+
+This loads all the CORE functionality at once. If you plan to use more then a
+handful of Facets core methods it is recommended that you require the library in
+this way. However, you can also "cherry pick" the CORE library as you prefer.
+And for uncommon extensions this must be done. The general require statement for
+a core extension library is:
+
+    require 'facets/<class|module>/<method>'
+
+For example:
+
+    require 'facets/time/stamp'
+
+Most "atoms" contain only one method, but 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.
+
+#### Method File Names
+
+Operator method redirect files are stored using English names. For instance
+`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 (aka Standard Library)
+
+On top of the extensive CORE library, Facets provides extensions for Ruby's
+standard library, as well as a small collection of additional modules and
+classes to supplement it.
+
+Use this library like you would any other 3rd party library.
+The only difference between Facet's Standard library and other libraries
+is the lack of any enclosing `Facets::` namespace.
+
+When using Facets extended versions of Ruby's standard libraries,
+the libraries have to loaded individually. 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'
+
+For details pertaining to the functionality of each feature,
+please see the API documentation.
+
+## Compatibility
+
+### MRI CRuby Compatibility
+
+Facets 2.8+ requires Ruby 1.8.7 or higher. Facets 3.0+ requires Ruby 2.0.0 or higher.
+
+### JRuby Compatibility
+
+This gem is fully compatible with [JRuby](https://www.jruby.org/), mapping JRuby versions to the [MRI CRuby Compatibility](#mri-cruby-compatibility) guidelines (e.g. JRuby 9.3.4.0 supports Ruby 2.6.x, and thus works with Facets 3.0+).
+
+### RubyMotion Compatibility
+
+This gem is mostly compatible with [RubyMotion](https://www.rubymotion.com/) as it loads all Core and Standard APIs upon including the gem except for the following files:
+- Core exclusions:
+  - core/facets/range/nudge.rb
+  - core/facets/applique/file_helpers.rb
+  - core/facets/enumerable/recursively.rb
+  - core/facets/hash/recursively.rb
+  - core/facets/functor.rb
+  - core/facets/lazy.rb
+  - core/facets/enumerable/associate.rb
+  - core/facets/kernel/as.rb
+  - core/facets/kernel/ergo.rb
+- Standard exclusions:
+  - standard/facets/uri/query.rb
+  - standard/facets/date.rb
+  - standard/facets/memoizer.rb
+  - standard/facets/enumargs.rb
+  - standard/facets/erb.rb
+  - standard/facets/fileutils/outofdate.rb
+  - standard/facets/interval.rb
+  - standard/facets/pathname/op_div.rb
+  - standard/facets/pathname/exists.rb
+
+## Contribute
+
+This project thrives on contribution!
+
+If you have any extension methods, classes or modules that you think have
+very general applicability and would like to see them included in
+this project, don't hesitate 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.
+
+
+## Development
+
+Facets uses the [Lemon](http://rubyworks.github.com/lemon) testing framework
+to handle unit testing, while [QED](http://rubyworks.github.com/qed) specifications
+provide tested documentation.
+
+Facets uses [Detroit](http://detroit.github.com) and [Rulebow](http://rubyworks.github.com/rulebow)
+build tools. Detroit is a life-cycle tool and Rulebow is a continuous integration tool. These
+tools, via the `Assembly` and `Rulebook` scripts respectively, sometimes use other tools such
+as [Mast](http://rubyworks.github.com/mast) and [Indexer](http://rubyworks.github.com/indexer).
+In addition we support [Rake](https://ruby.github.io/rake/) and [Guard](http://guardgem.org/)
+build tools, which most developers are familiar with.
+Note, that while these build tools can be easy circumvented, the Mast and Indexer tools are
+necessary to prepare Facets for release.
+
+To build the Ruby gem, run this command:
+
+```
+rake package
+```
+
+## Authors
+
+Much of this collection was written and/or inspired by a variety of great Ruby
+developers. Fortunately nearly all utilized works were copyrighted under the same
+open licenses, the Ruby License or the more liberal BSD and MIT licenses. In the
+one or two exceptions the copyright notice has been included with the source code.
+We have since received permission from the various authors to normalize the licensing
+to a single license. For this purpose we have chosen the BSD 2 Clause License.
+This is the license Ruby itself now uses, so it seemed the most appropriate choice.
+It is also almost identical to the MIT license. Any code file not specifically labeled
+otherwise shall fall under the this license (which is BSD 2-clause).
+
+In all cases, every effort has been made to give credit where credit is due.
+You will find these acknowledgments embedded in the source code. You can see
+them in "CREDIT:" and/or "@author" lines.
+Also see the [Contributors page](https://github.com/rubyworks/facets/wiki/Contributors)
+on the Wiki for a list of all contributing Rubyists. If anyone is missing from
+the list, please let us know so we can correct. Thanks.
+
+This collection was put together by, and much of it written by [trans](https://github.com/trans).
+If need be, he can be reached via email at transfire at gmail.com.
+
+
+## License
+
+The collection PER COLLECTION is licensed as follows:
+
+    Ruby Facets
+    Copyright (c) 2005-2022 Rubyworks
+
+    Distributed under the terms of the BSD-2 License (same as Ruby license).
+
+The BSD 2 Clause License is a simple open source license. The complete text of the
+license accompany this document (see the enclosed LICENSE file).
+
+Acknowledgments and Copyrights for particular snippets of borrowed code
+are given in their respective source. At this point, all licensing has been normalized
+for all included code. Original authors have given permission for inclusion of their
+code under such license, with appropriate credit citations.
+
+
+## "ALL YOUR BASE ARE BELONG TO RUBY!"
+
+Ruby Facets, Copyright (c) 2005-2022 Rubyworks
+
+Do you Ruby? (http://ruby-lang.org)

data/demo/applique/assertion_framework.rb

@@ -0,0 +1 @@
+require 'ae'

data/demo/applique/file_helpers.rb

@@ -0,0 +1,34 @@
+require 'fileutils'
+require 'pathname'
+
+def temporary_directory
+  @temporary_directory ||= 'tmp'
+end
+
+Before :document do
+  if File.exist?(temporary_directory)
+    FileUtils.rm_r(temporary_directory)
+  end
+  FileUtils.mkdir(temporary_directory)
+end
+
+When /Given a directory '(.*?)' containing/ do |dir, text|
+  #abort unless /^#{temporary_directory}/ =~ dir
+  text.lines.each do |file|
+    next if file =~ /^\s*$/
+    file = File.join(dir, file.strip)
+    path = File.dirname(file)
+    FileUtils.mkdir_p(path)
+    File.open(file, 'w'){ |f| f << "SPINICH" }
+  end
+end
+
+# Return project root directory by looking for +lib+ directory.
+def root_directory
+  @root_directory ||= (
+    Pathname.new(Dir.pwd).ascend do |root|
+      break root if root.join('lib').directory?
+    end
+  )
+end
+

data/demo/core/array/after.md

@@ -0,0 +1,13 @@
+## Array#after
+
+    require 'facets/array/after'
+
+`Array#after` returns the first value that comes after a given value. The
+value after the last is the first. Returns `nil` if the given value is not
+in the array.
+
+    sequence = ['a', 'b', 'c']
+    sequence.after('a').assert == 'b'
+    sequence.after('b').assert == 'c'
+    sequence.after('c').assert == 'a'
+    sequence.after('d').assert == nil

data/demo/core/array/arrange.md

@@ -0,0 +1,17 @@
+## Array#arrange
+
+    require 'facets/array/arrange'
+
+The `arrange` method produces appropriate ranges from the objects in the array.
+It assumes inclusive ranges (i.e. `1..4`) and `range.first <= range.last`.
+
+Works with integers, dates and strings. However, all the objects in the array must
+be of the same class.
+
+    [1,2,3,6,7,8].arrange.assert == [1..3, 6..8]
+
+    [10..15, 16..20, 21, 22].arrange.assert == [10..22]
+
+    a = %w{a b c g h i j k  m o}
+    a.arrange.assert == ['a'..'c','g'..'k', 'm' , 'o']
+

data/demo/core/array/before.md

@@ -0,0 +1,14 @@
+## Array#before
+
+    require 'facets/array/before'
+
+Returns the value prior to the given value. The value previous
+to the first is the last. Returns nil if the given value is not
+in the array.
+
+    sequence = ['a', 'b', 'c']
+    sequence.before('a').assert == 'c'
+    sequence.before('b').assert == 'a'
+    sequence.before('c').assert == 'b'
+    sequence.before('d').assert == nil
+

data/demo/core/array/collapse.md

@@ -0,0 +1,15 @@
+## Array#collapse
+
+    require 'facets/array/collapse'
+
+Simplify an array by flattening it then compacting it.
+
+    [1,[2,nil,[3]],nil,4].collapse.assert == [1,2,3,4]
+
+## Array#collapse!
+
+Simplify an array by flattening it in place then compacting it in place.
+
+    a = [1, nil, [1, 2], nil, [[3]]]
+    a.collapse!
+    a.assert == [1, 1, 2, 3]

data/demo/core/array/collisions.md

@@ -0,0 +1,30 @@
+## Array#collisions
+
+_alias for Array#commonality_.
+
+    require 'facets/array/collisions'
+
+Get a list of all items that have something in common in terms of the
+supplied block. If no block is given objects are considered to be in
+common if they return the same value for Object#hash and if obj1 == obj2.
+
+This can be useful, for instance, in determining all persons that share
+their last name with another person.
+
+    Person = Struct.new(:name)
+    persons = %w{Wayne Pennyworth Grayson Wayne Pennyworth}.map{|n| Person.new(n)}
+    persons.collisions { |person| person.name }.keys.assert == ["Wayne","Pennyworth"]
+
+The method is similar to #group_by which is a standard Ruby method as of 1.9.
+To get effectively the same results with #group_by use `select{ |k,v| v.size > 1 }`.
+
+    expected = { 2 => [2, 2], 4 => [4, 4] }
+
+    [1, 2, 2, 3, 4, 4].group_by{ |e| e }.
+                       select{ |k,v| v.size > 1 }.assert == expected
+
+    [1, 2, 2, 3, 4, 4].collisions.assert == expected
+
+    %w{foo bar baz}.collisions{|str| str[0]}.assert == {'b' =>["bar", "baz"] }
+
+Returns a Hash mapping common attribute to those elements.

data/demo/core/array/commonality.md

@@ -0,0 +1,31 @@
+## Array#commonality
+
+    require 'facets/array/commonality'
+
+Get a list of all items that have something in common in terms of the
+supplied block. If no block is given objects are considered to be in
+common if they return the same value for Object#hash and if obj1 == obj2.
+
+This can be useful, for instance, in determining all persons that share
+their last name with another person.
+
+    Person = Struct.new(:name)
+    persons = %w{Wayne Pennyworth Grayson Wayne Pennyworth}.map{|n| Person.new(n)}
+    persons.commonality { |person| person.name }.keys # => ["Wayne","Pennyworth"]
+
+The method is similar to #group_by which is a standard Ruby method as of 1.9.
+To get effectively the same results with #group_by use `select{ |k,v| v.size > 1 }`.
+
+    expected = { 2 => [2, 2], 4 => [4, 4] }
+
+    [1, 2, 2, 3, 4, 4].group_by{ |e| e }.
+                       select{ |k,v| v.size > 1 }.assert == expected
+
+    [1, 2, 2, 3, 4, 4].commonality.assert == expected
+
+
+    %w{foo bar baz}.commonality{|str| str[0]}.assert == {'b' =>["bar", "baz"] }
+
+Returns a Hash mapping common attribute to those elements.
+
+