facets 3.0.0 → 3.1.0

data/demo/core/integer/bitmask.md

@@ -0,0 +1,46 @@
+## Integer#bit
+
+    require 'facets/integer/bitmask'
+
+    0.bit(0).assert == 1
+    0.bit(1).assert == 2
+    0.bit(2).assert == 4
+    0.bit(3).assert == 8
+
+Negate
+
+    1.bit(~0).assert == 0
+    2.bit(~1).assert == 0
+    4.bit(~2).assert == 0
+    8.bit(~3).assert == 0
+
+## Integer#bit?
+
+    a = 8
+    assert(! a.bit?(0))
+    assert(! a.bit?(1))
+    assert(! a.bit?(2))
+    assert(  a.bit?(3))
+    assert(! a.bit?(4))
+    assert(! a.bit?(5))
+
+## Integer#bit_clear
+
+    1.bit_clear(0).assert == 0
+    2.bit_clear(1).assert == 0
+    4.bit_clear(2).assert == 0
+    8.bit_clear(3).assert == 0
+
+## Integer#bitmask
+
+    a =  1
+    m = Bit(4)
+    a = a.bitmask(m)
+    a.assert == 17
+    assert( a.bitmask?(m) )
+
+## Kernel#Bit
+
+    n = Bit(4)
+    n.assert == 16
+

data/demo/core/integer/{factorial.rdoc → factorial.md}

@@ -1,4 +1,4 @@
-== Integer#factorial
+## Integer#factorial
 
     require 'facets/integer/factorial'
 

data/demo/core/integer/{length.rdoc → length.md}

@@ -1,4 +1,4 @@
-== Numeric#length
+## Numeric#length
 
     require 'facets/numeric/length'
 

data/demo/core/integer/{multiple.rdoc → multiple.md}

@@ -1,7 +1,9 @@
-== Integer#multiple?
+## Integer#multiple?
 
     require 'facets/integer/multiple'
 
+Is a number an even multiple of another?
+
     1.multiple?(2)  #=> false
     5.multiple?(3)  #=> false
 

data/demo/core/integer/of.md

@@ -0,0 +1,11 @@
+## Integer#of
+
+    require 'facets/integer/of'
+
+Similar to `Enumerable#map` and `Enumerable#collect` but for a number
+of times.
+
+    a = 4
+    b = a.of{ |i| i*2 }
+    b.assert == [0,2,4,6]
+

data/demo/core/integer/{ordinal.rdoc → ordinal.md}

@@ -1,7 +1,9 @@
-= Integer#ordinal
+## Integer#ordinal
 
     require 'facets/integer/ordinal'
 
+Produce the ordinal name of a number.
+
     1.ordinal.assert == '1st'
     2.ordinal.assert == '2nd'
     3.ordinal.assert == '3rd'

data/demo/core/integer/{of.rdoc → times_collect.md}

@@ -1,14 +1,9 @@
-== Integer#of
+## Integer#times_collect
 
     require 'facets/integer/of'
 
-    a = 4
-    b = a.of{ |i| i*2 }
-    b.assert == [0,2,4,6]
-
-== Integer#times_collect
-
     a = 4
     b = a.times_collect{ |i| i*2 }
     b.assert == [0,2,4,6]
 
+See `Integer#of` which is an alias.

data/demo/core/matchdata/match.md

@@ -0,0 +1,7 @@
+## MatchData#match
+
+    require 'facets/matchdata/match'
+
+    md = /X(a)(b)(c)X/.match("YXabcXY")
+    md.match.assert == "XabcX"
+

data/demo/core/matchdata/matchset.md

@@ -0,0 +1,7 @@
+## MatchData#matchset
+
+    require 'facets/matchdata/matchset'
+
+    md = /(bb)(cc(dd))(ee)/.match "XXaabbccddeeffXX"
+    md.matchset.assert == ["XXaa", [["bb"], ["cc", ["dd"]], ["ee"]], "ffXX"]
+

data/demo/core/matchdata/matchtree.md

@@ -0,0 +1,10 @@
+## MatchData#matchtree
+
+    require 'facets/matchdata/matchtree'
+
+    md = /(bb)(cc(dd))(ee)/.match "XXaabbccddeeffXX"
+    md.matchtree.assert == [["bb"], ["cc", ["dd"]], ["ee"]]
+
+    md = /(bb)c(c(dd))(ee)/.match "XXaabbccddeeffXX"
+    md.matchtree.assert == [["bb"], "c", ["c", ["dd"]], ["ee"]]
+

data/demo/core/module/cattr.md

@@ -0,0 +1,43 @@
+## Class#cattr
+
+    require 'facets/module/cattr'
+
+    class CAttrMockObject
+      def initialize
+        @@a = 10
+      end
+      def b ; @@b ; end
+    end
+
+    Exception.refute.raised? do
+      CAttrMockObject.class_eval{ cattr :a }
+    end
+    t = CAttrMockObject.new
+    t.a.assert == 10
+
+## Class#cattr_reader
+
+    Exception.refute.raised? do
+      CAttrMockObject.class_eval { cattr_reader :a }
+    end
+    t = CAttrMockObject.new
+    t.a.assert == 10
+
+## Class#cattr_writer
+
+    Exception.refute.raised? do
+      CAttrMockObject.class_eval { cattr_writer :b }
+    end
+    t = CAttrMockObject.new
+    t.b = 5
+    t.b.assert == 5
+
+## Class#cattr_accessor
+
+    Exception.refute.raised? do
+      CAttrMockObject.class_eval { cattr_accessor :c }
+    end
+    t = CAttrMockObject.new
+    t.c = 50
+    t.c.assert == 50
+

data/demo/core/module/class_extend.md

@@ -0,0 +1,64 @@
+## Module#class_extend
+
+    require 'facets/module/class_extend'
+
+Module using class_extend
+
+    mix = Module.new do
+      def i ; end
+      class_extend do
+        def n ; 42   ; end
+        def s ; self ; end
+      end
+    end
+
+Extends module
+
+    mix.n.assert == 42
+    mix.s.assert == mix
+
+Has expected methods
+
+    mix.instance_methods.map{ |m| m.to_s }.assert == ['i']
+
+transfers class methods to including class
+
+    mod = Module.new do
+      include mix
+    end
+    mod.n.assert == 42
+    mod.s.assert == mod
+
+Doesn't overwrite instance methods
+
+    c = Class.new do
+      include mix
+      def n ; 11 ; end
+    end
+    c.new.n.assert == 11
+
+Is overridable via including module
+
+    mod = Module.new do
+      include mix
+      class_extend do
+        def n ; super + 1 ; end
+      end
+    end
+    mod.n.assert == 43  # notice the difference!
+    mod.s.assert == mod
+
+Transfers class methods thru multiple levels of include
+
+    alt = Module.new do
+      include mix
+      class_extend do
+        def n ; super + 1 ; end
+      end
+    end
+    mod = Module.new do
+      include alt
+    end
+    mod.n.assert == 43
+    mod.s.assert == mod
+

data/demo/core/module/{class_inheritor.rdoc → class_inheritor.md}

@@ -1,6 +1,6 @@
-== Module#class_inheritor
+## Module#class_inheritor
 
-  require 'facets/module/class_inheritor'
+    require 'facets/module/class_inheritor'
 
 Subclass with inheritor
 

data/demo/core/module/{copy_inheritor.rdoc → copy_inheritor.md}

@@ -1,8 +1,8 @@
-= Module#copy_inheritor
+## Module#copy_inheritor
 
-  require 'facets/module/copy_inheritor'
+    require 'facets/module/copy_inheritor'
 
-We see copy_inheritor
+We see `#copy_inheritor` in action.
 
     m = Module.new do
       copy_inheritor :koko, []
@@ -22,7 +22,7 @@ We see copy_inheritor
       koko << 4
     end
 
-copy_inheritor
+And the result.
 
     m.koko.assert  == [1]
     c1.koko.assert == [1,2,3]

data/demo/core/module/include_as.md

@@ -0,0 +1,31 @@
+## Module#include_as
+
+    require 'facets/module/include_as'
+
+Module#include_as utilizes #method_space to allow modules to be included
+within a separated namespace.
+
+    module T
+      def t ; "Tt"  ; end
+      def r ; "Tr"  ; end
+      def q ; super ; end
+    end
+
+    class N
+      def q ; "Nq" ; end
+    end
+
+    class X < N
+      include_as :test => T
+
+      def n ; test.inspect ; end
+      def m ; test.t ; end
+      def o ; test.r ; end
+    end
+
+    x = X.new
+
+    x.m.assert == "Tt"
+    x.o.assert == "Tr"
+    x.q.assert == "Nq"
+

data/demo/core/module/method_space.md

@@ -0,0 +1,24 @@
+## Module#method_space
+
+    require 'facets/module/method_space'
+
+    class A
+      attr_writer :x
+      method_space :inside do
+        def x; @x; end
+      end
+    end
+
+    a = A.new
+    a.x = 10
+
+We can see that the `inside` method space has access to the instance space.
+
+    a.inside.x  #=> 10
+
+But there is no reader in the instance space.
+
+    expect NoMethodError do
+      a.x
+    end
+

data/demo/core/string/acronym.md

@@ -0,0 +1,9 @@
+## String#acronym
+
+    require 'facets/string/acronym'
+
+Transform a string into an acronym.
+
+    'abc'.acronym.assert == 'a'
+    'abc def'.acronym.assert == 'ad'
+    'abc def ghi'.acronym.assert == 'adg'

data/demo/core/string/{align.rdoc → align.md}

@@ -1,34 +1,34 @@
-== String#align
+## String#align
 
-  require 'facets/string/align'
+    require 'facets/string/align'
 
 Align a string to a given position. This method simply delegates
 to the other three more specific align methods.
 
-  "xxx".align(:right, 9).assert == "      xxx"
-  "xxx".align(:left,  9).assert == "xxx      "
+    "xxx".align(:right, 9).assert == "      xxx"
+    "xxx".align(:left,  9).assert == "xxx      "
 
-== String#align_right
+## String#align_right
 
 Align a string to the right. The default alignment separation is
 a newline ("\n"). This can be changed as can be the padding string
 which defaults to a single space (' ').
 
-  "xxx".align_right(9).assert == "      xxx"
+    "xxx".align_right(9).assert == "      xxx"
 
-== String#align_left
+## String#align_left
 
 Align a string to the left. The default alignment separation is a
 newline ("\n"). This can be changed as can be the padding string
 which defaults to a single space (' ').
 
-  "xxx".align_left(9).assert == "xxx      "
+    "xxx".align_left(9).assert == "xxx      "
 
-== String#align_center
+## String#align_center
 
 Centers each line of a string. The default alignment separation is
 a new line ("\n"). This can be changed as can be the padding string
 which defaults to a single space (' ').
 
-  "xxx".align_center(9).assert == "   xxx   "
+    "xxx".align_center(9).assert == "   xxx   "
 

data/demo/core/string/ascii_only.md

@@ -0,0 +1,37 @@
+## String#ascii_only
+
+    require 'facets/string/ascii_only'
+
+Return a new string with non-ASCII characters removed.
+
+    'abc'.ascii_only.assert == 'abc'
+    '中文123'.ascii_only.assert == '123'
+
+Return a new string with non-ASCII characters replaced.
+
+    '中文123'.ascii_only('!').assert == '!!123'
+
+## String#ascii_only!
+
+Modifiy string with non-ASCII chracters removed.
+
+    s = 'abc'
+    s.ascii_only!
+    s.assert == 'abc'
+
+    s = '中文123'
+    s.ascii_only!
+    s.assert == '123'
+
+
+Modifiy string with non-ASCII chracters replaced.
+
+    s = 'abc'
+    s.ascii_only!('!')
+    s.assert == 'abc'
+
+    s = '中文123'
+    s.ascii_only!('!')
+    s.assert == '!!123'
+
+

data/demo/core/string/{bracket.rdoc → bracket.md}

@@ -1,16 +1,16 @@
-== String#bracket
+## String#bracket
 
-  require 'facets/string/bracket'
+    require 'facets/string/bracket'
 
-  'X'.bracket('#').assert == '#X#'
-  'X'.bracket('x','!').assert == 'xX!'
-  'X'.bracket('{','}').assert == '{X}'
-  'X'.bracket('<').assert == '<X>'
-  'X'.bracket('(').assert == '(X)'
-  'X'.bracket('[').assert == '[X]'
-  'X'.bracket('{').assert == '{X}'
+    'X'.bracket('#').assert == '#X#'
+    'X'.bracket('x','!').assert == 'xX!'
+    'X'.bracket('{','}').assert == '{X}'
+    'X'.bracket('<').assert == '<X>'
+    'X'.bracket('(').assert == '(X)'
+    'X'.bracket('[').assert == '[X]'
+    'X'.bracket('{').assert == '{X}'
 
-== String#bracket!
+## String#bracket!
 
     a = 'X' ; a.bracket!('#')
     a.assert == '#X#'