simple-service 0.1.3 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5300b67f8c93b974d4ae19f285aa80915b195f8c5483c340b1716ecf2b41f969
-  data.tar.gz: 4272fc5ea6add6f0bb774c7faee8d2abe00ad0f1bda1056b80cc3a57a9ab6df5
+  metadata.gz: 706a23842071b121c2b6298b7bdaec0b43c4b110125c2c09011537541c4f5b9b
+  data.tar.gz: 9ad938ece973392233c554053aa1906da0ea799722d527cb15870913ef108070
 SHA512:
-  metadata.gz: 83233c349d6a144183f0ca2a18993712a4902dcc65934a63dcc7cfed370ffc1ddcdfa7754a1ffff85f11c8875007de7843f8c5d7fd8d6f7eb799dd14c1e3b373
-  data.tar.gz: '0268ef5da51bcca27e9a3a1766f9ede7d67a8213cf52b97206d000836012cd7c3220511098dad734c316fa3a068f3e853301ffaf8b8dac73712b3f3757dd674b'
+  metadata.gz: 68563b2c8d9c955049814f90d31b765a30c077553d7199287c4d0117d7d1ed0eb2ce71674195820d482de52bd2f53c70dbb798549d2bf6a7c35ef2f149de3b56
+  data.tar.gz: ccb9fc69a58b3a9f7225e60e1b8120dced8ec58802483ee4151cb6a0fc71c20b5b3f9b4393b6b9c09de2ec18d3c09bfbdac16f341669ac055b3daa9b31b98ae0

data/.gitignore

@@ -1,5 +1,4 @@
 coverage
-rdoc
 pkg
 log/*.log
 .rspec.data
@@ -9,4 +8,5 @@ Gemfile.lock
 .DS_Store
 tmp
 .byebug_history
-.bundle/config
+.bundle/config
+.yardoc

data/.rubocop.yml

@@ -1,5 +1,6 @@
 AllCops:
-  TargetRubyVersion: 2.3
+  NewCops: enable
+  TargetRubyVersion: 2.7
   Exclude:
     - 'spec/**/*'
     - 'test/**/*'
@@ -14,7 +15,7 @@ Metrics/BlockLength:
   Exclude:
     - 'spec/**/*'
 
-Metrics/LineLength:
+Layout/LineLength:
   Max: 140
 
 Metrics/MethodLength:
@@ -98,3 +99,10 @@ Style/DoubleNegation:
 
 Style/ParallelAssignment:
   Enabled: false
+
+Style/CommentedKeyword:
+  Enabled: false
+
+Style/AccessorGrouping:
+  Enabled: false
+  

data/Gemfile

@@ -10,5 +10,7 @@ group :development, :test do
   gem 'rspec', '~> 3.7'
   # gem 'rubocop', '~> 0.61.1'
   gem 'simplecov', '~> 0'
-  gem 'byebug'
+  gem 'pry-byebug'
 end
+
+# gem "simple-immutable", "~> 1", path: "../simple-immutable"

data/Makefile

@@ -3,14 +3,10 @@
 test:
 	rspec
 
-.PHONY: doc doc/rdoc
-doc: doc/rdoc
-	
-doc/rdoc:
-	rm -rf doc/rdoc
-	rdoc -o doc/rdoc README.md \
-		lib/simple/service.rb \
-		lib/simple/service/action.rb \
-		lib/simple/service/context.rb \
-		lib/simple/service/errors.rb \
-		lib/simple/service/version.rb 
+.PHONY: doc
+doc: todo
+	rm -rf doc/*
+	yard doc -o doc - TODO.txt
+
+todo:
+	lentil . -f comp | tee TODO.txt

data/README.md

@@ -1,3 +1,68 @@
-# simple-service – a pretty simple and somewhat abstract service description
+# simple-service – at your service!
 
-Yea, that's it.
+The `simple-service` ruby gem helps you turn your ruby source code into *"services".* A service is a module which provides interfaces to one or more methods (*"actions"*) that implement business logic.
+
+While one could, of course, call any such method any way one wants, this gem lets you
+
+- discover available services (their names, their parameters (name, type, default values), comments - see `Simple::Service.actions`;
+- an interface to "run" (or "execute") a service, with separation from any other parallel runs - see `Simple::Service.invoke` and `Simple::Service.invoke2`;
+- a semi-constant "*environment*" for the duration of an execution;
+- ![TODO](https://badgen.net/badge/TODO/high?color=red) a normalized interface to check whether or not a specific service is allowed to run based on the current context.
+
+These features allow *simple-service* to serve as a building block for other tools. It is currently in used in:
+
+- *simple-httpd*: a simple web server
+- *simple-cli*: the best way to build a ruby CLI.
+
+## Example
+
+### Defining a service
+
+A service module can define one or more services. The following example defines a single service:
+
+    # A service which constructs universes with different physics.
+    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
+
+### Running a service
+
+To run the service one uses one of two different methods. If you have an **anonymous array** of arguments - think command line interface - you would call it like this:
+
+    Simple::Service.invoke GodMode, :build_universe, 
+                           "My Universe", 
+                           c: 3e8
+
+If the calling site, however, has **named arguments** (in a Hash), one would invoke a service using `invoke2`. This is used for HTTPD integration (with `simple-httpd`.)
+
+      args = { name:  "My Universe", c: 299792458}
+      Simple::Service.invoke2 GodMode, 
+                              :build_universe, 
+                              args: args
+
+Note that you must set a context during the execution; this is done by `with_context`. A  `nil` context is a valid value which describes an empty context.
+
+A full example could therefore look like:
+
+    Simple::Service.with_context(nil) do
+        args = { name:  "My Universe", c: 299792458}
+        Simple::Service.invoke2 GodMode, 
+                                :build_universe,
+                                args: args
+    end
+
+## History
+
+Historically, the `simple-cli` gem implemented an easy way to build a CLI application, and therefore needed a way to reflect on existing code to determine which methods to call, which arguments they support etc. Also, the `postjob` job queue calls a specific method based on its name and an arguments Array or Hash, which is being read from a database. Finally, when I tried to extent `postjob` with a HTTP interface I discovered that a similar feature would again be extremely useful.
+
+I therefore extracted these features into a standalone gem.

data/TODO.txt

@@ -0,0 +1,3 @@
+lib/simple/service.rb:39:
+   why a Hash? It feels much better if Simple::Service.actions returns an array of names. 
+

data/VERSION

@@ -1 +1 @@
-0.1.3
+0.2.0

data/doc/Simple/Service/Action/Comment/Extractor.html

@@ -0,0 +1,347 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>
+  Module: Simple::Service::Action::Comment::Extractor
+  
+    &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 = "Simple::Service::Action::Comment::Extractor";
+  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 (E)</a> &raquo;
+    <span class='title'><span class='object_link'><a href="../../../../Simple.html" title="Simple (module)">Simple</a></span></span> &raquo; <span class='title'><span class='object_link'><a href="../../../Service.html" title="Simple::Service (module)">Service</a></span></span> &raquo; <span class='title'><span class='object_link'><a href="../../Action.html" title="Simple::Service::Action (class)">Action</a></span></span> &raquo; <span class='title'><span class='object_link'><a href="../Comment.html" title="Simple::Service::Action::Comment (class)">Comment</a></span></span>
+     &raquo; 
+    <span class="title">Extractor</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>Module: Simple::Service::Action::Comment::Extractor
+  
+  
+  
+</h1>
+<div class="box_info">
+  
+
+  
+  
+  <dl>
+      <dt>Extended by:</dt>
+      <dd><span class='object_link'><a href="" title="Simple::Service::Action::Comment::Extractor (module)">Extractor</a></span></dd>
+  </dl>
+  
+  
+  
+  
+
+  
+  <dl>
+    <dt>Included in:</dt>
+    <dd><span class='object_link'><a href="" title="Simple::Service::Action::Comment::Extractor (module)">Extractor</a></span></dd>
+  </dl>
+  
+
+  
+  <dl>
+    <dt>Defined in:</dt>
+    <dd>lib/simple/service/action/comment.rb</dd>
+  </dl>
+  
+</div>
+
+
+
+
+
+
+
+
+  
+    <h2>
+      Instance Method Summary
+      <small><a href="#" class="summary_toggle">collapse</a></small>
+    </h2>
+
+    <ul class="summary">
+      
+        <li class="public ">
+  <span class="summary_signature">
+    
+      <a href="#_parse_source-instance_method" title="#_parse_source (instance method)">#<strong>_parse_source</strong>(file)  &#x21d2; Object </a>
+    
+
+    
+  </span>
+  
+  
+  
+  
+  
+  
+  
+
+  
+    <span class="summary_desc"><div class='inline'></div></span>
+  
+</li>
+
+      
+        <li class="public ">
+  <span class="summary_signature">
+    
+      <a href="#extract_comment_lines-instance_method" title="#extract_comment_lines (instance method)">#<strong>extract_comment_lines</strong>(file:, before_line:)  &#x21d2; Object </a>
+    
+
+    
+  </span>
+  
+  
+  
+  
+  
+  
+  
+
+  
+    <span class="summary_desc"><div class='inline'></div></span>
+  
+</li>
+
+      
+        <li class="public ">
+  <span class="summary_signature">
+    
+      <a href="#parse_source-instance_method" title="#parse_source (instance method)">#<strong>parse_source</strong>(file)  &#x21d2; Object </a>
+    
+
+    
+  </span>
+  
+  
+  
+  
+  
+  
+  
+
+  
+    <span class="summary_desc"><div class='inline'>
+<p>reads the source a file and turns each non-comment into :code and each comment into a string without the leading comment markup.</p>
+</div></span>
+  
+</li>
+
+      
+    </ul>
+  
+
+
+
+  <div id="instance_method_details" class="method_details_list">
+    <h2>Instance Method Details</h2>
+
+    
+      <div class="method_details first">
+  <h3 class="signature first" id="_parse_source-instance_method">
+  
+    #<strong>_parse_source</strong>(file)  &#x21d2; <tt>Object</tt> 
+  
+
+  
+
+  
+</h3><table class="source_code">
+  <tr>
+    <td>
+      <pre class="lines">
+
+
+27
+28
+29
+30
+31
+32
+33
+34</pre>
+    </td>
+    <td>
+      <pre class="code"><span class="info file"># File 'lib/simple/service/action/comment.rb', line 27</span>
+
+<span class='kw'>def</span> <span class='id identifier rubyid__parse_source'>_parse_source</span><span class='lparen'>(</span><span class='id identifier rubyid_file'>file</span><span class='rparen'>)</span>
+  <span class='const'>File</span><span class='period'>.</span><span class='id identifier rubyid_readlines'>readlines</span><span class='lparen'>(</span><span class='id identifier rubyid_file'>file</span><span class='rparen'>)</span><span class='period'>.</span><span class='id identifier rubyid_map'>map</span> <span class='kw'>do</span> <span class='op'>|</span><span class='id identifier rubyid_line'>line</span><span class='op'>|</span>
+    <span class='kw'>case</span> <span class='id identifier rubyid_line'>line</span>
+    <span class='kw'>when</span> <span class='tstring'><span class='regexp_beg'>/</span><span class='tstring_content'>^\s*# ?(.*)$</span><span class='regexp_end'>/</span></span> <span class='kw'>then</span> <span class='backref'>$1</span>
+    <span class='kw'>when</span> <span class='tstring'><span class='regexp_beg'>/</span><span class='tstring_content'>^\s*end</span><span class='regexp_end'>/</span></span> <span class='kw'>then</span> <span class='symbol'>:end</span>
+    <span class='kw'>end</span>
+  <span class='kw'>end</span>
+<span class='kw'>end</span></pre>
+    </td>
+  </tr>
+</table>
+</div>
+    
+      <div class="method_details ">
+  <h3 class="signature " id="extract_comment_lines-instance_method">
+  
+    #<strong>extract_comment_lines</strong>(file:, before_line:)  &#x21d2; <tt>Object</tt> 
+  
+
+  
+
+  
+</h3><table class="source_code">
+  <tr>
+    <td>
+      <pre class="lines">
+
+
+36
+37
+38
+39
+40
+41
+42
+43
+44
+45
+46
+47
+48
+49
+50
+51
+52
+53
+54
+55</pre>
+    </td>
+    <td>
+      <pre class="code"><span class="info file"># File 'lib/simple/service/action/comment.rb', line 36</span>
+
+<span class='kw'>def</span> <span class='id identifier rubyid_extract_comment_lines'>extract_comment_lines</span><span class='lparen'>(</span><span class='label'>file:</span><span class='comma'>,</span> <span class='label'>before_line:</span><span class='rparen'>)</span>
+  <span class='id identifier rubyid_parsed_source'>parsed_source</span> <span class='op'>=</span> <span class='id identifier rubyid_parse_source'>parse_source</span><span class='lparen'>(</span><span class='id identifier rubyid_file'>file</span><span class='rparen'>)</span>
+
+  <span class='comment'># go down from before_line until we see a line which is either a comment
+</span>  <span class='comment'># or an :end. Note that the line at before_line-1 should be the first
+</span>  <span class='comment'># line of the method definition in question.
+</span>  <span class='id identifier rubyid_last_line'>last_line</span> <span class='op'>=</span> <span class='id identifier rubyid_before_line'>before_line</span> <span class='op'>-</span> <span class='int'>1</span>
+  <span class='id identifier rubyid_last_line'>last_line</span> <span class='op'>-=</span> <span class='int'>1</span> <span class='kw'>while</span> <span class='id identifier rubyid_last_line'>last_line</span> <span class='op'>&gt;=</span> <span class='int'>0</span> <span class='op'>&amp;&amp;</span> <span class='op'>!</span><span class='id identifier rubyid_parsed_source'>parsed_source</span><span class='lbracket'>[</span><span class='id identifier rubyid_last_line'>last_line</span><span class='rbracket'>]</span>
+
+  <span class='id identifier rubyid_first_line'>first_line</span> <span class='op'>=</span> <span class='id identifier rubyid_last_line'>last_line</span>
+  <span class='id identifier rubyid_first_line'>first_line</span> <span class='op'>-=</span> <span class='int'>1</span> <span class='kw'>while</span> <span class='id identifier rubyid_first_line'>first_line</span> <span class='op'>&gt;=</span> <span class='int'>0</span> <span class='op'>&amp;&amp;</span> <span class='id identifier rubyid_parsed_source'>parsed_source</span><span class='lbracket'>[</span><span class='id identifier rubyid_first_line'>first_line</span><span class='rbracket'>]</span>
+  <span class='id identifier rubyid_first_line'>first_line</span> <span class='op'>+=</span> <span class='int'>1</span>
+
+  <span class='id identifier rubyid_comments'>comments</span> <span class='op'>=</span> <span class='id identifier rubyid_parsed_source'>parsed_source</span><span class='lbracket'>[</span><span class='id identifier rubyid_first_line'>first_line</span><span class='op'>..</span><span class='id identifier rubyid_last_line'>last_line</span><span class='rbracket'>]</span>
+  <span class='kw'>if</span> <span class='id identifier rubyid_comments'>comments</span><span class='period'>.</span><span class='id identifier rubyid_include?'>include?</span><span class='lparen'>(</span><span class='symbol'>:end</span><span class='rparen'>)</span>
+    <span class='lbracket'>[</span><span class='rbracket'>]</span>
+  <span class='kw'>else</span>
+    <span class='id identifier rubyid_parsed_source'>parsed_source</span><span class='lbracket'>[</span><span class='id identifier rubyid_first_line'>first_line</span><span class='op'>..</span><span class='id identifier rubyid_last_line'>last_line</span><span class='rbracket'>]</span>
+  <span class='kw'>end</span>
+<span class='kw'>end</span></pre>
+    </td>
+  </tr>
+</table>
+</div>
+    
+      <div class="method_details ">
+  <h3 class="signature " id="parse_source-instance_method">
+  
+    #<strong>parse_source</strong>(file)  &#x21d2; <tt>Object</tt> 
+  
+
+  
+
+  
+</h3><div class="docstring">
+  <div class="discussion">
+    
+<p>reads the source a file and turns each non-comment into :code and each comment into a string without the leading comment markup.</p>
+
+
+  </div>
+</div>
+<div class="tags">
+  
+
+</div><table class="source_code">
+  <tr>
+    <td>
+      <pre class="lines">
+
+
+22
+23
+24
+25</pre>
+    </td>
+    <td>
+      <pre class="code"><span class="info file"># File 'lib/simple/service/action/comment.rb', line 22</span>
+
+<span class='kw'>def</span> <span class='id identifier rubyid_parse_source'>parse_source</span><span class='lparen'>(</span><span class='id identifier rubyid_file'>file</span><span class='rparen'>)</span>
+  <span class='ivar'>@parsed_sources</span> <span class='op'>||=</span> <span class='lbrace'>{</span><span class='rbrace'>}</span>
+  <span class='ivar'>@parsed_sources</span><span class='lbracket'>[</span><span class='id identifier rubyid_file'>file</span><span class='rbracket'>]</span> <span class='op'>=</span> <span class='id identifier rubyid__parse_source'>_parse_source</span><span class='lparen'>(</span><span class='id identifier rubyid_file'>file</span><span class='rparen'>)</span>
+<span class='kw'>end</span></pre>
+    </td>
+  </tr>
+</table>
+</div>
+    
+  </div>
+
+</div>
+
+      <div id="footer">
+  Generated on Wed Dec  4 22:57:13 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>