eco-helpers 2.6.0 → 2.6.2

data/lib/eco/api/session/config/workflow.rb

@@ -11,7 +11,8 @@ module Eco
             :usecases, :launch_jobs,
             {post_launch: [:usecases, :launch_jobs]},
             :report,
-            :end, :close
+            :end,
+            :close
           ]
 
           class << self
@@ -34,12 +35,10 @@ module Eco
                 klass.model = model[key]
               end
             end
-
           end
 
           self.model = WORKFLOW_MODEL
           attr_reader :config
-          attr_reader :name
 
           def initialize(name = nil, _parent: self, config:)
             @config   = config
@@ -55,6 +54,11 @@ module Eco
             @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
@@ -80,23 +84,26 @@ module Eco
           end
 
           # Used in **configuration** time **to configure** the _workflow_ of the target (sub)stage `key`
-          # @note if a `block` is provided it will `yield` the target stage immediately
+          # @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] the current stage object (to ease chainig).
+          # @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)
-            raise "A block should be given." unless block_given?
-            if !key
-              yield(self)
-            else
-              stage(key).for(&block)
+            raise ArgumentError, "With no 'key', a block should be given." unless key || block_given?
+            self.tap do
+              next yield(self)            unless key
+              next stage(key).for(&block) if block_given?
+              return stage(key)
             end
-            self
           end
-          alias_method :open, :for
+          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
@@ -109,7 +116,7 @@ module Eco
           # @yieldreturn [Eco::API::UseCases::BaseIO] 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)
-            raise "A block should be given." unless block
+            raise ArgumentError, "A block should be given." unless block_given?
             if !key
               @on = block
             else
@@ -129,7 +136,10 @@ module Eco
             @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
             @exit_handle = block
@@ -149,7 +159,7 @@ module Eco
           # @yieldreturn [Eco::API::UseCases::BaseIO] `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)
-            raise "A block should be given." unless block
+            raise ArgumentError, "A block should be given." unless block_given?
             if !key
               @before.push(block)
             else
@@ -171,7 +181,7 @@ module Eco
           # @yieldreturn [Eco::API::UseCases::BaseIO] `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)
-            raise "A block should be given." unless block
+            raise ArgumentError, "A block should be given." unless block_given?
             if !key
               @after.push(block)
             else
@@ -192,7 +202,8 @@ module Eco
           #   - 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)
-          # @raise [ArgumentError] if the object returned by `before` and `after` callbacks is not an `Eco::API::UseCases::BaseIO`.
+          # @note [if the object returned by `before`, `after` and `run` callbacks is not an `Eco::API::UseCases::BaseIO`,
+          #   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_
@@ -204,62 +215,87 @@ module Eco
           # @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?(Eco::API::UseCases::BaseIO)
-            begin
-              if key
-                io = stage(key).run(io: io, &block)
-              elsif pending?
-                @before.each do |c|
-                  io = c.call(self, io).tap do |i_o|
-                    unless i_o.is_a?(Eco::API::UseCases::BaseIO)
-                      msg  = "Workflow callaback before('#{name}') should return Eco::API::UseCases::BaseIO object."
-                      msg += " Given #{i_o.class}"
-                      msg += " • Callback source location: '#{c.source_location}'"
-                      raise ArgumentError.new(msg)
-                    end
-                  end
-                end
 
-                unless skip?
-                  io.session.logger.debug("(Workflow: #{path}) running now")
-                  if block
-                    io = block.call(self, io)
-                  else
-                    existing_stages.each {|stg| io = stg.run(io: io)}
+            if key
+              io = io_result(io: io) do
+                stage(key).run(io: io, &block)
+              end
+            elsif pending?
+              @before.each do |c|
+                io = io_result(io: io) do
+                  io.evaluate(self, io, &c)
+                end
+              end
 
-                    unless ready?
-                      msg = "(Workflow: #{path}) 'on' callback is not defined, nor block given"
-                      io.session.logger.debug(msg)
+              unless skip?
+                io.session.logger.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
-                    io = @on.call(self, io) if ready?
                   end
-                  @pending = false
-                end
 
-                @after.each do |c|
-                  io = c.call(self, io).tap do |i_o|
-                    unless i_o.is_a?(Eco::API::UseCases::BaseIO)
-                      msg  = "Workflow callaback after('#{name}') should return Eco::API::UseCases::BaseIO object."
-                      msg += " Given #{i_o.class}"
-                      msg += " • Callback source location: '#{c.source_location}'"
-                      raise ArgumentError.new(msg)
-                    end
+                  unless ready?
+                    msg = "(Workflow: #{path}) 'on' callback is not defined, nor block given"
+                    io.session.logger.debug(msg)
                   end
+                  io = io_result(io: io) do
+                    io.evaluate(self, io, &@on)
+                  end
+                end
+                @pending = false
+              end
+
+              @after.each do |c|
+                io = io_result(io: io) do
+                  io.evaluate(self, io, &c)
                 end
               end
-            rescue SystemExit => e
-              self.exit_handle.call(e, io) if self.exit_handle
-              exit e.status
-            rescue Interrupt => i
-              raise
-            rescue Exception => e
-              self.rescue.call(e, io) if self.rescue
-              raise
             end
             io
+          rescue SystemExit => e
+            io = io_result(io: io) do
+              io.evaluate(e, io, &self.exit_handle)
+            end
+            exit e.status
+          rescue Interrupt => i
+            raise
+          rescue Exception => e
+            # raise unless self.rescue
+            io = io_result(io: io) do
+              io.evaluate(e, io, &self.rescue)
+            end
+            raise
+          ensure
+            @pending = false
           end
 
           protected
 
+          def root?
+            @_parent == self
+          end
+
+          # It ensures an `Eco::API::UseCases::BaseIO` 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 `Eco::API::UseCases::BaseIO`
+          # @return [Eco::API::UseCases::BaseIO] the `io` input/output object carried througout the _workflow_
+          def io_result(io:, klass: Eco::API::UseCases::BaseIO)
+            msg = "Expecting class to be child of Eco::API::UseCases::BaseIO. Given: #{klass}"
+            raise ErrorArgument, msg unless klass <= Eco::API::UseCases::BaseIO
+
+            result = yield
+            io = result if result.is_a?(klass)
+            io.instance_of?(klass) ? io : io.base
+          end
+
           def path
             return name if root?
             "#{@_parent.path}:#{name}"

data/lib/eco/api/session/config.rb

@@ -367,10 +367,10 @@ module Eco
         end
 
         # @return [Eco::API::Session::Batch::Policies]
-        def batch_policies
+        def batch_policies(&block)
           @batch_policies = self["batch_policies"] ||= Eco::API::Session::Batch::Policies.new("batch_policy")
           if block_given?
-            yield(@batch_policies)
+            @batch_policies.evaluate(@batch_policies, &block)
             self
           else
             @batch_policies

data/lib/eco/api/usecases/base_io.rb

@@ -5,6 +5,9 @@ module Eco
       class BaseIO < BaseCase
         @types  = BaseCase.types
 
+        include Eco::Language::Methods::DslAble
+        include Eco::Language::AuxiliarLogger
+
         class MissingParameter < StandardError
           attr_reader :type, :required, :given
 
@@ -37,14 +40,14 @@ module Eco
         # @param people [Eco::API::Organization::People] people object.
         # @param session [Eco::API:Session]
         # @param options [Hash] hash with symbol keys (i.e. behaviour modifiers, cli trackers, filters, etc.)
-        def initialize(type: nil, input: nil, people: nil, session:, options: {}, validate: true)
-          @output      = nil
+        def initialize(type: nil, input: nil, people: nil, session:, options: {}, output: nil, validate: true)
           self.type    = type if type
 
           if self.type && validate
             validate_args(input: input, people: people, session: session, options: options)
           end
 
+          @output      = output
           @input       = input
           @people      = people
           @session     = session
@@ -57,10 +60,13 @@ module Eco
           @type = value
         end
 
-        # Helper to obtain an `BaseIO` objcect from any child class.
+        # Helper to obtain an `BaseIO` object from any child class.
         # @return [Eco::API::UseCases::BaseIO]
         def base
-          kargs = params(keyed: true).merge(type: self.type).slice(:type, :input, :people, :session, :options)
+          kargs = params(keyed: true).merge({
+            type:   self.type,
+            output: self.output,
+          }).slice(:type, :input, :people, :session, :options, :output) # :validate <- ?
           Eco::API::UseCases::BaseIO.new(**kargs)
         end
 
@@ -73,6 +79,7 @@ module Eco
             people:   self.people,
             session:  self.session,
             options:  self.options,
+            output:   self.output,
             validate: true
           }
           self.class.new(**default.merge(kargs))
@@ -87,6 +94,45 @@ module Eco
           keyed ? kargs : kargs.values
         end
 
+        # Shortcut to run a usecase passing this `io` as parameter
+        # @note
+        #   1. It swaps `output` to `input` or `people` depending on `self.type`
+        #   2. does this, **before** the target `case_name` launch and **after
+        # @return [Eco::API::UseCases::BaseIO]
+        def process_case(case_name, case_type, **params)
+          session.process_case(case_name, io: chained, type: case_type, **params).chained
+        end
+
+        # Does the switch from output to result in a new IO object.
+        # @note if there isn't `output` it doesn't do the switch,
+        #   provided that it preserves the target parameter
+        #   (otherise it would blank it)
+        # @return [Eco::API::UseCases::BaseIO]
+        def chained(as: self.type)
+          base.tap do |io_base|
+            next unless io_base.output
+            case as
+            when :import
+              io_base.output_be_input!
+            when :filter
+              io_base.output_be_people!
+            when :transform, :sync, :export, :error_handler, :other
+            end
+          end
+        end
+
+        protected
+
+        def output_be_input!
+          @input, @output = output, nil
+          input
+        end
+
+        def output_be_people!
+          @people, @output = output, nil
+          people
+        end
+
         private
 
         def validate_args(input:, people:, session:, options:)

data/lib/eco/api/usecases/cli/dsl.rb

@@ -3,20 +3,29 @@ module Eco
     class UseCases
       class Cli
         module DSL
-          # Links the usecase to the Cli via `option_case`
-          def apply!(option_case = cli_name)
-            cli_config_case(option_case)
-            apply_options(option_case)
-            applied!
+          # Links the usecase to the Cli via `arg_case`
+          def apply!(arg_case = cli_name)
+            #puts "DEFINING CLI for '#{arg_case}' via #{self}"
+            if applied?(arg_case)
+              puts  "Warning: (#{self}) Tried to call again cli.apply! on '#{arg_case}'"
+              return self
+            end
+            cli_config_case(arg_case)
+            apply_options(arg_case)
+            applied!(arg_case)
             self
           end
 
-          def applied?
-            @applied || false
+          def applied
+            @applied ||= {}
+          end
+
+          def applied?(arg_case)
+            applied[arg_case] || false
           end
 
-          def applied!
-            @applied = true
+          def applied!(arg_case)
+            applied[arg_case] = true
           end
 
           attr_writer :usecase
@@ -48,6 +57,7 @@ module Eco
           end
 
           def callback(&block)
+            return @callback unless block_given?
             @callback = block
           end
 
@@ -64,14 +74,14 @@ module Eco
 
           private
 
-          def apply_options(option_case)
+          def apply_options(arg_case)
             options.each do |_key, option|
-              option.link_case(cli_config_case(option_case))
+              option.link_case(cli_config_case(arg_case))
             end
           end
 
-          def cli_config_case(option_case = nil)
-            @cli_config_case ||= usecases.add(option_case, type, desc, case_name: name, &callback)
+          def cli_config_case(arg_case = nil)
+            @cli_config_case ||= usecases.add(arg_case, type, desc, case_name: name, &callback)
           end
 
           def usecases(&block)

data/lib/eco/api/usecases/default/locations/cli/tagtree_extract_cli.rb

@@ -20,5 +20,10 @@ class Eco::API::UseCases::Default::Locations::TagtreeExtract
     add_option("-with-ancestors", "Include ancestors in tree csv/excel_tree") do |options|
       options.deep_merge!(output: {include: {ancestors: true}})
     end
+
+    add_option("-indent", "Custom indentation (i.e. \"++\")") do |options|
+      indent = SCR.get_arg("-indent", with_param: true) || ""
+      options.deep_merge!(output: {indent: indent})
+    end
   end
 end

data/lib/eco/api/usecases/default/locations/tagtree_extract_case.rb

@@ -17,7 +17,7 @@ class Eco::API::UseCases::Default::Locations::TagtreeExtract < Eco::API::UseCase
     when :excel_tree, :excel_nodes
       excel(output_filename) do |workbook|
         tag_trees.each do |tree|
-          excel_sheet(workbook, tree.name.gsub(/\s+/, "_"), header: format == :excel_nodes) do |sheet|
+          excel_sheet(workbook, compact_name(tree.name), header: format == :excel_nodes) do |sheet|
             tree_extract(tree).each_with_index do |row, idx|
               sheet.append_row(row)
             end
@@ -26,7 +26,7 @@ class Eco::API::UseCases::Default::Locations::TagtreeExtract < Eco::API::UseCase
       end
     when :list, :nodes, :csv_tree, :json
       tag_trees.each do |tree|
-        file(output_filename(tree.name.gsub(/\s+/, "_"))) do |fd|
+        file(output_filename(compact_name(tree.name))) do |fd|
           fd << tree_extract(tree)
         end
       end
@@ -38,6 +38,10 @@ class Eco::API::UseCases::Default::Locations::TagtreeExtract < Eco::API::UseCase
 
   private
 
+  def compact_name(str)
+    str.gsub(/\s+/, "_")[0..30]
+  end
+
   def str_node_attrs
     options.dig(:output, :attrs) || [:id]
   end
@@ -75,6 +79,10 @@ class Eco::API::UseCases::Default::Locations::TagtreeExtract < Eco::API::UseCase
     options.dig(:output, :format)&.to_sym || :list
   end
 
+  def indentation
+    options.dig(:output, :indent) || "  "
+  end
+
   def output_file_format
     case format
     when :list; 'txt'
@@ -97,7 +105,7 @@ class Eco::API::UseCases::Default::Locations::TagtreeExtract < Eco::API::UseCase
   end
 
   def include_ancestors?
-    options.dit(:output, :include, :ancestors)
+    options.dig(:output, :include, :ancestors)
   end
 
   def include_archived?
@@ -117,7 +125,7 @@ class Eco::API::UseCases::Default::Locations::TagtreeExtract < Eco::API::UseCase
   end
 
   # Transforms the input `tree` into a String list of indented nodes
-  def to_indented_list(tree, level: 0, attrs: str_node_attrs, indent: "  ")
+  def to_indented_list(tree, level: 0, attrs: str_node_attrs, indent: indentation)
     ''.tap do |result|
       out_str   = nil
       sublevel  = tree.top?? 0 : level + 1

data/lib/eco/api/usecases/graphql/helpers/location/base.rb

@@ -23,8 +23,7 @@ module Eco::API::UseCases::GraphQL::Helpers::Location
       return unless tree
       latest_tree = tree if tree.is_a?(Eco::API::Organization::TagTree)
       if tree.respond_to?(:treeify)
-        args = {  enviro: session.enviro, id: tree.id, name: tree.name}
-        latest_tree ||= Eco::API::Organization::TagTree.new(tree.treeify, **args)
+        latest_tree ||= Eco::API::Organization::TagTree.new(tree.treeify, id: tree.id, name: tree.name)
       end
       latest_tree.tap do |_tree|
         next unless latest_tree

data/lib/eco/api/usecases/ooze_samples/helpers/creatable.rb

@@ -0,0 +1,62 @@
+module Eco
+  module API
+    class UseCases
+      class OozeSamples
+        module Helpers
+          # set of helpers to create entries from a template
+          module Creatable
+            module InstanceMethods
+              private
+
+              def creating_new_page(draft_reference = "new entry", template_id:)
+                page_id = nil
+                drafting_entry(template_id) do |draft|
+                  yield(draft) if block_given?
+
+                  if page_id = create_entry(draft, reference: draft_reference)
+                    log(:info) { "Page '#{page_id}' created successfully -- #{draft_reference}" }
+                  elsif options.dig(:dry_run)
+                    log(:info) { "Simulated launch for #{draft_reference}" }
+                  end
+                end
+                page_id
+              end
+
+              # @return [Page] a draft of `template_id` (still not saved)
+              def drafting_entry(template_id)
+                raise ArgumentError, "Expecting block, but not given" unless block_given?
+                draft = apiv2.pages.get_new(template_id)
+                yield(draft)
+              end
+
+              # Does the actual creation of the entry
+              def create_entry(draft, reference: "new entry from #{draft&.template_id}")
+                with_rescue(reference) do
+                  if result = create_ooze(draft, template_id: draft.template_id)
+                    return result.page_id
+                  end
+                end
+              end
+            end
+
+            class << self
+              def included(base)
+                super
+                validate_base_type!(base)
+                base.include(InstanceMethods)
+              end
+
+              def validate_base_type!(base)
+                return super if defined?(super)
+                msg  = "#{self} can only be included in Eco::API::UseCases::OozeSamples::RegisterUpdateCase"
+                msg << "\nCan't be included in #{base}"
+                raise LoadError, msg unless base <= Eco::API::UseCases::OozeSamples::RegisterUpdateCase
+                true
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/ooze_samples/helpers/rescuable.rb

@@ -0,0 +1,59 @@
+module Eco
+  module API
+    class UseCases
+      class OozeSamples
+        module Helpers
+          module Rescuable
+            module InstanceMethods
+              private
+
+              # Helper to prevent script from stopping
+              def with_rescue(reference)
+                raise ArgumentError, "Expecting block, but not given" unless block_given?
+                yield
+              rescue StandardError => e
+                log(:error) {
+                  [reference, e.message].join(' => \n')
+                }
+                lines = []
+                lines << "\nThere was an error. Choose one option:\n"
+                lines << "  (C)      - Continue/resume. Just ignore this one."
+                lines << "  (A)      - Abort. Just break this run."
+
+                session.prompt_user('Type one option (C/a):', explanation: lines.join("\n"), default: 'C') do |res|
+                  res = res.upcase
+                  case
+                  when res.start_with?("A")
+                    raise
+                  else res.start_with?("C")
+                    log(:warn) {
+                      msg  = "Script resumed after error..."
+                      msg << "\n  • #{reference}"
+                    }
+                    nil
+                  end
+                end
+              end
+            end
+
+            class << self
+              def included(base)
+                super
+                validate_base_type!(base)
+                base.include(InstanceMethods)
+              end
+
+              def validate_base_type!(base)
+                return super if defined?(super)
+                msg  = "#{self} can only be included in Eco::API::Common::Loaders::Base"
+                msg << "\nCan't be included in #{base}"
+                raise LoadError, msg unless base <= Eco::API::Common::Loaders::Base
+                true
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

data/lib/eco/api/usecases/ooze_samples/helpers.rb

@@ -1,5 +1,7 @@
 require_relative 'helpers/shortcuts'
 require_relative 'helpers/filters'
+require_relative 'helpers/rescuable'
+require_relative 'helpers/creatable'
 
 module Eco
   module API

data/lib/eco/api/usecases/ooze_samples/ooze_base_case.rb

@@ -4,6 +4,7 @@ class Eco::API::UseCases::OozeSamples::OozeBaseCase < Eco::API::Common::Loaders:
   type :other
 
   include Eco::API::UseCases::OozeSamples::Helpers
+  include Eco::API::UseCases::OozeSamples::Helpers::Rescuable
 
   attr_reader :target
 
@@ -145,7 +146,7 @@ class Eco::API::UseCases::OozeSamples::OozeBaseCase < Eco::API::Common::Loaders:
   # It fill update the ooze only if it's dirty (it carries changes)
   # @return [Boolean, Response] `false` if there was not request against the server, `Response` otherwise
   def update_ooze(ooze = target)
-    if options[:simulate]
+    if dry_run?
       dry_run_feedback(ooze)
       false
     else