mime_actor 0.5.3 → 0.5.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 709cab49cc347653da124ec9147c7527b96f71df08059b6eab45a5d9b5b06888
-  data.tar.gz: ac9a75000c8711550971fa0d6e4f0ba3bc2b9e706ebd1654702df1b56d3e0f5d
+  metadata.gz: 5eb8de0fc146859794812ae3cb81cb99a1a775668af9681e22409fd8df0b245e
+  data.tar.gz: b39aa38f9a21c2b8a794ba1edaf01e184fbe0277cc256721e61df9f2fa98a3c4
 SHA512:
-  metadata.gz: 40fe1d6ba3560b836c12ec423d8285497f2576f231a385ecf910942cedd8be7c36ea1d20077283f2aa336c0aa1beab92a6472b998a63fde4a3b9de1e71f5a9c3
-  data.tar.gz: 5dc2dcc8697d65e386bf47f898b4ed85b8fe7d364ddfce84be873b966653c713e788c994a57e879e439ae1f6401e69092905dd88319a52c94f8c1be817daa1ca
+  metadata.gz: c4c8f432f1cd6d7a1678b9ed1da3cada46a28ed9406003f4fa9cac78375567dbc15f600c11cf3ef10acd76c8d4449b24385db6397be8f5dab6fc9f1ab6b9c3d9
+  data.tar.gz: bbe236716e0a3969737388f9390349563d088581486b17b8601b150bf88ccaf8a68beadb913c1496cfad0652727a17689a0f2ad9db46c4917bac6449e36e8a21

data/.yardopts

@@ -0,0 +1,2 @@
+--markup markdown
+lib/**/*.rb

data/COMPARE.md

@@ -27,7 +27,7 @@ class EventsController < ActionController::Base
     before_action only: :index { @events = Event.all }
 
     # dynamically defines the action method according to on: argument
-    compose_scene :html, :json, on: :index 
+    act_on_format :html, :json, on: :index 
 
     def index_html
         @event_categories = EventCategory.all
@@ -92,7 +92,7 @@ class EventsController < ActionController::Base
     # AbstractController::Callbacks here to load model with params
     before_action only: [:show, :update] { @event = Event.find(params.require(:event_id)) }
 
-    compose_scene :html, :json, on: [:show, :update]
+    act_on_format :html, :json, on: [:show, :update]
 
     rescue_actor_from ActiveRecord::RecordNotFound, format: :json do |ex|
         render status: :bad_request, json: { error: ex.message }

data/README.md

@@ -16,8 +16,8 @@ class EventsController < ActionController::Base
     before_action only: :index { @events = Event.all }
     before_action only: [:show, :update] { @event = Event.find(params.require(:event_id)) }
 
-    compose_scene :html, :json, on: :index
-    compose_scene :html, :json, on: [:show, :update]
+    act_on_format :html, :json, on: :index
+    act_on_format :html, :json, on: [:show, :update]
 
     rescue_actor_from ActiveRecord::RecordNotFound, format: :json do |ex|
         render status: :bad_request, json: { error: "Resouce not found" }

data/lib/mime_actor/action.rb

@@ -12,9 +12,9 @@ require "action_controller/metal/mime_responds"
 module MimeActor
   # # MimeActor Action
   #
-  # Action is the recommended Module to be included in ActionController.
+  # `Action` is the recommended `Module` to be included in the `ActionController`.
   #
-  # Provides intuitive way of action rendering for a specific MIME type with rescue handlers.
+  # Provides intuitive way of `action` rendering for a specific MIME type with rescue handlers.
   #
   module Action
     extend ActiveSupport::Concern
@@ -27,8 +27,21 @@ module MimeActor
     include Rescue
     include Logging
 
-    ##
-    # The core logic where rendering logics are collected as Proc through configuration and passed over to ActionController::MimeResponds
+    # The core logic where rendering logics are collected as `Proc` through configuration and passed over to `ActionController::MimeResponds`
+    #
+    # @param action the `action` of the controller
+    #
+    # @example process `create` action
+    #   start_scene(:create)
+    #
+    #   # it is equivalent to the following if `create` action is configured with `html` and `json` formats
+    #   def create
+    #     respond_to |format|
+    #       format.html { public_send(:create_html) }
+    #       format.json { public_send(:create_json) }
+    #     end
+    #   end
+    #
     def start_scene(action)
       action = action&.to_sym
       formats = acting_scenes.fetch(action, Set.new)

data/lib/mime_actor/logging.rb

@@ -10,7 +10,7 @@ require "active_support/tagged_logging"
 
 module MimeActor
   # # MimeActor Logging
-  # 
+  #
   # Provides a configurable logger.
   module Logging
     extend ActiveSupport::Concern

data/lib/mime_actor/rescue.rb

@@ -13,7 +13,10 @@ require "active_support/core_ext/string/inflections"
 module MimeActor
   # # MimeActor Rescue
   #
-  # Simillar to ActionController::Rescue but with additional filtering logic on Action/Format.
+  # Simillar to `ActionController::Rescue` but with additional filtering logic on `action`/`format`.
+  #
+  # @example Rescue RuntimeError when raised for any action with `json` format
+  #   rescue_actor_from RuntimeError, format: :json, with: :handle_json_error
   #
   module Rescue
     extend ActiveSupport::Concern
@@ -26,14 +29,21 @@ module MimeActor
     end
 
     module ClassMethods
-      ##
-      # Registers a rescue handler for the given error classes with action/format filter
+      # Registers a rescue handler for the given error classes with `action`/`format` filter
+      #
+      # @param klazzes the error classes to rescue
+      # @param action the `action` filter
+      # @param format the `format` filter
+      # @param with the rescue hanlder when `block` is not provided
+      # @param block the `block` to evaluate when `with` is not provided
       #
-      # rescue_actor_from StandardError, format: :json, action: :show do |ex|
-      #   render status: :bad_request, json: { error: ex.message }
-      # end
+      # @example Rescue StandardError when raised for any action with `html` format
+      #   rescue_actor_from StandardError, format: :html, with: :handle_html_error
       #
-      # rescue_actor_from StandardError, format: :html, with: :handle_html_error
+      # @example Rescue StandardError when raised for `show` action with `json` format
+      #   rescue_actor_from StandardError, format: :json, action: :show do |ex|
+      #     render status: :bad_request, json: { error: ex.message }
+      #   end
       #
       def rescue_actor_from(*klazzes, action: nil, format: nil, with: nil, &block)
         raise ArgumentError, "error filter is required" if klazzes.empty?
@@ -73,9 +83,16 @@ module MimeActor
         end
       end
 
-      ##
       # Resolve the error provided with the registered handlers.
-      # The handled error will be returned to indicate successful handling
+      #
+      # The handled error will be returned to indicate successful handling.
+      #
+      # @param error the error instance to rescue
+      # @param action the `action` filter
+      # @param format the `format` filter
+      # @param context the context to evaluate for rescue handler
+      # @param visited the errors to skip after no rescue handler matched the filter
+      #
       def rescue_actor(error, action: nil, format: nil, context: self, visited: [])
         return if visited.include?(error)
 

data/lib/mime_actor/scene.rb

@@ -13,12 +13,14 @@ require "active_support/core_ext/module/attribute_accessors"
 module MimeActor
   # # MimeActor Scene
   #
-  # Scene provides configuration for Action + Format definitions
+  # Scene provides configuration for `action` + `format` definitions
   #
-  # compose_scene :html, on: :index
-  # compose_scene :html, :json , on: [:index, :show]
+  # @example register a `html` format on action `index`
+  #     act_on_format :html, on: :index
+  # @example register `html`, `json` formats on actions `index`, `show`
+  #     act_on_format :html, :json , on: [:index, :show]
   #
-  # NOTE: Calling the same action/format multiple times will overwrite previous Action + Format definitions.
+  # NOTE: Calling the same `action`/`format` multiple times will overwrite previous `action` + `format` definitions.
   #
   module Scene
     extend ActiveSupport::Concern
@@ -30,10 +32,18 @@ module MimeActor
     end
 
     module ClassMethods
-      ##
-      # Register Action + Format definitions.
+      # Register `action` + `format` definitions.
       #
-      # For each unique action being registered, it will have a corresponding method being defined.
+      # @param options [Array]
+      # @option options [Array] klazzes the collection of `format`
+      # @option options [Hash] on the collection of `action`
+      #
+      # @example register a `html` format on action `index`
+      #   compose_scene :html, on: :index
+      # @example register `html`, `json` formats on actions `index`, `show`
+      #   compose_scene :html, :json , on: [:index, :show]
+      #
+      # For each unique `action` being registered, it will have a corresponding `action` method being defined.
       def compose_scene(*options)
         config = options.extract_options!
         validate!(:formats, options)
@@ -70,6 +80,8 @@ module MimeActor
           end
         end
       end
+
+      alias act_on_format compose_scene
     end
   end
 end

data/lib/mime_actor/stage.rb

@@ -11,7 +11,7 @@ require "active_support/core_ext/module/attribute_accessors"
 module MimeActor
   # # MimeActor Stage
   #
-  # Stage provides helpers for actor lookup and invocation.
+  # Stage provides helper methods for actor lookup and invocation.
   #
   module Stage
     extend ActiveSupport::Concern
@@ -23,8 +23,10 @@ module MimeActor
     end
 
     module ClassMethods
-      ##
-      # Determine if the name belongs to a public instance method excluding methods inherited from ancesstors
+      # Determine if the `actor_name` belongs to a public instance method excluding methods inherited from ancestors
+      #
+      # @param actor_name
+      #
       def actor?(actor_name)
         # exclude public methods from ancestors
         found = public_instance_methods(false).include?(actor_name.to_sym)
@@ -35,8 +37,20 @@ module MimeActor
         found
       end
 
-      ##
-      # Wraps the given block with lambda, rescue any error raised from the block via #rescue_actor if defined, otherwise, error will be re-raised
+      # Wraps the given `block` with a `lambda`, rescue any error raised from the `block` via `rescue_actor` if defined, otherwise, error will be re-raised
+      #
+      # @param action the `action` to be passed on to `rescue_actor`
+      # @param format the `format` to be passed on to `rescue_actor`
+      # @param context the context for the block evaluation
+      # @param block the `block` to be evaluated
+      #
+      # @example Dispatch a cue that prints out a text
+      #   dispatch = self.class.dispatch_cue(action: :create, format: :json, context: self) do
+      #       puts "completed the dispatch"
+      #   end
+      #
+      #   dispatch.call == "completed the dispatch" # true
+      #
       def dispatch_cue(action: nil, format: nil, context: self, &block)
         raise ArgumentError, "block must be provided" unless block_given?
 
@@ -48,10 +62,11 @@ module MimeActor
       end
     end
 
-    ##
-    # Call the actor method if defined, supports passing arguments to the actor method.
-    # 
-    # If a block is given, the result from the actor method will be yieled to the block
+    # Calls the `actor` method if defined, supports passing arguments to the `actor` method.
+    #
+    # If a block is given, the result from the `actor` method will be yieled to the block.
+    #
+    # @param actor_name
     def cue_actor(actor_name, *args)
       unless self.class.actor?(actor_name)
         raise MimeActor::ActorNotFound, actor_name if raise_on_missing_actor

data/lib/mime_actor/validator.rb

@@ -9,14 +9,14 @@ require "action_dispatch/http/mime_type"
 module MimeActor
   # # MimeActor Validator
   #
-  # Validator provides validation rules for action, format, and rescue handlers by default.
+  # Validator provides validation rules for `action`, `format`, and `with` handlers by default.
   #
-  # # raise error when rule is violated
-  # validate!(:action, action_param)
+  # @example Raise error when rule is violated
+  #   validate!(:action, action_param)
   #
-  # # return the error when rule is violated
-  # ex = validate_action(action_param)
-  # raise ex if error
+  # @example Return the error when rule is violated
+  #   ex = validate_action(action_param)
+  #   raise ex if error
   #
   module Validator
     extend ActiveSupport::Concern
@@ -26,8 +26,9 @@ module MimeActor
     end
 
     module ClassMethods
-      ##
-      # Raise the error returned by validator if present.
+      # Raise the error returned by validator if any.
+      #
+      # @param rule the name of validator
       def validate!(rule, *args)
         validator = "validate_#{rule}"
         raise NameError, "Validator not found, got: #{validator}" unless respond_to?(validator, true)
@@ -36,29 +37,33 @@ module MimeActor
         raise error if error
       end
 
-      ##
-      # validate :action must be a Symbol
+      # Validate `action` must be a Symbol
+      #
+      # @param unchecked the `action` to be validated
       def validate_action(unchecked)
         ArgumentError.new("action must be a Symbol") unless unchecked.is_a?(Symbol)
       end
 
-      ##
-      # validate :actions must be an Array of Symbol
+      # Validate `actions` must be a collection of Symbol
+      #
+      # @param unchecked the `actions` to be validated
       def validate_actions(unchecked)
         rejected = unchecked.reject { |action| action.is_a?(Symbol) }
         NameError.new("invalid actions, got: #{rejected.join(", ")}") if rejected.size.positive?
       end
 
-      ##
-      # validate :format must be a Symbol + a valid MIME type
+      # Validate `format` must be a Symbol and a valid MIME type
+      #
+      # @param unchecked the `format` to be validated
       def validate_format(unchecked)
         return ArgumentError.new("format must be a Symbol") unless unchecked.is_a?(Symbol)
 
         NameError.new("invalid format, got: #{unchecked}") unless scene_formats.include?(unchecked)
       end
 
-      ##
-      # validate :formats must be an Array of Symbol which each of them is a valid MIME type
+      # Validate `formats` must be an collection of Symbol which each of them is a valid MIME type
+      #
+      # @param unchecked the `formats` to be validated
       def validate_formats(unchecked)
         unfiltered = unchecked.to_set
         filtered = unfiltered & scene_formats
@@ -67,8 +72,10 @@ module MimeActor
         NameError.new("invalid formats, got: #{rejected.join(", ")}") if rejected.size.positive?
       end
 
-      ##
-      # validate :with or &block must be provided + :with must be a Symbol or Proc
+      # Validate `with` or `block` must be provided and if `with` is provided, it must be a Symbol or Proc
+      #
+      # @param unchecked the `with` to be validated
+      # @param block the `block` to be valiated
       def validate_with(unchecked, block)
         if unchecked.present? && block.present?
           return ArgumentError.new("provide either the with: keyword argument or a block")

data/lib/mime_actor/version.rb

@@ -12,7 +12,7 @@ module MimeActor
   module VERSION
     MAJOR = 0
     MINOR = 5
-    BUILD = 3
+    BUILD = 4
     PRE   = nil
 
     STRING = [MAJOR, MINOR, BUILD, PRE].compact.join(".")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: mime_actor
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.5.4
 platform: ruby
 authors:
 - Ryan Chang
@@ -63,6 +63,7 @@ files:
 - ".rspec"
 - ".rubocop.yml"
 - ".ruby-version"
+- ".yardopts"
 - COMPARE.md
 - LICENSE
 - README.md