ruff 1.0.1 → 1.1.0

data/docs/top-level-namespace.html

@@ -6,7 +6,7 @@
 <title>
   Top Level Namespace
   
-    &mdash; Ruff 1.0.0 Documentation
+    &mdash; Ruff 1.0.1 Documentation
   
 </title>
 
@@ -100,7 +100,7 @@
 </div>
 
       <div id="footer">
-  Generated on Thu Oct  3 05:05:04 2019 by
+  Generated on Fri Oct  4 13:57:07 2019 by
   <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
   0.9.20 (ruby-2.6.4).
 </div>

data/lib/ruff/handler.rb

@@ -13,7 +13,6 @@ class Ruff::Handler
   #
   # @example
   #   handler = Handler.new
-
   def initialize
     @handlers = {}
     @valh = ->(x) { x }
@@ -24,7 +23,8 @@ class Ruff::Handler
   # Value handler is the handler for *the result value of the computation*.
   # For example, `Handler.new.to{|_x| 0}.run { value }` results in `0` .
   #
-  # The value handler modifies the result of the call of continuation in effect handlers of the handler.
+  # The value handler modifies the result of the call of continuation
+  # in effect handlers of the handler.
   #
   # @param [Proc<A, B>] fun
   #   value handler
@@ -52,7 +52,6 @@ class Ruff::Handler
   #   # msg>> hello
   #   # msg>> world
   #   # returns !
-
   def to(&fun)
     @valh = fun
 
@@ -67,14 +66,14 @@ class Ruff::Handler
   #   a handler to handle `eff`;
   #   First argument of `&fun` is *continuation*, proc object
   #   to go back to the handled computation.
-  # @return [Handler<A!{Effect<Arg, Ret>, e}, B!{e}>] itself updated with handling `Effect<Arg, Ret>`
+  # @return [Handler<A!{Effect<Arg, Ret>, e}, B!{e}>]
+  #   itself updated with handling `Effect<Arg, Ret>`
   #
   # @example
   #   handler.on(Log) {|k, msg|
   #     puts "Logger: #{msg}"
   #     k[]
   #   }
-
   def on(eff, &fun)
     @handlers[eff.id] = fun
 
@@ -86,7 +85,8 @@ class Ruff::Handler
   # @param [Proc<(), A>] prc
   #   a thunk to be handled and returns `A`
   # @return [B]
-  #   a value modified by value handler `Proc<A, B>` , or returned from the effect handler throwing continuation away
+  #   a value modified by value handler `Proc<A, B>` ,
+  #   or returned from the effect handler throwing continuation away
   #
   # @example
   #   handler.run {
@@ -103,57 +103,58 @@ class Ruff::Handler
   #         Log.perform 3
   #     }
   #   }
-
   def run(&prc)
-    co = Fiber.new &prc
-    continue = nil
-    rehandles = nil
-
-    handle = lambda { |r|
-      case r
-      when Eff
-        if effh = @handlers[r.id]
-          effh[continue, *r.args]
-        else
-          Fiber.yield Resend.new(r, continue)
-        end
-      when Resend then
-        eff = r.eff
-        next_k = rehandles.call(r.k)
-
-        if effh = @handlers[eff.id]
-          effh.call(next_k, *eff.args)
-        else
-          Fiber.yield Resend.new(eff, next_k)
-        end
-      else
-        @valh.call(r)
-      end
-    }
+    co = Fiber.new(&prc)
 
-    rehandles = lambda { |k|
-      newh = self.class.new
-      def newh.add_handler(id, h)
-        @handlers[id] = h
-      end
+    continue(co).call(nil)
+  end
+
+  # is also private method.
+  def handlers=(handlers)
+    @handlers = handlers.dup
+  end
 
-      @handlers.each do |id, h|
-        newh.add_handler id, h
+  private
+
+  def continue(co)
+    ->(*arg) { handle(co, co.resume(*arg)) }
+  end
+
+  # rubocop:disable Metrics/AbcSize
+  def handle(co, r)
+    case r
+    when Eff
+      if (effh = @handlers[r.id])
+        effh[continue(co), *r.args]
+      else
+        Fiber.yield Resend.new(r, continue(co))
       end
+    when Resend then
+      eff = r.eff
+      next_k = rehandles(co, r.k)
 
-      class << newh
-        undef add_handler
+      if (effh = @handlers[eff.id])
+        effh.call(next_k, *eff.args)
+      else
+        Fiber.yield Resend.new(eff, next_k)
       end
+    else
+      @valh.call(r)
+    end
+  end
+  # rubocop:enable Metrics/AbcSize
 
-      lambda { |*args|
-        continue.call(newh.run { k.call(*args) })
-      }
-    }
+  def rehandles(co, k)
+    newh = self.class.new
 
-    continue = lambda { |*arg|
-      handle.call(co.resume(*arg))
-    }
+    newh.handlers = @handlers
 
-    continue.call(nil)
+    lambda { |*args|
+      newh
+        .to { |v| continue(co).call(v) }
+        .run { k.call(*args) }
+    }
   end
+
+  private_methods :handlers=
 end

data/lib/ruff/objects.rb

@@ -14,7 +14,8 @@ class Ruff::Throws::Eff
 
   # creates a new object with `id` and `args`.
   def initialize(id, args)
-    @id = id; @args = args
+    @id = id
+    @args = args
   end
 end
 
@@ -30,6 +31,7 @@ class Ruff::Throws::Resend
 
   # creates a new object with `eff` and `k`.
   def initialize(eff, k)
-    @eff = eff; @k = k
+    @eff = eff
+    @k = k
   end
 end

data/lib/ruff/standard.rb

@@ -1,5 +1,21 @@
 # frozen_string_literal: true
 
+# `Ruff::Standard` provides several pre-defined effect handlers modules.
+# Each module provides `Instance` class to instantiate and handle the indivisual effect instances.
+# @example
+#   include Ruff::Standard
+#
+#   state1 = State::Instance.new
+#   state2 = State::Instance.new
+#
+#   state1.with_init(3) {
+#   state2.with_init(4) {
+#     state2.modify {|s| s + state1.get }
+#
+#     puts state1.get #==> 3
+#     puts state2.get #==> 7
+#   }}
+#
 module Ruff::Standard end
 
 require 'ruff/standard/current_time'

data/lib/ruff/standard/current_time.rb

@@ -1,30 +1,57 @@
 # frozen_string_literal: true
 
+# `CurrentTime` provides an effect `CurrentTime.eff` and the implementation returning `Time.now` .
+#
+# The module has an instance of `Instance` and provides its methods as module method.
+# @see Standard::CurrentTime::Instance
 module Ruff::Standard::CurrentTime
   class Instance
+    # makes a new instance.
     def initialize
       @eff = Ruff.instance
     end
 
+    # is a smart method to invoke the effect operation.
+    # @return [Time]
+    #   with `with` , returns `Time.now`
     def get
       @eff.perform
     end
 
+    # is a handler to interpret the effect invokation as requesting the current time.
+    # This handler receives the *request* and returns current time.
+    #
+    # @param [Proc<(), A>!{CurrentTime.eff, e}] th
+    #  is a thunk returning `A` with the possibility to invoke effects,
+    #  including `CurrentTime.eff` .
+    #
+    # @return [A!{e}]
+    #   returns `A` , without modification by value handler.
+    #   But it still has the possibility to invoke effects(`e`).
     def with(&th)
-      Ruff.handler.on(@eff) { |k| k[Time.now] }.run &th
+      Ruff.handler.on(@eff) { |k| k[Time.now] }.run(&th)
     end
+
+    # You can reimplement the handler using this effect instance.
+    attr_reader :eff
   end
 
   # ---
   @inst = Instance.new
+  @eff = @inst.eff
 
+  # @see Ruff::Standard::CurrentTime::Instance#get
   def get
     @inst.get
   end
 
+  # @see Ruff::Standard::CurrentTime::Instance#with
   def with(&th)
-    @inst.with &th
+    @inst.with(&th)
   end
 
   module_function :get, :with
+
+  # @see Ruff::Standard::CurrentTime::Instance#eff
+  attr_reader :eff
 end

data/lib/ruff/standard/defer.rb

@@ -1,16 +1,36 @@
 # frozen_string_literal: true
 
+# `Defer` provides effects `Defer.eff` ,
+# and the implementation to defer procedures .
+#
+# The module has an instance of `Instance` and provides its methods as module method.
+# @see Standard::Defer::Instance
 module Ruff::Standard::Defer
   class Instance
+    # makes a new instance.
     def initialize
       @eff = Ruff.instance
     end
 
+    # is a smart method to invoke the effect operation.
+    # @param [Proc<(), ()>] prc
+    #   is deferred, or "registerred", and called on the end of computation.
+    # @return [()]
     def register(&prc)
       @eff.perform prc
     end
 
+    # is a handler to interpret the effect invocation as registering a procedure.
+    # Registerred procedures are run on the end of computation, by value handler.
+    #
+    # @param [Proc<(), A>!{Defer.eff, e}] th
+    #  is a thunk returning `A` with the possibility to invoke effects, including `Defer.eff` .
+    #
+    # @return [A!{e}]
+    #   returns `A` , without modification by value handler.
+    #   But it still has the possibility to invoke effects(`e`).
     def with(&th)
+      # This is a stack to store deferred procedures.
       procs = []
 
       Ruff.handler
@@ -19,22 +39,32 @@ module Ruff::Standard::Defer
         k[]
       end
           .to do |_|
+        # Like Go's defer functions, it crashes the thunk by reversed order.
         procs.reverse_each(&:[])
       end
-          .run &th
+          .run(&th)
     end
+
+    # You can reimplement the handler using this effect instance.
+    attr_reader :eff
   end
 
   # ---
   @inst = Instance.new
+  @eff = @inst.eff
 
+  # @see Ruff::Standard::Defer::Instance#register
   def register(&prc)
-    @inst.register &prc
+    @inst.register(&prc)
   end
 
+  # @see Ruff::Standard::Defer::Instance#with
   def with(&th)
-    @inst.with &th
+    @inst.with(&th)
   end
 
   module_function :register, :with
+
+  # @see Ruff::Standard::Defer::Instance#eff
+  attr_reader :eff
 end

data/lib/ruff/standard/state.rb

@@ -1,65 +1,120 @@
 # frozen_string_literal: true
 
+require 'ostruct'
+
+# `State` provides effects `State.get` and `State.modify` ,
+# and the implementation of the mutable cell or so-called *state* .
+#
+# The module has an instance of `Instance` and provides its methods as module method.
+# @see Standard::State::Instance
 module Ruff::Standard::State
   class Instance
+    # makes new instances.
     def initialize
-      @get = Ruff.instance
-      @modify = Ruff.instance
+      get = Ruff.instance
+      modify = Ruff.instance
+
+      # delegates effect instances
+      @eff = OpenStruct.new(get: get, modify: modify)
     end
 
+    # is a smart method to invoke the effect operation `State.get` .
+    # @return [S]
+    #   with `with` , returns `S` , the current state.
     def get
-      @get.perform
+      @eff.get.perform
     end
 
+    # is a smart hetmod to invoke the effect operation `State.modify` .
+    # @param [Proc<S, U>] fn
+    #   is the function to modify the state `S` to `U` .
+    #   This function has an argument receiving the state.
+    # @return [()]
     def modify(&fn)
-      @modify.perform fn
+      @eff.modify.perform fn
     end
 
+    # is a short hand for `modify {|_| s }`
+    # @param [S] s
+    #   is the new state.
+    # @return [()]
     def put(s)
-      @modify.perform ->(_) { s }
+      @eff.modify.perform ->(_) { s }
     end
 
-    def with_init(init, &task)
+    # is a handler to interpret the effect invocations like *state monad* .
+    #
+    # @param [S] init
+    #   is the initial state.
+    # @param [Proc<(), A!{State.get, State.modify,, e}>] th
+    #  is a thunk returning `A` with the possibility to invoke effects,
+    #  including `State.get` and `State.modify` .
+    # @return [A!{e}]
+    #   returns `A` , without modification by value handler.
+    #   But it still has the possibility to invoke effects(`e`).
+    def with_init(init, &th)
+      # not a parameter passing style, or so-called *pure* implementation,
+      # just using mutable assignment
       state = init
 
       Ruff.handler
-          .on(@modify) do |k, fn|
+          .on(@eff.modify) do |k, fn|
         state = fn[state]
         k[nil]
-      end
-          .on(@get) do |k|
+      end.on(@eff.get) do |k|
         k[state]
       end
-          .run &task
+          .run(&th)
     end
 
-    def with(&task)
-      with_init(nil, &task)
+    # is a short hand for `with_init(nil, th)` .
+    #
+    # @param [Proc<(), A!{State.get, State.modify,, e}>] th
+    #  is a thunk returning `A` with the possibility to invoke effects,
+    #  including `State.get` and `State.modify` .
+    # @return [A!{e}]
+    #   returns `A` , without modification by value handler.
+    #   But it still has the possibility to invoke effects(`e`).
+    def with(&th)
+      with_init(nil, &th)
     end
+
+    # You can reimplement the handler using these effect instances
+    # with accessing `#eff.get` and `#eff.modify` .
+    attr_reader :eff
   end
 
   # ---
   @inst = Instance.new
+  @eff = @inst.eff
 
+  # @see Ruff::Standard::State::Instance#get
   def get
     @inst.get
   end
 
+  # @see Ruff::Standard::State::Instance#modify
   def modify(&fn)
-    @inst.modify &fn
+    @inst.modify(&fn)
   end
 
+  # @see Ruff::Standard::State::Instance#put
   def put(s)
     @inst.put s
   end
 
+  # @see Ruff::Standard::State::Instance#with_init
   def with_init(init, &task)
     @inst.with_init init, &task
   end
 
+  # @see Ruff::Standard::State::Instance#with
   def with(&task)
-    @inst.with &task
+    @inst.with(&task)
   end
 
   module_function :get, :put, :modify, :with, :with_init
+
+  # @see Ruff::Standard::Instance#eff
+  attr_reader :eff
 end