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

simple-service 0.1.4

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

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