markdown_exec 3.4.0 → 3.5.1

data/Rakefile

@@ -77,25 +77,25 @@ end
 def execute_with_error_handling(iterator)
   all_error_level = 0
   all_failed_files = []
-  
+
   iterator.each do |item|
     command = yield(item)
     next unless command # Skip if command is nil
-    
-    result = system(command)
+
+    system(command)
     error_level = $?.exitstatus
 
-    if error_level != 0
-      puts "Error: Command '#{command}' failed with exit status #{error_level}."
-      all_error_level = error_level
-      all_failed_files << command
-    end
-  end
+    next unless error_level != 0
 
-  if all_error_level != 0
-    puts "Error: #{all_failed_files.join(', ')} failed."
-    exit all_error_level
+    puts "Error: Command '#{command}' failed with exit status #{error_level}."
+    all_error_level = error_level
+    all_failed_files << command
   end
+
+  return unless all_error_level != 0
+
+  puts "Error: #{all_failed_files.join(', ')} failed."
+  exit all_error_level
 end
 
 desc 'bats'
@@ -114,20 +114,28 @@ task :listtests do
   puts `find lib -name '*.rb' -type f | xargs grep '< Minitest::Test' -l | sort`
 end
 
-desc 'minitest'
-task :minitest do
-  commands = [
-    './lib/argument_processor.rb --verbose',
-    './lib/block_label.rb --verbose',
-    './lib/cached_nested_file_reader.rb --verbose',
-    './lib/collapser.rb --verbose',
+def dev_test_commands
+  dev_dir = File.join(__dir__, 'lib', 'dev')
+  return [] unless Dir.exist?(dev_dir)
+
+  [
     './lib/dev/ansi_codes.rb --verbose',
     './lib/dev/append_to_bash_history.rb --verbose',
     './lib/dev/generate_transition_codes.rb --verbose',
     './lib/dev/hierarchy.rb --verbose',
     './lib/dev/process_command.rb --verbose',
     './lib/dev/process_template.rb --test --verbose',
-    './lib/dev/visibility-controller.rb --verbose',
+    './lib/dev/visibility-controller.rb --verbose'
+  ]
+end
+
+desc 'minitest'
+task :minitest do
+  commands = dev_test_commands + [
+    './lib/argument_processor.rb --verbose',
+    './lib/block_label.rb --verbose',
+    './lib/cached_nested_file_reader.rb --verbose',
+    './lib/collapser.rb --verbose',
     './lib/directory_searcher.rb --verbose',
     './lib/evaluate_shell_expressions.rb --verbose',
     './lib/fcb.rb --verbose',
@@ -164,26 +172,26 @@ end
 desc 'test'
 task :test do
   success = true
-  
+
   # Run all tests and track failures
   rspec_success = system('bundle exec rspec')
   success = false unless rspec_success
-  
+
   Rake::Task['minitest'].invoke
   minitest_success = $?.success?
   success = false unless minitest_success
-  
+
   Rake::Task['bats'].invoke
   bats_success = $?.success?
   success = false unless bats_success
-  
+
   # Report failures and exit with non-zero status if any test failed
   unless success
     failed_tests = []
     failed_tests << 'RSpec' unless rspec_success
     failed_tests << 'Minitest' unless minitest_success
     failed_tests << 'Bats' unless bats_success
-    
+
     puts "\nThe following test suites failed: #{failed_tests.join(', ')}"
     exit 1
   end
@@ -213,7 +221,7 @@ task :update_menu_yml do
   File.write(MENU_YML, menu_options.to_yaml)
   puts `stat #{MENU_YML}`
 end
-task :menu => 'update_menu_yml'
+task menu: 'update_menu_yml'
 
 # write tab_completion.sh with erb
 #

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

@@ -0,0 +1,15 @@
+#!/usr/bin/env bats
+
+load 'test_helper'
+
+@test 'initial' {
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-shell-require-ux.md \
+   'require-a-UX-block__FULL_NAME='
+}
+
+@test 'activated' {
+  # 2025-11-13 add a '.' block to force the display to update
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-shell-require-ux.md \
+   require-a-UX-block . \
+   '__require-a-UX-block_Mythical_Monkey_FULL_NAME=Mythical Monkey'
+}

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

@@ -16,5 +16,5 @@ load 'test_helper'
 @test 'selected block - output of wc includes whitespace' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-echo.md \
    '(VAR_has_count)' '[IAB_has_count]' \
-   'VAR=      14_IAB=      14      14'
+   'VAR=mmaarrkkddoowwnn__eexxeecc_IAB=mmaarrkkddoowwnn__eexxeeccmmaarrkkddoowwnn__eexxeecc'
 }

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

@@ -0,0 +1,14 @@
+#!/usr/bin/env bats
+
+load 'test_helper'
+
+@test 'initial' {
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-require-context.md \
+   'Get the common name..._Entity: _ENTITY2: _UX1: _Common name: '
+}
+
+@test 'activated' {
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-require-context.md \
+   \[ux1\] \
+   'Get the common name..._Entity: _ENTITY2: Mythical Monkey_UX1: Mythical Monkey_Common name: Mythical Monkey'
+}

data/bats/import-directive-line-continuation.bats

@@ -5,5 +5,5 @@ load 'test_helper'
 @test '' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/import-directive-line-continuation.md \
    --blocks dname \
-   'Stem: U1_Species: Illacme tobini_Genus: Illacme'
+   'Stem: U1_Species: Illacme tobini'
 }

data/bats/import-directive-parameter-symbols.bats

@@ -5,5 +5,5 @@ load 'test_helper'
 @test '' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/import-directive-parameter-symbols.md \
    --blocks dname \
-   'Stem: U1_Species: Illacme tobini_Genus: Illacme_Stem: U2_Species: Hydrodynastes bicinctus_Genus: Hydrodynastes'
+   'Stem: U1_Species: Illacme tobini_Stem: U2_Species: Hydrodynastes bicinctus'
 }

data/bats/import-parameter-symbols.bats

@@ -4,5 +4,5 @@ load 'test_helper'
 
 @test 'Initial values' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/import-parameter-symbols.md \
-   'COMMON_NAME=Tapanuli Orangutan_Command substitution: Tapanuli Orangutan_echo "Command substitution: ${NAMEC}"__Evaluated expression: Tapanuli Orangutan_echo "Evaluated expression: ${NAMEE}"__Raw literal: Tapanuli Orangutan_echo "Raw literal: Tapanuli Orangutan"__Force-quoted literal: Tapanuli Orangutan_echo "Force-quoted literal: ${NAMEQ}"__Variable reference: Tapanuli Orangutan_echo "Variable reference: ${COMMON_NAME}"'
+   'COMMON_NAME=Tapanuli Orangutan_Evaluated expression: Tapanuli Orangutan_echo "Evaluated expression: $(printf %s "$COMMON_NAME")"__Raw literal: Tapanuli Orangutan_echo "Raw literal: Tapanuli Orangutan"__Force-quoted literal: Tapanuli Orangutan_echo "Force-quoted literal: Tapanuli Orangutan"__Variable reference: Tapanuli Orangutan_echo "Variable reference: ${COMMON_NAME}"'
 }

data/bats/options.bats

@@ -30,13 +30,13 @@ load 'test_helper'
 @test 'Options - list blocks' {
   BATS_OUTPUT_FILTER=A
   spec_mde_args_expect --list-blocks-message oname --list-blocks-type 0 examples/colors.md --list-blocks \
-   'load_colors load_colors2  Bash1 Edit1 History1 Link1 Load1 Opts1 Port1 Save1 Vars1'
+   'load_colors load_colors2 Unspecified1 Unknown1 Bash1 Edit-inherited-blocks History1 Link1 Load1 Opts1 Port1 Save1  Vars1'
 }
 
 @test 'Options - list blocks, eval' {
   BATS_OUTPUT_FILTER=A
   spec_mde_args_expect --list-blocks-eval block.oname examples/colors.md --list-blocks \
-   'load_colors load_colors2  Bash1 Edit1 History1 Link1 Load1 Opts1 Port1 Save1 Vars1'
+   'load_colors load_colors2 Unspecified1 Unknown1 Bash1 Edit-inherited-blocks History1 Link1 Load1 Opts1 Port1 Save1  Vars1'
 }
 
 @test 'Options - how' {

data/bin/bmde

@@ -1,4 +1,4 @@
-#!/usr/bin/env bundle exec ruby
+#!/usr/bin/env -S bundle exec ruby
 # frozen_string_literal: true
 
 # encoding=utf-8

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

@@ -0,0 +1,18 @@
+/ No blocks are evaluated at initialization.
+/ When the shell block is activated, the UX block is required.
+```bash :require-a-UX-block +[ux1]
+ENTITY='Mythical Monkey'
+```
+/ Display variables set in the UX block.
+${FIRST}
+${LAST}
+/ Parse and copy the name into variables.
+```ux :[ux1]
+echo:
+  FIRST: '${ENTITY%% *}'
+  LAST: '${ENTITY##* }'
+  FULL_NAME: '$ENTITY'
+init: false
+readonly: true
+```
+@import bats-document-configuration.md

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

@@ -10,7 +10,8 @@ menu_with_inherited_lines: true
 / This block is not visible. Execute to set a new value, displayed by the block above.
 ```ux :(VAR_has_count)
 init: false
-echo: $(basename `pwd` | wc -c)
+echo: >-
+  $(basename `pwd` | sed 's/./&&/g')
 force: false
 name: VAR
 ```

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

@@ -0,0 +1,10 @@
+/ v2025-06-28
+/ Demonstrate using a format key does not inhibit activation of the same block
+/
+```ux
+act: :echo
+echo: '`date`'
+format: 'Date: ${DATE}'
+name: DATE
+```
+@import bats-document-configuration.md

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

@@ -0,0 +1,32 @@
+/ Neither block is evaluated at initialization.
+/ When the first UX block is activated, it is evaluated.
+/ The variable set in the first UX block is available to the second,
+/ which is required by the first, resulting in its evaluation.
+```ux :[ux1] +[ux2] +(ENTITY)
+act: :echo
+echo:
+  UX1: '$ENTITY'
+format: |-
+  Get the common name...
+init: false
+```
+/ The shell required code and the first evaluated UX block are the context
+/ when the the `echo` expressions are being evaluated in the second UX block.
+/ The first evaluated UX block is the context when the `format` value is being expanded.
+```ux :[ux2]
+act: :echo
+echo:
+  UX2: '$UX1'
+  ENTITY2: '$ENTITY'
+format: |-
+  Entity: ${ENTITY}
+  ENTITY2: ${ENTITY2}
+  UX1: ${UX1}
+  Common name: ${UX2}
+init: false
+readonly: true
+```
+```bash :(ENTITY)
+ENTITY='Mythical Monkey'
+```
+@import bats-document-configuration.md

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

@@ -1,7 +1,3 @@
-/ This is an hidden shell block that is required by UX blocks.
-``` :(shell)
-ENTITY='Pongo tapanuliensis,Pongo'
-```
 ```ux +(shell)
 echo: "${ENTITY%%,*}"
 force: true
@@ -24,6 +20,14 @@ echo: "$NAME"
 force: true
 name: NAME2
 ```
+/
+/ This is a hidden shell block that is required by a UX block.
+/ All shell blocks required by a UX block are collected in a sequence
+/ that is the context for the evaluation of the expressions in the UX block.
+``` :(shell)
+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

data/docs/dev/import-directive-line-continuation.md

@@ -2,5 +2,4 @@
         __PS_STEM_SPECIES:q='Illacme tobini' \
         __PS_STEM_GENUS:q=Illacme \
         PS_STEM=U1
-Genus: ${__U1_GENUS}
 @import bats-document-configuration.md

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

@@ -1,9 +1,7 @@
 / use MDE 3.3.0 import parameter symbols
 /
 @import ./import/parameter-symbols.md   __PS_STEM_SPECIES:q='Illacme tobini'   __PS_STEM_GENUS:q=Illacme   PS_STEM=U1
-Genus: ${__U1_GENUS}
 /
 @import ./import/parameter-symbols.md   __PS_STEM_SPECIES:q='Hydrodynastes bicinctus'   __PS_STEM_GENUS:q=Hydrodynastes   PS_STEM=U2
-Genus: ${__U2_GENUS}
 /
 @import ./bats-document-configuration.md

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

@@ -1,8 +1,10 @@
-**Command substitution:** `NAMEC`
-```bash
-echo "Command substitution: NAMEC"
-```
-
+/ 2025-11-13 the name of the variable generated
+/ changes on every load is not predictable
+/**Command substitution:** `NAMEC`
+/```bash
+/echo "Command substitution: NAMEC"
+/```
+/
 **Evaluated expression:** `NAMEE`
 ```bash
 echo "Evaluated expression: NAMEE"

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

@@ -2,5 +2,13 @@
 echo: Tapanuli Orangutan
 name: COMMON_NAME
 ```
-@import import-parameter-symbols-template.md   NAMEC:c='printf %s "$COMMON_NAME"'   NAMEE:e=$COMMON_NAME   NAMEL="Tapanuli Orangutan"   NAMEQ:q="Tapanuli Orangutan"   NAMEV:v=COMMON_NAME
-@import bats-document-configuration.md
+@import import-parameter-symbols-template.md \
+  NAMEC:cq='printf %s "$COMMON_NAME"' \
+  NAMEE:eq=$COMMON_NAME \
+  NAMEL="Tapanuli Orangutan" \
+  NAMEQ:qq="Tapanuli Orangutan" \
+  NAMEV:vq=COMMON_NAME
+@import bats-document-configuration.md
+```opts :(document_opts)
+dump_inherited_lines: false
+```

data/docs/docker-testing.md

@@ -0,0 +1,115 @@
+# Docker Testing Environment
+
+This document describes how to use the Docker testing environment for `markdown_exec`.
+
+## Overview
+
+The `Dockerfile.ruby-3.3-spec` provides a complete testing environment with:
+- Ruby 3.3 on Debian Bookworm
+- All build dependencies
+- Git submodules initialized (BATS testing framework)
+- Development tools and aliases
+- Pre-configured BATS test setup
+
+## Building the Image
+
+```bash
+docker build -f Dockerfile.test -t markdown-exec-test .
+```
+
+You can specify a different Git branch to test:
+
+```bash
+docker build -f Dockerfile.test --build-arg GIT_BRANCH=develop -t markdown-exec-test .
+```
+
+## Running Tests
+
+### Run all BATS tests
+
+```bash
+docker run --rm markdown-exec-test bats test/
+```
+
+### Run specific test file
+
+```bash
+docker run --rm markdown-exec-test bats test/options.bats
+```
+
+### Run with verbose output
+
+```bash
+docker run --rm markdown-exec-test batsv test/
+```
+
+The container includes the `batsv` alias for verbose BATS output.
+
+## Interactive Development
+
+### Enter the container interactively
+
+```bash
+docker run --rm -it markdown-exec-test bash
+```
+
+Once inside, you have access to:
+- `bats` - BATS test runner (available in PATH)
+- `batsv` - Verbose BATS runner (alias)
+- `be` - Bundle exec alias
+- `bmde` - Bin/bmde alias
+- `ll` - Enhanced ls alias
+
+### Mount local directory for development
+
+To work with your local code changes:
+
+```bash
+docker run --rm -it -v "$(pwd)":/markdown_exec markdown-exec-test bash
+```
+
+**Note:** The container clones the repo by default. When mounting your local directory, you may need to adjust paths or rebuild dependencies.
+
+## Running Minitest
+
+```bash
+docker run --rm markdown-exec-test bundle exec rake minitest
+```
+
+## Container Details
+
+- **Working Directory**: `/markdown_exec`
+- **Base Image**: `ruby:3.3-bookworm`
+- **BATS Location**: `/markdown_exec/test/bats/bin/bats` (symlinked to `/usr/local/bin/bats`)
+- **Test Helpers**: Located in `/markdown_exec/test/test_helper/`
+
+## Troubleshooting
+
+### Submodules not initialized
+
+If you encounter issues with BATS submodules, the Dockerfile should handle this automatically. If problems persist:
+
+```bash
+docker run --rm -it markdown-exec-test bash
+cd /markdown_exec
+git submodule update --init --recursive
+```
+
+### Missing test files
+
+The container creates required directories and test files. If tests fail due to missing files, check that the Dockerfile build completed successfully.
+
+### Running tests with local changes
+
+For testing local changes without rebuilding:
+
+1. Build the base image once
+2. Use volume mounting to overlay your local code
+3. Re-run bundle install if dependencies changed:
+
+```bash
+docker run --rm -it -v "$(pwd)":/markdown_exec markdown-exec-test bash
+bundle install
+bats test/
+```
+

data/docs/tab-completion.md

@@ -0,0 +1,33 @@
+# Tab Completion
+
+## Install tab completion
+
+Append a command to load the completion script to your shell configuration file. `mde` must be executable for the command to be composed correctly.
+
+```bash
+echo "source $(mde --pwd)/bin/tab_completion.sh" >> ~/.bash_profile
+```
+
+## Behavior
+
+Press tab for completions appropriate to the current input.
+`mde <...> <prior word> <current word><TAB>`
+
+Completions are calculated based on the current word and the prior word. 
+1. If the current word starts with `-`, present matching options, eg `--version` for the current word `--v`.
+2. Else, if the current word is empty and the prior word is an option that takes an argument, present the type of the argument, eg `.BOOL.` for the option `--user-must-approve`.
+3. Else, if the current word is the type of argument, from the rule above, present the default value for the option. e.g. `1` for the type `.BOOL.` for the option `--user-must-approve`.
+4. Else, if the current word is non-empty, list matching files and folders.
+
+## Example Completions
+
+In the table below, tab is indicated by `!`
+| Input | Completions |
+| :--- | :--- |
+| `mde !` | local files and folders |
+| `mde -!` | all options |
+| `mde --!` | all options |
+| `mde --v!` | `mde --version` |
+| `mde --user-must-approve !` | `mde --user-must-approve .BOOL.`|
+| `mde --user-must-approve .BOOL.!` | `mde --user-must-approve 1` |
+

data/examples/colors.md

@@ -1,27 +1,19 @@
 # Demo configuring options
-
+/ v2025-09-30
 ::: These Opts blocks set the color for all elements.
-
-<https://en.wikipedia.org/wiki/Complementary_colors#/media/File:RGB_color_wheel.svg>
-
-/ ff0000 red - exception text
-/ ff7f00 orange - warning text
-/ ffff00 yellow - notification text
-/ 7fff00 chartreuse green - output frame
-/ 00ff00 green - prompt
-/ 00ff7f spring green - input frame
-/ 00ffff cyan - menu text
-/ 007fff azure - menu frame
-/ 0000ff blue
-/ 7f00ff violet - opts frame
-/ ff00ff magenta - opts text
-/ ff007f rose - exception frame
-
+/ blue    fg_rgbh_00_00_FF
+/ green   fg_rgbh_00_FF_00
+/ indigo  fg_rgbh_4B_00_82
+/ orange  fg_rgbh_FF_7F_00
+/ red     fg_rgbh_FF_00_00
+/ violet  fg_rgbh_94_00_D3
+/ yellow  fg_rgbh_FF_FF_00
 ```opts :load_colors
 exception_color_detail: fg_rgbh_1f_00_7f
 exception_color_name: fg_rgbh_1f_00_00
 execution_report_preview_frame_color: fg_rgbh_7f_1f_00
 menu_bash_color: fg_rgbh_00_c0_c0
+menu_block_color: fg_rgbh_47_ce_eb
 menu_chrome_color: fg_rgbh_40_c0_c0
 menu_divider_color: fg_rgbh_80_d0_c0
 menu_edit_color: fg_rgbh_e0_e0_20
@@ -44,11 +36,13 @@ script_preview_frame_color: fg_rgbh_7f_1f_00
 warning_color: fg_rgbh_1f_7f_00
 ```
 
+/ more green, less blue
 ```opts :load_colors2
 exception_color_detail: fg_rgbh_ff_00_7f
 exception_color_name: fg_rgbh_ff_00_00
 execution_report_preview_frame_color: fg_rgbh_7f_ff_00
 menu_bash_color: fg_rgbh_00_c0_c0
+menu_block_color: fg_rgbh_47_fe_bb
 menu_chrome_color: fg_rgbh_40_c0_c0
 menu_divider_color: fg_rgbh_80_d0_c0
 menu_edit_color: fg_rgbh_e2_e2_20
@@ -72,12 +66,18 @@ script_preview_frame_color: fg_rgbh_7f_ff_00
 warning_color: fg_rgbh_ff_7f_00
 ```
 
-::: Example blocks
+::: Divider color
+
+::: Fenced code blocks of different types
+Each block has a name. Its name is decorated according to the type of the block.
+``` :Unspecified1
 ```
+```unknown :Unknown1
 ```
 ```bash :Bash1
 ```
-```edit :Edit1
+/ Chrome decoration
+```edit :Edit-inherited-blocks
 ```
 ```history :History1
 ```
@@ -85,20 +85,22 @@ warning_color: fg_rgbh_ff_7f_00
 ```
 ```load :Load1
 ```
+/ Note decoration
+A Note
+/ Opts decoration
 ```opts :Opts1
 ```
 ```port :Port1
 ```
+/ Save decoration
 ```save :Save1
 ```
-```vars :Vars1
+/ Task decoration
+[ ] Task
+/ UX decoration
+```ux
+format: UX-1
 ```
-[ ] Task1
-
-/ blue;    fg_rgbh_00_00_FF
-/ green;   fg_rgbh_00_FF_00
-/ indigo;  fg_rgbh_4B_00_82
-/ orange;  fg_rgbh_FF_7F_00
-/ red;     fg_rgbh_FF_00_00
-/ violet;  fg_rgbh_94_00_D3
-/ yellow;  fg_rgbh_FF_FF_00
+/ Vars decoration
+```vars :Vars1
+```