markdown_exec 3.4.0 → 3.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: ec9a613148346890f4db46f3f5bdcade05b8e2221e92402c431fa9a359556e1e
-  data.tar.gz: 05d16eaf1ac5d433c8da62513da88159313e3b2898d36d7dfa0d71061c83a97b
+  metadata.gz: 6becba5a0ff94fb60399da0fc99248fff83905def9c65e4a8e1ae9c597652036
+  data.tar.gz: 98f0d4ad3764fec26b4ed8f1bce1904af1f350853b3e2678847f0557b381e8bf
 SHA512:
-  metadata.gz: 9dcec89e521fc194eb329b36dc83068a11215186c5e3e5447485000a40c8e75f8bdabd10824af34b9ff90fee3f0899d5bb0f82f76f4ffa3a0a950d213585e6a5
-  data.tar.gz: 06b8fb5443b026e628fd60962bd9c7abbccd78824ea0d0b001f27b4608cc0cb147fff6fa00eac5de3712ed97f76d50296b35368675478992e06b28db06b29dfc
+  metadata.gz: b2d1d60bcf1fe258a8be76893b070ab418563e27923c9e8a4370cd04fa5e0d421732c3c51e76e596a5d492885170270437916035530f64ba2e99a98d215bd908
+  data.tar.gz: 306d802cfcfc5bfa9460e2d58a69ac4f9ac0c058a28859243a237682d2622549277ff6f8515f84c51b2a2ede229c3f95eaa9a0ce5b9dbde98bfc2ad862c9aa8f

data/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## [3.5.1] - 2025-11-14
+
+### Added
+
+- Docker testing environment.
+
+### Changed
+
+- Correct tests for Docker environment.
+- Uses env split mode to parse the shell command.
+
+## [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/Dockerfile.test

@@ -0,0 +1,42 @@
+FROM ruby:3.3-bookworm
+
+ENV LANG C.UTF-8
+
+RUN apt-get update && apt-get install -y --no-install-recommends \
+        build-essential \
+        bsdmainutils \
+        gawk \
+        git \
+        tree \
+        vim
+
+# `markdown_exec` is the name expected by some BATS tests
+WORKDIR /markdown_exec
+
+# Clone the repository (shallow clone for faster builds)
+ARG GIT_BRANCH=main
+RUN git clone --depth 1 --branch ${GIT_BRANCH} https://github.com/fareedst/markdown_exec.git .
+
+# Initialize and update git submodules
+RUN git submodule update --init --recursive
+
+# Install dependencies
+RUN bundle install
+
+# Add aliases
+RUN echo 'alias batsv="bats --verbose-run --show-output-of-passing-tests"' >> ~/.bashrc && \
+    echo 'alias be="bundle exec"' >> ~/.bashrc && \
+    echo 'alias bmde="bin/bmde"' >> ~/.bashrc && \
+    echo 'alias ll="ls -FGlAhp"' >> ~/.bashrc
+
+RUN git submodule add https://github.com/bats-core/bats-core.git test/bats && \
+    git submodule add https://github.com/bats-core/bats-support.git test/test_helper/bats-support && \
+    git submodule add https://github.com/bats-core/bats-assert.git test/test_helper/bats-assert
+
+# make dirs, file for BATS tests
+RUN mkdir -p logs
+RUN mkdir -p docs/research
+RUN echo '04:31 e' > logs/mde_site.local_2024-07-31-20-04-01___examples_save_md_~_test_.out.txt
+RUN ln -s /markdown_exec/test/bats/bin/bats /usr/local/bin/
+
+CMD ["bash"]

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.1)
       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,9 +99,16 @@ 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)
+    nokogiri (1.16.6-aarch64-linux)
+      racc (~> 1.4)
     nokogiri (1.16.6-arm64-darwin)
       racc (~> 1.4)
     open3 (0.1.2)
@@ -218,6 +226,7 @@ GEM
     zeitwerk (2.6.16)
 
 PLATFORMS
+  aarch64-linux
   arm64-darwin-21
 
 DEPENDENCIES
@@ -227,6 +236,7 @@ DEPENDENCIES
   irb
   markdown_exec!
   minitest
+  minitest-reporters
   mocha
   pry-nav
   pry-stack_explorer

data/README.md

@@ -1,211 +1,350 @@
 # 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
 
-### 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
-```
+See [Tab Completion Documentation](docs/tab-completion.md) for installation and usage instructions.
 
-### Behavior
+## Example: Interactive Workflow
 
-Press tab for completions appropriate to the current input.
-`mde <...> <prior word> <current word><TAB>`
+This example demonstrates a complete interactive workflow with UX blocks, dependencies, and cross-document navigation:
 
-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
+### Step 1: User Input
+<pre><code>```ux :user-setup
+name: USER_NAME
+prompt: Enter your name
+init: Guest
+```
+</code></pre>
+
+<pre><code>```ux :environment
+name: ENVIRONMENT
+allow:
+  - development
+  - staging
+  - production
+prompt: Select environment
+```
+</code></pre>
 
-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` |
+### 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}"
+```
+</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
+```
+</code></pre>
+
+### Step 4: Cross-Document Navigation
+<pre><code>```link
+file: next-workflow.md
+vars:
+  user: ${USER_NAME}
+  env: ${ENVIRONMENT}
+```
+</code></pre>
 
-## Example Blocks
+# Testing
 
-When prompted, select either the `awake` or `asleep` block.
+## Docker Testing Environment
 
-``` :(day)
-export TIME=early
-```
+For a complete testing environment with all dependencies, use the Docker testing container:
 
-``` :(night)
-export TIME=late
-```
+```bash
+# Build the test environment
+docker build -f Dockerfile.test -t markdown-exec-test .
 
-``` :awake +(day) +(report)
-export ACTIVITY=awake
-```
+# Run all tests (RSpec, Minitest, and BATS)
+docker run -it markdown-exec-test bash -c 'bundle exec rake test'
 
-``` :asleep +(night) +(report)
-export ACTIVITY=asleep
-```
+# Run individual test suites
+docker run -it markdown-exec-test bash -c 'bundle exec rspec'          # RSpec only
+docker run -it markdown-exec-test bash -c 'bundle exec rake minitest'  # Minitest only
+docker run -it markdown-exec-test bash -c 'bundle exec rake bats'      # BATS tests only
 
-``` :(report)
-echo "$TIME -> $ACTIVITY"
+# Enter the container interactively
+docker run --rm -it markdown-exec-test bash
 ```
 
-# Testing
+## Local Testing
 
-Execute tests for individual libraries.
+Execute tests for individual libraries locally:
 
 `bundle exec rake minitest`