ruff 0.0.4 → 0.0.5

data/lib/ruff.rb

@@ -6,10 +6,23 @@ require 'securerandom'
 
 module Ruff
   class << self
+    # is alias for `Effect.new`
+    # @see Effect.initialize Effect.initialize
+    #
+    # @example
+    #   Log = Ruff.instance # === Ruff::Effect.new
     def instance
       Effect.new
     end
 
+    # is alias for `Handler.new`
+    # @see Handler.initialize Handler.initialize
+    #
+    # @example
+    #   log_handler = Ruff.handler.on(Log){|msg, k|
+    #     puts "Logger: #{msg}"
+    #     k[]
+    #   }
     def handler
       Handler.new
     end

data/lib/ruff/effect.rb

@@ -1,12 +1,25 @@
 module Ruff
+  # This class provides an effect instance.
   class Effect
-    attr_accessor :id
+    # Each instance must be unique so they have unique id with UUID
+    attr_reader :id
+
+    # instaciates an effect setting `id`.
+    # @return [Effect<Arg, Ret>]
+    # @example
+    #   Log = Effect.new #==> it _might_ be Effect<string, nil>
     def initialize
       @id = SecureRandom.uuid
+      @id.freeze
     end
 
+    # sends an effect ID and its arguments to a nearmost handler.
+    # @param [Arg] a of the object `Effect<Arg, Ret>`
+    # @return [Ret] of the object `Effect<Arg, Ret>`
+    # @example
+    #   Log.perform "hello"
     def perform(*a)
-      return Fiber.yield Eff.new(@id, a)
+      return Fiber.yield Throws::Eff.new(@id, a)
     end
   end
 end

data/lib/ruff/handler.rb

@@ -1,32 +1,72 @@
 module Ruff
+  # In algebraic effects, handler is an first-class object.
   class Handler
+    # makes a new handler, internally having fresh empty hash.
+    # This is a effect-handler store and when handliong it is looked up.
+    # @example
+    #   handler = Handler.new
     def initialize
       @handlers = Hash.new
     end
 
+    # sets effec handler `&prc` for `eff`
+    #
+    # @param [Effect<Arg, Ret>] eff
+    #   the effect instance to be handled
+    # @param [Proc<Arg, Ret => A>] prc
+    #   a handler to handle `eff`;
+    #   last argument of `&prc` is *continuation*, proc object
+    #   to go back to the handled computation.
+    # @return [Handler{Effect<Arg, Ret>, e}] itself updated with handling `Effect<Arg, Ret>`
+    #
+    # @example
+    #   handler.on(Log) {|msg, k|
+    #     puts "Logger: #{msg}"
+    #     k[]
+    #   }
     def on(eff, &prc)
       @handlers[eff.id] = prc
 
       self
     end
 
+    # @param [Proc<(), T>]
+    # @return [T]
+    #
+    # handles the computation.
+    #
+    # @example
+    #   handler.run {
+    #     Log.perform "hello"
+    #   }
+    #
+    # @example `handler` can be layered.
+    #   handler.run {
+    #     Handler.new
+    #       .on(Double){|v, k|
+    #         k[v * v]
+    #       }.run {
+    #         v = Double.perform 3
+    #         Log.perform 3
+    #     }
+    #   }
     def run(&prc)
       co = Fiber.new &prc
       continue = nil
       rehandles = nil
 
       handle = ->(r) {
-        if r.is_a? Eff
+        if r.is_a? Throws::Eff
           if effh = @handlers[r.id]
             effh[continue, *r.args]
           else
-            Fiber.yield (Resend.new r, continue)
+            Fiber.yield (Throws::Resend.new r, continue)
           end
-        elsif r.is_a? Resend
+        elsif r.is_a? Throws::Resend
           if effh = @handlers[r.eff.id]
             effh[rehandles[r.k], *r.eff.args]
           else
-            Fiber.yield (Resend.new r, rehandles[r.k])
+            Fiber.yield (Throws::Resend.new r, rehandles[r.k])
           end
         else
           r
@@ -43,6 +83,10 @@ module Ruff
           newh.add_handler id, h
         }
 
+        class << newh
+          undef add_handler
+        end
+
         ->(*args) {
           continue[
             newh.run {

data/lib/ruff/objects.rb

@@ -1,15 +1,39 @@
 module Ruff
-  class Eff
-    attr_accessor :id, :args
-    def initialize(id, args)
-      @id = id; @args = args
+  module Throws
+    # `Eff` is internal object.
+    #
+    # They make effects encapsulate with ID and arguments to be sent to the handler.
+    class Eff
+
+      # makes the object unique.
+      attr_reader :id
+
+      # passes to a handler which can catch the effect.
+      attr_reader :args
+
+      # creates a new object with `id` and `args`.
+      def initialize(id, args)
+        @id = id; @args = args
+      end
     end
   end
 
-  class Resend
-    attr_accessor :eff, :k
-    def initialize(eff, k)
-      @eff = eff; @k = k
+  module Throws
+    # `Resend` is internal object like `Eff`.
+    #
+    # It is used when an effect is unable to be handled and should be thrown to the outer handler.
+    class Resend
+
+      #is abstracted effect (such as `Eff` or (re)thrown `Resend`).
+      attr_reader :eff
+
+      # is a continuation of `eff` thrown context.
+      attr_reader :k
+
+      # creates a new object with `eff` and `k`.
+      def initialize(eff, k)
+        @eff = eff; @k = k
+      end
     end
   end
 end

data/lib/ruff/version.cpp.rb

@@ -0,0 +1,5 @@
+# // This file is passed to CPP
+#include "../../version.h"
+module Ruff
+  VERSION = RUFF_VERSION
+end

data/lib/ruff/version.rb

@@ -1,3 +1,3 @@
 module Ruff
-  VERSION = "0.0.4"
+  VERSION = "0.0.5"
 end

data/ruff.gemspec

@@ -3,7 +3,7 @@ lib = File.expand_path("../lib", __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
 require "ruff/version"
 
-Gem::Specification.new do |spec|
+Gem::Specification.new{|spec|
   spec.name          = "ruff"
   spec.version       = Ruff::VERSION
   spec.authors       = ["nymphium"]
@@ -13,14 +13,17 @@ Gem::Specification.new do |spec|
   spec.description   = %q{ONE-SHOT Algebraic Effects for Ruby!}
   spec.homepage      = "https://github.com/nymphium/ruff"
   spec.license       = "MIT"
+  
 
   spec.files         = Dir.chdir(File.expand_path('..', __FILE__)) do
     `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   end
-  spec.bindir        = "exe"
-  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
   spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "rake", "~> 10.0"
-end
+
+  spec.metadata = {
+    "documentation_url" => "https://nymphium.github.io/ruff"
+  }
+}

data/version.h

@@ -0,0 +1 @@
+#define RUFF_VERSION "0.0.5"

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ruff
 version: !ruby/object:Gem::Version
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors:
 - nymphium
 autorequire: 
-bindir: exe
+bindir: bin
 cert_chain: []
-date: 2019-08-06 00:00:00.000000000 Z
+date: 2019-08-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -51,16 +51,39 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- docs/Ruff.html
+- docs/Ruff/Effect.html
+- docs/Ruff/Handler.html
+- docs/Ruff/Throws.html
+- docs/Ruff/Throws/Eff.html
+- docs/Ruff/Throws/Resend.html
+- docs/_index.html
+- docs/class_list.html
+- docs/css/common.css
+- docs/css/full_list.css
+- docs/css/style.css
+- docs/file.README.html
+- docs/file_list.html
+- docs/frames.html
+- docs/index.html
+- docs/js/app.js
+- docs/js/full_list.js
+- docs/js/jquery.js
+- docs/method_list.html
+- docs/top-level-namespace.html
 - lib/ruff.rb
 - lib/ruff/effect.rb
 - lib/ruff/handler.rb
 - lib/ruff/objects.rb
+- lib/ruff/version.cpp.rb
 - lib/ruff/version.rb
 - ruff.gemspec
+- version.h
 homepage: https://github.com/nymphium/ruff
 licenses:
 - MIT
-metadata: {}
+metadata:
+  documentation_url: https://nymphium.github.io/ruff
 post_install_message: 
 rdoc_options: []
 require_paths: