facets 3.0.0 → 3.1.0

data/CONTRIBUTE.md

@@ -1,78 +0,0 @@
-# CONTRIBUTING TO FACETS
-
-* 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's not happening.)
-
-* 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 either via a Lemon unit test or a QED demo,
-  preferably both. 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.
-  All of the core library is loaded by default when using `require 'facets'`
-  (actually, almost all). The standard library (sometimes 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'`.
-
-* 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 tirck. 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!
-
-* When making a commit, if the commit is only a documentation change, then
-  and `[doc]` to the end of the first line of commit message. If it is only
-  a change to tests then add `[test]`. If the change only effects build files
-  then add `[admin]`. For actual code changes, if the change is not somethng
-  anyone would notice, use `[tweak]` or `[minor]` (minor being slightly more
-  improtant than tweak). For typical code changes no comment tag is necessary.
-  If the change fixes a bug that was reported via the issue system be sure to
-  reference the issue id in the message using `#` and add `[bug]`. If a change
-  is a significant change to the API, then end the message with `[major]`.
-  These are all rules of thumb, and no 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 creeped 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
-interoperabiltiy 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).
-
-Offically we publish documentation via rubydoc.info, which is the YARD server,
-and via the Facets website in Shomen JSON format.
-
-When writting documentation for a method it is best to give a simple summary 
-explaination, followed by some basic examples. Follow that up with deeper
-explaination if needed, including *when* and *why* the method could be useful.
-

data/demo/core/array/combination.rdoc

@@ -1,19 +0,0 @@
-== Array#combination
-
-  require 'facets/array/combination'
-
-finds pairs of combinations
-
-  e = [[1, 2], [1, 3], [1, 4], [2, 3], [2, 4], [3, 4]]
-  a = [1,2,3,4]
-  r = a.combination(2).to_a
-  r.assert == e
-
-can also take a block
-
-  e = [[1,2],[1,3],[1,4],[2,3],[2,4],[3,4]]
-  r = []
-  a = [1,2,3,4]
-  a.combination(2){ |a,b| r << [a,b] }
-  r.assert == e
-

data/demo/core/array/delete.rdoc

@@ -1,23 +0,0 @@
-== Array#delete_unless
-
-  require 'facets/array/delete'
-
-  a = [1,2,3]
-  a.delete_unless{ |e| e == 2 }
-  a.assert == [2]
-
-== Array#delete_values
-
-  a = [1,2,3,4]
-  a.delete_values(1,2).assert == [1,2]
-  a.assert == [3,4]
-
-== Array#delete_values_at
-
-  a = [1,2,3,4]
-  a.delete_values_at(1,2).assert == [2,3]
-  a.assert == [1,4]
-  a = [1,2,3,4]
-  a.delete_values_at(0..2).assert == [1,2,3]
-  a.assert == [4]
-

data/demo/core/array/index.rdoc

@@ -1,14 +0,0 @@
-== Array#index
-
-  require 'facets/array/index'
-
-can handle a block
-
-  i = [1,2,3].index{ |e| e == 2 }
-  i.assert == 1
-
-when no element is found
-
-  i = [1,2,3].index{ |e| e == 5 }
-  i.assert.nil?
-

data/demo/core/array/merge.rdoc

@@ -1,15 +0,0 @@
-== Array#merge
-
-  require 'facets/array/merge'
-
-  a = [1,2,3]
-  b = [3,4,5]
-  a.merge(b).assert == [1,2,3,4,5]
-
-== Array#merge!
-
-  a = [1,2,3]
-  b = [3,4,5]
-  a.merge!(b)
-  a.assert == [1,2,3,4,5]
-

data/demo/core/array/only.rdoc

@@ -1,9 +0,0 @@
-== Array#only
-
-  require 'facets/array/only'
-
-  [5].only.assert == 5
-  [nil].only.assert == nil
-  expect(IndexError){ [].only }
-  expect(IndexError){ [1,2,3].only }
-

data/demo/core/array/pad.rdoc

@@ -1,28 +0,0 @@
-== Array#pad
-
-  require 'facets/array/pad'
-
-  r = [0,1,2,3].pad(7,"x")
-  x = [0,1,2,3,"x","x","x"]
-  r.assert == x
-
-negative index
-
-  r = [0,1,2,3].pad(-7,"n")
-  x = ["n","n","n",0,1,2,3]
-  r.assert == x
-
-== Array#pad!
-
-  a = [0,1,2,3]
-  r = a.pad!(6,"y")
-  x = [0,1,2,3,"y","y"]
-  r.assert == x
-
-negative index
-
-  a = [0,1,2,3]
-  r = a.pad!(-6,"q")
-  x = ["q","q",0,1,2,3]
-  r.assert == x
-

data/demo/core/array/permutation.rdoc

@@ -1,10 +0,0 @@
-== Array#permutation
-
-  require 'facets/array/permutation'
-  require 'set'
-
-  r = Set.new
-  %w[a b c].permutation{ |x| r << x.join('') }
-  x = Set.new(['abc','acb','bac','bca','cab','cba'])
-  r.assert == x
-

data/demo/core/array/product.rdoc

@@ -1,26 +0,0 @@
-== Array#product
-
-  require 'facets/array/product'
-
-single argument
-
-  r = [1,2,3].product([4,5,6])
-  x = [[1, 4],[1, 5],[1, 6],[2, 4],[2, 5],[2, 6],[3, 4],[3, 5],[3, 6]]
-  r.assert == x
-
-multiple arguments
-
-  a = %w|a b|
-  b = %w|a x|
-  c = %w|x y|
-  r = a.product(b, c)
-  x = [ ["a", "a", "x"],
-        ["a", "a", "y"],
-        ["a", "x", "x"],
-        ["a", "x", "y"],
-        ["b", "a", "x"],
-        ["b", "a", "y"],
-        ["b", "x", "x"],
-        ["b", "x", "y"] ]
-  r.assert == x
-

data/demo/core/array/recursively.rdoc

@@ -1,16 +0,0 @@
-== Array#recursive
-
-  require 'facets/array/recursively'
-
-each
-
-  r = []
-  [1,2,['a','b']].recursively.each{ |v| r << v }
-  r.assert == [1,2,'a','b']
-
-
-map
-
-  r = [1,2,['a','b']].recursively.map{ |v| v.succ }
-  r.assert == [2,3,['b','c']]
-

data/demo/core/array/rotate.rdoc

@@ -1,30 +0,0 @@
-== Array#rotate
-
-  require 'facets/array/rotate'
-
-clockwise
-
-  a = [1,2,3]
-  r = a.rotate
-  r.assert == [2,3,1]
-
-counter-clockwise
-
-  a = [1,2,3]
-  r = a.rotate(-1)
-  r.assert == [3,1,2]
-
-== Array#rotate!
-
-clockwise
-
-  a = [1,2,3]
-  a.rotate!
-  a.assert == [2,3,1]
-
-counter-clockwise
-
-  a = [1,2,3]
-  a.rotate!(-1)
-  a.assert == [3,1,2]
-

data/demo/core/array/select.rdoc

@@ -1,8 +0,0 @@
-== Array#select
-
-  require 'facets/array/select'
-
-  a = [1,2,3,4,5,6,7,8,9,10]
-  a.select!{ |e| e % 2 == 0 }
-  a.assert == [2,4,6,8,10]
-

data/demo/core/array/uniq_by.rdoc

@@ -1,9 +0,0 @@
-== Array#uniq_by!
-
-  require 'facets/array/uniq_by'
-
-  e = [-5, -4, -3, -2, -1, 0]
-  r = (-5..5).to_a
-  r.uniq_by!{ |i| i*i }
-  r.assert == e
-

data/demo/core/binding/caller.rdoc

@@ -1,57 +0,0 @@
-The caller.rb script includes a few related methods.
-We will use the following code to demonstrate their use.
-
-  require 'facets/binding/caller'
-
-  a = 1
-  b = 2
-  x = "hello"
-  
-  @bind = binding
-  @line = __LINE__  # the line number must be updated if it moves
-  @file = __FILE__  # why does it equal basename only?
-
-== Binding#caller
-
-  @bind.caller
-
-== Binding#callstack
-
-  @bind.callstack.assert.is_a?(Array)
-
-== Binding#__LINE__
-
-  @bind.__LINE__.assert == @line - 1
-
-== Binding#__FILE__
-
-  @bind.__FILE__.assert == @file
-
-== Binding#__DIR__
-
-  @bind.__DIR__.assert == File.dirname(@file)
-
-== Binding#__callee__
-
-This only works for certain versions.
-
-  def alternate_callee
-    binding
-  end
-
-  unless RUBY_VERSION < "1.9"
-    alternate_callee.__callee__.assert == :alternate_callee
-  end
-
-== Binding#__method__
-
-This only works for certain versions.
-
-  def alternate_method
-    binding
-  end
-
-  unless RUBY_VERSION < "1.8.7"
-    alternate_method.__method__.assert == :alternate_method
-  end
-

data/demo/core/binding/defined.rdoc

@@ -1,10 +0,0 @@
-== Binding#defined?
-
-  require 'facets/binding/defined'
-
-  a = 1
-  b = 2
-  x = "hello"
-
-  binding.assert.defined?("x")
-

data/demo/core/binding/eval.rdoc

@@ -1,8 +0,0 @@
-== Binding#eval
-
-  require 'facets/binding/eval'
-
-  x = "hello"
-
-  binding.eval("x").assert == "hello"
-

data/demo/core/binding/local_variables.rdoc

@@ -1,26 +0,0 @@
-== Binding#local_variables
-
-  require 'facets/binding/local_variables'
-
-  a = 1
-  b = 2
-  x = "hello"
-
-  unless RUBY_VERSION > "1.9"
-
-    lvars = binding.local_variables
-
-    lvars.assert.include?('a')
-    lvars.assert.include?('b')
-    lvars.assert.include?('x')
-
-  else
-
-    lvars = binding.local_variables
-
-    lvars.assert.include?(:a)
-    lvars.assert.include?(:b)
-    lvars.assert.include?(:x)
-
-  end
-

data/demo/core/binding/opvars.rdoc

@@ -1,16 +0,0 @@
-== Binding#[]
-
-  require 'facets/binding/op'
-
-  a = 1
-  b = 2
-  x = "hello"
-
-  binding["x"].assert == "hello"
-
-== Binding#[]=
-
-  binding["x"] = "goodbye"
-
-  binding["x"].assert == "goodbye"
-

data/demo/core/binding/self.rdoc

@@ -1,6 +0,0 @@
-== Binding#self
-
-  require 'facets/binding/self'
-
-  binding.self == self
-

data/demo/core/class/descendants.rdoc

@@ -1,10 +0,0 @@
-== Class#descendants
-
-  require 'facets/class/descendants'
-
-  a = Class.new
-  b = Class.new(a)
-  c = Class.new(b)
-
-  a.descendants.assert == [b,c]
-