adt 0.0.1 → 0.0.2

data/CHANGELOG.md

@@ -0,0 +1,12 @@
+
+0.0.2
+=====
+
+* Added alias to #fold, named the same as the class in underscore form. ie. for CertStatus, value.fold <=> value.cert_status
+* Added special methods for enumerations (defined as ADTs with only nullary constructors): #all_values, #to_i/::from_i
+* Added caching of the values for nullary constructors, ie. Maybe.nothing.object_id == Maybe.nothing.object_id
+* Added #to_a: simplifies #==
+* Added #<=>
+* Added case information methods: #case_name, #case_index (1-based), #case_arity
+* BUG: Constructors were being defined on every class that extended ADT.
+

data/README.md

@@ -8,25 +8,48 @@ Usage
 
     gem install adt
 
-Now:
+ADT provides a DSL for specifying the cases in an algebraic data type.
 
     require 'adt'
     class ValidatedValue
       extend ADT
       cases do
-        ok(:value)
         missing
         invalid(:reason)
+        ok(:value)
+      end
+    end
+
+    # An Enumeration (nullary constructors only)
+    class State
+      extend ADT
+      cases do
+        snafu
+        smoking # 'Nullary contructor' means it takes no arguments
       end
     end
 
-Later...
+What you now have:
+
+* Constructors for each of the cases: Type._case_(arg)
+* A `fold` method, for matching on all the cases.
+* A good #== and #inspect implementation
+* \#_case_? and #when__case_(handle_case_proc, default_proc) for dealing with a single case
+
+Check the [documentation](http://rubydoc.info/gems/adt/0.0.2/ADT:cases) for more information.
+
+Usage examples
+--------------
+
+Construction:
 
     # Create values
     mine = ValidatedValue.ok(5)
     missing = ValidatedValue.missing
     invalid = ValidatedValue.invalid("Wrong number!")
-    
+
+Folding:
+
     # Define operations on a value, only the proc matching the value's case will be 
     # executed
     mine.fold(
@@ -35,22 +58,45 @@ Later...
         proc { |reason| raise "gah. Invalid is terrible" }
     )
 
-    mine.ok? # <= true
-    mine.when_missing(proc { "I'm missing!" }, proc { "It's okay I'm around" })
-
-    mine.fold(
+    # Use an alias to #fold, named after the type:
+    mine.validated_value(
         :ok => proc { |value| value },
         :missing => proc { "missing default " },
         :invalid => proc { |reason| raise "gah. Invalid is terrible!" }
     )
 
+Support methods:
+
+    mine.ok? # <= true
+    mine.when_missing(proc { "I'm missing!" }, proc { "It's okay I'm around" })
+
     # == does what you expect.
     mine == ValidatedValue.missing # <= false
     mine == ValidatedValue.ok(5) # <= true
 
+    # <=> 
+    ValidatedValue.ok(5) <=> ValidatedValue.ok(3) # <= 1 # Ordering is by the inner value(s), if the cases match
+    ValidatedValue.ok(5) <=> ValidatedValue.missing # <= 1 # Otherwise it is by increasing order in which the cases are defined
+
+    # to_a
+    ValidatedValue.ok(5).to_a == [5]
+    ValidatedValue.missing.to_a = []
+
     # Inspect looks good.
     mine.inspect # <= "#<ValidatedValue ok value:5>"
 
+For the enumeration only:
+
+    State.all_values # <= [State.snafu, State.smoking]
+    State.snafu.to_i # <= 1
+    State.from_i(2) # <= State.smoking
+
+Case info:
+
+    State.snafu.case_name == "snafu"
+    ValidatedValue.ok(3).case_arity == 1
+    State.snafu.case_index = 2
+
 More Information on ADTs
 ------------------------
 

data/lib/adt.rb

@@ -1,5 +1,17 @@
 require 'adt/case_recorder'
 
+module StringHelp
+  def self.underscore(camel_cased_word)
+    word = camel_cased_word.to_s.dup
+    word.gsub!(/::/, '/')
+    word.gsub!(/([A-Z]+)([A-Z][a-z])/,'\1_\2')
+    word.gsub!(/([a-z\d])([A-Z])/,'\1_\2')
+    word.tr!("-", "_")
+    word.downcase!
+    word
+  end
+end
+
 module ADT
   module_function
 
@@ -39,25 +51,40 @@ module ADT
   # In addition, a number of helper methods are defined:
   #
   # * Standard object methods: #==, #inspect
+  # * Conversion to an array of the arguments: #to_a (nullary constructors return empty arrays)
+  # * #<=> and Comparable: cases are compared by index, and then by their parameters as an array
   # * Case checking predicates:
   #       some_validation.success?
   #       some_validation.failure?
   # * Functions for handling specific cases:
   #       some_validation.when_success(proc { |values| values }, proc { [] })
+  # * Case information
+  #       some_validation.case_name # <= "success"
+  #       some_validation.case_index # <= 1 # Indexing is 1-based.
+  #       some_validation.case_arity # <= 1 # Number of arguments required by the case
+  # * #fold is aliased to an underscored name of the type. ie. ValidatedValue gets #validated_value
+  #
+  # If the type is an enumeration (it only has nullary constructors), then a few extra methods are available:
+  # 
+  # * 1-based conversion to and from integers: #to_i, ::from_i
+  # * Accessor for all values: ::all_values
+  #
   #
   # @param [Proc] &definitions block which defines the constructors. This will be evaluated using
   #               #instance_eval to record the cases.
   #
   def cases(&definitions)
+    singleton_class = class <<self; self; end
     dsl = CaseRecorder.new
     dsl.__instance_eval(&definitions)
 
     cases = dsl._church_cases
     num_cases = dsl._church_cases.length
     case_names = dsl._church_cases.map { |x| x[0] }
+    is_enumeration = dsl._church_cases.all?{ |(_, args)| args.count == 0 }
 
-    # creates procs with a certain arg count. body should use aN to access arguments. The result should be
-    # evalled at the call site
+    # creates procs with a certain arg count. body should use #{prefix}N to access arguments. The result should be
+    # eval'ed at the call site
     proc_create = proc { |argc, prefix, body|
       args = argc > 0 ? "|#{(1..argc).to_a.map { |a| "#{prefix}#{a}" }.join(',')}|" : ""
       "proc { #{args} #{body} }" 
@@ -77,14 +104,41 @@ module ADT
       end
     end
 
+    # If we're inside a named class, then set up an alias to fold
+    define_method(StringHelp.underscore(name.split('::').last)) do |*args| fold(*args) end
+
     # The Constructors
     dsl._church_cases.each_with_index do |(name, case_args), index|
-      self.class.send(:define_method, name) do |*args|
-        the_proc = eval(proc_create[num_cases, "a", "a#{index+1}.call(*args)"])
-        self.new(&the_proc)
+      constructor = proc { |*args| self.new(&eval(proc_create[num_cases, "a", "a#{index+1}.call(*args)"])) }
+      if case_args.size > 0 then
+        singleton_class.send(:define_method, name, &constructor)
+      else
+        # Cache the constructed value if it is unary
+        singleton_class.send(:define_method, name) do
+          instance_variable_get("@#{name}") || begin
+            instance_variable_set("@#{name}", constructor.call)
+          end
+        end
       end
     end
 
+    # Case info methods
+    # Indexing is 1-based
+    define_method(:case_index) do fold(*(1..case_names.length).to_a.map { |i| proc { i } }) end
+    define_method(:case_name) do fold(*case_names.map { |i| proc { i.to_s } }) end
+    define_method(:case_arity) do fold(*dsl._church_cases.map { |(_, args)| proc { args.count } }) end
+
+    # Enumerations are defined as classes with cases that don't take arguments. A number of useful
+    # functions can be defined for these.
+    if is_enumeration 
+      singleton_class.send(:define_method, :all_values) do
+        @all_values ||= case_names.map { |x| send(x) }
+      end
+
+      define_method(:to_i) { case_index }
+      singleton_class.send(:define_method, :from_i) do |idx| send(case_names[idx - 1]) end
+    end
+
     # The usual object helpers
     define_method(:inspect) do
       "#<" + self.class.name + fold(*dsl._church_cases.map { |(cn, case_args)|
@@ -98,14 +152,22 @@ module ADT
     end
 
     define_method(:==) do |other|
-      !other.nil? && begin
-        fold(*cases.map { |(cn, args)|
-          inner_check = proc_create[args.count, "o", (1..(args.count)).to_a.map { |idx| "s#{idx} == o#{idx}"  }.<<("true").join(' && ')]
-          eval(proc_create[args.count, "s", "other.when_#{cn}(#{inner_check}, proc { false })"])
-        })
-      end
+      !other.nil? && case_index == other.case_index && to_a == other.to_a
+    end
+
+    define_method(:to_a) do 
+      fold(*cases.map { |(cn, args)|
+        eval(proc_create[args.count, "a", "[" + (1..args.count).to_a.map { |idx| "a#{idx}" }.join(',') + "]"])
+      })
     end
 
+    # Comparisons are done by index, then by the values within the case (if any) via #to_a
+    define_method(:<=>) do |other|
+      comp = case_index <=> other.case_index
+      comp == 0 ?  to_a <=> other.to_a : comp
+    end
+    include Comparable
+
     # Case specific methods
     # eg.
     #     cases do foo(:a); bar(:b); end
@@ -133,23 +195,3 @@ module ADT
   end
 end
 
-module Kernel
-  # Returns a class configured with cases as specified in the block. See `ADT::cases` for details.
-  #
-  #     Maybe = ADT do
-  #       just(:value)
-  #       nothing
-  #     end
-  #
-  #     v = Maybe.just(5)
-  #  
-  def ADT(&blk)
-    c = Class.new
-    c.instance_eval do
-      extend ADT
-      cases(&blk)
-    end
-    c
-  end
-end
-

data/lib/adt/case_recorder.rb

@@ -1,4 +1,5 @@
 module ADT
+  # @private
   class CaseRecorder
     alias :__instance_eval :instance_eval
 
@@ -10,6 +11,7 @@ module ADT
       @_church_cases = []
     end
 
+    # Defines a case for an ADT.
     def define_case(sym, *args)
       @_church_cases << [sym, args]
     end

metadata

@@ -2,7 +2,7 @@
 name: adt
 version: !ruby/object:Gem::Version 
   prerelease: 
-  version: 0.0.1
+  version: 0.0.2
 platform: ruby
 authors: 
 - Nick Partridge
@@ -25,6 +25,7 @@ extra_rdoc_files: []
 files: 
 - lib/adt/case_recorder.rb
 - lib/adt.rb
+- CHANGELOG.md
 - README.md
 has_rdoc: true
 homepage: ""