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

simple-service 0.1.5

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 (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

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

@@ -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