dux 0.3.0 → 0.8.0

data/lib/dux/indifferent_string.rb

@@ -1,9 +1,11 @@
 module Dux
+  # A string value that is programmatically equivalent to its symbol representation.
   class IndifferentString < DelegateClass(String)
+    # @param [String, Symbol, Dux::IndifferentString, #to_str, #acts_like_string?] stringish
     def initialize(stringish)
       stringified =
         case stringish
-        when String then stringish
+        when String, Dux::IndifferentString then stringish
         when Symbol then stringish.to_s
         when Dux[:to_str] then stringish.to_str
         else
@@ -17,6 +19,9 @@ module Dux
       super(stringified)
     end
 
+    # Test basic equality.
+    #
+    # @param [String, Symbol] other
     def ==(other)
       if other.kind_of?(Symbol)
         self == other.to_s
@@ -27,6 +32,9 @@ module Dux
 
     alias_method :eql?, :==
 
+    # Test case equality
+    #
+    # @param [String, Symbol, Regexp] other
     def ===(other)
       if other.kind_of?(Symbol)
         self == other.to_s

data/lib/dux/inspect_id.rb

@@ -1,11 +1,16 @@
 module Dux
+  # Calculate the object's inspection id
   module InspectID
     # Calculates the id shown in the default
     # version of `#inspect` methods.
     #
+    # @note This is currently limited to the implementation
+    #   used in MRI. Rubinius and JRuby have their own
+    #   implementations that are not currently served
+    #   by this.
     # @param [Object] object
     # @return [String]
-    def inspect_id(object)
+    def inspect_id(object = self)
       "0x%0.14x" % ( object.object_id << 1 )
     end
 

data/lib/dux/monkey_patch.rb

@@ -0,0 +1,97 @@
+module Dux
+  class << self
+    # @!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!
+
+      Symbol.__send__ :prepend, Dux::HacksLikeADuck
+
+      return nil
+    end
+
+    # @!endgroup
+
+  end
+end

data/lib/dux/null_object.rb

@@ -1,30 +1,77 @@
 module Dux
+  # Null objects that can be used for smarter
+  # argument building.
+  #
+  # @example Usage
+  #   module Foo
+  #     class Bar
+  #       NULL = Dux.null 'Foo::Bar::NULL'
+  #
+  #       # Making it private is not required,
+  #       # but recommended if it is something
+  #       # that should only be available
+  #       # internally.
+  #       private_constant :NULL
+  #
+  #       def initialize(some_option: NULL)
+  #         if some_option == NULL
+  #           # Do some default logic
+  #         else
+  #           @some_option = some_option
+  #         end
+  #       end
+  #     end
+  #   end
   class NullObject
     include Dux::InspectID
 
+    # @!attribute [r] name
+    # The name of this null object,
+    # for self-documenting / introspection.
+    #
+    # In practice, this should be the object path,
+    # e.g. `Foo::Bar::NULL`
+    # @return [String]
     attr_reader :name
+
+    # @!attribute [r] purpose
+    # A purpose or description of this object,
+    # for self-documenting / introspection.
+    # @return [String]
     attr_reader :purpose
 
     # @param [String] name
     # @param [String] purpose
-    def initialize(name, purpose: 'a null object')
-      @name     = name
+    def initialize(name = nil, purpose: 'a null object')
+      @name     = name || default_name
       @purpose  = purpose
+
+      freeze
     end
 
     private
+
+    # Generates a default name for this object.
+    #
+    # @return [String]
     def default_name
-      
+      "Dux::NullObject(#{inspect_id(self)})"
     end
   end
 
   class << self
-    # @param (@see Dux::NullObject#initialize)
+    # @!group DSL
+
+    # Create {Dux::NullObject a null object} with the provided options.
+    #
+    # @see Dux::NullObject#initialize
     # @return [Dux::NullObject]
-    def null_object(name, **options)
+    def null_object(name = nil, **options)
       Dux::NullObject.new(name, **options)
     end
 
     alias_method :null, :null_object
+
+    # @!endgroup DSL
   end
 end

data/lib/dux/predicate.rb

@@ -0,0 +1,139 @@
+module Dux
+  # Methods for generating "interface" checks against an array of symbols
+  FLOCK_TYPES = Dux.enum :all, :any, :none
+
+  class << self
+    # @!group Predicates
+
+    # Create a predicate that checks if the provided object
+    # responds to the `symbol`.
+    #
+    # @param [Symbol] symbol
+    # @param [Boolean] include_all
+    # @return [Proc]
+    def [](symbol, include_all: false)
+      ->(obj) { obj.respond_to? symbol, include_all }
+    end
+
+    alias_method :predicate, :[]
+    alias_method :dux, :[]
+
+    # Create a predicate that checks if the provided `Class` or `Module`
+    # inherits from a given class or module.
+    #
+    # @param [Class, Module] parent
+    # @param [Boolean] include_self
+    # @raise [TypeError] requires a class or module to serve as parent
+    # @return [Proc]
+    def inherits(parent, include_self: false)
+      raise TypeError, "Must be a class or module to check inheritance" unless inheritable?(parent)
+
+      if include_self
+        ->(klass) { Dux.inheritable?(klass) && klass <= parent }
+      else
+        ->(klass) { Dux.inheritable?(klass) && klass < parent }
+      end
+    end
+
+    alias_method :includes, :inherits
+    alias_method :prepends, :inherits
+
+    # Create a predicate that checks if the provided `Class` or `Module`
+    # extends a given `parent` module.
+    #
+    # @param [Module] parent
+    # @raise [TypeError] requires a module to check extension
+    # @return [Proc]
+    def extends(parent)
+      raise TypeError, "Must be a module to check if something extends it" unless parent.kind_of?(Module)
+
+      ->(klass) { Dux.inheritable?(klass) && klass.singleton_class < parent }
+    end
+
+    # Create a predicate that checks against a specific YARD type description.
+    #
+    # @note Some limitations apply because of the underlying gem, e.g.
+    #   symbol / string literals are not matched and will raise an error
+    # @see https://github.com/pd/yard_types the gem used for parsing types
+    # @raise [SyntaxError] when `YardTypes` fails to parse.
+    # @param [String] pattern
+    # @return [Proc]
+    def yard(pattern)
+      type = YardTypes.parse pattern
+
+      ->(value) { !type.check(value).nil? }
+    end
+
+    # Check if the provided thing is a class or a module.
+    #
+    # @param [Class, Module] klass_or_module
+    # @api private
+    def inheritable?(klass_or_module)
+      klass_or_module.kind_of?(Class) || klass_or_module.kind_of?(Module)
+    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
+
+    # @param [:all, :any, :none] type
+    # @param [<Symbol, String>] methods
+    # @param [Boolean] include_all
+    # @raise [ArgumentError] on invalid type
+    # @api private
+    # @return [<Proc>]
+    def flock(type, *methods, include_all: false)
+      type = FLOCK_TYPES.fetch(type) { raise ArgumentError, "Invalid flock type: #{type}" }
+
+      __send__ type, methods, include_all: include_all
+    end
+
+    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
+
+    # @!endgroup
+  end
+end

data/lib/dux/version.rb

@@ -1,4 +1,4 @@
 module Dux
   # Gem version.
-  VERSION = "0.3.0"
+  VERSION = "0.8.0"
 end

metadata

@@ -1,17 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: dux
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.8.0
 platform: ruby
 authors:
 - Alexa Grey
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2017-04-06 00:00:00.000000000 Z
+date: 2017-04-09 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: lru_redux
+  name: yard_types
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -132,14 +132,16 @@ files:
 - lib/dux.rb
 - lib/dux/attempt.rb
 - lib/dux/blankness.rb
-- lib/dux/duck_type.rb
+- lib/dux/comparable.rb
 - lib/dux/duckify.rb
 - lib/dux/enum.rb
 - lib/dux/flock_methods.rb
 - lib/dux/hacks_like_a_duck.rb
 - lib/dux/indifferent_string.rb
 - lib/dux/inspect_id.rb
+- lib/dux/monkey_patch.rb
 - lib/dux/null_object.rb
+- lib/dux/predicate.rb
 - lib/dux/version.rb
 homepage: https://github.com/scryptmouse/dux
 licenses:
@@ -165,5 +167,5 @@ rubyforge_project:
 rubygems_version: 2.6.8
 signing_key: 
 specification_version: 4
-summary: Lazy duck-type matching
+summary: Swiss-army knife gem for duck-type matching and utility methods
 test_files: []