dux 0.3.0 → 0.8.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 8549a025dd5d4bd0d25700d7155a99ac46d222cc
-  data.tar.gz: 187be7a1fcfa97857bf948f846218131889aa17e
+  metadata.gz: ed22ad66960e4fd9f7c8616f2541a0363a2ecf40
+  data.tar.gz: 40d5a91736ca7ca6a0e61e3508c1fa0fdf94b3b7
 SHA512:
-  metadata.gz: a24dddfbe3465f64ac539c33a38c8369cb854761acaf72616b9c070c6d3b85c92c9b0effc7d022c0477ddd02fc733c9386ea886213a5568bf895fb63b062b9b2
-  data.tar.gz: d5ab3bff61e513d04bef1b78acb5afa218ee8dbd96cf35817913301fd9ada0e8b1ec0be57819b7571bdf593c693855571f9213ec68aa347f92d4a49ce330f241
+  metadata.gz: 1cb5fb4869324b0d8d9a2cf225d78e24b6c2de3315bf8917fe07b62d6528d01f1245d9dd6f498fd8e9a5e0a7956bdb2c2ad5ecd00238bea69c51097f78f67a0f
+  data.tar.gz: f5ce999d6fb1ab0f9d440108762167f8b0a2cd6b1461c8ae3e8ba69ea75a0a24de62e7d4f8adb7b42c5251a3ddc4a3a1439f4be6dda8919b04f1b72e5f3dfc59

data/.travis.yml

@@ -3,10 +3,10 @@ dist: trusty
 before_install: gem install bundler -v '~> 1.14'
 cache: bundler
 rvm:
-  - 2.1.0
-  - 2.2.1
-  - 2.3.0
-  - 2.4.0
+  - 2.1
+  - 2.2
+  - 2.3
+  - 2.4
   - ruby-head
   - rbx-3.73
   - jruby-head

data/.yardopts

@@ -1,3 +1,6 @@
+--embed-mixin Dux::Attempt
+--embed-mixin Dux::Blankness
+--embed-mixin Dux::InspectID
 --private
 --protected
 -m markdown

data/README.md

@@ -1,6 +1,6 @@
 # Dux [![Build Status](https://travis-ci.org/scryptmouse/dux.svg?branch=master)](https://travis-ci.org/scryptmouse/dux)
 
-A lazy duck-type matching gem that is particularly designed for use in case statements.
+A swiss-army knife of duck-type and utility objects without monkey-patching.
 
 ## Installation
 
@@ -18,27 +18,204 @@ Or install it yourself as:
 
     $ gem install dux
 
-## Usage
+## Dux[] / Predicates
 
-Usage is straightforward out of the box:
+`Dux[]` can be used for creating predicate matchers for case equality.
+It will check if whatever it is compared against can `respond_to?` the
+symbol it's provided with.
+
+Usage is straightforward:
 
 ```ruby
 case foo
-when Dux[:bar] then foo.bar
-when Dux[:baz] then foo.baz
-when Dux[:quux] then foo.quux
+when Dux[:bar]
+  foo.bar
+when Dux[:baz]
+  foo.baz
+when Dux[:quux]
+  foo.quux
+else
+  raise TypeError, "Dunno what do to do with #{foo.inspect}"
+end
+```
+
+Because it uses lambdas under the hood, it can also be used
+as an enumerable predicate:
+
+```ruby
+list_of_objects_that_should_conform.all?(&Dux[:some_method])
+```
+
+That's not the intended usage, but it works.
+
+### Inheritance / Inclusion / Extension
+
+There are also predicates for testing class structure:
+
+```ruby
+class SomeClass < SomeParentClass
+  extend SomeDSLMethods
+  include SomeHelpers
+  prepend SomeOverrides
 end
+
+Dux.inherits(SomeParentClass) === SomeClass # => true
+Dux.inherits(SomeHelpers) === SomeClass # => true
+Dux.inherits(SomeOverrides) === SomeClass # => true
+
+# If you want to use Module#<= in the predicate, use include_self: true
+Dux.inherits(SomeClass, include_self: true) === SomeClass # => true
+
+# Testing for module extension is different.
+Dux.extends(SomeDSLMethods) === SomeClass # => true
 ```
 
-It also has some methods for matching against a strict interface:
+`Dux.inherits` is aliased to `Dux.prepends` and `Dux.includes`
+for semantic clarity, but it does not currently check
+if a module was included or prepended.
+
+### Interfaces
+
+There are also some methods for matching against a strict / flexible interface:
 
 ```ruby
 case foo
-when Dux.all(:bar, :baz) then foo.bar && foo.baz
-when Dux.any(:quux, :bloop) then foo.try(:quux) || foo.try(:bloop)
+when Dux.all(:bar, :baz)
+  foo.bar && foo.baz
+when Dux.any(:quux, :bloop)
+  Dux.attempt(foo, :quux) || Dux.attempt(foo, :bloop)
+end
+```
+
+### YARD Types
+
+If you have a condition more easily expressed in [YARD types](http://yardoc.org/types),
+you can do something like the following:
+
+```ruby
+case some_overloaded_arg
+when Dux.yard('(Symbol, Symbol)')
+  # Do something with a tuple of two symbols
+when Dux.yard('{ Symbol => <Symbol> }')
+  # Do something with a symbol-keyed hash with
+  # values that are an array of symbols
+when Dux.yard('<SomeClass>')
+  # Do something with an array of `SomeClass` members
+end
+```
+
+Performance of the underlying gem is not thoroughly tested,
+but it should work just fine for non-intensive use cases.
+
+## Dux.comparable
+
+Simplifies creating comparable objects when just want
+to compare on a couple of attributes defined on objects.
+
+```ruby
+class Person < Struct.new(:name)
+  include Dux.comparable :name
+end
+
+alice = Person.new 'Alice'
+bob   = Person.new 'Bob'
+carol = Person.new 'Carol'
+
+[bob, carol, alice].sort == [alice, bob, carol]
+
+# You can also sort descending:
+
+Person.include Dux.comparable :name, sort_order: :desc
+
+[alice, carol, bob].sort == [carol, bob, alice]
+```
+
+You can additionally specify multiple attributes with
+individual sort ordering for each attribute:
+
+```ruby
+class Person < Struct.new(:name, :salary)
+  include Dux.comparable [:salary, :desc], :name
+end
+
+alice = Person.new 'Alice', 100_000
+bob   = Person.new 'Bob', 75_000
+carol = Person.new 'Carol', 100_000
+
+[carol, bob, alice].sort == [alice, carol, bob]
+```
+
+## Dux.enum
+
+Create an indifferent set of strings/symbols that can be used
+to validate options.
+
+```ruby
+ROLES = Dux.enum :author, :admin, :reader
+
+ROLES[:author] # => :author
+ROLES[:nonexistent] # raises Dux::Enum::NotFound
+
+ROLES.fetch :nonexistent do |value|
+  raise YourErrorHere, "Invalid role: #{value}"
 end
 ```
 
+If you want a specific fallback value instead of raising an error, you can do that too
+
+```ruby
+ROLES = Dux.enum :author, :admin, :reader, default: :reader
+
+ROLES[:nonexistent] # => :reader
+
+# Override the fallback for a particular fetch
+ROLES[:nonexistent, fallback: :author] # => :author
+```
+
+## Utilities
+
+Small utility methods, many to replace needing ActiveSupport / monkey patching.
+
+### Dux.attempt
+
+`Object#try` when you don't have/want ActiveSupport.
+
+It will attempt to execute a provided method (with optional args and block)
+with `public_send`, or simply return `nil` if it doesn't respond.
+
+```ruby
+Dux.attempt(some_object, :method, *args, &block)
+```
+
+### Dux.blankish? / Dux.presentish?
+
+`Object#blank?` & `Object#present?` when you don't have/want ActiveSupport.
+
+Rather than being monkey patched across all `Object`s, you will need to
+use `Dux` to check:
+
+```ruby
+Dux.blankish? [nil] # => true
+Dux.blankish? Hash.new # => true
+Dux.blankish? "\t" # => true
+Dux.blankish? Float::NAN
+```
+
+### Dux.inspect_id
+
+If you are overriding the `#inspect` method on an object and want
+to keep that unique hex `object_id`, this offers a shorthand:
+
+```ruby
+def inspect
+  "#<YourClassHere:#{Dux.inspect_id(self)}>"
+end
+```
+
+## Monkey patches / Experimental
+
+These will probably end up getting removed for version 1.x.
+
 ### Core Extensions
 
 There are a few core extensions available that can be manually enabled.
@@ -75,7 +252,7 @@ when %i[quux bloop].duckify(type: :any) then foo.try(:quux) || foo.try(:bloop)
 end
 ```
 
-#### Shorthand
+#### ~ Shorthand
 
 There is an experimental option that uses unary `~` as an alias for `#duckify`.
 
@@ -116,7 +293,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Supported Ruby Versions
 
-* MRI 2.1+
+* MRI 2.2+
 * Rubinius 2.5+
 * jruby-head / 9.0+
 

data/dux.gemspec

@@ -9,7 +9,7 @@ Gem::Specification.new do |spec|
   spec.authors       = ["Alexa Grey"]
   spec.email         = ["devel@mouse.vc"]
 
-  spec.summary       = %q{Lazy duck-type matching}
+  spec.summary       = %q{Swiss-army knife gem for duck-type matching and utility methods}
   spec.homepage      = "https://github.com/scryptmouse/dux"
   spec.license       = "MIT"
 
@@ -20,7 +20,7 @@ Gem::Specification.new do |spec|
 
   spec.metadata["yard.run"] = "yri"
 
-  spec.add_dependency "lru_redux"
+  spec.add_dependency "yard_types"
 
   spec.add_development_dependency "bundler",    "~> 1.9"
   spec.add_development_dependency "rspec",      "~> 3.5"

data/lib/dux.rb

@@ -1,183 +1,27 @@
 require 'delegate'
+require 'strscan'
+require 'yard_types'
 
 require 'dux/version'
+
 require 'dux/inspect_id'
 require 'dux/null_object'
 require 'dux/attempt'
 require 'dux/blankness'
-require 'dux/duckify'
-require 'dux/hacks_like_a_duck'
-require 'dux/flock_methods'
-
 require 'dux/indifferent_string'
-require 'dux/enum'
-
-# Super simple duck-type testing.
-module Dux
-  # Methods for generating "interface" checks against an array of symbols
-  FLOCK_TYPES = %i[all any none]
-
-  module_function
-
-  # @param [Symbol] symbol
-  # @param [Boolean] include_all
-  # @return [Proc]
-  def dux(symbol, include_all: false)
-    ->(obj) { obj.respond_to? symbol, include_all }
-  end
-
-  class << self
-    alias_method :[], :dux
-
-    # @param [:all, :any, :none] type
-    # @param [<Symbol, String>] methods
-    # @param [Boolean] include_all
-    # @raise [ArgumentError] on invalid type
-    # @return [<Proc>]
-    def flock(type, *methods, include_all: false)
-      raise ArgumentError, "Invalid flock type: #{type}" unless FLOCK_TYPES.include? type
-
-      __send__ type, methods, include_all: include_all
-    end
-
-    # Creates a lambda that describes a restrictive interface,
-    # wherein the provided object must `respond_to?` *all* of
-    # the methods.
-    #
-    # @param [<Symbol, String>] methods
-    # @param [Boolean] include_all
-    # @return [Proc]
-    def all(*methods, include_all: false)
-      ducks = flockify methods, include_all: include_all
-
-      ->(obj) { ducks.all? { |duck| duck.call obj } }
-    end
-
-    # Creates a lambda that describes a permissive interface,
-    # wherein the provided object must `respond_to?` at least
-    # one of the methods.
-    #
-    # @param [<Symbol>] methods
-    # @param [Boolean] include_all
-    # @return [Proc]
-    def any(*methods, include_all: false)
-      ducks = flockify methods, include_all: include_all
-
-      ->(obj) { ducks.any? { |duck| duck.call obj } }
-    end
-
-    # Creates a lambda that describes a restrictive interface,
-    # wherein the provided object must `respond_to?` *none* of
-    # the methods.
-    #
-    # @param [<Symbol>] methods
-    # @param [Boolean] include_all
-    # @return [Proc]
-    def none(*methods, include_all: false)
-      ducks = flockify methods, include_all: include_all
-
-      ->(obj) { ducks.none? { |duck| duck.call obj } }
-    end
-
-    # @!group Core extensions
-
-    # Enhance `Array` with {Dux::FlockMethods#duckify}
-    #
-    # @return [void]
-    def add_flock_methods!
-      Array.__send__ :prepend, Dux::FlockMethods
 
-      return nil
-    end
-
-    # Load all `Dux` core extensions.
-    #
-    # @param [Boolean] experimental whether to load experimental shorthand methods
-    # @return [void]
-    def extend_all!(experimental: false)
-      add_flock_methods!
-      extend_strings_and_symbols!
-
-      return unless experimental
-
-      array_shorthand!
-      string_shorthand!
-      symbol_shorthand!
-    end
-
-    # Enhance `String` with {Dux::Duckify}
-    #
-    # @return [void]
-    def extend_strings!
-      String.__send__ :prepend, Dux::Duckify
-
-      return nil
-    end
-
-    # Enhance `Symbol` with {Dux::Duckify}
-    #
-    # @return [void]
-    def extend_symbols!
-      Symbol.__send__ :prepend, Dux::Duckify
-
-      return nil
-    end
-
-    # Enhance `String` and `Symbol` classes with {Dux::Duckify#duckify}
-    #
-    # @return [void]
-    def extend_strings_and_symbols!
-      extend_strings!
-      extend_symbols!
-
-      return nil
-    end
-
-    # Experimental feature to add unary `~` to `Array`s
-    # for quick usage in case statements.
-    #
-    # @return [void]
-    def array_shorthand!
-      add_flock_methods!
-
-      Array.__send__ :prepend, Dux::HacksLikeADuck
-
-      nil
-    end
-
-    # Experimental feature to add unary `~` to `String`s
-    # for quick usage in case statements.
-    #
-    # @return [void]
-    def string_shorthand!
-      extend_strings!
-      String.__send__ :prepend, Dux::HacksLikeADuck
-
-      nil
-    end
-
-    # Experimental feature to add unary `~` to `Symbol`s
-    # for quick usage in case statements.
-    #
-    # @return [void]
-    def symbol_shorthand!
-      extend_symbols!
+require 'dux/enum'
 
-      Symbol.__send__ :prepend, Dux::HacksLikeADuck
+require 'dux/predicate'
 
-      return nil
-    end
+require 'dux/comparable'
 
-    # @!endgroup
+# Experimental nonsense
+require 'dux/monkey_patch'
+require 'dux/duckify'
+require 'dux/hacks_like_a_duck'
+require 'dux/flock_methods'
 
-    protected
-    # @param [<Symbol>] methods
-    # @param [Boolean] include_all
-    # @return [<Proc>]
-    def flockify(methods, include_all: false)
-      methods.flatten.map do |sym|
-        dux sym, include_all: include_all
-      end
-    end
-  end
+# Swiss-army duck type matching
+module Dux
 end