custom_boolean 0.1.2 → 0.1.3

data/README.markdown

@@ -1,7 +1,12 @@
 Custom Boolean
 ==============
 
-Cute hack to have if/else_if/else conditions with user-defined truthiness
+Cute hack to have if/else_if/else conditions with user-defined
+truthiness.
+
+* Implements various preset truth tests: Ruby, Python, Perl, C, Strict Boolean.
+* Provides ability to completely customize truthiness.
+* Provides common Boolean Operators (and, or, not) compatible with CustomBoolean
 
 Normal conditionals:
 --------------------
@@ -18,7 +23,7 @@ A Pythonic truthiness:
 ----------------------
 
     # redefine truthiness with the `truth_test` method
-    CustomBoolean.truth_test = proc { |b| b && b != 0 && b != [] }
+    CustomBoolean.truth_test = CustomBoolean::PYTHON_TRUTH
 
     if!(0) { 
         puts 'true' 
@@ -44,3 +49,125 @@ A full example:
     }
 
     #=> "x is 5"
+
+
+Nested ifs work fine:
+-------------------------
+
+    x = :delighted
+    y = :aroused
+    
+    if?(x == :sad) {
+      puts 'evaluates to true' 
+    }.
+    else_if(x == :delighted) {
+      if?(y == :happy) {
+        puts 'delighted and happy'
+      }.
+      else_if(y == :aroused) {
+        puts 'delighted and aroused'
+      }.
+      else { puts 'just delighted' }
+    }.
+    else {
+      puts 'not delighted'
+    }
+
+
+If expressions
+----------------
+
+    # prefixing `if!` with `+` invokes if-expression behaviour
+    +if!(false) {
+      :hello
+    }.
+    else {
+      :goodbye
+    }
+    #=> :goodbye
+
+Full list of preset CustomBoolean truth tests
+----------------------------------------------
+
+    CustomBoolean::RUBY_TRUTH  # the default
+    CustomBoolean::PYTHON_TRUTH 
+    CustomBoolean::PERL_TRUTH 
+    CustomBoolean::C_TRUTH
+    CustomBoolean::STRICT_TRUTH # (`true` or `false` only)
+
+Use as follows:
+
+    CustomBoolean.truth_test = CustomBoolean::C_TRUTH
+
+    +if!(0) {
+      true
+    }.
+    else {
+      false
+    }
+    #=> false
+       
+
+Customizable truthiness
+-------------------------
+
+`CustomBoolean.truth_test` can be set to an arbitrary Proc:
+    
+    # only :horse is true
+    CustomBoolean.truth_test = proc { |b| b == :horse }
+    
+    if!(true) {
+      puts 'evaluates to true' 
+    }.
+    else {
+      puts 'reached else'
+    }
+    
+    if!(:horse) {
+      puts 'evaluates to true' 
+    }.
+    else {
+      puts 'reached else'
+    }
+
+
+Boolean operators
+-----------------
+
+The ordinary `&&` and `||` and `!` operators do not implement
+CustomBoolean truthiness. Instead use `Object#and`, `Object#or`, and
+`Object#negate` (or `Object#&` and `Object#|` and `true.&` and `false.|`, etc)
+
+    # use perl truthiness where "0" is false
+    CustomBoolean.truth_test = CustomBoolean::PERL_TRUTH
+
+    +if!(true & "0") {
+      true
+    }.
+    else {
+      false
+    }
+    #=> false
+
+    # Or use Object#and
+    +if!(true.and "0") {...}
+
+    # Use negate (rather than not)
+    +if!(negate("0")) { true } ##=> true   
+    
+Testing truthiness of expressions
+----------------------------------
+
+You can test the truthiness of an expression without using the
+full machinery of if!/else_if/else. Just use the
+`CustomBoolean.truthy?()` function:
+
+    CustomBoolean.truth_test = CustomBoolean::PERL_TRUTH
+    CustomBoolean.truthy?("0") #=> false
+    
+Feedback
+-----------
+
+Problems or bugs, file an issue!
+
+Have fun!

data/lib/custom_boolean.rb

@@ -8,13 +8,13 @@ require "#{direc}/custom_boolean/version"
 class CustomBoolean
   module Operators
 
-    # Equivalent of **&&** for CustomBoolean truthiness.
-    # Differs from regular **&&** as it uses CustomBoolean truthiness
+    # Equivalent of *&&* for CustomBoolean truthiness.
+    # Differs from regular *&&* as it uses CustomBoolean truthiness
     # 
-    # **NOTE:** It is usually better to use the {#and} alias, as fewer objects override this
+    # *NOTE:* It is usually better to use the {#and} alias, as fewer objects override this
     # method)
     #
-    # @param The rhs of the boolean *and* operator
+    # @param other The rhs of the boolean *and* operator
     # @return [Boolean]
     # @example 
     #   obj1 & obj2
@@ -24,13 +24,13 @@ class CustomBoolean
     end
     alias_method :and, :"&"
     
-    # Equivalent of **||** for CustomBoolean truthiness.
-    # Differs from regular **||** as it uses CustomBoolean truthiness
+    # Equivalent of *||* for CustomBoolean truthiness.
+    # Differs from regular *||* as it uses CustomBoolean truthiness
     # 
-    # **NOTE:** It is usually better to use the {#or} alias, as fewer objects override this
+    # *NOTE:* It is usually better to use the {#or} alias, as fewer objects override this
     # method)
     #
-    # @param The rhs of the boolean *or* operator
+    # @param other The rhs of the boolean *or* operator
     # @return [Boolean]
     # @example 
     #   obj1 | obj2
@@ -47,10 +47,10 @@ true.extend(CustomBoolean::Operators)
 false.extend(CustomBoolean::Operators)
 Object.send(:include, CustomBoolean::Operators)
 
-# Equivalent of **!** for CustomBoolean truthiness.
-# Differs from regular **!** as it uses CustomBoolean truthiness
+# Equivalent of *!* for CustomBoolean truthiness.
+# Differs from regular *!* as it uses CustomBoolean truthiness
 # 
-# @param The expression to be negated
+# @param expr The expression to be negated
 # @return [Boolean]
 # @example 
 #   negate(obj)
@@ -58,20 +58,21 @@ def negate(expr)
   !CustomBoolean.truthy?(expr)
 end
 
-# Equivalent of **if** for CustomBoolean truthiness.
-# Differs from regular **if** as it uses CustomBoolean truthiness
+# Equivalent of *if* for CustomBoolean truthiness.
+# Differs from regular *if* as it uses CustomBoolean truthiness
 #
 # @example basic usage
-#   Use as follows: if_(condition) { ... }
-#   Other conditionals chain on to the end of if_() as follows:
+#   # Use as follows:
+#   if_(condition) { ... }
 #   
-#   if_(condition) { ... }.else { ... }
+#   # Other conditionals chain on to the end of if_() as follows:
+#   if_(condition) { ... }
+#   .else { ... }
 # @example if-expression form
-#   Can turn if_() statement into if-expression by prefixing with a `+`
-#   
+#   # Can turn if_() statement into if-expression by prefixing with a `+`
 #   value = +if_(true) { :hello }
 #   value #=> :hello
-# @param an expression to evaluate
+# @param condition an expression to evaluate
 # @return [CustomBoolean]
 # @yield the block will be executed if the condition evalues to true
 def if_(condition, &block)
@@ -91,7 +92,7 @@ class CustomBoolean
   attr_accessor :truth_value
 
   # @return [Object] The value of the block that was executed in the
-  # if/else_if/else 
+  #   if/else_if/else 
   attr_accessor :value
 
   class << self
@@ -105,32 +106,31 @@ class CustomBoolean
     # by CustomBoolean.truth_test.
     # 
     # Built in Truth tests include:
-    # CustomBoolean::RUBY_TRUTH
     # 
-    # CustomBoolean::PYTHON_TRUTH
+    # *CustomBoolean::RUBY_TRUTH*
+    # 
+    # *CustomBoolean::PYTHON_TRUTH*
     # 
-    # CustomBoolean::PERL_TRUTH
+    # *CustomBoolean::PERL_TRUTH*
     # 
-    # CustomBoolean::C_TRUTH
+    # *CustomBoolean::C_TRUTH*
     # 
-    # CustomBoolean::STRICT_TRUTH
+    # *CustomBoolean::STRICT_TRUTH*
     # 
     # @example changing truthiness to a preset 
     #   CustomBoolean.truth_test = CustomBoolean::PYTHON_TRUTH
     # @example user-defined truthiness  
     #   # only :horse is true:
     #   CustomBoolean.truth_test = proc { |expr| expr == :horse }
-    # @param an expression to evaluate
+    # @param condition an expression to evaluate
     # @return [Boolean]
     def truthy?(condition)
       self.truth_test.call(condition)
     end
   end
 
-  # exception raised when conditionals invoked after an else
   InvalidConditional = Class.new(StandardError)
   
-  # various ideas of truth
   RUBY_TRUTH = proc { |expr| expr }
   PYTHON_TRUTH = proc { |expr| expr && !(expr.respond_to?(:empty?) && expr.empty?) && expr != 0 }
   STRICT_TRUTH = proc { |expr| raise "Expression must be strictly true or false." if expr != true && expr != false; expr }
@@ -140,18 +140,20 @@ class CustomBoolean
   # default truth test is Ruby's
   self.truth_test = RUBY_TRUTH
   
+  # @param [Boolean, Symbol] truth_value
+  # @param block_value 
   def initialize(truth_value, block_value)
     self.truth_value = truth_value
     self.value = block_value
   end
 
-  # Prefixing +if_+ with `+` turns if-statement into if-expression
+  # Prefixing +if_+ with *+* turns if-statement into if-expression
   # by invoking #value on CustomBoolean object.
   # @return [Object] extracts the value of the if, transforming it
-  # into an if-expression
+  #   into an if-expression
   # @example single if-expression example
   #   +if(true) { :hello } #=> :hello
-  #   +if(fale) { :hello } #=> nil
+  #   +if(false) { :hello } #=> nil
   # @example if-else-expression example
   #   +if(false) {
   #     :hello
@@ -176,11 +178,10 @@ class CustomBoolean
   #   else_if(cond2) {
   #     :goodbye
   #   }
-  # @param [Object] an expression to evaluate
+  # @param condition an expression to evaluate
   # @return [CustomBoolean]
   # @yield the block will be executed if the condition evalues to true
-  # (so long as no prior *else_if* or *if* has evaluated to true further
-  # up the chain)
+  #   (so long as no prior *else_if* or *if* has evaluated to true further up the chain)
   def else_if(condition, &block)
     raise InvalidConditional, "No further conditionals allowed after an else." if self.truth_value == :else_reached
 
@@ -218,8 +219,7 @@ class CustomBoolean
   #   }
   # @return [CustomBoolean]
   # @yield the block will be executed if the condition evalues to true
-  # (so long as no prior *else_if* or *if* has evaluated to true further
-  # up the chain)  
+  #   (so long as no prior *else_if* or *if* has evaluated to true further up the chain)
   def else(&block)
     raise InvalidConditional, "No further conditionals allowed after an else." if self.truth_value == :else_reached
 

data/lib/custom_boolean/version.rb

@@ -1,3 +1,3 @@
 class CustomBoolean
-  VERSION = "0.1.2"
+  VERSION = "0.1.3"
 end

metadata

@@ -1,12 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: custom_boolean
 version: !ruby/object:Gem::Version 
+  hash: 29
   prerelease: false
   segments: 
   - 0
   - 1
-  - 2
-  version: 0.1.2
+  - 3
+  version: 0.1.3
 platform: ruby
 authors: 
 - John Mair (banisterfiend)
@@ -52,6 +53,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"
@@ -60,6 +62,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
+      hash: 3
       segments: 
       - 0
       version: "0"