markdown_exec 3.5.1 → 3.6.0

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/block-type-ux-transform.md

@@ -4,7 +4,7 @@
 exec: basename $(pwd)
 name: Var0
 ```
-$(echo -n "$Var0" | hexdump -v -e '16/1 " %02x"')
+$(print_bytes "$Var0")
 :::
 **With validate and transform, output has no newline.**
 ```ux :[document_ux_transform_1]
@@ -13,7 +13,7 @@ name: Var1
 transform: '%{name}'
 validate: (?<name>.+)
 ```
-$(echo -n "$Var1" | hexdump -v -e '16/1 " %02x"')
+$(print_bytes "$Var1")
 :::
 **With transform `:chomp`, output has no newline.**
 ```ux :[document_ux_transform_2]
@@ -21,7 +21,7 @@ exec: basename $(pwd)
 name: Var2
 transform: :chomp
 ```
-$(echo -n "$Var2" | hexdump -v -e '16/1 " %02x"')
+$(print_bytes "$Var2")
 :::
 **With transform `:upcase`, output is in upper case w/ newline.**
 ```ux :[document_ux_transform_3]
@@ -29,8 +29,9 @@ exec: basename $(pwd)
 name: Var3
 transform: :upcase
 ```
-$(echo -n "$Var3" | hexdump -v -e '16/1 " %02x"')
+$(print_bytes "$Var3")
 @import bats-document-configuration.md
+@import print_bytes.md
 ```opts :(document_opts)
 divider4_collapsible: false
 screen_width: 80

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/print_bytes.md

@@ -0,0 +1,3 @@
+```bash :(document_shell)
+print_bytes () { printf %s "$1" | hexdump -v -e '16/1 " %02x"' ; }
+```

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/shebang.md

@@ -0,0 +1,6 @@
+#!/usr/bin/env -S bin/bmde
+Demonstrate opening the document via Shebang.
+```bash :print-test
+echo Test
+```
+@import bats-document-configuration.md

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/docker-testing.md

@@ -83,6 +83,11 @@ docker run --rm markdown-exec-test bundle exec rake minitest
 - **BATS Location**: `/markdown_exec/test/bats/bin/bats` (symlinked to `/usr/local/bin/bats`)
 - **Test Helpers**: Located in `/markdown_exec/test/test_helper/`
 
+## Related Documentation
+
+- [Option Documentation Process](option-documentation-process.md) - Process for documenting options
+- [Option Documentation Tasks](option-documentation-tasks.md) - Task list for documentation
+
 ## Troubleshooting
 
 ### Submodules not initialized

data/docs/execution-control.md

@@ -0,0 +1,384 @@
+# Execution Control Options
+
+This document describes options that control how scripts are executed, including approval requirements, execution modes, and flow control.
+
+## Overview
+
+Execution control options allow you to:
+- Require user approval before executing scripts
+- Control where scripts execute (current terminal vs. new window)
+- Pause execution flow for review
+- Prevent accidental re-execution of the same block
+- Display scripts before execution
+
+These options provide safety and control mechanisms for script execution, especially useful when working with potentially destructive operations or when you need to review scripts before they run.
+
+## Configuration Options
+
+### `user-must-approve` / `-q`
+
+- **Option**: `user_must_approve`
+- **Long Name**: `--user-must-approve`
+- **Short Name**: `-q`
+- **Environment Variable**: `MDE_USER_MUST_APPROVE`
+- **Argument**: `BOOL`
+- **Default**: `false`
+- **Description**: Requires user approval before executing a script
+
+When enabled, displays the complete generated script (including all required dependencies) and prompts the user for confirmation before execution. This is a critical safety feature for reviewing scripts before they run.
+
+**Usage:**
+```bash
+mde my-document.md --user-must-approve 1
+mde my-document.md -q 1
+```
+
+**Examples:**
+```bash
+# Require approval for all executions
+mde README.md -b deploy --user-must-approve 1
+
+# Set via environment variable
+export MDE_USER_MUST_APPROVE=1
+mde README.md -b deploy
+
+# In configuration file
+# .mde.yml
+user_must_approve: true
+```
+
+**Behavior:**
+- The full script (including all required dependencies) is displayed
+- User is prompted with "Process?" (configurable via `prompt_approve_block`)
+- Execution only proceeds if user confirms (Yes/No)
+- Works in both interactive menu mode and command-line mode
+- When combined with `output_script`, the script is displayed regardless
+
+**Related Options:**
+- `output_script`: Display script before execution (doesn't require approval)
+- `prompt_approve_block`: Customize the approval prompt text
+
+### `execute-in-own-window` / `-w`
+
+- **Option**: `execute_in_own_window`
+- **Long Name**: `--execute-in-own-window`
+- **Short Name**: `-w`
+- **Environment Variable**: `MDE_EXECUTE_IN_OWN_WINDOW`
+- **Argument**: `BOOL`
+- **Default**: `false`
+- **Description**: Execute script in own window
+
+When enabled, executes the script in a new terminal window (iTerm on macOS) instead of the current terminal. Useful for long-running scripts or when you want to keep the main terminal free for other operations.
+
+**Usage:**
+```bash
+mde my-document.md --execute-in-own-window 1
+mde my-document.md -w 1
+```
+
+**Examples:**
+```bash
+# Execute in new window
+mde README.md -b long-running-task -w 1
+
+# Combine with approval
+mde README.md -b deploy -q 1 -w 1
+
+# Set via environment variable
+export MDE_EXECUTE_IN_OWN_WINDOW=1
+mde README.md -b deploy
+```
+
+**Requirements:**
+- Requires `execute_command_format` to be configured (defaults to AppleScript for iTerm on macOS)
+- Script and output files must be saved before execution (handled automatically)
+- Window title includes timestamp, document name, and block name
+
+**Window Title Format:**
+The window title uses `execute_command_title_time_format` (default: `"%T"`) and includes:
+- Timestamp (formatted)
+- Document filename
+- Block name
+
+**Customization:**
+For other terminal emulators or platforms, customize `execute_command_format` to use different commands or scripts.
+
+**Related Options:**
+- `execute_command_format`: AppleScript or command template for window execution
+- `execute_command_title_time_format`: Time format for window title
+
+### `output-script`
+
+- **Option**: `output_script`
+- **Long Name**: `--output-script`
+- **Environment Variable**: `MDE_OUTPUT_SCRIPT`
+- **Argument**: `BOOL`
+- **Default**: `false`
+- **Description**: Display script prior to execution
+
+When enabled, displays the generated script (including all required dependencies) before execution, even if `user_must_approve` is disabled. Useful for debugging, reviewing what will be executed, or logging.
+
+**Usage:**
+```bash
+mde my-document.md --output-script 1
+```
+
+**Examples:**
+```bash
+# Display script before execution
+mde README.md -b deploy --output-script 1
+
+# Combine with approval for review
+mde README.md -b deploy --output-script 1 --user-must-approve 1
+
+# Set via environment variable
+export MDE_OUTPUT_SCRIPT=1
+mde README.md -b deploy
+```
+
+**Behavior:**
+- Script is displayed with frame markers (configurable via `script_preview_head` and `script_preview_tail`)
+- Includes all required dependencies in execution order
+- Execution proceeds automatically (unless `user_must_approve` is also enabled)
+- Useful for debugging or understanding what will execute
+
+**Related Options:**
+- `user_must_approve`: Require approval after displaying script
+- `script_preview_head`: Text displayed before script preview
+- `script_preview_tail`: Text displayed after script preview
+- `script_preview_frame_color`: Color for preview frame
+
+### `debounce-execution`
+
+- **Option**: `debounce_execution`
+- **Environment Variable**: `MDE_DEBOUNCE_EXECUTION`
+- **Argument**: `BOOL`
+- **Default**: `true`
+- **Description**: Whether to prompt before re-executing the same block multiple times
+
+When enabled, prevents accidental re-execution of the same block by prompting for confirmation if you try to execute a block that was just executed. This helps prevent accidental duplicate executions.
+
+**Usage:**
+```bash
+# Via environment variable (no CLI flag)
+export MDE_DEBOUNCE_EXECUTION=0  # Disable
+export MDE_DEBOUNCE_EXECUTION=1  # Enable (default)
+```
+
+**Examples:**
+```bash
+# Disable debouncing (allow immediate re-execution)
+export MDE_DEBOUNCE_EXECUTION=0
+mde README.md
+
+# Enable debouncing (default behavior)
+export MDE_DEBOUNCE_EXECUTION=1
+mde README.md
+```
+
+**Behavior:**
+- When enabled, if you select the same block that was just executed, you're prompted with "Repeat this block?" (configurable via `prompt_debounce`)
+- Blocks executed from CLI (via `--block-name`) bypass debouncing
+- Debounce state is reset when navigating back or selecting different menu options
+- Only applies to interactive menu selections, not CLI-specified blocks
+
+**Related Options:**
+- `prompt_debounce`: Customize the debounce prompt text
+
+### `pause-after-script-execution`
+
+- **Option**: `pause_after_script_execution`
+- **Long Name**: `--pause-after-script-execution`
+- **Environment Variable**: `MDE_PAUSE_AFTER_SCRIPT_EXECUTION`
+- **Argument**: `BOOL`
+- **Default**: `false`
+- **Description**: Whether to pause after manually executing a block and before the next menu
+
+When enabled, pauses execution after a block completes and before displaying the next menu. Useful for reviewing execution results before continuing.
+
+**Usage:**
+```bash
+mde my-document.md --pause-after-script-execution 1
+```
+
+**Examples:**
+```bash
+# Pause after execution
+mde README.md -b deploy --pause-after-script-execution 1
+
+# Set via environment variable
+export MDE_PAUSE_AFTER_SCRIPT_EXECUTION=1
+mde README.md -b deploy
+
+# In configuration file
+# .mde.yml
+pause_after_script_execution: true
+```
+
+**Behavior:**
+- After script execution completes, displays the prompt (configurable via `prompt_after_script_execution`, default: "\nContinue?")
+- User must press Enter or respond to continue
+- Useful for reviewing execution output before the menu reappears
+- Works in interactive mode
+
+**Related Options:**
+- `prompt_after_script_execution`: Customize the pause prompt text
+- `prompt_color_after_script_execution`: Color for the pause prompt
+
+### `execute-command-format`
+
+- **Option**: `execute_command_format`
+- **Environment Variable**: `MDE_EXECUTE_COMMAND_FORMAT`
+- **Default**: AppleScript template for iTerm
+- **Description**: AppleScript to execute a command in a window
+
+Template string used when `execute_in_own_window` is enabled. The default is an AppleScript that creates a new iTerm window and executes the script there.
+
+**Usage:**
+```bash
+# Set via environment variable
+export MDE_EXECUTE_COMMAND_FORMAT='your-custom-template'
+```
+
+**Default Template:**
+The default template uses AppleScript to:
+1. Create a new iTerm window
+2. Set environment variables for script and output files
+3. Change to the working directory
+4. Set the window title
+5. Execute the script with output redirected to a log file
+
+**Customization:**
+For other terminal emulators or platforms, customize this template to use different commands. The template supports format placeholders:
+- `%{batch_index}`: Batch index
+- `%{home}`: Working directory
+- `%{output_filespec}`: Output file path
+- `%{script_filespec}`: Script file path
+- `%{started_at}`: Execution start time
+- `%{document_filename}`: Document filename
+- `%{block_name}`: Block name
+- `%{rest}`: Additional arguments
+
+**Related Options:**
+- `execute_in_own_window`: Enable window execution
+- `execute_command_title_time_format`: Time format for window title
+
+### `execute-command-title-time-format`
+
+- **Option**: `execute_command_title_time_format`
+- **Environment Variable**: `MDE_EXECUTE_COMMAND_TITLE_TIME_FORMAT`
+- **Default**: `"%T"`
+- **Description**: Format for time in window title
+
+Time format string used in the window title when `execute_in_own_window` is enabled. Uses Ruby `Time#strftime` format.
+
+**Usage:**
+```bash
+# Set via environment variable
+export MDE_EXECUTE_COMMAND_TITLE_TIME_FORMAT="%H:%M:%S"
+```
+
+**Examples:**
+```bash
+# 24-hour time
+export MDE_EXECUTE_COMMAND_TITLE_TIME_FORMAT="%H:%M:%S"
+
+# Full timestamp
+export MDE_EXECUTE_COMMAND_TITLE_TIME_FORMAT="%Y-%m-%d %H:%M:%S"
+
+# ISO 8601
+export MDE_EXECUTE_COMMAND_TITLE_TIME_FORMAT="%FT%TZ"
+```
+
+**Common Format Codes:**
+- `%H`: Hour (00-23)
+- `%M`: Minute (00-59)
+- `%S`: Second (00-59)
+- `%Y`: Year (4 digits)
+- `%m`: Month (01-12)
+- `%d`: Day (01-31)
+- `%T`: Time (equivalent to `%H:%M:%S`)
+- `%F`: Date (equivalent to `%Y-%m-%d`)
+
+## How It Works
+
+### Execution Flow
+
+1. **Script Generation**: The complete script is generated, including all required dependencies
+2. **Display Check**: If `output_script` or `user_must_approve` is enabled, the script is displayed
+3. **Approval Check**: If `user_must_approve` is enabled, user confirmation is required
+4. **Execution Mode**: Script executes either:
+   - In current terminal (default)
+   - In new window (if `execute_in_own_window` is enabled)
+5. **Post-Execution**: If `pause_after_script_execution` is enabled, execution pauses before menu
+
+### Debouncing Logic
+
+The debouncing mechanism tracks the last executed block:
+- If the same block is selected again, user is prompted
+- Blocks executed from CLI bypass debouncing
+- Debounce state resets on navigation or different block selection
+
+### Window Execution
+
+When `execute_in_own_window` is enabled:
+1. Script is saved to a temporary file
+2. Output file path is determined
+3. `execute_command_format` template is populated with values
+4. Template is executed (typically AppleScript for iTerm)
+5. New window opens and executes the script
+
+## Usage Examples
+
+### Safe Execution with Approval
+
+```bash
+# Require approval for all executions
+mde README.md -b deploy --user-must-approve 1
+
+# Or set globally
+export MDE_USER_MUST_APPROVE=1
+mde README.md -b deploy
+```
+
+### Review Script Before Execution
+
+```bash
+# Display script and require approval
+mde README.md -b deploy --output-script 1 --user-must-approve 1
+```
+
+### Long-Running Scripts in New Window
+
+```bash
+# Execute in new window
+mde README.md -b long-task --execute-in-own-window 1
+
+# With approval
+mde README.md -b long-task -q 1 -w 1
+```
+
+### Pause After Execution
+
+```bash
+# Pause to review results
+mde README.md -b deploy --pause-after-script-execution 1
+```
+
+### Configuration File Example
+
+```yaml
+# .mde.yml
+user_must_approve: true
+output_script: true
+pause_after_script_execution: true
+execute_in_own_window: false
+```
+
+## Related Documentation
+
+- [CLI Reference](cli-reference.md) - Command-line usage patterns
+- [Block Execution Modes](block-execution-modes.md) - Batch, interactive, and default execution modes
+- [Block Filtering](block-filtering.md) - Filtering and selecting blocks
+- [Block Naming Patterns](block-naming-patterns.md) - How block names are parsed and matched
+