blankity 0.1.0 → 0.9.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 34a522794c85b7f50a815a2a17e455685e5fff40512134a8652d52705fd96946
-  data.tar.gz: 44fe6ca43f7a274e076b00c83fee4da89617102769007615a56f9e8ba8345876
+  metadata.gz: 82b868a367489a12b73f469c8bda91b12bd4342ea50eca5014594dc852b9e77a
+  data.tar.gz: 9bc3240a45986f4781d0c69bb40614555e5be376e25ef47813f5063bea024bde
 SHA512:
-  metadata.gz: 2679a4fc2901543f1df080226bcd8d41cde7fff84ffadf084a5a3b54509bc150e5e70ed9cc138624d3a9d9d0ba09f792b11ae7253894b9d35adab64a736c4eb3
-  data.tar.gz: 9102b667417681d9e6c52a83d3e2742513d0ff9a95efaa5925f913c9017c0a841c14ea1d414b36846797d885568547f99feffb729de7e13d012bab88508301df
+  metadata.gz: b322727491e488bd3c72a52b2018d5898f0e2a53049f745738bb4c22ed71647184b5b235492a17fbc103c2e5e69c72b6d1aa8035c0f0ae4dc921f36b22bfc0e7
+  data.tar.gz: 424882212731398452338d31e67a68d8b3832ffb8ae0bb3b924ee14290182227fe1aa1722c1d9c0844fd15f23a8328e10b67dd2907f50d0b04dab9428abb3e8b

data/.yardopts

@@ -0,0 +1 @@
+--type-tag rbs --hide-tag rbs

data/README.md

@@ -1,38 +1,86 @@
 # Blankity
 
-TODO: Delete this and the text below, and describe your gem
-
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/blankity`. To experiment with that code, run `bin/console` for an interactive prompt.
+Blankity is a gem that provides "blank objects," which define minimal methods.
 
 ## Installation
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
-
 Install the gem and add to the application's Gemfile by executing:
-
 ```bash
-bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+bundle add blankity
 ```
 
 If bundler is not being used to manage dependencies, install the gem by executing:
-
 ```bash
-gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+gem install blankity
 ```
 
 ## Usage
 
-TODO: Write usage instructions here
+The `Blankity::Blank` class `undef`s all methods (other than `__send__` and `__id__`) from `BasicObject`:
+```ruby
+# No methods are defined
+blank = Blankity::Blank.new
+p defined?(blank.==)      #=> nil
+p defined?(blank.inspect) #=> nil
+
+# Include specific `Object` methods:
+blank = Blankity::Blank.new(methods: [:==])
+p blank == blank #=> true
+
+# Also supports blocks, which are `instance_exec`ed
+p Blankity::Blank.new { def inspect = "hi" } #=> "hi"
+```
+
+Also supplied are `Blankity::ToXXX` classes, which just define the conversion methods that are used throughout Ruby's stdlib:
+```ruby
+# String#* calls `.to_int` on its argument:
+p 'a' * Blankity::ToInt.new(3) #=> "aaa"
+
+# File.exist? calls `.to_path` on its argument:
+p File.exist? Blankity::ToPath.new('/tmp/foo') #=> false
+
+# Array#[] accepts custom ranges:
+p %w[a b c d][Blankity::Range.new(1, 3)] #=> ["b", "c", "d"]
+
+```
+
+As a convenience, `Blankity::To` defines these conversion methods:
+```ruby
+puts 'hello' + Blankity::To.str(' world')
+#=> hello world
+
+puts 'hello'.gsub(/[eo]/, Blankity::To.hash('e' => 'E', 'o' => 'O'))
+#=> hEllO
+```
+
+The `Blankity::To` module is also a mixin!
+```ruby
+extend Blankity::To
+
+puts 'hello' + str(' world')
+exit int(0)
+
+# Let's get crazy!
+system(
+  hash(
+    str('HELLO', hash: true) => str('WORLD')
+  ),
+  ary(str('sh'), str('-sh')),
+  str('-c'),
+  str('echo $0 $HELLO $PWD'),
+  chdir: path('/'),
+)
+```
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+Run tests via `rake test` and `steep check`.
 
-To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+Before pushing new versions, make sure to run `bundle exec rbs-inline --output lib` to generate new rbs signatures, and to update the `version.rb` file.
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/blankity.
+Bug reports and pull requests are welcome on GitHub at https://github.com/sampersand/blankity.
 
 ## License
 

data/Steepfile

@@ -18,12 +18,11 @@ target :lib do
   # end
 end
 
-# target :test do
+target :test do
 #   unreferenced!                     # Skip type checking the `lib` code when types in `test` target is changed
 #   signature "sig/test"              # Put RBS files for tests under `sig/test`
-#   check "test"                      # Type check Ruby scripts under `test`
-
-#   configure_code_diagnostics(D::Ruby.lenient)      # Weak type checking for test code
+  check "test"                      # Type check Ruby scripts under `test`
+  configure_code_diagnostics(D::Ruby.lenient)      # Weak type checking for test code
+  gem 'rake'
+end
 
-#   # library "pathname"              # Standard libraries
-# end

data/lib/blankity/blank.rb

@@ -2,54 +2,86 @@
 # rbs_inline: enabled
 
 module Blankity
-  # A "blank slate" class which removes _all_ methods (from `BasicObject`) other than the "required"
-  # ones of `__send__` and `__id__`.
+  # An "emptier" class than {BasicObject}, which +undef+ines nearly all instance methods.
   #
-  # Notably, it does not remove private instance methods, as Ruby actually requires some of them to
-  # function properly (e.g. {BasicObject#singleton_method_added}.)
+  # Not _all_ methods are undefined (see {Top} for a class which does):
+  #
+  # - Methods which match +/\\A__.*__\\z/+ are not removed. Traditionally, these methods are expected
+  #   to always be present (and +undef+ing them warns you!). Ruby has two of these: +__send__+
+  #   and +__id__+
+  # - Private methods are not undefined, as each one of them is expected to be present (most of them
+  #   are hooks, eg +singleton_method_added+), and aren't easily accessible from external classes.
+  #
+  # To make using +Blank+ easier, its constructor allows you to pass a +methods:+ keyword argument,
+  # which will define singleton methods based on {Object}.
   class Blank < BasicObject
-    # Remove every method except for `__send__` and `__id__`
+    # Remove every public and protected method that we inherit, except for `__xyz__` methods
     instance_methods.each do |name|
-      undef_method(name) unless name == :__send__ || name == :__id__
+      undef_method(name) unless name.match?(/\A__.*__\z/)
     end
 
-    # Helper method to create a new instance
-    #
-    # @rbs: () ?{ (Blank) -> void } -> singleton(Blank)
-    def self.blank(&block)
-      ::Class.new(self, &block).new
-    end
+    # Declare these as constants so we don't constantly look them up.
+    DEFINE_SINGLETON_METHOD = ::Object.instance_method(:define_singleton_method) #: UnboundMethod
+    INSTANCE_EXEC = ::Object.instance_method(:instance_exec) #: UnboundMethod
+    private_constant :DEFINE_SINGLETON_METHOD, :INSTANCE_EXEC
 
-    # A helper method to define some `Kernel`methods on `self`
-    def __with_Object_methods__(*methods)
-      dsm = ::Object.instance_method(:define_singleton_method).bind(self)
+    # Creates a new {BlankValue}, and defining singleton methods depending on the parameters
+    #
+    # @param methods [Array[interned]] a list of {Object} methods to define on +self+.
+    # @param hash [bool] convenience argument, adds +hash+ and +eql?+ to +methods+ so the resulting
+    #                    type can be used as a key in +Hash+es
+    # @yield [] if a block is given, runs it via +instance_exec+.
+    #
+    # === Example
+    #   # Make a empty instance
+    #   Blankity::Blank.new
+    #
+    #   # Include `Object#inspect`, so we can print with `p`
+    #   p Blankity::Blank.new(methods: %i[inspect])
+    #
+    #   # Define a singleton method
+    #   p Blankity::Blank.new{ def cool?(other) = other == 3 }.cool?(3) #=> true
+    #
+    # @rbs (?methods: Array[interned], ?hash: bool) ?{ () [self: instance] -> void } -> void
+    def initialize(methods: [], hash: false, &block)
+      # If `hash` is supplied, then add `hash` and `eql?` to the list of methods to define
+      methods |= %i[hash eql?] if hash
 
-      methods.each do |method|
-        dsm.call(method, ::Object.instance_method(method))
-      end
+      # Define any object methods requested by the end-user
+      __define_Object_methods__(*methods)
 
-      self
+      # If a block's provided, then `instance_exec`
+      INSTANCE_EXEC.bind_call(self, &__any__ = block) if block
     end
 
-    # Same as `__with_Object_methods__`, but adds them to subclasses. This shouldn't
-    # be called on `Blankity::Blank` directly, as that affects subclasses
-    def self.__with_Object_methods__(*methods)
-      if ::Blankity::Blank.equal?(self)
-        raise ArgumentError, 'Cannot call `__with_Object_methods__` on Blank, as that will affect all blank slates'
-      end
-
+    # A helper method to define {Object} instance methods on +self+
+    #
+    # @param methods [*interned] The list of instance methods from {Object} to define
+    # @return [self]
+    #
+    # === Example
+    #   # Make an empty instance
+    #   blank = Blankity::Blank.blank
+    #
+    #   # Make sure it's printable
+    #   blank.__define_Object_methods__(:inspect, :==)
+    #
+    #   # Now you can use them!
+    #   fail unless blank == blank
+    #   p blank
+    #
+    # @rbs (*interned) -> self
+    def __define_Object_methods__(*methods)
       methods.each do |method|
-        define_method(method, ::Kernel.instance_method(method))
+        DEFINE_SINGLETON_METHOD.bind_call(self, method, ::Object.instance_method(method).bind(self))
       end
 
       self
     end
-
-    # Helper method to create a new `Blank` with a block
-    def self.blank(&block)
-      ::Class.new(self, &block).new
-    end
   end
 
-  def self.blank(...) = Blank.blank(...)
+  # Shorthand constructor {Blankity::Blank}.
+  #
+  # @rbs (?methods: Array[interned], ?hash: bool) ?{ () [self: Blank] -> void } -> Blank
+  def self.blank(...) = Blank.new(...)
 end

data/lib/blankity/classes.rb

@@ -2,70 +2,66 @@
 # rbs_inline: enabled
 
 module Blankity
-  # BlankValue is a superclass of the +ToXXX+ classes, which consolidates their initialization
-  # into one convenient place
-  #
-  # @rbs generic T -- type of @__value__
-  class BlankValue < Blank
-    # @rbs @__value__: T
-
-    DEFINE_SINGLETON_METHOD = ::Kernel.instance_method(:define_singleton_method)
-    private_constant :DEFINE_SINGLETON_METHOD
+  # A Class which only defines +#to_i+; it implements RBS's +_ToI+ interface.
+  class ToI < Blank
+    # @rbs @__value__: Integer
 
-    # Creates a new {BlankValue}, and defining singleton methods depending on the parameters
+    # Creates a new instance; any additional arguments or block are passed to {Blank#initialize}.
     #
-    # @param value [T] the backing value for this class
-    # @param methods [Array[interned]] a list of methods to define on +self+ that will just forward
-    #                                  everything to +value.<method>+
-    # @param hash [bool] convenience argument, adds +hash+ and +eql?+ to +methods+ so the resulting
-    #                    type can be used as a key in +Hash+es
-    # @yield [] if a block is given, runs it via +instance_exec+.
-    #
-    # @rbs (T, ?methods: Array[interned], ?hash: bool) ?{ () [self: self] -> void } -> void
-    def initialize(value, methods: [], hash: false, &block)
+    # @rbs (Integer, ?methods: Array[interned], ?hash: bool) ?{ () [self: instance] -> void } -> void
+    def initialize(value, ...)
       @__value__ = value
-
-      # If `hash` is supplied, then add `hash` and `eql?` to the list of methods to define
-      methods |= %i[hash eql?] if hash
-
-      methods.each do |method|
-        # We can use `.method` instead of querying `Kernel` because all types that are used here
-        # inherit from `Object`.
-        DEFINE_SINGLETON_METHOD.bind_call(self, method, &@__value__.method(method))
-      end
-
-      instance_exec(&block) if block
+      super(...)
     end
-  end
 
-  # A Class which exclusively defines +#to_i+; it implements RBS's +_ToI+ interface.
-  #
-  # @rbs inherits BlankValue[Integer]
-  class ToI < BlankValue
     #: () -> Integer
     def to_i = @__value__
   end
 
   # A Class which exclusively defines +#to_int+; it implements RBS's +_ToInt+ interface.
-  #
-  # @rbs inherits BlankValue[Integer]
-  class ToInt < BlankValue
+  class ToInt < Blank
+    # @rbs @__value__: Integer
+
+    # Creates a new instance; any additional arguments or block are passed to {Blank#initialize}.
+    #
+    # @rbs (Integer, ?methods: Array[interned], ?hash: bool) ?{ () [self: instance] -> void } -> void
+    def initialize(value, ...)
+      @__value__ = value
+      super(...)
+    end
+
     #: () -> Integer
     def to_int = @__value__
   end
 
   # A Class which exclusively defines +#to_s+; it implements RBS's +_ToS+ interface.
-  #
-  # @rbs inherits BlankValue[String]
-  class ToS < BlankValue
+  class ToS < Blank
+    # @rbs @__value__: String
+
+    # Creates a new instance; any additional arguments or block are passed to {Blank#initialize}.
+    #
+    # @rbs (String, ?methods: Array[interned], ?hash: bool) ?{ () [self: instance] -> void } -> void
+    def initialize(value, ...)
+      @__value__ = value
+      super(...)
+    end
+
     #: () -> String
     def to_s = @__value__
   end
 
   # A Class which exclusively defines +#to_str+; it implements RBS's +_ToStr+ interface.
-  #
-  # @rbs inherits BlankValue[String]
-  class ToStr < BlankValue
+  class ToStr < Blank
+    # @rbs @__value__: String
+
+    # Creates a new instance; any additional arguments or block are passed to {Blank#initialize}.
+    #
+    # @rbs (String, ?methods: Array[interned], ?hash: bool) ?{ () [self: instance] -> void } -> void
+    def initialize(value, ...)
+      @__value__ = value
+      super(...)
+    end
+
     #: () -> String
     def to_str = @__value__
   end
@@ -73,8 +69,17 @@ module Blankity
   # A Class which exclusively defines +#to_a+; it implements RBS's +_ToA[T]+ interface.
   #
   # @rbs generic unchecked out T -- Type of elements
-  # @rbs inherits BlankValue[Array[T]]
-  class ToA < BlankValue
+  class ToA < Blank
+    # @rbs @__value__: Array[T]
+
+    # Creates a new instance; any additional arguments or block are passed to {Blank#initialize}.
+    #
+    # @rbs (Array[T], ?methods: Array[interned], ?hash: bool) ?{ () [self: instance] -> void } -> void
+    def initialize(value, ...)
+      @__value__ = value
+      super(...)
+    end
+
     #: () -> Array[T]
     def to_a = @__value__
   end
@@ -82,8 +87,17 @@ module Blankity
   # A Class which exclusively defines +#to_ary+; it implements RBS's +_ToAry[T]+ interface.
   #
   # @rbs generic unchecked out T -- Type of elements
-  # @rbs inherits BlankValue[Array[T]]
-  class ToAry < BlankValue
+  class ToAry < Blank
+    # @rbs @__value__: Array[T]
+
+    # Creates a new instance; any additional arguments or block are passed to {Blank#initialize}.
+    #
+    # @rbs (Array[T], ?methods: Array[interned], ?hash: bool) ?{ () [self: instance] -> void } -> void
+    def initialize(value, ...)
+      @__value__ = value
+      super(...)
+    end
+
     #: () -> Array[T]
     def to_ary = @__value__
   end
@@ -92,8 +106,17 @@ module Blankity
   #
   # @rbs generic unchecked out K -- Type of Key
   # @rbs generic unchecked out V -- Type of Value
-  # @rbs inherits BlankValue[Hash[K, V]]
-  class ToH < BlankValue
+  class ToH < Blank
+    # @rbs @__value__: Hash[K, V]
+
+    # Creates a new instance; any additional arguments or block are passed to {Blank#initialize}.
+    #
+    # @rbs (Hash[K, V], ?methods: Array[interned], ?hash: bool) ?{ () [self: instance] -> void } -> void
+    def initialize(value, ...)
+      @__value__ = value
+      super(...)
+    end
+
     #: () -> Hash[K, V]
     def to_h = @__value__
   end
@@ -102,72 +125,145 @@ module Blankity
   #
   # @rbs generic unchecked out K -- Type of Key
   # @rbs generic unchecked out V -- Type of Value
-  # @rbs inherits BlankValue[Hash[K, V]]
-  class ToHash < BlankValue
+  class ToHash < Blank
+    # @rbs @__value__: Hash[K, V]
+
+    # Creates a new instance; any additional arguments or block are passed to {Blank#initialize}.
+    #
+    # @rbs (Hash[K, V], ?methods: Array[interned], ?hash: bool) ?{ () [self: instance] -> void } -> void
+    def initialize(value, ...)
+      @__value__ = value
+      super(...)
+    end
+
     #: () -> Hash[K, V]
     def to_hash = @__value__
   end
 
   # A Class which exclusively defines +#to_sym+; it implements RBS's +_ToSym+ interface.
-  #
-  # @rbs inherits BlankValue[Symbol]
-  class ToSym < BlankValue
+  class ToSym < Blank
+    # @rbs @__value__: Symbol
+
+    # Creates a new instance; any additional arguments or block are passed to {Blank#initialize}.
+    #
+    # @rbs (Symbol, ?methods: Array[interned], ?hash: bool) ?{ () [self: instance] -> void } -> void
+    def initialize(value, ...)
+      @__value__ = value
+      super(...)
+    end
+
     #: () -> Symbol
     def to_sym = @__value__
   end
 
   # A Class which exclusively defines +#to_r+; it implements RBS's +_ToR+ interface.
-  #
-  # @rbs inherits BlankValue[Rational]
-  class ToR < BlankValue
+  class ToR < Blank
+    # @rbs @__value__: Rational
+
+    # Creates a new instance; any additional arguments or block are passed to {Blank#initialize}.
+    #
+    # @rbs (Rational, ?methods: Array[interned], ?hash: bool) ?{ () [self: instance] -> void } -> void
+    def initialize(value, ...)
+      @__value__ = value
+      super(...)
+    end
+
     #: () -> Rational
     def to_r = @__value__
   end
 
   # A Class which exclusively defines +#to_c+; it implements RBS's +_ToC+ interface.
-  #
-  # @rbs inherits BlankValue[Complex]
-  class ToC < BlankValue
+  class ToC < Blank
+    # @rbs @__value__: Complex
+
+    # Creates a new instance; any additional arguments or block are passed to {Blank#initialize}.
+    #
+    # @rbs (Complex, ?methods: Array[interned], ?hash: bool) ?{ () [self: instance] -> void } -> void
+    def initialize(value, ...)
+      @__value__ = value
+      super(...)
+    end
+
     #: () -> Complex
-    def to_C = @__value__
+    def to_c = @__value__
   end
 
   # A Class which exclusively defines +#to_f+; it implements RBS's +_ToF+ interface.
-  #
-  # @rbs inherits BlankValue[Float]
-  class ToF < BlankValue
+  class ToF < Blank
+    # @rbs @__value__: Float
+
+    # Creates a new instance; any additional arguments or block are passed to {Blank#initialize}.
+    #
+    # @rbs (Float, ?methods: Array[interned], ?hash: bool) ?{ () [self: instance] -> void } -> void
+    def initialize(value, ...)
+      @__value__ = value
+      super(...)
+    end
+
     #: () -> Float
     def to_f = @__value__
   end
 
   # A Class which exclusively defines +#to_regexp+; it implements RBS's +Regexp::_ToRegexp+ interface.
-  #
-  # @rbs inherits BlankValue[Regexp]
-  class ToRegexp < BlankValue
+  class ToRegexp < Blank
+    # @rbs @__value__: Regexp
+
+    # Creates a new instance; any additional arguments or block are passed to {Blank#initialize}.
+    #
+    # @rbs (Regexp, ?methods: Array[interned], ?hash: bool) ?{ () [self: instance] -> void } -> void
+    def initialize(value, ...)
+      @__value__ = value
+      super(...)
+    end
+
     #: () -> Regexp
     def to_regexp = @__value__
   end
 
   # A Class which exclusively defines +#to_path+; it implements RBS's +_ToPath+ interface.
-  #
-  # @rbs inherits BlankValue[String]
-  class ToPath < BlankValue
+  class ToPath < Blank
+    # @rbs @__value__: String
+
+    # Creates a new instance; any additional arguments or block are passed to {Blank#initialize}.
+    #
+    # @rbs (String, ?methods: Array[interned], ?hash: bool) ?{ () [self: instance] -> void } -> void
+    def initialize(value, ...)
+      @__value__ = value
+      super(...)
+    end
+
     #: () -> String
     def to_path = @__value__
   end
 
   # A Class which exclusively defines +#to_io+; it implements RBS's +_ToIO+ interface.
-  #
-  # @rbs inherits BlankValue[IO]
-  class ToIO < BlankValue
+  class ToIO < Blank
+    # @rbs @__value__: IO
+
+    # Creates a new instance; any additional arguments or block are passed to {Blank#initialize}.
+    #
+    # @rbs (IO, ?methods: Array[interned], ?hash: bool) ?{ () [self: instance] -> void } -> void
+    def initialize(value, ...)
+      @__value__ = value
+      super(...)
+    end
+
     #: () -> IO
     def to_io = @__value__
   end
 
   # A Class which exclusively defines +#to_proc+; it implements RBS's +_ToProc+ interface.
-  #
-  # @rbs inherits BlankValue[Proc]
-  class ToProc < BlankValue
+  class ToProc < Blank
+    # @rbs @__value__: Proc
+
+    # Creates a new instance; any additional arguments or block are passed to {Blank#initialize}.
+    #
+    # @rbs (Proc, ?methods: Array[interned], ?hash: bool) ?{ () [self: instance] -> void } -> void
+    def initialize(value, ...)
+      @__value__ = value
+      super(...)
+    end
+
     #: () -> Proc
     def to_proc = @__value__
   end
@@ -181,23 +277,15 @@ module Blankity
     # @rbs @end: T?
     # @rbs @exclude_end: bool
 
-    #: (T?, T?, ?bool) -> void
-    def initialize(begin_, end_, exclude_end = false, methods: [], hash: false, &block)
+    # Creates a new instance; any additional arguments or block are passed to {Blank#initialize}.
+    #
+    # @rbs (T?, T?, ?bool, ?methods: Array[interned], ?hash: bool) ?{ () [self: instance] -> void } -> void
+    def initialize(begin_, end_, exclude_end = false, ...)
       @__begin__ = begin_
       @__end__ = end_
       @__exclude_end__ = exclude_end
 
-      # If `hash` is supplied, then add `hash` and `eql?` to the list of methods to define
-      methods |= %i[hash eql?] if hash
-
-      methods.each do |method|
-        p method
-        # We can use `.method` instead of querying `Kernel` because all types that are used here
-        # inherit from `Object`.
-        DEFINE_SINGLETON_METHOD.bind_call(self, method, &@__value__.method(method))
-      end
-
-      instance_exec(&block) if block
+      super(...)
     end
 
     #: () -> T?