RubyGems - simple-service - Versions diffs - 0.1.4 - Mend

simple-service 0.1.4

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 (69) 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 +143 -0
data/lib/simple/service/action.rb +203 -0
data/lib/simple/service/action/comment.rb +57 -0
data/lib/simple/service/action/indie_hash.rb +37 -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_invoke2_spec.rb +166 -0
data/spec/simple/service/action_invoke_spec.rb +266 -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 +105 -0
data/spec/simple/service/version_spec.rb +7 -0
data/spec/spec_helper.rb +38 -0
data/spec/support/spec_services.rb +50 -0
metadata +130 -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,143 @@
+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.invoke</tt> or <tt>Simple::Service.invoke2</tt>. You must set a context first.
+#
+#     Simple::Service.with_context do
+#       Simple::Service.invoke(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 +arguments+ and +params+.
+  #
+  # When calling +invoke+ using positional arguments (i.e. non-keyword arguments)
+  # they will be matched against positional arguments of the invoked method -
+  # but they will not be matched against named arguments.
+  #
+  # In other words: if the service implements an action "def foo(bar, baz:)", one can
+  # run it via
+  #
+  # - +Service.invoke("bar-value", baz: "baz-value")+, or via
+  # - +Service.invoke(bar: "bar-value", baz: "baz-value")+
+  #
+  # 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.
+  #
+  # *Note:* You cannot call this method if the context is not set.
+  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
+  # 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: {})
+    raise ContextMissingError, "Need to set context before calling ::Simple::Service.invoke" unless context
+    action(service, name).invoke2(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,203 @@
+module Simple::Service
+  class Action
+  end
+end
+require_relative "./action/comment"
+require_relative "./action/parameter"
+require_relative "./action/indie_hash"
+module Simple::Service
+  # rubocop:disable Metrics/AbcSize
+  # rubocop:disable Metrics/PerceivedComplexity
+  # rubocop:disable Metrics/CyclomaticComplexity
+  # rubocop:disable Style/GuardClause
+  # 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
+    # build a service_instance and run the action, with arguments constructed from
+    # args_hsh and params_hsh.
+    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.
+      args = convert_argument_array_to_hash(args)
+      named_args = named_args.merge(args)
+      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:)
+      # args and flags are being stringified. This is necessary to not allow any
+      # unchecked input to DOS this process by just providing always changing
+      # key values.
+      args = IndieHash.new(args)
+      flags = IndieHash.new(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
+      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)
+    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
+      hsh = {}
+      if variadic_parameter
+        hsh[variadic_parameter.name] = []
+      end
+      if ary.length > positional_names.length
+        extra_arguments = ary[positional_names.length..-1]
+        if variadic_parameter
+          hsh[variadic_parameter.name] = extra_arguments
+        else
+          raise ::Simple::Service::ExtraArguments.new(self, extra_arguments)
+        end
+      end
+      ary.zip(positional_names).each do |value, parameter_name|
+        hsh[parameter_name] = value
+      end
+      hsh
+    end
+  end
+end