markdown_exec 3.0.8 → 3.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fd2355b28f935804fb135a650cc4260276be2bed20a8ed33cf9d188e01734466
-  data.tar.gz: 9e001b6252ebc4f012408e8a43373ab49b474d72982fc9bbc653c93e6d39c497
+  metadata.gz: 401f0583b9951f0cfd6259313d7120d2f5f7fbbb3c596110eeafe449f63b9ca7
+  data.tar.gz: 8c411e5c1f3ae394d76a2e0fbbc92aae009e31ba0e17b9fa29d30dabfd8b8e5a
 SHA512:
-  metadata.gz: a17c1e662569ae1b0f34ecbb63571120c3d56bc2efdde29651240ec6d6d07e0f24e361ae9c95d34725f5c9f6a1c2d6f18fc9aad9971bdba3e2b2f850f14418d5
-  data.tar.gz: 95184776dfde2e6579aa18e0893a9f54180c2b641d65263f0d47f5533512611f3b92c9012959bb18c0c263ca3f50dccc42e4f69651f46a4af878d02784ce40ba
+  metadata.gz: 896ac3441e10cac18bbccbe02913612f8a926a7108dd86a9b01d0dc8354d1da4f8ca58dcb8413f460072277802639be2bd4421efc83abced9e18ea9212505010
+  data.tar.gz: 4804a98ff4a6ff6a5d7ba7dc0739e6ec2d6b7a115dd7f6198955261bf1d07ed62e93c9d1180570e14f3d1e43e6a59a6ae587c21fbbd13d02491b79ad7ac92e1e

data/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [3.1.0] - 2025-06-23
+
+### Added
+
+- Enhance import with text substitution.
+- Load block modes (append, replace).
+
+### Changed
+
+- Handle interrupt at UX edit prompt.
+- Apply the force attribute (stated and default) in UX blocks.
+
+## [3.0.9] - 2025-06-12
+
+### Changed
+
+- Edited values are appended to inherited lines.
+
+## [3.0.8] - 2025-06-11
+
+### Changed
+
+- Export code from UX blocks.
+
+## [3.0.7] - 2025-06-10
+
+### Changed
+
+- Fix False as the initial allow value.
+
 ## [3.0.6] - 2025-06-07
 
 ### Added

data/Gemfile.lock

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

data/bats/block-type-ux-required-variables.bats

@@ -6,15 +6,3 @@ load 'test_helper'
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-required-variables.md \
    'SPECIES='
 }
-
-# hangs
-# Enter a value: []: #<Errno::EISDIR: Is a directory @ io_fillbuf - fd:12 test>
-# ["/Users/fareed/Documents/dev/ruby/markdown_exec/lib/hash_delegator.rb:4650:in `gets'",
-#  "/Users/fareed/Documents/dev/ruby/markdown_exec/lib/hash_delegator.rb:4650:in `gets'",
-#  "/Users/fareed/Documents/dev/ruby/markdown_exec/lib/hash_delegator.rb:4650:in `block in ux_block_export_activated'",
-#
-#@test 'An undefined variable is a precondition - active' {
-#  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-required-variables.md \
-#   test \
-#   'A value must exist for: MISSING_VARIABLE_SPECIES='
-#}

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

@@ -26,11 +26,3 @@ load 'test_helper'
    'false_false_false_false_false_false'
 }
 
-# test trigger presents prompt
-# test trigger presents allow list
-# test validation limits input
-# test transform formats output
-# test format creates output
-# test default, validation, prompt are displayed
-
-# bin/bmde docs/dev/block-type-ux-sources.md --list-blocks-message init_source --list-blocks-type 3 --list-blocks

data/bats/cli.bats

@@ -36,6 +36,18 @@ load 'test_helper'
    ' ARG1: 37'
 }
 
+@test 'vars in link block are appended to inherited lines - local link' {
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/requiring-blocks.md \
+   '[link-local-block-with-vars]' \
+   '* Exit_# [link-local-block-with-vars]_ARG1="37"_block: echo-ARG1_  file: docs/dev/linked-file.md_  vars:_    ARG1: arg1-from-link-file_block: output_arguments_  vars:_    ARG1: 37_block: missing_ARG1=37_output_arguments'
+}
+
+@test 'vars in link block are appended to inherited lines - external file' {
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/requiring-blocks.md \
+   '[link-file-block-with-vars]' \
+   '* Exit_# [link-file-block-with-vars]_ARG1="arg1-from-link-file"_echo-ARG1'
+}
+
 # the last block is a link block, so menu is displayed
 @test 'link block setting an environment variable requires a bash block' {
   BATS_OUTPUT_FILTER=A

data/bats/import-with-text-substitution.bats

@@ -0,0 +1,9 @@
+#!/usr/bin/env bats
+
+load 'test_helper'
+
+@test 'enhanced @import functionality with text substitution' {
+  BATS_OUTPUT_FILTER=A
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/import-with-text-substitution.md \
+   'IMPORT SUBSTITUTION COMPREHENSIVE TEST__Tests enhanced @import ./functionality with text_substitution using biological entity data.__Basic Import (Backward Compatibility)__Basic import without parameters.__Content: Static biological reference data._Source: Living entities research database._Format: Markdown with embedded data. __Raw Replacement - Simple Parameters__Genus: Pongo_Family: Hominidae  _Order: Primates__Classification hierarchy shows Pongo within Hominidae of_Primates.__Raw Replacement - Quoted Values__Common Name: Tapanuli Orangutan_Scientific Name: Pongo tapanuliensis_Discovery Location: Sumatra, Indonesia__Organism Tapanuli Orangutan (Pongo tapanuliensis) found_in Sumatra, Indonesia.__Note: Tapanuli Orangutan contains spaces, Pongo_tapanuliensis contains spaces, Sumatra, Indonesia_contains punctuation.__Raw Replacement - Mixed Parameters__Species: Psychedelic Frogfish (Histiophryne psychedelica)_Discovery: 2009_Depth Range: 15-65 meters_Habitat: Coral reefs__Marine organism Psychedelic Frogfish discovered in 2009._Lives at 15-65 meters in Coral reefs environment.__Test: 2009 is numeric, 15-65 meters contains units, Coral_reefs contains spaces.__Raw Replacement - Numbers and Special Characters__Organism: Yeti Crab_Year: 2005  _Depth: 2200 meters_Temperature: 2°C_Location: Easter Island microplate__Discovery data: Yeti Crab found 2005 at 2200 meters depth._Environment: 2°C water near Easter Island microplate.__Tests: Numbers (2005, 2200), special chars (2°C °C),_complex location.__Raw Replacement - Long Scientific Names__Classification of Ecuadorian Glassfrog:__Scientific Name: Hyalinobatrachium yaku_Genus: Hyalinobatrachium_Family: Centrolenidae_Order: Anura  _Class: Amphibia__Full classification: Amphibia > Anura > Centrolenidae >_Hyalinobatrachium > Hyalinobatrachium yaku__Long names test: Hyalinobatrachium and Centrolenidae are_lengthy taxonomic terms._Species Hyalinobatrachium yaku demonstrates complex_scientific nomenclature.__Raw Replacement - Plant Data__Plant Species: Spiny Dandelion (Taraxacum japonicum)__Kingdom: Plantae_Phylum: Tracheophyta  _Class: Magnoliopsida__Plant classification differs from animal taxonomy._Spiny Dandelion belongs to Plantae with phylum_Tracheophyta._Classification ends at Magnoliopsida level for this plant.__Test: Plant-specific taxonomic structure. __Raw Replacement - Multiple Species Comparison__Species Comparison:__Species A: Kiwa hirsuta (2005)_Species B: Phyllopteryx dewysea (2015)__Habitat A: Deep sea_Habitat B: Coastal waters__Discovery timeline: Kiwa hirsuta found 2005, Phyllopteryx_dewysea found 2015._Environment: Deep sea vs Coastal waters.__Test: Numbered parameters (Kiwa hirsuta/Phyllopteryx_dewysea) and temporal data.__Raw Replacement - Taxonomic Hierarchy__Complete Taxonomic Classification:__Domain: Eukaryota_Kingdom: Animalia_Phylum: Chordata_Class: Mammalia_Order: Primates_Family: Hominidae_Genus: Homo_Species: Homo luzonensis__Full hierarchy: Eukaryota > Animalia > Chordata >_Mammalia > Primates > Hominidae > Homo > Homo luzonensis__Test: Complete 8-level taxonomic classification with all_major ranks.__Raw Replacement - Research Data__Research Study:__Lead Researcher: Dr. Matthew Leach_Institution: California Academy of Sciences_Method: Genetic analysis_Sample Size: 47 specimens__Study conducted by Dr. Matthew Leach at California_Academy of Sciences._Used Genetic analysis with 47 total samples.__Test: Researcher names, institution names, methodology_terms, numeric data.__Export and Variables__Organism Data Export:__export Illacme tobini_NAME="Illacme tobini"_export 2016=2016_export 414=414_export California="California"_export Endemic="Endemic"__echo "Processing Illacme tobini from 2016"_echo "Characteristics: 414 legs"_echo "Location: California (Endemic)"__Variable assignment test: Illacme tobini has 414 legs,_found in California._Status: Endemic as of 2016 discovery.__Test: Shell exports, numeric values, status terms. __Expected output shows proper text substitution with word_boundary protection.'
+}

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

@@ -0,0 +1,26 @@
+#!/usr/bin/env bats
+
+load 'test_helper'
+
+@test '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'
+}
+
+@test 'load-mode-default' {
+  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'
+}
+
+@test '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'
+}
+
+@test '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'
+}

data/bats/options.bats

@@ -19,7 +19,7 @@ load 'test_helper'
 
 @test 'Options - find, find-path in directory names' {
   run_mde_specs_md_args_expect_xansi --find-path ./docs --find search \
-   'Searching in: ./docs In directory names ./docs/research'
+   'Searching in: ./docs In directory names ./docs/research In file names ./docs/dev/import-substitution-research.md'
 }
 
 @test 'Options - find, find-path in file names' {

data/docs/dev/import-substitution-basic.md

@@ -0,0 +1,5 @@
+Basic import without parameters.
+
+Content: Static biological reference data.
+Source: Living entities research database.
+Format: Markdown with embedded data. 

data/docs/dev/import-substitution-compare.md

@@ -0,0 +1,12 @@
+Species Comparison:
+
+Species A: SPECIES1 (YEAR1)
+Species B: SPECIES2 (YEAR2)
+
+Habitat A: HABITAT1
+Habitat B: HABITAT2
+
+Discovery timeline: SPECIES1 found YEAR1, SPECIES2 found YEAR2.
+Environment: HABITAT1 vs HABITAT2.
+
+Test: Numbered parameters (SPECIES1/SPECIES2) and temporal data. 

data/docs/dev/import-substitution-export.md

@@ -0,0 +1,18 @@
+Organism Data Export:
+
+```bash
+export ORGANISM_NAME="ORGANISM"
+export DISCOVERY_YEAR=DISCOVERY_YEAR
+export LEG_COUNT=LEG_COUNT
+export LOCATION="LOCATION"
+export STATUS="STATUS"
+
+echo "Processing ORGANISM from DISCOVERY_YEAR"
+echo "Characteristics: LEG_COUNT legs"
+echo "Location: LOCATION (STATUS)"
+```
+
+Variable assignment test: ORGANISM has LEG_COUNT legs, found in LOCATION.
+Status: STATUS as of DISCOVERY_YEAR discovery.
+
+Test: Shell exports, numeric values, status terms. 

data/docs/dev/import-substitution-long.md

@@ -0,0 +1,12 @@
+Classification of COMMON_NAME:
+
+Scientific Name: SPECIES
+Genus: GENUS
+Family: FAMILY
+Order: ORDER  
+Class: CLASS
+
+Full classification: CLASS > ORDER > FAMILY > GENUS > SPECIES
+
+Long names test: GENUS and FAMILY are lengthy taxonomic terms.
+Species SPECIES demonstrates complex scientific nomenclature. 

data/docs/dev/import-substitution-mixed.md

@@ -0,0 +1,9 @@
+Species: COMMON_NAME (SPECIES)
+Discovery: YEAR_DISCOVERED
+Depth Range: DEPTH
+Habitat: HABITAT
+
+Marine organism COMMON_NAME discovered in YEAR_DISCOVERED.
+Lives at DEPTH in HABITAT environment.
+
+Test: YEAR_DISCOVERED is numeric, DEPTH contains units, HABITAT contains spaces. 

data/docs/dev/import-substitution-plant.md

@@ -0,0 +1,11 @@
+Plant Species: COMMON_NAME (SPECIES)
+
+Kingdom: KINGDOM
+Phylum: PHYLUM  
+Class: CLASS
+
+Plant classification differs from animal taxonomy.
+COMMON_NAME belongs to KINGDOM with phylum PHYLUM.
+Classification ends at CLASS level for this plant.
+
+Test: Plant-specific taxonomic structure. 

data/docs/dev/import-substitution-quotes.md

@@ -0,0 +1,7 @@
+Common Name: COMMON_NAME
+Scientific Name: SPECIES
+Discovery Location: LOCATION
+
+Organism COMMON_NAME (SPECIES) found in LOCATION.
+
+Note: COMMON_NAME contains spaces, SPECIES contains spaces, LOCATION contains punctuation. 

data/docs/dev/import-substitution-research.md

@@ -0,0 +1,11 @@
+Research Study:
+
+Lead Researcher: RESEARCHER
+Institution: INSTITUTION
+Method: DISCOVERY_METHOD
+Sample Size: SAMPLE_SIZE specimens
+
+Study conducted by RESEARCHER at INSTITUTION.
+Used DISCOVERY_METHOD with SAMPLE_SIZE total samples.
+
+Test: Researcher names, institution names, methodology terms, numeric data. 

data/docs/dev/import-substitution-simple.md

@@ -0,0 +1,5 @@
+Genus: GENUS
+Family: FAMILY  
+Order: ORDER
+
+Classification hierarchy shows GENUS within FAMILY of ORDER. 

data/docs/dev/import-substitution-special.md

@@ -0,0 +1,10 @@
+Organism: COMMON_NAME
+Year: YEAR_DISCOVERED  
+Depth: DEPTH meters
+Temperature: TEMPERATURE
+Location: LOCATION
+
+Discovery data: COMMON_NAME found YEAR_DISCOVERED at DEPTH meters depth.
+Environment: TEMPERATURE water near LOCATION.
+
+Tests: Numbers (YEAR_DISCOVERED, DEPTH), special chars (TEMPERATURE °C), complex location. 

data/docs/dev/import-substitution-taxonomy.md

@@ -0,0 +1,14 @@
+Complete Taxonomic Classification:
+
+Domain: DOMAIN
+Kingdom: KINGDOM
+Phylum: PHYLUM
+Class: CLASS
+Order: ORDER
+Family: FAMILY
+Genus: GENUS
+Species: SPECIES
+
+Full hierarchy: DOMAIN > KINGDOM > PHYLUM > CLASS > ORDER > FAMILY > GENUS > SPECIES
+
+Test: Complete 8-level taxonomic classification with all major ranks. 

data/docs/dev/import-with-text-substitution.md

@@ -0,0 +1,57 @@
+# Import Substitution Comprehensive Test
+
+Tests enhanced @import ./functionality with text substitution using biological entity data.
+
+## Basic Import (Backward Compatibility)
+
+@import ./import-substitution-basic.md
+
+## Raw Replacement - Simple Parameters
+
+@import ./import-substitution-simple.md GENUS=Pongo FAMILY=Hominidae ORDER=Primates
+
+## Raw Replacement - Quoted Values
+
+@import ./import-substitution-quotes.md COMMON_NAME="Tapanuli Orangutan" SPECIES="Pongo tapanuliensis" LOCATION="Sumatra, Indonesia"
+
+## Raw Replacement - Mixed Parameters
+
+@import ./import-substitution-mixed.md COMMON_NAME="Psychedelic Frogfish" SPECIES="Histiophryne psychedelica" YEAR_DISCOVERED=2009 DEPTH="15-65 meters" HABITAT="Coral reefs"
+
+## Raw Replacement - Numbers and Special Characters
+
+@import ./import-substitution-special.md COMMON_NAME="Yeti Crab" YEAR_DISCOVERED=2005 DEPTH=2200 TEMPERATURE="2°C" LOCATION="Easter Island microplate"
+
+## Raw Replacement - Long Scientific Names
+
+@import ./import-substitution-long.md COMMON_NAME="Ecuadorian Glassfrog" SPECIES="Hyalinobatrachium yaku" GENUS=Hyalinobatrachium FAMILY=Centrolenidae ORDER=Anura CLASS=Amphibia
+
+## Raw Replacement - Plant Data
+
+@import ./import-substitution-plant.md COMMON_NAME="Spiny Dandelion" SPECIES="Taraxacum japonicum" KINGDOM=Plantae PHYLUM=Tracheophyta CLASS=Magnoliopsida
+
+## Raw Replacement - Multiple Species Comparison
+
+@import ./import-substitution-compare.md SPECIES1="Kiwa hirsuta" SPECIES2="Phyllopteryx dewysea" YEAR1=2005 YEAR2=2015 HABITAT1="Deep sea" HABITAT2="Coastal waters"
+
+## Raw Replacement - Taxonomic Hierarchy
+
+@import ./import-substitution-taxonomy.md DOMAIN=Eukaryota KINGDOM=Animalia PHYLUM=Chordata CLASS=Mammalia ORDER=Primates FAMILY=Hominidae GENUS=Homo SPECIES="Homo luzonensis"
+
+## Raw Replacement - Research Data
+
+@import ./import-substitution-research.md RESEARCHER="Dr. Matthew Leach" INSTITUTION="California Academy of Sciences" DISCOVERY_METHOD="Genetic analysis" SAMPLE_SIZE=47
+
+## Export and Variables
+
+@import ./import-substitution-export.md ORGANISM="Illacme tobini" DISCOVERY_YEAR=2016 LEG_COUNT=414 LOCATION="California" STATUS="Endemic"
+
+Expected output shows proper text substitution with word boundary protection.
+@import ./bats-document-configuration.md
+```opts :(document_opts)
+heading1_center: false
+heading2_center: false
+menu_include_imported_blocks: true
+menu_include_imported_notes: true
+screen_width: 64
+```

data/docs/dev/linked-file.md

@@ -1,3 +1,6 @@
 ```bash :echo-ARG1
 echo "ARG1: $ARG1"
+```
+```opts :(document_opts)
+menu_with_inherited_lines: true
 ```

data/docs/dev/load-mode-demo.md

@@ -0,0 +1,163 @@
+# LOAD Block Mode Demonstration
+
+This document demonstrates the difference between `mode: append` (default) and `mode: replace` for LOAD blocks.
+
+## Setup: Create Initial Inherited Lines
+
+First, let's establish some inherited lines that will be used to test the different modes:
+
+```vars :setup_environment
+PROJECT_NAME: load-mode-demo
+VERSION: 1.0.0
+AUTHOR: MDE Testing
+```
+
+```bash :create_initial_context
+echo "# Initial Context"
+echo "PROJECT: $PROJECT_NAME"
+echo "VERSION: $VERSION" 
+echo "AUTHOR: $AUTHOR"
+echo ""
+echo "# These lines are inherited and available for LOAD operations"
+```
+
+## Test Files Setup
+
+Create test files in document_configurations directory for loading:
+
+```bash :create_test_files
+mkdir -p document_configurations/load_demo
+
+# Create append-demo.sh
+cat > document_configurations/load_demo/append-demo.sh << 'EOF'
+echo "=== Loaded via APPEND mode ==="
+echo "This content will be ADDED to existing inherited lines"
+echo "Original context should still be visible above"
+echo "Loaded at: $(date)"
+EOF
+
+# Create replace-demo.sh  
+cat > document_configurations/load_demo/replace-demo.sh << 'EOF'
+echo "=== Loaded via REPLACE mode ==="
+echo "This content REPLACES all inherited lines"
+echo "Original context should NOT be visible"
+echo "Loaded at: $(date)"
+echo "Only this loaded content should execute"
+EOF
+
+echo "Test files created successfully"
+ls -la document_configurations/load_demo/
+```
+
+## Test 1: Default Mode (Append)
+
+This LOAD block uses the default behavior where loaded content is **appended** to inherited lines:
+
+```load :test_append_mode
+directory: document_configurations/load_demo
+filename_pattern: '^(?<name>.*)$'
+glob: 'append-demo.sh'
+view: '%{name}'
+```
+
+Expected behavior:
+- The initial context (PROJECT, VERSION, AUTHOR) should execute first
+- Then the loaded content from append-demo.sh should execute
+- Both sets of lines are combined
+
+## Test 2: Explicit Append Mode
+
+This LOAD block explicitly specifies `mode: append` (same as default):
+
+```load :test_explicit_append
+directory: document_configurations/load_demo  
+filename_pattern: '^(?<name>.*)$'
+glob: 'append-demo.sh'
+view: '%{name}'
+mode: append
+```
+
+Expected behavior: Same as Test 1 - inherited lines + loaded content
+
+## Test 3: Replace Mode
+
+This LOAD block uses `mode: replace` where loaded content **replaces** all inherited lines:
+
+```load :test_replace_mode
+directory: document_configurations/load_demo
+filename_pattern: '^(?<name>.*)$' 
+glob: 'replace-demo.sh'
+view: '%{name}'
+mode: replace
+```
+
+Expected behavior:
+- The initial context (PROJECT, VERSION, AUTHOR) should NOT execute
+- Only the loaded content from replace-demo.sh should execute
+- Inherited lines are completely replaced
+
+## Test 4: Multiple Loads with Different Modes
+
+First, load with append to build up context:
+
+```load :build_context_append
+directory: document_configurations/load_demo
+filename_pattern: '^(?<name>.*)$'
+glob: 'append-demo.sh' 
+view: '%{name}'
+mode: append
+```
+
+Then load with replace to demonstrate clearing:
+
+```load :clear_and_replace
+directory: document_configurations/load_demo
+filename_pattern: '^(?<name>.*)$'
+glob: 'replace-demo.sh'
+view: '%{name}'
+mode: replace  
+```
+
+Expected behavior:
+- After first load: initial context + append-demo content
+- After second load: only replace-demo content (everything else cleared)
+
+## Verification Commands
+
+Check what's in our inherited lines at different points:
+
+```bash :check_inherited_state
+echo "=== Current Inherited State ==="
+echo "If you see initial setup variables, APPEND mode is working"
+echo "If you only see loaded content, REPLACE mode is working"
+echo ""
+env | grep -E "(PROJECT_NAME|VERSION|AUTHOR)" || echo "No setup variables found - likely REPLACE mode was used"
+```
+
+## Use Cases for Each Mode
+
+### Mode: Append (Default)
+- **Use case**: Adding functionality to existing context
+- **Example**: Loading utility functions while keeping current environment
+- **Behavior**: Inherited lines + loaded content
+
+### Mode: Replace  
+- **Use case**: Starting fresh with completely new context
+- **Example**: Loading a different configuration that should not mix with current state
+- **Behavior**: Only loaded content, inherited lines discarded
+
+## Clean Up
+
+```bash :cleanup
+rm -rf document_configurations/load_demo
+echo "Test files cleaned up"
+```
+
+## Implementation Notes
+
+The `mode` parameter in LOAD blocks controls how the loaded content interacts with inherited lines:
+
+- `mode: append` (default): `inherited_lines + loaded_content`  
+- `mode: replace`: `loaded_content` (inherited_lines ignored)
+
+This is implemented in the `next_state_append_code` method which now accepts a mode parameter and conditionally includes inherited lines based on the mode value. 

data/docs/dev/requiring-blocks.md

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

data/examples/import_with_substitution_demo.md

@@ -0,0 +1,48 @@
+# Import with Text Substitution Demo
+
+This demonstrates the new enhanced `@import` functionality that supports text substitution parameters with **raw replacement** as the primary mode, using biological entity data.
+
+## Primate Classification Examples
+
+@import imports/organism_template.md COMMON_NAME="Tapanuli Orangutan" SPECIES="Pongo tapanuliensis" GENUS=Pongo FAMILY=Hominidae ORDER=Primates CLASS=Mammalia YEAR_DISCOVERED=2017
+
+@import imports/organism_template.md COMMON_NAME="Homo luzonensis" SPECIES="Homo luzonensis" GENUS=Homo FAMILY=Hominidae ORDER=Primates CLASS=Mammalia YEAR_DISCOVERED=2019
+
+## Marine Life Classification
+
+@import imports/organism_template.md COMMON_NAME="Yeti Crab" SPECIES="Kiwa hirsuta" GENUS=Kiwa FAMILY=Kiwaidae ORDER=Decapoda CLASS=Malacostraca YEAR_DISCOVERED=2005
+
+The imported template file uses **raw text placeholders** (just the key name) that get replaced with the biological data specified in the @import line.
+
+## Primary Mode: Raw Replacement
+
+By default, template placeholders are just the key names without any delimiters:
+
+```
+Common Name: COMMON_NAME
+Species: SPECIES  
+Genus: GENUS
+Family: FAMILY
+```
+
+Gets transformed to:
+
+```
+Common Name: Tapanuli Orangutan
+Species: Pongo tapanuliensis
+Genus: Pongo
+Family: Hominidae
+```
+
+## Usage Examples
+
+Here are different ways to specify biological data:
+
+- Simple values: `@import imports/organism_template.md GENUS=Pongo CLASS=Mammalia`
+- Quoted values with spaces: `@import imports/organism_template.md COMMON_NAME="Psychedelic Frogfish"`  
+- Multiple taxonomic parameters: `@import imports/organism_template.md SPECIES="Pongo tapanuliensis" GENUS=Pongo FAMILY=Hominidae`
+- Mixed quoting: `@import imports/organism_template.md COMMON_NAME='Ruby Seadragon' SPECIES="Phyllopteryx dewysea" GENUS=Phyllopteryx`
+
+## Optional: Template Delimiters
+
+For cases where you need `${}` or `{{}}` style placeholders, you can use the template delimiter mode (requires code configuration). 

data/examples/imports/mixed_template.md

@@ -0,0 +1,33 @@
+# Research Report: COMMON_NAME
+
+**Scientific Name:** SPECIES  
+**Discovery Year:** YEAR_DISCOVERED
+
+## Summary
+
+This research document covers COMMON_NAME (SPECIES), discovered in YEAR_DISCOVERED.
+
+## Taxonomic Classification
+
+- **Genus:** GENUS
+- **Family:** FAMILY  
+- **Order:** ORDER
+- **Class:** CLASS
+
+```bash
+# Generate biological data report
+ORGANISM_NAME="COMMON_NAME"
+SCIENTIFIC_NAME="SPECIES"
+DISCOVERY_YEAR="YEAR_DISCOVERED"
+TAXONOMIC_GENUS="GENUS"
+TAXONOMIC_FAMILY="FAMILY"
+TAXONOMIC_ORDER="ORDER"
+TAXONOMIC_CLASS="CLASS"
+
+echo "Generating research report for: $ORGANISM_NAME"
+echo "Scientific classification: $SCIENTIFIC_NAME"
+echo "Discovered in: $DISCOVERY_YEAR"
+echo "Taxonomic hierarchy: $TAXONOMIC_CLASS > $TAXONOMIC_ORDER > $TAXONOMIC_FAMILY > $TAXONOMIC_GENUS"
+```
+
+Biological research template using **raw replacement** - all taxonomic placeholders are just the key names without delimiters. 

data/examples/imports/organism_template.md

@@ -0,0 +1,42 @@
+# COMMON_NAME Classification
+
+**Common Name:** COMMON_NAME  
+**Species:** SPECIES  
+**Genus:** GENUS  
+**Family:** FAMILY  
+**Order:** ORDER  
+**Class:** CLASS  
+**Year Discovered:** YEAR_DISCOVERED
+
+## Taxonomic Classification
+
+```bash
+# Biological classification data
+export COMMON_NAME="COMMON_NAME"
+export SPECIES="SPECIES"
+export GENUS="GENUS"
+export FAMILY="FAMILY"
+export ORDER="ORDER"
+export CLASS="CLASS"
+export YEAR_DISCOVERED="YEAR_DISCOVERED"
+
+echo "Organism: COMMON_NAME"
+echo "Scientific name: SPECIES"
+echo "Discovered in: YEAR_DISCOVERED"
+```
+
+## Classification Hierarchy
+
+```yaml
+organism:
+  common_name: COMMON_NAME
+  scientific_name: SPECIES
+  taxonomy:
+    genus: GENUS
+    family: FAMILY
+    order: ORDER
+    class: CLASS
+  discovery_year: YEAR_DISCOVERED
+```
+
+Biological organism template using raw replacement for taxonomic data.