RubyGems - simple-service - Versions diffs - 0.1.1 → 0.1.6 - Mend

simple-service 0.1.1 → 0.1.6

Files changed (59) hide show

checksums.yaml +4 -4
data/.gitignore +2 -2
data/.rubocop.yml +7 -0
data/.tm_properties +1 -1
data/Makefile +8 -0
data/README.md +68 -1
data/TODO.txt +3 -0
data/VERSION +1 -1
data/doc/Simple.html +117 -0
data/doc/Simple/Service.html +865 -0
data/doc/Simple/Service/Action.html +923 -0
data/doc/Simple/Service/Action/Comment.html +451 -0
data/doc/Simple/Service/Action/Comment/Extractor.html +347 -0
data/doc/Simple/Service/Action/MethodReflection.html +285 -0
data/doc/Simple/Service/Action/Parameter.html +816 -0
data/doc/Simple/Service/ArgumentError.html +128 -0
data/doc/Simple/Service/ClassMethods.html +187 -0
data/doc/Simple/Service/Context.html +379 -0
data/doc/Simple/Service/ContextMissingError.html +124 -0
data/doc/Simple/Service/ContextReadOnlyError.html +206 -0
data/doc/Simple/Service/ExtraArguments.html +428 -0
data/doc/Simple/Service/GemHelper.html +190 -0
data/doc/Simple/Service/MissingArguments.html +426 -0
data/doc/Simple/Service/NoSuchAction.html +433 -0
data/doc/_index.html +274 -0
data/doc/class_list.html +51 -0
data/doc/css/common.css +1 -0
data/doc/css/full_list.css +58 -0
data/doc/css/style.css +496 -0
data/doc/file.README.html +146 -0
data/doc/file.TODO.html +70 -0
data/doc/file_list.html +61 -0
data/doc/frames.html +17 -0
data/doc/index.html +146 -0
data/doc/js/app.js +303 -0
data/doc/js/full_list.js +216 -0
data/doc/js/jquery.js +4 -0
data/doc/method_list.html +483 -0
data/doc/top-level-namespace.html +110 -0
data/lib/simple/service.rb +161 -56
data/lib/simple/service/action.rb +104 -107
data/lib/simple/service/action/comment.rb +3 -1
data/lib/simple/service/action/method_reflection.rb +3 -3
data/lib/simple/service/action/parameter.rb +3 -7
data/lib/simple/service/context.rb +69 -27
data/lib/simple/service/errors.rb +54 -0
data/lib/simple/service/version.rb +7 -2
data/scripts/stats +2 -1
data/spec/simple/service/action_invoke3_spec.rb +266 -0
data/spec/simple/service/action_invoke_spec.rb +237 -0
data/spec/simple/service/action_spec.rb +51 -0
data/spec/simple/service/context_spec.rb +39 -7
data/spec/simple/service/service_spec.rb +158 -0
data/spec/simple/service/version_spec.rb +7 -0
data/spec/spec_helper.rb +15 -2
data/spec/support/spec_services.rb +58 -0
metadata +48 -6
data/lib/simple.rb +0 -2
data/spec/support/004_simplecov.rb +0 -13

data/doc/top-level-namespace.html ADDED Viewed

@@ -0,0 +1,110 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Top Level Namespace
+    &mdash; Documentation by YARD 0.9.20
+</title>
+  <link rel="stylesheet" href="css/style.css" type="text/css" charset="utf-8" />
+  <link rel="stylesheet" href="css/common.css" type="text/css" charset="utf-8" />
+<script type="text/javascript" charset="utf-8">
+  pathId = "";
+  relpath = '';
+</script>
+  <script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
+  <script type="text/javascript" charset="utf-8" src="js/app.js"></script>
+  </head>
+  <body>
+    <div class="nav_wrap">
+      <iframe id="nav" src="class_list.html?1"></iframe>
+      <div id="resizer"></div>
+    </div>
+    <div id="main" tabindex="-1">
+      <div id="header">
+        <div id="menu">
+    <a href="_index.html">Index</a> &raquo;
+    <span class="title">Top Level Namespace</span>
+</div>
+        <div id="search">
+    <a class="full_list_link" id="class_list_link"
+        href="class_list.html">
+        <svg width="24" height="24">
+          <rect x="0" y="4" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="12" width="24" height="4" rx="1" ry="1"></rect>
+          <rect x="0" y="20" width="24" height="4" rx="1" ry="1"></rect>
+        </svg>
+    </a>
+</div>
+        <div class="clear"></div>
+      </div>
+      <div id="content"><h1>Top Level Namespace
+</h1>
+<div class="box_info">
+</div>
+<h2>Defined Under Namespace</h2>
+<p class="children">
+      <strong class="modules">Modules:</strong> <span class='object_link'><a href="Simple.html" title="Simple (module)">Simple</a></span>
+</p>
+</div>
+      <div id="footer">
+  Generated on Wed Dec  4 22:57:12 2019 by
+  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
+  0.9.20 (ruby-2.5.1).
+</div>
+    </div>
+  </body>
+</html>

data/lib/simple/service.rb CHANGED Viewed

@@ -1,89 +1,194 @@
-module Simple::Service
-  class ArgumentError < ::ArgumentError
-  end
+module Simple # @private
 end
+require "expectation"
+require "logger"
+require_relative "service/errors"
 require_relative "service/action"
 require_relative "service/context"
+require_relative "service/version"
-# The Simple::Service module.
+# <b>The Simple::Service interface</b>
+#
+# This module implements the main API of the Simple::Service ruby gem.
+#
+# 1. <em>Marking a service module:</em> To turn a target module as a service module one must include <tt>Simple::Service</tt>
+#    into the target. This serves as a marker that this module is actually intended
+#    to provide one or more services. Example:
+#
+#     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
+#
+# 2. <em>Discover services:</em> To discover services in a service module use the #actions method. This returns a Hash
+#    of actions.
 #
-# To mark a target module as a service module one must include the
-# Simple::Service module into the target module.
+#     Simple::Service.actions(GodMode)
+#     => {:build_universe=>#<Simple::Service::Action...>, ...}
+#
+# TODO: why a Hash? It feels much better if Simple::Service.actions returns an array of names.
+#
+#
+# 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.invoke3(GodMode, :build_universe, "TestWorld", c: 1e9)
+#     end
+#     => 42
 #
-# This serves as a marker that this module is actually intended
-# to be used as a service.
 module Simple::Service
-  def self.included(klass)
-    klass.extend ClassMethods
+  module ServiceExpectations
+    def expect!(*args, &block)
+      Expectation.expect!(*args, &block)
+    rescue ::Expectation::Error => e
+      raise ArgumentError, e.to_s
+    end
   end
-  # Returns the current context.
-  def self.context
-    Thread.current[:"Simple::Service.context"]
+  def self.included(klass) # @private
+    klass.extend ClassMethods
+    klass.include ServiceExpectations
   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
-    old_ctx = Thread.current[:"Simple::Service.context"]
-    Thread.current[:"Simple::Service.context"] = ctx
-    yield
-  ensure
-    Thread.current[:"Simple::Service.context"] = old_ctx
+  def self.logger
+    @logger ||= ::Logger.new(STDOUT)
   end
-  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}"
-    end
+  def self.logger=(logger)
+    @logger = logger
   end
+  # returns true if the passed in object is a service module.
+  #
+  # A service must be a module, and it must include the Simple::Service module.
   def self.service?(service)
-    service.is_a?(Module) && service.include?(self)
+    verify_service! service
+    true
+  rescue ::ArgumentError
+    false
   end
+  # Raises an error if the passed in object is not a service
+  def self.verify_service!(service) # @private
+    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.include?(self)
+  end
+  # returns a Hash with all actions in the +service+ module
   def self.actions(service)
-    raise ArgumentError, "service must be a #{self}" unless service?(service)
+    verify_service!(service)
     service.__simple_service_actions__
   end
-  def self.invoke(service, name, arguments, params, context: nil)
-    with_context(context) do
-      action(service, name).invoke(arguments, params)
+  # returns the action with the given name.
+  def self.action(service, name)
+    actions = self.actions(service)
+    actions[name] || begin
+      raise ::Simple::Service::NoSuchAction.new(service, name)
     end
   end
-  module ClassMethods
-    # returns a Hash of actions provided by the service module.
-    def __simple_service_actions__ # :nodoc:
-      @__simple_service_actions__ ||= Action.enumerate(service: self)
-    end
+  # 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
-  # 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
+  # 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.
+  #
+  # Note that the keys in both the +flags+ and the +args+ Hash must be strings.
+  #
+  # The service is being called with a parameters built out of those like this:
+  #
+  # - 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.
+  #
+  # 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.
+  # <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
+    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).invoke(args: args, flags: flags)
   end
-  def self.resolve_constant(str)
-    const_get(str)
-  rescue NameError
-    nil
+  module ClassMethods # @private
+    # returns a Hash of actions provided by the service module.
+    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
 end

data/lib/simple/service/action.rb CHANGED Viewed

@@ -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,14 +7,17 @@ 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 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_]*" # @private
+    IDENTIFIER_REGEXP = Regexp.compile("\\A#{IDENTIFIER_PATTERN}\\z") # @private
     # determines all services provided by the +service+ service module.
-    def self.enumerate(service:) # :nodoc:
+    def self.enumerate(service:) # @private
       service.public_instance_methods(false)
              .grep(IDENTIFIER_REGEXP)
              .each_with_object({}) { |name, hsh| hsh[name] = Action.new(service, name) }
@@ -28,12 +26,20 @@ module Simple::Service
     attr_reader :service
     attr_reader :name
+    def full_name
+      "#{service.name}##{name}"
+    end
+    def to_s # @private
+      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) # @private
       @service  = service
       @name     = name
@@ -63,131 +69,122 @@ 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, options)
-      args   ||= {}
-      options ||= {}
-      # 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
+    # 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 invoke(args:, flags:)
+      args = convert_argument_array_to_hash(args) if args.is_a?(Array)
+      verify_required_args!(args, flags)
-      # [TODO] Type conversion according to default values.
-      args_ary = build_method_arguments(args, options)
+      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) # @private
+      @required_names ||= parameters.select(&:required?).map(&:name).map(&:to_s)
-        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).map(&:to_s)
-      def self.missing_key!(name)
-        raise ArgumentError, "Missing argument in arguments hash: #{name}"
-      end
-    end
+      keys = @keyword_names & args.keys
+      values = args.fetch_values(*keys)
-    I = IndifferentHashEx
-    # returns an array of arguments suitable to be sent to the action method.
-    def build_method_arguments(args_hsh, params_hsh)
-      args = []
-      keyword_args = {}
-      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
-        end
-      end
+      # Note that +keys+ now only contains names of keyword arguments that actually exist.
+      # This is therefore not a way to DOS this process.
+      Hash[keys.map(&:to_sym).zip(values)]
+    end
-      unless keyword_args.empty?
-        args << keyword_args
-      end
+    def variadic_parameter
+      return @variadic_parameter if defined? @variadic_parameter
-      args
+      @variadic_parameter = parameters.detect(&:variadic?)
     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.
-      hsh = {}
-      variadic_parameter_name = nil
-      parameters.each do |parameter|
-        next if parameter.keyword?
-        parameter_name = parameter.name
-        if parameter.variadic?
-          variadic_parameter_name = parameter_name
-          next
-        end
+    def positional_names
+      @positional_names ||= parameters.select(&:positional?).map(&:name).map(&:to_s)
+    end
-        if ary.empty? && !parameter.optional?
-          raise ::Simple::Service::ArgumentError, "Missing #{parameter_name} parameter"
+    # 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
-        next if ary.empty?
+      # 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
-        hsh[parameter_name] = ary.shift
+        positionals.concat(value) if value
       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(", ")}"
+      positionals
+    end
+    def convert_argument_array_to_hash(ary)
+      expect! ary => Array
+      # +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 !extra_arguments.empty? && !variadic_parameter
+          raise ::Simple::Service::ExtraArguments.new(self, extra_arguments)
         end
-        hsh[variadic_parameter_name] = ary
+        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
-      hsh
-    end
+      # Build a hash with the existing_positional_names and the values from the array.
+      hsh = Hash[existing_positional_names.zip(ary)]
-    def full_name
-      "#{service}##{name}"
-    end
+      # Add the variadic_parameter, if any.
+      hsh[variadic_parameter.name] = extra_arguments if variadic_parameter
-    def to_s
-      full_name
+      hsh
     end
   end
 end