safebool 1.0.0 → 1.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e5a56c5aa20a4d11dd6ce2ebba0546355956cf02
-  data.tar.gz: d2e2851c0a079a483bb3521f4904492b010eb1e5
+  metadata.gz: 3259e4df2ebfb2f5359249c7d1fc87dbb03c23d3
+  data.tar.gz: 8357baa33140416175df3b652581a30a381e0d9e
 SHA512:
-  metadata.gz: c1f80ebf778f848f3db67011ef045d92ffba850f7b67e9fb4565d8851567597bad4715a30246796a43056c4bb0138de182cfccad455e7acaf24407dac7d3f716
-  data.tar.gz: a95229a84ee2dd89555e09885320a22b2daae5cf38d279f59e63005969466419c0642ff5859127fec50467194c206b819b5684bf9616843ba0a859f5f5f1f204
+  metadata.gz: 12332af592e5acda2b25cfc6919c281c304fa0ed82f3804dab36736c32476e74d9cbc2c5d7f807b111f2fbc72cd210fa6858a0feb5ff2ef3b051aa7c633bfb68
+  data.tar.gz: ff2e864c3b041f56b78be5ef1a1342984487affd5d56b8ef440c495fd69889b4a75c7bdb701e9980c36d49c5b9481747a5eec25c54338d5666ad20c5b1438705

data/README.md

@@ -2,7 +2,7 @@
 # Safe Bool Type - `Bool()`, `to_b`, `to_bool`, and More
 
 
-safebool gem / library - safe bool(ean) type adds `Bool()`, `to_b`, `to_bool`, `bool?`, `false?`, `true?`, `true.is_a?(Bool)==true`, `false.is_a?(Bool)==true`, and more
+safebool gem / library - safe bool / boolean type adds `Bool()`, `to_b`, `parse_bool` / `to_bool`, `bool?`, `false?`, `true?`, `true.is_a?(Bool)==true`, `false.is_a?(Bool)==true`, and more
 
 
 * home  :: [github.com/s6ruby/safebool](https://github.com/s6ruby/safebool)
@@ -25,10 +25,25 @@ false.class.ancestors #=> [FalseClass, Object, Kernel, BasicObject]
 
 # -or-
 
+false.to_s            #=> "false"
+true.to_s             #=> "true"
+false.to_i            #=> NoMethodError: undefined method `to_i' for false:FalseClass
+true.to_i             #=> NoMethodError: undefined method `to_i' for true:TrueClass
+Integer(false)        #=> TypeError: can't convert false into Integer
+Integer(true)         #=> TypeError: can't convert true into Integer
+
+# -or-
+
+"false".to_b          #=> NoMethodError: undefined method `to_b' for String
+0.to_b                #=> NoMethodError: undefined method `to_b' for Integer
+Bool("false")         #=> NoMethodError: undefined method `Bool' for Kernel
+Bool(0)               #=> NoMethodError: undefined method `Bool' for Kernel
+
 "true".to_b           #=> NoMethodError: undefined method `to_b' for String
 1.to_b                #=> NoMethodError: undefined method `to_b' for Integer
 Bool("true")          #=> NoMethodError: undefined method `Bool' for Kernel
 Bool(1)               #=> NoMethodError: undefined method `Bool' for Kernel
+
 ...
 ```
 
@@ -38,6 +53,13 @@ Why? Why not? Discuss.
 
 ## Usage
 
+[String](#string)  •
+[Symbol](#symbol)   •
+[Integer](#integer)   •
+[Kernel](#kernel)
+
+
+
 ``` ruby
 false.is_a?(Bool)     #=> true
 true.is_a?(Bool)      #=> true
@@ -46,35 +68,168 @@ false.class.ancestors #=> [FalseClass, Bool, Object, Kernel, BasicObject]
 
 # -or-
 
-"true".to_b           #=> true
-1.to_b                #=> true
-Bool("true")          #=> true
-Bool(1)               #=> true
+false.to_i            #=> 0
+true.to_i             #=> 1
+
+# -or-
 
 "false".to_b          #=> false
 0.to_b                #=> false
 Bool("false")         #=> false
 Bool(0)               #=> false
+
+"true".to_b           #=> true
+1.to_b                #=> true
+Bool("true")          #=> true
+Bool(1)               #=> true
 ```
 
+
 How about handling errors on invalid bool values when converting / parsing?
 
-1. `to_b` always return a bool even if the conversion / parsing failed e.g. `true` (for numbers) and `false` (for strings) on error
-2. `parse_bool/to_bool` always returns `nil` if the conversion / parsing failed
-3. `Bool()` always raises a `TypeError` if the conversion / parsing failed
+1. `to_b` always returns a bool even if the conversion / parsing fails e.g. `true` (for numbers) and `false` (for strings) on error
+2. `parse_bool / to_bool` always returns `nil` if the conversion / parsing fails
+3. `Bool()` always raises an `ArgumentError` if the conversion / parsing fails
+   and a `TypeError` if the conversion is unsupported (e.g. expected required `parse_bool` method missing / undefined)
 
 
 ``` ruby
-"2".to_b              #=> false
-"2".to_bool           #=> nil
-2.to_b                #=> true
-2.to_bool             #=> nil     
-Bool("2")             #=> TypeError: cannot convert "2":String to Bool; method parse_bool/to_bool expected
-Bool(2)               #=> TypeError: cannot convert 2:Fixnum to Bool; method parse_bool/to_bool expected
+"2".to_b                #=> false
+"2".to_bool             #=> nil
+"2".to_bool.bool?       #=> false
+"2".to_bool.is_a?(Bool) #=> false
+Bool("2")               #=> ArgumentError: invalid value "2":String for Bool(); parse_bool failed (returns nil)
+
+2.to_b                  #=> true
+2.to_bool               #=> nil
+2.to_bool.bool?         #=> false
+2.to_bool.is_a?(Bool)   #=> false
+Bool(2)                 #=> ArgumentError: invalid value 2:Integer for Bool(); parse_bool failed (returns nil)
 ...
 ```
 
 
+### String
+
+- Returns `true` if string is one of these values: **t**, **true**, **on**, **y**, **yes**, **1**.
+- Returns `false` if string is one of these values: **f**, **false**, **off**, **n**, **no**, **0**.
+
+For invalid boolean string values `to_b` returns `false` by default.
+See the "Handling Errors" section for more options.
+
+Note: The `Bool.parse` method ignores leading and trailing spaces and upper and lower cases e.g. ` FaLSe ` is the same as `false`.
+
+```ruby
+'1'.to_b        #=> true
+'t'.to_b        #=> true
+'T'.to_b        #=> true
+'true'.to_b     #=> true
+'TRUE'.to_b     #=> true
+'on'.to_b       #=> true
+'ON'.to_b       #=> true
+'y'.to_b        #=> true
+'yes'.to_b      #=> true
+'YES'.to_b      #=> true
+
+' 1 '.to_b      #=> true
+' t '.to_b      #=> true
+' T '.to_b      #=> true
+' true '.to_b   #=> true
+' TRUE '.to_b   #=> true
+' on '.to_b     #=> true
+' ON '.to_b     #=> true
+' y '.to_b      #=> true
+'Y'.to_b        #=> true
+' Y '.to_b      #=> true
+' yes '.to_b    #=> true
+' YES '.to_b    #=> true
+
+'0'.to_b        #=> false
+'f'.to_b        #=> false
+'F'.to_b        #=> false
+'false'.to_b    #=> false
+'FALSE'.to_b    #=> false
+'off'.to_b      #=> false
+'OFF'.to_b      #=> false
+'n'.to_b        #=> false
+'N'.to_b        #=> false
+'no'.to_b       #=> false
+'NO'.to_b       #=> false
+
+' 0 '.to_b      #=> false
+' f '.to_b      #=> false
+' F '.to_b      #=> false
+' false '.to_b  #=> false
+' FALSE '.to_b  #=> false
+' off '.to_b    #=> false
+' OFF '.to_b    #=> false
+' n '.to_b      #=> false
+' N '.to_b      #=> false
+' no '.to_b     #=> false
+' NO '.to_b     #=> false
+
+''.to_b         #=> false
+' '.to_b        #=> false
+'xxx'.to_b      #=> false
+'bool'.to_b     #=> false
+
+''.to_bool      #=> nil
+' '.to_bool     #=> nil
+'xxx'.to_bool   #=> nil
+'bool'.to_bool  #=> nil
+```
+
+### Symbol
+
+Same as `self.to_s.to_b` or `self.to_s.to_bool`.
+
+``` ruby
+:'1'.to_b      #=> true
+:t.to_b        #=> true
+:true.to_b     #=> true
+:on.to_b       #=> true
+:y.to_b        #=> true
+:yes.to_b      #=> true
+
+:'0'.to_b      #=> false
+:f.to_b        #=> false
+:false.to_b    #=> false
+:off.to_b      #=> false
+:n.to_b        #=> false
+:no.to_b       #=> false
+
+:xxx.to_b      #=> false
+:bool.to_b     #=> false
+
+:xxx.to_bool   #=> nil
+:bool.to_bool  #=> nil
+```
+
+
+
+
+### Integer
+
+Returns `false` if the number is zero and `true` otherwise.
+
+
+```ruby
+0.to_b      #=> false
+1.to_b      #=> true
+2.to_b      #=> true
+-1.to_b     #=> true
+-2.to_b     #=> true
+
+0.to_bool   #=> false
+1.to_bool   #=> true
+
+2.to_bool   #=> nil
+-1.to_bool  #=> nil
+-2.to_bool  #=> nil
+```
+
+
+### Kernel
 
 More methods added to `Kernel` include `bool?`, `false?`, `true?`.
 Example:

data/Rakefile

@@ -5,7 +5,7 @@ Hoe.spec 'safebool' do
 
   self.version = SaferBool::VERSION
 
-  self.summary = "safebool - safe bool(ean) type adds Bool(), to_b, to_bool, bool?, false?, true?, true.is_a?(Bool)==true, false.is_a?(Bool)==true, and more"
+  self.summary = "safebool - safe bool / boolean type adds Bool(), to_b, parse_bool / to_bool, bool?, false?, true?, true.is_a?(Bool)==true, false.is_a?(Bool)==true, and more"
   self.description = summary
 
   self.urls    = ['https://github.com/s6ruby/safebool']

data/lib/safebool.rb

@@ -30,27 +30,22 @@ module Bool
 
 
   def self.convert( o )   ## used by "global" Bool( o ) kernel conversion method
-    value = if o.respond_to?( :to_bool )
-              o.to_bool     # returns true/false/nil
-            elsif o.respond_to?( :parse_bool )  ## check parse_bool alias
-              o.parse_bool  # returns true/false/nil
-            else
-              nil
-            end
-
-    if value.nil?
-      raise TypeError.new( "cannot convert >#{o.inspect}< of type >#{o.class.name}< to Bool; method parse_bool/to_bool expected")
-    else
+    if o.respond_to?( :parse_bool )
+      value = o.parse_bool()  # note: returns true/false OR nil
+      if value.nil?
+        raise ArgumentError.new( "invalid value >#{o.inspect}< of type >#{o.class.name}< for Bool(); method parse_bool failed (returns nil)")
+      end
       value
+    else
+      raise TypeError.new( "can't convert >#{o.inspect}< of type >#{o.class.name}< to Bool; method parse_bool expected / missing")
     end
   end
 
-  def self.zero() false; end   ## note: false.frozen? == true by default
+  def self.zero() false; end
 
 
   def to_b()       self; end
   def parse_bool() self; end
-  alias_method :to_bool, :parse_bool
 end # module Bool
 
 
@@ -59,12 +54,21 @@ class FalseClass
   include Bool     ## "hack" - enables false.is_a?(Bool)
 
   def zero?() true; end
+  def to_i()  0; end
+
+  ## note: include Bool does NOT include module function (e.g. self.zero, etc.)
+  ##   todo/check/discuss - also include self.parse - why? why not?
+  def self.zero() false; end     ## lets you write:  false.class.zero
 end
 
 class TrueClass
   include Bool    ## "hack" - enables true.is_a?(Bool)
 
   def zero?() false; end
+  def to_i()  1; end
+
+  ## note: include Bool does NOT include module function (e.g. self.zero, etc.)
+  def self.zero() false; end   ## lets you write:  true.class.zero
 end
 
 
@@ -100,10 +104,29 @@ module Kernel
 
 
   #####
-  #   default "explicit" conversion to bool for all objects
-  def to_b() self ? true : false; end
+  #  default "explicit" conversion to bool for all objects
+  def to_b
+    if respond_to?( :parse_bool )
+      value = parse_bool()         # note: returns true/false/nil  (nil for error/cannot parse)
+      value = true  if value.nil?  #         default nil (cannot parse to bool) to true
+      value
+    else
+      self ? true : false    ## use "standard" ruby semantics, that is, everything is true except false & nil
+    end
+  end
 
 
+  # to_bool - "porcelain" method "alias" for parse_bool; use parse_bool for "internal" use and to_bool for "external" use
+  # note: by "default" the method parse_bool is undefined (!);
+  #         define parse_bool in concrete / derived class to add bool conversion support
+  def to_bool()
+    if respond_to?( :parse_bool )
+      parse_bool()
+    else
+      nil   ## note: returns nil if can't convert to true or false
+    end
+  end
+
   ### "global" conversion function / method
   def Bool( o ) Bool.convert( o ); end
 end
@@ -111,44 +134,41 @@ end
 
 
 class NilClass
-  def to_b() false; end
+  def to_b()       false; end
   def parse_bool() false; end
-  alias_method :to_bool, :parse_bool
 end
 
 class String
   def to_b
     value = parse_bool()
-    value.nil? ? false : value   ## note return false for all undefined / unknown string values
+    value = false  if value.nil?   ## note: return false (!) for all undefined / unknown string values that cannot convert to bool
+    value
   end
   def parse_bool() Bool.parse( self ); end
-  alias_method :to_bool, :parse_bool
 end
 
 class Symbol
-  def to_b() to_s.to_b; end
+  def to_b()       to_s.to_b; end
   def parse_bool() to_s.parse_bool(); end
-  alias_method :to_bool, :parse_bool
 end
 
-class Numeric
-  def to_b()
+class Integer
+  def to_b
     value = parse_bool()
-    value.nil? ? true : value   ## note return **true** for all undefined / unknown number/numeric values
+    value = true  if value.nil?   ## note return true for all undefined / unknown number/numeric values that cannot convert to bool
+    value
   end
-  def parse_bool()
+  def parse_bool
     if self == 0
       false
     elsif self == 1
       true
     else
-      nil  ## note: returns nil if cannot convert to true or false
+      nil  ## note: returns nil if can't convert to true or false
     end
   end
-  alias_method :to_bool, :parse_bool
 end
 
 
 
-
 puts SaferBool.banner    ## say hello

data/lib/safebool/version.rb

@@ -9,7 +9,7 @@
 module SaferBool
 
   MAJOR = 1
-  MINOR = 0
+  MINOR = 1
   PATCH = 0
   VERSION = [MAJOR,MINOR,PATCH].join('.')
 

data/test/test_bool.rb

@@ -11,33 +11,63 @@ require 'helper'
 class TestBool < MiniTest::Test
 
   def test_bool
-    assert_equal true,  false.is_a?(Bool)
-    assert_equal true,  false.false?
-    assert_equal false, false.true?
-    assert_equal true,  false.bool?
-    assert_equal false, false.to_b
-
-    assert_equal true,  true.is_a?(Bool)
-    assert_equal true,  true.true?
-    assert_equal false, true.false?
-    assert_equal true,  true.bool?
-    assert_equal true,  true.to_b
+    assert_equal true,    false.is_a?(Bool)
+    assert_equal true,    false.false?
+    assert_equal false,   false.true?
+    assert_equal true,    false.bool?
+    assert_equal false,   false.to_b
+    assert_equal 0,       false.to_i
+    assert_equal "false", false.to_s
+
+    assert_equal true,   true.is_a?(Bool)
+    assert_equal true,   true.true?
+    assert_equal false,  true.false?
+    assert_equal true,   true.bool?
+    assert_equal true,   true.to_b
+    assert_equal 1,      true.to_i
+    assert_equal "true", true.to_s
+
+    assert_equal false,  Bool.zero
+    assert_equal false,  false.class.zero
+    assert_equal false,  true.class.zero
+
+    assert_equal true,   false.zero?
+    assert_equal false,  true.zero?
+
+    assert_equal true,   false.frozen?   ## (always) true by default
+    assert_equal true,   true.frozen?    ## (always) true by default
+  end
+
+  def test_parse
+    assert_equal false,  Bool.parse( "false" )
+    assert_equal false,  Bool.parse( "f" )
+    assert_equal false,  Bool.parse( "0" )
+
+    assert_equal true,   Bool.parse( "true" )
+    assert_equal true,   Bool.parse( "t" )
+    assert_equal true,   Bool.parse( "1" )
+
+    assert_equal true,   Bool.parse( "" ) == nil
+    assert_equal true,   Bool.parse( "2" ) == nil
+    assert_equal true,   Bool.parse( "xxx" ) == nil
   end
 
   def test_nil
     assert_equal false, nil.to_b
+    assert_equal false, nil.to_bool
     assert_equal false, Bool(nil)
 
+    assert_equal 0,     nil.to_i
+    assert_equal "",    nil.to_s
+
+    assert_equal true,  nil.to_bool.is_a?(Bool)
+
     assert_equal false, nil.false?
     assert_equal false, nil.true?
     assert_equal false, nil.bool?
   end
 
   def test_string
-    assert_equal false, "true".false?
-    assert_equal false, "true".true?
-    assert_equal false, "true".bool?
-
     assert_equal true, "true".to_b
     assert_equal true, "yes".to_b
     assert_equal true, "on".to_b
@@ -57,13 +87,28 @@ class TestBool < MiniTest::Test
     assert_equal true, Bool("t")
     assert_equal true, Bool("y")
     assert_equal true, Bool("1")
+
+    assert_equal true, "".to_bool == nil
+    assert_equal true, "  ".to_bool == nil
+    assert_equal true, "2".to_bool == nil
+    assert_equal true, "xxx".to_bool == nil
+
+    assert_equal false, "".to_bool.bool?
+    assert_equal false, "  ".to_bool.bool?
+    assert_equal false, "2".to_bool.bool?
+    assert_equal false, "xxx".to_bool.bool?
+
+    assert_equal false, "".to_bool.is_a?(Bool)
+    assert_equal false, "  ".to_bool.is_a?(Bool)
+    assert_equal false, "2".to_bool.is_a?(Bool)
+    assert_equal false, "xxx".to_bool.is_a?(Bool)
+
+    assert_equal false, "true".false?
+    assert_equal false, "true".true?
+    assert_equal false, "true".bool?
   end
 
   def test_symbol
-    assert_equal false, :true.false?
-    assert_equal false, :true.true?
-    assert_equal false, :true.bool?
-
     assert_equal true, :true.to_b
     assert_equal true, :yes.to_b
     assert_equal true, :on.to_b
@@ -77,20 +122,45 @@ class TestBool < MiniTest::Test
     assert_equal true, Bool(:t)
     assert_equal true, Bool(:y)
     assert_equal true, Bool(:"1")
+
+    assert_equal true, :'2'.to_bool == nil
+    assert_equal true, :xxx.to_bool == nil
+
+    assert_equal false, :'2'.to_bool.bool?
+    assert_equal false, :'xxx'.to_bool.bool?
+
+    assert_equal false, :'2'.to_bool.is_a?(Bool)
+    assert_equal false, :'xxx'.to_bool.is_a?(Bool)
+
+    assert_equal false, :true.false?
+    assert_equal false, :true.true?
+    assert_equal false, :true.bool?
   end
 
 
   def test_integer
-    assert_equal false, 1.false?
-    assert_equal false, 1.true?
-    assert_equal false, 1.bool?
-
     assert_equal false, 0.to_b
     assert_equal true,  1.to_b
     assert_equal true,  2.to_b
 
     assert_equal false, Bool(0)
     assert_equal true,  Bool(1)
-    assert_equal true,  Bool(2)
+
+    assert_equal true,  2.to_bool == nil
+    assert_equal true, -1.to_bool == nil
+
+    assert_equal false, 2.to_bool.bool?
+    assert_equal false, -1.to_bool.bool?
+
+    assert_equal false, 2.to_bool.is_a?(Bool)
+    assert_equal false, -1.to_bool.is_a?(Bool)
+
+    assert_equal false, 1.false?
+    assert_equal false, 1.true?
+    assert_equal false, 1.bool?
+
+    assert_equal false, 0.false?
+    assert_equal false, 0.true?
+    assert_equal false, 0.bool?
   end
 end  # class TestBool

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: safebool
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.1.0
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-03-30 00:00:00.000000000 Z
+date: 2019-04-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdoc
@@ -38,8 +38,8 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.16'
-description: safebool - safe bool(ean) type adds Bool(), to_b, to_bool, bool?, false?,
-  true?, true.is_a?(Bool)==true, false.is_a?(Bool)==true, and more
+description: safebool - safe bool / boolean type adds Bool(), to_b, parse_bool / to_bool,
+  bool?, false?, true?, true.is_a?(Bool)==true, false.is_a?(Bool)==true, and more
 email: wwwmake@googlegroups.com
 executables: []
 extensions: []
@@ -83,6 +83,6 @@ rubyforge_project:
 rubygems_version: 2.5.2
 signing_key: 
 specification_version: 4
-summary: safebool - safe bool(ean) type adds Bool(), to_b, to_bool, bool?, false?,
-  true?, true.is_a?(Bool)==true, false.is_a?(Bool)==true, and more
+summary: safebool - safe bool / boolean type adds Bool(), to_b, parse_bool / to_bool,
+  bool?, false?, true?, true.is_a?(Bool)==true, false.is_a?(Bool)==true, and more
 test_files: []