markdown_exec 3.5.2 → 3.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 70772e4552a37222c8f9655c19d0c4938ef57a2abc786987d4b8220608aeb3b5
-  data.tar.gz: 7afe1c005a8d079e0d55ba36ccfd83e669665d038182c2d465e027ba5e7f46f7
+  metadata.gz: 51d3a7c5749462279a14861d0f17ddb2074e9154a5daa2ba688418a524eb83ed
+  data.tar.gz: 387d31d100c9e38a955c78974a7c2679024559a36b1c540289f50a42fa6b8405
 SHA512:
-  metadata.gz: b5ce74d1d56a732a6877d6dca7fd188e33b87fdbeccc6f3762281edfef9d53c525bcefb293931ec1cefa0e9176e45ef83d9a0c285589051169c15c8f2305a07d
-  data.tar.gz: 3798f4dfb87aeabb8e450bbb8790a72903a181f1171028042725f6231b90cc59605a88445c59a9e5178789a6b7d456060407ace48639f8b11b2b1ec385b8c23b
+  metadata.gz: 2f7521c909160d4f063875248e7d69264cb59916c659f47d1526acdc6ba8e142cffe46b5e0fd5f66c37f738d625f4e58ae3f6dd3443d1470452402e0508307bb
+  data.tar.gz: c0441396ed9b97bf4ac212451de554ec611e54d6ed15d2375812145d93f3fe7baddc42de936397eaf758f934c9a46f1fd5f90c21dd042ad625bb623a50261256

data/CHANGELOG.md

@@ -1,6 +1,13 @@
 # Changelog
 
-## [3.5.2]
+## [3.6.0] - 2025-12-08
+
+### Added
+
+- Directive to append shell block to the context code.
+- Directive to evaluate shell block prior to appending to context or transient code.
+
+## [3.5.2] - 2025-12-02
 
 ### Added
 

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    markdown_exec (3.5.2)
+    markdown_exec (3.6.0)
       clipboard (~> 1.3.6)
       open3 (~> 0.1.1)
       optparse (~> 0.1.1)

data/README.md

@@ -258,7 +258,7 @@ export MDE_USER_MUST_APPROVE=1
 # .mde.yml
 save_executed_script: true
 user_must_approve: true
-menu_with_inherited_lines: true
+menu_with_context_code: true
 ```
 </code></pre>
 

data/bats/block-type-shell-context-eval.bats

@@ -0,0 +1,48 @@
+#!/usr/bin/env bats
+
+load 'test_helper'
+
+@test 'context block appends shell code to context without executing it' {
+  BATS_OUTPUT_FILTER=A
+  BATS_SAFE=_
+  spec_mde_args_expect docs/dev/block-type-shell-context-eval.md \
+   '[context]' '[opts]' \
+  __Exit \
+  'VARS1 = 0.0__~ SHELL_V1=0.0, 1.1_~ SHELL_V2=0.0, 1.2__  context_code_  - : VARS1="0.0"_  - : SHELL_V1="${VARS1}, 1.1"_  - : SHELL_V2="${VARS1}, 1.2"'
+}
+
+@test 'eval block executes shell code and output becomes transient code' {
+  BATS_OUTPUT_FILTER=A
+  BATS_SAFE=_
+  spec_mde_args_expect docs/dev/block-type-shell-context-eval.md \
+   '[eval]' '[opts]' \
+  __Exit \
+  'VARS1 = 0.0__~ SHELL_V1=0.0, 2.1_~ SHELL_V2=0.0, 2.2__  context_code_  - : VARS1="0.0"'
+}
+
+@test 'eval-context block executes shell code and appends output to context' {
+  BATS_OUTPUT_FILTER=A
+  BATS_SAFE=_
+  spec_mde_args_expect docs/dev/block-type-shell-context-eval.md \
+   '[eval-context]' '[opts]' \
+  __Exit \
+  'VARS1 = 0.0__~ SHELL_V1=0.0, 3.1_~ SHELL_V2=0.0, 3.2__  context_code_  - : VARS1="0.0"_  - : SHELL_V1="0.0, 3.1"_  - : SHELL_V2="0.0, 3.2"'
+}
+
+@test 'require-context block requires context block and can access its variables' {
+  BATS_OUTPUT_FILTER=A
+  BATS_SAFE=_
+  spec_mde_args_expect docs/dev/block-type-shell-context-eval.md \
+   '[require-context]' '[opts]' \
+  __Exit \
+  'VARS1 = 0.0__~ SHELL_V1=0.0, 1.1, 4.1_~ SHELL_V2=0.0, 1.2, 4.2__  context_code_  - : VARS1="0.0"_  - : SHELL_V1="${VARS1}, 1.1"_  - : SHELL_V2="${VARS1}, 1.2"'
+}
+
+@test 'require-eval-context block requires eval-context block and can access its variables' {
+  BATS_OUTPUT_FILTER=A
+  BATS_SAFE=_
+  spec_mde_args_expect docs/dev/block-type-shell-context-eval.md \
+   '[require-eval-context]' '[opts]' \
+  __Exit \
+  'VARS1 = 0.0__~ SHELL_V1=0.0, 3.1, 5.1_~ SHELL_V2=0.0, 3.2, 5.2__  context_code_  - : VARS1="0.0"_  - : SHELL_V1="0.0, 3.1"_  - : SHELL_V2="0.0, 3.2"'
+}

data/bats/block-type-ux-echo.bats

@@ -9,7 +9,7 @@ load 'test_helper'
 
 @test 'displays inherited lines in menu' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-echo.md \
-   '(menu_with_inherited_lines)' \
+   '(menu_with_context_code)' \
    '[[ -z $VAR ]] && VAR=markdown_exec_VAR=markdown_exec_IAB='
 }
 

data/bats/block-type-ux-force.bats

@@ -5,5 +5,5 @@ load 'test_helper'
 # UX before VARS although VARS appears first
 @test 'forces UX block before VARS block' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-force.md \
-  'Common_Name = Tapanuli Orangutan_  inherited_lines_  - : Common_Name="Tapanuli Orangutan"_  - : Common_Name=Ruby\ Seadragon_Common_Name=Ruby Seadragon_| Common_Name | Ruby Seadragon |'
+  'Common_Name = Tapanuli Orangutan_  context_code_  - : Common_Name="Tapanuli Orangutan"_  - : Common_Name=Ruby\ Seadragon_Common_Name=Ruby Seadragon_| Common_Name | Ruby Seadragon |'
 }

data/bats/block-type-ux-invalid.bats

@@ -4,5 +4,5 @@ load 'test_helper'
 
 @test 'reports error when automatic block has invalid YAML' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-invalid.md \
-   '_Error: HashDelegator.ItrBlkFrmNstFls:1¤./docs/dev/block-type-ux-invalid.md:1 - --- !ruby/object:NullResult_message: Invalid YAML_data: invalid_ --  -- '
+   '_Error: HashDelegator.IBNF:1¤./docs/dev/block-type-ux-invalid.md:1 - --- !ruby/object:NullResult_message: Invalid YAML_data: invalid_ --  -- '
 }

data/bats/block-type-ux-require.bats

@@ -9,6 +9,6 @@ load 'test_helper'
 
 @test 'displays inherited lines in menu' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-require.md \
-   '(menu_with_inherited_lines)' \
+   '(menu_with_context_code)' \
    'SPECIES=Pongo\ tapanuliensis_GENUS=Pongo_NAME=Pongo\ tapanuliensis\ -\ Pongo_NAME2=Pongo\ tapanuliensis\ -\ Pongo_SPECIES=Pongo tapanuliensis_GENUS=Pongo_NAME=Pongo tapanuliensis - Pongo_NAME2=Pongo tapanuliensis - Pongo'
 }

data/bats/document-shell.bats

@@ -4,6 +4,6 @@ load 'test_helper'
 
 @test 'requires document_shell for inherited lines' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/document-shell.md \
-   --dump-inherited-lines t '* Exit' \
-   '  inherited_lines_  - : : from required_  - : : from document_shell'
+   --dump-context-code t '* Exit' \
+   '  context_code_  - : : from required_  - : : from document_shell'
 }

data/bats/import.bats

@@ -20,5 +20,5 @@ load 'test_helper'
   BATS_SAFE=_
   spec_mde_args_expect docs/dev/import.md \
    --list-block-message id --list-blocks \
-   'ItrBlkFrmNstFls:1¤./docs/dev/specs-import.md:0_ItrBlkFrmNstFls:4¤./docs/dev/specs-import.md:3_ItrBlkFrmNstFls:7¤./docs/dev/specs-import.md:6'
+   'IBNF:1¤./docs/dev/specs-import.md:0_IBNF:4¤./docs/dev/specs-import.md:3_IBNF:7¤./docs/dev/specs-import.md:6'
 }

data/bats/load-vars-state-demo.bats

@@ -4,23 +4,23 @@ load 'test_helper'
 
 @test 'displays document initial state' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/load-vars-state-demo.md \
-   'var1 = line1_var3 = line6_  inherited_lines_  - : var1="line1"_  - : var3="line6"_            LOAD BLOCK STATE MODIFICATION DEMO__This document demonstrates how a LOAD block can modify_the inherited state that was initially set by VARS_blocks.__First, establish baseline variables using a VARS block:__Use a LOAD block to modify the initial state:__load-mode-default_load-mode-append_load-mode-replace'
+   'var1 = line1_var3 = line6_  context_code_  - : var1="line1"_  - : var3="line6"_            LOAD BLOCK STATE MODIFICATION DEMO__This document demonstrates how a LOAD block can modify_the inherited state that was initially set by VARS_blocks.__First, establish baseline variables using a VARS block:__Use a LOAD block to modify the initial state:__load-mode-default_load-mode-append_load-mode-replace'
 }
 
 @test 'applies load-mode-default to inherited state' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/load-vars-state-demo.md \
    load-mode-default \
-   'var1 = line1_var3 = line6_  inherited_lines_  - : var1="line1"_  - : var3="line6"_  inherited_lines_  - : var1="line1"_  - : var3="line6"_  - : # line 1_  - : var1=line2_  - : # line 3_  - : var2=line4_  - : # line 5_            LOAD BLOCK STATE MODIFICATION DEMO__This document demonstrates how a LOAD block can modify_the inherited state that was initially set by VARS_blocks.__First, establish baseline variables using a VARS block:__Use a LOAD block to modify the initial state:__load-mode-default_load-mode-append_load-mode-replace'
+   'var1 = line1_var3 = line6_  context_code_  - : var1="line1"_  - : var3="line6"_  context_code_  - : var1="line1"_  - : var3="line6"_  - : # line 1_  - : var1=line2_  - : # line 3_  - : var2=line4_  - : # line 5_            LOAD BLOCK STATE MODIFICATION DEMO__This document demonstrates how a LOAD block can modify_the inherited state that was initially set by VARS_blocks.__First, establish baseline variables using a VARS block:__Use a LOAD block to modify the initial state:__load-mode-default_load-mode-append_load-mode-replace'
 }
 
 @test 'appends to inherited state with load-mode-append' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/load-vars-state-demo.md \
    load-mode-append \
-   'var1 = line1_var3 = line6_  inherited_lines_  - : var1="line1"_  - : var3="line6"_  inherited_lines_  - : var1="line1"_  - : var3="line6"_  - : # line 1_  - : var1=line2_  - : # line 3_  - : var2=line4_  - : # line 5_            LOAD BLOCK STATE MODIFICATION DEMO__This document demonstrates how a LOAD block can modify_the inherited state that was initially set by VARS_blocks.__First, establish baseline variables using a VARS block:__Use a LOAD block to modify the initial state:__load-mode-default_load-mode-append_load-mode-replace'
+   'var1 = line1_var3 = line6_  context_code_  - : var1="line1"_  - : var3="line6"_  context_code_  - : var1="line1"_  - : var3="line6"_  - : # line 1_  - : var1=line2_  - : # line 3_  - : var2=line4_  - : # line 5_            LOAD BLOCK STATE MODIFICATION DEMO__This document demonstrates how a LOAD block can modify_the inherited state that was initially set by VARS_blocks.__First, establish baseline variables using a VARS block:__Use a LOAD block to modify the initial state:__load-mode-default_load-mode-append_load-mode-replace'
 }
 
 @test 'replaces inherited state with load-mode-replace' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/load-vars-state-demo.md \
    load-mode-replace \
-   'var1 = line1_var3 = line6_  inherited_lines_  - : var1="line1"_  - : var3="line6"_  inherited_lines_  - : # line 1_  - : var1=line2_  - : # line 3_  - : var2=line4_  - : # line 5_            LOAD BLOCK STATE MODIFICATION DEMO__This document demonstrates how a LOAD block can modify_the inherited state that was initially set by VARS_blocks.__First, establish baseline variables using a VARS block:__Use a LOAD block to modify the initial state:__load-mode-default_load-mode-append_load-mode-replace'
+   'var1 = line1_var3 = line6_  context_code_  - : var1="line1"_  - : var3="line6"_  context_code_  - : # line 1_  - : var1=line2_  - : # line 3_  - : var2=line4_  - : # line 5_            LOAD BLOCK STATE MODIFICATION DEMO__This document demonstrates how a LOAD block can modify_the inherited state that was initially set by VARS_blocks.__First, establish baseline variables using a VARS block:__Use a LOAD block to modify the initial state:__load-mode-default_load-mode-append_load-mode-replace'
 }

data/bin/tab_completion.sh

@@ -44,7 +44,7 @@ _mde() {
             
               --dump-inherited-dependencies) COMPREPLY="f"; return 0 ;;
             
-              --dump-inherited-lines) COMPREPLY="f"; return 0 ;;
+              --dump-context-code) COMPREPLY="f"; return 0 ;;
             
               --dump-menu-blocks) COMPREPLY="f"; return 0 ;;
             
@@ -110,7 +110,7 @@ _mde() {
   # present matching option names
   #
   if [[ ${cur} == -* ]] ; then
-    opts=("--block-name" "--blocks" "--config" "--debug" "--dig" "--dump-blocks-in-file" "--dump-delegate-object" "--dump-dependencies" "--dump-inherited-block-names" "--dump-inherited-dependencies" "--dump-inherited-lines" "--dump-menu-blocks" "--dump-selected-block" "--execute-in-own-window" "--exit" "--filename" "--find" "--find-path" "--help" "--history" "--how" "--list-blocks" "--list-blocks-eval" "--list-blocks-message" "--list-blocks-type" "--list-count" "--list-default-env" "--list-default-yaml" "--list-docs" "--format" "--list-recent-output" "--list-recent-scripts" "--load-code" "--mine" "--open" "--output-script" "--output-stdout" "--path" "--pause-after-script-execution" "--probe" "--publish-document-file-mode" "--publish-document-file-name" "--pwd" "--run-last-script" "--sift" "--tab-completions" "--user-must-approve" "--version" "--display-level")
+    opts=("--block-name" "--blocks" "--config" "--debug" "--dig" "--dump-blocks-in-file" "--dump-delegate-object" "--dump-dependencies" "--dump-inherited-block-names" "--dump-inherited-dependencies" "--dump-context-code" "--dump-menu-blocks" "--dump-selected-block" "--execute-in-own-window" "--exit" "--filename" "--find" "--find-path" "--help" "--history" "--how" "--list-blocks" "--list-blocks-eval" "--list-blocks-message" "--list-blocks-type" "--list-count" "--list-default-env" "--list-default-yaml" "--list-docs" "--format" "--list-recent-output" "--list-recent-scripts" "--load-code" "--mine" "--open" "--output-script" "--output-stdout" "--path" "--pause-after-script-execution" "--probe" "--publish-document-file-mode" "--publish-document-file-name" "--pwd" "--run-last-script" "--sift" "--tab-completions" "--user-must-approve" "--version" "--display-level")
     COMPREPLY=( $(compgen -W "$(printf "'%s' " "${opts[@]}")" -- "${cur}") )
 
     return 0
@@ -145,7 +145,7 @@ _mde() {
         
           --dump-inherited-dependencies) COMPREPLY=".BOOL."; return 0 ;;
         
-          --dump-inherited-lines) COMPREPLY=".BOOL."; return 0 ;;
+          --dump-context-code) COMPREPLY=".BOOL."; return 0 ;;
         
           --dump-menu-blocks) COMPREPLY=".BOOL."; return 0 ;;
         

data/docs/dev/bats-document-configuration.md

@@ -3,7 +3,7 @@ divider4_center: false
 
 dump_blocks_in_file: false     # Dump BlocksInFile (stage 1)
 dump_delegate_object: false    # Dump @delegate_object
-dump_inherited_lines: false    # Dump inherited lines
+dump_context_code: false    # Dump inherited lines
 dump_menu_blocks: false        # Dump MenuBlocks (stage 2)
 dump_selected_block: false     # Dump selected block
 

data/docs/dev/block-type-shell-context-eval.md

@@ -0,0 +1,52 @@
+```vars :(document_vars)
+VARS1: '0.0'
+```
+/ these lines are appended to the context; print values
+```bash :[context] +print-values @context
+SHELL_V1="${VARS1}, 1.1"
+SHELL_V2="${VARS1}, 1.2"
+```
+
+/ these lines are executed and the output is the transient code; print values
+```bash :[eval] +print-values @eval
+echo "SHELL_V1=\"${VARS1}, 2.1\""
+echo "SHELL_V2=\"${VARS1}, 2.2\""
+```
+
+/ these lines are executed and the output is appended to the context; print values
+```bash :[eval-context] +print-values @eval @context
+echo "SHELL_V1=\"${VARS1}, 3.1\""
+echo "SHELL_V2=\"${VARS1}, 3.2\""
+```
+
+/ require block setting context; set transient code; print values
+```bash :[require-context] +[context]
+SHELL_V1="${SHELL_V1}, 4.1"
+SHELL_V2="${SHELL_V2}, 4.2"
+```
+
+/ require block setting context from eval output; set transient code; print values
+```bash :[require-eval-context] +[eval-context]
+SHELL_V1="${SHELL_V1}, 5.1"
+SHELL_V2="${SHELL_V2}, 5.2"
+```
+
+/ these values are present while the block is being evaluated
+```bash :print-values 
+echo "~ SHELL_V1=$SHELL_V1"
+echo "~ SHELL_V2=$SHELL_V2"
+```
+```opts :[opts]
+dump_context_code: true
+```
+/| Variable| Value
+/| -| -
+/| VARS1| ${VARS1}
+/| SHELL_V1| ${SHELL_V1}
+/| SHELL_V2| ${SHELL_V2}
+@import bats-document-configuration.md
+```opts :(document_opts)
+/dump_context_code: true
+/menu_for_saved_lines: true
+menu_with_exit: true
+```

data/docs/dev/block-type-shell-require-ux.md

@@ -1,6 +1,6 @@
 / No blocks are evaluated at initialization.
 / When the shell block is activated, the UX block is required.
-```bash :require-a-UX-block +[ux1]
+```bash :require-a-UX-block +[ux1] @context
 ENTITY='Mythical Monkey'
 ```
 / Display variables set in the UX block.
@@ -15,4 +15,8 @@ echo:
 init: false
 readonly: true
 ```
-@import bats-document-configuration.md
+@import bats-document-configuration.md
+/```opts :(document_opts)
+/dump_context_code: true
+/menu_for_saved_lines: true
+/```

data/docs/dev/block-type-ux-echo.md

@@ -4,8 +4,8 @@ echo: $(basename `pwd`)
 name: VAR
 ```
 / This block is not visible. Execute to display the inherited lines for testing.
-```opts :(menu_with_inherited_lines)
-menu_with_inherited_lines: true
+```opts :(menu_with_context_code)
+menu_with_context_code: true
 ```
 / This block is not visible. Execute to set a new value, displayed by the block above.
 ```ux :(VAR_has_count)
@@ -22,6 +22,6 @@ echo: $VAR$VAR
 name: IAB
 ```
 ```opts :(document_opts)
-menu_with_inherited_lines: false
+menu_with_context_code: false
 ```
 @import bats-document-configuration.md

data/docs/dev/block-type-ux-force.md

@@ -15,6 +15,6 @@ name: Common_Name
 ! Common_Name! ${Common_Name}
 @import bats-document-configuration.md
 ```opts :(document_opts)
-dump_inherited_lines: true
+dump_context_code: true
 table_center: false
 ```

data/docs/dev/block-type-ux-require-chained.md

@@ -28,6 +28,6 @@ init: false
 name: NAME2
 ```
 ```opts :(document_opts)
-menu_with_inherited_lines: true
+menu_with_context_code: true
 ```
 @import bats-document-configuration.md

data/docs/dev/block-type-ux-require.md

@@ -29,7 +29,7 @@ ENTITY='Pongo tapanuliensis,Pongo'
 ```
 /
 / This block is not visible. Execute to display the inherited lines for testing.
-```opts :(menu_with_inherited_lines)
-menu_with_inherited_lines: true
+```opts :(menu_with_context_code)
+menu_with_context_code: true
 ```
 @import bats-document-configuration.md

data/docs/dev/import-parameter-symbols.md

@@ -10,5 +10,5 @@ name: COMMON_NAME
   NAMEV:vq=COMMON_NAME
 @import bats-document-configuration.md
 ```opts :(document_opts)
-dump_inherited_lines: false
+dump_context_code: false
 ```

data/docs/dev/linked-file.md

@@ -2,5 +2,5 @@
 echo "ARG1: $ARG1"
 ```
 ```opts :(document_opts)
-menu_with_inherited_lines: true
+menu_with_context_code: true
 ```

data/docs/dev/load-vars-state-demo.md

@@ -28,7 +28,7 @@ mode: replace
 /
 @import bats-document-configuration.md
 ```opts :(document_opts)
-dump_inherited_lines: true
+dump_context_code: true
 # menu_for_saved_lines: true
 
 screen_width: 64

data/docs/dev/requiring-blocks.md

@@ -21,5 +21,5 @@ echo "ARG1: $ARG1"
 @import bats-document-configuration.md
 ```opts :(document_opts)
 menu_with_exit: true
-menu_with_inherited_lines: true
+menu_with_context_code: true
 ```

data/docs/dev/specs.md

@@ -72,7 +72,7 @@ dump_blocks_in_file: false
 dump_dependencies: false
 dump_inherited_block_names: false
 dump_inherited_dependencies: false
-dump_inherited_lines: false
+dump_context_code: false
 dump_menu_blocks: false
 ```
 
@@ -80,5 +80,5 @@ dump_menu_blocks: false
 ```opts :(document_opts) +(disable_dump_*)
 menu_note_color: 'plain'
 menu_with_exit: true
-menu_with_inherited_lines: false
+menu_with_context_code: false
 ```

data/docs/shell-script-evaluation.md

@@ -0,0 +1,78 @@
+/ v2025-12-07
+/---
+
+# App configuration
+
+## CLI loading of app configuration
+
+A file is read into the app configuration using the `--config` command line option.
+
+## Per-document app configuration
+
+An OPTS block that is automatically loaded when the document is loaded, modifies the app configuration.
+
+## Activated block effect on app configuration
+
+An OPTS block that is activated by the user modifies the app configuration.
+
+/---
+
+# Context code
+
+The context code is empty when the app starts.
+
+## CLI loading of context code
+
+A file is loaded as the context code using the `--load-code` command line option.
+
+## Automatic blocks
+
+Some blocks are automatically processed when the document is loaded.
+
+A VARS block that is automatically loaded when the document is loaded, is appended to the context code.  Display variables set per the app configuration.
+
+A UX block that is automatically loaded, is appended to the context code.  Display variables set per the app configuration.
+
+A shell block that is automatically loaded is appended to the context code.
+
+## Activated VARS block
+
+The variables named, converted to shell code to set to the corresponding values, are appended to the context code.
+The app's environment is also updated with the specified variables and values.
+
+## Activated UX block
+
+Variables named, converted to shell code to set to the corresponding values, are appended to the context code.
+The app's environment is also updated with the specified variables and values.
+
+## Activated shell block
+
+The activated and required shell blocks marked as context are appended to the context code.
+
+/---
+
+# Transient code
+
+The transient code is empty between block activations.
+
+## Activated shell block
+
+The required blocks, the transient code for this block, are executed in a shell script and its output is displayed and logged.
+
+/---
+
+# Shell script composition
+
+The shell script is composed of the context code followed by the transient code. The context code will include variables or context code in the required blocks.
+
+## Script output
+
+The output of the executed script (STDOUT and STDERR) is displayed in the console and logged to a file.
+
+/---
+
+## Shell block activation
+
+The activated and required shell blocks, not marked as context by default, are are the transient code.
+The script is composed and executed.
+Display shell output per the app configuration.

data/examples/link-blocks-vars.md

@@ -22,7 +22,7 @@ View the current inherited lines.
 The inherited lines can also be displayed automatically within the menu by enabling this option:
 
 ```opts
-menu_with_inherited_lines: true
+menu_with_context_code: true
 ```
 
 ## Setting Variables in the Inherited Lines
@@ -80,7 +80,7 @@ This Link block (YAML) appends the output of the Bash code to the inherited line
 @import example-document-opts.md
 ```opts :(document_opts)
 execute_in_own_window: false
-menu_with_inherited_lines: false
+menu_with_context_code: false
 output_execution_report: false
 output_execution_summary: false
 pause_after_script_execution: true

data/examples/linked.md

@@ -2,7 +2,7 @@ Demonstrate setting variable values interactively for use in generated scripts.
 
 @import example-document-opts.md
 ```opts :(document_opts)
-menu_with_inherited_lines: true
+menu_with_context_code: true
 pause_after_script_execution: false
 user_must_approve: false
 ```

data/examples/linked1.md

@@ -2,7 +2,7 @@
 
 @import example-document-opts.md
 ```opts :(document_opts)
-dump_inherited_lines: true
+dump_context_code: true
 pause_after_script_execution: false
 user_must_approve: false
 ```
@@ -40,12 +40,5 @@ file: examples/linked2.md
 ```link :linked2_import_vars +(vars2)
 file: examples/linked2.md
 vars:
-  page2_var_via_environment: ${PAGE2_VAR_VIA_INHERIT}
-  page2_var_via_environment1: ${d1_v1}
-  page2_var_via_environment2: for_page2_from_page1_via_current_environment
+  page2_var_via_environment: for_page2_from_page1_via_current_environment
 ```
-```vars :(document_vars)
-d1_v1: 1
-```
-
-```

data/examples/opts-blocks.md

@@ -38,7 +38,7 @@ note 4
 ```opts
 dump_blocks_in_file: true      # Dump BlocksInFile (stage 1)
 dump_delegate_object: true     # Dump @delegate_object
-dump_inherited_lines: true     # Dump inherited lines
+dump_context_code: true     # Dump inherited lines
 dump_menu_blocks: true         # Dump MenuBlocks (stage 2)
 dump_selected_block: true      # Dump selected block
 ```
@@ -46,7 +46,7 @@ dump_selected_block: true      # Dump selected block
 ```opts
 dump_blocks_in_file: false     # Dump BlocksInFile (stage 1)
 dump_delegate_object: false    # Dump @delegate_object
-dump_inherited_lines: false    # Dump inherited lines
+dump_context_code: false    # Dump inherited lines
 dump_menu_blocks: false        # Dump MenuBlocks (stage 2)
 dump_selected_block: false     # Dump selected block
 ```

data/examples/port-blocks.md

@@ -28,7 +28,7 @@ VAULT2
 
 @import example-document-opts.md
 ```opts :(document_opts)
-dump_inherited_lines: true
+dump_context_code: true
 execute_in_own_window: false
 output_execution_report: false
 output_execution_summary: false

data/examples/variable-expansion.md

@@ -75,7 +75,7 @@ divider4_center: false
 
 dump_blocks_in_file: false     # Dump BlocksInFile (stage 1)
 dump_delegate_object: false    # Dump @delegate_object
-dump_inherited_lines: false    # Dump inherited lines
+dump_context_code: false    # Dump inherited lines
 dump_menu_blocks: false        # Dump MenuBlocks (stage 2)
 dump_selected_block: false     # Dump selected block
 

data/lib/cached_nested_file_reader.rb

@@ -53,11 +53,12 @@ class CachedNestedFileReader
   def error_handler(name = '', opts = {})
     Exceptions.error_handler(
       "CachedNestedFileReader.#{name} -- #{$!}",
+      caller.deref(6),
       opts
     )
   end
 
-  def warn_format(name, message, opts = {})
+  def self.warn_format(name, message, opts = {})
     Exceptions.warn_format(
       "CachedNestedFileReader.#{name} -- #{message}",
       opts
@@ -113,7 +114,7 @@ class CachedNestedFileReader
 
         # apply substitutions to the @import line
         line_sub1 = apply_line_substitutions(line, substitutions,
-                                                    use_template_delimiters)
+                                             use_template_delimiters)
 
         # parse the @import line
         Regexp.new(@import_directive_line_pattern) =~ line_sub1
@@ -197,8 +198,10 @@ class CachedNestedFileReader
     wwt :read_document_code, 'processed_lines:', processed_lines
     @file_cache[cache_key] = processed_lines
   rescue Errno::ENOENT => err
-    warn_format('readlines', "#{err} @@ #{context}",
-                { abort: true })
+    CachedNestedFileReader.warn_format(
+      'readlines', "#{err} @@ #{context}",
+      { abort: true }
+    )
   rescue StandardError
     wwe $!
   end
@@ -327,7 +330,7 @@ class CachedNestedFileReader
   # Matches the beginning of the first line as '#!' - anything after that matches a shebang
   def is_shebang_line?(line, is_first_line)
     return false unless is_first_line
-    
+
     line.start_with?('#!')
   end
 end
@@ -542,7 +545,7 @@ class CachedNestedFileReaderTest < Minitest::Test
     )
 
     result = reader_with_hide.readlines(file_with_shebang.path).map(&:to_s)
-    assert_equal ['Line1', 'Line2'], result, 'Shebang line should be filtered when hide_shebang is true'
+    assert_equal %w[Line1 Line2], result, 'Shebang line should be filtered when hide_shebang is true'
 
     file_with_shebang.close
     file_with_shebang.unlink
@@ -633,7 +636,7 @@ class CachedNestedFileReaderTest < Minitest::Test
     )
 
     result = reader_with_hide.readlines(file_without_shebang.path).map(&:to_s)
-    assert_equal ['Line1', 'Line2', 'Line3'], result, 'File without shebang should work normally'
+    assert_equal %w[Line1 Line2 Line3], result, 'File without shebang should work normally'
 
     file_without_shebang.close
     file_without_shebang.unlink