markdown_exec 2.8.0 → 2.8.2

data/lib/hash_delegator.rb

@@ -306,7 +306,7 @@ module HashDelegatorSelf
       table__hs.each do |table_hs|
         table_hs.substrings.each do |substrings|
           substrings.each do |node|
-            next unless node[:text].class == TrackedString
+            next unless node[:text].instance_of?(TrackedString)
 
             exceeded_table_cell ||= node[:text].exceeded
             truncated_table_cell = node[:text].truncated
@@ -606,6 +606,9 @@ module MarkdownExec
 
       @process_mutex = Mutex.new
       @process_cv = ConditionVariable.new
+      @dml_link_state = Struct.new(:document_filename, :inherited_lines)
+                              .new(@delegate_object[:filename], [])
+      @dml_menu_blocks = []
 
       @p_all_arguments = []
       @p_options_parsed = []
@@ -934,7 +937,12 @@ module MarkdownExec
       end
     end
 
-    # private
+    def build_menu_options(exit_option, display_mode_option,
+                           menu_entries, display_format)
+      [exit_option,
+       display_mode_option,
+       *menu_entries.map(&display_format)].compact
+    end
 
     def build_replacement_dictionary(
       commands, link_state,
@@ -1017,25 +1025,11 @@ module MarkdownExec
       ]
     end
 
-    def neval(export_exec, inherited_code)
-      # ww0 export_exec
-      # ww0 inherited_code
-      code = (inherited_code || []) + [export_exec]
-      filespec = generate_temp_filename
-      File.write filespec, HashDelegator.join_code_lines(code)
-      File.chmod 0o755, filespec
-      # ww0 File.read(filespec)
-      ret = `#{filespec}`
-      File.delete filespec
-      ret
-    end
-
-    # sets ENV
+    # parse YAML body defining the UX for a single variable
+    # set ENV value for the variable and return code lines for the same
     def code_from_ux_block_to_set_environment_variables(
       selected, mdoc, inherited_code: nil, force: true, only_default: false
     )
-      # ww0 inherited_code
-      # ww0 mdoc
       exit_prompt = @delegate_object[:prompt_filespec_back]
 
       required = mdoc.collect_recursively_required_code(
@@ -1045,104 +1039,106 @@ module MarkdownExec
         block_source: block_source
       )
 
+      # process each ux block in sequence, setting ENV and collecting lines
       code_lines = []
-      case data = YAML.load(selected.body.join("\n"))
-      when Hash
-        export = parse_yaml_of_ux_block(
-          data,
-          prompt: @delegate_object[:prompt_ux_enter_a_value],
-          validate: '^(?<name>[^ ].*)$'
-        )
-
-        exportable = true
-        if only_default
-          value = case export.default
-                  # exec > default
-                  when :exec
-                    raise unless export.exec.present?
+      required[:blocks].each do |block|
+        next unless block.type == BlockType::UX
+
+        case data = YAML.load(block.body.join("\n"))
+        when Hash
+          export = parse_yaml_of_ux_block(
+            data,
+            prompt: @delegate_object[:prompt_ux_enter_a_value],
+            validate: '^(?<name>[^ ].*)$'
+          )
 
-                    n1 = neval(export.exec, (inherited_code || []) + required[:code])
+          # preconditions are variable names that must be set before the UX block is executed.
+          # if any precondition is not set, the sequence is aborted.
+          export.preconditions&.each do |precondition|
+            code_lines.push "[[ -z $#{precondition} ]] && exit 1"
+          end
 
-                    if export.transform.present?
-                      if export.transform.is_a? Symbol
-                        n1.send(export.transform)
-                      else
-                        format(
-                          export.transform,
-                          NamedCaptureExtractor.extract_named_groups(
-                            n1, export.validate
-                          )
-                        )
+          exportable = true
+          if only_default
+            value = case export.default
+                    # exec > default
+                    when :exec
+                      raise unless export.exec.present?
+
+                      output = export_exec_with_code(
+                        export, inherited_code, code_lines, required
+                      )
+                      if output == :invalidated
+                        return :ux_exec_prohibited
                       end
+
+                      transform_export_value(output, export)
+                    # default
                     else
-                      n1
+                      export.default.to_s
                     end
+          else
+            value = nil
 
-                  # default
-                  else
-                    export.default.to_s
-                  end
-        else
-          caps = nil
-          value = nil
-
-          # exec > allowed
-          if export.exec
-            value = neval(export.exec, (inherited_code || []) + required[:code])
-            caps = NamedCaptureExtractor.extract_named_groups(value,
-                                                              export.validate)
-
-          # allowed > prompt
-          elsif export.allowed && export.allowed.count.positive?
-            case (choice = prompt_select_code_filename(
-              [exit_prompt] + export.allowed,
-              string: export.prompt,
-              color_sym: :prompt_color_after_script_execution
-            ))
-            when exit_prompt
-              exportable = false
-            else
-              value = choice
-              caps = NamedCaptureExtractor.extract_named_groups(value,
-                                                                export.validate)
-            end
-
-          # prompt > default
-          elsif export.prompt.present?
-            begin
-              while true
-                print "#{export.prompt} [#{export.default}]: "
-                value = gets.chomp
-                value = export.default.to_s if value.empty?
-                caps = NamedCaptureExtractor.extract_named_groups(value,
-                                                                  export.validate)
-                break if caps
+            # exec > allowed
+            if export.exec
+              value = export_exec_with_code(
+                export, inherited_code, code_lines, required
+              )
+              if value == :invalidated
+                return :ux_exec_prohibited
+              end
 
-                # invalid input, retry
+            # allowed > prompt
+            elsif export.allowed && export.allowed.count.positive?
+              case (choice = prompt_select_code_filename(
+                [exit_prompt] + export.allowed,
+                string: export.prompt,
+                color_sym: :prompt_color_after_script_execution
+              ))
+              when exit_prompt
+                exportable = false
+              else
+                value = choice
+              end
 
+            # prompt > default
+            elsif export.prompt.present?
+              begin
+                loop do
+                  print "#{export.prompt} [#{export.default}]: "
+                  value = gets.chomp
+                  value = export.default.to_s if value.empty?
+                  caps = NamedCaptureExtractor.extract_named_groups(value,
+                                                                    export.validate)
+                  break if caps
+
+                  # invalid input, retry
+                end
+              rescue Interrupt
+                exportable = false
               end
-            rescue Interrupt
-              exportable = false
+
+            # default
+            else
+              value = export.default
             end
 
-          # default
-          else
-            value = export.default
+            if exportable
+              value = transform_export_value(value, export)
+            end
           end
 
-          if exportable && export.transform.present?
-            value = format(export.transform, caps)
+          if exportable
+            ENV[export.name] = value.to_s
+            code_lines.push code_line_safe_assign(export.name, value,
+                                                  force: force)
           end
+        else
+          raise "Invalid data type: #{data.inspect}"
         end
-
-        if exportable
-          ENV[export.name] = value.to_s
-          code_lines.push code_line_safe_assign(export.name, value,
-                                                force: force)
-        end
-      else
-        raise "Invalid data type: #{data.inspect}"
       end
+
       code_lines
     end
 
@@ -1167,7 +1163,6 @@ module MarkdownExec
 
     def code_line_safe_assign(name, value, force:)
       if force
-# ww0 value
         "#{name}=#{Shellwords.escape(value)}"
       else
         "[[ -z $#{name} ]] && #{name}=#{Shellwords.escape(value)}"
@@ -1216,7 +1211,8 @@ module MarkdownExec
         command_execute_in_process(
           args: args, command: command,
           erls: erls,
-          filename: @delegate_object[:filename], shell: shell
+          filename: @delegate_object[:filename],
+          shell: shell
         )
       end
 
@@ -1280,7 +1276,8 @@ module MarkdownExec
     )
       execute_command_with_streams(
         [shell, '-c', command,
-         @delegate_object[:filename], *args]
+         @delegate_object[:filename],
+         *args]
       )
     end
 
@@ -1981,19 +1978,21 @@ module MarkdownExec
         block_source: block_source
       )
 
-      # if the same menu is being displayed, collect the display name
-      #  of the selected menu item for use as the default item
-      [lfls.link_state,
-       lfls.load_file == LoadFile::LOAD ? nil : selected.dname,
-       # 2024-08-22 true to quit
-       lfls.load_file == LoadFile::EXIT]
+      # dname is not fixed for some block types, use block id
+      if lfls.load_file != LoadFile::LOAD
+        block_selection = BlockSelection.new(selected.id)
+      end
+
+      { link_state: lfls.link_state,
+        block_selection: block_selection,
+        quit: lfls.load_file == LoadFile::EXIT }
     end
 
     def execute_block_in_state(block_name)
       @dml_block_state = block_state_for_name_from_cli(block_name)
       dump_and_warn_block_state(name: block_name,
                                 selected: @dml_block_state.block)
-      @dml_link_state, @dml_menu_default_dname, quit =
+      next_block_state =
         execute_block_for_state_and_name(
           selected: @dml_block_state.block,
           mdoc: @dml_mdoc,
@@ -2005,7 +2004,10 @@ module MarkdownExec
             )
           }
         )
-      :break if quit
+
+      @dml_link_state = next_block_state[:link_state]
+      @dml_block_selection = next_block_state[:block_selection]
+      :break if next_block_state[:quit]
     end
 
     def execute_block_type_history_ux(
@@ -2152,6 +2154,7 @@ module MarkdownExec
           block_data['glob'] || glob
         )
       )
+      dirs.sort_by! { |f| File.mtime(f) }.reverse!
 
       if !contains_glob?(block_data['directory']) &&
          !contains_glob?(block_data['glob'])
@@ -2160,24 +2163,24 @@ module MarkdownExec
         else
           warn 'No matching file found.'
         end
-      elsif selected_option = select_option_with_metadata(
+      elsif (selected_option = select_option_with_metadata(
         prompt_title,
-        [exit_prompt] + dirs.sort.map do |file|
-          { name: format(
-            block_data['view'] || view,
-            NamedCaptureExtractor.extract_named_group_match_data(
-              file.match(
-                Regexp.new(block_data['filename_pattern'] ||
-                           filename_pattern)
-              )
-            )
-          ),
+        [exit_prompt] + dirs.map do |file|
+          { name:
+              format(
+                block_data['view'] || view,
+                NamedCaptureExtractor.extract_named_group_match_data(
+                  file.match(
+                    Regexp.new(block_data['filename_pattern'] || filename_pattern)
+                  )
+                )
+              ),
             oname: file }
         end,
         menu_options.merge(
           cycle: true
         )
-      )
+      ))
         if selected_option.dname != exit_prompt
           File.readlines(selected_option.oname, chomp: true)
         end
@@ -2326,50 +2329,34 @@ module MarkdownExec
     )
       # repeat select+display until user exits
 
-      pause_now = false
-      row_attrib = :row
-      loop do
-        if pause_now && (prompt_select_continue == MenuState::EXIT)
-          break
-        end
-
-        # menu with Back and Facet options at top
-        case (name = prompt_select_code_filename(
-          [exit_prompt,
-           @delegate_object[:prompt_filespec_facet]] +
-           files_table_rows.map(&row_attrib),
-          string: @delegate_object[:prompt_select_history_file],
-          color_sym: :prompt_color_after_script_execution
-        ))
-        when exit_prompt
-          break
-        when @delegate_object[:prompt_filespec_facet]
-          row_attrib = row_attrib == :row ? :file : :row
-          pause_now = false
-        else
-          file = files_table_rows.select { |ftr| ftr.row == name }&.first
-          info = file_info(file.file)
-          stream.puts "#{file.file} - #{info[:lines]} lines / " \
-                      "#{info[:size]} bytes"
-          stream.puts(
-            File.readlines(file.file,
-                           chomp: false).map.with_index do |line, ind|
-              format(' %s.  %s',
-                     AnsiString.new(format('% 4d', ind + 1)).send(:violet),
-                     line)
-            end
-          )
-          pause_now = pause_refresh
-        end
+      interactive_menu_with_display_modes(
+        files_table_rows,
+        display_formats: %i[row file],
+        display_mode_option: @delegate_object[:prompt_filespec_facet],
+        exit_option: exit_prompt,
+        menu_title: @delegate_object[:prompt_select_history_file],
+        pause_after_selection: pause_refresh
+      ) do |file|
+        info = file_info(file.file)
+        stream.puts "#{file.file} - #{info[:lines]} lines / " \
+                    "#{info[:size]} bytes"
+        stream.puts(
+          File.readlines(file.file,
+                         chomp: false).map.with_index do |line, ind|
+            format(' %s.  %s',
+                   AnsiString.new(format('% 4d', ind + 1)).send(:violet),
+                   line)
+          end
+        )
       end
     end
 
     def execute_inherited_save(
       code_lines: @dml_link_state.inherited_lines
     )
-      return unless save_filespec = save_filespec_from_expression(
-        document_name_in_glob_as_file_name
-      )
+      return unless (save_filespec = save_filespec_from_expression)
+
+      document_name_in_glob_as_file_name
 
       unless write_file_with_directory_creation(
         content: HashDelegator.join_code_lines(code_lines),
@@ -2425,6 +2412,27 @@ module MarkdownExec
       post_execution_process
     end
 
+    def execute_temporary_script(script_code, additional_code = [])
+      full_code = (additional_code || []) + [script_code]
+
+      Tempfile.create('script_exec') do |temp_file|
+        temp_file.write(HashDelegator.join_code_lines(full_code))
+        temp_file.flush
+        File.chmod(0o755, temp_file.path)
+
+        output = `#{temp_file.path}`
+
+        if $?.exitstatus != 0
+          return :invalidated
+        end
+
+        output
+      end
+    rescue StandardError => err
+      warn "Error executing script: #{err.message}"
+      nil
+    end
+
     def expand_blocks_with_replacements(
       menu_blocks, replacements, exclude_types: [BlockType::SHELL]
     )
@@ -2471,6 +2479,18 @@ module MarkdownExec
       expand_blocks_with_replacements(blocks, replacements)
     end
 
+    def export_exec_with_code(export, inherited_code, code_lines, required)
+      value = execute_temporary_script(
+        export.exec,
+        (inherited_code || []) +
+         code_lines + required[:code]
+      )
+      if value == :invalidated
+        warn "A value must exist for: #{export.preconditions.join(', ')}"
+      end
+      value
+    end
+
     # Retrieves a specific data symbol from the delegate object,
     # converts it to a string, and applies a color style
     # based on the specified color symbol.
@@ -2583,7 +2603,7 @@ module MarkdownExec
       # commands to echo variables
       #
       commands = {}
-      variable_counts.each do |variable, _count|
+      variable_counts.each_key do |variable|
         command = format(echo_format, variable)
         commands[variable] = command
       end
@@ -2640,7 +2660,6 @@ module MarkdownExec
     end
 
     def history_files(
-      link_state,
       direction: :reverse,
       filename: nil,
       home: Dir.pwd,
@@ -2679,6 +2698,56 @@ module MarkdownExec
       }
     end
 
+    def interactive_menu_with_display_modes(
+      menu_entries,
+      display_formats:,
+      display_mode_option:,
+      exit_option:,
+      menu_title:,
+      pause_after_selection:
+    )
+      pause_menu = false
+      current_display_format = display_formats.first
+
+      loop do
+        break if pause_menu && (prompt_select_continue == MenuState::EXIT)
+
+        menu_options = build_menu_options(
+          exit_option, display_mode_option,
+          menu_entries, current_display_format
+        )
+
+        selection = prompt_select_code_filename(
+          menu_options,
+          string: menu_title,
+          color_sym: :prompt_color_after_script_execution
+        )
+
+        case selection
+        when exit_option
+          break
+        when display_mode_option
+          current_display_format = next_item(
+            display_formats, current_display_format
+          )
+          pause_menu = false
+        else
+          handle_selection(menu_entries, selection,
+                           current_display_format) do |item|
+            yield item if block_given?
+          end
+          pause_menu = pause_after_selection
+        end
+      end
+    end
+
+    def handle_selection(menu_entries, selection, current_display_format)
+      selected_item = menu_entries.find do |entry|
+        entry.send(current_display_format) == selection
+      end
+      yield selected_item if selected_item
+    end
+
     # Iterates through blocks in a file, applying the provided block to each line.
     # The iteration only occurs if the file exists.
     # @yield [Symbol] :filter Yields to obtain selected messages for processing.
@@ -2903,19 +2972,24 @@ module MarkdownExec
       @ux_most_recent_filename = @delegate_object[:filename]
 
       (blocks.each.with_object([]) do |block, merged_options|
-        merged_options.push(
-          code_from_ux_block_to_set_environment_variables(
-            block,
-            mdoc,
-            force: @delegate_object[:ux_auto_load_force_default],
-            only_default: true
-          )
+        code = code_from_ux_block_to_set_environment_variables(
+          block,
+          mdoc,
+          force: @delegate_object[:ux_auto_load_force_default],
+          only_default: true
         )
+        if code == :ux_exec_prohibited
+          merged_options
+        else
+          merged_options.push(code)
+        end
       end).to_a
     end
 
-    def load_auto_vars_block(all_blocks,
-                             block_name: @delegate_object[:document_load_vars_block_name])
+    def load_auto_vars_block(
+      all_blocks,
+      block_name: @delegate_object[:document_load_vars_block_name]
+    )
       unless block_name.present? &&
              @vars_most_recent_filename != @delegate_object[:filename]
         return
@@ -3056,7 +3130,7 @@ module MarkdownExec
 
       # load document shell block
       #
-      if code_lines = load_document_shell_block(all_blocks, mdoc: mdoc)
+      if (code_lines = load_document_shell_block(all_blocks, mdoc: mdoc))
         next_state_set_code(nil, link_state, code_lines)
         link_state.inherited_lines = code_lines
         reload_blocks = true
@@ -3064,7 +3138,7 @@ module MarkdownExec
 
       # load document ux block
       #
-      if code_lines = load_auto_ux_block(all_blocks, mdoc)
+      if (code_lines = load_auto_ux_block(all_blocks, mdoc))
         new_code = HashDelegator.code_merge(link_state.inherited_lines,
                                             code_lines)
         next_state_set_code(nil, link_state, new_code)
@@ -3074,7 +3148,7 @@ module MarkdownExec
 
       # load document vars block
       #
-      if code_lines = load_auto_vars_block(all_blocks)
+      if (code_lines = load_auto_vars_block(all_blocks))
         new_code = HashDelegator.code_merge(link_state.inherited_lines,
                                             code_lines)
         next_state_set_code(nil, link_state, new_code)
@@ -3209,11 +3283,21 @@ module MarkdownExec
       end
     end
 
+    def next_item(list, current_item)
+      index = list.index(current_item)
+      return nil unless index # Return nil if the item is not in the list
+
+      list[(index + 1) % list.size] # Get the next item, wrap around if at the end
+    end
+
     def next_state_append_code(selected, link_state, code_lines)
       next_state_set_code(
         selected,
         link_state,
-        HashDelegator.code_merge(link_state&.inherited_lines, code_lines)
+        HashDelegator.code_merge(
+          link_state&.inherited_lines,
+          code_lines.is_a?(Array) ? code_lines : [] # no code for :ux_exec_prohibited
+        )
       )
     end
 
@@ -3355,8 +3439,8 @@ module MarkdownExec
     #
     # @param all_blocks [Array<Hash>] The list of blocks from the file.
     def select_blocks(menu_blocks)
-      menu_blocks.select do |fcb|
-        !Filter.prepared_not_in_menu?(
+      menu_blocks.reject do |fcb|
+        Filter.prepared_not_in_menu?(
           @delegate_object,
           fcb,
           %i[block_name_include_match block_name_wrapper_match]
@@ -3605,16 +3689,16 @@ module MarkdownExec
 
       case @delegate_object[:publish_document_file_mode]
       when 'append'
-        File.write(pipe_path, message + "\n", mode: 'a')
+        File.write(pipe_path, "#{message}\n", mode: 'a')
       when 'fifo'
         unless @vux_pipe_open
           unless File.exist?(pipe_path)
-            FileUtils.mkfifo(pipe_path)
+            File.mkfifo(pipe_path)
             @vux_pipe_created = pipe_path
           end
           @vux_pipe_open = File.open(pipe_path, 'w')
         end
-        @vux_pipe_open.puts(message + "\n")
+        @vux_pipe_open.puts("#{message}\n")
         @vux_pipe_open.flush
       when 'write'
         File.write(pipe_path, message)
@@ -3641,7 +3725,6 @@ module MarkdownExec
       regexp: @delegate_object[:saved_asset_match]
     )
       history_files(
-        @dml_link_state,
         filename:
           if asset.present?
             saved_asset_filename(asset, @dml_link_state)
@@ -3656,7 +3739,8 @@ module MarkdownExec
         end
 
         saved_asset = saved_asset_for_history(
-          file: file, form: form,
+          file: file,
+          form: form,
           match_info: $LAST_MATCH_INFO
         )
         saved_asset == :break ? nil : saved_asset
@@ -3905,7 +3989,7 @@ module MarkdownExec
 
     def screen_width
       width = @delegate_object[:screen_width]
-      if width && width.positive?
+      if width&.positive?
         width
       else
         @delegate_object[:console_width]
@@ -3922,7 +4006,7 @@ module MarkdownExec
     end
 
     def select_document_if_multiple(options, files, prompt:)
-      return files if files.class == String
+      return files if files.instance_of?(String)
       return files[0] if (count = files.count) == 1
 
       return unless count >= 2
@@ -3940,7 +4024,11 @@ module MarkdownExec
 
     # Presents a TTY prompt to select an option or exit,
     #  returns metadata including option and selected
-    def select_option_with_metadata(prompt_text, menu_items, opts = {})
+    def select_option_with_metadata(
+      prompt_text, menu_items, opts = {}, menu_blocks: nil
+    )
+      @dml_menu_blocks = menu_blocks if menu_blocks
+
       ## configure to environment
       #
       register_console_attributes(opts)
@@ -3985,23 +4073,16 @@ module MarkdownExec
         return
       end
 
-      selected = menu_items.find do |item|
+      selected = @dml_menu_blocks.find do |item|
         if item.instance_of?(Hash)
           [item[:id], item[:name], item[:dname]].include?(selection)
         elsif item.instance_of?(MarkdownExec::FCB)
-          item.dname == selection || item.id == selection
+          item.id == selection
         else
           item == selection
         end
       end
 
-      # new FCB if selected is not an object
-      if selected.instance_of?(String)
-        selected = FCB.new(dname: selected)
-      elsif selected.instance_of?(Hash)
-        selected = FCB.new(selected)
-      end
-
       unless selected
         HashDelegator.error_handler('select_option_with_metadata',
                                     error: 'menu item not found')
@@ -4111,7 +4192,7 @@ module MarkdownExec
       disabled = if fcb_title_groups.fetch(:type, '') == BlockType::YAML
                    TtyMenu::DISABLE
                  else
-                   nil
+                   TtyMenu::ENABLE
                  end
 
       MarkdownExec::FCB.new(
@@ -4152,6 +4233,21 @@ module MarkdownExec
       HashDelegator.apply_color_from_hash(string, @delegate_object, color_sym)
     end
 
+    def transform_export_value(value, export)
+      return value unless export.transform.present?
+
+      if export.transform.is_a? Symbol
+        value.send(export.transform)
+      else
+        format(
+          export.transform,
+          NamedCaptureExtractor.extract_named_groups(
+            value, export.validate
+          )
+        )
+      end
+    end
+
     ##
     # Processes an individual line within a loop, updating headings
     #  and handling fenced code blocks.
@@ -4237,11 +4333,11 @@ module MarkdownExec
       @delegate_object.merge!(options)
     end
 
-    def vux_await_user_selection
+    def vux_await_user_selection(prior_answer: @dml_block_selection)
       @dml_block_state = load_cli_or_user_selected_block(
         all_blocks: @dml_blocks_in_file,
         menu_blocks: @dml_menu_blocks,
-        prior_answer: @dml_menu_default_dname
+        prior_answer: prior_answer
       )
       if !@dml_block_state
         # HashDelegator.error_handler('block_state missing', { abort: true })
@@ -4318,7 +4414,7 @@ module MarkdownExec
 
       when formatted_choice_ostructs[:history].pub_name
         debounce_reset
-        return :break unless files_table_rows = vux_history_files_table_rows
+        return :break unless (files_table_rows = vux_history_files_table_rows)
 
         execute_history_select(files_table_rows, stream: $stderr)
         return :break if pause_user_exit
@@ -4395,7 +4491,7 @@ module MarkdownExec
         @dml_link_state.block_name.present?
       @cli_block_name = @dml_link_state.block_name
       @dml_now_using_cli = @run_state.source.block_name_from_cli
-      @dml_menu_default_dname = nil
+      @dml_block_selection = nil
       @dml_block_state = SelectedBlockMenuState.new
       @doc_saved_lines_files = []
 
@@ -4444,9 +4540,9 @@ module MarkdownExec
     end
 
     def vux_load_inherited
-      return unless filespec = load_filespec_from_expression(
+      return unless (filespec = load_filespec_from_expression(
         document_name_in_glob_as_file_name
-      )
+      ))
 
       @dml_link_state.inherited_lines_append(
         File.readlines(filespec, chomp: true)
@@ -4565,7 +4661,6 @@ module MarkdownExec
     )
       if @delegate_object[:menu_for_history]
         history_files(
-          @dml_link_state,
           filename: saved_asset_filename(@delegate_object[:filename],
                                          @dml_link_state),
           path: @delegate_object[:saved_script_folder]
@@ -4713,7 +4808,9 @@ module MarkdownExec
       else
         # puts "? - Select a block to execute (or type #{$texit}
         #  to exit):"
-        return :break if vux_await_user_selection == :break
+        return :break if vux_await_user_selection(
+          prior_answer: @dml_block_selection
+        ) == :break
         return :break if @dml_block_state.block.nil? # no block matched
       end
       # puts "! - Executing block: #{data}"
@@ -4762,9 +4859,17 @@ module MarkdownExec
                           menu_blocks.find do |block|
                             block.dname.include?(prior_answer)
                           end&.name
-                        when Struct
-                          prior_answer.index || prior_answer.name
+                        when Struct, MarkdownExec::FCB
+                          if prior_answer.id
+                            # when switching documents, the prior answer will not be found
+                            (menu_blocks.find_index do |block|
+                              block[:id] == prior_answer.id
+                            end || 0) + 1
+                          else
+                            prior_answer.index || prior_answer.name
+                          end
                         end
+
       # prior_answer value may not match if color is different from
       # originating menu (opts changed while processing)
       selection_opts = if selected_answer
@@ -5095,13 +5200,12 @@ module MarkdownExec
 
   class TestHashDelegatorAppendDivider < Minitest::Test
     def setup
-      @hd = HashDelegator.new
-      @hd.instance_variable_set(:@delegate_object, {
-                                  menu_divider_format: 'Format',
-                                  menu_initial_divider: 'Initial Divider',
-                                  menu_final_divider: 'Final Divider',
-                                  menu_divider_color: :color
-                                })
+      @hd = HashDelegator.new(
+        menu_divider_color: :color,
+        menu_divider_format: 'Format',
+        menu_final_divider: 'Final Divider',
+        menu_initial_divider: 'Initial Divider'
+      )
       @hd.stubs(:string_send_color).returns('Formatted Divider')
       HashDelegator.stubs(:safeval).returns('Safe Value')
     end
@@ -5123,7 +5227,7 @@ module MarkdownExec
     end
 
     def test_append_divider_without_format
-      @hd.instance_variable_set(:@delegate_object, {})
+      @hd = HashDelegator.new
       menu_blocks = []
       @hd.append_divider(menu_blocks: menu_blocks, position: :initial)
 
@@ -5161,7 +5265,6 @@ module MarkdownExec
       @hd = HashDelegator.new
       @hd.stubs(:iter_blocks_from_nested_files).yields(:blocks, FCB.new)
       @hd.stubs(:create_and_add_chrome_blocks)
-      @hd.instance_variable_set(:@delegate_object, {})
       HashDelegator.stubs(:error_handler)
     end
 
@@ -5172,7 +5275,7 @@ module MarkdownExec
     end
 
     def test_blocks_from_nested_files_with_no_chrome
-      @hd.instance_variable_set(:@delegate_object, { no_chrome: true })
+      @hd = HashDelegator.new(no_chrome: true)
       @hd.expects(:create_and_add_chrome_blocks).never
 
       result = @hd.blocks_from_nested_files
@@ -5184,7 +5287,6 @@ module MarkdownExec
   class TestHashDelegatorCollectRequiredCodeLines < Minitest::Test
     def setup
       @hd = HashDelegator.new
-      @hd.instance_variable_set(:@delegate_object, {})
       @mdoc = mock('YourMDocClass')
       @selected = FCB.new(
         body: ['key: value'],
@@ -5210,15 +5312,13 @@ module MarkdownExec
   class TestHashDelegatorCommandOrUserSelectedBlock < Minitest::Test
     def setup
       @hd = HashDelegator.new
-      @hd.instance_variable_set(:@delegate_object, {})
       HashDelegator.stubs(:error_handler)
       @hd.stubs(:wait_for_user_selected_block)
     end
 
     def test_command_selected_block
       all_blocks = [{ oname: 'block1' }, { oname: 'block2' }]
-      @hd.instance_variable_set(:@delegate_object,
-                                { block_name: 'block1' })
+      @hd = HashDelegator.new(block_name: 'block1')
 
       result = @hd.load_cli_or_user_selected_block(all_blocks: all_blocks)
 
@@ -5247,10 +5347,10 @@ module MarkdownExec
 
   class TestHashDelegatorCountBlockInFilename < Minitest::Test
     def setup
-      @hd = HashDelegator.new
-      @hd.instance_variable_set(:@delegate_object,
-                                { fenced_start_and_end_regex: '^```',
-                                  filename: '/path/to/file' })
+      @hd = HashDelegator.new(
+        fenced_start_and_end_regex: '^```',
+        filename: '/path/to/file'
+      )
       @hd.stubs(:cfile).returns(mock('cfile'))
     end
 
@@ -5359,7 +5459,6 @@ module MarkdownExec
     def setup
       @hd = HashDelegator.new
       @hd.instance_variable_set(:@fout, mock('fout'))
-      @hd.instance_variable_set(:@delegate_object, {})
       @hd.stubs(:string_send_color)
     end
 
@@ -5381,7 +5480,6 @@ module MarkdownExec
   class TestHashDelegatorFetchColor < Minitest::Test
     def setup
       @hd = HashDelegator.new
-      @hd.instance_variable_set(:@delegate_object, {})
     end
 
     def test_fetch_color_with_valid_data
@@ -5414,7 +5512,6 @@ module MarkdownExec
   class TestHashDelegatorFormatReferencesSendColor < Minitest::Test
     def setup
       @hd = HashDelegator.new
-      @hd.instance_variable_set(:@delegate_object, {})
     end
 
     def test_format_references_send_color_with_valid_data
@@ -5519,7 +5616,6 @@ module MarkdownExec
     # )
 
     # def history_files(
-    #   link_state,
     #   direction: :reverse,
     #   filename: nil,
     #   home: Dir.pwd,
@@ -5528,9 +5624,10 @@ module MarkdownExec
     # )
 
     def test_call
-      @hd.expects(:history_files).with(nil, filename: '*', path: nil).once
-      @hd.execute_block_type_history_ux(filename: '*', link_state: LinkState.new,
-                                        selected: FCB.new(body: []))
+      @hd.expects(:history_files).with(filename: '*', path: nil).once
+      @hd.execute_block_type_history_ux(
+        filename: '*', link_state: LinkState.new, selected: FCB.new(body: [])
+      )
     end
   end
 
@@ -5615,11 +5712,9 @@ module MarkdownExec
 
   class TestHashDelegatorHandleStream < Minitest::Test
     def setup
-      @hd = HashDelegator.new
+      @hd = HashDelegator.new(output_stdout: true)
       @hd.instance_variable_set(:@run_state,
                                 OpenStruct.new(files: StreamsOut.new))
-      @hd.instance_variable_set(:@delegate_object,
-                                { output_stdout: true })
     end
 
     def test_handle_stream
@@ -5651,9 +5746,7 @@ module MarkdownExec
 
   class TestHashDelegatorIterBlocksFromNestedFiles < Minitest::Test
     def setup
-      @hd = HashDelegator.new
-      @hd.instance_variable_set(:@delegate_object,
-                                { filename: 'test.md' })
+      @hd = HashDelegator.new(filename: 'test.md')
       @hd.stubs(:check_file_existence).with('test.md').returns(true)
       @hd.stubs(:initial_state).returns({})
       @hd.stubs(:cfile).returns(Minitest::Mock.new)
@@ -5682,12 +5775,11 @@ module MarkdownExec
 
   class TestHashDelegatorMenuChromeColoredOption < Minitest::Test
     def setup
-      @hd = HashDelegator.new
-      @hd.instance_variable_set(:@delegate_object, {
-                                  menu_option_back_name: 'Back',
-                                  menu_chrome_color: :red,
-                                  menu_chrome_format: '-- %s --'
-                                })
+      @hd = HashDelegator.new(
+        menu_chrome_color: :red,
+        menu_chrome_format: '-- %s --',
+        menu_option_back_name: 'Back'
+      )
       @hd.stubs(:menu_chrome_formatted_option)
          .with(:menu_option_back_name).returns('-- Back --')
       @hd.stubs(:string_send_color)
@@ -5701,8 +5793,9 @@ module MarkdownExec
     end
 
     def test_menu_chrome_colored_option_without_color
-      @hd.instance_variable_set(:@delegate_object,
-                                { menu_option_back_name: 'Back' })
+      @hd = HashDelegator.new(menu_option_back_name: 'Back')
+      @hd.stubs(:menu_chrome_formatted_option)
+         .with(:menu_option_back_name).returns('-- Back --')
       assert_equal '-- Back --',
                    @hd.menu_chrome_colored_option(:menu_option_back_name)
     end
@@ -5710,11 +5803,10 @@ module MarkdownExec
 
   class TestHashDelegatorMenuChromeOption < Minitest::Test
     def setup
-      @hd = HashDelegator.new
-      @hd.instance_variable_set(:@delegate_object, {
-                                  menu_option_back_name: "'Back'",
-                                  menu_chrome_format: '-- %s --'
-                                })
+      @hd = HashDelegator.new(
+        menu_chrome_format: '-- %s --',
+        menu_option_back_name: "'Back'"
+      )
       HashDelegator.stubs(:safeval).with("'Back'").returns('Back')
     end
 
@@ -5724,8 +5816,7 @@ module MarkdownExec
     end
 
     def test_menu_chrome_formatted_option_without_format
-      @hd.instance_variable_set(:@delegate_object,
-                                { menu_option_back_name: "'Back'" })
+      @hd = HashDelegator.new(menu_option_back_name: "'Back'")
       assert_equal 'Back',
                    @hd.menu_chrome_formatted_option(:menu_option_back_name)
     end
@@ -5733,10 +5824,12 @@ module MarkdownExec
 
   class TestHashDelegatorStartFencedBlock < Minitest::Test
     def setup
-      @hd = HashDelegator.new({
-                                block_name_wrapper_match: 'WRAPPER_REGEX',
-                                block_calls_scan: 'CALLS_REGEX'
-                              })
+      @hd = HashDelegator.new(
+        {
+          block_calls_scan: 'CALLS_REGEX',
+          block_name_wrapper_match: 'WRAPPER_REGEX'
+        }
+      )
     end
 
     def test_start_fenced_block
@@ -5754,9 +5847,7 @@ module MarkdownExec
 
   class TestHashDelegatorStringSendColor < Minitest::Test
     def setup
-      @hd = HashDelegator.new
-      @hd.instance_variable_set(:@delegate_object,
-                                { red: 'red', green: 'green' })
+      @hd = HashDelegator.new(red: 'red', green: 'green')
     end
 
     def test_string_send_color