markdown_exec 3.5.1 → 3.5.2

data/docs/block-execution-modes.md

@@ -0,0 +1,177 @@
+# Block Execution Modes
+
+This document explains how blocks can be configured to execute in different modes: batch mode, interactive mode, or the default document mode.
+
+## Overview
+
+Markdown Exec supports three execution modes for code blocks, plus a disable option:
+
+1. **Default Mode**: Uses `document_play_bin` (default: `play`) - standard execution
+2. **Batch Mode**: Uses `play_bin_batch` (default: `play`) - for non-interactive batch execution
+3. **Interactive Mode**: Uses `play_bin_interactive` (default: `play_interactive`) - for interactive execution
+4. **Disabled**: Blocks matching `block_disable_match` are marked as disabled and cannot be executed
+
+## Configuration Options
+
+### Block Batch Match
+
+- **Option**: `block_batch_match`
+- **Environment Variable**: `MDE_BLOCK_BATCH_MATCH`
+- **Default**: `'@batch'`
+- **Description**: Pattern to match blocks that should be executed in batch mode
+
+Blocks whose start line matches this pattern will be executed using the `play_bin_batch` binary instead of the default `document_play_bin`.
+
+### Block Interactive Match
+
+- **Option**: `block_interactive_match`
+- **Environment Variable**: `MDE_BLOCK_INTERACTIVE_MATCH`
+- **Default**: `'@interactive'`
+- **Description**: Pattern to match blocks that should be executed in interactive mode
+
+Blocks whose start line matches this pattern will be executed using the `play_bin_interactive` binary.
+
+### Block Disable Match
+
+- **Option**: `block_disable_match`
+- **Environment Variable**: `MDE_BLOCK_DISABLE_MATCH`
+- **Default**: `'@disable'`
+- **Description**: Pattern to match blocks that should be disabled (not executable)
+
+Blocks whose start line matches this pattern will be marked as disabled in the menu and cannot be executed. This is useful for documentation blocks, examples, or blocks that should be visible but not runnable.
+
+### Execution Binaries
+
+The following options control which binary is used for each execution mode:
+
+#### Document Play Bin
+
+- **Option**: `document_play_bin`
+- **Environment Variable**: `MDE_DOCUMENT_PLAY_BIN`
+- **Default**: `'play'`
+- **Description**: Binary used for default block execution mode
+
+This is the default binary used when a block doesn't match any special execution mode pattern.
+
+#### Play Bin Batch
+
+- **Option**: `play_bin_batch`
+- **Environment Variable**: `MDE_PLAY_BIN_BATCH`
+- **Default**: `'play'`
+- **Description**: Binary used for batch mode block execution
+
+This binary is used when a block matches the `block_batch_match` pattern.
+
+#### Play Bin Interactive
+
+- **Option**: `play_bin_interactive`
+- **Environment Variable**: `MDE_PLAY_BIN_INTERACTIVE`
+- **Default**: `'play_interactive'`
+- **Description**: Binary used for interactive mode block execution
+
+This binary is used when a block matches the `block_interactive_match` pattern.
+
+## How It Works
+
+### Execution Mode Selection
+
+The execution mode is determined by checking the block's start line against these patterns in the following order:
+
+1. First, check if the start line matches `block_interactive_match`
+   - If matched → use `play_bin_interactive`
+2. Then, check if the start line matches `block_batch_match`
+   - If matched → use `play_bin_batch`
+3. Otherwise → use `document_play_bin` (default)
+
+This logic is implemented in `lib/hash_delegator.rb` in the `compile_execute_and_trigger_reuse` method (lines 1586-1596).
+
+### Block Disabling
+
+Block disabling is handled separately during menu filtering. If a block's start line matches `block_disable_match`, the block is marked as disabled (`TtyMenu::DISABLE`) and will appear in the menu but cannot be executed. This check happens in `lib/filter.rb` in the `apply_other_filters` method (lines 130-132).
+
+**Note**: Disabled blocks are still visible in the menu but are shown as non-selectable/disabled. This is different from hidden blocks (which use `block_name_hide_custom_match` and are completely hidden from the menu).
+
+## Usage Examples
+
+### Batch Mode
+
+To mark a block for batch execution, include `@batch` in the block's start line:
+
+```bash :example-batch @batch
+echo "This block will execute in batch mode"
+echo "It uses play_bin_batch instead of document_play_bin"
+```
+
+### Interactive Mode
+
+To mark a block for interactive execution, include `@interactive` in the block's start line:
+
+```bash :example-interactive @interactive
+echo "This block will execute in interactive mode"
+echo "It uses play_bin_interactive"
+```
+
+### Disabled Blocks
+
+To mark a block as disabled (visible but not executable), include `@disable` in the block's start line:
+
+```bash :example-disabled @disable
+echo "This block is visible but cannot be executed"
+echo "It will appear in the menu but be marked as disabled"
+```
+
+### Custom Patterns
+
+You can customize the patterns via configuration:
+
+```opts
+block_batch_match: '@batch-mode'
+block_interactive_match: '@interactive-mode'
+block_disable_match: '@skip'
+```
+
+Then use the custom markers:
+
+```bash :custom-batch @batch-mode
+echo "Custom batch marker"
+```
+
+```bash :custom-interactive @interactive-mode
+echo "Custom interactive marker"
+```
+
+```bash :custom-disabled @skip
+echo "Custom disabled marker"
+```
+
+### Custom Execution Binaries
+
+You can also customize which binaries are used for each mode:
+
+```opts
+document_play_bin: 'play'
+play_bin_batch: 'play_batch'
+play_bin_interactive: 'play_interactive'
+```
+
+## Related Configuration
+
+All options in this group work together:
+
+- **Pattern Matching Options**:
+  - `block_interactive_match`: Pattern for interactive mode (checked first)
+  - `block_batch_match`: Pattern for batch mode (checked second)
+  - `block_disable_match`: Pattern for disabled blocks (checked during filtering)
+
+- **Binary Selection Options**:
+  - `document_play_bin`: Binary for default mode (default: `play`)
+  - `play_bin_batch`: Binary for batch mode (default: `play`)
+  - `play_bin_interactive`: Binary for interactive mode (default: `play_interactive`)
+
+## Related Documentation
+
+- [Block Filtering](block-filtering.md) - Filtering options including `block_name_hide_custom_match`, `hide_blocks_by_name`
+- [Execution Control](execution-control.md) - Execution control options including `user_must_approve`, `execute_in_own_window`
+- [Block Naming Patterns](block-naming-patterns.md) - How block names are parsed
+- [CLI Reference](cli-reference.md) - Command-line usage
+

data/docs/block-filtering.md

@@ -0,0 +1,252 @@
+# Block Filtering Options
+
+This document explains how blocks are filtered for inclusion or exclusion from menus and execution in markdown_exec.
+
+## Overview
+
+Markdown Exec provides multiple mechanisms to filter blocks:
+
+1. **Type-based filtering**: Filter by block type (bash, expect, etc.)
+2. **Name-based filtering**: Filter by block name using regex patterns
+3. **Shell-based filtering**: Filter by shell type using regex patterns
+4. **Pattern-based filtering**: Use naming patterns (hidden, include, wrapper)
+
+These filters work together in a specific order to determine which blocks appear in menus and can be executed.
+
+## Configuration Options
+
+### Bash Only
+
+- **Option**: `bash_only`
+- **Environment Variable**: `MDE_BASH_ONLY`
+- **Default**: `false`
+- **Description**: Execute only blocks of type "bash"
+
+When enabled, only blocks explicitly marked as type "bash" will be included. Blocks without a shell type specified will be excluded.
+
+**Usage:**
+```opts
+bash_only: true
+```
+
+### Exclude by Name Regex
+
+- **Option**: `exclude_by_name_regex`
+- **Environment Variable**: `MDE_EXCLUDE_BY_NAME_REGEX`
+- **Default**: (empty)
+- **Description**: Regex pattern to exclude blocks whose names match
+
+Blocks whose names match this regex pattern will be excluded from menus and execution. This is checked after name selection filters.
+
+**Example:**
+```opts
+exclude_by_name_regex: '^test-|^internal-'
+```
+
+This excludes blocks whose names start with `test-` or `internal-`.
+
+### Exclude by Shell Regex
+
+- **Option**: `exclude_by_shell_regex`
+- **Environment Variable**: `MDE_EXCLUDE_BY_SHELL_REGEX`
+- **Default**: (empty)
+- **Description**: Regex pattern to exclude blocks whose shell type matches
+
+Blocks whose shell type matches this regex pattern will be excluded from menus and execution.
+
+**Example:**
+```opts
+exclude_by_shell_regex: '^(python|ruby)$'
+```
+
+This excludes blocks with shell types "python" or "ruby".
+
+### Exclude Expect Blocks
+
+- **Option**: `exclude_expect_blocks`
+- **Environment Variable**: `MDE_EXCLUDE_EXPECT_BLOCKS`
+- **Default**: `true`
+- **Description**: Whether to exclude all blocks of type "expect" from menus
+
+When enabled (default), all blocks of type "expect" are automatically excluded from menus. Expect blocks are typically used for automated testing and are not meant for interactive execution.
+
+**Usage:**
+```opts
+exclude_expect_blocks: false  # Show expect blocks in menu
+```
+
+### Hide Blocks by Name
+
+- **Option**: `hide_blocks_by_name`
+- **Environment Variable**: `MDE_HIDE_BLOCKS_BY_NAME`
+- **Default**: `true`
+- **Description**: Whether to hide blocks whose names match block_name_hide_custom_match pattern
+
+When enabled, blocks whose names match the `block_name_hide_custom_match` pattern (default: `^-.+-$`) will be hidden from menus. This works in conjunction with the naming pattern options.
+
+**Usage:**
+```opts
+hide_blocks_by_name: true
+block_name_hide_custom_match: '^internal-.*'
+```
+
+### Select by Name Regex
+
+- **Option**: `select_by_name_regex`
+- **Environment Variable**: `MDE_SELECT_BY_NAME_REGEX`
+- **Default**: (empty)
+- **Description**: Regex pattern to include only blocks whose names match
+
+When specified, only blocks whose names match this regex pattern will be included. All other blocks will be excluded. This is checked before exclude filters.
+
+**Example:**
+```opts
+select_by_name_regex: '^production-'
+```
+
+This includes only blocks whose names start with `production-`.
+
+### Select by Shell Regex
+
+- **Option**: `select_by_shell_regex`
+- **Environment Variable**: `MDE_SELECT_BY_SHELL_REGEX`
+- **Default**: (empty)
+- **Description**: Regex pattern to include only blocks whose shell type matches
+
+When specified, only blocks whose shell type matches this regex pattern will be included. All other blocks will be excluded.
+
+**Example:**
+```opts
+select_by_shell_regex: '^(bash|sh)$'
+```
+
+This includes only blocks with shell types "bash" or "sh".
+
+## How It Works
+
+The filtering system in `lib/filter.rb` evaluates blocks in a specific order:
+
+### Filter Evaluation Order
+
+1. **Depth Check**: Blocks with `depth == true` are excluded
+2. **Chrome Check**: Decorative blocks (chrome) are included unless `no_chrome` is enabled
+3. **Expect Blocks**: If `exclude_expect_blocks` is true, expect blocks are excluded
+4. **Hidden Name Check**: If `hide_blocks_by_name` is enabled and name matches `block_name_hide_custom_match`, block is excluded
+5. **Include Name Check**: If name matches `block_name_hidden_match`, block is included
+6. **Wrapper Name Check**: If name matches `block_name_wrapper_match`, block is included
+7. **Exclude Filters**: 
+   - If `name_exclude` is true (name matches `exclude_by_name_regex`) → exclude
+   - If `shell_exclude` is true (shell matches `exclude_by_shell_regex`) → exclude
+8. **Select Filters**:
+   - If `name_select` is false (name doesn't match `select_by_name_regex`) → exclude
+   - If `shell_select` is false (shell doesn't match `select_by_shell_regex`) → exclude
+9. **Select Filters (positive)**:
+   - If `name_select` is true → include
+   - If `shell_select` is true → include
+10. **Default Filters**:
+    - If `name_default` is false or `shell_default` is false → exclude
+11. **Default**: Include the block
+
+### Filter Logic Details
+
+**Name Filters** (`apply_name_filters`):
+- `select_by_name_regex` is checked first - if specified, only matching blocks pass
+- `exclude_by_name_regex` is checked second - matching blocks are excluded
+- If neither is specified, all blocks pass name filtering
+
+**Shell Filters** (`apply_shell_filters`):
+- If `bash_only` is true and shell is empty, block is excluded
+- `select_by_shell_regex` is checked first - if specified, only matching blocks pass
+- `exclude_by_shell_regex` is checked second - matching blocks are excluded
+- Expect blocks are marked for exclusion if `exclude_expect_blocks` is true
+
+**Other Filters** (`apply_other_filters`):
+- Disabled blocks (via `block_disable_match`) are marked
+- Hidden name patterns are checked if `hide_blocks_by_name` is enabled
+- Include and wrapper name patterns are checked
+
+## Usage Examples
+
+### Filter to Only Bash Blocks
+
+```opts
+bash_only: true
+```
+
+Only blocks explicitly marked as `bash` will be included.
+
+### Exclude Test Blocks
+
+```opts
+exclude_by_name_regex: '^test'
+```
+
+All blocks whose names start with "test" will be excluded.
+
+### Include Only Production Blocks
+
+```opts
+select_by_name_regex: '^production-'
+```
+
+Only blocks whose names start with "production-" will be included.
+
+### Filter by Shell Type
+
+```opts
+select_by_shell_regex: '^(bash|sh)$'
+exclude_by_shell_regex: 'python'
+```
+
+Include only bash/sh blocks, but exclude any Python blocks.
+
+### Hide Internal Blocks
+
+```opts
+hide_blocks_by_name: true
+block_name_hide_custom_match: '^-internal-'
+```
+
+Blocks with names like `-internal-setup-` will be hidden.
+
+### Combined Filtering
+
+```opts
+# Only show bash blocks
+bash_only: true
+
+# But exclude test blocks
+exclude_by_name_regex: '^test'
+
+# And only include production blocks
+select_by_name_regex: '^production-'
+```
+
+This configuration will:
+1. Only include bash blocks
+2. Exclude blocks starting with "test"
+3. Only include blocks starting with "production-"
+
+## Filter Priority
+
+When multiple filters conflict, the evaluation order determines priority:
+
+1. **Explicit excludes** (exclude_by_name_regex, exclude_by_shell_regex) take precedence
+2. **Select filters** (select_by_name_regex, select_by_shell_regex) act as allowlists
+3. **Pattern-based filters** (hidden, include, wrapper) are evaluated early
+4. **Type-based filters** (bash_only, exclude_expect_blocks) are evaluated early
+
+## Related Configuration
+
+- **Block Naming Patterns**: `block_name_hide_custom_match`, `block_name_hidden_match`, `block_name_wrapper_match` - work with `hide_blocks_by_name`
+- **Block Execution Modes**: `block_disable_match` - marks blocks as disabled
+- **Menu Options**: `menu_include_imported_blocks` - controls imported block visibility
+
+## Related Documentation
+
+- [Block Naming Patterns](block-naming-patterns.md) - Pattern-based filtering
+- [Block Execution Modes](block-execution-modes.md) - Execution mode filtering
+- [Block Scanning Patterns](block-scanning-patterns.md) - How block content is scanned
+- [Import Options](import-options.md) - Imported block filtering
+- [CLI Reference](cli-reference.md) - Command-line usage
+

data/docs/block-naming-patterns.md

@@ -0,0 +1,210 @@
+# Block Naming Patterns
+
+This document explains how block names are parsed, matched, and used for filtering and display in markdown_exec.
+
+## Overview
+
+Markdown Exec uses several regex patterns to identify and categorize block names:
+
+1. **Block Name Extraction**: `block_name_match` - extracts the name from the fenced code block start line
+2. **Block Visibility**: `block_name_hide_custom_match` - control which blocks appear in menus
+3. **Block Types**: `block_name_hidden_match`, `block_name_nick_match`, `block_name_wrapper_match` - identify special block naming patterns
+
+## Configuration Options
+
+### Block Name Match
+
+- **Option**: `block_name_match`
+- **Environment Variable**: `MDE_BLOCK_NAME_MATCH`
+- **Default**: `":(?<title>\\S+)( |$)"`
+- **Description**: Regex pattern to extract the block name from the fenced code block start line
+
+This pattern is used to parse the block name from lines like:
+```bash
+```bash :my-block-name
+```
+
+The default pattern matches a colon followed by a name (captured in the `title` group). The pattern must include a named capture group (typically `title`) to extract the block name.
+
+**Example matches:**
+- `:example` → extracts `example`
+- `:my-block-name` → extracts `my-block-name`
+- `:test_block` → extracts `test_block`
+
+### Block Name Hidden Match
+
+- **Option**: `block_name_hide_custom_match`
+- **Environment Variable**: `MDE_BLOCK_NAME_HIDE_CUSTOM_MATCH`
+- **Default**: `"^-.+-$"`
+- **Description**: Regex pattern for block names that should be hidden from the menu
+
+Blocks whose names match this pattern will be hidden from the block selection menu when `hide_blocks_by_name` is enabled. The default pattern matches names that start and end with hyphens (e.g., `-hidden-`, `-internal-`).
+
+**Example matches:**
+- `-hidden-` → hidden from menu
+- `-internal-block-` → hidden from menu
+- `visible-block` → shown in menu
+
+### Block Name Hidden Match
+
+- **Option**: `block_name_hidden_match`
+- **Environment Variable**: `MDE_BLOCK_NAME_HIDE_CUSTOM_MATCH`
+- **Default**: `"^\\(.*\\)$"`
+- **Description**: Regex pattern for block names that should be included in the menu
+
+Blocks whose names match this pattern will be explicitly included in the menu, even if they might otherwise be filtered. The default pattern matches names in parentheses (e.g., `(document_opts)`, `(document_vars)`).
+
+**Example matches:**
+- `(document_opts)` → included in menu
+- `(document_vars)` → included in menu
+- `(config)` → included in menu
+
+**Note**: This works in conjunction with other filtering options. When `include_name` is true in the filter evaluation, the block is shown in the menu.
+
+### Block Name Nick Match
+
+- **Option**: `block_name_nick_match`
+- **Environment Variable**: `MDE_BLOCK_NAME_NICK_MATCH`
+- **Default**: `"^\\[.*\\]$"`
+- **Description**: Regex pattern for block nicknames (alternative names not displayed in menu)
+
+Blocks whose names match this pattern are treated as having nicknames. The nickname is an alternative identifier that is not displayed in the menu but can be used for references and dependencies. The default pattern matches names in square brackets (e.g., `[alias]`, `[short-name]`).
+
+**Example matches:**
+- `[alias]` → treated as nickname
+- `[short]` → treated as nickname
+- `regular-name` → not a nickname
+
+**Usage**: Nicknames are useful when you want to reference a block by a shorter name internally, but display a different name in the menu.
+
+### Block Name Wrapper Match
+
+- **Option**: `block_name_wrapper_match`
+- **Environment Variable**: `MDE_BLOCK_NAME_WRAPPER_MATCH`
+- **Default**: `"^{.+}$"`
+- **Description**: Regex pattern for block names that act as wrappers (include other blocks)
+
+Blocks whose names match this pattern are treated as wrapper blocks that can include or wrap other blocks. The default pattern matches names in curly braces (e.g., `{wrapper}`, `{container}`).
+
+**Example matches:**
+- `{wrapper}` → treated as wrapper
+- `{container}` → treated as wrapper
+- `regular-block` → not a wrapper
+
+**Usage**: Wrapper blocks are used in dependency resolution and block composition. When a block name matches this pattern in a dependency specification (e.g., `+{wrapper}`), it's treated as a wrapper rather than a regular dependency.
+
+### Block Name (CLI Option)
+
+- **Option**: `block_name`
+- **Long Name**: `--block-name`
+- **Short Name**: `-b`
+- **Environment Variable**: `MDE_BLOCK_NAME`
+- **Description**: Name of block to execute
+
+This is a CLI option that allows you to directly specify which block to execute, bypassing the interactive menu selection.
+
+**Usage:**
+```bash
+mde document.md -b my-block-name
+mde document.md --block-name example-block
+```
+
+## How It Works
+
+### Name Extraction Process
+
+1. When a fenced code block is encountered, the start line is matched against `block_name_match`
+2. If a match is found, the `title` capture group is extracted as the block name
+3. The extracted name is stored as the block's primary identifier
+
+### Filtering Process
+
+The filtering logic in `lib/filter.rb` evaluates blocks in this order:
+
+1. **Custome Hidden Name Check**: If `hide_blocks_by_name` is enabled and the name matches `block_name_hide_custom_match`, the block is hidden
+2. **Hidden Name Check**: If the name matches `block_name_hidden_match`, the block is hidden
+3. **Wrapper Name Check**: If the name matches `block_name_wrapper_match`, it's marked as a wrapper
+4. **Final Decision**: The `evaluate_filters` method combines these flags to determine menu visibility
+
+### Special Name Types
+
+- **Nicknames**: Matched by `block_name_nick_match`, used for internal references but not displayed
+- **Wrappers**: Matched by `block_name_wrapper_match`, used in dependency resolution
+- **Custom Hidden**: Matched by `block_name_hide_custom_match`, excluded from menus
+- **Hidden**: Matched by `block_name_hidden_match`, excluded from menus
+
+## Usage Examples
+
+### Basic Block Naming
+
+```bash :example-block
+echo "This block is named 'example-block'"
+```
+
+The name `example-block` is extracted using `block_name_match` pattern.
+
+### Hidden Blocks
+
+```bash :-internal-
+echo "This block is hidden from the menu"
+```
+
+The name `-internal-` matches `block_name_hide_custom_match` and will be hidden when `hide_blocks_by_name` is enabled.
+
+### Included Blocks (Document Configuration)
+
+```opts :(document_opts)
+# Configuration options
+clear_screen_for_select_block: false
+```
+
+The name `(document_opts)` matches `block_name_hidden_match` and will be hidden from the menu.
+
+### Nickname Blocks
+
+```bash :[alias]
+echo "This block has a nickname"
+```
+
+The name `[alias]` matches `block_name_nick_match` and is treated as a nickname.
+
+### Wrapper Blocks
+
+```bash :{wrapper}
+echo "This is a wrapper block"
+```
+
+The name `{wrapper}` matches `block_name_wrapper_match` and is treated as a wrapper.
+
+### Custom Patterns
+
+You can customize the patterns to match your naming conventions:
+
+```opts
+# Match block names starting with "internal_"
+block_name_hide_custom_match: '^internal_.*'
+
+# Match block names in double parentheses
+block_name_hidden_match: '^\\(\\(.*\\)\\)$'
+
+# Match block names starting with "@"
+block_name_nick_match: '^@.*'
+
+# Match block names in angle brackets
+block_name_wrapper_match: '^<.+>$'
+```
+
+## Related Configuration
+
+- `hide_blocks_by_name`: Enable/disable hiding blocks based on name patterns
+- `block_name`: CLI option to directly specify a block to execute
+- Block filtering options: `exclude_by_name_regex`, `select_by_name_regex`
+
+## Related Documentation
+
+- [Block Filtering](block-filtering.md) - Other block filtering mechanisms
+- [Block Execution Modes](block-execution-modes.md) - Execution mode patterns
+- [Block Scanning Patterns](block-scanning-patterns.md) - How block content is scanned
+- [Import Options](import-options.md) - How imported blocks are named
+- [CLI Reference](cli-reference.md) - Command-line usage
+