raki 0.0.3 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ab3397c01504c3d1377e3677fd9ab6e96bd008483439b67d5aec2470d148d8a7
-  data.tar.gz: 1c9785b4be9430e556cc5493864c9e8147fa161122275a11c3f37805f335e12f
+  metadata.gz: 44d1c46c2049a9ce58482fd1142eeb6bb7918389231e86eef6fea8ad8ec00653
+  data.tar.gz: 36f8ebea936c45decc39f7d93493132c029be5c9320498491e719ead1b2bc5c7
 SHA512:
-  metadata.gz: be5079c7ae71b350f7e46190153bbe6b2f75c00d998dfa8ed87e80be9c28f908ea8da0aa161ee6ec1666ae0ba840ab3243d693c23aafe63e88fd4bae03a0d445
-  data.tar.gz: ffe994cb549ef1edc9456afa5e3017d886118a0a95bd90ff6db678a0a112c6902d8abd7009953a5bbb3585368ad2a95393fc114a948a822e5fb72790360d8b86
+  metadata.gz: eda887ab0b6504e8879a3f771e649cf3490f69240a384dedba908092d0fdb2043f80db7a7f7bc99421e177e0acb466b49810643cc2055b5dd836068a5d01c87c
+  data.tar.gz: f8c2e6802a753cf4f52d5264395679221cffb41746a55953f1db3a3c000eadea7a7f52d6607a6aa581ac03774d5da16d44b18e493d270af0ad6ec7e40bad6dfc

data/LICENSE

@@ -1,6 +1,6 @@
-MIT License
+The MIT License (MIT)
 
-Copyright (c) 2020 Dittmar Krall - www.matique.com
+Copyright (c) 2020-2023 Dittmar Krall (www.matiq.com)
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,3 +1,148 @@
-# raki
+# Raki
+[![Gem Version](https://badge.fury.io/rb/raki.png)](http://badge.fury.io/rb/raki)
 
-Under heavy construction
+The Raki specification enables a kind of piping objects.
+
+The composing is done by Raki::Chain and Raki::Builder.
+
+## Installation
+
+As usual:
+```ruby
+# Gemfile
+gem "raki"
+```
+and run "bundle install".
+
+## Specification
+
+A Raki is a Ruby object (not a class) that responds to "call".
+It takes exactly one argument, a Hash, and returns a result, again a Hash.
+
+Rakis are stackable due to the generality of its argument and result.
+
+Sometimes it is expected that a Raki delivers an array of strings as
+part of the result.
+The convention is that this array is accessed as "result[:body]".
+
+## Simple Raki
+
+A simple Raki (a proc/lambda can be a Raki):
+
+~~~
+raki = ->(hsh) { {body: ["Hello World!"]} }
+~~~
+
+and a little more complex:
+
+~~~
+raki = ->(hsh) { {body: ["Hi #{hsh[:name]!", "Nice to meet you."] } }
+~~~
+
+## Middleware
+
+A Raki::Middleware is a Raki that calls another Raki enabling
+"before" and "after" code, i.e. operations around the second Raki.
+
+A Raki middleware is ready to be stacked.
+
+A sample for a Raki middleware:
+
+~~~ruby
+# already included in "gem raki"
+module Raki
+  class Middleware
+    def initialize(app)
+      @app = app
+    end
+  end
+end
+
+
+# your sample
+class SampleMiddleware < Raki::Middleware
+  def call(env)
+    # do something before
+    result = @app.call(env) # if @app
+    # do something after
+    result[:body] << "My grain of salt."
+    result
+  end
+end
+~~~
+
+## Composing
+
+### Raki::Chain
+
+Raki::Chain chains Rakis.
+In particular, it will forward the result of a previous Raki
+as the argument of the next one.
+The argument for the first Raki is the arguent of the "call".
+The return value is the result of the last Raki.
+
+A sample:
+
+~~~
+class Cl < Raki::Base
+  def call(env)
+    env + @args.first
+  end
+end
+
+proca = ->(env) { env + "a" }
+app = Raki::Chain.new do
+  add Cl, "C"
+  add proca
+  add { |env| env + "b" }
+  add ->(env) { env + "c" }
+end
+
+app.call("") # --> "Cabc"
+~~~
+
+### Raki::Builder
+
+Raki::Builder chains Raki::Middleware.
+In particular, the "@app" is initialized for each middleware.
+The last middleware "@app" is initialized to "nil".
+
+It is expected that each middleware takes care to call the next one.
+
+A sample:
+
+~~~
+class MW < Raki::Middleware
+  def call(env)
+    result = env + @args.first
+    return result unless @app
+
+    @app.call(result)
+  end
+end
+
+app = Raki::Builder.new do
+  add MW, "a"
+  add MW, "b"
+end
+
+app.call("") # --> "ab"
+
+~~~
+
+### Recommendations
+
+Implement a Raki as idempotent, i.e. same arguments delivers same results.
+
+It is always a good idea to avoid side-effects.
+
+Frozen arguments may avoid some strange behaviour.
+
+## Miscellaneous
+
+Heavily inspired by Rack.
+
+Copyright (c) 2020-2023 Dittmar Krall (www.matiq.com),
+released under the MIT license:
+
+* https://opensource.org/licenses/MIT

data/lib/raki/builder.rb

@@ -1,59 +1,45 @@
 # frozen_string_literal: true
 
-# see also
-# cat ~/test/rack/lib/rack/builder.rb
-
-# inspired by Rack::Builder
 module Raki
-  class Builder
-    def initialize(default_app = nil, &block)
-      @added = []
-      @runs = [default_app].compact
-      instance_eval(&block) if block_given?
-    end
+  class Builder < Raki::Base
+    # attr_accessor :stack
 
-    # Create a new Raki::Builder instance and return the Raki application
-    # generated from it.
-    def self.app(default_app = nil, &block)
-      new(default_app, &block).to_app
+    def initialize(&block)
+      @stack = []
+      instance_eval(&block) if block
+      chain
     end
 
     def add(middleware, *args, &block)
-      raise 'No add allowed after a run' if @runs.size.positive?
-
-      @added <<
+      @stack <<
         if middleware.instance_of?(Class)
-          proc { |app| middleware.new(app, *args, &block) }
+          middleware.new(*args, &block)
         else
-          proc { |_app| middleware }
+          middleware
         end
     end
-    ruby2_keywords(:add) if respond_to?(:ruby2_keywords, true)
 
-    def run(app)
-      @runs << app
+    def chain
+      previous = nil
+      @stack.each do |app|
+        previous.app = app if previous
+        previous = app
+      end
     end
 
-    def to_app
-      app = fake_parallel(@runs)
-      @added.reverse.inject(app) { |a, e| e[a] }
+    def call(hsh = {})
+      @stack.first&.call(hsh)
     end
 
-   private
-    def fake_parallel(runs)
-      return runs.first if runs.size < 2
-
-      app = lambda do |env|
-        status, hsh, body = [200, {}, []]
-        runs.shuffle.each { |run|
-          s, h, b = run.call(env)
-          status = s unless s == 200
-          hsh.merge! h
-          body << b unless b.empty?
-        }
-
-        [status, hsh, body.flatten]
-      end
-    end
+    # def to_s(pre = "")
+    #   next_pre = pre + "  "
+    #   res = []
+    #   res << "#{pre}#{self.class.name} #{object_id}"
+    #   res << "#{pre}@stack.length #{@stack.length}"
+    #   @stack.each_with_index { |mv, idx|
+    #     res << "#{pre}[#{idx}] #{mv.to_s(next_pre)}"
+    #   }
+    #   res.flatten.join("\n")
+    # end
   end
 end

data/lib/raki/chain.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Raki
+  class Chain < Base
+    def initialize(*args, &block)
+      super
+      @stack = []
+      instance_eval(&block) if block
+    end
+
+    def add(middleware = nil, *args, &block)
+      middleware ||= block
+      @stack <<
+        if middleware.instance_of?(Class)
+          middleware.new(*args, &block)
+        else
+          middleware
+        end
+    end
+
+    def call(hsh)
+      my_hsh = hsh
+      @stack.each { |app| my_hsh = app.call(my_hsh) }
+      my_hsh
+    end
+
+    # def to_s(pre = "")
+    #   next_pre = pre + "  "
+    #   res = []
+    #   res << "#{pre}#{self.class.name} #{object_id}"
+    #   res << "#{pre}args #{@args}"
+    #   #  res << @app.to_s(next_pre) if @app
+    #   res << "#{pre}@app #{@app.object_id}" if @app
+    #   @stack.each_with_index { |mv, idx|
+    #     res << "#{pre}[#{idx}] #{mv.to_s(next_pre)}"
+    #   }
+    #   res.flatten.join("\n")
+    # end
+  end
+end

data/lib/raki/idem.rb

@@ -1,13 +1,10 @@
 # frozen_string_literal: true
 
-# Middleware just passing over or returning the params.
+# Rreturns "env" (doing nothing)
 module Raki
-  class Idem < Raki::MiddlewareBase
+  class Idem < Raki::Middleware
     def call(env)
-      return env unless @app
-
-      @block&.call(env)
-      @app.call(env)
+      env
     end
   end
 end

data/lib/raki/lint.rb

@@ -1,31 +1,21 @@
 # frozen_string_literal: true
 
-# Raki::AssertRequest validates your requests according to Raki spec.
-
-# see also:
-# cat ~/test/rack/lib/rack/lint.rb
-# cat ~/test/rack/SPEC.rdoc
+# validates according to Raki definition.
 module Raki
   class LintError < RuntimeError; end
 
-  class Lint < Raki::MiddlewareBase
+  class Lint < Raki::Middleware
     def call(env)
-      assert('No env given') { env }
-      assert('Block complained') { @block.call(env) } if @block
-
-      @block&.call(env)
-      response = @app.call(env)
+      assert("No env given") { env }
+      # assert("Run complained") { @block.call(env) } if @block
 
-      assert('Expected array') { response.class == Array }
-      assert('Expected array of 3 items') { response.size == 3 }
-      assert('First item must be an Integer') { response[0].class == Integer }
-      assert('Second item must be a Hash') { response[1].class == Hash }
-      assert('Third item must be an Array') { response[2].class == Array }
-
-      response
+      result = @app&.call(env)
+      assert("Expected hash") { result.instance_of?(Hash) }
+      result
     end
 
-   private
+    private
+
     def assert(message)
       return if yield
 

data/lib/raki/merge.rb

@@ -2,11 +2,11 @@
 
 # Middleware Merge.
 module Raki
-  class Merge < Raki::MiddlewareBase
+  class Merge < Raki::Middleware
     def call(env)
       my_env = env.merge(*@args)
-      @block&.call(my_env)
-      @app.call(my_env)
+      app = @block || @app
+      app.call(my_env)
     end
   end
 end

data/lib/raki/middleware.rb

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# Base for middleware
+module Raki
+  class Middleware
+    attr_accessor :app
+
+    def initialize(*args, &block)
+      @app = nil
+      @args = args
+      @block = block
+    end
+
+    def call(env)
+      my_env = env
+      result = ZERO
+      app = @block || @app
+      return result unless app
+
+      app.call(my_env)
+    end
+
+    # def to_s(pre = "")
+    #   # next_pre = pre + "  "
+    #   res = []
+    #   res << "#{pre}#{self.class.name} #{object_id}"
+    #   res << "#{pre}args #{@args}"
+    #   # res << @app.to_s(next_pre) if @app
+    #   res << "#{pre}@app #{@app.object_id}" if @app
+    #   res.flatten.join("\n")
+    # end
+  end
+end

data/lib/raki/require.rb

@@ -4,14 +4,13 @@
 module Raki
   class RequireError < RuntimeError; end
 
-  class Require < Raki::MiddlewareBase
+  class Require < Raki::Middleware
     def call(env)
       expected = @args.flatten.sort
       bool = env.keys.sort == expected
       raise(RequireError, "Expected <#{expected.join}>") unless bool
 
-      @block&.call(env)
-      @app.call(env)
+      @app&.call(env)
     end
   end
 end

data/lib/raki/slice.rb

@@ -2,11 +2,11 @@
 
 # Middleware Slice.
 module Raki
-  class Slice < Raki::MiddlewareBase
+  class Slice < Raki::Middleware
     def call(env)
       my_env = env.slice(*@args.flatten)
-      @block&.call(my_env)
-      @app.call(my_env)
+      app = @block || @app
+      app.call(my_env)
     end
   end
 end

data/lib/raki/version.rb

@@ -1,6 +1,8 @@
-# frozen_string_literal: true
-
 module Raki
-  VERSION = '0.0.3' # 2020-07-14
-#  VERSION = '0.0.2'
+  VERSION = "0.1.1" # 2023-04-26
+  # VERSION = "0.1.0" # 2021-11-03
+  # VERSION = "0.0.5" # 2021-07-01
+  # VERSION = '0.0.4' # 2021-06-25
+  # VERSION = '0.0.3' # 2020-07-14
+  # VERSION = '0.0.2'
 end

data/lib/raki/version.rb.bak

@@ -1,14 +1,8 @@
-# frozen_string_literal: true
-
-# Raki is freely distributable under the terms of an MIT-style license.
-# See MIT-LICENSE or https://opensource.org/licenses/MIT.
-
-# The Raki main module, serving as a namespace for all core Raki
-# modules and classes.
-#
-# All modules meant for use in your application are <tt>autoload</tt>ed here,
-# so it should be enough just to <tt>require 'rack'</tt> in your code.
-
 module Raki
-  VERSION = '0.0.2'
+  VERSION = "0.1.1" # 2023-04-26
+  #  VERSION = "0.1.0" # 2021-11-03
+  # VERSION = "0.0.5" # 2021-07-01
+  # VERSION = '0.0.4' # 2021-06-25
+  # VERSION = '0.0.3' # 2020-07-14
+  # VERSION = '0.0.2'
 end

data/lib/raki.rb

@@ -1,15 +1,25 @@
 # frozen_string_literal: true
 
 module Raki
-  autoload :Block,   'raki/block'
-  autoload :Builder, 'raki/builder'
-  autoload :Cache,   'raki/cache'
-  autoload :Idem,    'raki/idem'
-  autoload :Lint,    'raki/lint'
-  autoload :Merge,   'raki/merge'
-  autoload :MiddlewareBase, 'raki/middleware_base'
-  autoload :Nil,     'raki/nil'
-  autoload :Params,  'raki/params'
-  autoload :Require, 'raki/require'
-  autoload :Slice,   'raki/slice'
+  autoload :Builder, "raki/builder"
+  autoload :Chain, "raki/chain"
+  autoload :Idem, "raki/idem"
+  autoload :Lint, "raki/lint"
+  autoload :Merge, "raki/merge"
+  autoload :Middleware, "raki/middleware"
+  autoload :Params, "raki/params"
+  autoload :Require, "raki/require"
+  autoload :Slice, "raki/slice"
+
+  ZERO = {body: []}
+
+  class Base
+    def initialize(*args)
+      @args = args
+    end
+
+    def call(env)
+      ZERO
+    end
+  end
 end

metadata

@@ -1,75 +1,64 @@
 --- !ruby/object:Gem::Specification
 name: raki
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.1.1
 platform: ruby
 authors:
 - Dittmar Krall
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-07-14 00:00:00.000000000 Z
+date: 2023-04-26 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '13'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '13'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '5.0'
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: minitest-global_expectations
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1'
+        version: '0'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - "~>"
+    - - ">="
       - !ruby/object:Gem::Version
-        version: '1'
-description: 'Raki is under construction
+        version: '0'
+description: |
+  Raki enables chaining of objects.
+  It is based on the definition of an interface and
+  some builders.
 
-'
-email: dittmar.krall@matique.de
+  Chained Rakis must conforms to the Raki definition.
+email: dittmar.krall@matiq.com
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -77,22 +66,21 @@ files:
 - LICENSE
 - README.md
 - lib/raki.rb
-- lib/raki/block.rb
 - lib/raki/builder.rb
-- lib/raki/cache.rb
+- lib/raki/chain.rb
 - lib/raki/idem.rb
 - lib/raki/lint.rb
 - lib/raki/merge.rb
-- lib/raki/middleware_base.rb
-- lib/raki/nil.rb
+- lib/raki/middleware.rb
 - lib/raki/require.rb
 - lib/raki/slice.rb
 - lib/raki/version.rb
 - lib/raki/version.rb.bak
-homepage: https://matique.com
+homepage: https://matiq.com
 licenses:
 - MIT
-metadata: {}
+metadata:
+  source_code_uri: https://github.com/matique/raki
 post_install_message: 
 rdoc_options: []
 require_paths:
@@ -101,15 +89,15 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '2.6'
+      version: '0'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.8
+rubygems_version: 3.4.10
 signing_key: 
 specification_version: 4
-summary: A modular hash interface.
+summary: Kind of chaining objects
 test_files: []

data/lib/raki/block.rb

@@ -1,12 +0,0 @@
-# frozen_string_literal: true
-
-# Middleware to execute a Block.
-module Raki
-  class Block < Raki::MiddlewareBase
-    def call(env)
-      my_env = env
-      @block.call(my_env)
-      @app.call(my_env)
-    end
-  end
-end

data/lib/raki/cache.rb

@@ -1,28 +0,0 @@
-# frozen_string_literal: true
-
-require 'crimp'
-
-# not yet finished
-# requires a Rails environment! (see Rails below)
-# middleware for caching.
-
-module Raki
-  class Cache < Raki::MiddlewareBase
-    def call(env)
-      @block&.call(env)
-      kache(Crimp.signature(env)) {
-        @app.call(env)
-      }
-    end
-
-   private
-    def kache(key)
-      # raise 'Missing Rails environment' unless defined?(Rails.cache)
-      return yield unless defined?(Rails.cache)
-
-      Rails.cache.fetch(key, expires_in: 1.hour) {
-        yield
-      }
-    end
-  end
-end

data/lib/raki/middleware_base.rb

@@ -1,16 +0,0 @@
-# frozen_string_literal: true
-
-# Middleware just passing over or returning the params.
-module Raki
-  class MiddlewareBase
-    def initialize(app = nil, *args, &block)
-      @app = app
-      @args = args
-      @block = block
-    end
-
-    def call(_env)
-      raise '#call must be overwritten by a middleware raki'
-    end
-  end
-end

data/lib/raki/nil.rb

@@ -1,13 +0,0 @@
-# frozen_string_literal: true
-
-# Returns a Raki zero.
-module Raki
-  class Nil < Raki::MiddlewareBase
-    def call(_env)
-      @block&.call(env)
-      @app&.call(env)
-
-      [200, {}, []]
-    end
-  end
-end