algebrick 0.4.0 → 0.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: d3e1690d46e7e9d3c9332eed298a46d35ec628ce
-  data.tar.gz: 7cf4ccef5ae69a055e9ac7806b84e0a6724d7c1b
+  metadata.gz: df5b658188ef94835725f056d1872942a1f10fe3
+  data.tar.gz: 5ac342bdfaaa354e8bf9575c25f1e06105170d18
 SHA512:
-  metadata.gz: ae2f4b9cd4bebbb889b8d91383cbe9380d8b2c440104c0302b4b128b589fbdb6d1bdae886a49cf790022a76f1fe304180bc8b6ed77da6ce60d6aba038fac67fd
-  data.tar.gz: becadc540cc08d5002060e0fc1e64eac87d1848ff11bc44b6e628a45b61bc705fcce870741e568b2e6803e39b08b7f789d42e2926d176f8c40c8083bea3db21c
+  metadata.gz: 1207c3040b5d32c3d64cc47c29f9bccb83a979600cc9dc169d1424b6514297bc3c844bfa12e5d851663f08382019cdf948a85397e4363f21b4f835756c92235a
+  data.tar.gz: af70a94f628feb94b59995adc5d6740cafdddf655a4c560f25e788c31f758138e21a6617abff047fc7d195176cf5357b7e9a65decb25916c0176d240b0f0eeb8

data/README.md

@@ -2,7 +2,7 @@
 
 [![Build Status](https://travis-ci.org/pitr-ch/algebrick.png?branch=master)](https://travis-ci.org/pitr-ch/algebrick)
 
-It's a gem providing **algebraic types** and **pattern matching** seamlessly integrates with standard features Ruby.
+Typed structs on steroids based on algebraic types and pattern matching seamlessly integrating with standard Ruby features.
 
 -   Documentation: <http://blog.pitr.ch/algebrick>
 -   Source: <https://github.com/pitr-ch/algebrick>
@@ -10,8 +10,11 @@ It's a gem providing **algebraic types** and **pattern matching** seamlessly int
 
 ## What is it good for?
 
--   Defining data structures.
--   Algebraic types play nice with JSON serialization and deserialization. It is ideal for defining message-based cross-process communication.
+-   Well defined data structures.
+-   Actor messages see [new Actor implementation](http://rubydoc.info/gems/concurrent-ruby/Concurrent/Actress) 
+    in [concurrent-ruby](concurrent-ruby.com).
+-   Describing message protocols in message-based cross-process communication. 
+    Algebraic types play nice with JSON de/serialization.
 -   and more...
 
 ## Quick example

data/README_FULL.md

@@ -1,6 +1,6 @@
 # Algebrick
 
-It's a gem providing **algebraic types** and **pattern matching** and seamlessly integrating with standard features of Ruby.
+Typed structs on steroids based on algebraic types and pattern matching seamlessly integrating with standard Ruby features.
 
 -   Documentation: <http://blog.pitr.ch/algebrick>
 -   Source: <https://github.com/pitr-ch/algebrick>
@@ -12,19 +12,23 @@ It's a gem providing **algebraic types** and **pattern matching** and seamlessly
 
 ## Algebraic types
 
-Algebraic type is a kind of composite type, i.e. a type formed by combining other types.
+Algebraic types are:
+
+-   products with a given number of fields,
+-   or a kind of composite type, i.e. a type formed by combining other types.
+
 In Haskell algebraic type looks like this:
 
     data Tree = Empty
               | Leaf Int
               | Node Tree Tree
-			  
-	depth :: Tree -> Int
-	      depth Empty = 0
-	      depth (Leaf n) = 1
-	      depth (Node l r) = 1 + max (depth l) (depth r)
+              
+    depth :: Tree -> Int
+    depth Empty = 0
+    depth (Leaf n) = 1
+    depth (Node l r) = 1 + max (depth l) (depth r)
     
-	depth (Node Empty (Leaf 5)) -- => 2
+    depth (Node Empty (Leaf 5)) -- => 2
 
 This snippet defines type `Tree` which has 3 possible values:
 
@@ -95,19 +99,7 @@ Algebraic types also play nice with JSON serialization and de-serialization maki
 
 Just a small snippet how it can be used in Actor model world.
 
-    class Worker < AbstractActor
-      def initialize(executor)
-        super()
-        @executor = executor
-      end
-
-      def on_message(message)
-        match message,
-              Work.(~any, ~any) >-> actor, work do
-                @executor.tell Finished[actor, work.call, self.reference]
-              end
-      end
-    end
+{include:file:doc/actor.rb}
 
 <!--
 ### Null Object Pattern

data/VERSION

@@ -1 +1 @@
-0.4.0
+0.5.0

data/doc/actor.rb

@@ -0,0 +1,21 @@
+Work = Algebrick.type do
+  fields key: String, work: Proc
+end
+
+Finished = Algebrick.type do
+  fields key: String, result: Object, worker: Worker
+end
+
+class Worker < AbstractActor
+  def initialize(executor)
+    super()
+    @executor = executor
+  end
+
+  def on_message(message)
+    match message,
+          Work.(~any, ~any) >-> key, work do
+            @executor.tell Finished[key, work.call, self]
+          end
+  end
+end

data/doc/data.in.rb

@@ -0,0 +1,99 @@
+extend Algebrick::Matching
+
+# Simple data structures like trees
+Tree = Algebrick.type do |tree|
+  variants Tip  = type,
+           Node = type { fields value: Object, left: tree, right: tree }
+end
+
+module Tree
+  def depth
+    match self,
+          Tip.to_m >> 0,
+          Node.(any, ~any, ~any) >-> left, right do
+            1 + [left.depth, right.depth].max
+          end
+  end
+end #
+
+tree = Node[2,
+            Tip,
+            Node[5,
+                 Node[4, Tip, Tip],
+                 Node[6, Tip, Tip]]]
+tree.depth
+
+# Whenever you find yourself to pass around too many fragile Hash-Array structures
+# e.g. for menus.
+Menu = Algebrick.type do |menu|
+  Item = Algebrick.type do
+    variants Delimiter = atom,
+             Link      = type { fields! label: String, url: String },
+             Group     = type { fields! label: String, submenu: menu }
+  end
+
+  fields! item: Item, next: menu
+  variants None = atom, menu
+end
+None
+Item
+
+module Link
+  def self.new(*fields)
+    super(*fields).tap { |menu| valid! menu.url }
+  end
+
+  def self.valid!(url)
+    # stub
+  end
+end #
+
+module Item
+  def draw_menu(indent = 0)
+    match self,
+          Delimiter >-> { [' '*indent + '-'*10] },
+          Link.(label: ~any) >-> label { [' '*indent + label] },
+          (on ~Group do |(label, sub_menu)|
+            [' '*indent + label] + sub_menu.draw_menu(indent + 2)
+          end)
+  end
+end #
+
+module Menu
+  def self.build(*items)
+    items.reverse_each.reduce(None) { |menu, item| Menu[item, menu] }
+  end
+
+  include Enumerable
+
+  def each(&block)
+    it = self
+    loop do
+      break if None === it
+      block.call it.item
+      it = it.next
+    end
+  end
+
+  def draw_menu(indent = 0)
+    map { |item| item.draw_menu indent }.reduce(&:+)
+  end
+end #
+
+sub_menu = Menu.build Link['Red Hat', '#red-hat'],
+                      Delimiter,
+                      Link['Ubuntu', '#ubuntu'],
+                      Link['Mint', '#mint']
+
+menu = Menu.build Link['Home', '#home'],
+                  Delimiter,
+                  Group['Linux', sub_menu],
+                  Link['About', '#about']
+
+menu.draw_menu.join("\n")
+
+
+#     Group['Products',
+#           Menu[]],
+#     Link['About', '#about']
+#]]

data/doc/data.out.rb

@@ -0,0 +1,103 @@
+extend Algebrick::Matching                         # => main
+
+# Simple data structures like trees
+Tree = Algebrick.type do |tree|
+  variants Tip  = type,
+           Node = type { fields value: Object, left: tree, right: tree }
+end                                                # => Tree(Tip | Node)
+
+module Tree
+  def depth
+    match self,
+          Tip.to_m >> 0,
+          Node.(any, ~any, ~any) >-> left, right do
+            1 + [left.depth, right.depth].max
+          end
+  end
+end 
+
+tree = Node[2,
+            Tip,
+            Node[5,
+                 Node[4, Tip, Tip],
+                 Node[6, Tip, Tip]]]
+    # => Node[value: 2, left: Tip, right: Node[value: 5, left: Node[value: 4, left: Tip, right: Tip], right: Node[value: 6, left: Tip, right: Tip]]]
+tree.depth                                         # => 3
+
+# Whenever you find yourself to pass around too many fragile Hash-Array structures
+# e.g. for menus.
+Menu = Algebrick.type do |menu|
+  Item = Algebrick.type do
+    variants Delimiter = atom,
+             Link      = type { fields! label: String, url: String },
+             Group     = type { fields! label: String, submenu: menu }
+  end
+
+  fields! item: Item, next: menu
+  variants None = atom, menu
+end                                                # => Menu(None | Menu(item: Item, next: Menu))
+None                                               # => None
+Item                                               # => Item(Delimiter | Link | Group)
+
+module Link
+  def self.new(*fields)
+    super(*fields).tap { |menu| valid! menu.url }
+  end
+
+  def self.valid!(url)
+    # stub
+  end
+end 
+
+module Item
+  def draw_menu(indent = 0)
+    match self,
+          Delimiter >-> { [' '*indent + '-'*10] },
+          Link.(label: ~any) >-> label { [' '*indent + label] },
+          (on ~Group do |(label, sub_menu)|
+            [' '*indent + label] + sub_menu.draw_menu(indent + 2)
+          end)
+  end
+end 
+
+module Menu
+  def self.build(*items)
+    items.reverse_each.reduce(None) { |menu, item| Menu[item, menu] }
+  end
+
+  include Enumerable
+
+  def each(&block)
+    it = self
+    loop do
+      break if None === it
+      block.call it.item
+      it = it.next
+    end
+  end
+
+  def draw_menu(indent = 0)
+    map { |item| item.draw_menu indent }.reduce(&:+)
+  end
+end 
+
+sub_menu = Menu.build Link['Red Hat', '#red-hat'],
+                      Delimiter,
+                      Link['Ubuntu', '#ubuntu'],
+                      Link['Mint', '#mint']
+    # => Menu[item: Link[label: Red Hat, url: #red-hat], next: Menu[item: Delimiter, next: Menu[item: Link[label: Ubuntu, url: #ubuntu], next: Menu[item: Link[label: Mint, url: #mint], next: None]]]]
+
+menu = Menu.build Link['Home', '#home'],
+                  Delimiter,
+                  Group['Linux', sub_menu],
+                  Link['About', '#about']
+    # => Menu[item: Link[label: Home, url: #home], next: Menu[item: Delimiter, next: Menu[item: Group[label: Linux, submenu: Menu[item: Link[label: Red Hat, url: #red-hat], next: Menu[item: Delimiter, next: Menu[item: Link[label: Ubuntu, url: #ubuntu], next: Menu[item: Link[label: Mint, url: #mint], next: None]]]]], next: Menu[item: Link[label: About, url: #about], next: None]]]]
+
+menu.draw_menu.join("\n")
+    # => "Home\n----------\nLinux\n  Red Hat\n  ----------\n  Ubuntu\n  Mint\nAbout"
+
+
+#     Group['Products',
+#           Menu[]],
+#     Link['About', '#about']
+#]]

data/doc/extending_behavior.in.rb

@@ -0,0 +1,61 @@
+Maybe = Algebrick.type do
+  variants None = atom,
+           Some = type { fields Object }
+end
+
+# Types can be extended with usual syntax for modules and using Ruby supports module reopening.
+module Maybe
+  def maybe(&block)
+    case self
+    when None
+    when Some
+      block.call value
+    end
+  end
+end #
+
+# #maybe method is defined on both values (None, Some) of Maybe.
+None.maybe { |_| raise 'never ever happens' }
+# Block is called with the value.
+Some[1].maybe { |v| v*2 }
+
+# It also works as expected when modules like Comparable are included.
+Season = Algebrick.type do
+  variants Spring = atom,
+           Summer = atom,
+           Autumn = atom,
+           Winter = atom
+end
+
+module Season
+  include Comparable
+  ORDER = Season.variants.each_with_index.each_with_object({}) { |(season, i), h| h[season] = i }
+
+  def <=>(other)
+    Type! other, Season
+    ORDER[self] <=> ORDER[other]
+  end
+end #
+
+Quarter = Algebrick.type do
+  fields! year: Integer, season: Season
+end
+
+module Quarter
+  include Comparable
+
+  def <=>(other)
+    Type! other, Quarter
+    [year, season] <=> [other.year, other.season]
+  end
+end #
+
+# Now Quarters and Seasons can be compared as expected.
+[Winter, Summer, Spring, Autumn].sort
+Quarter[2013, Spring] < Quarter[2013, Summer]
+Quarter[2014, Spring] > Quarter[2013, Summer]
+Quarter[2014, Spring] == Quarter[2014, Spring]
+[Quarter[2013, Spring], Quarter[2013, Summer], Quarter[2014, Spring]].sort
+
+
+

data/doc/extending_behavior.out.rb

@@ -0,0 +1,62 @@
+Maybe = Algebrick.type do
+  variants None = atom,
+           Some = type { fields Object }
+end                                                # => Maybe(None | Some)
+
+# Types can be extended with usual syntax for modules and using Ruby supports module reopening.
+module Maybe
+  def maybe(&block)
+    case self
+    when None
+    when Some
+      block.call value
+    end
+  end
+end 
+
+# #maybe method is defined on both values (None, Some) of Maybe.
+None.maybe { |_| raise 'never ever happens' }      # => nil
+# Block is called with the value.
+Some[1].maybe { |v| v*2 }                          # => 2
+
+# It also works as expected when modules like Comparable are included.
+Season = Algebrick.type do
+  variants Spring = atom,
+           Summer = atom,
+           Autumn = atom,
+           Winter = atom
+end                                                # => Season(Spring | Summer | Autumn | Winter)
+
+module Season
+  include Comparable
+  ORDER = Season.variants.each_with_index.each_with_object({}) { |(season, i), h| h[season] = i }
+
+  def <=>(other)
+    Type! other, Season
+    ORDER[self] <=> ORDER[other]
+  end
+end 
+
+Quarter = Algebrick.type do
+  fields! year: Integer, season: Season
+end                                                # => Quarter(year: Integer, season: Season)
+
+module Quarter
+  include Comparable
+
+  def <=>(other)
+    Type! other, Quarter
+    [year, season] <=> [other.year, other.season]
+  end
+end 
+
+# Now Quarters and Seasons can be compared as expected.
+[Winter, Summer, Spring, Autumn].sort              # => [Spring, Summer, Autumn, Winter]
+Quarter[2013, Spring] < Quarter[2013, Summer]      # => true
+Quarter[2014, Spring] > Quarter[2013, Summer]      # => true
+Quarter[2014, Spring] == Quarter[2014, Spring]     # => true
+[Quarter[2013, Spring], Quarter[2013, Summer], Quarter[2014, Spring]].sort
+    # => [Quarter[year: 2013, season: Spring], Quarter[year: 2013, season: Summer], Quarter[year: 2014, season: Spring]]
+
+
+

data/doc/format.rb

@@ -0,0 +1,75 @@
+require 'rubygems'
+require 'bundler/setup'
+require 'pry'
+require 'pp'
+
+input_paths = if ARGV.empty?
+                Dir.glob("#{File.dirname(__FILE__)}/*.in.rb")
+              else
+                ARGV
+              end.map { |p| File.expand_path p }
+
+input_paths.each_with_index do |input_path, i|
+
+  pid = fork do
+    require_relative 'init.rb'
+
+    begin
+      output_path = input_path.gsub /\.in\.rb$/, '.out.rb'
+      input       = File.readlines(input_path)
+
+      chunks = []
+      line   = ''
+
+      while !input.empty?
+        line += input.shift
+        if Pry::Code.complete_expression? line
+          chunks << line
+          line = ''
+        end
+      end
+
+      raise unless line.empty?
+
+      chunks.map! { |chunk| [chunk, [chunk.split($/).size, 1].max] }
+      environment = Module.new.send :binding
+      evaluate    = ->(code, line) do
+        eval(code, environment, input_path, line)
+      end
+
+      indent = 50
+
+      line_count = 1
+      output     = ''
+      chunks.each do |chunk, lines|
+        result = evaluate.(chunk, line_count)
+        unless chunk.strip.empty? || chunk =~ /\A *#/
+          pre_lines = chunk.lines.to_a
+          last_line = pre_lines.pop
+          output << pre_lines.join
+
+          if last_line =~ /\#$/
+            output << last_line.gsub(/\#$/, '')
+          else
+            if last_line.size < indent && result.inspect.size < indent
+              output << "%-#{indent}s %s" % [last_line.chomp, "# => #{result.inspect}\n"]
+            else
+              output << last_line << "    # => #{result.inspect}\n"
+            end
+          end
+        else
+          output << chunk
+        end
+        line_count += lines
+      end
+
+      puts "#{input_path}\n -> #{output_path}"
+      #puts output
+      File.write(output_path, output)
+    rescue => ex
+      puts "#{ex} (#{ex.class})\n#{ex.backtrace * "\n"}"
+    end
+  end
+
+  Process.wait pid
+end

data/doc/init.rb

@@ -0,0 +1 @@
+require 'algebrick'

data/doc/json.in.rb

@@ -0,0 +1,39 @@
+extend Algebrick::Matching
+
+# Lets define message-protocol for a cross-process communication.
+Request = Algebrick.type do
+  User = type { fields login: String, password: String }
+
+  variants CreateUser = type { fields User },
+           GetUser    = type { fields login: String }
+end
+
+Response = Algebrick.type do
+  variants Success = type { fields Object },
+           Failure = type { fields error: String }
+end
+
+Message = Algebrick.type { variants Request, Response }
+
+require 'algebrick/serializer'
+require 'multi_json'
+
+# Prepare a message for sending.
+serializer   = Algebrick::Serializer.new
+request      = CreateUser[User['root', 'lajDh4']]
+raw_request  = MultiJson.dump serializer.dump(request)
+
+# Receive the message.
+response     = match serializer.load(MultiJson.load(raw_request)),
+                     (on CreateUser.(~any) do |user|
+                       # create the user and send success
+                       Success[user]
+                     end)
+
+# Send response.
+response_raw = MultiJson.dump serializer.dump(response)
+
+# Receive response.
+serializer.load(MultiJson.load(response_raw))
+
+

data/doc/json.out.rb

@@ -0,0 +1,43 @@
+extend Algebrick::Matching                         # => main
+
+# Lets define message-protocol for a cross-process communication.
+Request = Algebrick.type do
+  User = type { fields login: String, password: String }
+
+  variants CreateUser = type { fields User },
+           GetUser    = type { fields login: String }
+end                                                # => Request(CreateUser | GetUser)
+
+Response = Algebrick.type do
+  variants Success = type { fields Object },
+           Failure = type { fields error: String }
+end                                                # => Response(Success | Failure)
+
+Message = Algebrick.type { variants Request, Response }
+    # => Message(Request | Response)
+
+require 'algebrick/serializer'                     # => true
+require 'multi_json'                               # => true
+
+# Prepare a message for sending.
+serializer   = Algebrick::Serializer.new           # => #<Algebrick::Serializer:0x007fab42bdf6d8>
+request      = CreateUser[User['root', 'lajDh4']]
+    # => CreateUser[User[login: root, password: lajDh4]]
+raw_request  = MultiJson.dump serializer.dump(request)
+    # => "{\"algebrick_type\":\"CreateUser\",\"algebrick_fields\":[{\"algebrick_type\":\"User\",\"login\":\"root\",\"password\":\"lajDh4\"}]}"
+
+# Receive the message.
+response     = match serializer.load(MultiJson.load(raw_request)),
+                     (on CreateUser.(~any) do |user|
+                       # create the user and send success
+                       Success[user]
+                     end)                          # => Success[User[login: root, password: lajDh4]]
+
+# Send response.
+response_raw = MultiJson.dump serializer.dump(response)
+    # => "{\"algebrick_type\":\"Success\",\"algebrick_fields\":[{\"algebrick_type\":\"User\",\"login\":\"root\",\"password\":\"lajDh4\"}]}"
+
+# Receive response.
+serializer.load(MultiJson.load(response_raw))      # => Success[User[login: root, password: lajDh4]]
+
+

data/doc/null.in.rb

@@ -0,0 +1,36 @@
+extend Algebrick::Matching
+
+def deliver_email(email)
+  true
+end #
+
+Contact = Algebrick.type do |contact|
+  variants Null = atom,
+           contact
+  fields username: String, email: String
+end
+
+module Contact
+  def username
+    match self,
+          Null >> 'no name',
+          Contact >-> { self[:username] }
+  end
+  def email
+    match self,
+          Null >> 'no email',
+          Contact >-> { self[:email] }
+  end
+  def deliver_personalized_email
+    match self,
+          Null >> true,
+          Contact >-> { deliver_email(self.email) }
+  end
+end #
+
+peter  = Contact['peter', 'example@dot.com']
+john   = Contact[username: 'peter', email: 'example@dot.com']
+nobody = Null
+
+[peter, john, nobody].map &:email
+[peter, john, nobody].map &:deliver_personalized_email

data/doc/null.out.rb

@@ -0,0 +1,40 @@
+extend Algebrick::Matching                         # => main
+
+def deliver_email(email)
+  true
+end 
+
+Contact = Algebrick.type do |contact|
+  variants Null = atom,
+           contact
+  fields username: String, email: String
+end
+    # => Contact(Null | Contact(username: String, email: String))
+
+module Contact
+  def username
+    match self,
+          Null >> 'no name',
+          Contact >-> { self[:username] }
+  end
+  def email
+    match self,
+          Null >> 'no email',
+          Contact >-> { self[:email] }
+  end
+  def deliver_personalized_email
+    match self,
+          Null >> true,
+          Contact >-> { deliver_email(self.email) }
+  end
+end 
+
+peter  = Contact['peter', 'example@dot.com']       # => Contact[username: peter, email: example@dot.com]
+john   = Contact[username: 'peter', email: 'example@dot.com']
+    # => Contact[username: peter, email: example@dot.com]
+nobody = Null                                      # => Null
+
+[peter, john, nobody].map &:email
+    # => ["example@dot.com", "example@dot.com", "no email"]
+[peter, john, nobody].map &:deliver_personalized_email
+    # => [true, true, true]