adornable 1.0.0 → 1.0.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b5866ce4d639cd7201a6467800e5ac85fa9e6b823c57496e8ac670059b5d7f5a
-  data.tar.gz: '0418007247c26928a448fd069495b41cdd722d8902f7894185c7589ac8586d2e'
+  metadata.gz: 4bea3ddf067bcb43aee2c2c9cd380297f6f741dc358572d65903a20fd1a0e1ec
+  data.tar.gz: a12b2559a2a647ff58c36f072d4ad0bf71180f3382cffd69d2f43e4fd2d3a040
 SHA512:
-  metadata.gz: be5afe7b6f0eaadd690d4c1e62112a71d1e2f9d26481cec53bf4358a99394809d1d8f2b6a71bf464316320776753bb687bc65e71b96378aabe378da0f2065463
-  data.tar.gz: 250c536c81d0ad0b5c7388af95623e1fc563b0fc41522902542a1e7e2ff9ca0f3f25f6e39378cc1d780ce048e4f184ab4d8a75c2a2f5d1c4ca3621e1084b645d
+  metadata.gz: 65d7e3170d90c2388a4e2a9610a6a2d2cfeb872153bb883791bf975d7f18eae4841ce3550010cfb0f17419b9bec7beeecd0d0553d9b2c46d35e6546ff0a23377
+  data.tar.gz: f3e79890b4d421628bbbf21680d676a83446915b34a067eb1d25fe45806ed4e78f8729be5a15f4308d1f50cfb51911c7235e05762841dd0ca264df997f3b5538

data/.gitignore

@@ -1,11 +1,70 @@
-/.bundle/
-/.yardoc
-/_yardoc/
-/coverage/
-/doc/
+# generic stuff
+.env
+*.gem
+*.rbc
+log/*.log
+/.config
+/InstalledFiles
 /pkg/
-/spec/reports/
 /tmp/
 
-# rspec failure tracking
+# testy stuff
+.rspec
 .rspec_status
+*.orig
+/coverage/
+/coverage/
+/db/*.sqlite3
+/db/*.sqlite3-[0-9]*
+/db/*.sqlite3-journal
+/public/system
+/spec/examples.txt
+/spec/reports/
+/spec/tmp
+/test/tmp/
+/test/version_tmp/
+capybara-*.html
+pickle-email-*.html
+rerun.txt
+test/dummy/db/*.sqlite3
+test/dummy/db/*.sqlite3-journal
+test/dummy/log/*.log
+test/dummy/node_modules/
+test/dummy/storage/
+test/dummy/tmp/
+test/dummy/yarn-error.log
+
+# debuggy stuff
+.byebug_history
+
+## doccy stuff
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## bundly stuff
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# "for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments"
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# rvmmy stuff
+.rvmrc
+
+# editory stuff
+.idea
+.vscode
+*.rdb
+
+# systemy stuff
+*.swm
+*.swn
+*.swo
+*.swp
+*.DS_Store

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    adornable (1.0.0)
+    adornable (1.0.1)
 
 GEM
   remote: https://rubygems.org/

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2021 Keegan Leitz
+
+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

@@ -1,35 +1,361 @@
 # Adornable
 
-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/adornable`. To experiment with that code, run `bin/console` for an interactive prompt.
-
-TODO: Delete this and the text above, and describe your gem
+Adornable provides method decorators in Ruby... 'nuff said.
 
 ## Installation
 
-Add this line to your application's Gemfile:
+### Locally (to your application)
+
+Add the gem to your application's `Gemfile`:
 
 ```ruby
 gem 'adornable'
 ```
 
-And then execute:
+...and then run:
+
+```bash
+bundle install
+```
+
+### Globally (to your system)
 
-    $ bundle
+Alternatively, install it globally:
 
-Or install it yourself as:
+```bash
+gem install adornable
+```
 
-    $ gem install adornable
+...but why would you do that?
 
 ## Usage
 
-TODO: Write usage instructions here
+### The basics
+
+Think of a decorator as if it's just a wrapper function. You want something to happen before, around, or after a method is called, in a reusable (but dynamic) way? Maybe you want to print to a log whenever a certain method is called, or memoize its result so that additional calls don't have to re-execute the body of the method. You've tried this:
+
+```rb
+class RandomValueGenerator
+  def value
+    # logging the method call
+    puts "Calling method `RandomValueGenerator#value` with no arguments"
+    # memoizing the result
+    @value ||= rand
+  end
+
+  def values(max)
+    # logging the method call
+    puts "Calling method `RandomValueGenerator#values` with arguments `[#{max}]`"
+    # memoizing the result
+    @values ||= {}
+    @values[max] ||= (1..max).map { rand }
+  end
+end
+
+random_value_generator = RandomValueGenerator.new
+
+values1 = random_value_generator.values(1000)
+# Calling method `RandomValueGenerator#values` with arguments `[1000]`
+#=> [0.7044444114998132, 0.401953296596267, 0.3023797513191562, ...]
+
+values1 = random_value_generator.values(1000)
+# Calling method `RandomValueGenerator#values` with arguments `[1000]`
+#=> [0.7044444114998132, 0.401953296596267, 0.3023797513191562, ...]
+
+values3 = random_value_generator.values(5000)
+# Calling method `RandomValueGenerator#values` with arguments `[5000]`
+#=> [0.9916088057511011, 0.04466750434972333, 0.6073659341272127]
+
+value1 = random_value_generator.value
+# Calling method `RandomValueGenerator#value` with no arguments
+#=> 0.4196007135344746
+
+value2 = random_value_generator.value
+# Calling method `RandomValueGenerator#value` with no arguments
+#=> 0.4196007135344746
+```
+
+...but you have a million more methods to write, and if you refactor, you'll have to screw around with a whole metric butt-load of method definitions across your app.
+
+How about this instead?
+
+```rb
+class RandomValueGenerator
+  extend Adornable
+
+  decorate :log
+  decorate :memoize
+  def value
+    rand
+  end
+
+  decorate :log
+  decorate :memoize_for_arguments
+  def values(max)
+    (1..max).map { rand }
+  end
+end
+
+random_value_generator = RandomValueGenerator.new
+
+values1 = random_value_generator.values(1000)
+# Calling method `RandomValueGenerator#values` with arguments `[1000]`
+#=> [0.7044444114998132, 0.401953296596267, 0.3023797513191562, ...]
+
+values1 = random_value_generator.values(1000)
+# Calling method `RandomValueGenerator#values` with arguments `[1000]`
+#=> [0.7044444114998132, 0.401953296596267, 0.3023797513191562, ...]
+
+values3 = random_value_generator.values(5000)
+# Calling method `RandomValueGenerator#values` with arguments `[5000]`
+#=> [0.9916088057511011, 0.04466750434972333, 0.6073659341272127]
+
+value1 = random_value_generator.value
+# Calling method `RandomValueGenerator#value` with no arguments
+#=> 0.4196007135344746
+
+value2 = random_value_generator.value
+# Calling method `RandomValueGenerator#value` with no arguments
+#=> 0.4196007135344746
+```
+
+Nice, right?
+
+> **Note:** in the case of multiple decorators decorating a method, each is executed from top to bottom.
+
+### Adding decorator functionality
+
+Add the `::decorate` macro to your classes by `extend`-ing `Adornable`:
+
+```rb
+class Foo
+  extend Adornable
+
+  # ...
+end
+```
+
+### Decorating methods
+
+Use the `decorate` macro to decorate methods.
+
+#### Using built-in decorators
+
+There are a few built-in decorators:
+
+```rb
+class Foo
+  extend Adornable
+
+  decorate :log
+  def some_method
+    # ...
+  end
+
+  decorate :memoize
+  def some_other_method
+    # ...
+  end
+
+  decorate :memoize_for_arguments
+  def yet_another_method(some_arg, some_other_arg = true, key_word_arg:, key_word_arg_with_default: 123)
+    # ...
+  end
+
+  decorate :log
+  decorate :memoize_for_arguments
+  def oh_boy_another_method(some_arg, some_other_arg = true, key_word_arg:, key_word_arg_with_default: 123)
+    # ...
+  end
+
+  decorate :log
+  def self.yeah_it_works_on_class_methods_too
+    # ...
+  end
+end
+```
+
+- `decorate :log` logs the method name and any passed arguments to the console
+- `decorate :memoize` caches the result of the first call and returns that initial result (and does not execute the method again) for any additional calls
+- `decorate :memoize_for_arguments` acts like `decorate :memoize` but it namespaces that cache by the arguments passed, so it will re-compute (and cache the result) only if the arguments change... if the arguments are the same as any previous time the method was called, it will return the cached result instead
+
+> **Note:** in the case of multiple decorators decorating a method, each is executed from top to bottom.
+
+#### Using custom decorators explicitly
+
+You can reference any decorator method you write, like so:
+
+```rb
+class FooDecorators
+  # Note: this is a class method
+  def self.blast_it(method_receiver, method_name, arguments)
+    puts "Blasting it!"
+    value = yield
+    "#{value}!"
+  end
+
+  # Note: this is an instance method
+  def wait_for_it(method_receiver, method_name, arguments)
+    puts "Waiting..."
+    value = yield
+    "#{value}..."
+  end
+end
+
+class Foo
+  extend Adornable
+
+  # Note: `from: FooDecorators` references a class (and will look for the
+  #       `::blast_it` method on that class)
+  decorate :blast_it, from: FooDecorators
+  def some_method
+    "haha I'm a method"
+  end
+
+  # Note: `from: FooDecorators.new` references an instance (and will look for
+  #       the `#wait_for_it` method on that instance)
+  decorate :wait_for_it, from: FooDecorators.new
+  def other_method
+    "haha I'm another method"
+  end
+
+  decorate :log
+  def yet_another_method(foo, bar:)
+    "haha I'm yet another method"
+  end
+end
+
+foo = Foo.new
+
+foo.some_method
+#=> "haha I'm a method!" # Note the exclamation mark
+
+foo.other_method
+#=> "haha I'm another method..." # Note the ellipsis
+
+foo.yet_another_method(123, bloop: "bleep")
+# Calling method `Foo#yet_another_method` with arguments `[123, {:bloop=>"bleep"}]`
+#=> "haha I'm yet another method"
+```
+
+Use the `from:` option to specify what should receive the decorator method. Keep in mind that the decorator method will be called on the thing specified by `from:`... so, if you provide a class, it better be a class method, and if you supply an instance, it better be an instance method.
+
+Every decorator method must take the following arguments:
+
+- `method_receiver`: the actual object that the [decorated] method is being called on (an object/class); e.g., `Foo` or an instance of `Foo`
+- `method_name`: the name of the [decorated] method being called on `method_receiver` (a symbol); e.g., `:some_method` or `:other_method`
+- `arguments`: an array of arguments passed to the [decorated] method, including keyword arguments; e.g., if `:yet_another_method` was called like `Foo.new.yet_another_method(123, bar: true)` then `arguments` would be `[123, {:bar=>true}]`
+
+> **Note:** Every decorator method _should_ also probably `yield` at some point in the method body. I say _"should"_ because, technically, you don't have to, but if you don't then the original method will never be called. That's a valid use-case, but 99% of the time you're gonna want to `yield`.
+>
+> **Note:** the return value of your decorator **will replace the return value of the decorated method,** so _also_ you should probably return whatever value `yield` returned. Again, it is a valid use case to return something _else,_ but 99% of the time you probably want to return the value returned by the wrapped method.
+
+Contrived example of when you might want to muck around with the return value:
+
+```rb
+class FooDecorators
+  def self.coerce_to_int(method_receiver, method_name, arguments)
+    value = yield
+    new_value = value.strip.to_i
+    puts "New value: #{value.inspect} (class: #{value.class})"
+    new_value
+  end
+end
+
+class Foo
+  extend Adornable
+
+  decorate :coerce_to_int, from: FooDecorators
+  def get_number_from_user
+    print "Enter a number: "
+    value = gets
+    puts "Value: #{value.inspect} (class: #{value.class})"
+    value
+  end
+end
+
+foo = Foo.new
+
+foo.get_number_from_user
+# Enter a number
+# > 123
+# Value: "123" (class: String)
+# New value: 123 (class: Integer)
+#=> 123
+```
+
+#### Using custom decorators implicitly
+
+You can also register decorator receivers so that you don't have to reference them with the `from:` option:
+
+```rb
+class FooDecorators
+  # Note: this is a class method
+  def self.blast_it(method_receiver, method_name, arguments)
+    puts "Blasting it!"
+    value = yield
+    "#{value}!"
+  end
+end
+
+class MoreFooDecorators
+  # Note: this is a class method
+  def self.wait_for_it(method_receiver, method_name, arguments)
+    puts "Waiting for it..."
+    value = yield
+    "#{value}..."
+  end
+end
+
+class Foo
+  extend Adornable
+
+  add_decorators_from FooDecorators
+  add_decorators_from MoreFooDecorators
+
+  decorate :blast_it
+  decorate :wait_for_it
+  def some_method
+    "haha I'm a method"
+  end
+end
+
+foo = Foo.new
+
+foo.some_method
+# Blasting it!
+# Waiting for it...
+#=> "haha I'm a method!..."
+```
+
+> **Note:** In the case of duplicate decorator methods, later receivers registered with `::add_decorators_from` will override any duplicate decorators from earlier registered receivers.
+>
+> **Note:** in the case of multiple decorators decorating a method, each is executed from top to bottom; i.e., the top wraps the next, which wraps the next, and so on, until the method itself is wrapped.
 
 ## Development
 
-After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+### Install dependencies
+
+```bash
+bin/setup
+```
+
+### Run testss
+
+```bash
+rake spec
+```
 
-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 tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+### Create release
+
+```
+rake release
+```
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/adornable.
+Bug reports and pull requests for this project are welcome at its [GitHub page](https://github.com/kjleitz/adornable). If you choose to contribute, please be nice so I don't have to run out of bubblegum, etc.
+
+## License
+
+This project is open source, under the terms of the [MIT license.](https://github.com/kjleitz/adornable/blob/master/LICENSE)

data/lib/adornable/version.rb

@@ -1,3 +1,3 @@
 module Adornable
-  VERSION = "1.0.0"
+  VERSION = "1.0.1"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: adornable
 version: !ruby/object:Gem::Version
-  version: 1.0.0
+  version: 1.0.1
 platform: ruby
 authors:
 - Keegan Leitz
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-02-12 00:00:00.000000000 Z
+date: 2021-02-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -64,6 +64,7 @@ files:
 - ".travis.yml"
 - Gemfile
 - Gemfile.lock
+- LICENSE
 - README.md
 - Rakefile
 - adornable.gemspec