markdown_exec 2.8.1 → 2.8.3

data/lib/hash_delegator.rb

@@ -306,7 +306,7 @@ module HashDelegatorSelf
       table__hs.each do |table_hs|
         table_hs.substrings.each do |substrings|
           substrings.each do |node|
-            next unless node[:text].class == TrackedString
+            next unless node[:text].instance_of?(TrackedString)
 
             exceeded_table_cell ||= node[:text].exceeded
             truncated_table_cell = node[:text].truncated
@@ -395,10 +395,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
 
@@ -606,6 +613,10 @@ module MarkdownExec
 
       @process_mutex = Mutex.new
       @process_cv = ConditionVariable.new
+      @dml_link_state = Struct.new(:document_filename, :inherited_lines)
+                              .new(@delegate_object[:filename], [])
+      @dml_menu_blocks = []
+      @fcb_store = [] # all fcbs created
 
       @p_all_arguments = []
       @p_options_parsed = []
@@ -734,7 +745,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
@@ -778,7 +789,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(
@@ -837,25 +848,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.
@@ -910,30 +902,6 @@ module MarkdownExec
       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,
@@ -1022,25 +990,11 @@ module MarkdownExec
       ]
     end
 
-    def neval(export_exec, inherited_code)
-      # ww0 export_exec
-      # ww0 inherited_code
-      code = (inherited_code || []) + [export_exec]
-      filespec = generate_temp_filename
-      File.write filespec, HashDelegator.join_code_lines(code)
-      File.chmod 0o755, filespec
-      # ww0 File.read(filespec)
-      ret = `#{filespec}`
-      File.delete filespec
-      ret
-    end
-
-    # sets ENV
+    # parse YAML body defining the UX for a single variable
+    # set ENV value for the variable and return code lines for the same
     def code_from_ux_block_to_set_environment_variables(
       selected, mdoc, inherited_code: nil, force: true, only_default: false
     )
-      # ww0 inherited_code
-      # ww0 mdoc
       exit_prompt = @delegate_object[:prompt_filespec_back]
 
       required = mdoc.collect_recursively_required_code(
@@ -1050,105 +1004,129 @@ module MarkdownExec
         block_source: block_source
       )
 
+      # process each ux block in sequence, setting ENV and collecting lines
       code_lines = []
-      case data = YAML.load(selected.body.join("\n"))
-      when Hash
-        export = parse_yaml_of_ux_block(
-          data,
-          prompt: @delegate_object[:prompt_ux_enter_a_value],
-          validate: '^(?<name>[^ ].*)$'
-        )
+      required[:blocks].each do |block|
+        next unless block.type == BlockType::UX
+
+        case data = YAML.load(block.body.join("\n"))
+        when Hash
+          export = parse_yaml_of_ux_block(
+            data,
+            prompt: @delegate_object[:prompt_ux_enter_a_value],
+            validate: '^(?<name>[^ ].*)$'
+          )
+
+          # preconditions are variable names that must be set before the UX block is executed.
+          # if any precondition is not set, the sequence is aborted.
+          export.preconditions&.each do |precondition|
+            code_lines.push "[[ -z $#{precondition} ]] && exit 1"
+          end
 
-        exportable = true
-        if only_default
-          value = case export.default
-                  # exec > default
-                  when :exec
-                    raise unless export.exec.present?
+          exportable = true
+          if only_default
+            value = case export.default
+                    # echo > default
+                    when :echo
+                      raise unless export.echo.present?
+
+                      output = export_echo_with_code(
+                        export, inherited_code, code_lines, required
+                      )
+                      if output == :invalidated
+                        return :ux_exec_prohibited
+                      end
 
-                    n1 = neval(export.exec,
-                               (inherited_code || []) + required[:code])
+                      transform_export_value(output, export)
 
-                    if export.transform.present?
-                      if export.transform.is_a? Symbol
-                        n1.send(export.transform)
-                      else
-                        format(
-                          export.transform,
-                          NamedCaptureExtractor.extract_named_groups(
-                            n1, export.validate
-                          )
-                        )
+                    # exec > default
+                    when :exec
+                      raise unless export.exec.present?
+
+                      output = export_exec_with_code(
+                        export, inherited_code, code_lines, required
+                      )
+                      if output == :invalidated
+                        return :ux_exec_prohibited
                       end
+
+                      transform_export_value(output, export)
+
+                    # default
                     else
-                      n1
+                      export.default.to_s
                     end
+          else
+            value = nil
 
-                  # default
-                  else
-                    export.default.to_s
-                  end
-        else
-          caps = nil
-          value = nil
-
-          # exec > allowed
-          if export.exec
-            value = neval(export.exec, (inherited_code || []) + required[:code])
-            caps = NamedCaptureExtractor.extract_named_groups(value,
-                                                              export.validate)
-
-          # allowed > prompt
-          elsif export.allowed && export.allowed.count.positive?
-            case (choice = prompt_select_code_filename(
-              [exit_prompt] + export.allowed,
-              string: export.prompt,
-              color_sym: :prompt_color_after_script_execution
-            ))
-            when exit_prompt
-              exportable = false
-            else
-              value = choice
-              caps = NamedCaptureExtractor.extract_named_groups(value,
-                                                                export.validate)
-            end
+            # echo > exec
+            if export.echo
+              value = export_echo_with_code(
+                export, inherited_code, code_lines, required
+              )
+              if value == :invalidated
+                return :ux_exec_prohibited
+              end
 
-          # prompt > default
-          elsif export.prompt.present?
-            begin
-              while true
-                print "#{export.prompt} [#{export.default}]: "
-                value = gets.chomp
-                value = export.default.to_s if value.empty?
-                caps = NamedCaptureExtractor.extract_named_groups(value,
-                                                                  export.validate)
-                break if caps
+            # exec > allowed
+            elsif export.exec
+              value = export_exec_with_code(
+                export, inherited_code, code_lines, required
+              )
+              if value == :invalidated
+                return :ux_exec_prohibited
+              end
 
-                # invalid input, retry
+            # allowed > prompt
+            elsif export.allowed && export.allowed.count.positive?
+              case (choice = prompt_select_code_filename(
+                [exit_prompt] + export.allowed,
+                string: export.prompt,
+                color_sym: :prompt_color_after_script_execution
+              ))
+              when exit_prompt
+                exportable = false
+              else
+                value = choice
+              end
 
+            # prompt > default
+            elsif export.prompt.present?
+              begin
+                loop do
+                  print "#{export.prompt} [#{export.default}]: "
+                  value = gets.chomp
+                  value = export.default.to_s if value.empty?
+                  caps = NamedCaptureExtractor.extract_named_groups(value,
+                                                                    export.validate)
+                  break if caps
+
+                  # invalid input, retry
+                end
+              rescue Interrupt
+                exportable = false
               end
-            rescue Interrupt
-              exportable = false
+
+            # default
+            else
+              value = export.default
             end
 
-          # default
-          else
-            value = export.default
+            if exportable
+              value = transform_export_value(value, export)
+            end
           end
 
-          if exportable && export.transform.present?
-            value = format(export.transform, caps)
+          if exportable
+            ENV[export.name] = value.to_s
+            code_lines.push code_line_safe_assign(export.name, value,
+                                                  force: force)
           end
+        else
+          raise "Invalid data type: #{data.inspect}"
         end
-
-        if exportable
-          ENV[export.name] = value.to_s
-          code_lines.push code_line_safe_assign(export.name, value,
-                                                force: force)
-        end
-      else
-        raise "Invalid data type: #{data.inspect}"
       end
+
       code_lines
     end
 
@@ -1221,7 +1199,8 @@ module MarkdownExec
         command_execute_in_process(
           args: args, command: command,
           erls: erls,
-          filename: @delegate_object[:filename], shell: shell
+          filename: @delegate_object[:filename],
+          shell: shell
         )
       end
 
@@ -1285,7 +1264,8 @@ module MarkdownExec
     )
       execute_command_with_streams(
         [shell, '-c', command,
-         @delegate_object[:filename], *args]
+         @delegate_object[:filename],
+         *args]
       )
     end
 
@@ -1390,7 +1370,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
@@ -1399,6 +1379,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.
@@ -1500,7 +1485,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,
@@ -1587,7 +1572,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),
@@ -1987,9 +1972,7 @@ module MarkdownExec
       )
 
       # dname is not fixed for some block types, use block id
-      if lfls.load_file != LoadFile::LOAD &&
-         [BlockType::HEADING, BlockType::TEXT,
-          BlockType::UX].include?(selected.type)
+      if lfls.load_file != LoadFile::LOAD
         block_selection = BlockSelection.new(selected.id)
       end
 
@@ -1999,7 +1982,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 =
@@ -2173,24 +2156,24 @@ module MarkdownExec
         else
           warn 'No matching file found.'
         end
-      elsif selected_option = select_option_with_metadata(
+      elsif (selected_option = select_option_with_metadata(
         prompt_title,
         [exit_prompt] + dirs.map do |file|
-          { name: format(
-            block_data['view'] || view,
-            NamedCaptureExtractor.extract_named_group_match_data(
-              file.match(
-                Regexp.new(block_data['filename_pattern'] ||
-                           filename_pattern)
-              )
-            )
-          ),
+          { name:
+              format(
+                block_data['view'] || view,
+                NamedCaptureExtractor.extract_named_group_match_data(
+                  file.match(
+                    Regexp.new(block_data['filename_pattern'] || filename_pattern)
+                  )
+                )
+              ),
             oname: file }
         end,
         menu_options.merge(
           cycle: true
         )
-      )
+      ))
         if selected_option.dname != exit_prompt
           File.readlines(selected_option.oname, chomp: true)
         end
@@ -2341,7 +2324,7 @@ module MarkdownExec
 
       interactive_menu_with_display_modes(
         files_table_rows,
-        display_formats: [:row, :file],
+        display_formats: %i[row file],
         display_mode_option: @delegate_object[:prompt_filespec_facet],
         exit_option: exit_prompt,
         menu_title: @delegate_object[:prompt_select_history_file],
@@ -2364,9 +2347,9 @@ module MarkdownExec
     def execute_inherited_save(
       code_lines: @dml_link_state.inherited_lines
     )
-      return unless save_filespec = save_filespec_from_expression(
-        document_name_in_glob_as_file_name
-      )
+      return unless (save_filespec = save_filespec_from_expression)
+
+      document_name_in_glob_as_file_name
 
       unless write_file_with_directory_creation(
         content: HashDelegator.join_code_lines(code_lines),
@@ -2422,6 +2405,27 @@ module MarkdownExec
       post_execution_process
     end
 
+    def execute_temporary_script(script_code, additional_code = [])
+      full_code = (additional_code || []) + [script_code]
+
+      Tempfile.create('script_exec') do |temp_file|
+        temp_file.write(HashDelegator.join_code_lines(full_code))
+        temp_file.flush
+        File.chmod(0o755, temp_file.path)
+
+        output = `#{temp_file.path}`
+
+        if $?.exitstatus != 0
+          return :invalidated
+        end
+
+        output
+      end
+    rescue StandardError => err
+      warn "Error executing script: #{err.message}"
+      nil
+    end
+
     def expand_blocks_with_replacements(
       menu_blocks, replacements, exclude_types: [BlockType::SHELL]
     )
@@ -2438,6 +2442,23 @@ 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',
@@ -2468,6 +2489,30 @@ module MarkdownExec
       expand_blocks_with_replacements(blocks, replacements)
     end
 
+    def export_echo_with_code(export, inherited_code, code_lines, required)
+      value = execute_temporary_script(
+        %Q{eval printf '%s' "#{export.echo}"},
+        (inherited_code || []) +
+         code_lines + required[:code]
+      )
+      if value == :invalidated
+        warn "A value must exist for: #{export.preconditions.join(', ')}"
+      end
+      value
+    end
+
+    def export_exec_with_code(export, inherited_code, code_lines, required)
+      value = execute_temporary_script(
+        export.exec,
+        (inherited_code || []) +
+         code_lines + required[:code]
+      )
+      if value == :invalidated
+        warn "A value must exist for: #{export.preconditions.join(', ')}"
+      end
+      value
+    end
+
     # Retrieves a specific data symbol from the delegate object,
     # converts it to a string, and applies a color style
     # based on the specified color symbol.
@@ -2501,6 +2546,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:,
@@ -2509,6 +2579,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,
@@ -2580,7 +2651,7 @@ module MarkdownExec
       # commands to echo variables
       #
       commands = {}
-      variable_counts.each do |variable, _count|
+      variable_counts.each_key do |variable|
         command = format(echo_format, variable)
         commands[variable] = command
       end
@@ -2618,10 +2689,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]
@@ -2637,7 +2706,6 @@ module MarkdownExec
     end
 
     def history_files(
-      link_state,
       direction: :reverse,
       filename: nil,
       home: Dir.pwd,
@@ -2670,7 +2738,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: []
       }
@@ -2950,19 +3018,24 @@ module MarkdownExec
       @ux_most_recent_filename = @delegate_object[:filename]
 
       (blocks.each.with_object([]) do |block, merged_options|
-        merged_options.push(
-          code_from_ux_block_to_set_environment_variables(
-            block,
-            mdoc,
-            force: @delegate_object[:ux_auto_load_force_default],
-            only_default: true
-          )
+        code = code_from_ux_block_to_set_environment_variables(
+          block,
+          mdoc,
+          force: @delegate_object[:ux_auto_load_force_default],
+          only_default: true
         )
+        if code == :ux_exec_prohibited
+          merged_options
+        else
+          merged_options.push(code)
+        end
       end).to_a
     end
 
-    def load_auto_vars_block(all_blocks,
-                             block_name: @delegate_object[:document_load_vars_block_name])
+    def load_auto_vars_block(
+      all_blocks,
+      block_name: @delegate_object[:document_load_vars_block_name]
+    )
       unless block_name.present? &&
              @vars_most_recent_filename != @delegate_object[:filename]
         return
@@ -3103,7 +3176,7 @@ module MarkdownExec
 
       # load document shell block
       #
-      if code_lines = load_document_shell_block(all_blocks, mdoc: mdoc)
+      if (code_lines = load_document_shell_block(all_blocks, mdoc: mdoc))
         next_state_set_code(nil, link_state, code_lines)
         link_state.inherited_lines = code_lines
         reload_blocks = true
@@ -3111,7 +3184,7 @@ module MarkdownExec
 
       # load document ux block
       #
-      if code_lines = load_auto_ux_block(all_blocks, mdoc)
+      if (code_lines = load_auto_ux_block(all_blocks, mdoc))
         new_code = HashDelegator.code_merge(link_state.inherited_lines,
                                             code_lines)
         next_state_set_code(nil, link_state, new_code)
@@ -3121,7 +3194,7 @@ module MarkdownExec
 
       # load document vars block
       #
-      if code_lines = load_auto_vars_block(all_blocks)
+      if (code_lines = load_auto_vars_block(all_blocks))
         new_code = HashDelegator.code_merge(link_state.inherited_lines,
                                             code_lines)
         next_state_set_code(nil, link_state, new_code)
@@ -3153,7 +3226,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)
@@ -3185,7 +3258,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(
@@ -3267,7 +3340,10 @@ module MarkdownExec
       next_state_set_code(
         selected,
         link_state,
-        HashDelegator.code_merge(link_state&.inherited_lines, code_lines)
+        HashDelegator.code_merge(
+          link_state&.inherited_lines,
+          code_lines.is_a?(Array) ? code_lines : [] # no code for :ux_exec_prohibited
+        )
       )
     end
 
@@ -3341,6 +3417,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
@@ -3409,8 +3491,8 @@ module MarkdownExec
     #
     # @param all_blocks [Array<Hash>] The list of blocks from the file.
     def select_blocks(menu_blocks)
-      menu_blocks.select do |fcb|
-        !Filter.prepared_not_in_menu?(
+      menu_blocks.reject do |fcb|
+        Filter.prepared_not_in_menu?(
           @delegate_object,
           fcb,
           %i[block_name_include_match block_name_wrapper_match]
@@ -3659,16 +3741,16 @@ module MarkdownExec
 
       case @delegate_object[:publish_document_file_mode]
       when 'append'
-        File.write(pipe_path, message + "\n", mode: 'a')
+        File.write(pipe_path, "#{message}\n", mode: 'a')
       when 'fifo'
         unless @vux_pipe_open
           unless File.exist?(pipe_path)
-            FileUtils.mkfifo(pipe_path)
+            File.mkfifo(pipe_path)
             @vux_pipe_created = pipe_path
           end
           @vux_pipe_open = File.open(pipe_path, 'w')
         end
-        @vux_pipe_open.puts(message + "\n")
+        @vux_pipe_open.puts("#{message}\n")
         @vux_pipe_open.flush
       when 'write'
         File.write(pipe_path, message)
@@ -3695,7 +3777,6 @@ module MarkdownExec
       regexp: @delegate_object[:saved_asset_match]
     )
       history_files(
-        @dml_link_state,
         filename:
           if asset.present?
             saved_asset_filename(asset, @dml_link_state)
@@ -3710,7 +3791,8 @@ module MarkdownExec
         end
 
         saved_asset = saved_asset_for_history(
-          file: file, form: form,
+          file: file,
+          form: form,
           match_info: $LAST_MATCH_INFO
         )
         saved_asset == :break ? nil : saved_asset
@@ -3959,7 +4041,7 @@ module MarkdownExec
 
     def screen_width
       width = @delegate_object[:screen_width]
-      if width && width.positive?
+      if width&.positive?
         width
       else
         @delegate_object[:console_width]
@@ -3976,7 +4058,7 @@ module MarkdownExec
     end
 
     def select_document_if_multiple(options, files, prompt:)
-      return files if files.class == String
+      return files if files.instance_of?(String)
       return files[0] if (count = files.count) == 1
 
       return unless count >= 2
@@ -3994,7 +4076,11 @@ module MarkdownExec
 
     # Presents a TTY prompt to select an option or exit,
     #  returns metadata including option and selected
-    def select_option_with_metadata(prompt_text, menu_items, opts = {})
+    def select_option_with_metadata(
+      prompt_text, menu_items, opts = {}, menu_blocks: nil
+    )
+      @dml_menu_blocks = menu_blocks if menu_blocks
+
       ## configure to environment
       #
       register_console_attributes(opts)
@@ -4039,23 +4125,16 @@ module MarkdownExec
         return
       end
 
-      selected = menu_items.find do |item|
+      selected = @dml_menu_blocks.find do |item|
         if item.instance_of?(Hash)
           [item[:id], item[:name], item[:dname]].include?(selection)
         elsif item.instance_of?(MarkdownExec::FCB)
-          item.dname == selection || item.id == selection
+          item.id == selection
         else
           item == selection
         end
       end
 
-      # new FCB if selected is not an object
-      if selected.instance_of?(String)
-        selected = FCB.new(dname: selected)
-      elsif selected.instance_of?(Hash)
-        selected = FCB.new(selected)
-      end
-
       unless selected
         HashDelegator.error_handler('select_option_with_metadata',
                                     error: 'menu item not found')
@@ -4168,7 +4247,7 @@ module MarkdownExec
                    TtyMenu::ENABLE
                  end
 
-      MarkdownExec::FCB.new(
+      persist_fcb(
         body: [],
         call: rest.match(
           Regexp.new(@delegate_object[:block_calls_scan])
@@ -4206,6 +4285,21 @@ module MarkdownExec
       HashDelegator.apply_color_from_hash(string, @delegate_object, color_sym)
     end
 
+    def transform_export_value(value, export)
+      return value unless export.transform.present?
+
+      if export.transform.is_a? Symbol
+        value.send(export.transform)
+      else
+        format(
+          export.transform,
+          NamedCaptureExtractor.extract_named_groups(
+            value, export.validate
+          )
+        )
+      end
+    end
+
     ##
     # Processes an individual line within a loop, updating headings
     #  and handling fenced code blocks.
@@ -4278,7 +4372,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
@@ -4317,7 +4413,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
@@ -4372,7 +4468,7 @@ module MarkdownExec
 
       when formatted_choice_ostructs[:history].pub_name
         debounce_reset
-        return :break unless files_table_rows = vux_history_files_table_rows
+        return :break unless (files_table_rows = vux_history_files_table_rows)
 
         execute_history_select(files_table_rows, stream: $stderr)
         return :break if pause_user_exit
@@ -4490,7 +4586,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
@@ -4498,9 +4595,9 @@ module MarkdownExec
     end
 
     def vux_load_inherited
-      return unless filespec = load_filespec_from_expression(
+      return unless (filespec = load_filespec_from_expression(
         document_name_in_glob_as_file_name
-      )
+      ))
 
       @dml_link_state.inherited_lines_append(
         File.readlines(filespec, chomp: true)
@@ -4619,7 +4716,6 @@ module MarkdownExec
     )
       if @delegate_object[:menu_for_history]
         history_files(
-          @dml_link_state,
           filename: saved_asset_filename(@delegate_object[:filename],
                                          @dml_link_state),
           path: @delegate_object[:saved_script_folder]
@@ -4759,7 +4855,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
         )
@@ -4818,15 +4914,17 @@ module MarkdownExec
                           menu_blocks.find do |block|
                             block.dname.include?(prior_answer)
                           end&.name
-                        when Struct
+                        when Struct, MarkdownExec::FCB
                           if prior_answer.id
-                            menu_items.find_index do |block|
+                            # when switching documents, the prior answer will not be found
+                            (menu_blocks.find_index do |block|
                               block[:id] == prior_answer.id
-                            end + 1
+                            end || 0) + 1
                           else
                             prior_answer.index || prior_answer.name
                           end
                         end
+
       # prior_answer value may not match if color is different from
       # originating menu (opts changed while processing)
       selection_opts = if selected_answer
@@ -5157,13 +5255,12 @@ module MarkdownExec
 
   class TestHashDelegatorAppendDivider < Minitest::Test
     def setup
-      @hd = HashDelegator.new
-      @hd.instance_variable_set(:@delegate_object, {
-                                  menu_divider_format: 'Format',
-                                  menu_initial_divider: 'Initial Divider',
-                                  menu_final_divider: 'Final Divider',
-                                  menu_divider_color: :color
-                                })
+      @hd = HashDelegator.new(
+        menu_divider_color: :color,
+        menu_divider_format: 'Format',
+        menu_final_divider: 'Final Divider',
+        menu_initial_divider: 'Initial Divider'
+      )
       @hd.stubs(:string_send_color).returns('Formatted Divider')
       HashDelegator.stubs(:safeval).returns('Safe Value')
     end
@@ -5185,7 +5282,7 @@ module MarkdownExec
     end
 
     def test_append_divider_without_format
-      @hd.instance_variable_set(:@delegate_object, {})
+      @hd = HashDelegator.new
       menu_blocks = []
       @hd.append_divider(menu_blocks: menu_blocks, position: :initial)
 
@@ -5223,7 +5320,6 @@ module MarkdownExec
       @hd = HashDelegator.new
       @hd.stubs(:iter_blocks_from_nested_files).yields(:blocks, FCB.new)
       @hd.stubs(:create_and_add_chrome_blocks)
-      @hd.instance_variable_set(:@delegate_object, {})
       HashDelegator.stubs(:error_handler)
     end
 
@@ -5234,7 +5330,7 @@ module MarkdownExec
     end
 
     def test_blocks_from_nested_files_with_no_chrome
-      @hd.instance_variable_set(:@delegate_object, { no_chrome: true })
+      @hd = HashDelegator.new(no_chrome: true)
       @hd.expects(:create_and_add_chrome_blocks).never
 
       result = @hd.blocks_from_nested_files
@@ -5246,7 +5342,6 @@ module MarkdownExec
   class TestHashDelegatorCollectRequiredCodeLines < Minitest::Test
     def setup
       @hd = HashDelegator.new
-      @hd.instance_variable_set(:@delegate_object, {})
       @mdoc = mock('YourMDocClass')
       @selected = FCB.new(
         body: ['key: value'],
@@ -5272,15 +5367,13 @@ module MarkdownExec
   class TestHashDelegatorCommandOrUserSelectedBlock < Minitest::Test
     def setup
       @hd = HashDelegator.new
-      @hd.instance_variable_set(:@delegate_object, {})
       HashDelegator.stubs(:error_handler)
       @hd.stubs(:wait_for_user_selected_block)
     end
 
     def test_command_selected_block
       all_blocks = [{ oname: 'block1' }, { oname: 'block2' }]
-      @hd.instance_variable_set(:@delegate_object,
-                                { block_name: 'block1' })
+      @hd = HashDelegator.new(block_name: 'block1')
 
       result = @hd.load_cli_or_user_selected_block(all_blocks: all_blocks)
 
@@ -5309,10 +5402,10 @@ module MarkdownExec
 
   class TestHashDelegatorCountBlockInFilename < Minitest::Test
     def setup
-      @hd = HashDelegator.new
-      @hd.instance_variable_set(:@delegate_object,
-                                { fenced_start_and_end_regex: '^```',
-                                  filename: '/path/to/file' })
+      @hd = HashDelegator.new(
+        fenced_start_and_end_regex: '^```',
+        filename: '/path/to/file'
+      )
       @hd.stubs(:cfile).returns(mock('cfile'))
     end
 
@@ -5421,7 +5514,6 @@ module MarkdownExec
     def setup
       @hd = HashDelegator.new
       @hd.instance_variable_set(:@fout, mock('fout'))
-      @hd.instance_variable_set(:@delegate_object, {})
       @hd.stubs(:string_send_color)
     end
 
@@ -5443,7 +5535,6 @@ module MarkdownExec
   class TestHashDelegatorFetchColor < Minitest::Test
     def setup
       @hd = HashDelegator.new
-      @hd.instance_variable_set(:@delegate_object, {})
     end
 
     def test_fetch_color_with_valid_data
@@ -5476,7 +5567,6 @@ module MarkdownExec
   class TestHashDelegatorFormatReferencesSendColor < Minitest::Test
     def setup
       @hd = HashDelegator.new
-      @hd.instance_variable_set(:@delegate_object, {})
     end
 
     def test_format_references_send_color_with_valid_data
@@ -5581,7 +5671,6 @@ module MarkdownExec
     # )
 
     # def history_files(
-    #   link_state,
     #   direction: :reverse,
     #   filename: nil,
     #   home: Dir.pwd,
@@ -5590,9 +5679,10 @@ module MarkdownExec
     # )
 
     def test_call
-      @hd.expects(:history_files).with(nil, filename: '*', path: nil).once
-      @hd.execute_block_type_history_ux(filename: '*', link_state: LinkState.new,
-                                        selected: FCB.new(body: []))
+      @hd.expects(:history_files).with(filename: '*', path: nil).once
+      @hd.execute_block_type_history_ux(
+        filename: '*', link_state: LinkState.new, selected: FCB.new(body: [])
+      )
     end
   end
 
@@ -5677,11 +5767,9 @@ module MarkdownExec
 
   class TestHashDelegatorHandleStream < Minitest::Test
     def setup
-      @hd = HashDelegator.new
+      @hd = HashDelegator.new(output_stdout: true)
       @hd.instance_variable_set(:@run_state,
                                 OpenStruct.new(files: StreamsOut.new))
-      @hd.instance_variable_set(:@delegate_object,
-                                { output_stdout: true })
     end
 
     def test_handle_stream
@@ -5691,7 +5779,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
@@ -5713,9 +5801,7 @@ module MarkdownExec
 
   class TestHashDelegatorIterBlocksFromNestedFiles < Minitest::Test
     def setup
-      @hd = HashDelegator.new
-      @hd.instance_variable_set(:@delegate_object,
-                                { filename: 'test.md' })
+      @hd = HashDelegator.new(filename: 'test.md')
       @hd.stubs(:check_file_existence).with('test.md').returns(true)
       @hd.stubs(:initial_state).returns({})
       @hd.stubs(:cfile).returns(Minitest::Mock.new)
@@ -5744,12 +5830,11 @@ module MarkdownExec
 
   class TestHashDelegatorMenuChromeColoredOption < Minitest::Test
     def setup
-      @hd = HashDelegator.new
-      @hd.instance_variable_set(:@delegate_object, {
-                                  menu_option_back_name: 'Back',
-                                  menu_chrome_color: :red,
-                                  menu_chrome_format: '-- %s --'
-                                })
+      @hd = HashDelegator.new(
+        menu_chrome_color: :red,
+        menu_chrome_format: '-- %s --',
+        menu_option_back_name: 'Back'
+      )
       @hd.stubs(:menu_chrome_formatted_option)
          .with(:menu_option_back_name).returns('-- Back --')
       @hd.stubs(:string_send_color)
@@ -5763,8 +5848,9 @@ module MarkdownExec
     end
 
     def test_menu_chrome_colored_option_without_color
-      @hd.instance_variable_set(:@delegate_object,
-                                { menu_option_back_name: 'Back' })
+      @hd = HashDelegator.new(menu_option_back_name: 'Back')
+      @hd.stubs(:menu_chrome_formatted_option)
+         .with(:menu_option_back_name).returns('-- Back --')
       assert_equal '-- Back --',
                    @hd.menu_chrome_colored_option(:menu_option_back_name)
     end
@@ -5772,11 +5858,10 @@ module MarkdownExec
 
   class TestHashDelegatorMenuChromeOption < Minitest::Test
     def setup
-      @hd = HashDelegator.new
-      @hd.instance_variable_set(:@delegate_object, {
-                                  menu_option_back_name: "'Back'",
-                                  menu_chrome_format: '-- %s --'
-                                })
+      @hd = HashDelegator.new(
+        menu_chrome_format: '-- %s --',
+        menu_option_back_name: "'Back'"
+      )
       HashDelegator.stubs(:safeval).with("'Back'").returns('Back')
     end
 
@@ -5786,8 +5871,7 @@ module MarkdownExec
     end
 
     def test_menu_chrome_formatted_option_without_format
-      @hd.instance_variable_set(:@delegate_object,
-                                { menu_option_back_name: "'Back'" })
+      @hd = HashDelegator.new(menu_option_back_name: "'Back'")
       assert_equal 'Back',
                    @hd.menu_chrome_formatted_option(:menu_option_back_name)
     end
@@ -5795,10 +5879,12 @@ module MarkdownExec
 
   class TestHashDelegatorStartFencedBlock < Minitest::Test
     def setup
-      @hd = HashDelegator.new({
-                                block_name_wrapper_match: 'WRAPPER_REGEX',
-                                block_calls_scan: 'CALLS_REGEX'
-                              })
+      @hd = HashDelegator.new(
+        {
+          block_calls_scan: 'CALLS_REGEX',
+          block_name_wrapper_match: 'WRAPPER_REGEX'
+        }
+      )
     end
 
     def test_start_fenced_block
@@ -5816,9 +5902,7 @@ module MarkdownExec
 
   class TestHashDelegatorStringSendColor < Minitest::Test
     def setup
-      @hd = HashDelegator.new
-      @hd.instance_variable_set(:@delegate_object,
-                                { red: 'red', green: 'green' })
+      @hd = HashDelegator.new(red: 'red', green: 'green')
     end
 
     def test_string_send_color