markdown_exec 2.0.8.4 → 2.2.0

data/examples/data-files.md

@@ -0,0 +1,50 @@
+# Demonstrate data blocks
+
+```opts :(document_options)
+pause_after_script_execution: true
+```
+
+## Create a data file by requiring a YAML block.
+::: YAML into a file
+/ YAML block that loads data into a file.
+```yaml :(test1) >test1.yml
+a: species
+b: genus
+```
+This is a Bash block that
+- requires a hidden YAML block (that creates a file), and
+- displays the file.
+```bash +(test1)
+echo "- The data file created"
+ls -al *.yml
+echo -e "\n- Contents of the file"
+cat -n test1.yml
+echo -e "\n- Remove the data file"
+rm test1.yml
+```
+
+## Load data by requiring a yaml block.
+::: YAML into a shell variable
+/ YAML block that loads data into a variable.
+```yaml :(test2) >$test2
+c: family
+d: order
+```
+This is a Bash block that
+- requires a hidden YAML block (that sets a variable), and
+- displays the variable.
+```bash +(test2)
+echo 'data:'
+echo "$test2"
+```
+
+## Visible YAML block that is not executable.
+::: Non-interactive data
+```yaml
+e: class
+f: phylum
+```
+
+# Related MDE options
+block_stdin_scan  | Match to place block body into a file or a variable
+block_stdout_scan | Match to place block body into a file or a variable

data/examples/indent.md

@@ -1,4 +1,42 @@
-This document demonstrates content is indented to match the source.
+# This document demonstrates the indentation of blocks and text
+
+Indentation is either leading spaces or tabs.
+Tabs are interpreted as 4 spaces.
+
+## Related MDE options
+fenced_start_and_end_regex   |  Matches the start and end of a fenced code block
+fenced_start_extended_regex  |  Match the start of a fenced block
+heading1_match               |  MDE_HEADING1_MATCH
+heading2_match               |  MDE_HEADING2_MATCH
+heading3_match               |  MDE_HEADING3_MATCH
+menu_divider_match           |  Pattern for topics/dividers in block selection menu
+menu_note_match              |  Pattern for notes in block selection menu
+menu_task_match              |  Pattern for tasks
+
+::: Flush divider, text, block, and comment
+Text
+```bash
+echo 'This is a very long string to force line wrapping in the interface.'
+ # comment indented 1 space
+```
+/ Comment
+
+  ::: Indented (2 spaces) text, block, and comment
+  Text
+  ```bash
+  echo 'This is a very long string to force line wrapping in the interface.'
+  # comment indented 1 space
+  ```
+  / Comment
+
+	::: Indented (1 tab) text, block, and comment
+	Text
+	```bash
+	echo 'This is a very long string to force line wrapping in the interface.'
+	 # comment indented 1 space
+	```
+	/ Comment
+
 
 This is a concise guide for using Bash commands to find and list recent files in a Linux system. The commands are safe to use and can help you quickly locate recently modified or accessed files.
 
@@ -45,24 +83,27 @@ These commands provide a basic way to manage and track file modifications and ac
 
 ```link :Link1
 ```
-
+   ::: Indented (4 spaces) Link block
    ```link :Link2
    ```
 
 ```opts :Opts1
 ```
 
+   ::: Indented (4 spaces) Opts block
    ```opts :Opts2
    ```
 
 ```port :Port1
 ```
 
+   ::: Indented (4 spaces) Port block
    ```port :Port2
    ```
 
 ```vars :Vars1
 ```
 
+   ::: Indented (4 spaces) Vars block
    ```vars :Vars2
    ```

data/examples/link-blocks-block.md

@@ -0,0 +1,5 @@
+## Demonstrate failing due to a missing block
+A missing block triggers an error.
+    ```link
+    block: (a_missing_block)
+    ```

data/examples/link-blocks-load-save.md

@@ -0,0 +1,59 @@
+::: Load file into inherited lines
+Load (do not evaluate) and append to inherited lines.
+```link :load1
+load: examples/load1.sh
+```
+Load, evaluate, and append output to inherited lines.
+```link :load2_eval
+load: examples/load2.sh
+eval: true
+```
+
+::: Load file into inherited lines and switch document
+Load (do not evaluate) and append to inherited lines and switch document.
+```link :load_from_file_link_and_show
+block: show_vars
+file: examples/linked_show.md
+load: examples/load1.sh
+```
+
+::: Save and Load
+Save inherited lines to a file.
+```link :save1
+save: tmp/save1.sh
+```
+Load inherited lines from a file.
+Subsequently, run the `display_variables` block.
+```link :load_saved
+load: tmp/save1.sh
+block: display_variables
+```
+Display variables ALPHA, var1, var2
+```bash :display_variables
+source bin/colorize_env_vars.sh
+colorize_env_vars '' ALPHA var1 var2
+```
+
+::: Load file matching glob pattern into inherited lines
+Load (do not evaluate) and append to inherited lines.
+```link :load_glob_load1*
+load: examples/load1*.sh
+```
+```link :load_glob_load*
+load: examples/load*.sh
+```
+```link :load_glob_fail
+load: examples/fail*
+```
+```link :load_glob_with_format
+load: "%{home}/examples/load*.sh"
+```
+```link :save_glob_load*
+save: examples/*.sh
+```
+```link :save_glob_*
+save: examples/*.sh
+```
+```link :load_glob_*
+load: examples/*.sh
+```

data/examples/link-blocks-vars.md

@@ -0,0 +1,56 @@
+# Demonstrate link blocks set variables
+```opts :(document_options)
+execute_in_own_window: false
+menu_with_inherited_lines: true
+output_execution_report: false
+output_execution_summary: false
+pause_after_script_execution: true
+```
+
+## Demonstrate a link block that sets a variable
+::: Click below to trigger. If it prints "VARIABLE1: 1", the Link block was processed.
+The hidden block "(print-VARIABLE1)" is required below. It prints variable "VARIABLE1".
+```bash :(print-VARIABLE1)
+source bin/colorize_env_vars.sh
+colorize_env_vars '' VARIABLE1
+```
+The block sets VARIABLE1 and requires hidden block "(print-VARIABLE1)".
+For each environment variable in `vars`, append an inherited line that assigns the variable the specified value.
+    ```link
+    block: (print-VARIABLE1)
+    vars:
+      VARIABLE1: 1
+    ```
+
+## Demonstrate a link block that requires a shell block that sets a variable
+This block "[bash_set_to_3]" is required below. It sets the variable "ALPHA".
+    ```bash :[bash_set_to_3]
+    ALPHA=3
+    ```
+::: Click below to trigger. If it prints "ALPHA: 3", the Link block was processed.
+These blocks require the *code* of the named shell block.
+    ```link +[bash_set_to_3]
+    block: "(display_variable_ALPHA)"
+    ```
+    ```link +[bash_set_to_3]
+    next_block: "(display_variable_ALPHA)"
+    ```
+
+This block "[bash_set_to_4]" is required below. It prints a command that sets the variable "ALPHA".
+    ```bash :[bash_set_to_4]
+    echo "ALPHA=4"
+    ```
+::: Click below to trigger. If it prints "ALPHA: 4", the Link block was processed.
+These blocks require the *output* of the execution of the code in the named shell block.
+    ```link +[bash_set_to_4]
+    eval: true
+    block: "(display_variable_ALPHA)"
+    ```
+    ```link +[bash_set_to_4]
+    eval: true
+    next_block: "(display_variable_ALPHA)"
+    ```
+```bash :(display_variable_ALPHA)
+source bin/colorize_env_vars.sh
+colorize_env_vars '' ALPHA
+```

data/examples/linked.md

@@ -6,38 +6,6 @@ pause_after_script_execution: false
 user_must_approve: false
 ```
 
-```link :missing_block
-block: (display_variable)
-eval: true
-```
-Block name with all chars.
-/ !"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~
-/ ¡¢£¤¥¦§¨©ª«¬®¯°±²³´µ¶·¸¹º»¼½¾¿ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖ×ØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüýþÿ
-```link :!"#$%&'()*+,-./0123456789:;<=>?@ABCDEFGHIJKLMNOPQRSTUVWXYZ[\]^_`abcdefghijklmnopqrstuvwxyz{|}~
-file: examples/linked2.md
-block: show_vars
-vars:
-  page2_var_via_environment: for_page2_from_page1_via_current_environment
-```
-```link :¡¢£¤¥¦§¨©ª«¬®¯°±²³´µ¶·¸¹º»¼½¾¿ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖ×ØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüýþÿ
-file: examples/linked2.md
-block: show_vars
-vars:
-  page2_var_via_environment: for_page2_from_page1_via_current_environment
-```
-Block with no title is displayed correctly in a single line (for a Bash comment).
-```link
-file: examples/linked2.md
-block: show_vars
-vars:
-  page2_var_via_environment: for_page2_from_page1_via_current_environment
-```
-Spaces in variable value are unchanged.
-```link :link_with_vars_with_spaces
-vars:
-  test: "1 2 3"
-```
-
 ::: Set variable ALPHA in a Vars block
 For each environment variable named in block,
  append an inherited line that assigns the variable the specified value.
@@ -45,16 +13,6 @@ For each environment variable named in block,
 ALPHA: 1
 ```
 
-::: Set variable ALPHA in a Link block
-For each environment variable in `vars`,
- append an inherited line that assigns the variable the specified value.
-Subsequently, run the `display_variable_ALPHA` block.
-```link :[set_ALPHA_to_2_via_link_block_and_display]
-block: display_variable_ALPHA
-vars:
-  ALPHA: 2
-```
-
 Make the code in the required block `(bash_set_to_3)` into inherited lines.
 Subsequently, run the `display_variable_ALPHA` block.
 ```bash :(bash_set_to_3)
@@ -82,42 +40,6 @@ echo The current value of environment variable ALPHA is now:
 colorize_env_vars '' ALPHA
 ```
 
-::: Load file into inherited lines
-Load (do not evaluate) and append to inherited lines.
-```link :load1
-load: examples/load1.sh
-```
-Load, evaluate, and append output to inherited lines.
-```link :load2_eval
-load: examples/load2.sh
-eval: true
-```
-
-::: Load file into inherited lines and switch document
-Load (do not evaluate) and append to inherited lines and switch document.
-```link :load_from_file_link_and_show
-block: show_vars
-file: examples/linked_show.md
-load: examples/load1.sh
-```
-
-::: Save and Load
-Save inherited lines to a file.
-```link :save1
-save: tmp/save1.sh
-```
-Load inherited lines from a file.
-Subsequently, run the `display_variables` block.
-```link :load_saved
-load: tmp/save1.sh
-block: display_variables
-```
-Display variables ALPHA, var1, var2
-```bash :display_variables
-source bin/colorize_env_vars.sh
-colorize_env_vars '' ALPHA var1 var2
-```
-
 Execute a script requiring input from the user.
 Save the output setting TIMESTAMP into inherited lines.
 Subsequently, run the `display_TIMESTAMP` block.
@@ -141,26 +63,9 @@ source bin/colorize_env_vars.sh
 colorize_env_vars '' TIMESTAMP
 ```
 
-::: Load file matching glob pattern into inherited lines
-Load (do not evaluate) and append to inherited lines.
-```link :load_glob_load1*
-load: examples/load1*.sh
-```
-```link :load_glob_load*
-load: examples/load*.sh
-```
-```link :load_glob_fail
-load: examples/fail*
-```
-```link :load_glob_with_format
-load: "%{home}/examples/load*.sh"
-```
-```link :save_glob_load*
-save: examples/*.sh
-```
-```link :save_glob_*
-save: examples/*.sh
-```
-```link :load_glob_*
-load: examples/*.sh
-```
+## Values
+Spaces in variable value are unchanged.
+    ```link :link_with_vars_with_spaces
+    vars:
+      test: "1 2 3"
+    ```

data/examples/opts-blocks-require.md

@@ -0,0 +1,28 @@
+# Demonstrate requiring blocks
+```opts :(document_options) +(custom) +[custom]
+menu_divider_color: red     # color to indicate failure
+```
+```opts :(custom)
+menu_divider_color: green   # color to indicate success
+```
+## Automatic documents options
+::: If this text is green, the required Opts block was processed; if this text is red, the required Opts block was NOT processed hidden, name: "(custom)"
+
+## Click this named block to test
+::: Click below to trigger. If this text starts with "+++", the required Opts block was processed; name: "custom"
+    ```opts :custom
+    menu_divider_format: "+++ %{line}"   # format to indicate success
+    ```
+
+## Click this nicknamed block to test
+::: Click below to trigger. If this text starts with "!!!", the Opts block was processed; name: "[custom]"
+This block has a nickname "[custom]". It is executable.
+    ```opts :[custom]
+    menu_divider_format: "!!! %{line}"   # format to indicate success
+    ```
+
+## Click this unnamed block to test
+::: Click below to trigger. If this text starts with "@@@", the required Opts block was processed; unnamed
+    ```opts
+    menu_divider_format: "@@@ %{line}"   # format to indicate success
+    ```

data/examples/opts_output_execution.md

@@ -0,0 +1,46 @@
+# Demo options: output_execution_report, output_execution_summary
+
+::: Options are initially True
+```opts :(document_options) +[document_options]
+output_execution_report: true
+output_execution_summary: true
+pause_after_script_execution: true
+```
+```bash
+whoami
+pwd >&2
+date >&1 1>&2
+```
+
+## output_execution_report
+### Example
+		 -^-
+		Command: mde ./examples/opt_output_execution_summary.md
+		StdOut: logs/mde_2024-07-08-03-21-59_opt_output_execution_summary_,_whoami___pwd__&2___date__&1_1_&2_.out.txt
+		 -v-
+### Toggle
+```opts
+output_execution_report: false
+```
+```opts
+output_execution_report: true
+```
+
+## output_execution_summary
+### Example (edited)
+		:execute_aborted_at:
+		:execute_completed_at: 2024-07-08 03:21:59.988451000 Z
+		:execute_error:
+		:execute_error_message:
+		:execute_options: { ... }
+		:execute_started_at: 2024-07-08 03:21:59.864442000 Z
+		:saved_filespec:
+		:script_block_name:
+		:streamed_lines: { ... }
+### Toggle
+```opts
+output_execution_summary: false
+```
+```opts
+output_execution_summary: true
+```

data/examples/{port.md → port-blocks.md}

@@ -1,12 +1,11 @@
 # Demo variable porting
 
-::: This block requires the Port block and displays the value.
-::: The Port block contributes the variable VAULT to the generated script.
-
-```bash :show +(vault)
-: ${VAULT:=This variable has not been set.}
-source bin/colorize_env_vars.sh
-colorize_env_vars '' VAULT
+```opts :(document_options)
+dump_inherited_lines: true
+execute_in_own_window: false
+output_execution_report: false
+output_execution_summary: false
+pause_after_script_execution: true
 ```
 
 ::: Set the VAULT value in memory.
@@ -16,8 +15,18 @@ colorize_env_vars '' VAULT
 VAULT: This variable was set by the "set" block.
 ```
 
-::: There is an invisible Port block that saves current/live environment variable values into the generated script.
+::: This is a Port block that saves current/live environment variable values into the generated script.
 
-```port :(vault)
+```port :[vault]
 VAULT
+VAULT2
+```
+
+::: This block requires the Port block and displays the value.
+::: The Port block contributes the variable VAULT to the generated script.
+
+```bash :show +[vault]
+: ${VAULT:=This variable has not been set.}
+source bin/colorize_env_vars.sh
+colorize_env_vars '' VAULT
 ```

data/examples/save.md

@@ -0,0 +1,79 @@
+# Demonstrate custom file names
+```opts :(document_options) +[custom]
+pause_after_script_execution: true  # for interactive demos
+save_executed_script:         true  # demonstrate saved scripts
+save_execution_output:        true  # demonstrate saved output
+```
+
+## Related MDE options
+save_executed_script   |  Whether to save an executed script
+save_execution_output  |  Save standard output of the executed script
+saved_asset_format     |  Format for script and log file names
+saved_asset_match      |  Regexp for script and log file names
+saved_history_format   |  Format for each row displayed in history
+
+### Add "DOMAIN" shell expansion. Include a wildcard as default to allow for matching when undefined.
+::: Default
+```opts
+saved_asset_format: "%{prefix}%{join}%{time}%{join}%{filename}%{join}%{mark}%{join}%{blockname}%{join}%{exts}"
+```
+::: Custom
+```opts :[custom]
+# Add "DOMAIN" shell expansion. Include a wildcard as default to allow for matching when undefined.
+saved_asset_format: "%{prefix}%{join}${DOMAIN:-*}%{join}%{time}%{join}%{filename}%{join}%{mark}%{join}%{blockname}%{join}%{exts}"
+```
+### Add "domain" capture group
+::: Default
+```opts
+saved_asset_match: "^(?<prefix>.+)(?<join>_)(?<time>[0-9\\-]+)\\g'join'(?<filename>.+)\\g'join'(?<mark>~)\\g'join'(?<blockname>.+)\\g'join'(?<exts>\\..+)$"
+```
+::: Custom
+```opts :[custom]
+# Add "domain" capture group
+saved_asset_match: "^(?<prefix>.+)(?<join>_)(?<domain>.*)\\g'join'(?<time>[0-9\\-]+)\\g'join'(?<filename>.+)\\g'join'(?<mark>~)\\g'join'(?<blockname>.+)\\g'join'(?<exts>\\..+)$"
+```
+### Add "domain" to history display
+::: Default
+```opts
+saved_history_format: "%{time}  %{blockname}  %{exts}"
+```
+::: Custom
+```opts :[custom]
+# Add "domain" to history display
+saved_history_format: "%{domain}  %{time}  %{blockname}  %{exts}"
+```
+
+## Append to Inherited Lines
+::: Load the DOMAIN variable.
+1. Set DOMAIN to "site.local"
+```vars
+DOMAIN: site.local
+```
+
+2. Set DOMAIN to "site.remote"
+```vars
+DOMAIN: site.remote
+```
+
+- Notice how the history changes according to the current DOMAIN.
+
+## Saved files
+::: Run this command to generate files for the script and the output of the execution.
+```bash :test +(test2)
+echo "$(date -u)"
+```
+```bash :(test2)
+echo "$(date -u)"
+```
+- Notice how the saved files increase by 2 with every execution.
+::: Test block with no name
+```bash
+sleep 1
+echo $(date -u)
+sleep 2
+echo $(date -u)
+sleep 3
+echo $(date -u)
+sleep 4
+echo $(date -u)
+```

data/examples/vars-blocks.md

@@ -0,0 +1,38 @@
+```opts :(document_options)
+execute_in_own_window: false
+output_execution_report: false
+output_execution_summary: false
+pause_after_script_execution: true
+```
+The hidden block "(defaults)" sets the environment variable VAULT to "default" if it is unset.
+```bash :(defaults)
+: ${VAULT:=default}
+```
+
+::: Click below to trigger. If it prints "VAULT: default", the shell block was processed.
+The named block prints the environment variable VAULT. It requires hidden block "(defaults)" before printing.
+    ```bash :show_vars +(defaults)
+    source bin/colorize_env_vars.sh
+    colorize_env_vars '' VAULT
+    ```
+
+The block sets the environment variable VAULT to "11".
+When clicked, it adds the variable to the inherited code. It does not output.
+    ```vars :[set_vault_11]
+    VAULT: 11
+    ```
+
+# DOES NOT WORK 2024-07-20
+## This does not evaluate the shell block.
+::: Click below to trigger. If it prints "VAULT: 22", the shell block was processed.
+The block sets the environment variable VAULT to "22". It requires block "show_vars". Notice block "show_vars" is called after the variable is set.
+    ```vars :[set_with_show] +show_vars
+    VAULT: 22
+    ```
+
+## This outputs the value before the variable is set.
+The named block prints the environment variable VAULT. It requires block "set".
+    ```bash :show_with_set +[set_vault_11]
+    source bin/colorize_env_vars.sh
+    colorize_env_vars '' VAULT
+    ```

data/lib/constants.rb

@@ -48,6 +48,7 @@ class MenuState
   CONTINUE = :continue
   EDIT = :edit
   EXIT = :exit
+  HISTORY = :history
   LOAD = :load
   SAVE = :save
   SHELL = :shell
@@ -63,7 +64,7 @@ end
 
 # selected block and subsequent menu state
 #
-SelectedBlockMenuState = Struct.new(:block, :state)
+SelectedBlockMenuState = Struct.new(:block, :source, :state)
 
 SHELL_COLOR_OPTIONS = {
   BlockType::BASH => :menu_bash_color,