operatic 0.3.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d23afc6809c6d2b335d1db3747eeaa96e931f6a8e3dd51c8cd52261512b78bd4
-  data.tar.gz: f21c35d239aca9518215252494bc1aeb8572750b56e30a4c94ee6aa0e2215aa0
+  metadata.gz: 05be6b41b0969a2f2ae37af1a149095939d78b8724591d7598c46543f15d9070
+  data.tar.gz: 071dc0a5a5d652476a33498206e5e7a34e1c911cd6276018d9022b0558628815
 SHA512:
-  metadata.gz: 010f2b26e6129b0fd7b6ac5c0c1499f1fadb9a0b31027b3ed4334cb54e2a5ecdbf4710e092c64457f6f10f7d97de016887bf7c356b2ffe8711be534e67214eee
-  data.tar.gz: 5e32262f6568ff446897a86840cb1f8bb1a3b19ca0a89fa05ffd7c32ef9f388c8e81862a6b07ea070488d44f3550893d316833e416ec0e1d3509448edf4faec2
+  metadata.gz: e76718b015b9f69c0d7fb8b9b600baacd95abfac4656b1c3d926f1c59b66e2d55e092f0c1cf2382978396fb03d65ce8a0f114f78eb9ee27879d28040e62426ad
+  data.tar.gz: f8adfcf7e3852cf6031ad407b1ea9f0cbdd82d9cd7983bf71fe5fab46c769997406ca58bccfcaddd2bc18ed8e828f29420b937ba15db3ffbdf8b2a5bbfba50aa

data/.github/workflows/ruby.yml

@@ -12,6 +12,7 @@ jobs:
           - '2.6'
           - '2.7'
           - '3.0'
+          - '3.1'
     name: Ruby ${{ matrix.ruby }} RSpec
     steps:
     - uses: actions/checkout@v2
@@ -19,4 +20,8 @@ jobs:
       with:
         bundler-cache: true
         ruby-version: ${{ matrix.ruby }}
-    - run: bundle exec rspec
+    - name: 'Set RSpec exclude pattern for Ruby < 2.7'
+      run: echo "::set-output name=value::**/*_gte_ruby_2_7_spec.rb"
+      if: matrix.ruby == '2.5' || matrix.ruby == '2.6'
+      id: rspec_exclude_pattern
+    - run: bundle exec rspec --exclude-pattern=${{ steps.rspec_exclude_pattern.outputs.value }}

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # CHANGELOG
 
+## Version 0.6.0 - 2022-08-22
+
+- Support pattern matching a Result (in Ruby 2.7+). <https://github.com/benpickles/operatic/pull/12>
+
+## Version 0.5.0 - 2022-06-23
+
+- Support custom initialize method to aid compatibility with other libraries. <https://github.com/benpickles/operatic/pull/11>
+- Rename to `Operatic.result_attr` to be more specific about its functionality. <https://github.com/benpickles/operatic/pull/10>
+- Get and set Result data with `#[]` / `#[]=`. <https://github.com/benpickles/operatic/pull/9>
+
+## Version 0.4.0 - 2022-05-25
+
+- Switch to keyword arguments. <https://github.com/benpickles/operatic/pull/8>
+
 ## Version 0.3.1 - 2020-01-05
 
 - Less specific Rake dependency. <https://github.com/benpickles/operatic/pull/6>

data/README.md

@@ -24,7 +24,7 @@ class SayHello
   attr_reader :name
 
   # Declare convenience accessors on the result.
-  result :message
+  result_attr :message
 
   def call
     # Exit the method and mark the result as a failure.
@@ -36,15 +36,28 @@ class SayHello
 end
 
 result = SayHello.call(name: 'Dave')
-result.success? # => true
-result.message  # => "Hello Dave"
-result.to_h     # => {:message=>"Hello Dave"}
+result.success?  # => true
+result.message   # => "Hello Dave"
+result[:message] # => "Hello Dave"
+result.to_h      # => {:message=>"Hello Dave"}
 
 result = SayHello.call
-result.failure? # => true
-result.success? # => false
-result.message  # => nil
-result.to_h     # => {}
+result.failure?  # => true
+result.success?  # => false
+result.message   # => nil
+result[:message] # => nil
+result.to_h      # => {}
+```
+
+An `Operatic::Result` also supports pattern matching in Ruby 2.7+ returning an array of `[success, data]`:
+
+```ruby
+case SayHello.call(name: 'Dave')
+in [true, { message: }]
+  # Result is a success, do something with the `message` variable.
+in [false, _]
+  # Result is a failure, do something else.
+end
 ```
 
 A Rails controller might use Operatic like this:
@@ -63,6 +76,35 @@ class HellosController < ApplicationController
 end
 ```
 
+Or a pattern matching alternative:
+
+```ruby
+class HellosController < ApplicationController
+  def create
+    case SayHello.call(name: params[:name])
+    in [true, { message: }]
+      render plain: message
+    in [false, _]
+      render :new
+    end
+  end
+end
+```
+
+## Development
+
+Run the tests with:
+
+```
+bundle exec rspec
+```
+
+Generate Yard documentation with:
+
+```
+bundle exec yardoc
+```
+
 ## License
 
 The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/lib/operatic/result.rb

@@ -1,10 +1,10 @@
 module Operatic
   class Result
     # Generate a subclass of {Result} with named +attrs+ accessors. This
-    # wouldn't normally be called directly, see {ClassMethods#result} for
+    # wouldn't normally be called directly, see {ClassMethods#result_attr} for
     # example usage.
     #
-    # @param attrs [Array<Symbol>] a list of accessors to the result's data.
+    # @param attrs [Array<Symbol>] a list of convenience data accessors.
     def self.generate(*attrs)
       Class.new(self) do
         attrs.each do |name|
@@ -24,17 +24,41 @@ module Operatic
       @success = true
     end
 
-    # Mark the result as a failure, optionally attach data, and freeze the
-    # object so it cannot be modified further.
+    # Read data that's attached to the result.
+    def [](key)
+      @data[key]
+    end
+
+    # Set data on the result.
+    def []=(key, value)
+      @data[key] = value
+    end
+
+    # Returns an array of success and data.
+    #
+    # @example
+    #   result = Result.new.success!(message: 'Hello world')
     #
-    # *Note*: After calling this method calling {#success!} or {#failure!}
-    # again will raise a +FrozenError+.
+    #   case result
+    #   in [true, { message: }]
+    #     # Result is a success, do something with the `message` variable.
+    #   in [false, _]
+    #     # Result is a failure, do something else.
+    #   end
     #
-    # @param data [Hash<Symbol, anything>] an optional hash of data to attach
-    #   to the result.
-    def failure!(data = nil)
-      set_data(data) if data
+    # @return [Array(Boolean, Hash<Symbol, anything>)]
+    def deconstruct
+      [@success, @data]
+    end
+
+    # Mark the result as a failure, optionally attach +data+ via kwargs, and
+    # freeze the object so it cannot be modified further.
+    #
+    # *Note*: Calling {#success!} or {#failure!} more than once will raise a
+    # +FrozenError+.
+    def failure!(**data)
       @success = false
+      set_data(data)
       freeze
     end
 
@@ -47,21 +71,18 @@ module Operatic
       super
     end
 
-    # Mark the result as a success, optionally attach data, and freeze the
-    # object so it cannot be modified further.
+    # Mark the result as a success, optionally attach +data+ via kwargs, and
+    # freeze the object so it cannot be modified further.
     #
-    # Calling this is not strictly necessary as a result defaults to being a
+    # Calling this is not strictly necessary as a +Result+ defaults to being a
     # success, but it's a convenient means of attaching data and of indicating
     # intent in the consuming code.
     #
-    # *Note*: After calling this method calling {#success!} or {#failure!}
-    # again will raise a +FrozenError+.
-    #
-    # @param data [Hash<Symbol, anything>] an optional hash of data to attach
-    #   to the result.
-    def success!(data = nil)
-      set_data(data) if data
+    # *Note*: Calling {#success!} or {#failure!} more than once will raise a
+    # +FrozenError+.
+    def success!(**data)
       @success = true
+      set_data(data)
       freeze
     end
 
@@ -72,7 +93,7 @@ module Operatic
     # Returns the full (frozen) hash of data attached to the result via
     # {#success!}, {#failure!}, or convenience accessors added with {.generate}.
     #
-    # @return [Hash]
+    # @return [Hash<Symbol, anything>]
     def to_h
       @data
     end

data/lib/operatic/version.rb

@@ -1,3 +1,3 @@
 module Operatic
-  VERSION = '0.3.1'
+  VERSION = '0.6.0'
 end

data/lib/operatic.rb

@@ -11,15 +11,12 @@ module Operatic
   module ClassMethods
     # The main way of calling an operation.
     #
-    # The class is instantiated with supplied +attrs+ and calls {Operatic#call}
-    # returning a frozen {Result} instance.
+    # The class is instantiated with the supplied +attrs+ keyword arguments and
+    # calls {Operatic#call} returning a frozen {Result} instance.
     #
-    # @param attrs [Hash<Symbol, anything>] an optional hash of key/values to
-    #   to the result. The class must have corresponding +attr_reader+s
-    #
-    # @return a [Result]
-    def call(attrs = nil)
-      new(attrs)
+    # @return [Result]
+    def call(**attrs)
+      new(**attrs)
         .tap(&:call)
         .result
         .freeze
@@ -30,8 +27,8 @@ module Operatic
     # test setups, etc.
     #
     # @return [Result]
-    def call!(attrs = nil)
-      call(attrs).tap { |result|
+    def call!(**attrs)
+      call(**attrs).tap { |result|
         raise FailureError if result.failure?
       }
     end
@@ -45,7 +42,7 @@ module Operatic
     #
     #     attr_reader :name
     #
-    #     result :message
+    #     result_attr :message
     #
     #     def call
     #       success!(message: "Hello #{name}")
@@ -55,8 +52,11 @@ module Operatic
     #   result = SayHello.call(name: 'Dave')
     #   result.success? # => true
     #   result.message  # => "Hello Dave"
-    def result(*args)
-      @result_class = Result.generate(*args)
+    #
+    # @param attrs [Array<Symbol>] a list of convenience data accessors to
+    #   define on the {Result}.
+    def result_attr(*attrs)
+      @result_class = Result.generate(*attrs)
     end
 
     def result_class
@@ -64,22 +64,16 @@ module Operatic
     end
   end
 
-  # An instance of {Result} or a subclass generated by {ClassMethods#result}.
-  #
-  # @return [Result]
-  attr_reader :result
-
-  def initialize(attrs = nil)
-    @result = self.class.result_class.new
-
+  def initialize(**attrs)
     attrs.each do |key, value|
       instance_variable_set("@#{key}", value)
-    end if attrs
+    end
   end
 
   # Override this method with your implementation. Use {#success!} or
   # {#failure!} methods to communicate the {#result}'s status and to attach
-  # data it. Define convenience result accessors with {ClassMethods#result}.
+  # data to it. Define convenience result accessors with
+  # {ClassMethods#result_attr}.
   #
   # @example
   #   class SayHello
@@ -87,6 +81,8 @@ module Operatic
   #
   #     attr_reader :name
   #
+  #     result_attr :message
+  #
   #     def call
   #       return failure! unless name
   #       success!(message: "Hello #{name}")
@@ -94,23 +90,34 @@ module Operatic
   #   end
   #
   #   result = SayHello.call(name: 'Dave')
+  #   result.failure? # => false
   #   result.success? # => true
+  #   result.message  # => "Hello Dave"
   #   result.to_h     # => {:message=>"Hello Dave"}
   #
   #   result = SayHello.call
   #   result.failure? # => true
   #   result.success? # => false
+  #   result.message  # => nil
   #   result.to_h     # => {}
   def call
   end
 
   # Convenience shortcut to the operation's {Result#failure!}.
-  def failure!(data = nil)
-    result.failure!(data)
+  def failure!(**data)
+    result.failure!(**data)
+  end
+
+  # An instance of {Result} or a subclass generated by
+  # {ClassMethods#result_attr}.
+  #
+  # @return [Result]
+  def result
+    @result ||= self.class.result_class.new
   end
 
   # Convenience shortcut to the operation's {Result#success!}.
-  def success!(data = nil)
-    result.success!(data)
+  def success!(**data)
+    result.success!(**data)
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: operatic
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.6.0
 platform: ruby
 authors:
 - Ben Pickles
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2021-01-05 00:00:00.000000000 Z
+date: 2022-08-22 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -97,7 +97,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.2.3
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: A minimal standard interface for your operations