flor 0.16.1 → 0.16.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 325520bb299ef5655cd1e18c0e11a4c7ecf30bd8
-  data.tar.gz: fb17d66b6254ca47b508007045b172222a336bcb
+  metadata.gz: 0c913a70a19f7d01588c3cd927cb529d64538177
+  data.tar.gz: 25d6262fe8024c0159a172f392ef65b203f72a1a
 SHA512:
-  metadata.gz: 472fe3d93e7853fffcd1fd69de1ef3ce4ea85647d60bcd908f6820270c4d1fab6475084f604b7b36bd611aa75afe0aa676110f088e09db8fd8764e72e44e0737
-  data.tar.gz: 53770fa93cd46eb71ef3cb76f54fa70f3d042f671595d84a2665bf3712f2817b23adc4bd6d80799469f7a43051f65753dfba4bc6c3d99fa6f5fe5b0da536172b
+  metadata.gz: 1d9834e300f1d5158f42027e51966efcfc500edeedf3c7495a42985b77d24dbcd87aafdd1061776c04cc0713181ced907d535cc5c59032b13b355211fab2dad8
+  data.tar.gz: ecdd517230e0f0602fb8b617b9d57ce94938864a30ecd7df827dab486de1f85de55ef296f8d0964fc878ccd764685230d2d73bea0e3c9aa53e144ccf52df8dee

data/CHANGELOG.md

@@ -2,6 +2,14 @@
 # CHANGELOG.md
 
 
+## flor 0.16.2  not yet released
+
+- Allow for `[ 'he' 'll' 'o' ] | + join: '.'` (yields "he.ll.o")
+- Allow for `[ 1 2 3 ] | + _` (yields `6`)
+- Make "child_on_error:"/"children_on_error:" a common attribute
+- Ensure "on_cancel" sets only one handler
+
+
 ## flor 0.16.1  released 2019-02-05
 
 - Depend on Sequel 5 (Sequel 4 and 5 seem OK)

data/CREDITS.md

@@ -3,6 +3,7 @@
 
 ## Contributors
 
+* Ryan Scott - https://github.com/Subtletree
 * Jeffrey Hicks - https://github.com/jrhicks
 * David Verrier - https://github.com/dverrier
 * Tsunehisa Doi - https://github.com/dmicky0419

data/Makefile

@@ -71,7 +71,7 @@ mk:
 	$(RUBY) -Ilib -e "require 'flor/tools/env'; Flor::Tools::Env.make('tmp', '$(FLOR_ENV)', gitkeep: true)"
 
 doc:
-	$(RUBY) -Imak -r 'doc' -e "make_procedures_doc()"
+	$(RUBY) -Imak -r 'doc_procedures' -e "make_doc_procedures()"
 doct:
 	@$(RUBY) mak/ptree.rb
 

data/README.md

@@ -10,10 +10,11 @@ Flor is a "Ruby workflow engine", if that makes any sense.
 * [floraison mailing list](https://groups.google.com/forum/#!forum/floraison)
 * [twitter.com/@flor_workflow](https://twitter.com/flor_workflow)
 
-## Design
+
+## design
 
 * Strives to propose a scheming interpreter for long running executions
-* Is written in Ruby a rather straightforward language with at least two
+* Is written in Ruby, a rather straightforward language with at least two
   wonderful implementations (MRI and JRuby, which is enterprise-friendly)
 * Stores everything as JSON (if it breaks it's still readable)
 * Stores in any database supported by [Sequel](http://sequel.jeremyevans.net/)
@@ -22,14 +23,89 @@ Flor is a "Ruby workflow engine", if that makes any sense.
 * All in all should be easy to maintain (engine itself and executions running
   on top of it)
 
-## Quickstart
 
-See [quickstart/](quickstart/).
+## quickstart
+
+This quickstart sets up a flor unit tied to a SQLite database, resets the databse, binds two taskers and then launches a flow execution involving the two taskers. Finally, it prints out the resulting workitem as the execution has just terminated.
+
+```ruby
+require 'flor/unit'
+
+#ENV['FLOR_DEBUG'] = 'dbg,sto,stdout' # full sql + flor debug output
+#ENV['FLOR_DEBUG'] = 'dbg,stdout' # flor debug output
+  # uncomment to see the flor activity
+
+sto_uri = 'sqlite://flor_qs.db'
+sto_uri = 'jdbc:sqlite://flor_qs.db' if RUBY_PLATFORM.match(/java/)
+
+flor = Flor::Unit.new(loader: Flor::HashLoader, sto_uri: sto_uri)
+  # instantiate flor unit
+
+flor.storage.delete_tables
+flor.storage.migrate
+  # blank slate database
+
+class DemoTasker < Flor::BasicTasker
+  def task(message)
+    (attd['times'] || 1).times do
+      message['payload']['log'] << "#{tasker}: #{task_name}"
+    end
+    reply
+  end
+end
+flor.add_tasker(:alice, DemoTasker)
+flor.add_tasker(:bob, DemoTasker)
+  # a simple logging tasker implementation bound under
+  # two different tasker names
+
+flor.start
+  # start the flor unit, so that it can process executions
+
+exid = flor.launch(
+  %q{
+    sequence
+      alice 'hello' times: 2
+      bob 'world'
+  },
+  payload: { log: [ "started at #{Time.now}" ] })
+    # launch a new execution, one that chains alice and bob work
 
-## Documentation
+#r = flor.wait(exid, 'terminated')
+r = flor.wait(exid)
+  # wait for the execution to terminate or to fail
+
+p r['point']
+  # "terminated" hopefully
+p r['payload']['log']
+  # [ "started at 2019-03-31 10:20:18 +0900",
+  #   "alice: hello", "alice: hello",
+  #   "bob: world" ]
+```
+
+This quickstart is at [doc/quickstart0/](doc/quickstart0/), it's a minimal, one-file Ruby quickstart.
+
+There is also [doc/quickstart1/](doc/quickstart1/), a more complex example, that shows a flor setup, where taskers and flows are layed out in a flor directory tree.
+
+
+## documentation
 
 See [doc/](doc/).
 
+* [doc/procedures/](doc/procedures/#procedures) - the basic building blocks of the flor language
+* [doc/glossary](doc/glossary.md) - words and their meaning in the flor context
+* [doc/patterns](doc/patterns.md) - workflow patterns and their flor (tentative) implementations
+
+
+## related projects
+
+* [mantor/floristry](https://github.com/mantor/floristry) - visualize and interact with flor through Rails facilities
+* [floraison/pollen](https://github.com/floraison/pollen) - a set of flor hooks that emit over the http
+* [floraison/florist](https://github.com/floraison/florist) - a flor worklist implementation
+* [floraison/flack](https://github.com/floraison/flack) - a flor wrapping [Rack](https://github.com/rack/rack) app
+* [floraison/fugit](https://github.com/floraison/fugit) - a time library for flor and [rufus-scheduler](https://github.com/jmettraux/rufus-scheduler)
+* [floraison/raabro](https://github.com/floraison/raabro) - the PEG library flor uses for its parsing needs
+
+
 ## blog posts and presentations
 
 * [the flor language](http://jmettraux.skepti.ch/20180927.html?t=the_flor_language) - on the flor workflow definition language itself
@@ -39,7 +115,7 @@ See [doc/](doc/).
 * [flor 2017](https://speakerdeck.com/jmettraux/flor-2017) - q1 2017 - very dry deck
 
 
-## LICENSE
+## license
 
 MIT, see [LICENSE.txt](LICENSE.txt)
 

data/lib/flor.rb

@@ -14,7 +14,7 @@ require 'dense'
 
 module Flor
 
-  VERSION = '0.16.1'
+  VERSION = '0.16.2'
   #VERSION = '1.0.0'
 end
 

data/lib/flor/conf.rb

@@ -48,6 +48,15 @@ module Flor
     #   "reserved" state, messages are put back in the "created" state
     #   (by a running unit (scheduler) if any).
     #
+    # * :db_migration / :sto_migration / :db_migration_dir / :sto_migration_dir
+    #   (Flor::Storage#migrate option)
+    #   Points the migrator to its Ruby Sequel migration directory.
+    #
+    # * :db_sparse_migrations / :sto_sparse_migrations
+    #   (Flor::Storage#migrate option)
+    #   Setting this to true is equivalent to calling
+    #   `unit.storage.migration(allow_missing_migration_files: true)`
+    #
     # And finally:
     #
     # * :flor_debug or :debug
@@ -71,8 +80,12 @@ module Flor
 
       def prepare(conf, over_conf)
 
-        c = conf
-        c = Flor::ConfExecutor.interpret_path_or_source(c) if c.is_a?(String)
+        c =
+          case conf
+          when String then Flor::ConfExecutor.interpret_path_or_source(conf)
+          when Hash then Flor.to_string_keyed_hash(conf)
+          else conf
+          end
 
         fail ArgumentError.new(
           "cannot extract conf out of #{c.inspect} (#{conf.class})"
@@ -92,10 +105,10 @@ module Flor
 
       def get_class(conf, key)
 
-        if v = conf[key]
-          Flor.const_lookup(v)
-        else
-          nil
+        case v = conf[key]
+        when Class then v
+        when String then Flor.const_lookup(v)
+        else nil
         end
       end
 

data/lib/flor/core/executor.rb

@@ -69,18 +69,31 @@ module Flor
 
     def trigger_hook(hook, message)
 
-      hook.notify(self, message)
+      m =
+        case
+        when hook.respond_to?(:notify) then :notify
+        when hook.respond_to?(:on_message) then :on_message
+        else :on
+        end
+      as =
+        case hook.method(m).arity
+        when 3 then [ @unit, self, message ]
+        when 2 then [ self, message ]
+        else [ message ]
+        end
+
+      r = hook.send(m, *as)
+
+      Flor.is_array_of_messages?(r) ? r : []
     end
 
     def trigger_block(block, opts, message)
 
       r =
-        if block.arity == 1
-          block.call(message)
-        elsif block.arity == 2
-          block.call(message, opts)
-        else
-          block.call(self, message, opts)
+        case block.arity
+        when 1 then block.call(message)
+        when 2 then block.call(message, opts)
+        else block.call(self, message, opts)
         end
 
       r.is_a?(Array) && r.all? { |e| e.is_a?(Hash) } ? r : []
@@ -146,9 +159,10 @@ module Flor
         # cnid: closure nid
         # dbg: used to debug messages (useful @node['dbg'] when 'receive')
 
-      if oeh = message['on_error_handler']
-        node['on_error'] = [ [ [ '*' ], oeh ] ]
-      end
+      %w[ error cancel timeout ]
+        .each { |k|
+          h = message["on_#{k}_handler"]
+          node["on_#{k}"] = [ h ] if h }
 
       @execution['nodes'][nid] = node
     end
@@ -228,6 +242,19 @@ module Flor
       heap = node['heap']
 
       heac = Flor::Procedure[heap]
+unless heac
+  puts "v" * 80
+  puts "===node:"
+  p node['nid']
+  p heap
+  puts "."
+  pp node
+  puts "===message:"
+  p message['point']
+  puts "."
+  pp message
+  puts "." * 80
+end
       fail NameError.new("unknown procedure #{heap.inspect}") unless heac
 
       head = heac.new(self, node, message)
@@ -426,7 +453,7 @@ module Flor
         ms = []
         ms += @unit.notify(self, message) # pre
 
-        ms += self.send(message['point'], message)
+        ms += send(message['point'], message)
 
         message['payload'] = message.delete('pld') if message.has_key?('pld')
         message['consumed'] = Flor.tstamp
@@ -456,11 +483,6 @@ module Flor
       []
     end
 
-    def entered(message); []; end
-    def left(message); []; end
-
-    def ceased(message); []; end
-
     def terminated(message)
 
       message['vars'] = @execution['nodes']['0']['vars']
@@ -496,6 +518,13 @@ module Flor
     end
 
     def signal(message); []; end
+    def entered(message); []; end
+    def left(message); []; end
+    def ceased(message); []; end
+      #
+      # Return an empty array of new messages. No direct effect.
+      #
+      # Some trap, hook, and/or waiter might lie in wait though.
 
     def lookup_on_error_parent(message)
 

data/lib/flor/core/node.rb

@@ -441,12 +441,12 @@ class Flor::Node
       if node == nil || mod == 'd'
 
     return lookup_arg_container(key) \
-      if mod == '' && %w[ args argv argh ].include?(key)
+      if mod == '' && %w[ arga args argv argh argd ].include?(key)
 
-    if vwl = node['vwlist']
+    if vwl = node['vwlist'] # variable white list
       return lookup_dvar_container(mod, key) unless var_match?(vwl, key)
     end
-    if vbl = node['vblist']
+    if vbl = node['vblist'] # variable black list
       return lookup_dvar_container(mod, key) if var_match?(vbl, key)
     end
 
@@ -502,7 +502,7 @@ class Flor::Node
 
     val =
       case key
-      when 'args', 'argv' then args.collect(&:last)
+      when 'arga', 'args', 'argv' then args.collect(&:last)
       else args.inject({}) { |h, (k, v)| h[k] = v if k; h }
       end
 

data/lib/flor/core/procedure.rb

@@ -615,6 +615,13 @@ class Flor::Procedure < Flor::Node
       # was considering passing the whole vars back (as 'varz'), but
       # it got in the way... and it might be heavy
 
+    %w[ error cancel timeout ]
+      .each { |k|
+        co = @node["child_on_#{k}"]
+        next unless co
+        kri = [ '*' ]
+        m["on_#{k}_handler"] = [ kri, co ] }
+
     [ m ]
   end
 
@@ -787,6 +794,10 @@ class Flor::Procedure < Flor::Node
       #
       # an idea from "sort" apply, may be useful later on...
 
+    if pl = opts[:payload]
+      ms.first['payload'] = pl
+    end
+
     ms
   end
 
@@ -893,6 +904,35 @@ class Flor::Procedure < Flor::Node
     wrap_cancel_children('flavour' => 'kill') +
     wrap_cancelled
   end
+
+  def do_add
+
+    return [] unless node_open?
+      # if the node is closed or ended, discard the add message
+
+    add
+  end
+
+  def add
+
+    fail Flor::FlorError.new(
+      "procedure does not accept add-iteration", self
+    ) if message['elements']
+
+    # TODO fail if the procedure changed
+    #      could the message contain a SHA for the node as was when the
+    #      that message got emitted?
+    #      well, could that be applied to other messages? too late?
+
+#puts " === add " + ("=" * 40)
+#pp message
+#puts " === add. " + ("=" * 39)
+    t = tree
+    i = Flor.child_id(message['tnid'])
+    t[1].insert(i, *message['trees'])
+
+    []
+  end
 end
 
 

data/lib/flor/djan.rb

@@ -88,10 +88,13 @@ module Flor
 
       if kt = opts[:keytab]
         out << ' ' * kt
+        :indent
       elsif opts[:indent]
         newline(out, opts)
+        :newline
       elsif ! opts[:compact]
         space(out, opts)
+        :space
       end
     end
 
@@ -152,9 +155,9 @@ module Flor
         c_inf(':', out, opts)
 
         kt = key_max_len ? key_max_len - kl : nil
-        newline_or_space(out, opts.merge(keytab: kt))
+        r = newline_or_space(out, opts.merge(keytab: kt))
 
-        to_d(v, out, indent(opts, inc: 2, keytab: kt))
+        to_d(v, out, indent(opts, inc: 2, keytab: r == :newline ? kt : 1))
 
         if ii < x.size - 1
           c_inf(',', out, opts)

data/lib/flor/flor.rb

@@ -52,15 +52,29 @@ module Flor
     end
     def dupm(h, hh); self.dup_and_merge(h, hh); end
 
-    def deep_freeze(o)
+    def deep_merge(o0, o1, in_place=false)
 
-      if o.is_a?(Array)
-        o.each { |e| e.freeze }
-      elsif o.is_a?(Hash)
-        o.each { |k, v| k.freeze; v.freeze }
+      t0 = type(o0)
+      t1 = type(o1)
+
+      return o1 if t1 != t0
+
+      if t0 == :array
+        o1.each_with_index.inject(in_place ? o0 : o0.dup) { |a, (e1, i)|
+          a[i] = deep_merge(o0[i], e1, in_place)
+          a }
+      elsif t0 == :object
+        o1.inject(in_place ? o0 : o0.dup) { |h, (k, v1)|
+          h[k] = deep_merge(o0[k], v1, in_place)
+          h }
+      else
+        o1
       end
+    end
+
+    def deep_merge!(o0, o1)
 
-      o.freeze
+      deep_merge(o0, o1, true)
     end
 
     def false?(o)
@@ -314,7 +328,14 @@ module Flor
         "not a sub domain #{sub.inspect}"
       ) unless potential_domain_name?(sub)
 
-      sub == dom || sub[0, dom.length + 1] == dom + '.'
+      sub_domain?(dom, sub)
+    end
+
+    def sub_domain?(dom, sub)
+
+      dom == '' ||
+      sub == dom ||
+      sub[0, dom.length + 1] == dom + '.'
     end
 
     def split_domain_unit(s)
@@ -443,6 +464,36 @@ module Flor
       o[1].match(/\A\/.*\/[a-zA-Z]*\z/)
     end
 
+    def is_sqs_tree?(o)
+
+      o.is_a?(Array) &&
+      o[0] == '_sqs' &&
+      o[2].is_a?(Integer) &&
+      o[1].is_a?(String)
+    end
+
+    def is_num_tree?(o)
+
+      o.is_a?(Array) &&
+      o[0] == '_num' &&
+      o[2].is_a?(Integer) &&
+      o[1].is_a?(Numeric)
+    end
+
+    def is_ref_tree?(o)
+
+      o.is_a?(Array) &&
+      (o[0] == '_ref' || o[0] == '_reff') &&
+      o[2].is_a?(Integer) &&
+      o[1].is_a?(Array) &&
+      o[1].all? { |e| is_sqs_tree?(e) || is_num_tree?(e) }
+    end
+
+    def ref_to_path(t)
+
+      t[1].collect { |tt| tt[1].to_s }.join('.')
+    end
+
     # Returns [ st, i ], the parent subtree for the final i index of the nid
     # Used when inserting updated subtrees.
     #
@@ -543,6 +594,40 @@ module Flor
 
       indent == '' ? out.string : nil
     end
+
+    def to_string_keyed_hash(o)
+
+      case o
+      when Array
+        o.collect { |e| to_string_keyed_hash(e) }
+      when Hash
+        o.inject({}) { |h, (k, v)| h[k.to_s] = to_string_keyed_hash(v); h }
+      else
+        o
+      end
+    end
+
+    def to_camel_case(s)
+
+      s.sub(/\A[a-z]/) { |m| m.upcase }.gsub(/_[a-z]/) { |m| m[1, 1].upcase }
+    end
+
+    # Available as `Flor.migration_dir`
+    #
+    def migration_dir
+
+      File.absolute_path(
+        File.join(
+          File.dirname(__FILE__), 'migrations'))
+    end
+
+    def caller_fname
+
+      caller
+        .find { |l| ! l.match(/\/lib\/flor\//) }
+        .match(/\A([^:]+:\d+)/)[1]
+        .strip
+    end
   end
 end