simple-service 0.1.4 → 0.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7921a94a0cb4244efa536f350ec568d21f9d5a5b09e141c459a7e0ad59eb4076
-  data.tar.gz: 2c07601a1334a830bd2ff4b406563d73f816d9cbdc3ced6b788237d15cfce7ef
+  metadata.gz: 11f94dc8ace9fd802e2070599093e8032a83d68ae448b67cd8daddd9c3ff0d99
+  data.tar.gz: 71d8c154622760417f1afb7c036e1c185da50a072604e23a08b08cbb70631c2c
 SHA512:
-  metadata.gz: 97c672710c6317d3eda455b1c1eda485ebc80aed55ce5e3ec6d1af3b08e372247cfdcfbb9e56aabab6e06456bd45f0a5b9b9945e5d980cf7e4886e59fceb735b
-  data.tar.gz: e0733c90d2a99af1c4c88ad4053b4130f7d73fc8d4e2d80e632196ca19dfe4ec5d7480710f789595c6644089410116e392bc48eadba14261347f31e20b996024
+  metadata.gz: 8cce4acded3ec3adb8e58c2dab41a91f7b19b6dba24d3cae68f4954e18b55ab0eb798d7865a3689d64194baa7fc31e2fd40df8aa7e6abb2ecc35fc26dc762734
+  data.tar.gz: 90f763056b319c7cd45030a3f76ae18e672972ff40905408a930c84dbe1410ebdadc3cd710b04a388ad3309080db3be717b9bd3f08e6ea515301db3e77bb0d3d

data/VERSION

@@ -1 +1 @@
-0.1.4
+0.1.5

data/lib/simple/service.rb

@@ -18,14 +18,14 @@ require_relative "service/version"
 #
 #     module GodMode
 #       include Simple::Service
-#     
+#
 #       # Build a universe.
 #       #
 #       # This comment will become part of the full description of the
 #       # "build_universe" service
 #       def build_universe(name, c: , pi: 3.14, e: 2.781)
 #         # at this point I realize that *I* am not God.
-#     
+#
 #         42 # Best try approach
 #       end
 #     end
@@ -36,10 +36,10 @@ require_relative "service/version"
 #     Simple::Service.actions(GodMode)
 #     => {:build_universe=>#<Simple::Service::Action...>, ...}
 #
-# 3. <em>Invoke a service:</em> run <tt>Simple::Service.invoke</tt> or <tt>Simple::Service.invoke2</tt>. You must set a context first. 
+# 3. <em>Invoke a service:</em> run <tt>Simple::Service.invoke3</tt> or <tt>Simple::Service.invoke</tt>. You must set a context first.
 #
 #     Simple::Service.with_context do
-#       Simple::Service.invoke(GodMode, :build_universe, "TestWorld", c: 1e9)
+#       Simple::Service.invoke3(GodMode, :build_universe, "TestWorld", c: 1e9)
 #     end
 #     => 42
 #
@@ -79,17 +79,52 @@ module Simple::Service
     end
   end
 
-  # invokes an action with a given +name+ in a service with +arguments+ and +params+.
+  # invokes an action with a given +name+ in a service with +args+ and +flags+.
+  #
+  # This is a helper method which one can use to easily call an action from
+  # ruby source code.
+  #
+  # As the main purpose of this module is to call services with outside data,
+  # the +.invoke+ action is usually preferred.
+  #
+  # *Note:* You cannot call this method if the context is not set.
+  def self.invoke3(service, name, *args, **flags)
+    flags = flags.each_with_object({}) { |(k, v), hsh| hsh[k.to_s] = v }
+    invoke service, name, args: args, flags: flags
+  end
+
+  # invokes an action with a given +name+.
+  #
+  # This is the general form of invoking a service. It accepts the following
+  # arguments:
+  #
+  # - args: an Array of positional arguments OR a Hash of named arguments.
+  # - flags: a Hash of flags.
   #
-  # When calling +invoke+ using positional arguments (i.e. non-keyword arguments)
-  # they will be matched against positional arguments of the invoked method - 
-  # but they will not be matched against named arguments.
+  # Note that the keys in both the +flags+ and the +args+ Hash must be strings.
   #
-  # In other words: if the service implements an action "def foo(bar, baz:)", one can
-  # run it via
+  # The service is being called with a parameters built out of those like this:
   #
-  # - +Service.invoke("bar-value", baz: "baz-value")+, or via
-  # - +Service.invoke(bar: "bar-value", baz: "baz-value")+  
+  # - The service's positional arguments are being built from the +args+ array
+  #   parameter or from the +named_args+ hash parameter.
+  # - The service's keyword arguments are being built from the +named_args+
+  #   and +flags+ arguments.
+  #
+  # In other words:
+  #
+  # 1. You cannot set both +args+ and +named_args+ at the same time.
+  # 2. The +flags+ arguments are only being used to determine the
+  #    service's keyword parameters.
+  #
+  # So, if the service X implements an action "def foo(bar, baz:)", the following would
+  # all invoke that service:
+  #
+  # - +Service.invoke3(X, :foo, "bar-value", baz: "baz-value")+, or
+  # - +Service.invoke3(X, :foo, bar: "bar-value", baz: "baz-value")+, or
+  # - +Service.invoke(X, :foo, args: ["bar-value"], flags: { "baz" => "baz-value" })+, or
+  # - +Service.invoke(X, :foo, args: { "bar" => "bar-value", "baz" => "baz-value" })+.
+  #
+  # (see spec/service_spec.rb)
   #
   # When there are not enough positional arguments to match the number of required
   # positional arguments of the method we raise an ArgumentError.
@@ -98,21 +133,16 @@ module Simple::Service
   # by the method we raise an ArgumentError.
   #
   # Entries in the +named_args+ Hash that are not defined in the action itself are ignored.
-  #
-  # *Note:* You cannot call this method if the context is not set.
-  def self.invoke(service, name, *args, **named_args)
-    raise ContextMissingError, "Need to set context before calling ::Simple::Service.invoke" unless context
 
-    action(service, name).invoke(*args, **named_args)
-  end
+  # <b>Note:</b> You cannot call this method if the context is not set.
+  def self.invoke(service, name, args: {}, flags: {})
+    raise ContextMissingError, "Need to set context before calling ::Simple::Service.invoke3" unless context
 
-  # invokes an action with a given +name+ in a service with a Hash of arguments.
-  #
-  # You cannot call this method if the context is not set.
-  def self.invoke2(service, name, args: {}, flags: {})
-    raise ContextMissingError, "Need to set context before calling ::Simple::Service.invoke" unless context
+    expect! args => [Hash, Array], flags: Hash
+    args.keys.each { |key| expect! key => String } if args.is_a?(Hash)
+    flags.keys.each { |key| expect! key => String }
 
-    action(service, name).invoke2(args: args, flags: flags)
+    action(service, name).invoke(args: args, flags: flags)
   end
 
   module ClassMethods # @private

data/lib/simple/service/action.rb

@@ -5,13 +5,11 @@ end
 
 require_relative "./action/comment"
 require_relative "./action/parameter"
-require_relative "./action/indie_hash"
 
 module Simple::Service
   # rubocop:disable Metrics/AbcSize
   # rubocop:disable Metrics/PerceivedComplexity
   # rubocop:disable Metrics/CyclomaticComplexity
-  # rubocop:disable Style/GuardClause
   # rubocop:disable Metrics/ClassLength
 
   class Action
@@ -71,30 +69,11 @@ module Simple::Service
       @service.instance_method(name).source_location
     end
 
-    # build a service_instance and run the action, with arguments constructed from
-    # args_hsh and params_hsh.
-    def invoke(*args, **named_args)
-      # convert Array arguments into a Hash of named arguments. This is strictly
-      # necessary to be able to apply default value-based type conversions. (On
-      # the downside this also means we convert an array to a hash and then back
-      # into an array. This, however, should only be an issue for CLI based action
-      # invocations, because any other use case (that I can think of) should allow
-      # us to provide arguments as a Hash.
-      args = convert_argument_array_to_hash(args)
-      named_args = named_args.merge(args)
-
-      invoke2(args: named_args, flags: {})
-    end
-
     # invokes an action with a given +name+ in a service with a Hash of arguments.
     #
     # You cannot call this method if the context is not set.
-    def invoke2(args:, flags:)
-      # args and flags are being stringified. This is necessary to not allow any
-      # unchecked input to DOS this process by just providing always changing
-      # key values.
-      args = IndieHash.new(args)
-      flags = IndieHash.new(flags)
+    def invoke(args:, flags:)
+      args = convert_argument_array_to_hash(args) if args.is_a?(Array)
 
       verify_required_args!(args, flags)
 
@@ -145,7 +124,7 @@ module Simple::Service
     end
 
     def positional_names
-      @positional_names ||= parameters.select(&:positional?).map(&:name)
+      @positional_names ||= parameters.select(&:positional?).map(&:name).map(&:to_s)
     end
 
     # Enumerating all parameters it collects all positional parameters into
@@ -177,26 +156,34 @@ module Simple::Service
     def convert_argument_array_to_hash(ary)
       expect! ary => Array
 
-      hsh = {}
-
-      if variadic_parameter
-        hsh[variadic_parameter.name] = []
-      end
-
-      if ary.length > positional_names.length
+      # +ary* might contain more, less, or the exact number of positional
+      # arguments. If the number is less, we return a hash with only whart
+      # exists in ary - the action might define default values after all.
+      #
+      # If it contains more the action better supports a variadic parameter;
+      # we otherwise raise a ExtraArguments exception.
+      case ary.length <=> positional_names.length
+      when 1  # i.e. ary.length > positional_names.length
         extra_arguments = ary[positional_names.length..-1]
+        ary = ary[0..positional_names.length]
 
-        if variadic_parameter
-          hsh[variadic_parameter.name] = extra_arguments
-        else
+        if !extra_arguments.empty? && !variadic_parameter
           raise ::Simple::Service::ExtraArguments.new(self, extra_arguments)
         end
-      end
 
-      ary.zip(positional_names).each do |value, parameter_name|
-        hsh[parameter_name] = value
+        existing_positional_names = positional_names
+      when 0  # i.e. ary.length == positional_names.length
+        existing_positional_names = positional_names
+      when -1 # i.e. ary.length < positional_names.length
+        existing_positional_names = positional_names[0, ary.length]
       end
 
+      # Build a hash with the existing_positional_names and the values from the array.
+      hsh = Hash[existing_positional_names.zip(ary)]
+
+      # Add the variadic_parameter, if any.
+      hsh[variadic_parameter.name] = extra_arguments if variadic_parameter
+
       hsh
     end
   end

data/lib/simple/service/action/parameter.rb

@@ -36,7 +36,7 @@ class ::Simple::Service::Action::Parameter
     expect! default_value.length => [0, 1]
 
     @kind = kind
-    @name = name
+    @name = name.to_s
     @default_value = default_value[0]
   end
 end

data/spec/simple/service/action_invoke3_spec.rb

@@ -0,0 +1,266 @@
+# rubocop:disable Style/WordArray
+
+require "spec_helper"
+
+describe "Simple::Service.invoke3" do
+  # the context to use in the around hook below. By default this is nil -
+  # which gives us an empty context.
+  let(:context) { nil }
+
+  around do |example|
+    ::Simple::Service.with_context(context) { example.run }
+  end
+
+  let(:service) { InvokeTestService }
+  let(:action)  { nil }
+
+  # a shortcut
+  def invoke3!(*args, **keywords)
+    @actual = ::Simple::Service.invoke3(service, action, *args, **keywords)
+    # rescue ::StandardError => e
+  rescue ::Simple::Service::ArgumentError => e
+    @actual = e
+  end
+
+  attr_reader :actual
+
+  # when calling #invoke3 using positional arguments they will be matched against
+  # positional arguments of the invoke3d method - but they will not be matched
+  # against named arguments.
+  #
+  # When there are not enough positional arguments to match the number of required
+  # positional arguments of the method we raise an ArgumentError.
+  #
+  # When there are more positional arguments provided than the number accepted
+  # by the method we raise an ArgumentError.
+
+  context "calling an action w/o parameters" do
+    # reminder: this is the definition of no_params
+    #
+    # def no_params
+    #   "service2 return"
+    # end
+
+    let(:action) { :no_params }
+
+    context "calling without args" do
+      it "runs the action" do
+        invoke3!
+        expect(actual).to eq("service2 return")
+      end
+    end
+
+    context "calling with extra positional args" do
+      it "raises ExtraArguments" do
+        invoke3!("foo", "bar")
+        expect(actual).to be_a(::Simple::Service::ExtraArguments)
+        expect(actual.to_s).to match(/"foo", "bar"/)
+      end
+    end
+
+    context "calling with extra named args" do
+      it "ignores extra args" do
+        invoke3!(foo: "foo", bar: "bar")
+        expect(actual).to eq("service2 return")
+      end
+    end
+
+    context "calling with an additional hash arg" do
+      xit "ignores extra args" do
+        args = []
+        args.push foo: "foo", bar: "bar"
+        invoke3!(*args)
+
+        expect(actual).to be_a(::Simple::Service::ExtraArguments)
+      end
+    end
+  end
+
+  context "calling an action w/positional parameters" do
+    # reminder: this is the definition of positional_params
+    #
+    # def positional_params(a, b, c = "speed-of-light", e = 2.781)
+    #   [a, b, c, e]
+    # end
+
+    let(:action) { :positional_params }
+
+    context "without args" do
+      it "raises MissingArguments" do
+        invoke3!
+        expect(actual).to be_a(::Simple::Service::MissingArguments)
+      end
+    end
+
+    context "with the required number of args" do
+      it "runs" do
+        invoke3!("foo", "bar")
+        expect(actual).to eq(["foo", "bar", "speed-of-light", 2.781])
+      end
+    end
+
+    context "with the allowed number of args" do
+      it "runs" do
+        invoke3!("foo", "bar", "baz", "number4")
+        expect(actual).to eq(%w[foo bar baz number4])
+      end
+    end
+
+    context "with more than the allowed number of args" do
+      it "raises ExtraArguments" do
+        invoke3!("foo", "bar", "baz", "number4", "extra")
+        expect(actual).to be_a(::Simple::Service::ExtraArguments)
+      end
+    end
+
+    context "calling with extra named args" do
+      it "ignores extra args" do
+        invoke3!("foo", "bar", "baz", extra3: 3)
+        expect(actual).to eq(["foo", "bar", "baz", 2.781])
+      end
+    end
+
+    context "calling with an additional hash arg" do
+      xit "raises ExtraArguments" do
+        args = ["foo", "bar", "baz", extra3: 3]
+        invoke3!(*args)
+        expect(actual).to be_a(::Simple::Service::ExtraArguments)
+      end
+    end
+  end
+
+  context "calling an action w/named parameters" do
+    # reminder: this is the definition of named_params
+    #
+    # def named_params(a:, b:, c: "speed-of-light", e: 2.781)
+    #   [a, b, c, e]
+    # end
+
+    let(:action) { :named_params }
+
+    context "without args" do
+      it "raises MissingArguments" do
+        invoke3!
+        expect(actual).to be_a(::Simple::Service::MissingArguments)
+      end
+    end
+
+    context "with the required number of args" do
+      it "runs" do
+        invoke3!(a: "foo", b: "bar")
+        expect(actual).to eq(["foo", "bar", "speed-of-light", 2.781])
+      end
+    end
+
+    context "with the allowed number of args" do
+      it "runs" do
+        invoke3!(a: "foo", b: "bar", c: "baz", e: "number4")
+        expect(actual).to eq(%w[foo bar baz number4])
+      end
+    end
+
+    context "with more than the allowed number of args" do
+      it "runs" do
+        invoke3!("foo", "bar", "baz", "number4", "extra")
+        expect(actual).to be_a(::Simple::Service::ExtraArguments)
+      end
+    end
+
+    context "with extra named args" do
+      it "ignores extra args" do
+        invoke3!(a: "foo", b: "bar", c: "baz", extra3: 3)
+        expect(actual).to eq(["foo", "bar", "baz", 2.781])
+      end
+    end
+  end
+
+  context "calling an action w/mixed and optional parameters" do
+    # reminder: this is the definition of named_params
+    #
+    # def mixed_optional_params(a, b = "default-b", c = "speed-of-light", e: 2.781)
+    #   [a, b, c, e]
+    # end
+
+    let(:action) { :mixed_optional_params }
+
+    context "without args" do
+      it "raises MissingArguments" do
+        invoke3!
+        expect(actual).to be_a(::Simple::Service::MissingArguments)
+      end
+    end
+
+    context "with the required number of args" do
+      it "runs" do
+        invoke3!("foo")
+        expect(actual).to eq(["foo", "default-b", "speed-of-light", 2.781])
+      end
+    end
+
+    context "with the allowed number of args" do
+      it "runs" do
+        invoke3!("foo", "bar", "baz", e: "number4")
+        expect(actual).to eq(%w[foo bar baz number4])
+      end
+    end
+
+    context "with more than the allowed number of args" do
+      it "runs" do
+        invoke3!("foo", "bar", "baz", "extra", e: "number4")
+        expect(actual).to be_a(::Simple::Service::ExtraArguments)
+      end
+    end
+
+    context "with extra named args" do
+      it "ignores extra args" do
+        invoke3!("foo", "bar", "baz", e: "number4", extra3: 3)
+        expect(actual).to eq(["foo", "bar", "baz", "number4"])
+      end
+    end
+  end
+
+  context "calling an action w/mixed and variadic parameters" do
+    # reminder: this is the definition of variadic_params
+    #
+    # def variadic_params(a, b = "queen bee", *args, e: 2.781)
+    #   [a, b, args, e]
+    # end
+
+    let(:action) { :variadic_params }
+
+    context "without args" do
+      it "raises MissingArguments" do
+        invoke3!
+        expect(actual).to be_a(::Simple::Service::MissingArguments)
+      end
+    end
+
+    context "with the required number of args" do
+      it "runs" do
+        invoke3!("foo")
+        expect(actual).to eq(["foo", "queen bee", [], 2.781])
+      end
+    end
+
+    context "with the allowed number of args" do
+      it "runs" do
+        invoke3!("foo", "bar", "baz", e: "number4")
+        expect(actual).to eq(["foo", "bar", ["baz"], "number4"])
+      end
+    end
+
+    context "with more than the allowed number of args" do
+      it "runs" do
+        invoke3!("foo", "bar", "baz", "extra", e: "number4")
+        expect(actual).to eq(["foo", "bar", ["baz", "extra"], "number4"])
+      end
+    end
+
+    context "with extra named args" do
+      it "ignores extra args" do
+        invoke3!("foo", "bar", "baz", e: "number4", extra3: 3)
+        expect(actual).to eq(["foo", "bar", ["baz"], "number4"])
+      end
+    end
+  end
+end

data/spec/simple/service/action_invoke_spec.rb

@@ -15,8 +15,8 @@ describe "Simple::Service.invoke" do
   let(:action)  { nil }
 
   # a shortcut
-  def invoke!(*args, **keywords)
-    @actual = ::Simple::Service.invoke(service, action, *args, **keywords)
+  def invoke!(args = {}, flags: {})
+    @actual = ::Simple::Service.invoke(service, action, args: args, flags: flags)
     # rescue ::StandardError => e
   rescue ::Simple::Service::ArgumentError => e
     @actual = e
@@ -24,16 +24,6 @@ describe "Simple::Service.invoke" do
 
   attr_reader :actual
 
-  # when calling #invoke using positional arguments they will be matched against
-  # positional arguments of the invoked method - but they will not be matched
-  # against named arguments.
-  #
-  # When there are not enough positional arguments to match the number of required
-  # positional arguments of the method we raise an ArgumentError.
-  #
-  # When there are more positional arguments provided than the number accepted
-  # by the method we raise an ArgumentError.
-
   context "calling an action w/o parameters" do
     # reminder: this is the definition of no_params
     #
@@ -50,30 +40,12 @@ describe "Simple::Service.invoke" do
       end
     end
 
-    context "calling with extra positional args" do
-      it "raises ExtraArguments" do
-        invoke!("foo", "bar")
-        expect(actual).to be_a(::Simple::Service::ExtraArguments)
-        expect(actual.to_s).to match(/"foo", "bar"/)
-      end
-    end
-
     context "calling with extra named args" do
       it "ignores extra args" do
-        invoke!(foo: "foo", bar: "bar")
+        invoke!("foo" => "foo", "bar" => "bar")
         expect(actual).to eq("service2 return")
       end
     end
-
-    context "calling with an additional hash arg" do
-      xit "ignores extra args" do
-        args = []
-        args.push foo: "foo", bar: "bar"
-        invoke!(*args)
-
-        expect(actual).to be_a(::Simple::Service::ExtraArguments)
-      end
-    end
   end
 
   context "calling an action w/positional parameters" do
@@ -89,42 +61,28 @@ describe "Simple::Service.invoke" do
       it "raises MissingArguments" do
         invoke!
         expect(actual).to be_a(::Simple::Service::MissingArguments)
+        expect(actual.to_s).to match(/\ba, b\b/)
       end
     end
 
     context "with the required number of args" do
       it "runs" do
-        invoke!("foo", "bar")
+        invoke!("a" => "foo", "b" => "bar")
         expect(actual).to eq(["foo", "bar", "speed-of-light", 2.781])
       end
     end
 
     context "with the allowed number of args" do
       it "runs" do
-        invoke!("foo", "bar", "baz", "number4")
+        invoke!("a" => "foo", "b" => "bar", "c" => "baz", "e" => "number4")
         expect(actual).to eq(%w[foo bar baz number4])
       end
     end
 
-    context "with more than the allowed number of args" do
-      it "raises ExtraArguments" do
-        invoke!("foo", "bar", "baz", "number4", "extra")
-        expect(actual).to be_a(::Simple::Service::ExtraArguments)
-      end
-    end
-
     context "calling with extra named args" do
       it "ignores extra args" do
-        invoke!("foo", "bar", "baz", extra3: 3)
-        expect(actual).to eq(["foo", "bar", "baz", 2.781])
-      end
-    end
-
-    context "calling with an additional hash arg" do
-      xit "raises ExtraArguments" do
-        args = ["foo", "bar", "baz", extra3: 3]
-        invoke!(*args)
-        expect(actual).to be_a(::Simple::Service::ExtraArguments)
+        invoke!("a" => "foo", "b" => "bar", "c" => "baz", "e" => "number4", "extra3" => 3)
+        expect(actual).to eq(%w[foo bar baz number4])
       end
     end
   end
@@ -132,7 +90,7 @@ describe "Simple::Service.invoke" do
   context "calling an action w/named parameters" do
     # reminder: this is the definition of named_params
     #
-    # def named_params(a:, b:, c: "speed-of-light", e: 2.781)
+    # def named_params(a:, b:, "c" => "speed-of-light", e: 2.781)
     #   [a, b, c, e]
     # end
 
@@ -142,33 +100,27 @@ describe "Simple::Service.invoke" do
       it "raises MissingArguments" do
         invoke!
         expect(actual).to be_a(::Simple::Service::MissingArguments)
+        expect(actual.to_s).to match(/\ba, b\b/)
       end
     end
 
     context "with the required number of args" do
       it "runs" do
-        invoke!(a: "foo", b: "bar")
+        invoke!("a" => "foo", "b" => "bar")
         expect(actual).to eq(["foo", "bar", "speed-of-light", 2.781])
       end
     end
 
     context "with the allowed number of args" do
       it "runs" do
-        invoke!(a: "foo", b: "bar", c: "baz", e: "number4")
+        invoke!("a" => "foo", "b" => "bar", "c" => "baz", "e" => "number4")
         expect(actual).to eq(%w[foo bar baz number4])
       end
     end
 
-    context "with more than the allowed number of args" do
-      it "runs" do
-        invoke!("foo", "bar", "baz", "number4", "extra")
-        expect(actual).to be_a(::Simple::Service::ExtraArguments)
-      end
-    end
-
     context "with extra named args" do
       it "ignores extra args" do
-        invoke!(a: "foo", b: "bar", c: "baz", extra3: 3)
+        invoke!("a" => "foo", "b" => "bar", "c" => "baz", "extra3" => 3)
         expect(actual).to eq(["foo", "bar", "baz", 2.781])
       end
     end
@@ -192,75 +144,23 @@ describe "Simple::Service.invoke" do
 
     context "with the required number of args" do
       it "runs" do
-        invoke!("foo")
+        invoke!("a" => "foo")
         expect(actual).to eq(["foo", "default-b", "speed-of-light", 2.781])
       end
     end
 
     context "with the allowed number of args" do
       it "runs" do
-        invoke!("foo", "bar", "baz", e: "number4")
+        invoke!("a" => "foo", "b" => "bar", "c" => "baz", "e" => "number4")
         expect(actual).to eq(%w[foo bar baz number4])
       end
     end
 
-    context "with more than the allowed number of args" do
-      it "runs" do
-        invoke!("foo", "bar", "baz", "extra", e: "number4")
-        expect(actual).to be_a(::Simple::Service::ExtraArguments)
-      end
-    end
-
     context "with extra named args" do
       it "ignores extra args" do
-        invoke!("foo", "bar", "baz", e: "number4", extra3: 3)
+        invoke!("a" => "foo", "b" => "bar", "c" => "baz", "e" => "number4", "extra3" => 3)
         expect(actual).to eq(["foo", "bar", "baz", "number4"])
       end
     end
   end
-
-  context "calling an action w/mixed and variadic parameters" do
-    # reminder: this is the definition of variadic_params
-    #
-    # def variadic_params(a, b = "queen bee", *args, e: 2.781)
-    #   [a, b, args, e]
-    # end
-
-    let(:action) { :variadic_params }
-
-    context "without args" do
-      it "raises MissingArguments" do
-        invoke!
-        expect(actual).to be_a(::Simple::Service::MissingArguments)
-      end
-    end
-
-    context "with the required number of args" do
-      it "runs" do
-        invoke!("foo")
-        expect(actual).to eq(["foo", "queen bee", [], 2.781])
-      end
-    end
-
-    context "with the allowed number of args" do
-      it "runs" do
-        invoke!("foo", "bar", "baz", e: "number4")
-        expect(actual).to eq(["foo", "bar", ["baz"], "number4"])
-      end
-    end
-
-    context "with more than the allowed number of args" do
-      it "runs" do
-        invoke!("foo", "bar", "baz", "extra", e: "number4")
-        expect(actual).to eq(["foo", "bar", ["baz", "extra"], "number4"])
-      end
-    end
-
-    context "with extra named args" do
-      it "ignores extra args" do
-        invoke!("foo", "bar", "baz", e: "number4", extra3: 3)
-        expect(actual).to eq(["foo", "bar", ["baz"], "number4"])
-      end
-    end
-  end
 end

data/spec/simple/service/service_spec.rb

@@ -22,10 +22,10 @@ describe "Simple::Service" do
       end
     end
 
-    describe ".invoke" do
+    describe ".invoke3" do
       it "raises an argument error" do
         ::Simple::Service.with_context do
-          expect { Simple::Service.invoke(service, :service1, {}, {}, context: nil) }.to raise_error(::ArgumentError)
+          expect { Simple::Service.invoke3(service, :service1, {}, {}, context: nil) }.to raise_error(::ArgumentError)
         end
       end
     end
@@ -76,9 +76,10 @@ describe "Simple::Service" do
     end
   end
 
-  describe ".invoke" do
-    let(:positionals) { { a: "my_a", b: "my_b" } }
-    let(:named) { { d: "my_d" } }
+  describe '.invoke3' do
+    def invoke3
+      Simple::Service.invoke3(service, :service1, "my_a", "my_b", d: "my_d")
+    end
 
     context "when context is not set" do
       it "raises a ContextMissingError" do
@@ -86,20 +87,70 @@ describe "Simple::Service" do
         expect(action).not_to receive(:invoke)
 
         expect do
-          Simple::Service.invoke(service, :service1, *positionals, named_args: named)
+          invoke3
         end.to raise_error(::Simple::Service::ContextMissingError)
       end
     end
 
-    context "when context is not set" do
-      it "properly delegates call to action object" do
+    context "when context is set" do
+      it "calls Action#invoke with the right arguments" do
         action = Simple::Service.actions(service)[:service1]
-        expect(action).to receive(:invoke).with(*positionals, named_args: named)
+        expect(action).to receive(:invoke).with(args: ["my_a", "my_b"], flags: { "d" => "my_d" })
 
         ::Simple::Service.with_context do
-          Simple::Service.invoke(service, :service1, *positionals, named_args: named)
+          invoke3
+        end
+      end
+    end
+  end
+
+  describe ".invoke" do
+    context "with a args array" do
+      def invoke
+        Simple::Service.invoke(service, :service1, args: ["my_a", "my_b"], flags: { "d" => "my_d" })
+      end
+
+      context "when context is not set" do
+        it "raises a ContextMissingError" do
+          action = Simple::Service.actions(service)[:service1]
+          expect(action).not_to receive(:invoke)
+
+          expect do
+            invoke
+          end.to raise_error(::Simple::Service::ContextMissingError)
         end
       end
+
+      context "when context is set" do
+        it "calls Action#invoke with the right arguments" do
+          action = Simple::Service.actions(service)[:service1]
+          expect(action).to receive(:invoke).with(args: ["my_a", "my_b"], flags: { "d" => "my_d" }).and_call_original
+
+          ::Simple::Service.with_context do
+            invoke
+          end
+        end
+      end
+    end
+  end
+
+  describe "documentation example" do
+    def invoke(*args, **flags)
+      Simple::Service.invoke(SpecTestService, :foo, *args, **flags)
+    end
+
+    def invoke3(*args, **flags)
+      Simple::Service.invoke3(SpecTestService, :foo, *args, **flags)
+    end
+
+    it "calls Action#invoke with the right arguments" do
+      expected = ["bar-value", "baz-value"]
+      ::Simple::Service.with_context do
+      expect(invoke3("bar-value", baz: "baz-value")).to eq(expected)
+      expect(invoke3(bar: "bar-value", baz: "baz-value")).to eq(expected)
+      expect(invoke(args: ["bar-value"], flags: { "baz" => "baz-value" })).to eq(expected)
+      expect(invoke(args: { "bar" => "bar-value", "baz" => "baz-value" })).to eq(expected)
+    end
     end
   end
 end

data/spec/support/spec_services.rb

@@ -48,3 +48,11 @@ module InvokeTestService
     [a, b, args, e]
   end
 end
+
+module SpecTestService
+  include Simple::Service
+
+  def foo(bar, baz:)
+    [ bar, baz ]
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: simple-service
 version: !ruby/object:Gem::Version
-  version: 0.1.4
+  version: 0.1.5
 platform: ruby
 authors:
 - radiospiel
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2019-12-03 00:00:00.000000000 Z
+date: 2019-12-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: expectation
@@ -77,7 +77,6 @@ files:
 - lib/simple/service.rb
 - lib/simple/service/action.rb
 - lib/simple/service/action/comment.rb
-- lib/simple/service/action/indie_hash.rb
 - lib/simple/service/action/method_reflection.rb
 - lib/simple/service/action/parameter.rb
 - lib/simple/service/context.rb
@@ -89,7 +88,7 @@ files:
 - scripts/stats
 - scripts/watch
 - simple-service.gemspec
-- spec/simple/service/action_invoke2_spec.rb
+- spec/simple/service/action_invoke3_spec.rb
 - spec/simple/service/action_invoke_spec.rb
 - spec/simple/service/action_spec.rb
 - spec/simple/service/context_spec.rb
@@ -120,7 +119,7 @@ signing_key:
 specification_version: 4
 summary: Pretty simple and somewhat abstract service description
 test_files:
-- spec/simple/service/action_invoke2_spec.rb
+- spec/simple/service/action_invoke3_spec.rb
 - spec/simple/service/action_invoke_spec.rb
 - spec/simple/service/action_spec.rb
 - spec/simple/service/context_spec.rb

data/lib/simple/service/action/indie_hash.rb

@@ -1,37 +0,0 @@
-class Simple::Service::Action
-  # The IndieHash class defines as much of the Hash interface as necessary for simple-service
-  # to successfully run.
-  class IndieHash
-    def initialize(hsh)
-      @hsh = hsh.each_with_object({}) { |(k, v), h| h[k.to_s] = v }
-    end
-
-    def keys
-      @hsh.keys
-    end
-
-    def fetch_values(*keys)
-      keys = keys.map(&:to_s)
-      @hsh.fetch_values(*keys)
-    end
-
-    def key?(sym)
-      @hsh.key?(sym.to_s)
-    end
-
-    def [](sym)
-      @hsh[sym.to_s]
-    end
-
-    def merge(other_hsh)
-      @hsh = @hsh.merge(other_hsh.send(:__hsh__))
-      self
-    end
-
-    private
-
-    def __hsh__
-      @hsh
-    end
-  end
-end

data/spec/simple/service/action_invoke2_spec.rb

@@ -1,166 +0,0 @@
-# rubocop:disable Style/WordArray
-
-require "spec_helper"
-
-describe "Simple::Service.invoke2" do
-  # the context to use in the around hook below. By default this is nil -
-  # which gives us an empty context.
-  let(:context) { nil }
-
-  around do |example|
-    ::Simple::Service.with_context(context) { example.run }
-  end
-
-  let(:service) { InvokeTestService }
-  let(:action)  { nil }
-
-  # a shortcut
-  def invoke2!(**hsh)
-    @actual = ::Simple::Service.invoke2(service, action, args: hsh)
-    # rescue ::StandardError => e
-  rescue ::Simple::Service::ArgumentError => e
-    @actual = e
-  end
-
-  attr_reader :actual
-
-  context "calling an action w/o parameters" do
-    # reminder: this is the definition of no_params
-    #
-    # def no_params
-    #   "service2 return"
-    # end
-
-    let(:action) { :no_params }
-
-    context "calling without args" do
-      it "runs the action" do
-        invoke2!
-        expect(actual).to eq("service2 return")
-      end
-    end
-
-    context "calling with extra named args" do
-      it "ignores extra args" do
-        invoke2!(foo: "foo", bar: "bar")
-        expect(actual).to eq("service2 return")
-      end
-    end
-  end
-
-  context "calling an action w/positional parameters" do
-    # reminder: this is the definition of positional_params
-    #
-    # def positional_params(a, b, c = "speed-of-light", e = 2.781)
-    #   [a, b, c, e]
-    # end
-
-    let(:action) { :positional_params }
-
-    context "without args" do
-      it "raises MissingArguments" do
-        invoke2!
-        expect(actual).to be_a(::Simple::Service::MissingArguments)
-        expect(actual.to_s).to match(/\ba, b\b/)
-      end
-    end
-
-    context "with the required number of args" do
-      it "runs" do
-        invoke2!(a: "foo", b: "bar")
-        expect(actual).to eq(["foo", "bar", "speed-of-light", 2.781])
-      end
-    end
-
-    context "with the allowed number of args" do
-      it "runs" do
-        invoke2!(a: "foo", b: "bar", c: "baz", e: "number4")
-        expect(actual).to eq(%w[foo bar baz number4])
-      end
-    end
-
-    context "calling with extra named args" do
-      it "ignores extra args" do
-        invoke2!(a: "foo", b: "bar", c: "baz", e: "number4", extra3: 3)
-        expect(actual).to eq(%w[foo bar baz number4])
-      end
-    end
-  end
-
-  context "calling an action w/named parameters" do
-    # reminder: this is the definition of named_params
-    #
-    # def named_params(a:, b:, c: "speed-of-light", e: 2.781)
-    #   [a, b, c, e]
-    # end
-
-    let(:action) { :named_params }
-
-    context "without args" do
-      it "raises MissingArguments" do
-        invoke2!
-        expect(actual).to be_a(::Simple::Service::MissingArguments)
-        expect(actual.to_s).to match(/\ba, b\b/)
-      end
-    end
-
-    context "with the required number of args" do
-      it "runs" do
-        invoke2!(a: "foo", b: "bar")
-        expect(actual).to eq(["foo", "bar", "speed-of-light", 2.781])
-      end
-    end
-
-    context "with the allowed number of args" do
-      it "runs" do
-        invoke2!(a: "foo", b: "bar", c: "baz", e: "number4")
-        expect(actual).to eq(%w[foo bar baz number4])
-      end
-    end
-
-    context "with extra named args" do
-      it "ignores extra args" do
-        invoke2!(a: "foo", b: "bar", c: "baz", extra3: 3)
-        expect(actual).to eq(["foo", "bar", "baz", 2.781])
-      end
-    end
-  end
-
-  context "calling an action w/mixed and optional parameters" do
-    # reminder: this is the definition of named_params
-    #
-    # def mixed_optional_params(a, b = "default-b", c = "speed-of-light", e: 2.781)
-    #   [a, b, c, e]
-    # end
-
-    let(:action) { :mixed_optional_params }
-
-    context "without args" do
-      it "raises MissingArguments" do
-        invoke2!
-        expect(actual).to be_a(::Simple::Service::MissingArguments)
-      end
-    end
-
-    context "with the required number of args" do
-      it "runs" do
-        invoke2!(a: "foo")
-        expect(actual).to eq(["foo", "default-b", "speed-of-light", 2.781])
-      end
-    end
-
-    context "with the allowed number of args" do
-      it "runs" do
-        invoke2!(a: "foo", b: "bar", c: "baz", e: "number4")
-        expect(actual).to eq(%w[foo bar baz number4])
-      end
-    end
-
-    context "with extra named args" do
-      it "ignores extra args" do
-        invoke2!(a: "foo", b: "bar", c: "baz", e: "number4", extra3: 3)
-        expect(actual).to eq(["foo", "bar", "baz", "number4"])
-      end
-    end
-  end
-end