constrain 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b37ca58d51de33d6c5d6810c5b8e4b77e0d1d19355d4e381241b923f44918817
+  data.tar.gz: c64f19d94bb2e4dae6e4fbaf61a74d1fb6caee56f58a9006915a5749ee35b906
+SHA512:
+  metadata.gz: bd6114ec7c7b5516c409ef41beae62d979c582f8f53c149634a1fc8ed8b4c595a7b3fd2d12d07a08fd2b7b587515adef890e6f68cdf6dd897d6ef79e8bad9c50
+  data.tar.gz: 9eec4bc8dac6976bbe2eb22e45bcf57589b5f1e04092596e1cb99f658c0b9144a68182eab73e0e5ae3eb9be9bb9434184f8c71122aaddba284d15f90cac4600e

data/.gitignore

@@ -0,0 +1,19 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+# Ignore auto-generated main file
+/main
+
+# Ignore Gemfile.lock. See https://stackoverflow.com/questions/4151495/should-gemfile-lock-be-included-in-gitignore
+/Gemfile.lock
+
+# Put your personal ignore files in /home/clr/.config/git/ignore

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+ruby-2.7.1

data/.travis.yml

@@ -0,0 +1,6 @@
+---
+language: ruby
+cache: bundler
+rvm:
+  - 2.7.1
+before_install: gem install bundler -v 2.1.4

data/Gemfile

@@ -0,0 +1,7 @@
+source "https://rubygems.org"
+
+# Specify your gem's dependencies in constrain.gemspec
+gemspec
+
+gem "rake", "~> 12.0"
+gem "rspec", "~> 3.0"

data/README.md

@@ -0,0 +1,103 @@
+# Constrain
+
+`Constrain` allows you to check if an object match a class expression. It is
+typically used to check the type of method parameters and is an alternative to
+using Ruby-3 .rbs files but with a different syntax and only dynamic checks
+
+Constrain works with ruby-2 (and maybe ruby-3)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'constrain'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install constrain
+
+## Usage
+
+You'll typically include the Constrain module and use the #constrain method to chech values:
+
+    include Constrain
+
+    # f takes a String and an array of Integer objects
+    def f(a, b)
+      constrain a, String
+      constrain b, [Integer]
+    end
+
+The constrain instance method raises a Constrain::TypeError if the value
+doesn't match the class expression. Constrain also defines the Constrain::check
+class method that returns true/false depending on if the value match the
+expression. Both methods raise a Constrain::Error if the expression is invalid
+
+### Class Expressions
+
+Constrain#constrain and Constrain::check use class expressions composed of
+Class objects, Proc objects, or arrays and hashes of class objects. Class
+objects match if the value is an instance of the class:
+
+    constrain 42, Integer   # Success
+    constrain 42, String    # Failure
+
+Note that NilClass and TrueClass and FalseClass are valid arguments and allows
+you to do value comparison for those types:
+
+    constrain nil, Integer             # Failure
+    constrain nil, Integer, NilClass   # Success
+
+Proc objects are called with the value as argument and should return truish or falsy:
+
+    proc = lambda { |value| value > 1 }
+    constrain 42, proc   # Success
+    constrain 0, proc    # Failure
+
+Proc objects can check every aspect of an object and but you should not overuse
+them as `Constrain` is throught of as a poor-man's type checker. More elaborate
+constraints should be checked explicitly
+
+Arrays match if the value is an Array and all its element match the given class expression:
+
+    constrain [42], [Integer]   # Success
+    constrain [42], [String]    # Failure
+
+Arrays can be nested
+
+    constrain [[42]], [[Integer]]
+
+Note that arrays are treated specially in hashes
+
+Hashes match if value is a hash and every key/value pair match one of the given
+key-class/value-class expressions:
+
+    constrain({"str" => 42}, String => Integer)   # Success
+    constrain({"str" => 42}, String => String)    # Failure
+
+Note that the parenthesis are needed because otherwise the Ruby parser would
+interpret the hash as block argument to #constrain
+
+Hash keys or values can also be lists of class expressions that match if any
+expression match. List are annotated as an array but contains more than one
+element so that `[String, Symbol]` matches either a String or a Symbol value
+while `[String]` matches an array of String objects:
+
+    constrain({ sym: 42 }, [Symbol, String] => Integer)       # Success
+    constrain({ [sym] => 42 }, [Symbol, String] => Integer)   # Failure
+
+To specify an array of Symbol or String objects in hash keys or values, make
+sure the list expression is enclosed in an array:
+
+    constrain({ [sym] => 42 }, [[Symbol, String]] => Integer)   # Success
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/clrgit/constrain.
+

data/Rakefile

@@ -0,0 +1,6 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "constrain"
+
+# 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(__FILE__)

data/bin/setup

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

data/constrain.gemspec

@@ -0,0 +1,47 @@
+require_relative 'lib/constrain/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "constrain"
+  spec.version       = Constrain::VERSION
+  spec.authors       = ["Claus Rasmussen"]
+  spec.email         = ["claus.l.rasmussen@gmail.com"]
+
+  spec.summary       = %q{Dynamic in-file type checking}
+  spec.description   = %q{
+    Allows you check if an object match a class expression. It is typically
+    used to check the type of method paraameters. It is an alternative to using
+    Ruby-3 .rbs files but with a different syntax and only dynamic checks
+    
+    Typically you'll include the Constrain module and use #constrain to check
+    the type of method parameters:
+
+      include Constrain
+
+      # f takes a String and an array of Integer objects. Raise a Constrain::Error
+      # if parameters doesn't have the expected types
+      def f(a, b)
+        constrain a, String
+        constrain b, [Integer]
+      end
+
+    Constrain works with ruby-2 (and maybe ruby-3)
+  }
+  spec.homepage      = "http://www.nowhere.com/"
+  spec.required_ruby_version = Gem::Requirement.new(">= 2.3.0")
+
+  spec.metadata["homepage_uri"] = spec.homepage
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  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_dependency GEM [, VERSION]
+
+  # spec.add_development_dependency GEM [, VERSION]
+  spec.add_development_dependency "simplecov"
+end

data/lib/constrain.rb

@@ -0,0 +1,73 @@
+require "constrain/version"
+
+module Constrain
+  # Raised on any error
+  class Error < StandardError; end
+
+  # Raised if types doesn't match a class expression
+  class TypeError < Error
+    def initialize(value, exprs)
+      super "Expected #{value.inspect} to match #{Constrain.fmt_exprs(exprs)}"
+    end
+  end
+
+  # Check that value matches one of the class expressions. Raises a
+  # Constrain::Error if the expression is invalid and a Constrain::TypeError if
+  # the value doesn't match
+  def constrain(value, *exprs)
+    return if exprs.any? { |expr| Constrain.check(value, expr) }
+    error = TypeError.new(value, exprs)
+    error.set_backtrace(caller[1..-1])
+    raise error
+  end
+
+  # Return true if the value matches the class expression. Raises a
+  # Constrain::Error if the expression is invalid
+  def self.check(value, expr)
+    case expr
+      when Class
+        value.is_a?(expr)
+      when Array
+        !expr.empty? or raise Error, "Empty array"
+        value.is_a?(Array) && value.all? { |elem| expr.any? { |e| check(elem, e) } }
+      when Hash
+        value.is_a?(Hash) && value.all? { |key, value|
+          expr.any? { |key_expr, value_expr|
+            [[key, key_expr], [value, value_expr]].all? { |value, expr|
+              if expr.is_a?(Array) && (expr.size > 1 || expr.first.is_a?(Array))
+                expr.any? { |e| check(value, e) }
+              else
+                check(value, expr)
+              end
+            }
+          }
+        }
+      when Proc
+        expr.call(value)
+    else
+      raise Error, "Illegal expression #{expr.inspect}"
+    end
+  end
+
+  # Render a class expression as a String. Same as
+  # <tt>exprs.map(&:inspect).join(", ")</tt> except that Proc objects are rendered as
+  # "Proc@<sourcefile>:<linenumber>"
+  def self.fmt_exprs(exprs)
+    exprs.map { |expr| fmt_expr(expr) }.join(", ")
+  end
+
+  # Render a class expression as a String. Same as +expr.inspect+ except that
+  # Proc objects are rendered as "Proc@<sourcefile>>:<linenumber>"
+  #
+  def self.fmt_expr(expr)
+    case expr
+      when Class; expr.to_s
+      when Array; "[" + expr.map { |expr| fmt_expr(expr) }.join(", ") + "]"
+      when Hash; "{" + expr.map { |k,v| "#{fmt_expr(k)} => #{fmt_expr(v)}" }.join(", ") + "}"
+      when Proc; "Proc@#{expr.source_location.first}:#{expr.source_location.last}"
+    else
+      raise Error, "Illegal expression"
+    end
+  end
+end
+

data/lib/constrain/version.rb

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

metadata

@@ -0,0 +1,77 @@
+--- !ruby/object:Gem::Specification
+name: constrain
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Claus Rasmussen
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2021-05-15 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: simplecov
+  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: "\n    Allows you check if an object match a class expression. It is
+  typically\n    used to check the type of method paraameters. It is an alternative
+  to using\n    Ruby-3 .rbs files but with a different syntax and only dynamic checks\n
+  \   \n    Typically you'll include the Constrain module and use #constrain to check\n
+  \   the type of method parameters:\n\n      include Constrain\n\n      # f takes
+  a String and an array of Integer objects. Raise a Constrain::Error\n      # if parameters
+  doesn't have the expected types\n      def f(a, b)\n        constrain a, String\n
+  \       constrain b, [Integer]\n      end\n\n    Constrain works with ruby-2 (and
+  maybe ruby-3)\n  "
+email:
+- claus.l.rasmussen@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- ".ruby-version"
+- ".travis.yml"
+- Gemfile
+- README.md
+- Rakefile
+- bin/console
+- bin/setup
+- constrain.gemspec
+- lib/constrain.rb
+- lib/constrain/version.rb
+homepage: http://www.nowhere.com/
+licenses: []
+metadata:
+  homepage_uri: http://www.nowhere.com/
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 2.3.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.1.4
+signing_key: 
+specification_version: 4
+summary: Dynamic in-file type checking
+test_files: []