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

simple-service 0.1.1 → 0.1.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

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