RubyGems - simple-service - Versions diffs - 0.1.5 - Mend

simple-service 0.1.5

Files changed (68) hide show

checksums.yaml +7 -0
data/.gitignore +12 -0
data/.rubocop.yml +100 -0
data/.tm_properties +1 -0
data/Gemfile +14 -0
data/Makefile +9 -0
data/README.md +68 -0
data/Rakefile +6 -0
data/VERSION +1 -0
data/bin/bundle +105 -0
data/bin/console +15 -0
data/bin/rake +29 -0
data/bin/rspec +29 -0
data/doc/Simple.html +117 -0
data/doc/Simple/Service.html +863 -0
data/doc/Simple/Service/Action.html +1014 -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/IndieHash.html +506 -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 +286 -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_list.html +56 -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 +539 -0
data/doc/top-level-namespace.html +110 -0
data/lib/simple-service.rb +3 -0
data/lib/simple/service.rb +173 -0
data/lib/simple/service/action.rb +190 -0
data/lib/simple/service/action/comment.rb +57 -0
data/lib/simple/service/action/method_reflection.rb +70 -0
data/lib/simple/service/action/parameter.rb +42 -0
data/lib/simple/service/context.rb +94 -0
data/lib/simple/service/errors.rb +54 -0
data/lib/simple/service/version.rb +29 -0
data/log/.gitkeep +0 -0
data/scripts/release +2 -0
data/scripts/release.rb +91 -0
data/scripts/stats +5 -0
data/scripts/watch +2 -0
data/simple-service.gemspec +25 -0
data/spec/simple/service/action_invoke3_spec.rb +266 -0
data/spec/simple/service/action_invoke_spec.rb +166 -0
data/spec/simple/service/action_spec.rb +51 -0
data/spec/simple/service/context_spec.rb +69 -0
data/spec/simple/service/service_spec.rb +156 -0
data/spec/simple/service/version_spec.rb +7 -0
data/spec/spec_helper.rb +38 -0
data/spec/support/spec_services.rb +58 -0
metadata +129 -0

@@ -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 Tue Dec  3 13:46:26 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 ADDED

@@ -0,0 +1,3 @@
+# rubocop:disable Naming/FileName
+require "simple/service"

data/lib/simple/service.rb ADDED

@@ -0,0 +1,173 @@
+module Simple # @private
+end
+require "expectation"
+require_relative "service/errors"
+require_relative "service/action"
+require_relative "service/context"
+require_relative "service/version"
+# <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. [TODO] why a Hash?
+#
+#     Simple::Service.actions(GodMode)
+#     => {:build_universe=>#<Simple::Service::Action...>, ...}
+#
+# 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
+#
+module Simple::Service
+  def self.included(klass) # @private
+    klass.extend ClassMethods
+  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)
+    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)
+    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
+      raise ::Simple::Service::NoSuchAction.new(service, name)
+    end
+  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
+  # 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
+  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 ADDED

@@ -0,0 +1,190 @@
+module Simple::Service
+  class Action
+  end
+end
+require_relative "./action/comment"
+require_relative "./action/parameter"
+module Simple::Service
+  # rubocop:disable Metrics/AbcSize
+  # rubocop:disable Metrics/PerceivedComplexity
+  # rubocop:disable Metrics/CyclomaticComplexity
+  # rubocop:disable Metrics/ClassLength
+  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:) # @private
+      service.public_instance_methods(false)
+             .grep(IDENTIFIER_REGEXP)
+             .each_with_object({}) { |name, hsh| hsh[name] = Action.new(service, name) }
+    end
+    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) # @private
+      @service  = service
+      @name     = name
+      parameters
+    end
+    def short_description
+      comment.short
+    end
+    def full_description
+      comment.full
+    end
+    private
+    # returns a Comment object
+    #
+    # The comment object is extracted on demand on the first call.
+    def comment
+      @comment ||= Comment.extract(action: self)
+    end
+    public
+    def source_location
+      @service.instance_method(name).source_location
+    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)
+      positionals = build_positional_arguments(args, flags)
+      keywords = build_keyword_arguments(args.merge(flags))
+      service_instance = Object.new
+      service_instance.extend service
+      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
+    # 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)
+      missing_parameters = @required_names - args.keys - flags.keys
+      return if missing_parameters.empty?
+      raise ::Simple::Service::MissingArguments.new(self, missing_parameters)
+    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)
+      keys = @keyword_names & args.keys
+      values = args.fetch_values(*keys)
+      # 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
+    def variadic_parameter
+      return @variadic_parameter if defined? @variadic_parameter
+      @variadic_parameter = parameters.detect(&:variadic?)
+    end
+    def positional_names
+      @positional_names ||= parameters.select(&:positional?).map(&:name).map(&:to_s)
+    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
+      # 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
+      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
+        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
+end