markdown_exec 3.4.0 → 3.5.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec9a613148346890f4db46f3f5bdcade05b8e2221e92402c431fa9a359556e1e
-  data.tar.gz: 05d16eaf1ac5d433c8da62513da88159313e3b2898d36d7dfa0d71061c83a97b
+  metadata.gz: 4a4c6bcbb464222e907cb93cc549ef294d45b83f0f8be5e88e603b87c64eb7a4
+  data.tar.gz: dfce2b71eb6c954e3d438b6036b6543da7bcfe63178ca56971ddb198f49852db
 SHA512:
-  metadata.gz: 9dcec89e521fc194eb329b36dc83068a11215186c5e3e5447485000a40c8e75f8bdabd10824af34b9ff90fee3f0899d5bb0f82f76f4ffa3a0a950d213585e6a5
-  data.tar.gz: 06b8fb5443b026e628fd60962bd9c7abbccd78824ea0d0b001f27b4608cc0cb147fff6fa00eac5de3712ed97f76d50296b35368675478992e06b28db06b29dfc
+  metadata.gz: c7b2076de902483e3f2362b8319d99f1876c7f41e7ffd1815e92278803d55776f700df721dc16700064c890c7c48628657ef2bf4003ba989b7c6eee1c27a9088
+  data.tar.gz: ed8705a9687dc56cbef235fe0821065653852d5b1e1c05293a9ea53baf08a7a12c24fdc5e909e9dd04047378d664ddb0b8e7d644e38d54c753ef1a470138ce60

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [3.5.0] - 2025-11-13
+
+### Added
+
+- MP4 with demonstration of Bash "trap" command.
+- Type casting for tokens in imported documents.
+- Default color for fenced code blocks per type.
+- Shell blocks can require UX blocks.
+- Common markdown patterns for text decorations.
+
+### Changed
+
+- README.md
+
 ## [3.4.0] - 2025-09-16
 
 ### Added

data/Gemfile

@@ -12,6 +12,7 @@ gem 'erb'
 gem 'irb'
 gem 'mocha', require: false
 gem 'minitest', require: false
+gem 'minitest-reporters', require: false
 gem 'pry-nav'
 gem 'pry-stack_explorer'
 gem 'railties'

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    markdown_exec (3.4.0)
+    markdown_exec (3.5.0)
       clipboard (~> 1.3.6)
       open3 (~> 0.1.1)
       optparse (~> 0.1.1)
@@ -37,6 +37,7 @@ GEM
       minitest (>= 5.1)
       mutex_m
       tzinfo (~> 2.0)
+    ansi (1.5.0)
     ast (2.4.2)
     base64 (0.2.0)
     bigdecimal (3.1.8)
@@ -98,6 +99,11 @@ GEM
       nokogiri (>= 1.12.0)
     method_source (1.1.0)
     minitest (5.24.1)
+    minitest-reporters (1.7.1)
+      ansi
+      builder
+      minitest (>= 5.0)
+      ruby-progressbar
     mocha (2.4.5)
       ruby2_keywords (>= 0.0.5)
     mutex_m (0.2.0)
@@ -227,6 +233,7 @@ DEPENDENCIES
   irb
   markdown_exec!
   minitest
+  minitest-reporters
   mocha
   pry-nav
   pry-stack_explorer

data/README.md

@@ -1,150 +1,271 @@
 # MarkdownExec
 
-Interactively select and execute fenced code blocks in markdown files. Build complex scripts by naming and requiring blocks. Log resulting scripts and output. Re-run scripts.
-
-* Code blocks may be named. Named blocks can be required by other blocks.
-
-* The user-selected code block, and all required blocks, are arranged into a script in the order they appear in the markdown file. The script can be presented for approval prior to execution.
-
-* Executed scripts can be saved. Saved scripts can be listed, selected, and executed.
-
-* Output from executed scripts can be saved.
-
-## Screenshots
-
-### Select a file
-
-![Select a file](/assets/select_a_file.png)
-
-### Select a block
-
-![Select a block](/assets/select_a_block.png)
-
-### Approve code
-
-![Approve code](/assets/approve_code.png)
-
-### Output
-
-![Output of execution](/assets/output_of_execution.png)
-
-### Example blocks
-
-![Example blocks](/assets/example_blocks.png)
+[![MarkdownExec For Interactive Bash Instruction](https://raw.githubusercontent.com/fareedst/markdown_exec/main/demo/trap.demo1.gif)](https://raw.githubusercontent.com/fareedst/markdown_exec/main/demo/trap.demo1.mp4)
+
+*Click the GIF above to view the full video with audio (MP4)*
+
+Transform static markdown into interactive, executable workflows. Build complex scripts with named blocks, interactive forms, cross-document navigation, and template systems.
+
+## Key Features
+
+### Interactive Code Execution
+- **Named Blocks**: Create reusable code blocks with dependencies
+- **Block Requirements**: Automatically include required blocks in execution order
+- **Interactive Selection**: Choose blocks from intuitive menus
+- **Script Approval**: Review generated scripts before execution
+
+### UX Blocks - Interactive Forms
+- **Variable Input**: Create interactive forms for user input
+- **Validation**: Built-in regex validation with custom transforms
+- **Dynamic Menus**: Selection from allowed values or command output
+- **Auto-initialization**: Set values from environment, commands, or defaults
+- **Dependencies**: Chain UX blocks with complex relationships
+
+### Cross-Document Navigation
+- **Link Blocks**: Navigate between markdown files seamlessly
+- **Variable Passing**: Share data between documents
+- **Inherited Context**: Maintain state across document boundaries
+- **HyperCard-style Navigation**: Create interactive document stacks
+
+### Template System & Imports
+- **Import Directives**: Include content from other files with `@import`
+- **Parameter Substitution**: Replace variables in imported content
+- **Shell Expansions**: Use `${variable}` and `$(command)` syntax throughout documents
+- **Dynamic Content**: Generate content based on user selections
+
+### Advanced Block Types
+- **Shell Blocks**: Execute bash shells
+- **UX Blocks**: Interactive forms with validation, transforms, and dynamic behavior
+- **Vars Blocks**: Define variables in YAML format
+- **Opts Blocks**: Configure document behavior and appearance
+- **Link Blocks**: Cross-document navigation and variable passing
+
+### State Management
+- **Script Persistence**: Save and replay executed scripts
+- **Output Logging**: Capture and review execution results
+- **State Inheritance**: Manage context across sessions
+- **Configuration**: Flexible options via environment, files, or CLI
 
 ## Installation
 
-Install:
-    $ gem install markdown_exec
+```bash
+gem install markdown_exec
+```
 
-## Usage
+## Quick Start
 
-### Help
+### Interactive Mode (Recommended)
+```bash
+mde                    # Process README.md in current folder
+mde my-document.md     # Process specific markdown file
+mde .                  # Select from markdown files in current folder
+```
 
-::: `mde --help`
+### Command Line Mode
+```bash
+mde my-document.md my-block    # Execute specific block directly
+mde --list-blocks              # List all available blocks
+mde --list-docs                # List all markdown documents
+```
 
-Displays help information.
+## Interactive Features
 
-### Basic
+### UX Blocks - Interactive Forms
 
-::: `mde`
+Create interactive forms that prompt users for input:
 
-Process `README.md` file in the current folder. Displays all the blocks in the file and allows you to select using [up], [down], and [return].
+<pre><code>```ux
+name: USER_NAME
+prompt: Enter your name
+init: Guest
+```
+</code></pre>
+
+<pre><code>```ux
+name: ENVIRONMENT
+allow:
+  - development
+  - staging
+  - production
+prompt: Select environment
+```
+</code></pre>
 
-::: `mde my.md` or `mde -f my.md`
+<pre><code>```ux
+name: EMAIL
+prompt: Enter email address
+validate: '(?<local>[^@]+)@(?<domain>[^@]+)'
+transform: '%{local}@%{domain}'
+```
+</code></pre>
 
-Select a block to execute from `my.md`.
+### Cross-Document Navigation
 
-::: `mde my.md myblock`
+Navigate between documents while maintaining context:
 
-Execute the block named `myblock` from `my.md`.
+<pre><code>```link
+file: next-document.md
+vars:
+  current_user: ${USER_NAME}
+  environment: ${ENVIRONMENT}
+```
+</code></pre>
 
-::: `mde .` or `mde -p .`
+### Template System
 
-Select a markdown file in the current folder. Select a block to execute from that file.
+Use imports with parameter substitution:
 
-### Report documents and blocks
+```
+@import template.md USER_NAME=John ENVIRONMENT=production
+```
+</code></pre>
 
-::: `mde --list-blocks`
+### Block Dependencies
 
-List all blocks in the all the markdown documents in the current folder.
+Create complex workflows with automatic dependency resolution:
 
-::: `mde --list-docs`
+<pre><code>```bash :deploy +setup +test +deploy
+echo "Deploying to ${ENVIRONMENT}"
+```
+</code></pre>
 
-List all markdown documents in the current folder.
+<pre><code>```bash :setup
+echo "Setting up environment"
+```
+</code></pre>
 
-### Configuration
+<pre><code>```bash :test
+echo "Running tests"
+```
+</code></pre>
 
-::: `mde --list-default-env` or `mde --list-default-yaml`
+## Advanced Usage
 
-List default values that can be set in configuration file, environment, and command line.
+### Configuration
 
-::: `mde -0`
+```
+# Environment variables
+export MDE_SAVE_EXECUTED_SCRIPT=1
+export MDE_USER_MUST_APPROVE=1
 
-Show current configuation values that will be applied to the current run. Does not interrupt processing.
+# Configuration file (.mde.yml)
+save_executed_script: true
+user_must_approve: true
 
-### Save scripts
+# Command line
+mde --save-executed-script 1 --user-must-approve 1
+```
 
-::: `mde --save-executed-script 1`
+### Script Management
 
-Save executed script in saved script folder.
+```bash
+mde --save-executed-script 1      # Save executed scripts
+mde --list-recent-scripts         # List saved scripts
+mde --select-recent-script        # Execute saved script
+mde --save-execution-output 1     # Save execution output
+```
 
-::: `mde --list-recent-scripts`
+## Block Types Reference
 
-List recent saved scripts in saved script folder.
+### Shell Blocks
+<pre><code>```bash
+echo "Hello World"
+```
+</code></pre>
 
-::: `mde --select-recent-script`
+### UX Blocks (Interactive Forms)
+<pre><code>```ux
+name: USER_NAME
+prompt: Enter your name
+init: Guest
+```
+</code></pre>
+
+<pre><code>```ux
+name: ENVIRONMENT
+allow:
+  - development
+  - staging
+  - production
+act: :allow
+```
+</code></pre>
 
-Select and execute a recently saved script in saved script folder.
+<pre><code>```ux
+name: CURRENT_DIR
+exec: basename $(pwd)
+transform: :chomp
+```
+</code></pre>
 
-### Save output
+<pre><code>```ux
+name: EMAIL
+prompt: Enter email address
+validate: '(?<local>[^@]+)@(?<domain>[^@]+)'
+transform: '%{local}@%{domain}'
+```
+</code></pre>
 
-::: `mde --save-execution-output 1`
+### Variable Blocks
+<pre><code>```vars
+DATABASE_URL: postgresql://localhost:5432/myapp
+DEBUG: true
+```
+</code></pre>
 
-Save execution output in saved output folder.
+### Link Blocks (Cross-Document Navigation)
+<pre><code>```link
+file: next-page.md
+vars:
+  current_user: ${USER_NAME}
+```
+</code></pre>
+
+### Data Blocks (YAML)
+<pre><code>```yaml
+users:
+  - name: John
+    role: admin
+  - name: Jane
+    role: user
+```
+</code></pre>
 
-## Behavior
+### Import Directives
+```
+@import template.md USER_NAME=John ENVIRONMENT=production
+```
 
-* If no file and no folder are specified, blocks within `./README.md` are presented.
-* If a file is specified, its blocks are presented.
-* If a folder is specified, its files are presented. When a file is selected, its blocks are presented.
+### Options Blocks
+<pre><code>```opts :(document_opts)
+user_must_approve: true
+save_executed_script: true
+menu_ux_row_format: 'DEFAULT %{name} = ${%{name}}'
+```
+</code></pre>
 
 ## Configuration
 
 ### Environment Variables
-
-When executed, `mde` reads the current environment.
-* Configuration in current and children shells, e.g. `export MDE_SAVE_EXECUTED_SCRIPT=1`.
-* Configuration for the current command, e.g. `MDE_SAVE_EXECUTED_SCRIPT=1 mde`.
+<pre><code>```bash
+export MDE_SAVE_EXECUTED_SCRIPT=1
+export MDE_USER_MUST_APPROVE=1
+```
+</code></pre>
 
 ### Configuration Files
+<pre><code>```yaml
+# .mde.yml
+save_executed_script: true
+user_must_approve: true
+menu_with_inherited_lines: true
+```
+</code></pre>
 
-* Configuration in all shells, e.g. environment variables set in your user's `~/.bashrc` or `~/.bash_profile` files.
-* Configuration in the optional file `.mde.yml` in the current folder. .e.g. `save_executed_script: true`
-* Configuration in a YAML file and read while parsing the inputs, e.g. `--config my_path/my_file.yml`
-
-### Program Arguments
-
-* Configuration in command options, e.g. `mde --save-executed-script 1`
-
-## Representing boolean values
-
-Boolean values expressed as strings are interpreted as:
-| String | Boolean |
-| :---: | :---: |
-| *empty string* | False |
-| `0` | False |
-| `1` | True |
-| *anything else* | True |
-
-E.g. `opt1=1` will set option `opt1` to True.
-
-Boolean options configured with environment variables:
-- Set to `1` or non-empty value to save executed scripts; empty or `0` to disable saving.
-  e.g. `export MDE_SAVE_EXECUTED_SCRIPT=1`
-  e.g. `export MDE_SAVE_EXECUTED_SCRIPT=`
-- Specify variable on command line.
-  e.g. `MDE_SAVE_EXECUTED_SCRIPT=1 mde`
+### Command Line Options
+```bash
+mde --save-executed-script 1 --user-must-approve 1 --config my-config.yml
+```
 
 ## Tab Completion
 
@@ -152,7 +273,7 @@ Boolean options configured with environment variables:
 
 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 :()
+```bash
 echo "source $(mde --pwd)/bin/tab_completion.sh" >> ~/.bash_profile
 ```
 
@@ -179,29 +300,54 @@ In the table below, tab is indicated by `!`
 | `mde --user-must-approve !` | `mde --user-must-approve .BOOL.`|
 | `mde --user-must-approve .BOOL.!` | `mde --user-must-approve 1` |
 
-## Example Blocks
+## Example: Interactive Workflow
 
-When prompted, select either the `awake` or `asleep` block.
+This example demonstrates a complete interactive workflow with UX blocks, dependencies, and cross-document navigation:
 
-``` :(day)
-export TIME=early
+### Step 1: User Input
+<pre><code>```ux :user-setup
+name: USER_NAME
+prompt: Enter your name
+init: Guest
 ```
-
-``` :(night)
-export TIME=late
+</code></pre>
+
+<pre><code>```ux :environment
+name: ENVIRONMENT
+allow:
+  - development
+  - staging
+  - production
+prompt: Select environment
 ```
+</code></pre>
 
-``` :awake +(day) +(report)
-export ACTIVITY=awake
+### Step 2: Automated Setup
+Prompts the user for both values and generates output.
+<pre><code>```bash :setup +user-setup +environment
+echo "Setting up for user: ${USER_NAME}"
+echo "Environment: ${ENVIRONMENT}"
 ```
-
-``` :asleep +(night) +(report)
-export ACTIVITY=asleep
+</code></pre>
+
+### Step 3: Conditional Logic
+<pre><code>```bash :deploy +setup
+if [ "${ENVIRONMENT}" = "production" ]; then
+  echo "Deploying to production with extra safety checks"
+else
+  echo "Deploying to ${ENVIRONMENT}"
+fi
 ```
-
-``` :(report)
-echo "$TIME -> $ACTIVITY"
+</code></pre>
+
+### Step 4: Cross-Document Navigation
+<pre><code>```link
+file: next-workflow.md
+vars:
+  user: ${USER_NAME}
+  env: ${ENVIRONMENT}
 ```
+</code></pre>
 
 # Testing
 

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-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/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-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