markdown_exec 3.2.0 → 3.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8c39aff829d6b7a3d4eb05134922cdb6fed1d54192fab72ba244d7d7ff73183e
-  data.tar.gz: f2bbfa6b9be857c718ba23c1bbc071b91ffe7ba027626c9a27b1d06c8bfce5a9
+  metadata.gz: a1b653c2db50fe8b7a8de3ea448a49d814b0210fd90090f06b829f30465dc313
+  data.tar.gz: e48016ab6903bf7967c575fa5f3c84893bf2ffb7e35b5b00788a59b5de2257e5
 SHA512:
-  metadata.gz: 1b97c91ff7b91da388ff9d3aed19ee5e15fd25bd4d6e8f3591a8997614736e27e1c12fb3682a3395bae5853131578b924cbf55284ffda2beb9b89843c8b7c2b7
-  data.tar.gz: 3056e41d512fa097204cae511a057b193c5ad3c70e406dee3da1df369bb0bed4f517137cf55e86ac6fcdc1308b70d604c75e9c2c2ee8c9b30edf0d5f574c006e
+  metadata.gz: 8e34466abddbda4228bb45d6bfb75e18e3bf4f9fc664a38eaa89aed3d93aceb0b042463854f02a4c0bb9ccf51e2d03226247e2a5c247315d1bb65954b3635739
+  data.tar.gz: 77bf12764fe5bf436d270a3d8c1763de469fae4fb6741714dedd1d400bb2e11d1fbeb2811cf062460fdd9cfe05ef2a32e9b6bd83b3e77e3f7f720d808a3472ed

data/CHANGELOG.md

@@ -1,5 +1,32 @@
 # Changelog
 
+## [3.3.0] - 2025-09-02
+
+### Added
+
+- Process Shell, Vars, and UX blocks in sequence.
+- A personal exclude file that is not checked in.
+- Option to annotate required lines.
+- Option to make the directory if it does not exist when saving inherited code.
+- Support for single-line tables.
+- Options to decorate UX blocks per its activation.
+- Special value '0' for environment variable 'WW' silences it. Otherwise, 'WW' outputs that it's testing new algorithm when the app is started.
+- Apply text substitutions for each parameter according to a symbol.
+
+### Changed
+
+- Trigger a selected block by it ID instead of its name. Stops co-triggering of blocks with and without names.
+- Imported documents are skipped if duplicate. Importing a document with alternate parameters makes it unique.
+- Set multiple variables in a UX block:
+  - UX blocks set multiple variables from echo expansions or exec evaluations
+  - Automatic allowed value based on echo or exec is the first line of the first variable set by the block
+- Debug output improvements:
+  - Debug output indicates the depth of the call stack in each line.
+  - Add a function to alert and abort
+  - Add an environment variable to the log file name to document variations.
+- Remove an unused option.
+- Improve handling of interrupt at prompt.
+
 ## [3.2.0] - 2025-07-24
 
 ### Added

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    markdown_exec (3.2.0)
+    markdown_exec (3.3.0)
       clipboard (~> 1.3.6)
       open3 (~> 0.1.1)
       optparse (~> 0.1.1)

data/Rakefile

@@ -103,9 +103,9 @@ task :bats do
   execute_with_error_handling(FileList['bats/**/*.bats']) do |file|
     next nil if %w[bats/bats.bats bats/fail.bats].include?(file)
 
-    # temporary clear WW to disable debugging
-    # WW pollutes output expected by BATS tests
-    %(unset WW; bats #{file})
+    # If enabled, WW pollutes stderr processed by BATS tests
+    # silence with WW=0
+    %(export WW=0; bats #{file})
   end
 end
 

data/bats/block-type-ux-auto.bats

@@ -4,5 +4,5 @@ load 'test_helper'
 
 @test 'Initial values' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-auto.md \
-   'v1 = _v2 = _v3 = 12_v4 = 21_v5 = markdown_exec__v6 = 31'
+   'v1 = _v2 = _v3 = 12_v4 = 21_v5 = markdown_exec_v6 = 31'
 }

data/bats/block-type-ux-default.bats

@@ -4,5 +4,5 @@ load 'test_helper'
 
 @test 'Initial values' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-default.md \
-   'v1 = _v2 = 11_v3 = 12_v4 = 21_v5 = markdown_exec__v6 = 31'
+   'v1 = _v2 = 11_v3 = 12_v4 = 21_v5 = markdown_exec_v6 = 31'
 }

data/bats/block-type-ux-echo-hash-transform.bats

@@ -4,5 +4,5 @@ load 'test_helper'
 
 @test 'Each key in the echo hash is processed.' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-echo-hash-transform.md \
-   'Tapanuli Orangutan_Species: PONGO TAPANULIENSIS_Genus: PONGO_Tapanuli Orangutan_Family: H:Hominidae_Order: P:Primates'
+   'Tapanuli Orangutan_Species: PONGO TAPANULIENSIS_Genus: PONGO_Tapanuli Orangutan_Family: H:Hominidae_Order: P:Primates_Psychedelic Frogfish_Species2:  Haccdeeehhiiilnopprsstyy_Genus2: Hehiinoprsty_Family2: Aaadeeiinnnrt'
 }

data/bats/block-type-ux-echo-hash.bats

@@ -4,11 +4,11 @@ load 'test_helper'
 
 @test 'an automatic block sets multiple variables' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-echo-hash.md \
-   'BASENAME=markdown_exec_DOCUMENTS=markdown_OPERATION=exec_Load Tapanuli Orangutan_Load Psychedelic Frogfish_| Variable | Value |_| -------- | ----- |_| Species  |   |_| Genus    |       |_| Family   |   |'
+   'BASENAME=markdown_exec_DOCUMENTS=markdown_OPERATION=exec_Load Tapanuli Orangutan_Load Psychedelic Frogfish_| Variable | Value |_| -------- | ----- |_| Species  |       |_| Genus    |       |_| Family   |   |'
 }
 
 @test 'an activated block sets multiple variables' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-echo-hash.md \
    'Load Tapanuli Orangutan' \
-   'BASENAME=markdown_exec_DOCUMENTS=markdown_OPERATION=exec_Load Tapanuli Orangutan_Load Psychedelic Frogfish_| Variable | Value                   |_| -------- | ----------------------- |_| Species  | Pongo tapanuliensis |_| Genus    | Pongo                   |_| Family   | Hominidae           |'
+   'BASENAME=markdown_exec_DOCUMENTS=markdown_OPERATION=exec_Load Tapanuli Orangutan_Load Psychedelic Frogfish_| Variable | Value               |_| -------- | ------------------- |_| Species  | Pongo tapanuliensis |_| Genus    | Pongo               |_| Family   | Hominidae       |'
 }

data/bats/block-type-ux-exec-hash-transform.bats

@@ -0,0 +1,8 @@
+#!/usr/bin/env bats
+
+load 'test_helper'
+
+@test 'Each key in the exec hash is processed.' {
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-exec-hash-transform.md \
+   'Cappuccino Snake_Species_ H  Y  D  R  O  D  Y  N  A  S  T  E  S     B  I_ 48 59 44 52 4F 44 59 4E 41 53 54 45 53 20 42 49_  C  I  N  C  T  U  S  _ _ 43 49 4E 43 54 55 53 0A_Genus_ H  Y  D  R  O  D  Y  N  A  S  T  E  S  _ _ 48 59 44 52 4F 44 59 4E 41 53 54 45 53 0A_Family_ C  O  L  U  B  R  I  D  A  E_ 43 4F 4C 55 42 52 49 44 41 45_Order_ S  u  m  t  _ _ 53 75 6D 74 0A_Class_ R  p  i  i_ 52 70 69 69_Phylum_ C  o  d  t_ 43 6F 64 74'
+}

data/bats/block-type-ux-exec-hash.bats

@@ -0,0 +1,15 @@
+#!/usr/bin/env bats
+
+load 'test_helper'
+
+@test 'automatic' {
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-exec-hash.md \
+   'A single named variable is set automatically as the_output of the exec string._Common_Name=Yeti Crab_Common_Name=Yeti Crab_ Y  e  t  i     C  r  a  b  _ _ 59 65 74 69 20 43 72 61 62 0A__Multiple variables are set automatically as the_output of each exec string._One variable is temporary/not stored to inherited lines_but available for calculations within the block._Domain=ukaryota____D=_Domain=ukaryota_ u  k  a  r  y  o  t  a  _   _ _ 75 6B 61 72 79 6F 74 61 0A 0A__A single named variable is set interactively as the_output of the exec string._Year_Discovered=_Year_Discovered=_$(hexdump_format "$Year_Discovered")__Multiple variables are set interactively as the_output of the exec string._Genus=_Species=_$(hexdump_format "$Species")_Genus=_$(hexdump_format "$Genus")__A single named variable is set automatically as the_first line of the output of the first element in the echo_hash._Kingdom=Animalia_Kingdom=Animalia_ A  n  i  m  a  l  i  a_ 41 6E 69 6D 61 6C 69 61__A single named variable is set automatically as the_first line of the output of the first element in the exec_hash._Class=Malacostraca_Class=Malacostraca_ M  a  l  a  c  o  s  t  r  a  c  a_ 4D 61 6C 61 63 6F 73 74 72 61 63 61'
+}
+
+@test 'interactive' {
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-exec-hash.md \
+   '[Year_Discovered]' \
+   '[Genus]' \
+   'A single named variable is set automatically as the_output of the exec string._Common_Name=Yeti Crab_Common_Name=Yeti Crab_ Y  e  t  i     C  r  a  b  _ _ 59 65 74 69 20 43 72 61 62 0A__Multiple variables are set automatically as the_output of each exec string._One variable is temporary/not stored to inherited lines_but available for calculations within the block._Domain=ukaryota____D=_Domain=ukaryota_ u  k  a  r  y  o  t  a  _   _ _ 75 6B 61 72 79 6F 74 61 0A 0A__A single named variable is set interactively as the_output of the exec string._Year_Discovered=2005_Year_Discovered=2005_ 2  0  0  5  _ _ 32 30 30 35 0A__Multiple variables are set interactively as the_output of the exec string._Genus=Kiwa__Species=Kiwa hirsuta_ K  i  w  a     h  i  r  s  u  t  a  _ _ 4B 69 77 61 20 68 69 72 73 75 74 61 0A_Genus=Kiwa_ K  i  w  a  _   _ _ 4B 69 77 61 0A 0A__A single named variable is set automatically as the_first line of the output of the first element in the echo_hash._Kingdom=Animalia_Kingdom=Animalia_ A  n  i  m  a  l  i  a_ 41 6E 69 6D 61 6C 69 61__A single named variable is set automatically as the_first line of the output of the first element in the exec_hash._Class=Malacostraca_Class=Malacostraca_ M  a  l  a  c  o  s  t  r  a  c  a_ 4D 61 6C 61 63 6F 73 74 72 61 63 61'
+}

data/bats/block-type-ux-exec.bats

@@ -4,5 +4,5 @@ load 'test_helper'
 
 @test 'Output of executed commands as initial value' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-exec.md \
-   "ux0=_ux1=Unknown_ux2=markdown_exec__ux3=markdown_exec__ux4=Xform: 'markdown'"
+   "ux0=_ux1=Unknown_ux2=markdown_exec_ux3=markdown_exec_ux4=Xform: 'markdown'"
 }

data/bats/block-type-ux-force.bats

@@ -0,0 +1,9 @@
+#!/usr/bin/env bats
+
+load 'test_helper'
+
+# UX before VARS although VARS appears first
+@test 'automatic' {
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-force.md \
+  'Common_Name = Tapanuli Orangutan_  inherited_lines_  - : Common_Name="Tapanuli Orangutan"_  - : Common_Name=Ruby\ Seadragon_Common_Name=Ruby Seadragon_| Common_Name | Ruby Seadragon |'
+}

data/bats/block-type-ux-formats.bats

@@ -0,0 +1,8 @@
+#!/usr/bin/env bats
+
+load 'test_helper'
+
+@test 'UX block appearance' {
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-formats.md \
+   'Demonstrate UX block appearance according to its state.__A simple variable declaration._EDIT VAR1 = value1__A selection from predefined options._ALLOW VAR2 = value2__A computed value using command substitution._ECHO VAR3 = Gemfile__An editable computed value._EDIT VAR4 = Gemfile__A command execution with formatted output._EXEC VAR5 = Gemfile___A read-only value._READONLY VAR6 = Gemfile_'
+}

data/bats/block-type-ux-readonly.bats

@@ -5,6 +5,6 @@ load 'test_helper'
 @test 'automatic block - disabled' {
   spec_mde_args_expect \
    docs/dev/block-type-ux-readonly.md \
-   --list-blocks-message readonly --list-blocks-type 3 --list-blocks \
+   --blocks readonly \
    true
 }

data/bats/block-type-ux-row-format.bats

@@ -4,5 +4,5 @@ load 'test_helper'
 
 @test 'Row format merges with prior table' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-row-format.md \
-   "   | Variable   | Value                | Prompt                |_   | ---------- | -------------------- | --------------------- |_   | Species    | Pongo tapanuliensis  | New species?      |_  | Name: Genu | Value: Xform: 'Pongo | Prompt: New genus? |_   | Family     | Hominidae            | Enter a value:    |"
+   "   | Variable    | Value                 | Prompt             |_   | ----------- | --------------------- | ------------------ |_   | Species     | Pongo tapanuliensis   | New species?       |_   | Name: Genus | Value: Xform: 'Pongo' | Prompt: New genus? |_   | Family      | Hominidae             | Enter a value: |"
 }

data/bats/block-type-ux-transform.bats

@@ -4,5 +4,5 @@ load 'test_helper'
 
 @test 'Transformed output of executed commands' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-transform.md \
-  '_Execution output has a trailing newline._Var0=markdown_exec__ 6d 61 72 6b 64 6f 77 6e 5f 65 78 65 63 0a      __With validate and transform, output has no newline._Var1=markdown_exec_ 6d 61 72 6b 64 6f 77 6e 5f 65 78 65 63         __With transform :chomp, output has no newline._Var2=markdown_exec_ 6d 61 72 6b 64 6f 77 6e 5f 65 78 65 63         __With transform :upcase, output is in upper case w/ newline._Var3=MARKDOWN_EXEC__ 4d 41 52 4b 44 4f 57 4e 5f 45 58 45 43 0a      '
+  '_Execution output has a trailing newline._Var0=markdown_exec_ 6d 61 72 6b 64 6f 77 6e 5f 65 78 65 63 0a      __With validate and transform, output has no newline._Var1=markdown_exec_ 6d 61 72 6b 64 6f 77 6e 5f 65 78 65 63         __With transform :chomp, output has no newline._Var2=markdown_exec_ 6d 61 72 6b 64 6f 77 6e 5f 65 78 65 63         __With transform :upcase, output is in upper case w/ newline._Var3=MARKDOWN_EXEC_ 4d 41 52 4b 44 4f 57 4e 5f 45 58 45 43 0a      '
 }

data/bats/import-directive-parameter-symbols.bats

@@ -0,0 +1,9 @@
+#!/usr/bin/env bats
+
+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'
+}

data/bats/import-duplicates.bats

@@ -20,20 +20,22 @@ load 'test_helper'
    '_d1.1_d0.1_u0.1'
 }
 
+# a name in the CLI that matches multiple blocks only loads the first
 @test 'Import and require blocks with duplicate names - duplicate 0' {
   BATS_OUTPUT_FILTER=A
   BATS_SAFE=_
   spec_mde_args_expect docs/dev/import-duplicates-0.md \
    'd0' \
-   '_d1.0_d1.1_d0.0_d0.1'
+   '_d1.0_d1.1_d0.1'
 }
 
+# a name in the CLI that matches multiple blocks only loads the first
 @test 'Import and require blocks with duplicate names - duplicate 1' {
   BATS_OUTPUT_FILTER=A
   BATS_SAFE=_
   spec_mde_args_expect docs/dev/import-duplicates-0.md \
    'd1' \
-   '_d1.1_d0.1'
+   '_d1.1'
 }
 
 @test 'Import and require blocks with duplicate names - unique in import 0' {

data/bats/import-parameter-symbols.bats

@@ -0,0 +1,8 @@
+#!/usr/bin/env bats
+
+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}"'
+}

data/bats/markup.bats

@@ -16,7 +16,7 @@ load 'test_helper'
 
 @test 'Options - list blocks - 3 decorates' {
   spec_mde_args_expect docs/dev/text-decoration.md \
-   --list-blocks-message dname --list-blocks-type 3 --list-blocks \
+   --blocks dname \
    $'\x1b\x5b\x33\x38\x3b\x32\x3b\x31\x39\x32\x3b\x31\x39\x32\x3b\x31\x39\x32\x6d\x2d\x20\x1b\x5b\x30\x6d\x1b\x5b\x31\x6d\x1b\x5b\x34\x6d\x42\x6f\x6c\x64\x2d\x55\x6e\x64\x65\x72\x6c\x69\x6e\x65\x1b\x5b\x32\x32\x6d\x1b\x5b\x32\x34\x6d\x0a\x1b\x5b\x33\x38\x3b\x32\x3b\x31\x39\x32\x3b\x31\x39\x32\x3b\x31\x39\x32\x6d\x2d\x20\x1b\x5b\x30\x6d\x1b\x5b\x31\x6d\x42\x6f\x6c\x64\x1b\x5b\x32\x32\x6d\x0a\x1b\x5b\x33\x38\x3b\x32\x3b\x31\x39\x32\x3b\x31\x39\x32\x3b\x31\x39\x32\x6d\x2d\x20\x1b\x5b\x30\x6d\x1b\x5b\x31\x6d\x1b\x5b\x33\x6d\x42\x6f\x6c\x64\x2d\x49\x74\x61\x6c\x69\x63\x1b\x5b\x32\x32\x6d\x1b\x5b\x32\x33\x6d\x0a\x1b\x5b\x33\x38\x3b\x32\x3b\x31\x39\x32\x3b\x31\x39\x32\x3b\x31\x39\x32\x6d\x2d\x20\x1b\x5b\x30\x6d\x1b\x5b\x34\x6d\x55\x6e\x64\x65\x72\x6c\x69\x6e\x65\x1b\x5b\x32\x34\x6d\x0a\x1b\x5b\x33\x38\x3b\x32\x3b\x31\x39\x32\x3b\x31\x39\x32\x3b\x31\x39\x32\x6d\x2d\x20\x1b\x5b\x30\x6d\x1b\x5b\x34\x6d\x1b\x5b\x33\x6d\x55\x6e\x64\x65\x72\x6c\x69\x6e\x65\x2d\x49\x74\x61\x6c\x69\x63\x1b\x5b\x32\x33\x6d\x1b\x5b\x32\x34\x6d\x0a\x1b\x5b\x33\x38\x3b\x32\x3b\x31\x39\x32\x3b\x31\x39\x32\x3b\x31\x39\x32\x6d\x2d\x20\x1b\x5b\x30\x6d\x1b\x5b\x33\x6d\x49\x74\x61\x6c\x69\x63\x1b\x5b\x32\x33\x6d\x0a\x1b\x5b\x33\x38\x3b\x32\x3b\x31\x39\x32\x3b\x31\x39\x32\x3b\x31\x39\x32\x6d\x2d\x20\x1b\x5b\x30\x6d\x1b\x5b\x39\x6d\x53\x74\x72\x69\x6b\x65\x74\x68\x72\x6f\x75\x67\x68\x1b\x5b\x32\x39\x6d'
 }
 

data/bats/options.bats

@@ -74,7 +74,7 @@ load 'test_helper'
 @test 'Options - load-code' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/load_code.md \
    --load-code docs/dev/load1.sh \
-   --list-blocks-message dname --list-blocks-type 3 --list-blocks \
+   --blocks dname \
    'Demonstrate loading inherited code via the command line.__Run this command to display the inherited code._mde --load-code docs/dev/load1.sh docs/dev/load_code.md__| Variable | Value |_| -------- | ----- |_| var1     | line2 |_| var2     | line4 |'
 }
 

data/bin/tab_completion.sh

@@ -26,6 +26,8 @@ _mde() {
     if [[ ${prev} == -* ]] ; then
       case $prev in
         
+              --blocks) COMPREPLY="''"; return 0 ;;
+            
               --config) COMPREPLY="."; return 0 ;;
             
               --debug) COMPREPLY="f"; return 0 ;;
@@ -108,7 +110,7 @@ _mde() {
   # present matching option names
   #
   if [[ ${cur} == -* ]] ; then
-    opts=("--block-name" "--config" "--debug" "--dig" "--dump-blocks-in-file" "--dump-delegate-object" "--dump-dependencies" "--dump-inherited-block-names" "--dump-inherited-dependencies" "--dump-inherited-lines" "--dump-menu-blocks" "--dump-selected-block" "--execute-in-own-window" "--exit" "--filename" "--find" "--find-path" "--help" "--history" "--how" "--list-blocks" "--list-blocks-eval" "--list-blocks-message" "--list-blocks-type" "--list-count" "--list-default-env" "--list-default-yaml" "--list-docs" "--format" "--list-recent-output" "--list-recent-scripts" "--load-code" "--mine" "--open" "--output-script" "--output-stdout" "--path" "--pause-after-script-execution" "--probe" "--publish-document-file-mode" "--publish-document-file-name" "--pwd" "--run-last-script" "--sift" "--tab-completions" "--user-must-approve" "--version" "--display-level")
+    opts=("--block-name" "--blocks" "--config" "--debug" "--dig" "--dump-blocks-in-file" "--dump-delegate-object" "--dump-dependencies" "--dump-inherited-block-names" "--dump-inherited-dependencies" "--dump-inherited-lines" "--dump-menu-blocks" "--dump-selected-block" "--execute-in-own-window" "--exit" "--filename" "--find" "--find-path" "--help" "--history" "--how" "--list-blocks" "--list-blocks-eval" "--list-blocks-message" "--list-blocks-type" "--list-count" "--list-default-env" "--list-default-yaml" "--list-docs" "--format" "--list-recent-output" "--list-recent-scripts" "--load-code" "--mine" "--open" "--output-script" "--output-stdout" "--path" "--pause-after-script-execution" "--probe" "--publish-document-file-mode" "--publish-document-file-name" "--pwd" "--run-last-script" "--sift" "--tab-completions" "--user-must-approve" "--version" "--display-level")
     COMPREPLY=( $(compgen -W "$(printf "'%s' " "${opts[@]}")" -- "${cur}") )
 
     return 0
@@ -125,6 +127,8 @@ _mde() {
         
           -b) COMPREPLY=".NAME."; return 0 ;;
         
+          --blocks) COMPREPLY=".MESSAGE."; return 0 ;;
+        
           --config) COMPREPLY=".PATH."; return 0 ;;
         
           --debug) COMPREPLY=".BOOL."; return 0 ;;

data/docs/dev/block-type-ux-echo-hash-transform.md

@@ -25,16 +25,18 @@ validate: >
 ```
 Family: ${Family}
 Order: ${Order}
-//
-// Each key in the exec hash is processed.
-/```ux
-/exec:
-/  Species2: printf %s 'Histiophryne psychedelica'
-/  Genus2: printf %s 'Histiophryne'
-/format: Psychedelic Frogfish
-/name: Species2
-/transform: :downcase
-/```
-/Species2: ${Species2}
-/Genus2: ${Genus2}
+/
+/ Each key in the echo hash is processed.
+```ux
+echo:
+  Species2: Histiophryne psychedelica
+  Genus2: Histiophryne
+  Family2: Antennariidae
+format: Psychedelic Frogfish
+name: Common2
+transform: :sort_chars
+```
+Species2: ${Species2}
+Genus2: ${Genus2}
+Family2: ${Family2}
 @import bats-document-configuration.md

data/docs/dev/block-type-ux-exec-hash-transform.md

@@ -0,0 +1,37 @@
+/ Each key in the exec hash is processed.
+```ux
+exec:
+  Species: echo 'Hydrodynastes bicinctus'
+  Genus: echo Hydrodynastes
+  Family: printf %s Colubridae
+format: Cappuccino Snake
+name: Common
+transform: :upcase
+```
+__Species__
+$(hexdump_format "$Species")
+__Genus__
+$(hexdump_format "$Genus")
+__Family__
+$(hexdump_format "$Family")
+/
+```ux :()
+exec:
+  Order: echo Squamata
+  Class: printf %s Reptilia
+  Phylum: printf %s Chordata
+name: Common
+transform: :delete_even_chars
+```
+__Order__
+$(hexdump_format "$Order")
+__Class__
+$(hexdump_format "$Class")
+__Phylum__
+$(hexdump_format "$Phylum")
+/
+@import hexdump_format.md
+@import bats-document-configuration.md
+```opts :(document_opts)
+screen_width: 64
+```

data/docs/dev/block-type-ux-exec-hash.md

@@ -0,0 +1,93 @@
+A single named variable is set **automatically** as the output of the exec string.
+```ux
+exec: echo 'Yeti Crab'
+name: Common_Name
+```
+Common_Name=${Common_Name}
+$(hexdump_format "$Common_Name")
+
+
+
+Multiple variables are set **automatically** as the output of each exec string.
+One variable is temporary/not stored to inherited lines but available for calculations within the block.
+/ Substring Extraction using POSIX parameter expansion.
+```ux
+exec:
+  __D: >-
+    echo 'Domain: Eukaryota'
+  Domain: >-
+    echo "${__D:7,9}"
+name: Domain
+```
+__D=${__D}
+Domain=${Domain}
+$(hexdump_format "$Domain")
+
+
+
+A single named variable is set **interactively** as the output of the exec string.
+```ux :[Year_Discovered]
+exec: echo 2005
+init: false
+name: Year_Discovered
+```
+Year_Discovered=${Year_Discovered}
+$(hexdump_format "$Year_Discovered")
+
+
+
+Multiple variables are set **interactively** as the output of the exec string.
+/ String Replacement
+```ux :[Genus]
+exec:
+  Species: echo 'Kiwa hirsuta'
+  Genus: echo "${Species/ hirsuta/}"
+init: false
+name: Genus
+```
+Species=${Species}
+$(hexdump_format "$Species")
+Genus=${Genus}
+$(hexdump_format "$Genus")
+
+
+
+A single named variable is set **automatically** as the first line of the output of the first element in the echo hash.
+```ux
+allow: :echo
+echo:
+  __K: |
+    Animalia
+    Animalia2
+  __P: |
+    Arthropoda
+    Arthropoda2
+name: Kingdom
+```
+Kingdom=${Kingdom}
+$(hexdump_format "$Kingdom")
+
+
+
+**A single named variable is set automatically** as the first line of the output of the first element in the exec hash.
+```ux
+allow: :exec
+exec:
+  __C: |
+    echo Malacostraca
+    echo Malacostraca2
+  __P: |
+    echo Arthropoda
+    echo Arthropoda2
+name: Class
+```
+Class=${Class}
+$(hexdump_format "$Class")
+
+
+
+@import hexdump_format.md
+@import bats-document-configuration.md
+```opts :(document_opts)
+screen_width: 64
+```

data/docs/dev/block-type-ux-force.md

@@ -0,0 +1,20 @@
+/ The variable is defined mulitple times.
+/ Blocks are evaluated in order from top to bottom.
+/ The VARS assignment is output.
+/ Inherited lines are output.
+/ This VARS block creates the first assignment.
+```vars :(document_vars)
+Common_Name: Tapanuli Orangutan
+```
+/ This UX block forces the value in a second assignment.
+```ux :[2]
+init: Ruby Seadragon
+force: true
+name: Common_Name
+```
+! Common_Name! ${Common_Name}
+@import bats-document-configuration.md
+```opts :(document_opts)
+dump_inherited_lines: true
+table_center: false
+```

data/docs/dev/block-type-ux-formats.md

@@ -0,0 +1,58 @@
+Demonstrate UX block appearance according to its state.
+
+A simple variable declaration.
+```ux
+init: value1
+name: VAR1
+```
+
+A selection from predefined options.
+```ux
+act: :allow
+allow:
+  - value2
+name: VAR2
+```
+
+A computed value using command substitution.
+```ux
+act: :echo
+echo: '`ls Gemfile`'
+name: VAR3
+```
+
+An editable computed value.
+```ux
+act: :edit
+echo: '`ls Gemfile`'
+name: VAR4
+```
+
+A command execution with formatted output.
+```ux
+act: :exec
+exec: ls Gemfile
+name: VAR5
+```
+
+A read-only value.
+```ux
+exec: ls Gemfile
+name: VAR6
+readonly: true
+```
+@import bats-document-configuration.md
+```opts :(document_opts)
+menu_ux_row_format: 'DEFAULT %{name} = ${%{name}}'
+menu_ux_row_format_allow: 'ALLOW %{name} = ${%{name}}'
+menu_ux_row_format_echo: 'ECHO %{name} = ${%{name}}'
+menu_ux_row_format_edit: 'EDIT %{name} = ${%{name}}'
+menu_ux_row_format_exec: 'EXEC %{name} = ${%{name}}'
+menu_ux_row_format_readonly: 'READONLY %{name} = ${%{name}}'
+# menu_ux_color_readonly: fg_bg_rgbh_df_df_00_14_18_1c
+menu_ux_color_allow: fg_rgbh_6f_00_7f
+menu_ux_color_echo: fg_rgbh_3f_00_7f
+menu_ux_color_edit: fg_rgbh_1f_00_7f
+menu_ux_color_exec: fg_rgbh_1f_40_7f
+menu_ux_color_readonly: fg_rgbh_1f_00_9f
+```