markdown_exec 3.1.1 → 3.3.0

data/lib/hash_delegator.rb

@@ -97,6 +97,33 @@ module HashDelegatorSelf
     blocks.select { |item| item.send(msg) == value }
   end
 
+  def chrome_block_criteria
+    [
+      { center: :table_center,         format: :menu_note_format,
+        match: :table_row_multi_line_match, type: BlockType::TEXT },
+      { case_conversion: :upcase,      center: :heading1_center,
+        collapse: :heading1_collapse,  collapsible: :heading1_collapsible,
+        color: :menu_heading1_color,   format: :menu_heading1_format,      level: 1,
+        match: :heading1_match,        type: BlockType::HEADING,           wrap: true },
+      { center: :heading2_center,
+        collapse: :heading2_collapse,  collapsible: :heading2_collapsible,
+        color: :menu_heading2_color,   format: :menu_heading2_format,      level: 2,
+        match: :heading2_match,        type: BlockType::HEADING,           wrap: true },
+      { case_conversion: :downcase,    center: :heading3_center,
+        collapse: :heading3_collapse,  collapsible: :heading3_collapsible,
+        color: :menu_heading3_color,   format: :menu_heading3_format,      level: 3,
+        match: :heading3_match,        type: BlockType::HEADING,           wrap: true },
+      { center: :divider4_center,
+        collapse: :divider4_collapse, collapsible: :divider4_collapsible,
+        color: :menu_divider_color,    format: :menu_divider_format, level: 4,
+        match: :divider_match,         type: BlockType::DIVIDER                       },
+      { color: :menu_note_color,       format: :menu_note_format,
+        match: :menu_note_match,       type: BlockType::TEXT,              wrap: true },
+      { color: :menu_task_color,       format: :menu_task_format,
+        match: :menu_task_match,       type: BlockType::TEXT,              wrap: true }
+    ]
+  end
+
   def count_matches_in_lines(lines, regex)
     lines.count { |line| line.to_s.match(regex) }
   end
@@ -274,7 +301,9 @@ module HashDelegatorSelf
     lines = blocks_menu.map(&:oname)
     text_tables = TableExtractor.extract_tables(
       lines,
-      regexp: delegate_object[:table_parse_regexp]
+      regexp: delegate_object[:table_parse_regexp],
+      multi_line_delimiter: delegate_object[:table_row_multi_line_delimiter],
+      single_line_delimiter: delegate_object[:table_row_single_line_delimiter]
     )
     return unless text_tables.count.positive?
 
@@ -287,11 +316,16 @@ module HashDelegatorSelf
         column_count: table[:columns],
         decorate: {
           border: delegate_object[:table_border_color],
-          header_row: delegate_object[:table_header_row_color],
+          header_row: if table[:rows] == 1
+                        delegate_object[:table_row_color]
+                      else
+                        delegate_object[:table_header_row_color]
+                      end,
           row: delegate_object[:table_row_color],
           separator_line: delegate_object[:table_separator_line_color]
         },
         lines: lines,
+        table: table,
         table_width: screen_width_for_table,
         truncate: $table_cell_truncate
       )
@@ -390,11 +424,22 @@ module HashDelegatorSelf
   # @param [String] line The line to be processed.
   # @param [Array<Symbol>] selected_types A list of message types to check.
   # @param [Proc] block The block to be called with the line data.
-  def yield_line_if_selected(line, selected_types, all_fcbs: nil,
-                             source_id: '', &block)
+  def yield_line_if_selected(
+    line, selected_types, all_fcbs: nil,
+    criteria: nil, source_id: '', &block
+  )
     return unless block && block_type_selected?(selected_types, :line)
 
-    block.call(:line, persist_fcb_self(all_fcbs, body: [line], id: source_id))
+    opts = {
+      body: [line],
+      id: source_id
+    }
+    # add style if it is a single line table
+    opts[:criteria] = criteria if criteria
+
+    block.call(:line, persist_fcb_self(all_fcbs, opts))
+  rescue StandardError
+    wwe 'YAML loading error', { body: body, error: $! }
   end
 
   def persist_fcb_self(all_fcbs, options)
@@ -626,6 +671,8 @@ module MarkdownExec
 
       @compressed_ids = {}
       @expanded_ids = {}
+    rescue StandardError
+      wwe $!
     end
 
     ##
@@ -709,6 +756,22 @@ module MarkdownExec
       )
     end
 
+    def annotate_required_lines(name, lines, block_name:)
+      if @delegate_object[:required_lines_with_source_comments] && !lines.empty?
+        formatted = formatted_block_name(block_name,
+                                         :script_comment_block_name_format)
+        ['',
+         "#‡¯¯¯ #{name} ¯¯¯ #{formatted}",
+         '',
+         *lines,
+         '',
+         "#‡___ #{name} ___ #{formatted}",
+         '']
+      else
+        lines || []
+      end
+    end
+
     # Appends a chrome block, which is a menu option for Back or Exit
     #
     # @param all_blocks [Array] The current blocks in the menu
@@ -819,6 +882,7 @@ module MarkdownExec
     # @param block_type_color_option [Symbol, nil] The shell color option to apply.
     # @return [String] The colorized or original name string.
     def apply_block_type_color_option(name, block_type_color_option)
+      ### accept string for color
       if block_type_color_option && @delegate_object[block_type_color_option].present?
         string_send_color(name, block_type_color_option)
       else
@@ -866,6 +930,7 @@ module MarkdownExec
       results = {}
       iter_blocks_from_nested_files do |btype, fcb|
         count += 1
+        wwt :iter, 'count:', count, 'btype:', btype, 'fcb.id:', fcb&.id
         case btype
         when :blocks
           result = SuccessResult.instance
@@ -903,7 +968,11 @@ module MarkdownExec
                       center: fcb0.center,
                       chrome: true,
                       collapse: false,
-                      disabled: is_enabled_but_inactive ? TtyMenu::ENABLE : TtyMenu::DISABLE,
+                      disabled: if is_enabled_but_inactive
+                                  TtyMenu::ENABLE
+                                else
+                                  TtyMenu::DISABLE
+                                end,
                       dname: fcb0.indent + menu_line,
                       id: "#{id_prefix}#{index}",
                       indent: fcb0.indent,
@@ -922,9 +991,11 @@ module MarkdownExec
                   end
 
                   result = fcb.for_menu!(
+                    appopts: @delegate_object,
                     block_calls_scan: @delegate_object[:block_calls_scan],
                     block_name_match: @delegate_object[:block_name_match],
-                    block_name_nick_match: @delegate_object[:block_name_nick_match],
+                    block_name_nick_match:
+                      @delegate_object[:block_name_nick_match],
                     id: fcb.id,
                     menu_format: @delegate_object[:menu_ux_row_format],
                     prompt: @delegate_object[:prompt_ux_enter_a_value],
@@ -939,9 +1010,11 @@ module MarkdownExec
               else
                 # prepare block for menu, may fail and call HashDelegator.error_handler
                 result = fcb.for_menu!(
+                  appopts: @delegate_object,
                   block_calls_scan: @delegate_object[:block_calls_scan],
                   block_name_match: @delegate_object[:block_name_match],
-                  block_name_nick_match: @delegate_object[:block_name_nick_match],
+                  block_name_nick_match:
+                    @delegate_object[:block_name_nick_match],
                   id: fcb.id,
                   menu_format: @delegate_object[:menu_ux_row_format],
                   prompt: @delegate_object[:prompt_ux_enter_a_value],
@@ -978,7 +1051,7 @@ module MarkdownExec
       end
       OpenStruct.new(blocks: blocks, results: results)
     rescue StandardError
-      wwe 'link_state:', link_state, 'source_id:', source_id, 'btype:', btype,
+      wwe $!, 'link_state:', link_state, 'source_id:', source_id, 'btype:', btype,
           'fcb:', fcb
     end
 
@@ -1027,7 +1100,28 @@ module MarkdownExec
 
     def cfile
       @cfile ||= CachedNestedFileReader.new(
-        import_pattern: @delegate_object.fetch(:import_pattern) #, "^ *@import +(?<name>.+?) *$")
+        import_directive_line_pattern:
+          @delegate_object.fetch(:import_directive_line_pattern),
+        import_directive_parameter_scan:
+          Regexp.new(
+            @delegate_object.fetch(:import_directive_parameter_scan, '')
+          ),
+        import_parameter_variable_assignment:
+          @delegate_object[:import_parameter_variable_assignment],
+        shell:
+          @delegate_object[:shell],
+        shell_block_name:
+          @delegate_object[:document_load_shell_block_name],
+        symbol_command_substitution:
+          @delegate_object[:import_symbol_command_substitution],
+        symbol_evaluated_expression:
+          @delegate_object[:import_symbol_evaluated_expression],
+        symbol_force_quoted_literal:
+          @delegate_object[:import_symbol_force_quoted_literal],
+        symbol_raw_literal:
+          @delegate_object[:import_symbol_raw_literal],
+        symbol_variable_reference:
+          @delegate_object[:import_symbol_variable_reference]
       )
     end
 
@@ -1045,48 +1139,130 @@ module MarkdownExec
       true
     end
 
-    def chrome_block_criteria
-      [
-        { center: :table_center,         format: :menu_note_format,
-          match: :menu_table_rows_match, type: BlockType::TEXT },
-        { case_conversion: :upcase,      center: :heading1_center,
-          collapse: :heading1_collapse,  collapsible: :heading1_collapsible,
-          color: :menu_heading1_color,   format: :menu_heading1_format,      level: 1,
-          match: :heading1_match,        type: BlockType::HEADING,           wrap: true },
-        { center: :heading2_center,
-          collapse: :heading2_collapse,  collapsible: :heading2_collapsible,
-          color: :menu_heading2_color,   format: :menu_heading2_format,      level: 2,
-          match: :heading2_match,        type: BlockType::HEADING,           wrap: true },
-        { case_conversion: :downcase,    center: :heading3_center,
-          collapse: :heading3_collapse,  collapsible: :heading3_collapsible,
-          color: :menu_heading3_color,   format: :menu_heading3_format,      level: 3,
-          match: :heading3_match,        type: BlockType::HEADING,           wrap: true },
-        { center: :divider4_center,
-          collapse: :divider4_collapse, collapsible: :divider4_collapsible,
-          color: :menu_divider_color,    format: :menu_divider_format, level: 4,
-          match: :divider_match,         type: BlockType::DIVIDER                       },
-        { color: :menu_note_color,       format: :menu_note_format,
-          match: :menu_note_match,       type: BlockType::TEXT,              wrap: true },
-        { color: :menu_task_color,       format: :menu_task_format,
-          match: :menu_task_match,       type: BlockType::TEXT,              wrap: true }
-      ]
+    # return code resulting from evaluating all automatic blocks in order
+    def code_from_auto_blocks(all_blocks, mdoc: nil, default_only: true)
+      shell_block_name = @delegate_object[:document_load_shell_block_name]
+      vars_block_name = @delegate_object[:document_load_vars_block_name]
+
+      # do not reload the same document
+      read_shell = @shell_most_recent_filename != @delegate_object[:filename]
+      read_ux = @ux_most_recent_filename != @delegate_object[:filename]
+      read_vars = @vars_most_recent_filename != @delegate_object[:filename]
+      @shell_most_recent_filename = @delegate_object[:filename]
+      @ux_most_recent_filename = @delegate_object[:filename]
+      @vars_most_recent_filename = @delegate_object[:filename]
+
+      all_code = []
+      all_blocks.each do |fcb|
+        block_code = []
+        if fcb.oname == shell_block_name
+          if read_shell
+            # collect code from shell block
+            code = if mdoc
+                     mdoc.collect_recursively_required_code(
+                       anyname: fcb.id,
+                       ### anyname: fcb.pub_name,
+                       label_format_above:
+                         @delegate_object[:shell_code_label_format_above],
+                       label_format_below:
+                         @delegate_object[:shell_code_label_format_below],
+                       block_source: block_source
+                     )[:code]
+                   else
+                     fcb.body
+                   end
+            block_code = annotate_required_lines('blk:SHELL', code,
+                                                 block_name: fcb.id)
+          end
+        elsif fcb.oname == vars_block_name
+          if read_vars
+            block_code = code_from_vars_block_to_set_environment_variables(fcb)
+          end
+        elsif fcb.type == 'ux'
+          if !read_ux
+            # skip
+          elsif fcb.is_split_rest?
+            # ignore
+          else
+            command_result_w_e_t_nl =
+              code_from_ux_block_to_set_environment_variables(
+                fcb,
+                mdoc,
+                force: @delegate_object[:ux_auto_load_force_default],
+                only_default: default_only,
+                silent: true
+              )
+            block_code = if command_result_w_e_t_nl&.success?
+                           command_result_w_e_t_nl.new_lines
+                         else
+                           []
+                         end
+          end
+
+        else
+          # do nothing
+        end
+
+        wwt :code, 'block_code:', block_code unless block_code&.empty?
+        all_code += block_code
+      end
+
+      all_code.tap { wwt :code, _1 }
+    rescue StandardError
+      wwe 'all_blocks.count:', all_blocks.count
     end
 
-    def code_from_automatic_ux_blocks(
+    # return code resulting from evaluating all automatic SHELL blocks in order
+    def code_from_auto_shell_blocks(all_blocks, mdoc: nil)
+      # a block name is required
+      # do not reload the most recent filename
+      block_name = @delegate_object[:document_load_shell_block_name]
+      unless block_name.present? &&
+             @shell_most_recent_filename != @delegate_object[:filename]
+        return
+      end
+
+      @shell_most_recent_filename = @delegate_object[:filename]
+
+      # select the first block with the given name
+      fcb = HashDelegator.block_find(all_blocks, :oname, block_name)
+      return unless fcb
+
+      # collect code from shell block
+      code = if mdoc
+               mdoc.collect_recursively_required_code(
+                 anyname: fcb.pub_name,
+                 label_format_above:
+                   @delegate_object[:shell_code_label_format_above],
+                 label_format_below:
+                   @delegate_object[:shell_code_label_format_below],
+                 block_source: block_source
+               )[:code]
+             else
+               fcb.body
+             end
+      annotate_required_lines('blk:SHELL', code, block_name: fcb.id)
+    end
+
+    # return code resulting from evaluating all UX blocks in order
+    def code_from_auto_ux_blocks(
       all_blocks,
       mdoc
     )
+      # do not reload the most recent filename
       unless @ux_most_recent_filename != @delegate_object[:filename]
         return
       end
 
+      @ux_most_recent_filename = @delegate_object[:filename]
+
+      # select all UX blocks, rejecting non-primary split
       blocks = select_automatic_ux_blocks(
         all_blocks.reject(&:is_split_rest?)
       )
       return if blocks.empty?
 
-      @ux_most_recent_filename = @delegate_object[:filename]
-
+      # collect code from all ux blocks
       (blocks.each.with_object([]) do |block, merged_options|
         command_result_w_e_t_nl =
           code_from_ux_block_to_set_environment_variables(
@@ -1097,6 +1273,7 @@ module MarkdownExec
             silent: true
           )
         if command_result_w_e_t_nl.failure?
+          # if a block fails, proceed with next block
           merged_options
         else
           merged_options.push(command_result_w_e_t_nl.new_lines)
@@ -1104,8 +1281,39 @@ module MarkdownExec
       end).to_a
     end
 
+    # return code resulting from evaluating all automatic VARS blocks in order
+    def code_from_auto_vars_blocks(
+      all_blocks,
+      block_name: @delegate_object[:document_load_vars_block_name]
+    )
+      # a block name is required
+      # do not reload the most recent filename
+      unless block_name.present? &&
+             @vars_most_recent_filename != @delegate_object[:filename]
+        return
+      end
+
+      @vars_most_recent_filename = @delegate_object[:filename]
+
+      # select all blocks with the given name
+      blocks = HashDelegator.block_select(all_blocks, :oname, block_name)
+      return if blocks.empty?
+
+      # collect code for vars from all blocks
+      (blocks.each.with_object([]) do |block, merged_options|
+        merged_options.push(
+          code_from_vars_block_to_set_environment_variables(block)
+        )
+      end).to_a
+    end
+
+    def selected_id_name(selected)
+      selected.id
+    end
+
     # parse YAML body defining the UX for a single variable
     # set ENV value for the variable and return code lines for the same
+    # for BlockType::UX
     def code_from_ux_block_to_set_environment_variables(
       selected, mdoc, inherited_code: nil, force: true, only_default: false,
       silent:
@@ -1115,7 +1323,7 @@ module MarkdownExec
       exit_prompt = @delegate_object[:prompt_filespec_back]
 
       required = mdoc.collect_recursively_required_code(
-        anyname: selected.pub_name,
+        anyname: selected_id_name(selected),
         label_format_above: @delegate_object[:shell_code_label_format_above],
         label_format_below: @delegate_object[:shell_code_label_format_below],
         block_source: block_source
@@ -1129,7 +1337,8 @@ module MarkdownExec
 
         wwt :fcb, 'a required block', block
 
-        case data = safe_yaml_load(block.body.join("\n"))
+        body1 = block.raw_body || block.body
+        case data = safe_yaml_load(body1.join("\n"))
         when Hash
           export = parse_yaml_of_ux_block(
             data,
@@ -1146,6 +1355,8 @@ module MarkdownExec
           export.required&.each do |precondition|
             required_variables.push "[[ -z $#{precondition} ]] && exit #{EXIT_STATUS_REQUIRED_EMPTY}"
           end
+          wwt :required_variables, 'required_variables',
+              required_variables
 
           eval_code = join_array_of_arrays(
             inherited_code, # inherited code
@@ -1153,6 +1364,7 @@ module MarkdownExec
             required_variables, # test conditions
             required[:code] # current block code
           )
+          wwt :eval_code, 'eval_code:', eval_code
           if only_default
             command_result_w_e_t_nl =
               ux_block_export_automatic(eval_code, export)
@@ -1163,7 +1375,9 @@ module MarkdownExec
             command_result_w_e_t_nl =
               ux_block_export_activated(eval_code, export, exit_prompt)
             if command_result_w_e_t_nl.failure?
-              warn command_result_w_e_t_nl.warning if command_result_w_e_t_nl.warning&.present? && !silent
+              if command_result_w_e_t_nl.warning&.present? && !silent
+                warn command_result_w_e_t_nl.warning
+              end
               return command_result_w_e_t_nl
             end
           end
@@ -1174,25 +1388,35 @@ module MarkdownExec
             process_command_result_lines(command_result_w_e_t_nl, export,
                                          required_lines)
           required_lines.concat(command_result_w_e_t_nl.new_lines)
+
+          required_lines = annotate_required_lines(
+            'blk:UX', required_lines, block_name: selected.id
+          )
+
           command_result_w_e_t_nl.new_lines = required_lines
           ret_command_result = command_result_w_e_t_nl
         else
           raise "Invalid data type: #{data.inspect}"
         end
       end
+      wwt :required_lines, required_lines
 
-      (ret_command_result || CommandResult.new(stdout: required_lines)).tap do |ret|
-        wwt :cr, ret
+      (ret_command_result || CommandResult.new(
+        stdout: annotate_required_lines(
+          'blk:UX', required_lines, block_name: selected.id
+        )
+      )).tap do |ret|
+        wwt :cr, ret, caller.deref
       end
     rescue StandardError
       wwe 'selected:', selected, 'required:', required, 'block:', block,
           'data:', data
     end
 
+    # def
     # sets ENV
     def code_from_vars_block_to_set_environment_variables(selected)
       code_lines = []
-      # code_lines << '# code_from_vars_block_to_set_environment_variables'
       case data = YAML.load(selected.body.join("\n"))
       when Hash
         data.each do |key, value|
@@ -1201,12 +1425,15 @@ module MarkdownExec
 
           next unless @delegate_object[:menu_vars_set_format].present?
 
+          # in-menu display
           formatted_string = format(@delegate_object[:menu_vars_set_format],
                                     { key: key, value: value })
+
+          # activity dump
           print string_send_color(formatted_string, :menu_vars_set_color)
         end
       end
-      code_lines
+      annotate_required_lines('blk:VARS', code_lines, block_name: selected.id)
     rescue StandardError
       wwe 'selected:', selected, 'data:', data, 'key:', key, 'value:', value,
           'code_lines:', code_lines, 'formatted_string:', formatted_string
@@ -1386,7 +1613,7 @@ module MarkdownExec
 
       if allow_execution
         execute_required_lines(
-          blockname: selected.pub_name,
+          blockname: selected_id_name(selected),
           erls: { play_bin: play_bin,
                   shell: selected_shell(selected.shell) },
           required_lines: required_lines,
@@ -1513,7 +1740,9 @@ module MarkdownExec
       if wrap
         line_caps = line_caps.flat_map do |line_cap|
           text = line_cap[:text]
-          wrapper = StringWrapper.new(width: screen_width_for_wrapping - line_cap[:indent].length)
+          wrapper = StringWrapper.new(
+            width: screen_width_for_wrapping - line_cap[:indent].length
+          )
 
           if text.length > screen_width_for_wrapping
             # Wrap this text and create line_cap objects for each part
@@ -1559,13 +1788,16 @@ module MarkdownExec
         decorated = apply_tree_decorations(
           oname, color_method, decor_patterns
         )
-
         line_obj[:line] = line_obj[:indent] + line_obj[:text]
 
         if use_fcb
           fcb.center = center
           fcb.chrome = true
-          fcb.collapse = collapse.nil? ? (line_obj[:collapse] == COLLAPSIBLE_TOKEN_COLLAPSE) : collapse
+          fcb.collapse = if collapse.nil?
+                           (line_obj[:collapse] == COLLAPSIBLE_TOKEN_COLLAPSE)
+                         else
+                           collapse
+                         end
           fcb.disabled = disabled ? TtyMenu::DISABLE : nil
           fcb.dname = line_obj[:indent] + decorated
           fcb.id = "#{id}.#{index}"
@@ -1583,7 +1815,12 @@ module MarkdownExec
           fcb = persist_fcb(
             center: center,
             chrome: true,
-            collapse: collapse.nil? ? (line_obj[:collapse] == COLLAPSIBLE_TOKEN_COLLAPSE) : collapse,
+            collapse:
+              if collapse.nil?
+                (line_obj[:collapse] == COLLAPSIBLE_TOKEN_COLLAPSE)
+              else
+                collapse
+              end,
             disabled: disabled ? TtyMenu::DISABLE : nil,
             dname: line_obj[:indent] + decorated,
             id: "#{id}.#{index}",
@@ -1613,53 +1850,65 @@ module MarkdownExec
     # @param use_chrome [Boolean] Indicates if the chrome styling should
     #  be applied.
     def create_and_add_chrome_blocks(blocks, fcb, id: '', init_ids: false)
-      chrome_block_criteria.each_with_index do |criteria, index|
-        unless @delegate_object[criteria[:match]].present? &&
-               (mbody = fcb.body[0].match @delegate_object[criteria[:match]])
-          next
+      index = nil
+
+      unless (criteria = fcb.criteria)
+        HashDelegator.chrome_block_criteria.each_with_index do |criteria1, index1|
+          # rubocop:disable Lint/UselessAssignment
+          if !@delegate_object[criteria1[:match]].present? ||
+             !(match_data = fcb.body[0].match @delegate_object[criteria1[:match]])
+            next
+          end
+          # rubocop:enable Lint/UselessAssignment
+
+          criteria = criteria1
+          index = index1
+          break
         end
+      end
 
-        if block_given?
-          # expand references only if block is recognized (not a comment)
-          yield if block_given?
+      return unless criteria
 
-          # parse multiline to capture output of variable expansion
-          mbody = fcb.body[0].match Regexp.new(
-            @delegate_object[criteria[:match]], Regexp::MULTILINE
-          )
-        end
+      if block_given?
+        # expand references only if block is recognized (not a comment)
+        yield if block_given?
 
-        create_and_add_chrome_block(
-          blocks: blocks,
-          case_conversion: criteria[:case_conversion],
-          center: criteria[:center] &&
-                  @delegate_object[criteria[:center]],
-
-          collapse: case fcb.collapse_token
-                    when COLLAPSIBLE_TOKEN_COLLAPSE
-                      true
-                    when COLLAPSIBLE_TOKEN_EXPAND
-                      false
-                    else
-                      false
-                    end,
-
-          color_method: criteria[:color] &&
-                        @delegate_object[criteria[:color]].to_sym,
-          decor_patterns:
-            @decor_patterns_from_delegate_object_for_block_create,
-          disabled: !(criteria[:collapsible] && @delegate_object[criteria[:collapsible]]),
-          fcb: fcb,
-          id: "#{id}.#{index}",
-          format_option: criteria[:format] &&
-                         @delegate_object[criteria[:format]],
-          level: criteria[:level],
-          match_data: mbody,
-          type: criteria[:type],
-          wrap: criteria[:wrap]
+        # parse multiline to capture output of variable expansion
+        match_data = fcb.body[0].match Regexp.new(
+          @delegate_object[criteria[:match]], Regexp::MULTILINE
         )
-        break
       end
+
+      create_and_add_chrome_block(
+        blocks: blocks,
+        case_conversion: criteria[:case_conversion],
+        center: criteria[:center] &&
+                @delegate_object[criteria[:center]],
+
+        collapse: case fcb.collapse_token
+                  when COLLAPSIBLE_TOKEN_COLLAPSE
+                    true
+                  when COLLAPSIBLE_TOKEN_EXPAND
+                    false
+                  else
+                    false
+                  end,
+
+        color_method: criteria[:color] &&
+                      @delegate_object[criteria[:color]].to_sym,
+        decor_patterns:
+          @decor_patterns_from_delegate_object_for_block_create,
+        disabled: !(criteria[:collapsible] &&
+                    @delegate_object[criteria[:collapsible]]),
+        fcb: fcb,
+        id: "#{id}.#{index}",
+        format_option: criteria[:format] &&
+                       @delegate_object[criteria[:format]],
+        level: criteria[:level],
+        match_data: match_data,
+        type: criteria[:type],
+        wrap: criteria[:wrap]
+      )
     end
 
     def create_divider(position, source_id: '')
@@ -1668,8 +1917,10 @@ module MarkdownExec
                     else
                       :menu_final_divider
                     end
-      oname = format(@delegate_object[:menu_divider_format],
-                     HashDelegator.safeval(@delegate_object[divider_key]))
+      oname = format(
+        @delegate_object[:menu_divider_format],
+        HashDelegator.safeval(@delegate_object[divider_key])
+      )
 
       persist_fcb(
         chrome: true,
@@ -1996,11 +2247,6 @@ module MarkdownExec
 
         LoadFileLinkState.new(LoadFile::REUSE, link_state)
 
-      # from CLI
-      elsif selected.nickname == @delegate_object[:menu_option_exit_name][:line]
-        debounce_reset
-        LoadFileLinkState.new(LoadFile::EXIT, link_state)
-
       elsif @menu_user_clicked_back_link
         debounce_reset
         LoadFileLinkState.new(
@@ -2037,6 +2283,7 @@ module MarkdownExec
           selected,
           @dml_mdoc,
           inherited_code: @dml_link_state.inherited_lines,
+          only_default: false,
           silent: true
         )
         ### TBD if command_result_w_e_t_nl.failure?
@@ -2154,16 +2401,19 @@ module MarkdownExec
       link_state: LinkState.new, block_source: {}
     )
       link_block_data = HashDelegator.parse_yaml_data_from_body(link_block_body)
+
       ## collect blocks specified by block
       #
       if mdoc
         code_info = mdoc.collect_recursively_required_code(
-          anyname: selected.pub_name,
+          anyname: selected_id_name(selected),
+          block_source: block_source,
           label_format_above: @delegate_object[:shell_code_label_format_above],
-          label_format_below: @delegate_object[:shell_code_label_format_below],
-          block_source: block_source
+          label_format_below: @delegate_object[:shell_code_label_format_below]
+        )
+        code_lines = annotate_required_lines(
+          'blk:LINK', code_info[:code], block_name: selected.id
         )
-        code_lines = code_info[:code]
         block_names = code_info[:block_names]
         dependencies = code_info[:dependencies]
       else
@@ -2198,9 +2448,8 @@ module MarkdownExec
 
       # if an eval link block, evaluate code_lines and return its standard output
       #
-      if link_block_data.fetch(LinkKeys::EVAL,
-                               false) || link_block_data.fetch(LinkKeys::EXEC,
-                                                               false)
+      if link_block_data.fetch(LinkKeys::EVAL, false) ||
+         link_block_data.fetch(LinkKeys::EXEC, false)
         code_lines += link_block_data_eval(
           link_state, code_lines, selected, link_block_data,
           block_source: block_source,
@@ -2217,6 +2466,10 @@ module MarkdownExec
         nil
       ) || link_block_data.fetch(LinkKeys::BLOCK, nil) || ''
 
+      code_lines = annotate_required_lines(
+        'blk:LINK', code_lines, block_name: selected.id
+      )
+
       if link_block_data[LinkKeys::RETURN]
         pop_add_current_code_to_head_and_trigger_load(
           link_state, block_names, code_lines,
@@ -2229,9 +2482,9 @@ module MarkdownExec
           curr_block_name: selected.pub_name,
           curr_document_filename: @delegate_object[:filename],
           inherited_block_names:
-           ((link_state&.inherited_block_names || []) + block_names).sort.uniq,
+            ((link_state&.inherited_block_names || []) + block_names).sort.uniq,
           inherited_dependencies:
-           (link_state&.inherited_dependencies || {}).merge(dependencies || {}), ### merge, not replace, key data
+            (link_state&.inherited_dependencies || {}).merge(dependencies || {}), ### merge, not replace, key data
           inherited_lines: HashDelegator.flatten_and_compact_arrays(
             link_state&.inherited_lines, code_lines
           ),
@@ -2239,7 +2492,12 @@ module MarkdownExec
           next_block_name: next_block_name,
           next_document_filename: next_document_filename,
           next_keep_code: next_keep_code,
-          next_load_file: next_document_filename == @delegate_object[:filename] ? LoadFile::REUSE : LoadFile::LOAD
+          next_load_file:
+            if next_document_filename == @delegate_object[:filename]
+              LoadFile::REUSE
+            else
+              LoadFile::LOAD
+            end
         )
       end
     end
@@ -2279,7 +2537,9 @@ module MarkdownExec
                        block_data['view'] || view,
                        NamedCaptureExtractor.extract_named_group_match_data(
                          file.match(
-                           Regexp.new(block_data['filename_pattern'] || filename_pattern)
+                           Regexp.new(
+                             block_data['filename_pattern'] || filename_pattern
+                           )
                          )
                        )
                      ),
@@ -2306,9 +2566,11 @@ module MarkdownExec
         reason = 'default Load mode'
         mode = LoadMode::APPEND
       end
+      wwt :state, '@dml_block_state:', @dml_block_state
 
       OpenStruct.new(
-        code: code,
+        code: annotate_required_lines('blk:LOAD', code,
+                                      block_name: selected.id),
         mode: mode,
         reason: reason
       )
@@ -2325,7 +2587,7 @@ module MarkdownExec
     def execute_block_type_port_code_lines(mdoc:, selected:, block_source:,
                                            link_state: LinkState.new)
       required = mdoc.collect_recursively_required_code(
-        anyname: selected.pub_name,
+        anyname: selected_id_name(selected),
         label_format_above: @delegate_object[:shell_code_label_format_above],
         label_format_below: @delegate_object[:shell_code_label_format_below],
         block_source: block_source
@@ -2356,15 +2618,21 @@ module MarkdownExec
 
       if selected[:type] == BlockType::OPTS
         # body of blocks is returned as a list of lines to be read an YAML
-        HashDelegator.flatten_and_compact_arrays(required[:blocks].map(&:body).flatten(1))
+        HashDelegator.flatten_and_compact_arrays(
+          required[:blocks].map(&:body).flatten(1)
+        )
       else
         code_lines = if selected.type == BlockType::VARS
                        code_from_vars_block_to_set_environment_variables(selected)
                      else
                        []
                      end
-        HashDelegator.flatten_and_compact_arrays(link_state&.inherited_lines,
-                                                 required[:code] + code_lines)
+        HashDelegator.flatten_and_compact_arrays(
+          link_state&.inherited_lines,
+          annotate_required_lines(
+            'blk:PORT', required[:code] + code_lines, block_name: selected.id
+          )
+        )
       end
     end
 
@@ -2383,6 +2651,11 @@ module MarkdownExec
       save_filespec_from_expression(directory_glob).tap do |save_filespec|
         if save_filespec && save_filespec != exit_prompt
           begin
+            if @delegate_object[:document_save_make_directory]
+              # make directory if it doesn't exist
+              FileUtils.mkdir_p(File.dirname(save_filespec))
+            end
+
             File.write(save_filespec,
                        HashDelegator.join_code_lines(code_lines))
           rescue Errno::ENOENT
@@ -2425,8 +2698,10 @@ module MarkdownExec
         end
 
         # Handle stdin stream
-        input_thread = handle_stream(stream: $stdin,
-                                     file_type: ExecutionStreams::STD_IN) do |line|
+        input_thread = handle_stream(
+          stream: $stdin,
+          file_type: ExecutionStreams::STD_IN
+        ) do |line|
           stdin.puts(line)
           yield line, nil, nil, exec_thread if block_given?
         end
@@ -2555,6 +2830,7 @@ module MarkdownExec
     end
 
     def expand_references!(fcb, link_state)
+      wwt :expand_references, 'fcb.id', fcb.id, 'link_state:', link_state
       # options expansions
       expand_variable_references!(
         blocks: [fcb],
@@ -2562,8 +2838,9 @@ module MarkdownExec
         group_name: :payload,
         initial_code_required: false,
         link_state: link_state,
-        pattern: @delegate_object[:option_expansion_expression_regexp].present? &&
-          Regexp.new(@delegate_object[:option_expansion_expression_regexp])
+        pattern:
+          @delegate_object[:option_expansion_expression_regexp].present? &&
+            Regexp.new(@delegate_object[:option_expansion_expression_regexp])
       )
 
       # variable expansions
@@ -2572,7 +2849,8 @@ module MarkdownExec
         echo_formatter: lambda do |variable|
           %(echo "$#{variable}")
         end,
-        group_name: @delegate_object[:variable_expansion_name_capture_group]&.to_sym,
+        group_name:
+          @delegate_object[:variable_expansion_name_capture_group]&.to_sym,
         initial_code_required: false,
         link_state: link_state,
         pattern: options_variable_expansion_regexp
@@ -2582,12 +2860,15 @@ module MarkdownExec
       expand_variable_references!(
         blocks: [fcb],
         echo_formatter: lambda { |command| command },
-        group_name: @delegate_object[:command_substitution_name_capture_group]&.to_sym,
+        group_name:
+          @delegate_object[:command_substitution_name_capture_group]&.to_sym,
         initial_code_required: false,
         link_state: link_state,
         pattern: options_command_substitution_regexp
       )
       # no return
+    rescue StandardError
+      wwe 'fcb:', fcb, 'link_state:', link_state
     end
 
     def expand_variable_references!(
@@ -2623,55 +2904,88 @@ module MarkdownExec
       # no return
     end
 
-    def export_echo_with_code(
-      bash_script_lines, export, force:, silent:, string: nil
+    def ux_block_eval_for_export(
+      bash_script_lines, export,
+      data:,
+      first_only: false,
+      force:,
+      printf_expand: false,
+      silent:,
+      string: nil
     )
-      wwp
       exportable = true
       command_result = nil
       new_lines = []
-      export_string = string.nil? ? export.echo : string
+      export_string = string.nil? ? data : string
+      expander = ->(expression) { %(printf '%s' "#{expression}") }
+
       case export_string
       when String, Integer, Float, TrueClass, FalseClass
         command_result, exportable, = output_from_adhoc_bash_script_file(
           join_array_of_arrays(
             bash_script_lines,
-            %(printf '%s' "#{export_string}")
+            printf_expand ? expander.call(export_string) : [export_string]
           ),
           export,
           force: force
         )
         if command_result.exit_status == EXIT_STATUS_REQUIRED_EMPTY
           exportable = false
-          command_result.warning = warning_required_empty(export) unless silent
+          unless silent
+            command_result.warning = warning_required_empty(export)
+          end
         else
+          # store the transformed value in ENV
           EnvInterface.set(export.name, command_result.stdout.to_s)
+
           new_lines << { name: export.name, force: force,
                          text: command_result.stdout }
         end
 
       when Hash
+        required_lines = []
+
         # each item in the hash is a variable name and value
         export_string.each do |name, expression|
           command_result, = output_from_adhoc_bash_script_file(
             join_array_of_arrays(
               bash_script_lines,
-              %(printf '%s' "#{expression}")
+              required_lines,
+              printf_expand ? expander.call(expression) : [expression]
             ),
             export,
             force: force
           )
           if command_result.exit_status == EXIT_STATUS_REQUIRED_EMPTY
-            command_result.warning = warning_required_empty(export) unless silent
+            unless silent
+              command_result.warning = warning_required_empty(export)
+            end
           else
-            EnvInterface.set(name, command_result.stdout.to_s)
-            new_lines << { name: name, force: force,
-                           text: command_result.stdout }
+            transformed = command_result.stdout.to_s
+
+            # code for subsequent expression evaluations
+            required_lines << code_line_to_assign_a_variable(
+              name, transformed, force: force
+            )
+
+            if variable_is_exportable(name)
+              # store the transformed value in ENV
+              EnvInterface.set(name, transformed)
+
+              new_lines << { name: name, force: force,
+                             text: command_result.stdout }
+            end
           end
+
+          break if first_only
         end
+      else
+        # do nothing
       end
 
       [command_result, exportable, new_lines]
+    rescue StandardError
+      wwe bash_script_lines, export, force, silent, string
     end
 
     # Retrieves a specific data symbol from the delegate object,
@@ -2711,8 +3025,13 @@ module MarkdownExec
     # fallback to @dml_menu_blocks if not found.
     def find_block_by_name(blocks, block_name)
       match_block = ->(item) do
-        [item.pub_name, item.nickname,
-         item.oname, item.s2title].include?(block_name)
+        [
+          selected_id_name(item),
+          item.pub_name,
+          item.nickname,
+          item.oname,
+          item.s2title
+        ].include?(block_name)
       end
 
       @dml_blocks_in_file.find(&match_block) ||
@@ -2759,7 +3078,9 @@ module MarkdownExec
     end
 
     def format_echo_command(payload)
-      payload_match = payload.match(@delegate_object[:option_expansion_payload_regexp])
+      payload_match = payload.match(
+        @delegate_object[:option_expansion_payload_regexp]
+      )
       variable = payload_match[:option]
       property = payload_match[:property]
 
@@ -2807,6 +3128,20 @@ module MarkdownExec
       string_send_color(formatted_string, color_sym)
     end
 
+    # for inherited code comments
+    # for external automation
+    def formatted_block_name(block_name,
+                             format_sym = :publish_block_name_format)
+      format(
+        @delegate_object[format_sym],
+        { block: block_name,
+          document: @delegate_object[:filename],
+          time: Time.now.utc.strftime(
+            @delegate_object[:publish_time_format]
+          ) }
+      )
+    end
+
     # Expand expression if it contains format specifiers
     def formatted_expression(expr)
       expr.include?('%{') ? format_expression(expr) : expr
@@ -2994,6 +3329,7 @@ module MarkdownExec
       ) do |nested_line|
         next if nested_line.nil?
 
+        wwt :iterlines, 'nested_line:', nested_line
         update_line_and_block_state(
           nested_line, state, selected_types,
           source_id: "ItrBlkFrmNstFls:#{index}¤#{nested_line.filename}:#{nested_line.index}",
@@ -3002,6 +3338,8 @@ module MarkdownExec
 
         index += 1
       end
+    rescue StandardError
+      wwe $!, 'state:', state, 'nested_line:', nested_line
     end
 
     def iter_source_blocks(source, source_id: nil, &block)
@@ -3036,8 +3374,9 @@ module MarkdownExec
 
     def link_block_data_eval(link_state, code_lines, selected, link_block_data,
                              block_source:, shell:)
-      all_code = HashDelegator.flatten_and_compact_arrays(link_state&.inherited_lines,
-                                                          code_lines)
+      all_code = HashDelegator.flatten_and_compact_arrays(
+        link_state&.inherited_lines, code_lines
+      )
       output_lines = []
 
       Tempfile.open do |file|
@@ -3171,9 +3510,10 @@ module MarkdownExec
 
     # Loads and updates auto options for document blocks if the current filename has changed.
     #
-    # This method checks if the delegate object specifies a document load options block name and if the filename
-    # has been updated. It then selects the appropriate blocks, collects their dependencies, processes their
-    # options, and updates the menu base with the merged options.
+    # This method checks if the delegate object specifies a document load
+    # options block name and if the filename has been updated. It then
+    # selects the appropriate blocks, collects their dependencies, processes
+    # their options, and updates the menu base with the merged options.
     #
     # @param all_blocks [Array] An array of all block elements.
     # @param mdoc [Object] The document object managing dependencies and options.
@@ -3211,27 +3551,6 @@ module MarkdownExec
       true
     end
 
-    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
-      end
-
-      blocks = HashDelegator.block_select(all_blocks, :oname, block_name)
-      return if blocks.empty?
-
-      @vars_most_recent_filename = @delegate_object[:filename]
-
-      (blocks.each.with_object([]) do |block, merged_options|
-        merged_options.push(
-          code_from_vars_block_to_set_environment_variables(block)
-        )
-      end).to_a
-    end
-
     def load_cli_or_user_selected_block(all_blocks: [], menu_blocks: [],
                                         prior_answer: nil)
       if @delegate_object[:block_name].present?
@@ -3252,30 +3571,6 @@ module MarkdownExec
       SelectedBlockMenuState.new(block, source, state)
     end
 
-    def load_document_shell_block(all_blocks, mdoc: nil)
-      block_name = @delegate_object[:document_load_shell_block_name]
-      unless block_name.present? &&
-             @shell_most_recent_filename != @delegate_object[:filename]
-        return
-      end
-
-      fcb = HashDelegator.block_find(all_blocks, :oname, block_name)
-      return unless fcb
-
-      @shell_most_recent_filename = @delegate_object[:filename]
-
-      if mdoc
-        mdoc.collect_recursively_required_code(
-          anyname: fcb.pub_name,
-          label_format_above: @delegate_object[:shell_code_label_format_above],
-          label_format_below: @delegate_object[:shell_code_label_format_below],
-          block_source: block_source
-        )[:code]
-      else
-        fcb.body
-      end
-    end
-
     # format + glob + select for file in load block
     # name has references to ENV vars and doc and batch vars
     #  incl. timestamp
@@ -3367,32 +3662,21 @@ module MarkdownExec
         reload_blocks = true
       end
 
-      # load document shell block
+      # return code resulting from evaluating all SHELL, UX, VARS blocks;
+      # each set in sequence; with its own order
       #
-      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
-      end
-
-      # load document ux block
-      #
-      if (code_lines = code_from_automatic_ux_blocks(all_blocks, mdoc))
-        new_code = HashDelegator.flatten_and_compact_arrays(link_state.inherited_lines,
-                                                            code_lines)
-        next_state_set_code(nil, link_state, new_code)
-        link_state.inherited_lines = new_code
-        reload_blocks = true
-      end
-
-      # load document vars block
-      #
-      if (code_lines = load_auto_vars_block(all_blocks))
-        new_code = HashDelegator.flatten_and_compact_arrays(link_state.inherited_lines,
-                                                            code_lines)
+      if (code_lines = code_from_auto_blocks(
+        all_blocks,
+        default_only: true,
+        mdoc: mdoc
+      ))&.select_by(:empty?, false)&.compact&.count&.positive?
+        new_code = code_lines
+        wwt :code_lines, 'code_lines:', code_lines
         next_state_set_code(nil, link_state, new_code)
         link_state.inherited_lines = new_code
         reload_blocks = true
+      else
+        link_state&.inherited_lines
       end
 
       if reload_blocks
@@ -3448,6 +3732,7 @@ module MarkdownExec
       [all_blocks, menu_blocks, mdoc]
     end
 
+    # enable scroll targets in long sequences of inactive lines
     def handle_consecutive_inactive_items!(menu_blocks)
       consecutive_inactive_count = 0
       menu_blocks.each do |fcb|
@@ -3455,7 +3740,10 @@ module MarkdownExec
           consecutive_inactive_count = 0
         else
           consecutive_inactive_count += 1
-          if (consecutive_inactive_count % (@delegate_object[:select_page_height] / 3)).zero?
+          if (consecutive_inactive_count %
+              (@delegate_object[:select_page_height] /
+               @delegate_object[:select_page_ratio])
+             ).zero?
             fcb.disabled = TtyMenu::ENABLE
             fcb.is_enabled_but_inactive = true
           end
@@ -3463,7 +3751,7 @@ module MarkdownExec
       end
     end
 
-    def menu_add_disabled_option(document_glob)
+    def menu_add_disabled_option(document_glob, id)
       raise unless document_glob.present?
       raise if @dml_menu_blocks.nil?
 
@@ -3473,13 +3761,16 @@ module MarkdownExec
       #
       return unless block.nil?
 
+      dname = HashDelegator.new(@delegate_object).string_send_color(
+        document_glob, :menu_inherited_lines_color
+      )
+
       chrome_block = persist_fcb(
         chrome: true,
         disabled: TtyMenu::DISABLE,
-        dname: HashDelegator.new(@delegate_object).string_send_color(
-          document_glob, :menu_inherited_lines_color
-        ),
+        dname: dname,
         # 2025-01-03 menu item is disabled ∴ does not need a recall id
+        id: id,
         oname: formatted_name
       )
 
@@ -3749,7 +4040,8 @@ module MarkdownExec
       end
     end
 
-    # This method handles the back-link operation in the Markdown execution context.
+    # This method handles the back-link operation in
+    # the Markdown execution context.
     # It updates the history state for the next block.
     #
     # @return [LinkState] An object indicating the state for
@@ -3804,12 +4096,13 @@ module MarkdownExec
         multiline = fcb.indented_decorated ||
                     (fcb.indent + (fcb.s1decorated || fcb.dname))
 
-        fcb.name = multiline.each_line.with_index.map do |line, index|
+        fcb.name = multiline.split("\n",
+                                   -1).each_with_index.map do |line, index|
           if fcb.fetch(:disabled, nil).nil?
             index.zero? ? active : inactive
           else
             inactive
-          end + line.chomp
+          end + line
         end.join("\n")
 
         fcb.value = fcb.id || fcb.name.split("\n").first
@@ -3855,8 +4148,10 @@ module MarkdownExec
       raise StandardError, $!
     end
 
-    def process_string_array(arr, begin_pattern: nil, end_pattern: nil, scan1: nil,
-                             format1: nil, name: '')
+    def process_string_array(
+      arr, begin_pattern: nil, end_pattern: nil, scan1: nil,
+      format1: nil, name: ''
+    )
       in_block = !begin_pattern.present?
       collected_lines = []
 
@@ -3909,6 +4204,9 @@ module MarkdownExec
 
       @allowed_execution_block = @prior_execution_block
       true
+    rescue TTY::Reader::InputInterrupt
+      # treat as denial
+      false
     end
 
     def prompt_for_command(prompt)
@@ -3992,6 +4290,9 @@ module MarkdownExec
       end
 
       sel == MenuOptions::YES
+    rescue TTY::Reader::InputInterrupt
+      # treat as denial
+      false
     end
 
     def prompt_margin_left_text
@@ -4016,7 +4317,14 @@ module MarkdownExec
         menu.choice @delegate_object[:prompt_yes]
         menu.choice @delegate_object[:prompt_exit]
       end
-      sel == @delegate_object[:prompt_exit] ? MenuState::EXIT : MenuState::CONTINUE
+      sel == if @delegate_object[:prompt_exit]
+               MenuState::EXIT
+             else
+               MenuState::CONTINUE
+             end
+    rescue TTY::Reader::InputInterrupt
+      # treat as denial
+      MenuState::EXIT
     end
 
     # public
@@ -4045,6 +4353,9 @@ module MarkdownExec
           end
         end
       end
+    rescue TTY::Reader::InputInterrupt
+      # treat as no selection
+      nil
     end
 
     # user prompt to exit if the menu will be displayed again
@@ -4081,15 +4392,6 @@ module MarkdownExec
       end
     end
 
-    # Handle expression with wildcard characters
-    # allow user to select or enter
-    def puts_gets_oprompt_(filespec)
-      puts format(@delegate_object[:prompt_show_expr_format],
-                  { expr: filespec })
-      puts @delegate_object[:prompt_enter_filespec]
-      gets.chomp
-    end
-
     def read_saved_assets_for_history_table(
       asset: nil,
       filename: nil,
@@ -4323,7 +4625,9 @@ module MarkdownExec
       required_lines:, selected:, shell:
     )
       write_command_file(
-        required_lines: required_lines, blockname: selected.pub_name, shell: selected_shell(shell)
+        required_lines: required_lines,
+        blockname: selected.pub_name,
+        shell: selected_shell(shell)
       )
       @fout.fout "File saved: #{@run_state.saved_filespec}"
     end
@@ -4371,7 +4675,8 @@ module MarkdownExec
 
     def screen_width_for_table
       # menu adds newline after some lines if sized to the edge
-      screen_width - prompt_margin_left_width - prompt_margin_right_width - 3 # menu prompt symbol (1) + space (1) + gap (1)
+      # menu prompt symbol (1) + space (1) + gap (1)
+      screen_width - prompt_margin_left_width - prompt_margin_right_width - 3
     end
 
     def screen_width_for_wrapping
@@ -4472,10 +4777,14 @@ module MarkdownExec
         exit 1
       end
 
-      if selection == menu_chrome_colored_option(:menu_option_back_name)
+      if selected.oname == HashDelegator.safeval(
+        @delegate_object.fetch(:menu_option_back_name, '')
+      )[:line]
         selected.option = selection
         selected.type = BlockType::LINK
-      elsif selection == menu_chrome_colored_option(:menu_option_exit_name)
+      elsif selected.oname == HashDelegator.safeval(
+        @delegate_object.fetch(:menu_option_exit_name, '')
+      )[:line]
         selected.option = selection
       else
         selected.selected = selection
@@ -4616,6 +4925,7 @@ module MarkdownExec
     #  color_sym is not found in @delegate_object.
     # @return [String] The string with the applied color method.
     def string_send_color(string, color_sym)
+      ### accept string with color as well as symbol for color_hash
       HashDelegator.apply_color_from_hash(string, @delegate_object, color_sym)
     end
 
@@ -4705,12 +5015,23 @@ module MarkdownExec
             @delegate_object[:menu_include_imported_notes]
         # add line if it is depth 0 or option allows it
         #
+        criteria = nil
+        if @delegate_object[:table_row_single_line_match]&.present? &&
+           line.match(@delegate_object[:table_row_single_line_match])
+          criteria = {
+            center: :table_center,
+            match: :table_row_single_line_match
+          }
+        end
         HashDelegator.yield_line_if_selected(
           line, selected_types,
           all_fcbs: @fcb_store,
+          criteria: criteria,
           source_id: source_id, &block
         )
       end
+    rescue StandardError
+      wwe $!, 'state:', state, 'nested_line:', nested_line
     end
 
     ## apply options to current state
@@ -4743,10 +5064,13 @@ module MarkdownExec
 
         case export.allow
         when :echo, ExportValueSource::ECHO
-          command_result, exportable, new_lines = export_echo_with_code(
+          command_result, exportable, new_lines = ux_block_eval_for_export(
             bash_script_lines,
             export,
+            data: export.echo,
+            first_only: true,
             force: force,
+            printf_expand: true,
             silent: silent
           )
 
@@ -4754,15 +5078,20 @@ module MarkdownExec
             command_result
           else
             command_result = CommandResult.new(
-              stdout: menu_from_list_with_back(command_result.stdout.split("\n"))
+              stdout: menu_from_list_with_back(
+                command_result.stdout.split("\n")
+              )
             )
           end
 
         when :exec, UxActSource::EXEC
-          command_result, = output_from_adhoc_bash_script_file(
-            join_array_of_arrays(bash_script_lines, export.exec),
+          command_result, exportable, new_lines = ux_block_eval_for_export(
+            bash_script_lines,
             export,
-            force: force
+            data: export.exec,
+            first_only: true,
+            force: force,
+            silent: silent
           )
 
           if command_result.exit_status == EXIT_STATUS_REQUIRED_EMPTY
@@ -4777,10 +5106,13 @@ module MarkdownExec
 
         else
           export_init = menu_from_list_with_back(export.allow)
-          command_result, exportable, new_lines = export_echo_with_code(
+          command_result, exportable, new_lines = ux_block_eval_for_export(
             [assign_key_value_in_bash(export.name, export_init)],
             export,
+            data: export.echo,
+            first_only: true,
             force: force,
+            printf_expand: true,
             silent: silent,
             string: export_init
           )
@@ -4788,11 +5120,12 @@ module MarkdownExec
         end
 
       when :echo, UxActSource::ECHO
-        wwp
-        command_result, exportable, new_lines = export_echo_with_code(
+        command_result, exportable, new_lines = ux_block_eval_for_export(
           bash_script_lines,
           export,
+          data: export.echo,
           force: force,
+          printf_expand: true,
           silent: silent
         )
 
@@ -4822,10 +5155,12 @@ module MarkdownExec
         command_result = CommandResult.new(stdout: output)
 
       when :exec, UxActSource::EXEC
-        command_result, exportable, new_lines = output_from_adhoc_bash_script_file(
-          join_array_of_arrays(bash_script_lines, export.exec),
+        command_result, exportable, new_lines = ux_block_eval_for_export(
+          bash_script_lines,
           export,
-          force: force
+          data: export.exec,
+          force: force,
+          silent: silent
         )
 
       else
@@ -4843,6 +5178,8 @@ module MarkdownExec
       command_result.transformable = transformable
       command_result.new_lines = new_lines
       command_result
+    rescue StandardError
+      wwe bash_script_lines, export, exit_prompt
     end
 
     def ux_block_export_automatic(
@@ -4866,36 +5203,47 @@ module MarkdownExec
 
         case export.allow
         when :echo, ExportValueSource::ECHO
-          cr_echo, = output_from_adhoc_bash_script_file(
-            join_array_of_arrays(
-              bash_script_lines,
-              %(printf '%s' "#{export.echo}")
-            ),
+          cr_echo, = ux_block_eval_for_export(
+            bash_script_lines,
             export,
-            force: force
+            data: export.echo,
+            first_only: true,
+            force: force,
+            printf_expand: true,
+            silent: silent
           )
           export_init = cr_echo.stdout.split("\n").first
-          command_result, exportable, new_lines = export_echo_with_code(
+
+          command_result, exportable, new_lines = ux_block_eval_for_export(
             [assign_key_value_in_bash(export.name, export_init)],
             export,
+            data: export.echo,
+            first_only: true,
             force: force,
+            printf_expand: true,
             silent: silent,
             string: export_init
           )
 
         when :exec, ExportValueSource::EXEC
           # extract first line from 'exec' output
-          command_result, exportable, new_lines = output_from_adhoc_bash_script_file(
-            join_array_of_arrays(bash_script_lines, export.exec),
+          command_result, exportable, new_lines = ux_block_eval_for_export(
+            bash_script_lines,
             export,
-            force: force
+            data: export.exec,
+            first_only: true,
+            force: force,
+            silent: silent
           )
+
           unless command_result.failure?
             export_init = command_result.stdout.split("\n").first
-            command_result, exportable, new_lines = export_echo_with_code(
+            command_result, exportable, new_lines = ux_block_eval_for_export(
               [assign_key_value_in_bash(export.name, export_init)],
               export,
+              data: export.exec,
               force: force,
+              printf_expand: true,
               silent: silent,
               string: export_init
             )
@@ -4904,10 +5252,12 @@ module MarkdownExec
         else
           # first item from 'allow' list
           export_init = export.allow.first
-          command_result, exportable, new_lines = export_echo_with_code(
+          command_result, exportable, new_lines = ux_block_eval_for_export(
             [assign_key_value_in_bash(export.name, export_init)],
             export,
+            data: export.allow,
             force: force,
+            printf_expand: true,
             silent: silent,
             string: export_init
           )
@@ -4921,32 +5271,37 @@ module MarkdownExec
       when :echo, UxActSource::ECHO
         raise unless export.echo.present?
 
-        command_result, exportable, new_lines = export_echo_with_code(
+        command_result, exportable, new_lines = ux_block_eval_for_export(
           bash_script_lines,
           export,
+          data: export.echo,
           force: force,
+          printf_expand: true,
           silent: silent
         )
 
       when :exec, UxActSource::EXEC
         raise unless export.exec.present?
 
-        command_result, exportable, new_lines = output_from_adhoc_bash_script_file(
-          join_array_of_arrays(bash_script_lines, export.exec),
+        command_result, exportable, new_lines = ux_block_eval_for_export(
+          bash_script_lines,
           export,
-          force: force
+          data: export.exec,
+          force: force,
+          silent: silent
         )
 
       else
         export_init = export.init.to_s
-        command_result, exportable, new_lines = export_echo_with_code(
+        command_result, exportable, new_lines = ux_block_eval_for_export(
           [assign_key_value_in_bash(export.name, export_init)],
           export,
+          data: export.exec,
           force: force,
+          printf_expand: true,
           silent: silent,
           string: export_init
         )
-        # raise "Unknown FCB.init_source(export) #{FCB.init_source(export)}"
       end
 
       # add message for required variables
@@ -4959,10 +5314,19 @@ module MarkdownExec
       command_result.transformable = transformable
       command_result.new_lines = new_lines
       command_result
+    rescue StandardError
+      wwe bash_script_lines, export
     end
 
-    def warning_required_empty(export)
-      "A value must exist for: #{export.required.join(', ')}"
+    # true if the variable is exported in a series of evaluations
+    def variable_is_exportable(name)
+      local_name_pattern = @delegate_object.fetch(:local_name_pattern, '')
+
+      # export all if rule is empty
+      return true if local_name_pattern.empty?
+
+      # export if it its name does not match the rule
+      name !~ Regexp.new(local_name_pattern)
     end
 
     def vux_await_user_selection(prior_answer: @dml_block_selection)
@@ -4981,17 +5345,119 @@ module MarkdownExec
     end
 
     def vux_clear_menu_state
+      @dml_block_selection = @dml_block_state.block
       @dml_block_state = SelectedBlockMenuState.new
       @delegate_object[:block_name] = nil
     end
 
     def vux_edit_inherited
       edited = edit_text(@dml_link_state.inherited_lines_block)
-      @dml_link_state.inherited_lines = edited.split("\n") if edited
+      return unless edited
+
+      @dml_link_state.inherited_lines =
+        annotate_required_lines(
+          'blk:EDIT', edited.split("\n"), block_name: 'EDIT'
+        )
+    end
+
+    def block_is_back(fcb)
+      fcb.oname == HashDelegator.safeval(
+        @delegate_object[:menu_option_back_name]
+      )[:line]
+    end
+
+    def block_is_edit(fcb)
+      fcb.oname == HashDelegator.safeval(
+        @delegate_object[:menu_option_edit_name]
+      )[:line]
+    end
+
+    def block_is_exit(fcb)
+      fcb.oname == HashDelegator.safeval(
+        @delegate_object[:menu_option_exit_name]
+      )[:line]
+    end
+
+    def block_is_history(fcb)
+      fcb.oname == HashDelegator.safeval(
+        @delegate_object[:menu_option_history_name]
+      )[:line]
+    end
+
+    def block_is_load(fcb)
+      fcb.oname == HashDelegator.safeval(
+        @delegate_object[:menu_option_load_name]
+      )[:line]
+    end
+
+    def block_is_save(fcb)
+      fcb.oname == HashDelegator.safeval(
+        @delegate_object[:menu_option_save_name]
+      )[:line]
+    end
+
+    def block_is_shell(fcb)
+      fcb.oname == HashDelegator.safeval(
+        @delegate_object[:menu_option_shell_name]
+      )[:line]
+    end
+
+    def block_is_view(fcb)
+      fcb.oname == HashDelegator.safeval(
+        @delegate_object[:menu_option_view_name]
+      )[:line]
     end
 
     def vux_execute_and_prompt(block_name)
       @dml_block_state = find_block_state_by_name(block_name)
+
+      if @dml_block_state.block
+        if block_is_back(@dml_block_state.block)
+          debounce_reset
+          vux_navigate_back_for_ls
+          return
+
+        elsif block_is_edit(@dml_block_state.block)
+          debounce_reset
+          vux_edit_inherited
+          return pause_user_exit ? :break : nil
+
+        elsif block_is_exit(@dml_block_state.block)
+          debounce_reset
+          ### LoadFileLinkState.new(LoadFile::EXIT, link_state)
+          return :break
+
+        elsif block_is_history(@dml_block_state.block)
+          debounce_reset
+          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
+
+          return
+
+        elsif block_is_load(@dml_block_state.block)
+          debounce_reset
+          vux_load_inherited
+          return pause_user_exit ? :break : nil
+
+        elsif block_is_save(@dml_block_state.block)
+          debounce_reset
+          return execute_inherited_save == :break ? :break : nil
+
+        elsif block_is_shell(@dml_block_state.block)
+          debounce_reset
+          vux_input_and_execute_shell_commands(stream: $stderr, shell: shell)
+          return pause_user_exit ? :break : nil
+
+        elsif block_is_view(@dml_block_state.block)
+          debounce_reset
+          vux_view_inherited(stream: $stderr)
+          return pause_user_exit ? :break : nil
+
+        end
+      end
+
       if @dml_block_state.block &&
          @dml_block_state.block.type == BlockType::OPTS
         debounce_reset
@@ -5032,62 +5498,12 @@ module MarkdownExec
     end
 
     def vux_execute_block_per_type(block_name, formatted_choice_ostructs)
-      case block_name
-      when formatted_choice_ostructs[:back].pub_name
-        debounce_reset
-        vux_navigate_back_for_ls
+      return :break if vux_execute_and_prompt(block_name) == :break
 
-      when formatted_choice_ostructs[:edit].pub_name
-        debounce_reset
-        vux_edit_inherited
-        return :break if pause_user_exit
-
-        InputSequencer.next_link_state(prior_block_was_link: true)
-
-      when formatted_choice_ostructs[:history].pub_name
-        debounce_reset
-        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
-
-        InputSequencer.next_link_state(prior_block_was_link: true)
-
-      when formatted_choice_ostructs[:load].pub_name
-        debounce_reset
-        vux_load_inherited
-        return :break if pause_user_exit
-
-        InputSequencer.next_link_state(prior_block_was_link: true)
-
-      when formatted_choice_ostructs[:save].pub_name
-        debounce_reset
-        return :break if execute_inherited_save == :break
-
-        InputSequencer.next_link_state(prior_block_was_link: true)
-
-      when formatted_choice_ostructs[:shell].pub_name
-        debounce_reset
-        vux_input_and_execute_shell_commands(stream: $stderr, shell: shell)
-        return :break if pause_user_exit
-
-        InputSequencer.next_link_state(prior_block_was_link: true)
-
-      when formatted_choice_ostructs[:view].pub_name
-        debounce_reset
-        vux_view_inherited(stream: $stderr)
-        return :break if pause_user_exit
-
-        InputSequencer.next_link_state(prior_block_was_link: true)
-
-      else
-        return :break if vux_execute_and_prompt(block_name) == :break
-
-        InputSequencer.next_link_state(
-          block_name: @dml_link_state.block_name,
-          prior_block_was_link: @dml_block_state.block.type != BlockType::SHELL
-        )
-      end
+      InputSequencer.next_link_state(
+        block_name: @dml_link_state.block_name,
+        prior_block_was_link: @dml_block_state.block.type != BlockType::SHELL
+      )
     end
 
     def vux_formatted_names_for_state_chrome_blocks(
@@ -5237,10 +5653,13 @@ module MarkdownExec
         block_list
       ).run do |msg, data|
         count += 1
+        wwt :id, 'count:', count, 'msg:', msg, 'data:', data
         case msg
         when :parse_document # once for each menu
           count = 0
-          vux_parse_document(source_id: "#{@delegate_object[:filename]}¤VuxMainLoop®PrsDoc")
+          vux_parse_document(
+            source_id: "#{@delegate_object[:filename]}¤VuxMainLoop®PrsDoc"
+          )
           vux_menu_append_history_files(
             formatted_choice_ostructs,
             source_id: "#{@delegate_object[:filename]}¤VuxMainLoop®HstFls"
@@ -5254,8 +5673,19 @@ module MarkdownExec
         when :end_of_cli
           # yield :end_of_cli, @delegate_object
 
-          if @delegate_object[:list_blocks]
-            list_blocks(source_id: "#{@delegate_object[:filename]}¤VuxMainLoop®EndCLI")
+          if @delegate_object[:blocks].present?
+            @delegate_object[:list_blocks_message] =
+              @delegate_object[:blocks].to_sym
+            @delegate_object[:list_blocks_type] = 3
+
+            list_blocks(
+              source_id: "#{@delegate_object[:filename]}¤VuxMainLoop®EndCLI"
+            )
+            :exit
+          elsif @delegate_object[:list_blocks]
+            list_blocks(
+              source_id: "#{@delegate_object[:filename]}¤VuxMainLoop®EndCLI"
+            )
             :exit
           end
 
@@ -5263,9 +5693,14 @@ module MarkdownExec
           vux_user_selected_block_name
 
         when :execute_block
-          ret = vux_execute_block_per_type(data, formatted_choice_ostructs)
-          vux_publish_block_name_for_external_automation(data)
-          ret
+          begin
+            ret = vux_execute_block_per_type(data, formatted_choice_ostructs)
+            vux_publish_block_name_for_external_automation(data)
+            ret
+          rescue StandardError
+            # error executing block, do not abort
+            InputSequencer.next_link_state(prior_block_was_link: false)
+          end
 
         when :close_ux
           if @vux_pipe_open.present? && File.exist?(@vux_pipe_open)
@@ -5321,7 +5756,7 @@ module MarkdownExec
 
       # add menu items (glob, load, save) and enable selectively
       if files.count.positive? || lines_count.positive?
-        menu_add_disabled_option(document_glob)
+        menu_add_disabled_option(document_glob, "#{source_id}_vmahf_glob")
       end
       if files.count.positive?
         dml_menu_append_chrome_item(
@@ -5402,14 +5837,7 @@ module MarkdownExec
 
     def vux_publish_block_name_for_external_automation(block_name)
       publish_for_external_automation(
-        message: format(
-          @delegate_object[:publish_block_name_format],
-          { block: block_name,
-            document: @delegate_object[:filename],
-            time: Time.now.utc.strftime(
-              @delegate_object[:publish_time_format]
-            ) }
-        )
+        message: formatted_block_name(block_name)
       )
     end
 
@@ -5445,7 +5873,7 @@ module MarkdownExec
         return :break if @dml_block_state.block.nil? # no block matched
       end
       # puts "! - Executing block: #{data}"
-      @dml_block_state.block&.pub_name
+      @dml_block_state.block&.id
     end
 
     def vux_view_inherited(stream:)
@@ -5488,11 +5916,12 @@ module MarkdownExec
                           nil
                         when String
                           menu_blocks.find do |block|
-                            block.dname.include?(prior_answer)
+                            block.id == prior_answer
                           end&.name
                         when Struct, MarkdownExec::FCB
                           if prior_answer.id
-                            # when switching documents, the prior answer will not be found
+                            # when switching documents,
+                            # the prior answer will not be found
                             (menu_blocks.find_index do |block|
                               block[:id] == prior_answer.id
                             end || 0) + 1
@@ -5519,6 +5948,10 @@ module MarkdownExec
       determine_block_state(selected_option)
     end
 
+    def warning_required_empty(export)
+      "A value must exist for: #{export.required.join(', ')}"
+    end
+
     # Handles the core logic for generating the command
     # file's metadata and content.
     def write_command_file(required_lines:, blockname:, shell: nil)
@@ -5590,8 +6023,10 @@ module MarkdownExec
       if save_expr.present?
         save_filespec = save_filespec_from_expression(save_expr)
         if save_filespec.present?
-          File.write(save_filespec,
-                     HashDelegator.join_code_lines(link_state&.inherited_lines))
+          File.write(
+            save_filespec,
+            HashDelegator.join_code_lines(link_state&.inherited_lines)
+          )
           @delegate_object[:filename]
         else
           link_block_data[LinkKeys::FILE] || @delegate_object[:filename]
@@ -5602,6 +6037,7 @@ module MarkdownExec
     end
 
     def safe_yaml_load(body)
+      caller.deref(12)
       return {} unless body&.present?
 
       YAML.load(body.to_s)
@@ -6725,4 +7161,427 @@ module MarkdownExec
       end
     end
   end
+
+  # Comprehensive tests for ux_block_eval_for_export function
+  class TestUxBlockEvalForExport < Minitest::Test
+    def setup
+      @hd = HashDelegator.new
+      @bash_script_lines = ['#!/bin/bash', 'set -e']
+      @export = OpenStruct.new(name: 'TEST_VAR', required: ['TEST_VAR'])
+      @mock_result = OpenStruct.new(
+        exit_status: 0,
+        stdout: 'test_output',
+        stderr: '',
+        warning: nil
+      )
+    end
+
+    def teardown
+      # Clean up environment variables set during tests
+      ENV.delete('TEST_VAR')
+      ENV.delete('VAR1')
+      ENV.delete('VAR2')
+    end
+
+    # Test string input - typical case
+    def test_string_input_success
+      @hd.stubs(:output_from_adhoc_bash_script_file).returns([@mock_result,
+                                                              true])
+      @hd.stubs(:variable_is_exportable).returns(true)
+
+      result = @hd.ux_block_eval_for_export(
+        @bash_script_lines, @export,
+        data: 'echo "hello"',
+        force: false,
+        silent: false
+      )
+
+      command_result, exportable, new_lines = result
+      assert_equal @mock_result, command_result
+      assert_equal true, exportable
+      assert_equal 1, new_lines.length
+      assert_equal 'TEST_VAR', new_lines.first[:name]
+      assert_equal 'test_output', new_lines.first[:text]
+    end
+
+    # Test string input with printf_expand
+    def test_string_input_with_printf_expand
+      @hd.stubs(:output_from_adhoc_bash_script_file).returns([@mock_result,
+                                                              true])
+      @hd.stubs(:variable_is_exportable).returns(true)
+
+      @hd.ux_block_eval_for_export(
+        @bash_script_lines, @export,
+        data: 'test_value',
+        force: false,
+        printf_expand: true,
+        silent: false
+      )
+
+      # Verify that join_array_of_arrays was called with printf wrapped expression
+      # This tests that the expander lambda is applied correctly
+    end
+
+    # Test integer input
+    def test_integer_input
+      @hd.stubs(:output_from_adhoc_bash_script_file).returns([@mock_result,
+                                                              true])
+      @hd.stubs(:variable_is_exportable).returns(true)
+
+      result = @hd.ux_block_eval_for_export(
+        @bash_script_lines, @export,
+        data: 42,
+        force: true,
+        silent: false
+      )
+
+      command_result, exportable, new_lines = result
+      assert_equal @mock_result, command_result
+      assert_equal true, exportable
+      assert_equal 1, new_lines.length
+    end
+
+    # Test boolean inputs
+    def test_boolean_true_input
+      @hd.stubs(:output_from_adhoc_bash_script_file).returns([@mock_result,
+                                                              true])
+      @hd.stubs(:variable_is_exportable).returns(true)
+
+      result = @hd.ux_block_eval_for_export(
+        @bash_script_lines, @export,
+        data: true,
+        force: false,
+        silent: false
+      )
+
+      command_result, exportable, = result
+      assert_equal @mock_result, command_result
+      assert_equal true, exportable
+    end
+
+    def test_boolean_false_input
+      @hd.stubs(:output_from_adhoc_bash_script_file).returns([@mock_result,
+                                                              true])
+      @hd.stubs(:variable_is_exportable).returns(true)
+
+      result = @hd.ux_block_eval_for_export(
+        @bash_script_lines, @export,
+        data: false,
+        force: false,
+        silent: false
+      )
+
+      command_result, exportable, = result
+      assert_equal @mock_result, command_result
+      assert_equal true, exportable
+    end
+
+    # Test float input
+    def test_float_input
+      @hd.stubs(:output_from_adhoc_bash_script_file).returns([@mock_result,
+                                                              true])
+      @hd.stubs(:variable_is_exportable).returns(true)
+
+      result = @hd.ux_block_eval_for_export(
+        @bash_script_lines, @export,
+        data: 3.14,
+        force: false,
+        silent: false
+      )
+
+      command_result, exportable, = result
+      assert_equal @mock_result, command_result
+      assert_equal true, exportable
+    end
+
+    # Test hash input - typical case
+    def test_hash_input_success
+      hash_data = { 'VAR1' => 'value1', 'VAR2' => 'value2' }
+      @hd.stubs(:output_from_adhoc_bash_script_file).returns([@mock_result,
+                                                              true])
+      @hd.stubs(:variable_is_exportable).returns(true)
+      @hd.stubs(:code_line_to_assign_a_variable).returns('VAR1=value1')
+
+      result = @hd.ux_block_eval_for_export(
+        @bash_script_lines, @export,
+        data: hash_data,
+        force: false,
+        silent: false
+      )
+
+      command_result, exportable, new_lines = result
+      assert_equal @mock_result, command_result
+      assert_equal true, exportable
+      assert_equal 2, new_lines.length
+      assert_equal 'VAR1', new_lines.first[:name]
+      assert_equal 'VAR2', new_lines.last[:name]
+    end
+
+    # Test hash input with first_only flag
+    def test_hash_input_first_only
+      hash_data = { 'VAR1' => 'value1', 'VAR2' => 'value2' }
+      @hd.stubs(:output_from_adhoc_bash_script_file).returns([@mock_result,
+                                                              true])
+      @hd.stubs(:variable_is_exportable).returns(true)
+      @hd.stubs(:code_line_to_assign_a_variable).returns('VAR1=value1')
+
+      result = @hd.ux_block_eval_for_export(
+        @bash_script_lines, @export,
+        data: hash_data,
+        first_only: true,
+        force: false,
+        silent: false
+      )
+
+      command_result, _, new_lines = result
+      assert_equal @mock_result, command_result
+      assert_equal 1, new_lines.length
+      assert_equal 'VAR1', new_lines.first[:name]
+    end
+
+    # Test hash with non-exportable variables
+    def test_hash_input_non_exportable_variables
+      hash_data = { 'LOCAL_VAR' => 'value1' }
+      @hd.stubs(:output_from_adhoc_bash_script_file).returns([@mock_result,
+                                                              true])
+      @hd.stubs(:variable_is_exportable).returns(false)
+      @hd.stubs(:code_line_to_assign_a_variable).returns('LOCAL_VAR=value1')
+
+      result = @hd.ux_block_eval_for_export(
+        @bash_script_lines, @export,
+        data: hash_data,
+        force: false,
+        silent: false
+      )
+
+      command_result, _, new_lines = result
+      assert_equal @mock_result, command_result
+      assert_equal 0, new_lines.length # No exportable variables
+    end
+
+    # Test EXIT_STATUS_REQUIRED_EMPTY handling
+    def test_exit_status_required_empty_with_warning
+      failed_result = OpenStruct.new(
+        exit_status: 248, # EXIT_STATUS_REQUIRED_EMPTY
+        stdout: '',
+        stderr: 'Required variable empty',
+        warning: nil
+      )
+      @hd.stubs(:output_from_adhoc_bash_script_file).returns([failed_result,
+                                                              false])
+      @hd.stubs(:warning_required_empty).returns('Warning: required empty')
+
+      result = @hd.ux_block_eval_for_export(
+        @bash_script_lines, @export,
+        data: 'echo ""',
+        force: false,
+        silent: false
+      )
+
+      command_result, exportable, new_lines = result
+      assert_equal failed_result, command_result
+      assert_equal false, exportable
+      assert_equal 0, new_lines.length
+      assert_equal 'Warning: required empty', command_result.warning
+    end
+
+    # Test EXIT_STATUS_REQUIRED_EMPTY handling with silent flag
+    def test_exit_status_required_empty_silent
+      failed_result = OpenStruct.new(
+        exit_status: 248,
+        stdout: '',
+        stderr: 'Required variable empty',
+        warning: nil
+      )
+      @hd.stubs(:output_from_adhoc_bash_script_file).returns([failed_result,
+                                                              false])
+
+      result = @hd.ux_block_eval_for_export(
+        @bash_script_lines, @export,
+        data: 'echo ""',
+        force: false,
+        silent: true
+      )
+
+      command_result, exportable, = result
+      assert_equal failed_result, command_result
+      assert_equal false, exportable
+      assert_nil command_result.warning # No warning when silent
+    end
+
+    # Test string parameter override
+    def test_string_parameter_override
+      @hd.stubs(:output_from_adhoc_bash_script_file).returns([@mock_result,
+                                                              true])
+      @hd.stubs(:variable_is_exportable).returns(true)
+
+      result = @hd.ux_block_eval_for_export(
+        @bash_script_lines, @export,
+        data: 'original_data',
+        string: 'override_string',
+        force: false,
+        silent: false
+      )
+
+      # The function should use string parameter instead of data
+      command_result, exportable, = result
+      assert_equal @mock_result, command_result
+      assert_equal true, exportable
+    end
+
+    # Edge case: empty string
+    def test_empty_string_input
+      @hd.stubs(:output_from_adhoc_bash_script_file).returns([@mock_result,
+                                                              true])
+      @hd.stubs(:variable_is_exportable).returns(true)
+
+      result = @hd.ux_block_eval_for_export(
+        @bash_script_lines, @export,
+        data: '',
+        force: false,
+        silent: false
+      )
+
+      command_result, exportable, = result
+      assert_equal @mock_result, command_result
+      assert_equal true, exportable
+    end
+
+    # Edge case: nil data (uses string.nil? check)
+    def test_nil_data_input
+      @hd.stubs(:output_from_adhoc_bash_script_file).returns([@mock_result,
+                                                              true])
+      @hd.stubs(:variable_is_exportable).returns(true)
+
+      result = @hd.ux_block_eval_for_export(
+        @bash_script_lines, @export,
+        data: 'd1',
+        force: false,
+        silent: false
+      )
+
+      command_result, exportable, = result
+      assert_equal @mock_result, command_result
+      assert_equal true, exportable
+    end
+
+    # Edge case: empty hash
+    def test_empty_hash_input
+      result = @hd.ux_block_eval_for_export(
+        @bash_script_lines, @export,
+        data: {},
+        force: false,
+        silent: false
+      )
+
+      command_result, exportable, new_lines = result
+      assert_nil command_result # No iterations, so command_result remains nil
+      assert_equal true, exportable # Initial value
+      assert_equal 0, new_lines.length
+    end
+
+    # Edge case: hash with nil values
+    def test_hash_with_nil_values
+      hash_data = { 'VAR1' => nil, 'VAR2' => 'value2' }
+      @hd.stubs(:output_from_adhoc_bash_script_file).returns([@mock_result,
+                                                              true])
+      @hd.stubs(:variable_is_exportable).returns(true)
+      @hd.stubs(:code_line_to_assign_a_variable).returns('VAR1=')
+
+      result = @hd.ux_block_eval_for_export(
+        @bash_script_lines, @export,
+        data: hash_data,
+        force: false,
+        silent: false
+      )
+
+      command_result, exportable, new_lines = result
+      assert_equal @mock_result, command_result
+      assert_equal true, exportable
+      assert_equal 2, new_lines.length
+    end
+
+    # Edge case: unsupported input type (Array)
+    def test_unsupported_input_type_array
+      result = @hd.ux_block_eval_for_export(
+        @bash_script_lines, @export,
+        data: %w[item1 item2],
+        force: false,
+        silent: false
+      )
+
+      command_result, exportable, new_lines = result
+      assert_nil command_result # No processing for unsupported types
+      assert_equal true, exportable # Initial value
+      assert_equal 0, new_lines.length
+    end
+
+    # Edge case: unsupported input type (custom object)
+    def test_unsupported_input_type_object
+      custom_object = Object.new
+      result = @hd.ux_block_eval_for_export(
+        @bash_script_lines, @export,
+        data: custom_object,
+        force: false,
+        silent: false
+      )
+
+      command_result, exportable, new_lines = result
+      assert_nil command_result # No processing for unsupported types
+      assert_equal true, exportable # Initial value
+      assert_equal 0, new_lines.length
+    end
+
+    # Test error handling - StandardError rescue
+    def test_standard_error_rescue
+      # Should not raise, but return nil due to rescue block
+      result = @hd.ux_block_eval_for_export(
+        @bash_script_lines, @export,
+        data: 'test_data',
+        force: false,
+        silent: false
+      )
+
+      command_result, = result
+      assert_equal 127, command_result.exit_status
+    end
+
+    # Test environment variable setting
+    def test_environment_variable_setting
+      @hd.stubs(:output_from_adhoc_bash_script_file).returns([@mock_result,
+                                                              true])
+      @hd.stubs(:variable_is_exportable).returns(true)
+
+      # Mock EnvInterface.set to verify it's called
+      EnvInterface.expects(:set).with('TEST_VAR', 'test_output')
+
+      @hd.ux_block_eval_for_export(
+        @bash_script_lines, @export,
+        data: 'echo "test"',
+        force: false,
+        silent: false
+      )
+    end
+
+    # Test join_array_of_arrays is called correctly
+    def test_join_array_of_arrays_called
+      @hd.stubs(:output_from_adhoc_bash_script_file).returns([@mock_result,
+                                                              true])
+      @hd.stubs(:variable_is_exportable).returns(true)
+
+      # Mock join_array_of_arrays to verify it's called with correct parameters
+      @hd.expects(:join_array_of_arrays).with(
+        @bash_script_lines,
+        ['test_data']
+      ).returns(['combined_script_lines'])
+
+      @hd.ux_block_eval_for_export(
+        @bash_script_lines, @export,
+        data: 'test_data',
+        force: false,
+        printf_expand: false,
+        silent: false
+      )
+    end
+  end
 end # module MarkdownExec