markdown_exec 2.8.2 → 2.8.4

data/lib/hash_delegator.rb

@@ -1,4 +1,4 @@
-#!/usr/bin/env bundle exec ruby
+#!/usr/bin/env -S bundle exec ruby
 # frozen_string_literal: true
 
 # encoding=utf-8
@@ -45,14 +45,6 @@ require_relative 'text_analyzer'
 $pd = false unless defined?($pd)
 $table_cell_truncate = true
 
-class String
-  # Checks if the string is not empty.
-  # @return [Boolean] Returns true if the string is not empty, false otherwise.
-  def non_empty?
-    !empty?
-  end
-end
-
 module HashDelegatorSelf
   # Applies an ANSI color method to a string using a specified color key.
   # The method retrieves the color method from the provided hash. If the
@@ -166,7 +158,7 @@ module HashDelegatorSelf
   #  (default is an empty string).
   # @return [String] A single string with each line indented as specified.
   def indent_all_lines(body, indent = nil)
-    return body unless indent&.non_empty?
+    return body unless indent&.present?
 
     body.lines.map { |line| indent + line.chomp }.join("\n")
   end
@@ -395,10 +387,17 @@ 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, source_id: '', &block)
+  def yield_line_if_selected(line, selected_types, all_fcbs: nil,
+                             source_id: '', &block)
     return unless block && block_type_selected?(selected_types, :line)
 
-    block.call(:line, MarkdownExec::FCB.new(body: [line], id: source_id))
+    block.call(:line, persist_fcb_self(all_fcbs, body: [line], id: source_id))
+  end
+
+  def persist_fcb_self(all_fcbs, options)
+    fcb = MarkdownExec::FCB.new(options)
+    all_fcbs << fcb if all_fcbs
+    fcb
   end
 end
 
@@ -609,6 +608,7 @@ module MarkdownExec
       @dml_link_state = Struct.new(:document_filename, :inherited_lines)
                               .new(@delegate_object[:filename], [])
       @dml_menu_blocks = []
+      @fcb_store = [] # all fcbs created
 
       @p_all_arguments = []
       @p_options_parsed = []
@@ -737,7 +737,7 @@ module MarkdownExec
 
       formatted_name = format(@delegate_object[:menu_link_format],
                               HashDelegator.safeval(option_name))
-      chrome_block = FCB.new(
+      chrome_block = persist_fcb(
         chrome: true,
         dname: HashDelegator.new(@delegate_object).string_send_color(
           formatted_name, :menu_chrome_color
@@ -781,7 +781,7 @@ module MarkdownExec
       chrome_blocks = link_state.inherited_lines_map do |line|
         formatted = format(@delegate_object[:menu_inherited_lines_format],
                            { line: line })
-        FCB.new(
+        persist_fcb(
           chrome: true,
           disabled: TtyMenu::DISABLE,
           dname: HashDelegator.new(@delegate_object).string_send_color(
@@ -840,25 +840,6 @@ module MarkdownExec
       end
     end
 
-    # private
-
-    def expand_references!(fcb, link_state)
-      expand_variable_references!(
-        blocks: [fcb],
-        initial_code_required: false,
-        link_state: link_state
-      )
-      expand_variable_references!(
-        blocks: [fcb],
-        echo_format: '%s',
-        group_name: :command,
-        initial_code_required: false,
-        key_format: '$(%s)',
-        link_state: link_state,
-        pattern: options_command_substitution_regexp
-      )
-    end
-
     # Iterates through nested files to collect various types
     #  of blocks, including dividers, tasks, and others.
     # The method categorizes blocks based on their type and processes them accordingly.
@@ -873,12 +854,15 @@ module MarkdownExec
 
       count = 0
       blocks = []
+      results = {}
       iter_blocks_from_nested_files do |btype, fcb|
         count += 1
         case btype
         when :blocks
+          result = SuccessResult.instance
           if @delegate_object[:bash]
-            fcb.for_menu!(
+            # prepare block for menu, may fail and call HashDelegator.error_handler
+            result = fcb.for_menu!(
               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],
@@ -889,10 +873,11 @@ module MarkdownExec
             ) do |oname, color|
               apply_block_type_color_option(oname, color)
             end
+            results[fcb.id] = result if result.failure?
           else
             expand_references!(fcb, link_state)
           end
-          blocks << fcb
+          blocks << fcb unless result.failure?
         when :filter # types accepted
           %i[blocks line]
         when :line
@@ -907,36 +892,12 @@ module MarkdownExec
           end
         end
       end
-      # !!t blocks.count
-      blocks
+      OpenStruct.new(blocks: blocks, results: results)
     rescue StandardError
+      # ww $@, $!,
       HashDelegator.error_handler('blocks_from_nested_files')
     end
 
-    # find a block by its original (undecorated) name or nickname (not visible in menu)
-    # if matched, the block returned has properties that it is from cli and not ui
-    def block_state_for_name_from_cli(block_name)
-      SelectedBlockMenuState.new(
-        blocks_find_by_block_name(@dml_blocks_in_file, block_name),
-        OpenStruct.new(
-          block_name_from_cli: true,
-          block_name_from_ui: false
-        ),
-        MenuState::CONTINUE
-      )
-    end
-
-    def blocks_find_by_block_name(blocks, block_name)
-      @dml_blocks_in_file.find do |item|
-        # 2024-08-04 match oname for long block names
-        # 2024-08-04 match nickname for long block names
-        block_name == item.pub_name || block_name == item.nickname || block_name == item.oname
-      end || @dml_menu_blocks.find do |item|
-        # 2024-08-22 search in menu blocks to allow matching of automatic chrome with nickname
-        block_name == item.pub_name || block_name == item.nickname || block_name == item.oname
-      end
-    end
-
     def build_menu_options(exit_option, display_mode_option,
                            menu_entries, display_format)
       [exit_option,
@@ -949,7 +910,8 @@ module MarkdownExec
       initial_code_required: false, key_format:
     )
       evaluate_shell_expressions(
-        (link_state&.inherited_lines_block || ''), commands,
+        (link_state&.inherited_lines_block || ''),
+        commands,
         initial_code_required: initial_code_required,
         key_format: key_format
       )
@@ -1025,6 +987,21 @@ module MarkdownExec
       ]
     end
 
+    # Executes the allowed exec command and processes the output
+    # @param export [Object] The export configuration object
+    # @param inherited_code [Array] The inherited code lines
+    # @param code_lines [Array] The code lines to append to
+    # @param required [Hash] Required code information
+    # @return [String, Symbol] The command output or :ux_exec_prohibited if execution failed
+    def process_allowed_exec(export, inherited_code, code_lines, required)
+      output = export_exec_with_code(
+        export, inherited_code, code_lines, required
+      )
+      return :ux_exec_prohibited if output == :invalidated
+
+      output.split("\n")
+    end
+
     # 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(
@@ -1058,82 +1035,30 @@ module MarkdownExec
             code_lines.push "[[ -z $#{precondition} ]] && exit 1"
           end
 
-          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
-                      export.default.to_s
-                    end
-          else
-            value = nil
-
-            # exec > allowed
-            if export.exec
-              value = export_exec_with_code(
+            value, exportable, transformable =
+              ux_block_export_automatic(
                 export, inherited_code, code_lines, required
               )
-              if value == :invalidated
-                return :ux_exec_prohibited
-              end
-
-            # 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
+          else
+            value, exportable, transformable =
+              ux_block_export_activated(
+                export, inherited_code, code_lines, required, exit_prompt
+              )
+          end
+          return :ux_exec_prohibited if value == :ux_exec_prohibited
 
-            # default
-            else
-              value = export.default
+          if SelectResponse.continue?(value)
+            if transformable
+              value = transform_export_value(value, export)
             end
 
             if exportable
-              value = transform_export_value(value, export)
+              ENV[export.name] = value.to_s
+              code_lines.push code_line_safe_assign(export.name, value,
+                                                    force: force)
             end
           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
@@ -1382,7 +1307,7 @@ module MarkdownExec
         next if exclude_types.include?(block.type)
 
         # Scan each block name for matches of the pattern
-        ([block.oname || ''] + block.body).join("\n").scan(pattern) do |(_, _variable_name)|
+        count_named_group_occurrences_block_body_fix_indent(block).scan(pattern) do |(_, _variable_name)|
           pattern.match($LAST_MATCH_INFO.to_s) # Reapply match for named groups
           occurrence_count[$LAST_MATCH_INFO[group_name]] += 1
         end
@@ -1391,6 +1316,11 @@ module MarkdownExec
       occurrence_count
     end
 
+    def count_named_group_occurrences_block_body_fix_indent(block)
+      ### actually double the entries, but not a problem since it's used as a boolean
+      ([block.oname || ''] + block.body).join("\n")
+    end
+
     ##
     # Creates and adds a formatted block to the blocks array
     #  based on the provided match and format options.
@@ -1432,10 +1362,30 @@ module MarkdownExec
       line_cap[:line] ||= ''
 
       line_caps = [line_cap]
-      if wrap && line_cap[:text].length > screen_width_for_wrapping
-        wrapper = StringWrapper.new(width: screen_width_for_wrapping - line_cap[:indent].length)
-        line_caps = wrapper.wrap(line_cap[:text]).map do |wrapped_line|
-          line_cap.dup.merge(text: wrapped_line)
+
+      # split text with newlines, from variable expansion
+      if line_cap[:text].include?("\n")
+        lines = line_cap[:text].split("\n")
+        line_caps = (lines.map do |line|
+                          line_cap.dup.merge(text: line)
+                        end.to_a)
+      end
+
+      # wrap text on multiple lines to screen width, replacing line_caps
+      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)
+        
+          if text.length > screen_width_for_wrapping
+            # Wrap this text and create line_cap objects for each part
+            wrapper.wrap(text).map do |wrapped_text|
+              line_cap.dup.merge(text: wrapped_text)
+            end
+          else
+            # No change needed for this line
+            line_cap
+          end
         end
       end
 
@@ -1492,7 +1442,7 @@ module MarkdownExec
           fcb.type = type
           use_fcb = false # next line is new record
         else
-          fcb = FCB.new(
+          fcb = persist_fcb(
             center: center,
             chrome: true,
             collapse: collapse.nil? ? (line_obj[:collapse] == COLLAPSIBLE_TOKEN_COLLAPSE) : collapse,
@@ -1534,7 +1484,9 @@ module MarkdownExec
         if block_given?
           # expand references only if block is recognized (not a comment)
           yield if block_given?
-          mbody = fcb.body[0].match @delegate_object[criteria[:match]]
+
+          # parse multiline to capture output of variable expansion
+          mbody = fcb.body[0].match Regexp.new(@delegate_object[criteria[:match]], Regexp::MULTILINE)
         end
 
         create_and_add_chrome_block(
@@ -1579,7 +1531,7 @@ module MarkdownExec
       oname = format(@delegate_object[:menu_divider_format],
                      HashDelegator.safeval(@delegate_object[divider_key]))
 
-      FCB.new(
+      persist_fcb(
         chrome: true,
         disabled: TtyMenu::DISABLE,
         dname: string_send_color(oname, :menu_divider_color),
@@ -1989,7 +1941,7 @@ module MarkdownExec
     end
 
     def execute_block_in_state(block_name)
-      @dml_block_state = block_state_for_name_from_cli(block_name)
+      @dml_block_state = find_block_state_by_name(block_name)
       dump_and_warn_block_state(name: block_name,
                                 selected: @dml_block_state.block)
       next_block_state =
@@ -2439,7 +2391,8 @@ module MarkdownExec
       # update blocks
       #
       Regexp.union(replacements.keys.map do |word|
-                     Regexp.new(Regexp.escape(word))
+                     # match multiline text from variable expansion
+                     Regexp.new(Regexp.escape(word), Regexp::MULTILINE)
                    end).tap do |pattern|
         menu_blocks.each do |block|
           next if exclude_types.include?(block.type)
@@ -2449,9 +2402,26 @@ module MarkdownExec
       end
     end
 
+    def expand_references!(fcb, link_state)
+      expand_variable_references!(
+        blocks: [fcb],
+        initial_code_required: false,
+        link_state: link_state
+      )
+      expand_variable_references!(
+        blocks: [fcb],
+        echo_format: '%s',
+        group_name: :command,
+        initial_code_required: false,
+        key_format: '$(%s)',
+        link_state: link_state,
+        pattern: options_command_substitution_regexp
+      )
+    end
+
     def expand_variable_references!(
       blocks:,
-      echo_format: 'echo $%s',
+      echo_format: 'echo "$%s"',
       group_name: :variable,
       initial_code_required: false,
       key_format: '${%s}',
@@ -2479,6 +2449,40 @@ module MarkdownExec
       expand_blocks_with_replacements(blocks, replacements)
     end
 
+    def export_echo_with_code_single(export_echo, inherited_code, code_lines,
+                                     required)
+      code = %(printf '%s' "#{export_echo}")
+      value = execute_temporary_script(
+        code,
+        (inherited_code || []) +
+         code_lines + required[:code]
+      )
+      if value == :invalidated
+        warn "A value must exist for: #{export.preconditions.join(', ')}"
+      end
+      value
+    end
+
+    def export_echo_with_code(export, inherited_code, code_lines, required,
+                              force:)
+      exportable = true
+      case export.echo
+      when String
+        value = export_echo_with_code_single(export.echo, inherited_code,
+                                             code_lines, required)
+      when Hash
+        # each item in the hash is a variable name and value
+        export.echo.each do |name, expression|
+          value = export_echo_with_code_single(expression, inherited_code,
+                                               code_lines, required)
+          ENV[name] = value.to_s
+          code_lines.push code_line_safe_assign(name, value, force: force)
+        end
+        exportable = false
+      end
+      [value, exportable]
+    end
+
     def export_exec_with_code(export, inherited_code, code_lines, required)
       value = execute_temporary_script(
         export.exec,
@@ -2524,6 +2528,31 @@ module MarkdownExec
       { size: file_size, lines: line_count }
     end
 
+    # Search in @dml_blocks_in_file first,
+    # 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)
+      end
+
+      @dml_blocks_in_file.find(&match_block) ||
+        @dml_menu_blocks.find(&match_block)
+    end
+
+    # find a block by its original (undecorated) name or nickname (not visible in menu)
+    # if matched, the block returned has properties that it is from cli and not ui
+    def find_block_state_by_name(block_name)
+      SelectedBlockMenuState.new(
+        find_block_by_name(@dml_blocks_in_file, block_name),
+        OpenStruct.new(
+          block_name_from_cli: true,
+          block_name_from_ui: false
+        ),
+        MenuState::CONTINUE
+      )
+    end
+
     def format_and_execute_command(
       code_lines:,
       erls:,
@@ -2532,6 +2561,7 @@ module MarkdownExec
       formatted_command = code_lines.flatten.join("\n")
       @fout.fout fetch_color(data_sym: :script_execution_head,
                              color_sym: :script_execution_frame_color)
+
       command_execute(
         formatted_command,
         args: @pass_args,
@@ -2641,10 +2671,8 @@ module MarkdownExec
       @process_mutex.synchronize do
         Thread.new do
           stream.each_line do |line|
-            line.strip!
             if @run_state.files.streams
-              @run_state.files.append_stream_line(file_type,
-                                                  line)
+              @run_state.files.append_stream_line(file_type, line)
             end
 
             puts line if @delegate_object[:output_stdout]
@@ -2692,7 +2720,7 @@ module MarkdownExec
          Regexp.new(@delegate_object.fetch(
                       :fenced_start_and_end_regex, '^(?<indent> *)`{3,}'
                     )),
-        fcb: MarkdownExec::FCB.new(id: 'INIT'),
+        fcb: persist_fcb(id: 'INIT'),
         in_fenced_block: false,
         headings: []
       }
@@ -2717,7 +2745,7 @@ module MarkdownExec
           menu_entries, current_display_format
         )
 
-        selection = prompt_select_code_filename(
+        selection = prompt_select_from_list(
           menu_options,
           string: menu_title,
           color_sym: :prompt_color_after_script_execution
@@ -2773,7 +2801,7 @@ module MarkdownExec
     def iter_source_blocks(source, source_id: nil, &block)
       case source
       when 1
-        blocks_from_nested_files(source_id: source_id).each(&block)
+        blocks_from_nested_files(source_id: source_id).blocks.each(&block)
       when 2
         @dml_blocks_in_file.each(&block)
       when 3
@@ -2816,7 +2844,8 @@ module MarkdownExec
                                                   nil),
             end_pattern: @delegate_object.fetch(:output_assignment_end, nil),
             scan1: @delegate_object.fetch(:output_assignment_match, nil),
-            format1: @delegate_object.fetch(:output_assignment_format, nil)
+            format1: @delegate_object.fetch(:output_assignment_format, nil),
+            name: ''
           )
 
         else
@@ -3077,7 +3106,7 @@ module MarkdownExec
       else
         ## user selects from existing files or other
         #
-        case (name = prompt_select_code_filename(
+        case (name = prompt_select_from_list(
           [@delegate_object[:prompt_filespec_back]] + files,
           string: @delegate_object[:prompt_select_code_file],
           color_sym: :prompt_color_after_script_execution
@@ -3108,11 +3137,19 @@ module MarkdownExec
     end
 
     def mdoc_and_blocks_from_nested_files(source_id: nil)
-      menu_blocks = blocks_from_nested_files(source_id: source_id)
-      mdoc = MDoc.new(menu_blocks) do |nopts|
+      blocks_results = blocks_from_nested_files(source_id: source_id)
+
+      blocks_results.results.select do |_id, result|
+        result.failure?
+      end.each do |id, result|
+        HashDelegator.error_handler("#{id} - #{result.to_yaml}")
+      end
+
+      mdoc = MDoc.new(blocks_results.blocks) do |nopts|
         @delegate_object.merge!(nopts)
       end
-      [menu_blocks, mdoc]
+
+      [blocks_results.blocks, mdoc]
     end
 
     ## Handles the file loading and returns the blocks
@@ -3180,7 +3217,7 @@ module MarkdownExec
       #
       menu_blocks.each do |fcb|
         fcb.body = fcb.raw_body || fcb.body || []
-        fcb.dname = fcb.raw_dname || fcb.dname
+        fcb.name_in_menu!(fcb.raw_dname || fcb.dname)
         fcb.s0printable = fcb.raw_s0printable || fcb.s0printable
         fcb.s1decorated = fcb.raw_s1decorated || fcb.s1decorated
         expand_references!(fcb, link_state)
@@ -3212,7 +3249,7 @@ module MarkdownExec
       #
       return unless block.nil?
 
-      chrome_block = FCB.new(
+      chrome_block = persist_fcb(
         chrome: true,
         disabled: TtyMenu::DISABLE,
         dname: HashDelegator.new(@delegate_object).string_send_color(
@@ -3259,6 +3296,19 @@ module MarkdownExec
       end
     end
 
+    def menu_from_list_with_back(list)
+      case (name = prompt_select_from_list(
+        [@delegate_object[:prompt_filespec_back]] + list,
+        string: @delegate_object[:prompt_select_code_file],
+        color_sym: :prompt_color_after_script_execution
+      ))
+      when @delegate_object[:prompt_filespec_back]
+        SelectResponse::BACK
+      else
+        name
+      end
+    end
+
     def menu_toggle_collapsible_block(selected)
       # return true if @compress_ids.key?(fcb.id) && !!@compress_ids[fcb.id]
       # return false if @expand_ids.key?(fcb.id) && !!@expand_ids[fcb.id]
@@ -3371,6 +3421,12 @@ module MarkdownExec
         prompt_select_continue == MenuState::EXIT
     end
 
+    def persist_fcb(options)
+      MarkdownExec::FCB.new(options).tap do |fcb|
+        @fcb_store << fcb
+      end
+    end
+
     def pop_add_current_code_to_head_and_trigger_load(
       link_state, block_names, code_lines,
       dependencies, selected, next_block_name: nil
@@ -3486,7 +3542,7 @@ module MarkdownExec
     # private
 
     def process_string_array(arr, begin_pattern: nil, end_pattern: nil, scan1: nil,
-                             format1: nil)
+                             format1: nil, name: '')
       in_block = !begin_pattern.present?
       collected_lines = []
 
@@ -3508,6 +3564,9 @@ module MarkdownExec
                 collected_lines << formatted
               end
             end
+          elsif format1.present?
+            formatted = format(format1, { value: line })
+            collected_lines << formatted
           else
             collected_lines << line
           end
@@ -3633,9 +3692,22 @@ module MarkdownExec
       0
     end
 
+    def prompt_select_continue(filter: true, quiet: true)
+      sel = @prompt.select(
+        string_send_color(@delegate_object[:prompt_after_script_execution],
+                          :prompt_color_after_script_execution),
+        filter: filter,
+        quiet: quiet
+      ) do |menu|
+        menu.choice @delegate_object[:prompt_yes]
+        menu.choice @delegate_object[:prompt_exit]
+      end
+      sel == @delegate_object[:prompt_exit] ? MenuState::EXIT : MenuState::CONTINUE
+    end
+
     # public
 
-    def prompt_select_code_filename(
+    def prompt_select_from_list(
       filenames,
       color_sym: :prompt_color_after_script_execution,
       cycle: true,
@@ -3661,19 +3733,6 @@ module MarkdownExec
       end
     end
 
-    def prompt_select_continue(filter: true, quiet: true)
-      sel = @prompt.select(
-        string_send_color(@delegate_object[:prompt_after_script_execution],
-                          :prompt_color_after_script_execution),
-        filter: filter,
-        quiet: quiet
-      ) do |menu|
-        menu.choice @delegate_object[:prompt_yes]
-        menu.choice @delegate_object[:prompt_exit]
-      end
-      sel == @delegate_object[:prompt_exit] ? MenuState::EXIT : MenuState::CONTINUE
-    end
-
     # user prompt to exit if the menu will be displayed again
     #
     def prompt_user_exit(block_name_from_cli:, selected:)
@@ -3747,27 +3806,6 @@ module MarkdownExec
       end&.compact
     end
 
-    def saved_asset_for_history(
-      file:, form:, match_info:
-    )
-      OpenStruct.new(
-        file: file[(Dir.pwd.length + 1)..-1],
-        full: file,
-        row: format(
-          form,
-          # default '*' so unknown parameters are given a wildcard
-          match_info.names.each_with_object(Hash.new('*')) do |name, hash|
-            hash[name.to_sym] = match_info[name]
-          end
-        )
-      )
-    rescue KeyError
-      # pp $!, $@
-      warn "Cannot format with: #{@delegate_object[:saved_history_format]}"
-      error_handler('saved_history_format')
-      :break
-    end
-
     # Processes YAML data from the selected menu item, updating delegate
     #  objects and optionally printing formatted output.
     # @param selected [Hash] Selected item from the menu containing a YAML body.
@@ -3822,8 +3860,8 @@ module MarkdownExec
     #      console [height, width]. If not provided or if the terminal
     #      is resized, it will be set to the current console dimensions.
     #   - :select_page_height [Integer, nil] The height of the page for
-    #      selection. If not provided or if not positive, it will be set
-    #      to the maximum of (console height - 3) or 4.
+    #      selection. If not provided or if not positive, it
+    #      will be set to the maximum of (console height - 3) or 4.
     #   - :per_page [Integer, nil] The number of items per page. If
     #      :select_page_height is not provided or if not positive, it
     #      will be set to the maximum of (console height - 3) or 4.
@@ -3950,7 +3988,7 @@ module MarkdownExec
         ## user selects from existing files or other
         # input into path with wildcard for easy entry
         #
-        case (name = prompt_select_code_filename(
+        case (name = prompt_select_from_list(
           [@delegate_object[:prompt_filespec_back],
            @delegate_object[:prompt_filespec_other]] + files,
           string: @delegate_object[:prompt_select_code_file],
@@ -3987,6 +4025,27 @@ module MarkdownExec
       ).generate_name
     end
 
+    def saved_asset_for_history(
+      file:, form:, match_info:
+    )
+      OpenStruct.new(
+        file: file[(Dir.pwd.length + 1)..-1],
+        full: file,
+        row: format(
+          form,
+          # default '*' so unknown parameters are given a wildcard
+          match_info.names.each_with_object(Hash.new('*')) do |name, hash|
+            hash[name.to_sym] = match_info[name]
+          end
+        )
+      )
+    rescue KeyError
+      # pp $!, $@
+      warn "Cannot format with: #{@delegate_object[:saved_history_format]}"
+      error_handler('saved_history_format')
+      :break
+    end
+
     def screen_width
       width = @delegate_object[:screen_width]
       if width&.positive?
@@ -4195,7 +4254,7 @@ module MarkdownExec
                    TtyMenu::ENABLE
                  end
 
-      MarkdownExec::FCB.new(
+      persist_fcb(
         body: [],
         call: rest.match(
           Regexp.new(@delegate_object[:block_calls_scan])
@@ -4320,7 +4379,9 @@ module MarkdownExec
         # add line if it is depth 0 or option allows it
         #
         HashDelegator.yield_line_if_selected(
-          line, selected_types, source_id: source_id, &block
+          line, selected_types,
+          all_fcbs: @fcb_store,
+          source_id: source_id, &block
         )
       end
     end
@@ -4333,6 +4394,147 @@ module MarkdownExec
       @delegate_object.merge!(options)
     end
 
+    def ux_block_export_activated(export, inherited_code, code_lines, required,
+                                  exit_prompt)
+      exportable = true
+      transformable = true
+      [if export.allowed.present?
+         if export.allowed == :echo
+           output, exportable = export_echo_with_code(
+             export, inherited_code, code_lines, required, force: true
+           )
+           return :ux_exec_prohibited if output == :invalidated
+
+           menu_from_list_with_back(output.split("\n"))
+
+         elsif export.allowed == :exec
+           output = process_allowed_exec(export, inherited_code,
+                                         code_lines, required)
+           return :ux_exec_prohibited if output == :ux_exec_prohibited
+
+           menu_from_list_with_back(output)
+
+         else
+           menu_from_list_with_back(export.allowed)
+         end
+
+       # echo > exec
+       elsif export.echo
+         output, exportable = export_echo_with_code(
+           export, inherited_code, code_lines, required, force: true
+         )
+         return :ux_exec_prohibited if output == :invalidated
+
+         output
+
+       # exec > allowed
+       elsif export.exec
+         output = export_exec_with_code(
+           export, inherited_code, code_lines, required
+         )
+         return :ux_exec_prohibited if output == :invalidated
+
+         output
+
+       # allowed > prompt
+       elsif export.allowed && export.allowed.count.positive?
+         case (choice = prompt_select_from_list(
+           [exit_prompt] + export.allowed,
+           string: export.prompt,
+           color_sym: :prompt_color_after_script_execution
+         ))
+         when exit_prompt
+           exportable = false
+           transformable = false
+           nil
+         else
+           choice
+         end
+
+       # prompt > default
+       elsif export.prompt.present?
+         begin
+           loop do
+             print "#{export.prompt} [#{export.default}]: "
+             output = gets.chomp
+             output = export.default.to_s if output.empty?
+             caps = NamedCaptureExtractor.extract_named_groups(output,
+                                                               export.validate)
+             break if caps
+
+             # invalid input, retry
+           end
+         rescue Interrupt
+           exportable = false
+           transformable = false
+         end
+
+         output
+
+       # default
+       else
+         transformable = false
+         export.default
+       end, exportable, transformable]
+    end
+
+    def ux_block_export_automatic(export, inherited_code, code_lines, required)
+      transformable = true
+      exportable = true
+      [case export.default
+       when :allowed
+         raise unless export.allowed.present?
+
+         if export.allowed == :echo
+           output, exportable = export_echo_with_code(
+             export, inherited_code, code_lines, required, force: false
+           )
+           return :ux_exec_prohibited if output == :invalidated
+
+           exportable && output.split("\n").first
+
+         elsif export.allowed == :exec
+           output = process_allowed_exec(export, inherited_code,
+                                         code_lines, required)
+           return :ux_exec_prohibited if output == :ux_exec_prohibited
+
+           output.first
+
+         else
+           export.allowed.first
+         end
+
+       # echo > default
+       when :echo
+         raise unless export.echo.present?
+
+         output, exportable = export_echo_with_code(
+           export, inherited_code, code_lines, required, force: false
+         )
+         return :ux_exec_prohibited if output == :invalidated
+
+         output
+
+       # exec > default
+       when :exec
+         raise unless export.exec.present?
+
+         output = export_exec_with_code(
+           export, inherited_code, code_lines, required
+         )
+         return :ux_exec_prohibited if output == :invalidated
+
+         output
+
+       # default
+       else
+         transformable = false
+         export.default.to_s
+       end,
+       exportable,
+       transformable]
+    end
+
     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,
@@ -4359,7 +4561,7 @@ module MarkdownExec
     end
 
     def vux_execute_and_prompt(block_name)
-      @dml_block_state = block_state_for_name_from_cli(block_name)
+      @dml_block_state = find_block_state_by_name(block_name)
       if @dml_block_state.block &&
          @dml_block_state.block.type == BlockType::OPTS
         debounce_reset
@@ -4532,7 +4734,8 @@ module MarkdownExec
 
       inherited_block_names = []
       inherited_dependencies = {}
-      selected = FCB.new(oname: 'load_code')
+      selected = persist_fcb(oname: 'load_code')
+
       pop_add_current_code_to_head_and_trigger_load(
         @dml_link_state, inherited_block_names,
         code_lines, inherited_dependencies, selected
@@ -4800,7 +5003,7 @@ module MarkdownExec
     def vux_user_selected_block_name
       if @dml_link_state.block_name.present?
         # @prior_block_was_link = true
-        @dml_block_state.block = blocks_find_by_block_name(
+        @dml_block_state.block = find_block_by_name(
           @dml_blocks_in_file,
           @dml_link_state.block_name
         )
@@ -5269,7 +5472,7 @@ module MarkdownExec
     end
 
     def test_blocks_from_nested_files
-      result = @hd.blocks_from_nested_files
+      result = @hd.blocks_from_nested_files.blocks
       assert_kind_of Array, result
       assert_kind_of FCB, result.first
     end
@@ -5278,7 +5481,7 @@ module MarkdownExec
       @hd = HashDelegator.new(no_chrome: true)
       @hd.expects(:create_and_add_chrome_blocks).never
 
-      result = @hd.blocks_from_nested_files
+      result = @hd.blocks_from_nested_files.blocks
 
       assert_kind_of Array, result
     end
@@ -5724,7 +5927,7 @@ module MarkdownExec
       Thread.new { @hd.handle_stream(stream: stream, file_type: file_type) }
 
       @hd.wait_for_stream_processing
-      assert_equal ['line 1', 'line 2'],
+      assert_equal ["line 1\n", "line 2\n"],
                    @hd.instance_variable_get(:@run_state)
                       .files.stream_lines(ExecutionStreams::STD_OUT)
     end