algebrick 0.4.0 → 0.5.0

data/doc/parametrized.in.rb

@@ -0,0 +1,37 @@
+# Let's define Tree but this time parameterized by :value_type,
+Tree = Algebrick.type(:value_type) do |tree|
+  variants Empty = atom,
+           Leaf  = type(:value_type) { fields value: :value_type },
+           Node  = type(:value_type) { fields left: tree, right: tree }
+end
+
+# with method depth defined as before.
+module Tree
+  def depth
+    match self,
+          Empty >> 0,
+          Leaf >> 1,
+          Node.(~any, ~any) >-> left, right do
+            1 + [left.depth, right.depth].max
+          end
+  end
+end #
+
+# Then Tree, Leaf, Node are
+Tree.class
+[Tree, Leaf, Node]
+# which servers as factories to actual types.
+Tree[Float]
+Tree[String]
+
+# Types cannot be mixed.
+Leaf[Integer]['1'] rescue $!
+Node[Integer][Leaf[String]['a'], Empty] rescue $!
+Leaf[String]['1']
+
+# Depth method works as before.
+integer_tree = Node[Integer][Leaf[Integer][2], Empty]
+integer_tree.depth
+string_tree = Node[String][Empty, Empty]
+string_tree.depth
+

data/doc/parametrized.out.rb

@@ -0,0 +1,41 @@
+# Let's define Tree but this time parameterized by :value_type,
+Tree = Algebrick.type(:value_type) do |tree|
+  variants Empty = atom,
+           Leaf  = type(:value_type) { fields value: :value_type },
+           Node  = type(:value_type) { fields left: tree, right: tree }
+end
+
+# with method depth defined as before.
+module Tree
+  def depth
+    match self,
+          Empty >> 0,
+          Leaf >> 1,
+          Node.(~any, ~any) >-> left, right do
+            1 + [left.depth, right.depth].max
+          end
+  end
+end 
+
+# Then Tree, Leaf, Node are
+Tree.class                                         # => Algebrick::ParametrizedType
+[Tree, Leaf, Node]
+    # => [Tree[value_type], Leaf[value_type], Node[value_type]]
+# which servers as factories to actual types.
+Tree[Float]                                        # => Tree[Float](Empty | Leaf[Float] | Node[Float])
+Tree[String]                                       # => Tree[String](Empty | Leaf[String] | Node[String])
+
+# Types cannot be mixed.
+Leaf[Integer]['1'] rescue $!
+    # => #<TypeError: Value (String) '1' is not any of: Integer.>
+Node[Integer][Leaf[String]['a'], Empty] rescue $!
+    # => #<TypeError: Value (Leaf[String](value: String)) 'Leaf[String][value: a]' is not any of: Tree[Integer](Empty | Leaf[Integer] | Node[Integer]).>
+Leaf[String]['1']                                  # => Leaf[String][value: 1]
+
+# Depth method works as before.
+integer_tree = Node[Integer][Leaf[Integer][2], Empty]
+    # => Node[Integer][left: Leaf[Integer][value: 2], right: Empty]
+integer_tree.depth                                 # => 2
+string_tree = Node[String][Empty, Empty]           # => Node[String][left: Empty, right: Empty]
+string_tree.depth                                  # => 1
+

data/doc/pattern_matching.in.rb

@@ -0,0 +1,116 @@
+# Let's define a tree and binary tree to demonstrate the pattern matching abilities.
+Tree = Algebrick.type do |tree|
+  variants Empty = type,
+           Leaf  = type { fields Integer },
+           Node  = type { fields tree, tree }
+end
+
+BinaryTree = BTree = Algebrick.type do |btree|
+  fields! value: Comparable, left: btree, right: btree
+  variants Empty, btree
+end
+
+extend Algebrick::Matching
+
+# Product matchers are constructed with #.() syntax.
+Leaf.(any) === Leaf[1]
+Leaf.(1) === Leaf[1]
+Leaf.(2) === Leaf[1]
+# There are also some shortcuts to use when product has more fields.
+BTree.()
+BTree.(value: any, left: Empty)
+BTree.(value: any, left: Empty) === BTree[1, Empty, Empty]
+
+# Any object responding to #=== can be converted to matcher.
+(1..2).to_m
+(1..2).to_m === 2
+Empty.to_m
+# As matchers are using standard #=== method it does not have to be always converted.
+Empty === Empty
+Leaf === Leaf[1]
+
+# Tree matches all its values.
+[Empty, Leaf[1], Node[Empty, Empty]].all? { |v| Tree === v }
+
+# There is also a #match method in Matching module to make pattern matching easier.
+match Leaf[1], # supply the value for matching
+      # if Leaf.(0) matches :zero is returned
+      (on Leaf.(0), :zero),
+      # when computation of the result needs to be avoided use block
+      # if Leaf.(1) matches block is called and its result is returned
+      (on Leaf.(1) do
+        (1..10000).inject(:*) # expensive computation
+        :one # which is :one in this case
+      end)
+
+# Alternatively case can be used.
+case Leaf[1]
+when Leaf.(0)
+  :zero
+when Leaf.(1)
+  (1..10000).inject(:*) # expensive computation
+  :one
+end
+
+# But that won't work nicely with value deconstruction.
+# Each matcher can be marked with #~ method to store value against which is being matched,
+# each matched value is passed to the block, ...
+match Leaf[0],
+      (on ~Leaf.(~any) do |leaf, value|
+        [leaf, value]
+      end)
+
+btree = BTree[1,
+              BTree[0, Empty, Empty],
+              Empty]
+match btree,
+      (on BTree.(any, ~any, ~any) do |left, right|
+        [left, right]
+      end)
+
+# or alternatively you can use Ruby's multi-assignment feature.
+match btree,
+      (on ~BTree do |(_, left, right)|
+        [left, right]
+      end)
+
+
+# Matchers also support logical operations #& for and, #| for or, and #! for negation.
+Color = Algebrick.type do
+  variants Black = atom,
+           White = atom,
+           Pink  = atom,
+           Grey  = type { fields scale: Float }
+end
+
+def color?(color)
+  match color,
+        on(Black | Grey.(-> v { v < 0.2 }), 'black-ish'),
+        on(White | Grey.(-> v { v > 0.8 }), 'white-ish'),
+        on(Grey.(-> v { v >= 0.2 }) & Grey.(-> v { v <= 0.8 }), 'grey-ish'),
+        on(Pink, "that's not a color ;)")
+end
+
+color? Black
+color? Grey[0.1]
+color? Grey[0.3]
+color? Grey[0.9]
+color? White
+color? Pink
+
+# A more complicated example of extracting node's value and values of its left and right side
+# using also logical operators to allow Empty sides.
+match BTree[0, Empty, BTree[1, Empty, Empty]],
+      (on BTree.({ value: ~any,
+                   left:  Empty | BTree.(value: ~any),
+                   right: Empty | BTree.(value: ~any) }) do |value, left, right|
+        { left: left, value: value, right: right }
+      end)
+
+# There is also a more funky syntax for matching
+# using #>, #>> and Ruby 1.9 syntax for lambdas `-> {}`.
+match Leaf[1],
+      Leaf.(0) >> :zero,
+      Leaf.(~any) >-> value do
+        (1..value).inject(:*) # an expensive computation
+      end

data/doc/pattern_matching.out.rb

@@ -0,0 +1,122 @@
+# Let's define a tree and binary tree to demonstrate the pattern matching abilities.
+Tree = Algebrick.type do |tree|
+  variants Empty = type,
+           Leaf  = type { fields Integer },
+           Node  = type { fields tree, tree }
+end                                                # => Tree(Empty | Leaf | Node)
+
+BinaryTree = BTree = Algebrick.type do |btree|
+  fields! value: Comparable, left: btree, right: btree
+  variants Empty, btree
+end
+    # => BTree(Empty | BTree(value: Comparable, left: BTree, right: BTree))
+
+extend Algebrick::Matching                         # => main
+
+# Product matchers are constructed with #.() syntax.
+Leaf.(any) === Leaf[1]                             # => true
+Leaf.(1) === Leaf[1]                               # => true
+Leaf.(2) === Leaf[1]                               # => false
+# There are also some shortcuts to use when product has more fields.
+BTree.()                                           # => BTree.(any, any, any)
+BTree.(value: any, left: Empty)                    # => BTree.(any, Empty, any)
+BTree.(value: any, left: Empty) === BTree[1, Empty, Empty]
+    # => true
+
+# Any object responding to #=== can be converted to matcher.
+(1..2).to_m                                        # => Wrapper.(1..2)
+(1..2).to_m === 2                                  # => true
+Empty.to_m                                         # => Empty.to_m
+# As matchers are using standard #=== method it does not have to be always converted.
+Empty === Empty                                    # => true
+Leaf === Leaf[1]                                   # => true
+
+# Tree matches all its values.
+[Empty, Leaf[1], Node[Empty, Empty]].all? { |v| Tree === v }
+    # => true
+
+# There is also a #match method in Matching module to make pattern matching easier.
+match Leaf[1], # supply the value for matching
+      # if Leaf.(0) matches :zero is returned
+      (on Leaf.(0), :zero),
+      # when computation of the result needs to be avoided use block
+      # if Leaf.(1) matches block is called and its result is returned
+      (on Leaf.(1) do
+        (1..10000).inject(:*) # expensive computation
+        :one # which is :one in this case
+      end)                                         # => :one
+
+# Alternatively case can be used.
+case Leaf[1]
+when Leaf.(0)
+  :zero
+when Leaf.(1)
+  (1..10000).inject(:*) # expensive computation
+  :one
+end                                                # => :one
+
+# But that won't work nicely with value deconstruction.
+# Each matcher can be marked with #~ method to store value against which is being matched,
+# each matched value is passed to the block, ...
+match Leaf[0],
+      (on ~Leaf.(~any) do |leaf, value|
+        [leaf, value]
+      end)                                         # => [Leaf[0], 0]
+
+btree = BTree[1,
+              BTree[0, Empty, Empty],
+              Empty]
+    # => BTree[value: 1, left: BTree[value: 0, left: Empty, right: Empty], right: Empty]
+match btree,
+      (on BTree.(any, ~any, ~any) do |left, right|
+        [left, right]
+      end)
+    # => [BTree[value: 0, left: Empty, right: Empty], Empty]
+
+# or alternatively you can use Ruby's multi-assignment feature.
+match btree,
+      (on ~BTree do |(_, left, right)|
+        [left, right]
+      end)
+    # => [BTree[value: 0, left: Empty, right: Empty], Empty]
+
+
+# Matchers also support logical operations #& for and, #| for or, and #! for negation.
+Color = Algebrick.type do
+  variants Black = atom,
+           White = atom,
+           Pink  = atom,
+           Grey  = type { fields scale: Float }
+end                                                # => Color(Black | White | Pink | Grey)
+
+def color?(color)
+  match color,
+        on(Black | Grey.(-> v { v < 0.2 }), 'black-ish'),
+        on(White | Grey.(-> v { v > 0.8 }), 'white-ish'),
+        on(Grey.(-> v { v >= 0.2 }) & Grey.(-> v { v <= 0.8 }), 'grey-ish'),
+        on(Pink, "that's not a color ;)")
+end                                                # => :color?
+
+color? Black                                       # => "black-ish"
+color? Grey[0.1]                                   # => "black-ish"
+color? Grey[0.3]                                   # => "grey-ish"
+color? Grey[0.9]                                   # => "white-ish"
+color? White                                       # => "white-ish"
+color? Pink                                        # => "that's not a color ;)"
+
+# A more complicated example of extracting node's value and values of its left and right side
+# using also logical operators to allow Empty sides.
+match BTree[0, Empty, BTree[1, Empty, Empty]],
+      (on BTree.({ value: ~any,
+                   left:  Empty | BTree.(value: ~any),
+                   right: Empty | BTree.(value: ~any) }) do |value, left, right|
+        { left: left, value: value, right: right }
+      end)                                         # => {:left=>nil, :value=>0, :right=>1}
+
+# There is also a more funky syntax for matching
+# using #>, #>> and Ruby 1.9 syntax for lambdas `-> {}`.
+match Leaf[1],
+      Leaf.(0) >> :zero,
+      Leaf.(~any) >-> value do
+        (1..value).inject(:*) # an expensive computation
+      end                                          # => 1

data/doc/quick_example.in.rb

@@ -0,0 +1,27 @@
+# Let's define a Tree
+Tree = Algebrick.type do |tree|
+  variants Empty = atom,
+           Leaf  = type { fields Integer },
+           Node  = type { fields tree, tree }
+end
+
+# Now types `Tree(Empty | Leaf | Node)`, `Empty`, `Leaf(Integer)` and `Node(Tree, Tree)` are defined.
+# Let's add a method, don't miss the **pattern matching** example.
+module Tree
+  # compute depth of a tree
+  def depth
+    match self,
+          (on Empty, 0),
+          (on Leaf, 1),
+          # ~ will store and pass matched parts to variables left and right
+          (on Node.(~any, ~any) do |left, right|
+            1 + [left.depth, right.depth].max
+          end)
+  end
+end #
+
+# Method defined in module `Tree` are passed down to **all** values of type Tree.
+Empty.depth
+Leaf[10].depth
+Node[Leaf[4], Empty].depth
+Node[Empty, Node[Leaf[1], Empty]].depth

data/doc/quick_example.out.rb

@@ -0,0 +1,27 @@
+# Let's define a Tree
+Tree = Algebrick.type do |tree|
+  variants Empty = atom,
+           Leaf  = type { fields Integer },
+           Node  = type { fields tree, tree }
+end                                                # => Tree(Empty | Leaf | Node)
+
+# Now types `Tree(Empty | Leaf | Node)`, `Empty`, `Leaf(Integer)` and `Node(Tree, Tree)` are defined.
+# Let's add a method, don't miss the **pattern matching** example.
+module Tree
+  # compute depth of a tree
+  def depth
+    match self,
+          (on Empty, 0),
+          (on Leaf, 1),
+          # ~ will store and pass matched parts to variables left and right
+          (on Node.(~any, ~any) do |left, right|
+            1 + [left.depth, right.depth].max
+          end)
+  end
+end 
+
+# Method defined in module `Tree` are passed down to **all** values of type Tree.
+Empty.depth                                        # => 0
+Leaf[10].depth                                     # => 1
+Node[Leaf[4], Empty].depth                         # => 2
+Node[Empty, Node[Leaf[1], Empty]].depth            # => 3

data/doc/tree1.in.rb

@@ -0,0 +1,10 @@
+Tree = Algebrick.type do |tree|
+  variants Empty = type,
+           Leaf  = type { fields Integer },
+           Node  = type { fields tree, tree }
+end
+# Which sets 4 modules representing these types in current module/class
+Tree
+Empty
+Leaf
+Node

data/doc/tree1.out.rb

@@ -0,0 +1,10 @@
+Tree = Algebrick.type do |tree|
+  variants Empty = type,
+           Leaf  = type { fields Integer },
+           Node  = type { fields tree, tree }
+end                                                # => Tree(Empty | Leaf | Node)
+# Which sets 4 modules representing these types in current module/class
+Tree                                               # => Tree(Empty | Leaf | Node)
+Empty                                              # => Empty
+Leaf                                               # => Leaf(Integer)
+Node                                               # => Node(Tree, Tree)

data/doc/type_def.in.rb

@@ -0,0 +1,21 @@
+# Let's define some types
+Maybe = Algebrick.type do
+  variants None = atom,
+           Some = type { fields Numeric }
+end
+
+# where the Maybe actually is:
+Maybe.class
+Maybe.class.superclass
+Maybe.class.superclass.superclass
+Maybe.class.superclass.superclass.superclass
+
+# if there is a circular dependency you can define the dependent types inside the block like this:
+Tree = Algebrick.type do |tree|
+  variants Empty = type,
+           Leaf  = type { fields Integer },
+           Node  = type { fields tree, tree }
+end
+Empty
+Leaf
+Node

data/doc/type_def.out.rb

@@ -0,0 +1,21 @@
+# Let's define some types
+Maybe = Algebrick.type do
+  variants None = atom,
+           Some = type { fields Numeric }
+end                                                # => Maybe(None | Some)
+
+# where the Maybe actually is:
+Maybe.class                                        # => Algebrick::ProductVariant
+Maybe.class.superclass                             # => Algebrick::Type
+Maybe.class.superclass.superclass                  # => Module
+Maybe.class.superclass.superclass.superclass       # => Object
+
+# if there is a circular dependency you can define the dependent types inside the block like this:
+Tree = Algebrick.type do |tree|
+  variants Empty = type,
+           Leaf  = type { fields Integer },
+           Node  = type { fields tree, tree }
+end                                                # => Tree(Empty | Leaf | Node)
+Empty                                              # => Empty
+Leaf                                               # => Leaf(Integer)
+Node                                               # => Node(Tree, Tree)

data/doc/values.in.rb

@@ -0,0 +1,52 @@
+# Let's define a Tree
+Tree = Algebrick.type do |tree|
+  variants Empty = type,
+           Leaf  = type { fields Integer },
+           Node  = type { fields tree, tree }
+end
+
+# Values of atomic types are represented by itself,
+# they are theirs own value.
+Empty.kind_of? Algebrick::Value
+Empty.kind_of? Algebrick::Type
+Empty.kind_of? Empty
+
+# Values of product types are constructed with #[] and they are immutable.
+Leaf[1].kind_of? Algebrick::Value
+Leaf[1].kind_of? Leaf
+Node[Empty, Empty].kind_of? Node
+
+# Variant does not have its own values, it uses atoms and products.
+Leaf[1].kind_of? Tree
+Empty.kind_of? Tree
+
+# Product can have its fields named.
+BinaryTree = BTree = Algebrick.type do |btree|
+  fields! value: Integer, left: btree, right: btree
+  variants Tip = atom, btree
+end
+
+# Then values can be created with names
+tree1      = BTree[value: 1, left: Tip, right: Tip]
+# or without them as before.
+BTree[0, Tip, tree1]
+
+# Fields of products can be read as follows:
+# 1. When type has only one field method #value is defined
+Leaf[1].value
+# 2. By multi-assign
+v, left, right = BTree[value: 1, left: Tip, right: Tip]
+[v, left, right]
+# 3. With #[] method when fields are named
+BTree[value: 1, left: Tip, right: Tip][:value]
+BTree[value: 1, left: Tip, right: Tip][:left]
+# 4. With methods named by fields when fields are named
+#    (it can be disabled if fields are defined with #fields instead of #fields!)
+BTree[1, Tip, Tip].value
+BTree[1, Tip, Tip].left
+
+# Product instantiation raises TypeError when being constructed with wrong type.
+Leaf['a'] rescue $!
+Node[nil, Empty] rescue $!
+
+

data/doc/values.out.rb

@@ -0,0 +1,58 @@
+# Let's define a Tree
+Tree = Algebrick.type do |tree|
+  variants Empty = type,
+           Leaf  = type { fields Integer },
+           Node  = type { fields tree, tree }
+end                                                # => Tree(Empty | Leaf | Node)
+
+# Values of atomic types are represented by itself,
+# they are theirs own value.
+Empty.kind_of? Algebrick::Value                    # => true
+Empty.kind_of? Algebrick::Type                     # => true
+Empty.kind_of? Empty                               # => true
+
+# Values of product types are constructed with #[] and they are immutable.
+Leaf[1].kind_of? Algebrick::Value                  # => true
+Leaf[1].kind_of? Leaf                              # => true
+Node[Empty, Empty].kind_of? Node                   # => true
+
+# Variant does not have its own values, it uses atoms and products.
+Leaf[1].kind_of? Tree                              # => true
+Empty.kind_of? Tree                                # => true
+
+# Product can have its fields named.
+BinaryTree = BTree = Algebrick.type do |btree|
+  fields! value: Integer, left: btree, right: btree
+  variants Tip = atom, btree
+end
+    # => BTree(Tip | BTree(value: Integer, left: BTree, right: BTree))
+
+# Then values can be created with names
+tree1      = BTree[value: 1, left: Tip, right: Tip]
+    # => BTree[value: 1, left: Tip, right: Tip]
+# or without them as before.
+BTree[0, Tip, tree1]
+    # => BTree[value: 0, left: Tip, right: BTree[value: 1, left: Tip, right: Tip]]
+
+# Fields of products can be read as follows:
+# 1. When type has only one field method #value is defined
+Leaf[1].value                                      # => 1
+# 2. By multi-assign
+v, left, right = BTree[value: 1, left: Tip, right: Tip]
+    # => BTree[value: 1, left: Tip, right: Tip]
+[v, left, right]                                   # => [1, Tip, Tip]
+# 3. With #[] method when fields are named
+BTree[value: 1, left: Tip, right: Tip][:value]     # => 1
+BTree[value: 1, left: Tip, right: Tip][:left]      # => Tip
+# 4. With methods named by fields when fields are named
+#    (it can be disabled if fields are defined with #fields instead of #fields!)
+BTree[1, Tip, Tip].value                           # => 1
+BTree[1, Tip, Tip].left                            # => Tip
+
+# Product instantiation raises TypeError when being constructed with wrong type.
+Leaf['a'] rescue $!
+    # => #<TypeError: Value (String) 'a' is not any of: Integer.>
+Node[nil, Empty] rescue $!
+    # => #<TypeError: Value (NilClass) '' is not any of: Tree(Empty | Leaf | Node).>
+
+

data/lib/algebrick/atom.rb

@@ -0,0 +1,49 @@
+#  Copyright 2013 Petr Chalupa <git+algebrick@pitr.ch>
+#
+#  Licensed under the Apache License, Version 2.0 (the "License");
+#  you may not use this file except in compliance with the License.
+#  You may obtain a copy of the License at
+#
+#    http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+module Algebrick
+  # Representation of Atomic types
+  class Atom < Type
+    include Value
+
+    def initialize(name, &block)
+      super name, &block
+      extend self
+    end
+
+    def to_m
+      Matchers::Atom.new self
+    end
+
+    def be_kind_of(type)
+      extend type
+    end
+
+    def ==(other)
+      self.equal? other
+    end
+
+    def type
+      self
+    end
+
+    def to_s
+      name
+    end
+
+    def pretty_print(q)
+      q.text to_s
+    end
+  end
+end