facets 3.0.0 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 04425cff670267fec297484f50e19edbb8a22fc8
-  data.tar.gz: 19b9480ec202b072704267dc8760209cb6648338
+  metadata.gz: 6968b01e3ed3e46be3265a381de7443ec38bb966
+  data.tar.gz: 4668e23ad2f1e44a65cf8ba895f0daccbf65c175
 SHA512:
-  metadata.gz: e36beb518158636837793bcab25e5c004cfd904d8e78f865099ff5b904ee562f04078d3d6ff5e10a7ab02b225de49d3ba51365fdc3538d50725855b0a5830baf
-  data.tar.gz: 13b826e5a84e8c7b91562c2df850eb16972a843dc6f6546f7f0aaf34a548d9db2c3d27935ea39a98573700d65cfe3bbdac183f8df2cdb1b66b68ee4faa9d8e54
+  metadata.gz: 6deb1971ac97f93bb75d4c144fabb91d6e9f6424867e4be70a2b99623d35080a49cf774c18e36236877c3f35d3549ca5563eb6a6c18912beccd3e67b1a414ec0
+  data.tar.gz: 4fefcae7db154ac8b054aa4d5fc293653ea2376a1a36a59968bbad9a70763a06ca8bde410c1c3bb1c89d10e455420feee977264bfd8d1f4e49494bf90a16b9cf

data/.index

@@ -12,24 +12,28 @@ organizations:
 requirements:
 - groups:
   - test
-  version: '>= 0'
+  version: ">= 0"
   name: lemon
 - groups:
   - test
-  version: '>= 0'
+  version: ">= 0"
   name: qed
 - groups:
   - test
-  version: '>= 0'
+  version: ">= 0"
   name: rubytest-cli
 - groups:
   - test
-  version: '>= 0'
+  version: ">= 0"
   name: rake
 - groups:
   - test
-  version: '>= 0'
+  version: ">= 0"
   name: simplecov
+- groups:
+  - guard
+  version: ">= 0"
+  name: guard
 conflicts: []
 alternatives: []
 resources:
@@ -63,7 +67,7 @@ paths:
   - lib/standard
 name: facets
 title: Ruby Facets
-version: 3.0.0
+version: 3.1.0
 summary: The orginal well curated collection of extension methods for Ruby.
 slogan: ALL YOUR BASE ARE BELONG TO RUBY!
 description: Facets is the premier collection of extension methods for the Ruby programming
@@ -73,4 +77,4 @@ description: Facets is the premier collection of extension methods for the Ruby
   applications.
 scm_uri: https://github.com/rubyworks/facets/tree/master
 created: '2004-12-16'
-date: '2014-12-20'
+date: '2016-05-09'

data/CONTRIBUTING.md

@@ -0,0 +1,112 @@
+# CONTRIBUTING TO FACETS
+
+## General Rules
+
+* Facets methods must have no external dependencies. (The only possible
+  exception to this is if the functor gets spun-off as a separate gem along
+  with related methods, but for now that hasn't happened.)
+
+* Each method must be in it's own file of the same name. If the method ends
+  with `=` or `?` just leave it off the file name.
+
+* On rare occasion two or more methods can be very tightly related. In these
+  cases the methods can all go in a single file under the name of the method
+  considered most significant. Usually files for the other methods should
+  still be created that simply require the main file.
+
+* Methods must be tested both via a Lemon unit test and as a QED demo.
+  The Lemon unit tests are for testing a method in detail whereas the QED
+  demos are for demonstrating usage.
+
+* Facets is divided into two parts, *core* and *standard* libraries.
+  Almost all of the core library can be loaded at once using `require 'facets'`
+  The standard library (also called the *more* library) must be required
+  per-script.
+
+* Some core methods are included on a *trial* basis, and these are not
+  necessary loaded automatically with `require 'facets'`. These should be
+  documented as such in the method comments.
+
+* Standard libraries that are not extensions of existing standard libraries
+  do not have to be divvied up into individual method files. But note that
+  full classes and/or modules are less likely to make it into Facets, as
+  these sorts of additions to Facets are only for very basic sorts of things.
+  Otherwise they'd deserve their own gem.
+
+* When submitting new methods for consideration, it is best if each method
+  (or *tightly related* set of methods) is in it's own pull request. If you
+  have only one method to submit then a simple  commit will do the trick. If
+  you have more than one it best to use separate branches. Let me emphasizes
+  this point because it makes it *much more likely* that your pull request
+  will be merged. If you submit a bunch of methods in a single pull request,
+  it is very likely that it will not be merged even if methods you submitted
+  are accepted!!!
+
+* Don't be discouraged when you get feedback about a method that isn't
+  all sunshine and roses. Facets has been around long enough now that
+  it needs to maintain a certain degree of quality control, and that means
+  serious discernment about what goes into the library. That includes
+  having in depth discussions the merits of methods, even about the best
+  name for a method --even if the functionality has been accepted the name
+  may not.
+
+
+## Versioning
+
+Facets tries to follow a semantic versioning system, but with a slightly
+differt scheme than most projects. For Facets the version number represents:
+
+    gestault.major.minor
+
+Techinically there can be a fouth `build` number, but we never use it for
+releases.
+
+
+## Commit Tags
+
+When making a commit, it is helpful to add a *commit tag* to the end of the
+first line of commit message. Commit tags are single words wrapped in colons.
+
+* If the commit is only a documentation change, then and `:doc:`.
+* If it is only a change to tests then add `:test:`.
+* If the change only effects project build or config files then add `:admin:`.
+* If the change fixes a bug that was reported via the issue system be sure
+  to reference the issue number in the message using `#` and add a `:bug:` tag.
+* For actual code changes, if the change is *very minor* and not something
+  anyone would notice, you can use `:tweak:`, if you want. 
+* If the change would require a minor version change than use `:minor:`.
+* But if a change is a significant change to the API, and thus will require
+  a major version change, then end the message with `:major:`.
+
+These are all rules of thumb, and no one expects them to be applied perfectly.
+
+
+## Documentation
+
+Facets started when the only choice for API documentation was RDoc. So originally
+that's how methods were documented. Since then both YARD and Tomdoc have come
+along. And some of these documentation styles have crept into a number of
+methods. So right now, things are a bit messy. But going forward it looks like we
+are going to settle on Tomdoc as the official documentation style (but using
+the tomparse gem's extensions). Using Tomdoc will give us reasonable
+interoperability with both RDoc and YARD, both of which now have support for
+Tomdoc (albeit support is not 100% the same, but hopefully it's close enough).
+
+Officially we publish documentation via rubydoc.info, which is the YARD server,
+and via the Facets website in Shomen JSON format.
+
+When writing documentation for a method it is best to give a simple summary
+explanation, followed by some basic examples. Follow that up with deeper
+explanation if needed, including *when* and *why* the method could be useful.
+
+
+## Testing
+
+* Methods in `lib/core/facets/{class}/{method}.rb` will be tested in `test/foo/{class}/test_{method}.rb`.
+* If `lib/core/facets/{class}/{method}.rb` consists only of a require statement, no test file is expected.
+* If `lib/core/facets/{class}/{method}.rb` consists only of a require and an alias, then `test/foo/{class}/{method}.rb`, only needs to test the existence of the alias and not the underlying code. But it's okay if the alias is tested further.
+* Methods in `lib/core/facets/{class}/{method}.rb` will be demoed in `demo/core/{class}/{method}.md`.
+* Require only files will have a full demo of it's method or methods. Code in a single file may be split into multiple demos, named after the method. This is to promote discoverability in the documentation.
+* Demos of aliases will have a simple demo, and a reference to the file it aliases
+
+

data/HISTORY.md

@@ -1,5 +1,39 @@
 # Facets Release History
 
+## 3.1.0 / 2016-05-10
+
+More or less a minor release, but there are some backward incompatabilites
+such as `Hash#except!` which no longer returns the rejected entries (use
+`Hash#remove!` for old behavior).
+
+Special thanks to Scott Parrish for all his help getting Facets in tip-top
+shape.
+
+Changes:
+
+* New Features
+
+  * Add `Hash#remove!` for old `except!` behavior.
+  * Add `Array#standard_deviation`.
+  * Add `Array#variance`.
+  * Add `Array#average`.
+  * Add `Numeric#delimit`.
+
+* Improved Features
+
+  * Change `Hash#except!` to not return rejected entries.
+  * Improve definition of Character Set in `String.random`.
+  * Add one to denominator of `String#similarity` score.
+  * Enhanced download methods.
+  * Improvements on compatability with ActiveSupport.
+  * Enumerable#from and #thru return empty set when index is out of bounds.
+
+* Bug Fixes
+
+  * Fix `Enumerable#key_by`.
+  * Fix `Enumerable#sum` to take initial value.
+
+
 ## 3.0.0 / 2014-11-11
 
 This major release has been a long time in coming --too long in fact. As with
@@ -21,8 +55,10 @@ Changes:
   * Add Dir.lookup method
   * Add Enumerator::Lazy#squeeze
   * Add Hash#fetch_nested
+  * Add Hash#deep_rekey and Hash#deep_rekey!
   * Add Kernel#instance_extract
   * Add Math#EC for Euler's constant
+  * Add Module#alias_class_method
   * Add Pathname#chdir
   * Add Pathname#readline
   * Add Proc.wrap (may become `Kernel#Proc()`)
@@ -34,6 +70,7 @@ Changes:
 * Improved Features
 
   * Enumerable#sum argument is initial value.
+  * Generalize Enumerable#sum to duck-type on `#+`.
   * Hash#collate can take multiple arguments.
   * Hash#collate no longer flattens automatically.
   * Time#past? and #future? use Time.current.
@@ -43,6 +80,7 @@ Changes:
 
   * Rename Object#replace to Object#instance_replace.
   * Rename Range#to_r to Range#to_rng, since #to_r is now for Rational.  
+  * Rename Kernel#eigen to #meta.
 
 * Bug Fixes
 

data/{README.rdoc → README.md}

@@ -1,9 +1,14 @@
-= Ruby Facets
+# Ruby Facets
 
-"ALL YOUR BASE ARE BELONG TO RUBY"
+[![Gem Version](https://badge.fury.io/rb/facets.png)](http://badge.fury.io/rb/facets)
+[![Build Status](https://secure.travis-ci.org/rubyworks/facets.png)](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)
 
 
-== Introduction
+*"ALL YOUR BASE ARE BELONG TO RUBY"*
+
+
+## Introduction
 
 Ruby Facets is the premiere collection of general purpose method
 extensions and standard additions for the Ruby programming language.
@@ -21,7 +26,7 @@ libraries constitute an reliable source of reusable components, suitable
 to a wide variety of usecases.
 
 
-== Resources
+## Resources
 
 * Homepage: http://rubyworks.github.com/facets
 * Report Bugs: http://github.com/rubyworks/facets/issues
@@ -30,7 +35,7 @@ to a wide variety of usecases.
 * Source Code: http://github.com/rubyworks/facets
 
 
-== Documentation
+## Documentation
 
 Facets has special documentation needs due to its extensive breadth.
 The documentation generated when installing via RubyGems, or the YARD
@@ -40,13 +45,12 @@ 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.
+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
+## Installation
 
-=== Bundler
+### 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`
@@ -54,25 +58,25 @@ option.
 
     gem "facets", require: false
 
-=== RubyGems
+### RubyGems
 
 The easiest way to install is via RubyGems.
 
     $ gem install facets
 
-=== Setup.rb
+### Setup.rb
 
-Facets can be installed the old-fashioned way using Ruby Setup (http://rubyworks.github.com/setup).
+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 2.8+ requires Ruby 1.8.7 or higher. Facets 3.0+ requires Ruby 2.0.0 or higher.
 
 
-== Mission
+## 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
@@ -84,9 +88,9 @@ will be able to serve the community. There are a number of advantages here:
 * One-stop Shop and Installation
 
 
-== Usage
+## Usage
 
-=== CORE Library
+### 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
@@ -95,7 +99,7 @@ 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'
+    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
@@ -103,11 +107,11 @@ 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>'
+    require 'facets/<class|module>/<method>'
 
 For example:
 
-  require 'facets/time/stamp'
+    require 'facets/time/stamp'
 
 Most "atoms" contain only one method, but exceptions occur when methods
 are closely tied together.
@@ -115,7 +119,7 @@ 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'
+    require 'facets/time'
 
 Will require all the core Time method extensions.
 
@@ -124,7 +128,7 @@ 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
+#### Method File Names
 
 Operator method redirect files are stored using English names. For instance 
 `Proc#*` is `proc/op_mul`.
@@ -160,36 +164,34 @@ 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)
+### MORE Library (aka Standard Library)
 
 On top of the extensive CORE library, Facets provides extensions for Ruby's
-standard library, as well as very small collection of additional modules and
+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. This is because
-the libraries provided by Facets are fairly low-level and very general 
-purpose.
+is the lack of any enclosing `Facets::` namespace.
 
 When using Facets extended versions of Ruby's standard libraries,
-the 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.
+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'
+    require 'ostruct'
 
 To load 'ostruct.rb' plus Facets extensions for it simply use:
 
-  require 'facets/ostruct'
+    require 'facets/ostruct'
 
 For details pertaining to the functionality of each feature,
 please see the API documentation.
 
 
-== Contribute
+## Contribute
 
 This project thrives on contribution!
 
@@ -200,48 +202,46 @@ 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. And uses QED specifications to provide a higher level
-of testing along wth documentation. It is most important to provide Lemon
-tests when contributing, but feel free to provide QED specs if you are feeling
-particularly verbose!
+## Development
 
-Facets uses {Detroit}[http://detroit.github.com] and {Fire}[http://rubyworks.github.com/fire]
-build tools. Detroit is a life-cycle tool and Fire is something of a cross between Rake and
-Watchr. The build scripts (the Assembly and the `Rulefile` respectively), sometimes used other
-tools such as `mast` and `vclog`.
+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 continuous integrations tool. The build
+scripts (`Assembly` and `Rulebook` respectively), sometimes use other tools such as
+[Mast](http://rubyworks.github.com/mast) and [Indexer](http://rubyworks.github.com/indexer).
 
-== Authors
 
-This collection was put together by, and largely written by Trans. He can be
-reached via email at transfire at gmail.com.
+## Authors
 
-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, or the more liberal BSD and MIT licenses. In the one or two exceptions
-I have included the copyright notice with the source code. Any code file not
-specifically labeled othewise shall fall under the Ruby License.
+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.
+Any code file not specifically labeled othewise shall fall under the current Ruby
+License (which is BSD 2-clause).
 
-In all cases, I have made every effort to give credit where credit is due.
+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 {Contibutors page}[https://github.com/rubyworks/facets/wiki/Contributors]
+Also see the [Contibutors 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 me know and I will correct right away. Thanks.
+the list, please let us know so we can correct right away. 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
+## License
 
 The collection PER COLLECTION is licensed as follows:
 
-  Ruby Facets
-  Copyright (c) 2004,2010 Rubyworks
+    Ruby Facets
+    Copyright (c) 2004,2010 Rubyworks
 
-  Distributed under the terms of the Ruby license.
+    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).