noaidi 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 616599ed29b3b649e96e11e287fe697930b16cd6
+  data.tar.gz: ca3cd45631602312e0928079f75098b734c1b91c
+SHA512:
+  metadata.gz: d4974660037e467062b5200c645ff7a8365b28c4828611afe15628a8805db70bfc13d46a8bc7f78f637229fbb08c8d5b8b12cf0dc9abee6ec57fd748932f9f50
+  data.tar.gz: 5c8ef7539e37911f5d85c8177eb28c50a51bf94f2ed27d75e4a8da0f88ca7912aafa472de2131e1e3d3f8fc7dea09d30f29c15201e2b30b72e3f77bdb6008dc2

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.rspec

@@ -0,0 +1,2 @@
+--format documentation
+--color

data/.travis.yml

@@ -0,0 +1,4 @@
+language: ruby
+rvm:
+  - 2.2.2
+before_install: gem install bundler -v 1.10.6

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in noaidi.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015 Paweł Świątkowski
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,147 @@
+# Noaidi
+
+This is a proof-of-concept gem for creating focused modules with pattern matching support. At its root it was inspired by how Erlang does it, but later was refined using concepts from Elixir language.
+
+Noaidi is a Saami name for a shaman. According to Wikipedia:
+
+> A noaidi was a mediator between the human world and _saivo_, the underworld, for the least of community problems.
+
+So, this Noaidi is a mediator between the functional world and Ruby world (which of those is _saivo_, I leave it to you).
+
+There are some blog posts about it:
+* [A quest for pattern-matching in Ruby](http://katafrakt.me/2016/02/13/quest-for-pattern-matching-in-ruby/) (now obsolete, but still tells some things about motivation)
+* [Refactoring Rails with pattern-matching (Noaidi)](http://katafrakt.me/2016/05/24/refactoring-rails-with-noaidi/)
+
+## Usage
+
+A basic unit of this library is a module. Module should define some functions (called `fun`s) and be responsible for some part of the domain. A classic example is a naive recursive Fibonacci implementation. Here's how it looks with `Noaidi`:
+
+```ruby
+require 'noaidi'
+
+naive = Noaidi.module do
+  fun :fib, [0] { 0 }
+  fun :fib, [1] { 1 }
+  fun :fib, [Integer] do |n|
+    fib(n - 1) + fib(n - 2)
+  end
+end
+
+puts naive.fib(5)
+puts naive.fib(15)
+```
+
+As you see, the core concept is a `fun`. You create is using DSL inside a block passed to `Noaidi.module`. First parameter is a fun name, second is array of arguments pattern. It is followed by a block. Of course, you can reference `fun`s from the same module in other funs. If you call for example `fib(1)`, the first fun where arguments pattern matches the actual arguments is called (and in this case will return `1`).
+
+### Pattern matching
+
+You can leverage pattern matching in Noaidi with some choices. That basic match will use `===` operator (like `case`). This way, except for exact values, you can match on:
+
+* Classes – to indicate that the argument has to be an instance of this class or its subclass
+* Values – so that the argument has to be exactly the same
+* Ranges – to have the argument included in the boundaries of a range
+
+There are also some special patterns, that are handled differently:
+
+**Hashes**: You can pass `{ status: :ok }` as a pattern at it will match all hashes that include value `100` under `:status` key. It does not matter what the rest of the keys are. As a values you can also use other pattern, i.e. `{ response: 500..599, headers: { language: 'fi' } }` will match all hashes with response between 500 and 599 and also having a `:headers` key, containing a hash having `'fi'` under `:language` key.
+
+**Lambdas** provide basic guard possibilities. If the lambda evaluates to `true`, it is a match. For example:
+
+```ruby
+Stat = Noaidi.module do
+  # Assuming array is already sorted
+
+  fun :median, [->(array) { array.is_a?(Array) && array.length.even? }] do
+    half = array.length/2
+    (array[half] + array[half - 1]) / 2.0
+  end
+
+  fun :median, [Array] { array[array.length/2] }
+end
+```
+
+You can use `any` keyword if you don't want to specify constraint on the argument:
+
+```ruby
+fun :whatever, [any, Integer] { |a, i| a.to_s * i }
+```
+
+### Argument relevance
+
+```ruby
+Noaidi.match open_file(path) do |m|
+  m.(:ok, File)         {|file| process_file(file) },
+  m.(:error, Exception) {|ex| handle_file_opening_exception(path, ex) }
+end
+```
+
+If you look at the example above, you'll notice that even though the pattern consists of two elements, only one is passed to execution block. This is because of relevance checker. If you match against `:ok, File` you will always have `:ok` as the first argument, and therefore there's no point in passing it to the block.
+
+The rule here is that if you match by value (usually symbols, strings, numbers), the pattern is irrelevant. In every other case, it is relevant and passed to the block.
+
+### Immutability
+
+It's not easy to enforce immutability in language like Ruby and I won't try too hard to do it. However, `fun`s are frozen, which means that you can change it after it has been moduled. It also means that **you can't use instance variables** in `fun`s (that's intentional, as using them could possibly yield unexpected results). Of course, I bet there are some trick with which you can overcome this, but having to use them should discourage you enough.
+
+### Default arguments
+
+Default arguments for `fun`s are not supported and won't be supported. This is by design. If you want to have default arguments, use constructs known in other languages, i.e.
+
+```ruby
+fun :mult, [Integer, Integer] {|x,y| x*y }
+fun :mult, [Integer] {|x| mult(x, 1) }
+```
+
+### Using pattern matching outside modules
+
+Sometimes you don want to write a module to use pattern matching. In those cases, use `Noaidi.match`.
+
+```ruby
+Noaidi.match save_post(@post) do |m|
+    m.(:ok, Post) {|post| redirect_to post, notice: 'Post successfully created' },
+    m.(:invalid, any) {|_validation_errors| render :new },
+    m.(:error, StandardError) {|error| render :error_500, error: error }
+end
+```
+
+If you care for performance, treat this pattern matching as RegEx, where initialization is a most expensive part. With that in mind, you can "compile" the match beforehand and only call subsequent values on compiled version. Use `Noaidi.compile_match` just like with an example above. The returned value will be a compiled matcher.
+
+```ruby
+matcher = Noaidi.compile_match do |m|
+  ...
+end
+
+matcher.(value)
+```
+
+The benchmark comparing those two approaches on my laptop gives following results:
+
+```
+Rehearsal ----------------------------------------------------------------
+100000 times without compile   1.190000   0.000000   1.190000 (  1.191833)
+100000 times with compile      0.380000   0.000000   0.380000 (  0.388147)
+------------------------------------------------------- total: 1.570000sec
+
+                                   user     system      total        real
+100000 times without compile   1.190000   0.000000   1.190000 (  1.184098)
+100000 times with compile      0.390000   0.000000   0.390000 (  0.386056)
+```
+
+## Roadmap
+
+Things I want to implement in the future:
+
+* Private funs in module
+* `_` operator that matches argument as irrelevant and does not pass it to execution block
+
+## Testing
+
+Run `rake spec`.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/katafrakt/noaidi.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,11 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+task :benchmark do
+  require_relative 'benchmark/benchmark'
+  NoaidiBenchmark.run
+end

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "noaidi"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/setup

@@ -0,0 +1,7 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/noaidi.rb

@@ -0,0 +1,15 @@
+require "noaidi/version"
+require "noaidi/dsl"
+require "noaidi/module"
+require "noaidi/fun"
+require "noaidi/matcher"
+require "noaidi/matchmaker"
+require "noaidi/idioms/match"
+
+module Noaidi
+  def self.module(&block)
+    Noaidi::Module.new.tap do |mod|
+      mod.instance_eval(&block)
+    end
+  end
+end

data/lib/noaidi/dsl.rb

@@ -0,0 +1,7 @@
+module Noaidi
+  module DSL
+    def any
+      BasicObject
+    end
+  end
+end

data/lib/noaidi/fun.rb

@@ -0,0 +1,38 @@
+module Noaidi
+  ReturnContractViolation = Class.new(StandardError)
+
+  class Fun
+    def initialize(noaidi, name, args, block)
+      @module = noaidi
+      @name = name
+      @args = args.map{|a| Matcher.new(a)}
+      @block = block
+    end
+
+    def call(*args)
+      freeze unless frozen?
+      instance_exec(*args, &@block)
+    end
+
+    def matches?(args)
+      return false unless arity == args.length
+      args.each_with_index do |arg, i|
+        return false unless @args[i].match?(arg)
+      end
+      true
+    end
+
+    def method_missing(name, *args)
+      @module.public_send(name, *args)
+    end
+
+    private
+    def arity
+      @args.length
+    end
+
+    def arguments
+      @args
+    end
+  end
+end

data/lib/noaidi/idioms/match.rb

@@ -0,0 +1,9 @@
+module Noaidi
+  module Idioms
+    module Match
+      def match(*args, &block)
+        Noaidi.match(*args, &block)
+      end
+    end
+  end
+end

data/lib/noaidi/matcher.rb

@@ -0,0 +1,37 @@
+module Noaidi
+  class Matcher
+    def initialize(pattern)
+      @pattern = pattern
+    end
+
+    def match?(value)
+      case @pattern
+      when Proc
+        match_with_lambda(value)
+      when Hash
+        match_with_hash(value)
+      else
+        @pattern === value
+      end
+    end
+
+    def pattern_class
+      @pattern.class
+    end
+
+    private
+
+    # TODO: compile it at construction time
+    def match_with_hash(value)
+      return false unless value.is_a?(Hash)
+
+      @pattern.map do |key, val|
+        Matcher.new(val).match?(value[key])
+      end.all?{ |x| x == true }
+    end
+
+    def match_with_lambda(value)
+      @pattern.call(value)
+    end
+  end
+end

data/lib/noaidi/matchmaker.rb

@@ -0,0 +1,56 @@
+module Noaidi
+  def self.match(value, &block)
+    compile_match(&block).call(value)
+  end
+
+  def self.compile_match(&block)
+    Matchmaker.new(block)
+  end
+
+  class Matchmaker
+    NoMatchError = Class.new(StandardError)
+
+    def initialize(block)
+      @branches = process_block(block)
+    end
+
+    def call(value)
+      values = Array(value)
+      @branches.each do |matchers, block|
+        return block.call(*meaningful_values(matchers, values)) if matches?(matchers, values)
+      end
+      raise NoMatchError, "No match for #{@values.inspect}"
+    end
+
+    private
+    def process_block(block)
+      block.call(Parser.new)
+    end
+
+    def meaningful_values(matchers, values)
+      values.zip(matchers).select do |i|
+        value = i[0]
+        matcher = i[1]
+        !matcher.nil? && (matcher.pattern_class == Class || value.class != matcher.pattern_class)
+      end.map{|i| i[0]}
+    end
+
+    def matches?(matchers, values)
+      return false unless values.length == matchers.length
+      values.each_with_index do |value, i|
+        return false unless matchers[i].match?(value)
+      end
+      true
+    end
+
+    class Parser
+      def call(*args, &block)
+        @branches ||= {}
+        key = args.map{ |i| Noaidi::Matcher.new(i) }
+        @branches[key] = block
+        @branches
+      end
+    end
+    private_constant :Parser
+  end
+end

data/lib/noaidi/module.rb

@@ -0,0 +1,33 @@
+module Noaidi
+  NoBlockGiven = Class.new(StandardError)
+
+  class Module
+    include Noaidi::DSL
+    
+    def initialize
+      @funs = {}
+    end
+
+    def fun(name, args=[], &block)
+      raise NoBlockGiven unless block_given?
+      name = name.to_sym
+      f = Fun.new(self, name, args, block)
+      @funs[name] ||= []
+      @funs[name] << f
+      f
+    end
+
+    def inspect_funs
+      @funs.inspect
+    end
+
+    def method_missing(name, *args)
+      find_best_method(name, args).call(*args)
+    end
+
+    private
+    def find_best_method(name, args)
+      @funs[name].detect { |f| f.matches?(args) }
+    end
+  end
+end

data/lib/noaidi/version.rb

@@ -0,0 +1,3 @@
+module Noaidi
+  VERSION = "0.1.0"
+end

data/noaidi.gemspec

@@ -0,0 +1,25 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'noaidi/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "noaidi"
+  spec.version       = Noaidi::VERSION
+  spec.authors       = ["Paweł Świątkowski"]
+  spec.email         = ["inquebrantable@gmail.com"]
+
+  spec.summary       = %q{Functional shamanism for Ruby}
+  spec.description   = %q{Functional shamanism for Ruby}
+  spec.homepage      = "https://github.com/katafrakt/noaidi"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features|benchmark)/}) }
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_development_dependency "bundler", "~> 1.10"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+end

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: noaidi
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Paweł Świątkowski
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2016-11-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.10'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Functional shamanism for Ruby
+email:
+- inquebrantable@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".travis.yml"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- lib/noaidi.rb
+- lib/noaidi/dsl.rb
+- lib/noaidi/fun.rb
+- lib/noaidi/idioms/match.rb
+- lib/noaidi/matcher.rb
+- lib/noaidi/matchmaker.rb
+- lib/noaidi/module.rb
+- lib/noaidi/version.rb
+- noaidi.gemspec
+homepage: https://github.com/katafrakt/noaidi
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.1
+signing_key: 
+specification_version: 4
+summary: Functional shamanism for Ruby
+test_files: []