markdown_exec 3.5.2 → 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

@@ -17,18 +17,21 @@ module MarkdownExec
     # @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.
+    # @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,
-      inherited_lines: nil, keep_code: false, prior_block_was_link: 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
@@ -51,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
@@ -140,11 +143,11 @@ if $PROGRAM_NAME == __FILE__
         @link_history = LinkHistory.new
         @link_state1 = LinkState.new(
           block_name: 'block1', document_filename: 'document1.txt',
-          inherited_lines: ['code1.rb']
+          context_code: ['code1.rb']
         )
         @link_state2 = LinkState.new(
           block_name: 'block2', document_filename: 'document2.txt',
-          inherited_lines: ['code2.rb']
+          context_code: ['code2.rb']
         )
       end
 
@@ -167,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
@@ -180,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.2'
+  VERSION = '3.6.0'
 end

data/lib/mdoc.rb

@@ -68,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
 
-    # Generates a shell command to redirect a block's body to either a shell variable or a file.
+    # 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.
@@ -165,12 +183,12 @@ 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,
-      inherited_lines: [] ###s
+      context_code: []
     )
       raise 'unexpected label_body' unless label_body
 
@@ -179,22 +197,28 @@ module MarkdownExec
         blocks = collect_wrapped_blocks(block_search[:blocks])
         # !!t blocks.count
 
-        code_inherit = blocks.map do |fcb|
+        context_transient_codes = blocks.map do |fcb|
           process_block_to_code(
             fcb, block_source,
             label_body, label_format_above, label_format_below,
-            inherited_lines: inherited_lines
+            context_code: context_code
           )
-        end
+        end.tap { ww anyname, _1 }
 
         block_search.merge(
-          { block_names: blocks.map(&:pub_name),
-            code: code_inherit.map(&:first).compact.flatten(1).compact,
-            inherit: code_inherit.map(&:last).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: [], inherit: [] })
-      end
+        block_search.merge(
+          { block_names: [], context_code: [], transient_code: [] }
+        )
+      end.tap { wwr _1 }
     rescue StandardError
       error_handler('collect_recursively_required_code')
     end
@@ -286,9 +310,7 @@ 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? &&
@@ -415,61 +437,67 @@ module MarkdownExec
     # @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, inherited_lines: [])
+                              label_format_below, context_code: [])
       raise 'unexpected label_body' unless label_body
 
-      new_inherited_lines = []
-
-      new_code_lines = if fcb[:cann]
-                         collect_block_code_cann(fcb)
-                       elsif fcb[:stdout]
-                         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/ ###s
-                           command_result = HashDelegator.execute_bash_script_lines(
-                             code_lines: inherited_lines + fcb.body,
-                             export: OpenStruct.new(exportable: true, name: ''),
-                             force: true,
-                             shell: fcb.shell || 'bash'
-                           )
-                           command_result.new_lines.map { _1[:text] }.tap do
-                             if fcb.start_line =~ /@inherit/ ###s
-                               new_inherited_lines = _1
+      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
 
-                         elsif fcb.start_line =~ /@inherit/ ###s
-                           # raw body
-                           ### expansions?
-                           new_inherited_lines = fcb.body
-                           nil # 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
-
-      [new_code_lines, new_inherited_lines].tap { wwr _1 }
+      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.

data/lib/menu.src.yml

@@ -308,9 +308,9 @@
   :default: false
   :procname: val_as_bool
 
-- :opt_name: dump_inherited_lines
-  :long_name: dump-inherited-lines
-  :env_var: MDE_DUMP_INHERITED_LINES
+- :opt_name: dump_context_code
+  :long_name: dump-context-code
+  :env_var: MDE_DUMP_CONTEXT_CODE
   :description: Display inherited code lines from imported documents (debug/diagnostic output)
   :arg_name: BOOL
   :default: false
@@ -1206,8 +1206,8 @@
   :default: true
   :procname: val_as_bool
 
-- :opt_name: menu_with_inherited_lines
-  :env_var: MDE_MENU_WITH_INHERITED_LINES
+- :opt_name: menu_with_context_code
+  :env_var: MDE_MENU_WITH_CONTEXT_CODE
   :description: Display inherited lines in menu
   :arg_name: BOOL
   :default: false

data/lib/menu.yml

@@ -272,9 +272,9 @@
   :arg_name: BOOL
   :default: false
   :procname: val_as_bool
-- :opt_name: dump_inherited_lines
-  :long_name: dump-inherited-lines
-  :env_var: MDE_DUMP_INHERITED_LINES
+- :opt_name: dump_context_code
+  :long_name: dump-context-code
+  :env_var: MDE_DUMP_CONTEXT_CODE
   :description: Display inherited code lines from imported documents (debug/diagnostic
     output)
   :arg_name: BOOL
@@ -1046,8 +1046,8 @@
   :arg_name: BOOL
   :default: true
   :procname: val_as_bool
-- :opt_name: menu_with_inherited_lines
-  :env_var: MDE_MENU_WITH_INHERITED_LINES
+- :opt_name: menu_with_context_code
+  :env_var: MDE_MENU_WITH_CONTEXT_CODE
   :description: Display inherited lines in menu
   :arg_name: BOOL
   :default: false

data/lib/ww.rb

@@ -245,7 +245,7 @@ class Array
     # exclude vendor and .bundle directories
     # limit the count to 4
     # replace the home directory with a .
-    def deref(count = 4)
+    def deref(count = 6)
       dir_pwd = Dir.pwd
       map(&:deref).reject do |line|
         %r{^/(vendor|\.bundle)/}.match(line)

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: markdown_exec
 version: !ruby/object:Gem::Version
-  version: 3.5.2
+  version: 3.6.0
 platform: ruby
 authors:
 - Fareed Stevenson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-03 00:00:00.000000000 Z
+date: 2025-12-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: clipboard
@@ -118,6 +118,7 @@ files:
 - bats/block-type-link.bats
 - bats/block-type-opts.bats
 - bats/block-type-port.bats
+- bats/block-type-shell-context-eval.bats
 - bats/block-type-shell-require-ux.bats
 - bats/block-type-ux-act-init.bats
 - bats/block-type-ux-allowed.bats
@@ -195,6 +196,7 @@ files:
 - docs/dev/block-type-bash.md
 - docs/dev/block-type-opts.md
 - docs/dev/block-type-port.md
+- docs/dev/block-type-shell-context-eval.md
 - docs/dev/block-type-shell-require-ux.md
 - docs/dev/block-type-ux-act-init.md
 - docs/dev/block-type-ux-allowed.md
@@ -285,6 +287,7 @@ files:
 - docs/execution-control.md
 - docs/getting-started.md
 - docs/import-options.md
+- docs/shell-script-evaluation.md
 - docs/tab-completion.md
 - docs/ux-blocks.md
 - examples/bash-blocks.md