custom_boolean 0.1.1 → 0.1.2

data/CHANGELOG

@@ -1,2 +1,9 @@
-27/0/10 version 0.1.0
+28/9/10 version 0.1.2
+* added YARD documentation
+* added more examples and tests
+27/9/10 version 0.1.1
+* added boolean operators
+	
+27/9/10 version 0.1.0
 * release!
+	

data/Rakefile

@@ -1,4 +1,5 @@
 require 'rake/gempackagetask'
+require 'rake/rdoctask'
 require './lib/custom_boolean/version'
 
 $dlext = Config::CONFIG['DLEXT']
@@ -14,7 +15,10 @@ specification = Gem::Specification.new do |s|
   s.require_path = 'lib'
   s.platform = Gem::Platform::RUBY
   s.homepage = "http://banisterfiend.wordpress.com"
-  s.has_rdoc = false
+  s.has_rdoc = 'yard'
+  s.extra_rdoc_files = ["README.markdown"]
+  s.rdoc_options << '--main' << 'README.markdown'
+  
   s.files =  ["Rakefile", "README.markdown", "CHANGELOG", 
               "lib/custom_boolean.rb", "lib/custom_boolean/version.rb"] +
     FileList["examples/*.rb", "test/*.rb"].to_a
@@ -25,3 +29,7 @@ Rake::GemPackageTask.new(specification) do |package|
   package.need_tar = false
 end
 
+Rake::RDocTask.new do |rd|
+  rd.main = "README.markdown"
+  rd.rdoc_files.include("README.markdown", "lib/**/*.rb")
+end

data/lib/custom_boolean.rb

@@ -1,17 +1,40 @@
 # CustomBoolean by John Mair (banisterfiend)
 # MIT license
 
-
 direc = File.dirname(__FILE__)
 require "#{direc}/custom_boolean/version"
 
+# @author John Mair (banisterfiend)
 class CustomBoolean
   module Operators
+
+    # 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
+    # method)
+    #
+    # @param The rhs of the boolean *and* operator
+    # @return [Boolean]
+    # @example 
+    #   obj1 & obj2
+    #   obj1.and obj2
     def &(other)
       CustomBoolean.truthy?(self) && CustomBoolean.truthy?(other)
     end
     alias_method :and, :"&"
     
+    # 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
+    # method)
+    #
+    # @param The rhs of the boolean *or* operator
+    # @return [Boolean]
+    # @example 
+    #   obj1 | obj2
+    #   obj1.or obj2
     def |(other)
       CustomBoolean.truthy?(self) || CustomBoolean.truthy?(other)
     end
@@ -19,14 +42,38 @@ class CustomBoolean
   end
 end
 
+# Unfortunately patching these objects is necessary :(
 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
+# 
+# @param The expression to be negated
+# @return [Boolean]
+# @example 
+#   negate(obj)
 def negate(expr)
   !CustomBoolean.truthy?(expr)
 end
 
+# 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:
+#   
+#   if_(condition) { ... }.else { ... }
+# @example if-expression form
+#   Can turn if_() statement into if-expression by prefixing with a `+`
+#   
+#   value = +if_(true) { :hello }
+#   value #=> :hello
+# @param an expression to evaluate
+# @return [CustomBoolean]
+# @yield the block will be executed if the condition evalues to true
 def if_(condition, &block)
   truth = !!CustomBoolean.truthy?(condition)
   bvalue = block.call if truth
@@ -39,11 +86,42 @@ alias _if if_
 alias if? if_
 
 class CustomBoolean
-  attr_accessor :truth_value, :value
+
+  # @return [Boolean] 
+  attr_accessor :truth_value
+
+  # @return [Object] The value of the block that was executed in the
+  # if/else_if/else 
+  attr_accessor :value
 
   class << self
+
+    # @return [Proc] The proc that defines the truth test
     attr_accessor :truth_test
 
+    # Tests whether *condition* is truthy according to
+    # CustomBoolean truthiness.
+    # CustomBoolean truthiness is determined by the proc referenced
+    # by CustomBoolean.truth_test.
+    # 
+    # Built in Truth tests include:
+    # CustomBoolean::RUBY_TRUTH
+    # 
+    # CustomBoolean::PYTHON_TRUTH
+    # 
+    # CustomBoolean::PERL_TRUTH
+    # 
+    # CustomBoolean::C_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
+    # @return [Boolean]
     def truthy?(condition)
       self.truth_test.call(condition)
     end
@@ -67,10 +145,42 @@ class CustomBoolean
     self.value = block_value
   end
 
+  # 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
+  # @example single if-expression example
+  #   +if(true) { :hello } #=> :hello
+  #   +if(fale) { :hello } #=> nil
+  # @example if-else-expression example
+  #   +if(false) {
+  #     :hello
+  #   }.
+  #   else {
+  #     :goodbye
+  #   }
+  #   #=> :goodbye
   def +@
     self.value
   end
   
+  # Equivalent of **elsif** for CustomBoolean truthiness.
+  # Must be chained after an if_() or another else_if()
+  # 
+  # Differs from regular **elsif** as it uses CustomBoolean truthiness
+  #
+  # @example else_if example
+  #   if_(cond) {
+  #     :hello
+  #   }.
+  #   else_if(cond2) {
+  #     :goodbye
+  #   }
+  # @param [Object] 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)
   def else_if(condition, &block)
     raise InvalidConditional, "No further conditionals allowed after an else." if self.truth_value == :else_reached
 
@@ -90,6 +200,26 @@ class CustomBoolean
   alias elsif? else_if
   alias elsif! else_if
   
+  # Equivalent of **else** for CustomBoolean truthiness.
+  # Must be chained after an if_() or an else_if()
+  # 
+  # Differs from regular **else** as it uses CustomBoolean truthiness
+  # 
+  # No other conditionals may be chained after an +else+.
+  # In event a conditional is chained after an +else+ an
+  # **InvalidConditional** exception will be raised.
+  #
+  # @example else example
+  #   if_(cond) {
+  #     :hello
+  #   }.
+  #   else {
+  #     :goodbye
+  #   }
+  # @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)  
   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.1"
+  VERSION = "0.1.2"
 end

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 0
   - 1
-  - 1
-  version: 0.1.1
+  - 2
+  version: 0.1.2
 platform: ruby
 authors: 
 - John Mair (banisterfiend)
@@ -24,8 +24,8 @@ executables: []
 
 extensions: []
 
-extra_rdoc_files: []
-
+extra_rdoc_files: 
+- README.markdown
 files: 
 - Rakefile
 - README.markdown
@@ -37,13 +37,14 @@ files:
 - examples/example_nested.rb
 - examples/example_operators.rb
 - test/test.rb
-has_rdoc: true
+has_rdoc: yard
 homepage: http://banisterfiend.wordpress.com
 licenses: []
 
 post_install_message: 
-rdoc_options: []
-
+rdoc_options: 
+- --main
+- README.markdown
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement