eco-helpers 3.0.37 → 3.1.1

data/lib/eco/language/models/workflow.rb

@@ -0,0 +1,385 @@
+module Eco::Language::Models
+  # Execution workflow
+  class Workflow
+    extend Eco::Language::Klass::HelpersBuilt
+    extend Eco::Language::Models::Hierarchy
+
+    class << self
+      def stages
+        model_attrs
+      end
+
+      def model
+        super || {}
+      end
+
+      def validate_stage!(stage)
+        return true if stages.include?(stage)
+
+        msg = "Unknown Workflow stage '#{stage}'. Should be any of #{stages}"
+        raise ArgumentError, msg
+      end
+
+      def workflow_class(key)
+        class_name = to_constant(key.to_s)
+
+        new_class(
+          class_name,
+          inherits: Eco::API::Session::Config::Workflow
+        ) do |klass|
+          klass.model = model[key]
+        end
+      end
+    end
+
+    attr_reader :config
+
+    def initialize(name = nil, config:, _parent: self) # rubocop:disable Lint/UnderscorePrefixedVariableName
+      @config   = config
+      @name     = name
+
+      @stages   = {}
+      @_parent  = _parent
+
+      @pending  = true
+      # moments
+      @on       = nil
+      @before   = []
+      @after    = []
+    end
+
+    def name(with_path: false)
+      return @name if !with_path || root?
+
+      [@_parent.name(with_path: true), @name].compact.join('.')
+    end
+
+    # Has this stage run yet?
+    # @note it does **not** include _sub-stages_ that run `before`
+    # @return [Boolean] `true` if it has run, `false` otherwise
+    def pending?
+      @pending
+    end
+
+    # Do not run this stage!
+    def skip!
+      @skip    = true
+      @pending = false
+    end
+
+    # Has this stage been marked as to be skipped
+    # @return [Boolean] depends on this order:
+    #   - `true` if `skip!` was called
+    #   - `false` if the current _stage_ is `root?` (the top stage of the hierarchy)
+    #   - `true` if its parent task is to be skipped
+    def skip?
+      return @skip if instance_variable_defined?(:@skip)
+      return false if root?
+
+      @_parent.skip?
+    end
+
+    # Used in **configuration** time **to configure** the _workflow_ of the target (sub)stage `key`
+    # @note
+    #   1. if a `block` is provided it will `yield` the target stage immediately
+    #   2. a `block` is only required when `key` has not been specified.
+    # @param key [Symbol, nil] cases:
+    #   - if `key` is not provided, it targets the _current stage_
+    #   - if `key` is provided, it targets the specific _sub-stage_
+    # @yield [stage_workflow] further _workflow_ configuration `for` the target stage `key`
+    # @yieldparam stage_workflow [Eco::API::Session::Config::Workflow] the _target stage_  referred by `key`
+    # @return [Eco::API::Session::Config::Workflow]
+    #   1. if block is provided provided, it returns the **current stage** object (to ease chainig).
+    #   2. if block is not provided, it returns the **stage** referred by `key`
+    def for(key = nil, &block)
+      msg = "With no 'key', a block should be given."
+      raise ArgumentError, msg unless key || block_given?
+
+      tap do
+        next yield(self)            unless key
+        next stage(key).for(&block) if block_given?
+
+        return stage(key)
+      end
+    end
+    alias_method :with, :for
+
+    # Used in **configuration** time **to define** the **behaviour**  the target (sub)stage `key`
+    # @note if a `block` is provided it will **not** `yield` the target stage immediately,
+    #   but when the _workflow_ reaches the stage
+    # @param key [Symbol, nil] cases:
+    #   - if `key` is not provided, it targets the _current stage_
+    #   - if `key` is provided, it targets the specific _sub-stage_
+    # @yield [stage_workflow, io] the behaviour of the target stage `key` when the _workflow_ reaches it
+    # @yieldparam stage_workflow [Eco::API::Session::Config::Workflow] the _target stage_  referred by `key`
+    # @yieldparam io [INPUT_OUTPUT_CLASS] the input/output object carried througout all the _workflow_
+    # @yieldreturn [INPUT_OUTPUT_CLASS] the `io` input/output object carried througout all the _workflow_
+    # @return [Eco::API::Session::Config::Workflow] the current stage object (to ease chainig).
+    def on(key = nil, &block)
+      msg = 'A block should be given.'
+      raise ArgumentError, msg unless block_given?
+
+      if key
+        stage(key).on(&block)
+      else
+        @on = block
+      end
+
+      self
+    end
+
+    # When there is an `Exception`, you might have defined some `callback`
+    # to do something with it (i.e. register, email)
+    # @yield [exception, io] the `callback` to do something with
+    #   an `Exception` raised within this _workflow_ stage
+    # @yieldparam exception [Exception] the exception object that was raised
+    # @yieldparam io [INPUT_OUTPUT_CLASS] the input/output object carried througout all the _workflow_
+    # @yieldreturn [INPUT_OUTPUT_CLASS] the `io` input/output object carried througout all the _workflow_
+    # @return [Eco::API::Session::Config::Workflow] the current stage object (to ease chainig).
+    def rescue(&block)
+      return @rescue unless block_given?
+
+      @rescue = block
+      self
+    end
+    # Prevent reserved word clash on DSL
+    alias_method :exception, :rescue
+
+    # Called on `SystemExit` exception
+    def exit_handle(&block)
+      return @exit_handle unless block_given?
+
+      @exit_handle = block
+      self
+    end
+
+    # Used in **configuration** time **add previous** `callbacks`
+    # **before** the `on` _callback_ of the (sub)stage `key` is actually `run`
+    # @note
+    #   - it will **not** `yield` it immediately, but when the _workflow_ reaches the target stage
+    #   - in this case, you can define multiple `callbacks`
+    # @param key [Symbol, nil] cases:
+    #   - if `key` is not provided, it targets the _current stage_
+    #   - if `key` is provided, it targets the specific _sub-stage_
+    # @yield [stage_workflow, io] one of the things to do **before** the
+    #  `on` _callback_ of the (sub)stage `key` is actually `run`
+    # @yieldparam stage_workflow [Eco::API::Session::Config::Workflow] the _target stage_  referred by `key`
+    # @yieldparam io [INPUT_OUTPUT_CLASS] the input/output object carried througout all the _workflow_
+    # @yieldreturn [INPUT_OUTPUT_CLASS] `io` the input/output object carried througout all the _workflow_
+    # @return [Eco::API::Session::Config::Workflow] the current stage object (to ease chainig).
+    def before(key = nil, &block)
+      msg = 'A block should be given.'
+      raise ArgumentError, msg unless block_given?
+
+      if key
+        stage(key).before(&block)
+      else
+        @before.push(block)
+      end
+
+      self
+    end
+
+    # Used in **configuration** time **add previous** `callbacks` **after** the `on` _callback_
+    # of the (sub)stage `key` is actually `run`
+    # @note
+    #   - it will **not** `yield` it immediately, but when the _workflow_ reaches the target stage
+    #   - in this case, you can define multiple `callbacks`
+    # @param key [Symbol, nil] cases:
+    #   - if `key` is not provided, it targets the _current stage_
+    #   - if `key` is provided, it targets the specific _sub-stage_
+    # @yield [stage_workflow, io] one of the things to do **after** the
+    #   `on` _callback_ of the (sub)stage `key` is actually `run`
+    # @yieldparam stage_workflow [Eco::API::Session::Config::Workflow] the _target stage_  referred by `key`
+    # @yieldparam io [INPUT_OUTPUT_CLASS] the input/output object carried througout all the _workflow_
+    # @yieldreturn [INPUT_OUTPUT_CLASS] `io` the input/output object carried througout all the _workflow_
+    # @return [Eco::API::Session::Config::Workflow] the current stage object (to ease chainig).
+    def after(key = nil, &block)
+      msg = 'A block should be given.'
+      raise ArgumentError, msg unless block_given?
+
+      if key
+        stage(key).after(&block)
+      else
+        @after.push(block)
+      end
+
+      self
+    end
+
+    # Used in run time to **execute the workflow** of the (sub)stage `key`
+    # @note if a `block` is **not** provided:
+    #   - it will run the `before` _callbacks_ defined during the configuration time
+    #   - it will run the _workflow_ of any defined _**substage**_ of the `key` stage
+    #   - it will run the `on` _callback_ defined during the configuration time
+    #   - it will mark the stage as **not** `pending?`.
+    #   - it will run the `after` _callbacks_ defined during the configuration time
+    # @note if a `block` is provided:
+    #   - it will **not** run the workflow of the substages to `key` stage
+    #   - it will **not** run the `callback` for `on` defined during the configuration time
+    #   - it will rather `yield` the target stage after all the `before` _callbacks_ have been run
+    #   - aside of this, the rest will be the same as when the _block_ is provided (see previous note)
+    # @note [if the object returned by `before`, `after` and `run` callbacks
+    #   is not an `INPUT_OUTPUT_CLASS`, the original `io` object will be returned instead.
+    # @param key [Symbol, nil] cases:
+    #   - if `key` is not provided, it targets the _current stage_
+    #   - if `key` is provided, it targets the specific _sub-stage_
+    # @param io [INPUT_OUTPUT_CLASS] the input/output object
+    # @yield [stage_workflow, io] if a `block` is provided, see `note`
+    # @yieldparam stage_workflow [Eco::API::Session::Config::Workflow] the _target stage_ referred by `key`
+    # @yieldparam io [INPUT_OUTPUT_CLASS] the input/output object carried througout all the _workflow_
+    # @yieldreturn [INPUT_OUTPUT_CLASS] the `io` input/output object carried througout all the _workflow_
+    # @return [Eco::API::Session::Config::Workflow] the current stage object (to ease chainig).
+    def run(key = nil, io:, &block)
+      raise 'Missing BaseIO object' unless io.is_a?(input_output_class)
+
+      rescuable(io) do
+        if key
+          io = io_result(io: io) do
+            stage(key).run(io: io, &block)
+          end
+        elsif pending?
+          io = run_before(io)
+          io = run_it(io, &block) unless skip?
+          io = run_after(io)
+        end
+        io
+      ensure
+        @pending = false
+      end
+    end
+
+    protected
+
+    def root?
+      @_parent == self
+    end
+
+    def path
+      return name if root?
+
+      "#{@_parent.path}:#{name}"
+    end
+
+    def ready?
+      !!@on
+    end
+
+    def run_before(io)
+      @before.each do |c|
+        io = io_result(io: io) do
+          io.evaluate(self, io, &c)
+        end
+      end
+
+      io
+    end
+
+    def run_after(io)
+      @after.each do |c|
+        io = io_result(io: io) do
+          io.evaluate(self, io, &c)
+        end
+      end
+
+      io
+    end
+
+    def run_it(io, &block)
+      io.session.log(:debug) {
+        "(Workflow: #{path}) running now"
+      }
+
+      if block
+        io = io_result(io: io) do
+          io.evaluate(self, io, &block)
+        end
+      else
+        existing_stages.each do |stg|
+          io = io_result(io: io) do
+            stg.run(io: io)
+          end
+        end
+
+        unless ready?
+          io.session.log(:debug) {
+            "(Workflow: #{path}) 'on' callback is not defined, nor block given"
+          }
+        end
+
+        io = io_result(io: io) do
+          io.evaluate(self, io, &@on)
+        end
+      end
+
+      io
+    ensure
+      @pending = false
+    end
+
+    # It ensures an `INPUT_OUTPUT_CLASS` is returned
+    # @note it always brings the IO to be a `BaseIO`.
+    #   As the `output` and the type is captured, it just cleans usecase related
+    #   logic from the object.
+    # @raise ArgumentError if `klass` isn't child of `INPUT_OUTPUT_CLASS`
+    # @return [INPUT_OUTPUT_CLASS] the `io` input/output object carried througout the _workflow_
+    def io_result(io:, klass: input_output_class)
+      msg = "Expecting class to be child of #{input_output_class}. Given: #{klass}"
+      raise ErrorArgument, msg unless klass <= input_output_class
+
+      result = yield
+      io     = result if result.is_a?(klass)
+      io.instance_of?(klass) ? io : io.base
+    end
+
+    def existing_stages
+      # sort defined stages by stage order
+      sorted_keys = self.class.stages & @stages.keys
+      sorted_keys.map {|k| stage(k)}
+    end
+
+    def ready_stages
+      exiting_stages.select(&:ready?)
+    end
+
+    def stages_ready?
+      existing_stages.all?(&:ready?)
+    end
+
+    def stage(key)
+      self.class.validate_stage!(key)
+      @stages[key] ||= self.class.workflow_class(key).new(
+        key,
+        _parent: self,
+        config:  config
+      )
+    end
+
+    def input_output_class
+      self.class::INPUT_OUTPUT_CLASS
+    end
+
+    # helper to treat trigger the exit and rescue handlers
+    def rescuable(io)
+      yield
+    # rescue SystemStackError => err
+    #   puts err.patch_full_message(trace_count: 100)
+    #   exit 1
+    rescue SystemExit => err
+      io = io_result(io: io) do
+        io.evaluate(err, io, &exit_handle)
+      end
+
+      exit err.status
+    rescue Interrupt => _int
+      raise
+    rescue StandardError => err
+      # raise unless self.rescue
+      io = io_result(io: io) do
+        io.evaluate(err, io, &self.rescue)
+      end
+
+      raise
+    end
+  end
+end

data/lib/eco/language/models.rb

@@ -5,8 +5,9 @@ module Eco
   end
 end
 
-require_relative 'models/class_helpers'
 require_relative 'models/modifier'
+require_relative 'models/hierarchy'
+require_relative 'models/workflow'
 require_relative 'models/collection'
 require_relative 'models/parser_serializer'
 require_relative 'models/wrap'

data/lib/eco/version.rb

@@ -1,3 +1,3 @@
 module Eco
-  VERSION = '3.0.37'.freeze
+  VERSION = '3.1.1'.freeze
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: eco-helpers
 version: !ruby/object:Gem::Version
-  version: 3.0.37
+  version: 3.1.1
 platform: ruby
 authors:
 - Oscar Segura
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-04-15 00:00:00.000000000 Z
+date: 2025-04-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: byebug
@@ -559,14 +559,12 @@ files:
 - lib/eco-helpers.rb
 - lib/eco/api.rb
 - lib/eco/api/common.rb
-- lib/eco/api/common/class_auto_loader.rb
-- lib/eco/api/common/class_helpers.rb
-- lib/eco/api/common/class_hierarchy.rb
 - lib/eco/api/common/class_meta_basics.rb
 - lib/eco/api/common/loaders.rb
 - lib/eco/api/common/loaders/base.rb
 - lib/eco/api/common/loaders/case_base.rb
 - lib/eco/api/common/loaders/config.rb
+- lib/eco/api/common/loaders/config/block.rb
 - lib/eco/api/common/loaders/config/cli.rb
 - lib/eco/api/common/loaders/config/session.rb
 - lib/eco/api/common/loaders/config/workflow.rb
@@ -886,7 +884,13 @@ files:
 - lib/eco/api/usecases/lib/error_handling.rb
 - lib/eco/api/usecases/lib/files.rb
 - lib/eco/api/usecases/lib/files/file_pattern.rb
+- lib/eco/api/usecases/lib/files/input_file.rb
 - lib/eco/api/usecases/lib/files/sftp.rb
+- lib/eco/api/usecases/lib/locations.rb
+- lib/eco/api/usecases/lib/locations/base.rb
+- lib/eco/api/usecases/lib/locations/mapping.rb
+- lib/eco/api/usecases/lib/people.rb
+- lib/eco/api/usecases/lib/people/base.rb
 - lib/eco/api/usecases/ooze_cases.rb
 - lib/eco/api/usecases/ooze_cases/export_register_case.rb
 - lib/eco/api/usecases/ooze_samples.rb
@@ -924,6 +928,7 @@ files:
 - lib/eco/api/usecases/use_case_chain/chaining.rb
 - lib/eco/api/usecases/use_case_io.rb
 - lib/eco/api/usecases/use_case_io/chain.rb
+- lib/eco/api/usecases/workflow.rb
 - lib/eco/assets.rb
 - lib/eco/assets/language.rb
 - lib/eco/cli.rb
@@ -949,17 +954,31 @@ files:
 - lib/eco/cli_default/people_filters.rb
 - lib/eco/cli_default/usecases.rb
 - lib/eco/cli_default/workflow.rb
+- lib/eco/cli_default/workflow/end.rb
+- lib/eco/cli_default/workflow/launch_jobs.rb
+- lib/eco/cli_default/workflow/load.rb
+- lib/eco/cli_default/workflow/load/data.rb
+- lib/eco/cli_default/workflow/load/input.rb
+- lib/eco/cli_default/workflow/options.rb
+- lib/eco/cli_default/workflow/post_launch.rb
+- lib/eco/cli_default/workflow/report.rb
+- lib/eco/cli_default/workflow/rescued_exception.rb
+- lib/eco/cli_default/workflow/usecases.rb
 - lib/eco/common.rb
 - lib/eco/csv.rb
 - lib/eco/csv/split.rb
 - lib/eco/csv/stream.rb
 - lib/eco/csv/table.rb
 - lib/eco/data.rb
+- lib/eco/data/count_trace.rb
 - lib/eco/data/files.rb
+- lib/eco/data/files/content.rb
 - lib/eco/data/files/directory.rb
 - lib/eco/data/files/encoding.rb
 - lib/eco/data/files/file_pattern.rb
-- lib/eco/data/files/helpers.rb
+- lib/eco/data/files/folder.rb
+- lib/eco/data/files/relative_path.rb
+- lib/eco/data/files/timestamp.rb
 - lib/eco/data/fuzzy_match.rb
 - lib/eco/data/fuzzy_match/array_helpers.rb
 - lib/eco/data/fuzzy_match/chars_position_score.rb
@@ -1021,24 +1040,29 @@ files:
 - lib/eco/language/hash_transform.rb
 - lib/eco/language/hash_transform_modifier.rb
 - lib/eco/language/klass.rb
+- lib/eco/language/klass/auto_loader.rb
 - lib/eco/language/klass/builder.rb
+- lib/eco/language/klass/const.rb
 - lib/eco/language/klass/helpers_built.rb
 - lib/eco/language/klass/hierarchy.rb
 - lib/eco/language/klass/inheritable_class_vars.rb
 - lib/eco/language/klass/naming.rb
 - lib/eco/language/klass/resolver.rb
+- lib/eco/language/klass/uid.rb
 - lib/eco/language/klass/when_inherited.rb
 - lib/eco/language/match.rb
 - lib/eco/language/match_modifier.rb
 - lib/eco/language/methods.rb
+- lib/eco/language/methods/access_modifier.rb
 - lib/eco/language/methods/call_detector.rb
 - lib/eco/language/methods/dsl_able.rb
 - lib/eco/language/methods/instance_method_helpers.rb
 - lib/eco/language/models.rb
-- lib/eco/language/models/class_helpers.rb
 - lib/eco/language/models/collection.rb
+- lib/eco/language/models/hierarchy.rb
 - lib/eco/language/models/modifier.rb
 - lib/eco/language/models/parser_serializer.rb
+- lib/eco/language/models/workflow.rb
 - lib/eco/language/models/wrap.rb
 - lib/eco/language/strings.rb
 - lib/eco/language/strings/underscore.rb

data/lib/eco/api/common/class_auto_loader.rb

@@ -1,114 +0,0 @@
-module Eco
-  module API
-    module Common
-      # Helpers for dynamic object loading based on class declaration
-      # @note
-      #   - this helpers aim to boost the usage of the ruby language in complex api configurations.
-      module ClassAutoLoader
-        include Eco::API::Common::ClassHelpers
-
-        # To enable the class autoloader, you should use this  method
-        def autoloads_children_of(klass)
-          class_resolver :autoloader_class, klass
-          @autoloaded_class = klass
-        end
-
-        # Resolves the class `autoloader_class` if it has been defined via `autoloads_children_of`
-        def autoloaded_class
-          return nil unless @autoloaded_class
-          autoloader_class
-        end
-
-        # To which restricted namespaces this class autoloads from
-        def autoloaded_namespaces(type = :include)
-          @autoloaded_namespaces       ||= {}
-          @autoloaded_namespaces[type] ||= []
-        end
-
-        # To restrict which namespaces it is allowed to load from
-        def autoload_namespace(*namespaces)
-          _autoload_namespace(:include, *namespaces)
-        end
-
-        # To ignore certain namespaces this class should not autoload from
-        def autoload_namespace_ignore(*namespaces)
-          _autoload_namespace(:ignore, *namespaces)
-        end
-
-        def _autoload_namespace(type, *namespaces)
-          autoloaded_namespaces(type).concat(namespaces) unless namespaces.empty?
-        end
-
-        # @param constant [Class, String] a class or namespace we want to check auto-load entitlement thereof.
-        # @return [Boolean] determines if a given namespace is entitled for autoloading
-        def autoload_class?(constant)
-          constants = "#{constant}".split("::").compact
-          autoload = true
-          unless autoloaded_namespaces(:include).empty?
-            autoload = autoloaded_namespaces(:include).any? do |ns|
-              "#{ns}".split("::").compact.zip(constants).all? {|(r, c)| r == c}
-            end
-          end
-          unless autoloaded_namespaces(:ignore).empty?
-            autoload &&= autoloaded_namespaces(:ignore).none? do |ns|
-              "#{ns}".split("::").compact.zip(constants).all? {|(r, c)| r == c}
-            end
-          end
-          autoload
-        end
-
-        # As children are loaded as they are declared, we should not load twice same children.
-        def autoloaded_children
-          @auto_loaded_children ||= []
-        end
-
-        # Children classes of `autoloader_class` that have not been created an instance of.
-        def unloaded_children
-          return [] unless autoloaded_class
-          new_detected = new_classes
-          known_class!(*new_detected)
-          descendants(parent_class: autoloaded_class, scope: new_detected).select do |child_class|
-            !autoloaded_children.include?(child_class) && autoload_class?(child_class)
-          end.sort
-        end
-
-        # It loads/creates a new instance of children classes pending to be loaded.
-        # @return [Boolean] `true` if there were children loaded, `false` otherwise.
-        def autoload_children(object)
-          return false if !autoloaded_class || @loading_children
-          pending_children = unloaded_children
-          return false if pending_children.empty?
-          @loading_children = true
-          pending_children.each do |klass|
-            begin
-              @child = klass.new(object)
-            rescue TypeError => e
-              # Can't create from this class (must be the singleton class)
-              # Just ignore
-            ensure
-              autoloaded_children.push(klass)
-            end
-          end
-          @loading_children = false
-          true
-        end
-
-        # Known namespaces serves the purpose to discover recently added namespaces
-        #   provided that the namespace discovery is optimized
-        def known_classes
-          @known_classes ||= []
-        end
-
-        # Add to known namespaces
-        def known_class!(*classes)
-          known_classes.concat(classes)
-        end
-
-        # List all new namespaces
-        def new_classes
-          ObjectSpace.each_object(::Class).to_a - known_classes
-        end
-      end
-    end
-  end
-end

data/lib/eco/api/common/class_helpers.rb

@@ -1,9 +0,0 @@
-module Eco
-  module API
-    module Common
-      module ClassHelpers
-        include Eco::Language::Klass::HelpersBuilt
-      end
-    end
-  end
-end

data/lib/eco/api/common/class_hierarchy.rb

@@ -1,45 +0,0 @@
-module Eco
-  module API
-    module Common
-      # Helpers for dynammic generation of classes based on a hierarchical model
-      # @attr_reader model [Hash, nil] the `model` of the current `class`
-      module ClassHierarchy
-        include Eco::API::Common::ClassHelpers
-
-        attr_reader :model
-
-        # @param value [Hash, Enumerable, String, Symbol, nil] unparsed model to be assigned to the `class`
-        def model=(value)
-          @model = parse_model(value)
-        end
-
-        # @return [Array<String>] the `keys` of the current class' `model`
-        def model_attrs
-          model&.keys || []
-        end
-
-        # Thanks to this step the format on the declaration of the model is flexible
-        # @param model [Hash, Enumerable, String, Symbol, nil]
-        # @return [Hash, nil] where keys are `Symbol` s
-        def parse_model(model)
-          case model
-          when String
-            parse_model(model.to_sym)
-          when Symbol
-            {model => nil}
-          when Hash
-            model.transform_keys(&:to_sym)
-          when Enumerable
-            model.each_with_object({}) do |sub, hash|
-              hash.merge!(parse_model(sub))
-            end
-          when NilClass
-            nil
-          else
-            raise "Incorrect model declaration, allowed String, Symbol, Hash and Enumerable. Given: #{model.class}"
-          end
-        end
-      end
-    end
-  end
-end