allow autolink to accept a group name and fix docs

lib/active_interaction/base.rb

@@ -40,25 +40,10 @@ class << self
       include Missable
 
       # @!method run(inputs = {})
-      #   @note If the interaction inputs are valid and there are no runtime
-      #     errors and execution completed successfully, {#valid?} will always
-      #     return true.
-      #
-      #   Runs validations and if there are no errors it will call {#execute}.
-      #
-      #   @param (see ActiveInteraction::Base#initialize)
-      #
-      #   @return [Base]
+      #   (see ActiveInteraction::Runnable#run)
 
       # @!method run!(inputs = {})
-      #   Like {.run} except that it returns the value of {#execute} or raises
-      #     an exception if there were any validation errors.
-      #
-      #   @param (see ActiveInteraction::Base.run)
-      #
-      #   @return (see ActiveInteraction::Runnable::ClassMethods#run!)
-      #
-      #   @raise (see ActiveInteraction::Runnable::ClassMethods#run!)
+      #   (see ActiveInteraction::Runnable#run!)
 
       # Get or set the description.
       #
@@ -178,49 +163,19 @@ def initialize(inputs = {})
     end
 
     # @!method compose(other, inputs = {})
-    #   Run another interaction and return its result. If the other interaction
-    #     fails, halt execution.
-    #
-    #   @param other (see ActiveInteraction::Runnable#compose)
-    #   @param inputs (see ActiveInteraction::Base#initialize)
-    #
-    #   @return (see ActiveInteraction::Base.run!)
+    #   (see ActiveInteraction::Runnable#compose)
 
     # @!method link(name)
-    #   Used when sending inputs to `compose`. Links a filter in the current
-    #     interaction such that its value is passed to the other interaction
-    #     in the inputs and errors on that input are mapped back to the linked
-    #     filter.
-    #
-    #   @param name (see ActiveInteraction::Runnable#link)
-    #
-    #   @return (see ActiveInteraction::Runnable#link)
+    #   (see ActiveInteraction::Runnable#link)
 
-    # @!method autolink(*names)
-    #   Used when sending inputs to `compose`. Automatically creates a hash of
-    #     links where the current interaction and the composed interaction share
-    #     filter names.
-    #
-    #   @param *names (see ActiveInteraction::Runnable#autolink)
-    #
-    #   @return (see ActiveInteraction::Runnable#autolink)
+    # @!method autolink(*names, group: nil)
+    #   (see ActiveInteraction::Runnable#autolink)
 
     # @!method automove(*names)
-    #   Used with `merge!` to generate a hash of moves when the moved errors
-    #     share the same name as where they're being moved to.
-    #
-    #   @param *names (see ActiveInteraction::Runnable#automove)
-    #
-    #   @return (see ActiveInteraction::Runnable#automove)
+    #   (see ActiveInteraction::Runnable#automove)
 
     # @!method execute
-    #   @abstract
-    #
-    #   Runs the business logic associated with the interaction. This method is
-    #   only run when there are no validation errors. The return value is
-    #   placed into {#result}.
-    #
-    #   @raise (see ActiveInteraction::Runnable#execute)
+    #   (see ActiveInteraction::Runnable#execute)
 
     # Returns the inputs provided to {.run} or {.run!} after being cast based
     #   on the filters in the class.

lib/active_interaction/concerns/runnable.rb

@@ -37,6 +37,10 @@ def errors
 
     # @abstract
     #
+    # Runs the business logic associated with the interaction. This method is
+    #   only run when there are no validation errors. The return value is
+    #   placed into {#result}.
+    #
     # @raise [NotImplementedError]
     def execute
       raise NotImplementedError
@@ -67,22 +71,37 @@ def valid?(*)
 
     private
 
+    # Used when sending inputs to `compose`. Links a filter in the current
+    #   interaction such that its value is passed to the other interaction
+    #   in the inputs and errors on that input are mapped back to the linked
+    #   filter.
+    #
     # @param name [Symbol] A filter name.
     #
     # @return [Link]
     def link(name)
       Link.new(name, inputs[name])
     end
 
+    # Used when sending inputs to `compose`. Automatically creates a hash of
+    #   links where the current interaction and the composed interaction share
+    #   filter names.
+    #
     # @param *names [Symbol] A list of filter names.
+    # @param group [Symbol] Include filters from this group.
     #
-    # @return [Hash]
-    def autolink(*names)
+    # @return [Hash{Symbol => Link}]
+    def autolink(*names, group: nil)
+      names += inputs.group(group).keys unless group.nil?
+
       names.each_with_object({}) do |name, mapping|
         mapping[name] = link(name)
       end
     end
 
+    # Used with `merge!` to generate a hash of moves when the moved errors
+    #   share the same name as where they're being moved to.
+    #
     # @param *names [Symbol] A list of filter names.
     #
     # @return [Hash]
@@ -92,6 +111,9 @@ def automove(*names)
       end
     end
 
+    # Run another interaction and return its result. If the other interaction
+    #   fails, halt execution.
+    #
     # @param other [Class] The other interaction.
     # @param (see ClassMethods.run)
     #
@@ -132,8 +154,11 @@ def extract_moves(args)
       end
     end
 
-    # @return (see #result=)
-    # @return [nil]
+    # Runs validations and if there are no errors it will call {#execute}.
+    #
+    # @param (see ActiveInteraction::Base#initialize)
+    #
+    # @return [ActiveInteraction::Base]
     def run
       self.result =
         if valid?
@@ -151,6 +176,11 @@ def run
         end
     end
 
+    # Like {.run} except that it returns the value of {#execute} or raises
+    #   an exception if there were any validation errors.
+    #
+    # @param (see .run)
+    #
     # @return [Object]
     #
     # @raise [InvalidInteractionError] If there are validation errors.

spec/active_interaction/base_spec.rb

@@ -44,6 +44,14 @@ def execute
   end
 end
 
+AutoLinkedGroupInteraction = Class.new(TestInteraction) do
+  float :x, :y, groups: [:one]
+
+  def execute
+    compose(AddInteraction, autolink(group: :one))
+  end
+end
+
 FiltersToImportInteraction = Class.new(TestInteraction) do
   float :x
   array :y do
@@ -446,6 +454,14 @@ def execute
         it 'returns the sum' do
           expect(result).to eql x + z
         end
+
+        context 'with the :group option' do
+          let(:described_class) { AutoLinkedGroupInteraction }
+
+          it 'returns the sum' do
+            expect(result).to eql x + z
+          end
+        end
       end
 
       context 'with invalid composition' do