facets 3.0.0 → 3.1.0

data/demo/core/binding/opvars.md

@@ -0,0 +1,16 @@
+## 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.md

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

data/demo/core/class/descendants.md

@@ -0,0 +1,13 @@
+## Class#descendants
+
+    require 'facets/class/descendants'
+
+The `Class#descendants` method returns a list of classes that are subclasses
+of a class.
+
+    a = Class.new
+    b = Class.new(a)
+    c = Class.new(b)
+
+    a.descendants.assert == [b,c]
+

data/demo/core/class/to_proc.md

@@ -0,0 +1,11 @@
+## Class#to_proc
+
+    require 'facets/class/to_proc'
+
+The `Class#to_proc` method provides a convenient way to create new
+instances from a set of initialization data.
+
+    person = Struct.new(:name)
+    people = ["joe"].map(&person)
+    people[0].name.assert == "joe"
+

data/demo/core/comparable/at_least.md

@@ -0,0 +1,11 @@
+## Comparable#at_least
+
+    require 'facets/comparable/at_least'
+
+Limits a number to at least a given amount.
+
+    3.at_least(4).assert == 4
+    4.at_least(4).assert == 4
+    5.at_least(4).assert == 5
+
+This is similar to `#clip`.

data/demo/core/comparable/at_most.md

@@ -0,0 +1,11 @@
+## Comparable#at_most
+
+    require 'facets/comparable/at_most'
+
+Limits a number to at most a given amount.
+
+    3.at_most(4).assert == 3
+    4.at_most(4).assert == 4
+    5.at_most(4).assert == 4
+
+This is similar to `#cap`.

data/demo/core/comparable/bound.md

@@ -0,0 +1,13 @@
+## Comparable#bound
+
+    require 'facets/comparable/bound'
+
+The `#bound` method is an alias for `#clip`. It is the original name
+of the method before the `clip`/`cap` duo was decided upon.
+
+    3.bound(4).assert == 4
+
+    4.bound(3,5).assert == 4
+
+    'd'.bound('c','e').assert == 'd'
+

data/demo/core/comparable/cap.md

@@ -0,0 +1,11 @@
+## Comparable#cap
+
+    require 'facets/comparable/cap'
+
+Put a cap on what a number can be.
+
+    3.cap(4).assert == 3
+    4.cap(4).assert == 4
+    5.cap(4).assert == 4
+
+This is very similar to `#at_most`.

data/demo/core/comparable/clip.md

@@ -0,0 +1,29 @@
+## Comparable#clip
+
+    require 'facets/comparable/clip'
+
+Given a single argument `#clip` behaves like `#at_least`.
+
+    3.clip(4).assert == 4
+    4.clip(4).assert == 4
+    5.clip(4).assert == 5
+
+With two arguments `#clip` puts both a lower and an upper limit
+on the return value.
+
+    4.clip(3,5).assert == 4
+    3.clip(3,5).assert == 3
+    5.clip(3,5).assert == 5
+    2.clip(3,5).assert == 3
+    6.clip(3,5).assert == 5
+
+This almost works on characters (using ASCII order).
+
+    'd'.clip('c','e').assert == 'd'
+    'c'.clip('c','e').assert == 'c'
+    'e'.clip('c','e').assert == 'e'
+    'b'.clip('c','e').assert == 'c'
+    'f'.clip('c','e').assert == 'e'
+
+This method is aliases as `bound`.
+

data/demo/core/comparable/cmp.md

@@ -0,0 +1,18 @@
+## Comparable#cmp
+
+    require 'facets/comparable/cmp'
+
+On integers
+
+    3.cmp(4).assert == -1
+    3.cmp(3).assert ==  0
+    3.cmp(2).assert ==  1
+
+On strings
+
+    "abc".cmp("abc").assert == 0
+    "abc".cmp("abcd").assert == -1
+    "abcd".cmp("abc").assert ==  1
+    "abc".cmp("bcd").assert == -1
+    "bcd".cmp("abc").assert ==  1
+

data/demo/core/comparable/op_get.md

@@ -0,0 +1,32 @@
+## Comparable.[]
+
+    require 'facets/comparable/op_get'
+
+Allows `Comparable` to be included as a *parmetric mixin*. This makes it easy to define
+a class as comparable on a limited set of attributes.
+
+    c = Class.new do
+      include Comparable[:a,:b]
+
+      attr_accessor :a, :b
+
+      def initialize(a,b)
+        @a=a; @b=b
+      end
+    end
+
+    a = [c.new(10,20),c.new(10,30)]
+    a.sort.assert == a
+
+    a = [c.new(10,30),c.new(10,20)]
+    a.sort.assert == a.reverse
+
+    a = [c.new(10,10),c.new(20,10)]
+    a.sort.assert == a
+
+    a = [c.new(20,10),c.new(10,10)]
+    a.sort.assert == a.reverse
+
+    a = [c.new(10,30),c.new(20,10)]
+    a.sort.assert == a
+

data/demo/core/dir/ascend.md

@@ -0,0 +1,24 @@
+## Dir#ascend
+
+    require 'facets/dir/ascend'
+
+    path = 'A/B/C'
+
+    tmp = []
+
+    Dir.ascend(path) do |d|
+      tmp << d
+    end
+
+    tmp.assert == %w{A/B/C A/B A}
+
+Exclude current path.
+
+    tmp = []
+
+    Dir.ascend(path, false) do |d|
+      tmp << d
+    end
+    
+    tmp.assert == %w{A/B A}
+

data/demo/core/dir/descend.md

@@ -0,0 +1,16 @@
+## Dir#descend
+
+    require 'facets/dir/descend'
+
+Descend thru a file path.
+
+    path = 'A/B/C'
+
+    tmp = []
+
+    Dir.descend(path) do |d|
+      tmp << d
+    end
+
+    tmp.assert == %w{A A/B A/B/C}
+

data/demo/core/dir/multiglob.md

@@ -0,0 +1,41 @@
+## Dir#multiglob
+
+Dir#multglob is like Dir#glob but it can handle more than one match
+parameter at a time.
+
+Given a directory 'multiglob' containing:
+
+    A.txt
+    A/B.txt
+    A/B/C.txt
+
+We can use #multglob to find multiple matches.
+
+    require 'facets/dir/multiglob'
+
+    x = %w{
+      multiglob/A
+      multiglob/A.txt
+    }
+
+    r = Dir.multiglob('multiglob/A', 'multiglob/A.*').sort
+
+    r.assert == x
+
+## Dir#multiglob_r
+
+Dir#multiglob_r is like #multiglob but automatically searches
+directories recrusively.
+
+    x = %w{
+      multiglob/A 
+      multiglob/A/B
+      multiglob/A.txt
+      multiglob/A/B.txt
+      multiglob/A/B/C.txt
+    }.sort
+
+    r = Dir.multiglob_r('multiglob/*').sort
+
+    r.assert == x
+

data/demo/core/dir/parent.md

@@ -0,0 +1,6 @@
+## Dir#parent
+
+    require 'facets/dir/parent'
+
+    Dir.assert.parent?("a/b/c", "a/b/c/d")
+

data/demo/core/dir/recurse.md

@@ -0,0 +1,41 @@
+## Dir#recurse
+
+Given a directory 'recurse' containing:
+
+    A.txt
+    A/B.txt
+    A/B/C.txt
+
+We can use #recurse to gather a complete recursive
+list of all the entries.
+
+    require 'facets/dir/recurse'
+
+    x = %w{
+      recurse/A
+      recurse/A.txt
+      recurse/A/B
+      recurse/A/B.txt
+      recurse/A/B/C.txt
+    }.sort
+
+    r = Dir.recurse('recurse').sort
+
+    r.assert == x
+
+## Dir#ls_r
+
+Dir#ls_r is an alias for #recurse which can also be used to gather
+a complete recursive list of all the entries.
+
+    x = %w{
+      recurse/A
+      recurse/A.txt
+      recurse/A/B
+      recurse/A/B.txt
+      recurse/A/B/C.txt
+    }.sort
+
+    r = Dir.ls_r('recurse').sort
+
+    r.assert == x

data/demo/core/exception/detail.md

@@ -0,0 +1,19 @@
+## Exception#detail
+
+    require 'facets/exception/detail'
+
+Provides a more detailed error message.
+
+    begin
+      raise ArgumentError
+    rescue ArgumentError => err
+      r = err.detail
+      r.assert.include?('ArgumentError')
+    end
+
+The output of `#detail` looks something like this:
+
+    ArgumentError: ArgumentError
+      example.rb:4:in `<main>'
+      LOGGED FROM: example.rb:6:in `rescue in <main>'
+

data/demo/core/{facets.rdoc → facets.md}

@@ -1,4 +1,4 @@
-= Requiring Facets
+# Requiring Facets
 
 We should be able to require all the core libraries by simply calling,
 

data/demo/core/filetest/root.md

@@ -0,0 +1,13 @@
+## FileTest#root?
+
+    require 'facets/filetest/root'
+
+Returns true if the given directory is the file system root.
+Obviously on a Linux system them means `/`.
+
+    FileTest.assert.root?('/')
+
+Anything else will return false.
+
+    FileTest.refute.root?('/home')
+

data/demo/core/hash/recursively.md

@@ -0,0 +1,21 @@
+## Hash#recursively
+
+    require 'facets/hash/recursively'
+
+    h = {:a=>1, :b=>{:c=>3}}
+
+Without a block passed to the `#recursively` method, the block passed to the
+enumeratig method will be used for both recursive and non-recursive yields.
+
+    r = h.recursively.map{ |k,v| [k.to_s, v] }
+
+    r.assert == [['a', 1], ['b', [['c', 3]]]]
+
+But if we pass a block to `#recursively` we can treat the recusive yield 
+separately, which in turn allows us to manipulate the non-recursive
+yields with a different procedure.
+
+    r = h.recursively{ |k,v| [k.to_s, v] }.map{ |k,v| [k.to_s,v.to_s] }
+
+    r.assert == [['a','1'], ['b', [['c', '3']]]]
+

data/demo/core/indexable.md

@@ -0,0 +1,95 @@
+# Indexable
+
+Indexable it a module, like Enumerable, but provides methods specific
+to an indexable collection. The Indexable module can be used independently,
+but Facets can also automatically use it to extend Array.
+
+    require 'facets/array/indexable'
+
+## Indexable#head
+
+    a = [1,2,3,4,5]
+    a.head.assert = [1]
+
+## Indexable#tail
+
+    a = [1,2,3,4,5]
+    a.tail.assert = [2,3,4,5]
+
+## Indexable#foot
+
+    a = [1,2,3,4,5]
+    a.foot.assert = [5]
+
+## Indexable#body
+
+    a = [1,2,3,4,5]
+    a.body.assert = [1,2,3,4]
+
+## Indexable#mid
+
+    a = [1,2,3,4,5]
+    b = [1,2,3,4,5,6]
+    a.mid.assert = 3
+    b.mid.assert = 4
+    a.mid(1).assert = 4
+    b.mid(1).assert = 5
+    b.mid(2).assert = 6
+    b.mid(-1).assert = 3
+
+## Indexable#middle
+
+    a = [1,2,3,4,5]
+    b = [1,2,3,4,5,6]
+    a.middle.assert = [3]
+    b.middle.assert = [3,4]
+
+## Indexable#thru
+
+    [0,1,2,3,4,5].thru(2,4).assert = [2,3,4]
+    [0,1,2,3,4,5].thru(0,1).assert = [0,1]
+
+## Indexable#first=
+
+    a = [1,2]
+    a.first = 0
+    a.assert = [0,2]
+
+## Indexable#last=
+
+    a = [1,2]
+    a.last = 3
+    a.assert = [1,3]
+
+## Indexable#ends
+
+    [1,2,3,4,5].ends.assert = 4
+
+## Indexable#pos
+
+    a = [1,2,3,4,5]
+    a.pos(1).assert = 0
+    a.pos(-1).assert = 4
+
+## Indexable#range
+
+    a = [1,2,3,4,5]
+    b = [1,2,3,4,5,6]
+    a.range.assert = (0..4)
+    b.range.assert = (0..5)
+    a.range(2,4).assert = (1..3)
+    b.range(2,3).assert = (1..2)
+    b.range(4,2).assert = (3..1)
+
+## Indexable#first!
+
+    a = [1,2,3]
+    a.first!.assert = 1
+    a.assert = [2,3]
+
+## Indexable#last!
+
+    a = [1,2,3]
+    a.last!.assert = 3
+    a.assert = [1,2]
+