simple-service 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9641586855a538c0b450d4731d39d28f23c4ee19abec379f5ac9047888fe9106
-  data.tar.gz: a395f0a7815935557163cc81532ef7e3fc2b97dfc2bf7347e32460481589dd1d
+  metadata.gz: ddfef08de84da78d9ffbc767ed827300fd1c17e354b3227dc896c0271870eece
+  data.tar.gz: 71682a1f87227f246a4ab7d62c5884e2a7babb5052c175e16c902a39572b21d1
 SHA512:
-  metadata.gz: 43a8d60d9c7b1f14913f431b24ebd50db6a41c2b951a41bd8b1c136d466b2d198b0582e7adcbc34b0df0c81206abe79fda05ea25f8e9c74c4f52a5722e23146a
-  data.tar.gz: a0376b41661076f53a4ffe6a20650efc6dda513f762ddd0e96d7c7da0f568b6dc2e687c4fbfb67da759f7ac076ce115468a0fd2ba63a686f7ab15504a1ee5cd8
+  metadata.gz: 760810f36df807705637d39079501aebc79a80be8423a25bc41371c5d4c2f5ee165a2dff4ae55d518e04dd0e07e58f5b306a6566e51dd4a7d8e75cc7fe9bd12b
+  data.tar.gz: 315b4b8ff7d70687e8cfb5cc1a8206d3bdc1bd3200663c1c26ec41c599884e83f96a2be41435400d42f6c763f03aa2e0fd91e1a7d42627b3df415bc8bf4fcdef

data/.rubocop.yml

@@ -10,6 +10,10 @@ AllCops:
     - 'Rakefile'
     - 'scripts/*.rb'
 
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+
 Metrics/LineLength:
   Max: 140
 

data/.tm_properties

@@ -1 +1 @@
-excludeDirectories = "{_build,coverage,assets/node_modules,node_modules,deps,db,cover,priv/static,storage,github,vendor,arena,}"
+excludeDirectories = "{_build,coverage,rdoc,assets/node_modules,node_modules,deps,db,cover,priv/static,storage,github,vendor,arena,}"

data/Makefile

@@ -2,3 +2,15 @@
 
 test:
 	rspec
+
+.PHONY: doc doc/rdoc
+doc: doc/rdoc
+	
+doc/rdoc:
+	rm -rf doc/rdoc
+	rdoc -o doc/rdoc README.md \
+		lib/simple/service.rb \
+		lib/simple/service/action.rb \
+		lib/simple/service/context.rb \
+		lib/simple/service/errors.rb \
+		lib/simple/service/version.rb 

data/README.md

@@ -1 +1,3 @@
 # simple-service – a pretty simple and somewhat abstract service description
+
+Yea, that's it.

data/VERSION

@@ -1 +1 @@
-0.1.1
+0.1.2

data/lib/simple/service.rb

@@ -1,10 +1,12 @@
-module Simple::Service
-  class ArgumentError < ::ArgumentError
-  end
+module Simple # :nodoc:
 end
 
+require "expectation"
+
+require_relative "service/errors"
 require_relative "service/action"
 require_relative "service/context"
+require_relative "service/version"
 
 # The Simple::Service module.
 #
@@ -14,76 +16,89 @@ require_relative "service/context"
 # This serves as a marker that this module is actually intended
 # to be used as a service.
 module Simple::Service
-  def self.included(klass)
+  def self.included(klass) # :nodoc:
     klass.extend ClassMethods
   end
 
-  # Returns the current context.
-  def self.context
-    Thread.current[:"Simple::Service.context"]
+  # returns true if the passed in object is a service module.
+  def self.service?(service)
+    service.is_a?(Module) && service.include?(self)
   end
 
-  # yields a block with a given context, and restores the previous context
-  # object afterwards.
-  def self.with_context(ctx, &block)
-    expect! ctx => [Simple::Service::Context, nil]
-    _ = block
+  def self.verify_service!(service) # :nodoc:
+    raise ::ArgumentError, "#{service.inspect} must be a Simple::Service, but is not even a Module" unless service.is_a?(Module)
+    raise ::ArgumentError, "#{service.inspect} must be a Simple::Service, did you 'include Simple::Service'" unless service?(service)
+  end
 
-    old_ctx = Thread.current[:"Simple::Service.context"]
-    Thread.current[:"Simple::Service.context"] = ctx
-    yield
-  ensure
-    Thread.current[:"Simple::Service.context"] = old_ctx
+  # returns a Hash with all actions in the +service+ module
+  def self.actions(service)
+    verify_service!(service)
+
+    service.__simple_service_actions__
   end
 
+  # returns the action with the given name.
   def self.action(service, name)
     actions = self.actions(service)
     actions[name] || begin
-      action_names = actions.keys.sort
-      informal = "service #{service} has these actions: #{action_names.map(&:inspect).join(", ")}"
-      raise "No such action #{name.inspect}; #{informal}"
+      raise ::Simple::Service::NoSuchAction.new(service, name)
     end
   end
 
-  def self.service?(service)
-    service.is_a?(Module) && service.include?(self)
+  # invokes an action with a given +name+ in a service with +arguments+ and +params+.
+  #
+  # You cannot call this method if the context is not set.
+  #
+  # 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.
+  #
+  # Entries in the named_args Hash that are not defined in the action itself are ignored.
+  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
 
-  def self.actions(service)
-    raise ArgumentError, "service must be a #{self}" unless service?(service)
-
-    service.__simple_service_actions__
-  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 self.invoke2(service, name, args: {}, flags: {})
+    args.each { |key, _| expect! key => Symbol }
+    raise ContextMissingError, "Need to set context before calling ::Simple::Service.invoke" unless context
 
-  def self.invoke(service, name, arguments, params, context: nil)
-    with_context(context) do
-      action(service, name).invoke(arguments, params)
-    end
+    action(service, name).invoke2(args: args, flags: flags)
   end
 
-  module ClassMethods
+  module ClassMethods # :nodoc:
     # returns a Hash of actions provided by the service module.
-    def __simple_service_actions__ # :nodoc:
+    def __simple_service_actions__
       @__simple_service_actions__ ||= Action.enumerate(service: self)
     end
   end
 
-  # Resolves a service by name. Returns nil if the name does not refer to a service,
-  # or the service module otherwise.
-  def self.resolve(str)
-    return unless str =~ /^[A-Z][A-Za-z0-9_]*(::[A-Z][A-Za-z0-9_]*)*$/
-
-    service = resolve_constant(str)
-
-    return unless service.is_a?(Module)
-    return unless service.include?(::Simple::Service)
-
-    service
-  end
-
-  def self.resolve_constant(str)
-    const_get(str)
-  rescue NameError
-    nil
-  end
+  # # Resolves a service by name. Returns nil if the name does not refer to a service,
+  # # or the service module otherwise.
+  # def self.resolve(str)
+  #   return unless str =~ /^[A-Z][A-Za-z0-9_]*(::[A-Z][A-Za-z0-9_]*)*$/
+  #
+  #   service = resolve_constant(str)
+  #
+  #   return unless service.is_a?(Module)
+  #   return unless service.include?(::Simple::Service)
+  #
+  #   service
+  # end
+  #
+  # def self.resolve_constant(str)
+  #   const_get(str)
+  # rescue NameError
+  #   nil
+  # end
 end

data/lib/simple/service/action.rb

@@ -1,8 +1,3 @@
-# rubocop:disable Metrics/CyclomaticComplexity
-# rubocop:disable Metrics/AbcSize
-# rubocop:disable Metrics/MethodLength
-# rubocop:disable Metrics/PerceivedComplexity
-
 module Simple::Service
   class Action
   end
@@ -12,11 +7,15 @@ require_relative "./action/comment"
 require_relative "./action/parameter"
 
 module Simple::Service
-  class Action
-    ArgumentError = ::Simple::Service::ArgumentError
+  # rubocop:disable Metrics/AbcSize
+  # rubocop:disable Metrics/PerceivedComplexity
+  # rubocop:disable Metrics/CyclomaticComplexity
+  # rubocop:disable Style/GuardClause
+  # rubocop:disable Metrics/ClassLength
 
-    IDENTIFIER_PATTERN = "[a-z][a-z0-9_]*"
-    IDENTIFIER_REGEXP = Regexp.compile("\\A#{IDENTIFIER_PATTERN}\\z")
+  class Action
+    IDENTIFIER_PATTERN = "[a-z][a-z0-9_]*" # :nodoc:
+    IDENTIFIER_REGEXP = Regexp.compile("\\A#{IDENTIFIER_PATTERN}\\z") # :nodoc:
 
     # determines all services provided by the +service+ service module.
     def self.enumerate(service:) # :nodoc:
@@ -28,12 +27,20 @@ module Simple::Service
     attr_reader :service
     attr_reader :name
 
+    def full_name
+      "#{service.name}##{name}"
+    end
+
+    def to_s # :nodoc:
+      full_name
+    end
+
     # returns an Array of Parameter structures.
     def parameters
       @parameters ||= Parameter.reflect_on_method(service: service, name: name)
     end
 
-    def initialize(service, name)
+    def initialize(service, name) # :nodoc:
       @service  = service
       @name     = name
 
@@ -65,129 +72,123 @@ module Simple::Service
 
     # build a service_instance and run the action, with arguments constructed from
     # args_hsh and params_hsh.
-    def invoke(args, options)
-      args   ||= {}
-      options ||= {}
-
+    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. 
-      if args.is_a?(Array)
-        args = convert_argument_array_to_hash(args)
-      end
+      # us to provide arguments as a Hash.
+      args = convert_argument_array_to_hash(args)
+      named_args = named_args.merge(args)
 
-      # [TODO] Type conversion according to default values.
-      args_ary = build_method_arguments(args, options)
+      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:)
+      verify_required_args!(args, flags)
+
+      positionals = build_positional_arguments(args, flags)
+      keywords = build_keyword_arguments(args.merge(flags))
 
       service_instance = Object.new
       service_instance.extend service
-      service_instance.public_send(@name, *args_ary)
+
+      if keywords.empty?
+        service_instance.public_send(@name, *positionals)
+      else
+        # calling this with an empty keywords Hash still raises an ArgumentError
+        # if the target method does not accept arguments.
+        service_instance.public_send(@name, *positionals, **keywords)
+      end
     end
 
     private
 
-    module IndifferentHashEx
-      def self.fetch(hsh, name)
-        missing_key!(name) unless hsh
+    # returns an error if the keywords hash does not define all required keyword arguments.
+    def verify_required_args!(args, flags) # :nodoc:
+      @required_names ||= parameters.select(&:required?).map(&:name)
 
-        hsh.fetch(name.to_sym) do
-          hsh.fetch(name.to_s) do
-            missing_key!(name)
-          end
-        end
-      end
+      missing_parameters = @required_names - args.keys - flags.keys
+      return if missing_parameters.empty?
 
-      def self.key?(hsh, name)
-        return false unless hsh
+      raise ::Simple::Service::MissingArguments.new(self, missing_parameters)
+    end
 
-        hsh.key?(name.to_sym) || hsh.key?(name.to_s)
-      end
+    # Enumerating all parameters it puts all named parameters into a Hash
+    # of keyword arguments.
+    def build_keyword_arguments(args)
+      @keyword_names ||= parameters.select(&:keyword?).map(&:name)
 
-      def self.missing_key!(name)
-        raise ArgumentError, "Missing argument in arguments hash: #{name}"
-      end
+      keys = @keyword_names & args.keys
+      values = args.fetch_values(*keys)
+
+      Hash[keys.zip(values)]
     end
 
-    I = IndifferentHashEx
+    def variadic_parameter
+      return @variadic_parameter if defined? @variadic_parameter
+
+      @variadic_parameter = parameters.detect(&:variadic?)
+    end
 
-    # returns an array of arguments suitable to be sent to the action method.
-    def build_method_arguments(args_hsh, params_hsh)
-      args = []
-      keyword_args = {}
+    def positional_names
+      @positional_names ||= parameters.select(&:positional?).map(&:name)
+    end
 
-      parameters.each do |parameter|
-        if parameter.keyword?
-          if I.key?(params_hsh, parameter.name)
-            keyword_args[parameter.name] = I.fetch(params_hsh, parameter.name)
-          end
-        else
-          if parameter.variadic?
-            if I.key?(args_hsh, parameter.name)
-              args.concat(Array(I.fetch(args_hsh, parameter.name)))
-            end
-          else
-            if !parameter.optional? || I.key?(args_hsh, parameter.name)
-              args << I.fetch(args_hsh, parameter.name)
-            end
-          end
+    # Enumerating all parameters it collects all positional parameters into
+    # an Array.
+    def build_positional_arguments(args, flags)
+      positionals = positional_names.each_with_object([]) do |parameter_name, ary|
+        if args.key?(parameter_name)
+          ary << args[parameter_name]
+        elsif flags.key?(parameter_name)
+          ary << flags[parameter_name]
         end
       end
 
-      unless keyword_args.empty?
-        args << keyword_args
+      # A variadic parameter is appended to the positionals array.
+      # It is always optional - but if it exists it must be an Array.
+      if variadic_parameter
+        value = if args.key?(variadic_parameter.name)
+                  args[variadic_parameter.name]
+                elsif flags.key?(variadic_parameter.name)
+                  flags[variadic_parameter.name]
+                end
+
+        positionals.concat(value) if value
       end
 
-      args
+      positionals
     end
 
     def convert_argument_array_to_hash(ary)
-      # enumerate all of the action's anonymous arguments, trying to match them
-      # against the values in +ary+. If afterwards any arguments are still left
-      # in +ary+ they will be assigned to the variadic arguments array, which
-      # - if a variadic parameter is defined in this action - will be added to
-      # the hash as well.
+      expect! ary => Array
+
       hsh = {}
-      variadic_parameter_name = nil
 
-      parameters.each do |parameter|
-        next if parameter.keyword?
-        parameter_name = parameter.name
+      if variadic_parameter
+        hsh[variadic_parameter.name] = []
+      end
 
-        if parameter.variadic?
-          variadic_parameter_name = parameter_name
-          next
-        end
+      if ary.length > positional_names.length
+        extra_arguments = ary[positional_names.length..-1]
 
-        if ary.empty? && !parameter.optional?
-          raise ::Simple::Service::ArgumentError, "Missing #{parameter_name} parameter"
+        if variadic_parameter
+          hsh[variadic_parameter.name] = extra_arguments
+        else
+          raise ::Simple::Service::ExtraArguments.new(self, extra_arguments)
         end
-
-        next if ary.empty?
-
-        hsh[parameter_name] = ary.shift
       end
 
-      # Any arguments are left? Set variadic parameter, if defined, raise an error otherwise.
-      unless ary.empty?
-        unless variadic_parameter_name
-          raise ::Simple::Service::ArgumentError, "Extra parameters: #{ary.map(&:inspect).join(", ")}"
-        end
-
-        hsh[variadic_parameter_name] = ary
+      ary.zip(positional_names).each do |value, parameter_name|
+        hsh[parameter_name] = value
       end
 
       hsh
     end
-
-    def full_name
-      "#{service}##{name}"
-    end
-
-    def to_s
-      full_name
-    end
   end
 end