markdown_exec 3.5.1 → 3.6.0

data/lib/input_sequencer.rb

@@ -35,7 +35,7 @@ class InputSequencer
       document_filename: next_state.document_filename || current.document_filename,
       inherited_block_names: next_state.inherited_block_names,
       inherited_dependencies: next_state.inherited_dependencies,
-      inherited_lines: next_state.inherited_lines,
+      context_code: next_state.context_code,
       prior_block_was_link: next_state.prior_block_was_link.nil? ? current.prior_block_was_link : next_state.prior_block_was_link
     )
   # rubocop:disable Style/RescueStandardError
@@ -49,13 +49,13 @@ class InputSequencer
 
   def self.next_link_state(
     block_name: nil, display_menu: nil, document_filename: nil,
-    inherited_lines: nil, keep_code: false, prior_block_was_link: false
+    context_code: nil, keep_code: false, prior_block_was_link: false
   )
     MarkdownExec::LinkState.new(
       block_name: block_name,
       display_menu: display_menu,
       document_filename: document_filename,
-      inherited_lines: inherited_lines,
+      context_code: context_code,
       keep_code: keep_code,
       prior_block_was_link: prior_block_was_link
     )
@@ -96,6 +96,7 @@ class InputSequencer
       if now_menu.display_menu
         # !!b
         break if run_yield(:end_of_cli, &block) == :exit
+
         # !!b
 
         exit_when_bq_empty = false

data/lib/link_history.rb

@@ -14,24 +14,32 @@ module MarkdownExec
     # Initialize the LinkState with keyword arguments for each attribute.
     # @param block_name [String, nil] the name of the block.
     # @param document_filename [String, nil] the filename of the document.
-    # @param inherited_block_names [Array<String>, nil] the names of the inherited blocks.
+    # @param inherited_block_names [Array<String>, nil] the names of
+    # the inherited blocks.
     # @param inherited_dependencies [?, nil] the dependecy hierarcy.
-    # @param inherited_lines [Array<String>, nil] the inherited lines of code.
-    def initialize(block_name: nil, display_menu: nil, document_filename: nil,
-                   inherited_block_names: [], inherited_dependencies: nil, inherited_lines: nil,
-                   keep_code: false, prior_block_was_link: nil)
+    # @param context_code [Array<String>, nil] the context code (shell code that provides
+    #   the necessary code and data for the evaluation of individual blocks).
+    # @param context_code [Array<String>, nil] Deprecated: Use context_code instead.
+    def initialize(
+      block_name: nil, display_menu: nil, document_filename: nil,
+      inherited_block_names: [], inherited_dependencies: nil,
+      context_code: nil, keep_code: false, prior_block_was_link: nil
+    )
       @block_name = block_name
       @display_menu = display_menu
       @document_filename = document_filename
       @inherited_block_names = inherited_block_names
       @inherited_dependencies = inherited_dependencies
-      @inherited_lines = inherited_lines
+      # Support both new and deprecated parameter names
+      @context_code = context_code
       @keep_code = keep_code
       @prior_block_was_link = prior_block_was_link
+      wwt :link_state, self, caller.deref
     end
 
     # Creates an empty LinkState instance.
-    # @return [LinkState] an instance with all attributes set to their default values.
+    # @return [LinkState] an instance with all attributes
+    # set to their default values.
     def self.empty
       new
     end
@@ -46,50 +54,50 @@ module MarkdownExec
         other.document_filename == document_filename &&
         other.inherited_block_names == inherited_block_names &&
         other.inherited_dependencies == inherited_dependencies &&
-        other.inherited_lines == inherited_lines &&
+        other.context_code == context_code &&
         other.keep_code == keep_code &&
         other.prior_block_was_link == prior_block_was_link
     end
 
-    def inherited_lines
-      @inherited_lines.tap do |ret|
-        pp ['LinkState.inherited_lines() ->', ret] if $pd
+    def context_code
+      @context_code.tap do |ret|
+        pp ['LinkState.context_code() ->', ret] if $pd
       end
     end
 
-    def inherited_lines=(value)
-      @inherited_lines = value.tap do |ret|
-        pp ['LinkState.inherited_lines=() ->', ret, caller.deref(3).last] if $pd
+    def context_code=(value)
+      @context_code = value.tap do |ret|
+        pp ['LinkState.context_code=() ->', ret, caller.deref(3).last] if $pd
       end
     end
 
-    def inherited_lines_append(value)
-      @inherited_lines = ((@inherited_lines || []) + value).tap do |ret|
-        pp ['LinkState.inherited_lines_append() ->', ret] if $pd
+    def context_code_append(value)
+      @context_code = ((@context_code || []) + value).tap do |ret|
+        pp ['LinkState.context_code_append() ->', ret] if $pd
       end
     end
 
-    def inherited_lines_block
-      (@inherited_lines || []).join("\n").tap do |ret|
-        pp ['LinkState.inherited_lines_block() ->', ret] if $pd
+    def context_code_block
+      (@context_code || []).join("\n").tap do |ret|
+        pp ['LinkState.context_code_block() ->', ret] if $pd
       end
     end
 
-    def inherited_lines_count
-      (@inherited_lines&.count || 0).tap do |ret|
-        pp ['LinkState.inherited_lines_count() ->', ret] if $pd
+    def context_code_count
+      (@context_code&.count || 0).tap do |ret|
+        pp ['LinkState.context_code_count() ->', ret] if $pd
       end
     end
 
-    def inherited_lines_map(&block)
-      @inherited_lines.map(&block).tap do |ret|
-        pp ['LinkState.inherited_lines_map() ->', ret] if $pd
+    def context_code_map(&block)
+      @context_code.map(&block).tap do |ret|
+        pp ['LinkState.context_code_map() ->', ret] if $pd
       end
     end
 
-    def inherited_lines_present?
-      @inherited_lines.present?.tap do |ret|
-        pp ['LinkState.inherited_lines_present?() ->', ret] if $pd
+    def context_code_present?
+      @context_code.present?.tap do |ret|
+        pp ['LinkState.context_code_present?() ->', ret] if $pd
       end
     end
   end
@@ -99,12 +107,14 @@ module MarkdownExec
       @history = []
     end
 
-    # Peeks at the most recent LinkState, returns an empty LinkState if stack is empty.
+    # Peeks at the most recent LinkState, returns an empty LinkState
+    # if stack is empty.
     def peek
       @history.last || LinkState.empty
     end
 
-    # Pops the most recent LinkState off the stack, returns an empty LinkState if stack is empty.
+    # Pops the most recent LinkState off the stack, returns an empty LinkState
+    # if stack is empty.
     def pop
       @history.pop || LinkState.empty
     end
@@ -131,10 +141,14 @@ if $PROGRAM_NAME == __FILE__
     class TestLinkHistory < Minitest::Test
       def setup
         @link_history = LinkHistory.new
-        @link_state1 = LinkState.new(block_name: 'block1', document_filename: 'document1.txt',
-                                     inherited_lines: ['code1.rb'])
-        @link_state2 = LinkState.new(block_name: 'block2', document_filename: 'document2.txt',
-                                     inherited_lines: ['code2.rb'])
+        @link_state1 = LinkState.new(
+          block_name: 'block1', document_filename: 'document1.txt',
+          context_code: ['code1.rb']
+        )
+        @link_state2 = LinkState.new(
+          block_name: 'block2', document_filename: 'document2.txt',
+          context_code: ['code2.rb']
+        )
       end
 
       def test_push
@@ -156,6 +170,51 @@ if $PROGRAM_NAME == __FILE__
       def test_pop_empty
         assert_equal LinkState.empty, @link_history.pop
       end
+
+      def test_context_code_accessor
+        state = LinkState.new(context_code: %w[line1 line2])
+        assert_equal %w[line1 line2], state.context_code
+      end
+
+      def test_context_code_block
+        state = LinkState.new(context_code: %w[line1 line2])
+        assert_equal "line1\nline2", state.context_code_block
+      end
+
+      def test_context_code_append
+        state = LinkState.new(context_code: ['line1'])
+        state.context_code_append(['line2'])
+        assert_equal %w[line1 line2], state.context_code
+      end
+
+      def test_context_code_count
+        state = LinkState.new(context_code: %w[line1 line2 line3])
+        assert_equal 3, state.context_code_count
+      end
+
+      def test_context_code_present?
+        state_with_code = LinkState.new(context_code: ['line1'])
+        state_without_code = LinkState.new(context_code: nil)
+        assert state_with_code.context_code_present?
+        refute state_without_code.context_code_present?
+      end
+
+      def test_context_code_equality
+        state1 = LinkState.new(context_code: ['line1'])
+        state2 = LinkState.new(context_code: ['line1'])
+        state3 = LinkState.new(context_code: ['line2'])
+        assert_equal state1, state2
+        refute_equal state1, state3
+      end
+
+      def test_deprecated_context_code_methods
+        state = LinkState.new(context_code: %w[line1 line2])
+        # Test backward compatibility
+        assert_equal %w[line1 line2], state.context_code
+        assert_equal "line1\nline2", state.context_code_block
+        assert_equal 2, state.context_code_count
+        assert state.context_code_present?
+      end
     end
   end
 end
@@ -169,7 +228,7 @@ To generate the Ruby classes `LinkState` and `LinkHistory` with their current fe
 Create Ruby classes `LinkState` and `LinkHistory` with the following specifications:
 
 1. **Class `LinkState`**:
-    - Attributes: `block_name`, `document_filename`, `inherited_lines`.
+    - Attributes: `block_name`, `document_filename`, `context_code`.
     - Initialize with optional parameters for each attribute, defaulting to `nil`.
     - Include a class method `empty` that creates an instance with all attributes set to `nil`.
     - Implement a custom `==` method for comparing instances based on attribute values.

data/lib/markdown_exec/version.rb

@@ -8,5 +8,5 @@ module MarkdownExec
   BIN_NAME = 'mde'
   GEM_NAME = 'markdown_exec'
   TAP_DEBUG = 'MDE_DEBUG'
-  VERSION = '3.5.1'
+  VERSION = '3.6.0'
 end

data/lib/mdoc.rb

@@ -5,6 +5,7 @@
 
 require_relative 'block_types'
 require_relative 'collapser'
+require_relative 'command_result'
 require_relative 'filter'
 
 $pd = false unless defined?($pd)
@@ -12,7 +13,7 @@ $pd = false unless defined?($pd)
 module MarkdownExec
   class MenuFilter
     def initialize(opts)
-      @opts = opts.merge(block_name_hidden_match: nil)
+      @opts = opts.merge(block_name_hide_custom_match: nil)
     end
 
     def fcb_in_menu?(fcb)
@@ -38,10 +39,10 @@ module MarkdownExec
         false
       else
         @opts[:hide_blocks_by_name] &&
-          ((@opts[:block_name_hidden_match]&.present? &&
+          ((@opts[:block_name_hide_custom_match]&.present? &&
+            block.s2title&.match(Regexp.new(@opts[:block_name_hide_custom_match]))) ||
+           (@opts[:block_name_hidden_match]&.present? &&
             block.s2title&.match(Regexp.new(@opts[:block_name_hidden_match]))) ||
-           (@opts[:block_name_include_match]&.present? &&
-            block.s2title&.match(Regexp.new(@opts[:block_name_include_match]))) ||
            (@opts[:block_name_wrapper_match]&.present? &&
             block.s2title&.match(Regexp.new(@opts[:block_name_wrapper_match])))) &&
           (block.s2title&.present? || block[:label]&.present?)
@@ -67,25 +68,43 @@ module MarkdownExec
       @table = table
     end
 
-    def collect_block_code_cann(fcb)
+    # Generates a yq (YAML query) shell command from a call annotation.
+    # The call annotation specifies I/O redirection patterns:
+    # - <$VAR_NAME: read YAML from environment variable, apply expression from block body
+    # - <FILE_NAME: read YAML from file, apply expression from block body
+    # - >$VAR_NAME: write result to environment variable
+    # - >FILE_NAME: write result to file
+    #
+    # @param fcb [FCB] The fenced code block containing the call annotation and body
+    # @return [String] A shell command string that executes the yq query
+    def generate_yq_command_from_call_annotation(fcb)
       body = fcb.body.join("\n")
       xcall = fcb[:cann][1..-2]
+      # match <$VAR_NAME, <FILE_NAME, >$VAR_NAME, >FILE_NAME
       mstdin = xcall.match(/<(?<type>\$)?(?<name>[\-.\w]+)/)
       mstdout = xcall.match(/>(?<type>\$)?(?<name>[\-.\w]+)/)
 
       yqcmd = if mstdin[:type]
+                # when <$VAR_NAME
+                # the value of the variable is the expression to apply to the YAML from the block body.
                 "echo \"$#{mstdin[:name]}\" | yq '#{body}'"
               else
+                # when <FILE_NAME
+                # the block body is the expression to apply to the YAML file.
                 "yq e '#{body}' '#{mstdin[:name]}'"
               end
       if mstdout[:type]
+        # when >$VAR_NAME
+        # set the value of the variable to the result of the expression
         "export #{mstdout[:name]}=$(#{yqcmd})"
       else
+        # when >FILE_NAME
+        # write the result of the expression to the file
         "#{yqcmd} > '#{mstdout[:name]}'"
       end
     end
 
-    # Collects and formats the shell command output to redirect script block code to a file or a variable.
+    # Generates a shell command to copy the block's body to either a shell variable or a file.
     #
     # @param [Hash] fcb A hash containing information about the script block's stdout and body.
     #   @option fcb [Hash] :stdout A hash specifying the stdout details.
@@ -93,10 +112,10 @@ module MarkdownExec
     #     @option stdout [String] :name The name of the variable or file to which the body will be output.
     #   @option fcb [Array<String>] :body An array of strings representing the lines of the script block's body.
     #
-    # @return [String] A string containing the formatted shell command to output the script block's body.
+    # @return [String] A string containing the shell command to redirect the script block's body.
     #   If stdout[:type] is true, the command will export the body to a shell variable.
     #   If stdout[:type] is false, the command will write the body to a file.
-    def collect_block_code_stdout(fcb)
+    def code_for_fcb_body_into_var_or_file(fcb)
       stdout = fcb[:stdout]
       body = fcb.body.join("\n")
       if stdout[:type]
@@ -164,49 +183,42 @@ module MarkdownExec
     # Collects recursively required code blocks and returns them as an array of strings.
     #
     # @param name [String] The name of the code block to start the collection from.
-    # @return [Array<String>] An array of strings containing the collected code blocks.
+    # @return [OpenStruct]
     #
     def collect_recursively_required_code(
       anyname:, block_source:,
-      label_body: true, label_format_above: nil, label_format_below: nil
+      label_body: true, label_format_above: nil, label_format_below: nil,
+      context_code: []
     )
+      raise 'unexpected label_body' unless label_body
+
       block_search = collect_block_dependencies(anyname: anyname)
       if block_search[:blocks]
         blocks = collect_wrapped_blocks(block_search[:blocks])
         # !!t blocks.count
 
+        context_transient_codes = blocks.map do |fcb|
+          process_block_to_code(
+            fcb, block_source,
+            label_body, label_format_above, label_format_below,
+            context_code: context_code
+          )
+        end.tap { ww anyname, _1 }
+
         block_search.merge(
-          { block_names: blocks.map(&:pub_name),
-            code: blocks.map do |fcb|
-              if fcb[:cann]
-                collect_block_code_cann(fcb)
-              elsif fcb[:stdout]
-                collect_block_code_stdout(fcb)
-              elsif [BlockType::OPTS].include? fcb.type
-                fcb.body # entire body is returned to requesing block
-
-              elsif [BlockType::LINK,
-                     BlockType::LOAD,
-                     BlockType::UX,
-                     BlockType::VARS].include? fcb.type
-                nil # Vars for all types are collected later
-              elsif fcb[:chrome] # for Link blocks like History
-                nil
-              elsif fcb.type == BlockType::PORT
-                generate_env_variable_shell_commands(fcb)
-              elsif label_body
-                generate_label_body_code(
-                  fcb, block_source,
-                  label_format_above, label_format_below
-                )
-              else # raw body
-                fcb.body
-              end
-            end.compact.flatten(1).compact }
+          {
+            block_names: blocks.map(&:pub_name),
+            context_code:
+              context_transient_codes.map(&:context_code).compact.flatten(1).compact,
+            transient_code:
+              context_transient_codes.map(&:transient_code).compact.flatten(1).compact
+          }
         )
       else
-        block_search.merge({ block_names: [], code: [] })
-      end
+        block_search.merge(
+          { block_names: [], context_code: [], transient_code: [] }
+        )
+      end.tap { wwr _1 }
     rescue StandardError
       error_handler('collect_recursively_required_code')
     end
@@ -237,6 +249,8 @@ module MarkdownExec
             table_not_split.select { |fcb| fcb.code_name_included?(wrap_after) }
           end.flatten(1)
       end.flatten(1).compact
+    rescue StandardError
+      wwe $!
     end
 
     def error_handler(name = '', opts = {})
@@ -252,7 +266,7 @@ module MarkdownExec
     # @return [Array<Hash>] An array of code blocks that match the options.
     #
     def fcbs_per_options(opts = {})
-      options = opts.merge(block_name_hidden_match: nil)
+      options = opts.merge(block_name_hide_custom_match: nil)
       selrows = @table.select do |fcb_title_groups|
         Filter.fcb_select? options, fcb_title_groups
       end
@@ -296,15 +310,15 @@ module MarkdownExec
       # remove
       # . empty chrome between code; edges are same as blanks
       #
-      select_elements_with_neighbor_conditions(selrows) do |prev_element,
-                                                            current,
-                                                            next_element|
+      select_elements_with_neighbor_conditions(selrows) do |prev_element, current, next_element|
         !(current[:chrome] && !current.oname.present?) ||
           !(!prev_element.nil? &&
             prev_element.shell.present? &&
             !next_element.nil? &&
             next_element.shell.present?)
       end
+    rescue StandardError
+      wwe $!
     end
 
     # Generates shell code lines to set environment variables named in the body of the given object.
@@ -328,7 +342,7 @@ module MarkdownExec
       end
     end
 
-    # Generates a formatted code block with labels above and below the main content.
+    # Wraps a code block body with formatted labels above and below the main content.
     # The labels and content are based on the provided format strings and the body of the given object.
     #
     # @param fcb [Object] An object with a `pub_name` method that returns a string, and a `body` method that returns an array of strings.
@@ -343,8 +357,8 @@ module MarkdownExec
     #   and `label_format_below` is "End of %{block_name}", the method will return:
     #     ["Start of Example_Block", "line1", "line2", "End of Example_Block"]
     #
-    def generate_label_body_code(fcb, block_source, label_format_above,
-                                 label_format_below)
+    def wrap_block_body_with_labels(fcb, block_source, label_format_above,
+                                    label_format_below)
       block_name_for_bash_comment = fcb.pub_name.gsub(/\s+/, '_')
 
       label_above = if label_format_above.present?
@@ -403,16 +417,89 @@ module MarkdownExec
         false
       else
         opts[:hide_blocks_by_name] &&
-          ((opts[:block_name_hidden_match]&.present? &&
+          ((opts[:block_name_hide_custom_match]&.present? &&
+            block.s2title&.match(Regexp.new(opts[:block_name_hide_custom_match]))) ||
+           (opts[:block_name_hidden_match]&.present? &&
             block.s2title&.match(Regexp.new(opts[:block_name_hidden_match]))) ||
-           (opts[:block_name_include_match]&.present? &&
-            block.s2title&.match(Regexp.new(opts[:block_name_include_match]))) ||
            (opts[:block_name_wrapper_match]&.present? &&
             block.s2title&.match(Regexp.new(opts[:block_name_wrapper_match])))) &&
           (block.s2title&.present? || block[:label]&.present?)
       end
     end
 
+    # Processes a single code block and returns its code representation.
+    #
+    # @param fcb [Hash] The code block to process.
+    # @param block_source [Hash] Additional information for label generation.
+    # @param label_body [Boolean] Whether to generate labels around the body.
+    # @param label_format_above [String, nil] Format string for label above content.
+    # @param label_format_below [String, nil] Format string for label below content.
+    # @return [String, Array, nil] The code representation of the block, or nil if the block should be skipped.
+    #
+    def process_block_to_code(fcb, block_source, label_body, label_format_above,
+                              label_format_below, context_code: [])
+      raise 'unexpected label_body' unless label_body
+
+      new_context_code = []
+
+      new_transient_code = if fcb[:cann]
+                             generate_yq_command_from_call_annotation(fcb)
+                           elsif fcb[:stdout]
+                             # copy the block's body to either a shell variable or a file
+                             code_for_fcb_body_into_var_or_file(fcb)
+                           elsif [BlockType::OPTS].include? fcb.type
+                             fcb.body # entire body is returned to requesing block
+
+                           elsif [BlockType::LINK,
+                                  BlockType::LOAD,
+                                  BlockType::UX,
+                                  BlockType::VARS].include? fcb.type
+                             nil # Vars for all types are collected later
+                           elsif fcb[:chrome] # for Link blocks like History
+                             nil
+                           elsif fcb.type == BlockType::PORT
+                             generate_env_variable_shell_commands(fcb)
+                           elsif label_body
+                             raise 'unexpected type' if fcb.type != BlockType::SHELL
+
+                             # BlockType::  SHELL block
+                             if fcb.start_line =~ /@eval/
+                               command_result = HashDelegator.execute_bash_script_lines(
+                                 transient_code: context_code + fcb.body,
+                                 export: OpenStruct.new(exportable: false, name: ''),
+                                 export_name: '',
+                                 force: true,
+                                 shell: fcb.shell || 'bash'
+                               )
+                               command_result.stdout.split("\n").tap do
+                                 if fcb.start_line =~ /@context/
+                                   new_context_code = _1
+                                 end
+                               end
+                             elsif fcb.start_line =~ /@context/
+                               # raw body
+                               ### expansions?
+                               new_context_code = fcb.body
+                               [] # collect later or return as code to inherit
+
+                             else
+                               wrap_block_body_with_labels(
+                                 fcb, block_source,
+                                 label_format_above, label_format_below
+                               )
+                             end
+                           else # raw body
+                             fcb.body
+                           end
+
+      OpenStruct.new(
+        context_code: new_context_code,
+        transient_code: new_transient_code
+      ).tap { wwr _1 }
+    rescue StandardError
+      wwe $!
+    end
+
     # Recursively fetches required code blocks for a given list of requirements.
     #
     # @param reqs [Array<String>] An array of requirements to start the recursion from.
@@ -620,7 +707,7 @@ if $PROGRAM_NAME == __FILE__
 
       def test_hide_menu_block_on_name
         opts = { hide_blocks_by_name: true,
-                 block_name_hidden_match: 'block1' }
+                 block_name_hide_custom_match: 'block1' }
         block = FCB.new(s2title: 'block1')
         result = @doc.hide_menu_block_on_name(opts, block)
         assert result # this should be true based on the given logic
@@ -628,7 +715,7 @@ if $PROGRAM_NAME == __FILE__
 
       def test_fcbs_per_options
         opts = { hide_blocks_by_name: true,
-                 block_name_hidden_match: 'block1' }
+                 block_name_hide_custom_match: 'block1' }
         result = @doc.fcbs_per_options(opts)
         assert_equal [@table[1], @table[2]], result
       end if false ### broken test