markdown_exec 2.8.2 → 2.8.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 066c72f2f85462a89163b7834669dee6526e516ee3ebfe4be2e8b269cb4ece36
-  data.tar.gz: 48c2bce9ac82cda2cbecca5bea4564b28013cdbab7005e249e8a856d0280afa0
+  metadata.gz: 7ace0bdaa8d2925a4274a4cfc039fdde5e9aaaf8bfbd761f21e0679417f71062
+  data.tar.gz: 0a9f38be8b322be828fe28cd19441da7a9bb032dd739aaa73ba0526456251503
 SHA512:
-  metadata.gz: fe1270b8cf11efc8ad9e81cb43052bc75cfc217e362c7d6e30acb6981a6d0be749f290b9b15ce1a2655d6a7e157177c4cd975aa61de22a6f6bafe2a835285228
-  data.tar.gz: 9445285db86af55fe5ba0b784a24d30dd418ac3d1dc551183a5a1b3b865df27a6b314ddc08b4a013de5e926e023439753fe08cd4ea8d6c6da0c0d9547e4a9546
+  metadata.gz: b0c0c4eea966bad0e29e0957e68049cfee1c61bd730fab880f63ea1501cba153dd1592ef415142a91a9aecd09802cf0bb48eac36607964b97ce372c9b249536f
+  data.tar.gz: d254a22305dd0d57f2048271d40f15d22b6f2473971cc3c398a6479d439fe80255f0dabb7cb94f9df8c21bc6214b2f60b5238c102e3048cbdbd3dd3dd18b693a

data/CHANGELOG.md

@@ -1,5 +1,57 @@
 # Changelog
 
+## [2.8.4] - 2025-03-24
+
+### Added
+
+- UX block default selection behavior: load as default the first item in `allowed` or the first line in the evaluated output of `echo` or `exec` parameters.
+- A hidden UX block can be required.
+- BATS tests validating an active UX block that requires read-only blocks.
+- UX blocks evaluated automatically load their specified defaults.
+- During interactive/manual evaluation, UX blocks present a menu of the list in the `allowed` parameter or the lines in the evaluated output of `echo` or `exec` parameters.
+- New `SelectResponse` class tracks user's "Back" choice in interactive menus.
+- `ww` calls now return the last item from the provided array, facilitating prefix usage in statements.
+- Ability to set multiple variables from a single UX block using a dictionary of variable names and evaluated expressions defined in the `echo` parameter.
+- BATS tests covering hidden and invalid UX blocks.
+- Introduced standardized result objects for representing success and failure states, supporting custom payloads for failures.
+
+### Changed
+
+- Enabled verbose mode by default for all minitests.
+- Improved whitespace handling in the evaluated output of `echo`.
+- Updated and expanded minitest suite.
+- Update the execution of UX blocks.
+- Aggregated results collected per UX block when processing input from files.
+- Enhanced ANSI sequence tests with more complex formatting scenarios (e.g., bold, italicized, bright-yellow text on a light-yellow background).
+- Standardized script shebangs to consistently execute Ruby minitests via `bundle exec`.
+- Multi-line shell expansions create multiple lines in the menu.
+
+## [2.8.3] - 2025-02-27
+
+### Added
+
+- "echo" support to UX blocks for evaluated shell expressions
+
+  Introduces the `echo` key to UX blocks, allowing the output of an
+  evaluated shell expression to be assigned to a named variable.
+  Implements `export_echo_with_code` to execute the expression safely
+  and handle invalidated outputs. Also ensures proper transformation of
+  export values.
+
+- Persist allocated FCBs.
+
+- Read-only flag to UX menu blocks
+
+  Introduces a `readonly` flag for UX menu blocks, allowing exports to
+  specify whether a block should be immutable. The flag is assigned from
+  the export definition and enforced in the menu logic.
+
+### Changed
+
+- Correct indent of all lines displayed for a block.
+- Retain whitespace in output from shell blocks.
+- Remove a function to report the compiled version from the tab completion script. It is not used.
+
 ## [2.8.2] - 2025-02-19
 
 ### Added

data/Gemfile.lock

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

data/Rakefile

@@ -105,7 +105,7 @@ task :bats do
 
     # temporary clear WW to disable debugging
     # WW pollutes output expected by BATS tests
-    "unset WW; bats #{file}"
+    %(unset WW; bats #{file})
   end
 end
 
@@ -117,29 +117,39 @@ end
 desc 'minitest'
 task :minitest do
   commands = [
-    './lib/argument_processor.rb',
-    './lib/cached_nested_file_reader.rb',
-    './lib/collapser.rb',
-    './lib/directory_searcher.rb',
-    './lib/evaluate_shell_expressions.rb',
-    './lib/fcb.rb',
-    './lib/filter.rb',
+    './lib/argument_processor.rb --verbose',
+    './lib/block_label.rb --verbose',
+    './lib/cached_nested_file_reader.rb --verbose',
+    './lib/collapser.rb --verbose',
+    './lib/dev/ansi_codes.rb --verbose',
+    './lib/dev/append_to_bash_history.rb --verbose',
+    './lib/dev/generate_transition_codes.rb --verbose',
+    './lib/dev/hierarchy.rb --verbose',
+    './lib/dev/process_command.rb --verbose',
+    './lib/dev/process_template.rb --test --verbose',
+    # './lib/dev/ruby_file_processor.rb --test --verbose',
+    # './lib/dev/std_out_err_logger.rb', ### errs
+    './lib/dev/visibility-controller.rb --verbose',
+    './lib/directory_searcher.rb --verbose',
+    './lib/evaluate_shell_expressions.rb --verbose',
+    './lib/fcb.rb --verbose',
+    './lib/filter.rb --verbose',
     './lib/find_files.rb',
-    './lib/format_table.rb',
-    './lib/hash_delegator.rb',
-    './lib/hierarchy_string.rb',
-    './lib/link_history.rb',
-    './lib/markdown_exec.rb',
-    './lib/mdoc.rb',
-    './lib/object_present.rb',
-    './lib/option_value.rb',
-    './lib/regexp.rb',
-    './lib/resize_terminal.rb',
-    './lib/saved_assets.rb',
-    './lib/saved_files_matcher.rb',
-    './lib/table_extractor.rb',
-    './lib/text_analyzer.rb',
-    './lib/dev/process_template.rb --test'
+    './lib/format_table.rb --verbose',
+    './lib/hash_delegator.rb --verbose',
+    './lib/hierarchy_string.rb --verbose',
+    './lib/link_history.rb --verbose',
+    './lib/markdown_exec.rb --verbose',
+    './lib/mdoc.rb --verbose',
+    './lib/object_present.rb --verbose',
+    './lib/option_value.rb --verbose',
+    './lib/regexp.rb --verbose',
+    './lib/resize_terminal.rb --verbose',
+    './lib/saved_assets.rb --verbose',
+    './lib/saved_files_matcher.rb --verbose',
+    # './lib/shell_session.rb --verbose',
+    './lib/table_extractor.rb --verbose',
+    './lib/text_analyzer.rb --verbose'
   ]
 
   execute_with_error_handling(commands) do |command|

data/bats/{block-types.bats → block-type-bash.bats}

@@ -2,8 +2,6 @@
 
 load 'test_helper'
 
-# Type: Bash
-
 @test 'Bash blocks - default' {
   BATS_OUTPUT_FILTER=A
   spec_mde_args_expect docs/dev/block-type-bash.md block-with-no-shell-type \
@@ -38,26 +36,3 @@ load 'test_helper'
   spec_mde_args_expect docs/dev/block-type-bash.md \[show-shell-version\] \
    ' detected_shell: bash'
 }
-
-# Type: Link
-
-@test 'Link blocks - set variable in link block; call hidden block' {
-  # __Exit is required as last block is a Link type
-  run_mde_specs_md_args_expect_xansi '[VARIABLE1]' __Exit ' VARIABLE1: 1'
-  run_mde_specs_md_args_expect_xansi '[VARIABLE1]' '(echo-VARIABLE1)' ' VARIABLE1: 1   VARIABLE1: 1'
-}
-
-# Type: Port
-
-# includes output from assignment and from shell block
-@test 'Port block - export variable' {
-  BATS_OUTPUT_FILTER=A
-  spec_mde_args_expect docs/dev/block-type-port.md '[set_vault_1]' show \
-   'VAULT = 1  VAULT: 1'
-}
-
-@test 'Port block - export variable - not set' {
-  BATS_OUTPUT_FILTER=A
-  spec_mde_args_expect docs/dev/block-type-port.md VAULT-is-export show \
-   '   VAULT: This variable has not been set.'
-}

data/bats/block-type-link.bats

@@ -0,0 +1,9 @@
+#!/usr/bin/env bats
+
+load 'test_helper'
+
+@test 'Link blocks - set variable in link block; call hidden block' {
+  # __Exit is required as last block is a Link type
+  run_mde_specs_md_args_expect_xansi '[VARIABLE1]' __Exit ' VARIABLE1: 1'
+  run_mde_specs_md_args_expect_xansi '[VARIABLE1]' '(echo-VARIABLE1)' ' VARIABLE1: 1   VARIABLE1: 1'
+}

data/bats/block-type-port.bats

@@ -0,0 +1,16 @@
+#!/usr/bin/env bats
+
+load 'test_helper'
+
+# includes output from assignment and from shell block
+@test 'Port block - export variable' {
+  BATS_OUTPUT_FILTER=A
+  spec_mde_args_expect docs/dev/block-type-port.md '[set_vault_1]' show \
+   'VAULT = 1  VAULT: 1'
+}
+
+@test 'Port block - export variable - not set' {
+  BATS_OUTPUT_FILTER=A
+  spec_mde_args_expect docs/dev/block-type-port.md VAULT-is-export show \
+   '   VAULT: This variable has not been set.'
+}

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

@@ -0,0 +1,29 @@
+#!/usr/bin/env bats
+
+load 'test_helper'
+
+@test 'automatic blocks load defaults - constants or first allowed from output of echo or exec' {
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-allowed.md \
+   'SPECIES=Pongo tapanuliensis_GENUS=Pongo_FAMILY=_ORDER=Click to select..._CLASS=Click to select..._YEAR_DISCOVERED=_NAME=Tapanuli Orangutan'
+}
+
+@test 'executing a block loads the first allowed value' {
+  skip 'Unable to test the menu presented'
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-allowed.md \
+   '[FAMILY]' \
+   'SPECIES=Pongo tapanuliensis_GENUS=Pongo_FAMILY=Hominidae_ORDER=Click to select..._CLASS=Click to select..._YEAR_DISCOVERED=_NAME='
+}
+
+@test 'executing a block loads the first line in the output of exec' {
+  skip 'Unable to test the menu presented'
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-allowed.md \
+   '[YEAR_DISCOVERED]' \
+   'SPECIES=Pongo tapanuliensis_GENUS=Pongo_FAMILY=_YEAR_DISCOVERED=2017_NAME='
+}
+
+@test 'executing a block loads the first line in the output of echo' {
+  skip 'Unable to test the menu presented'
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-allowed.md \
+   '[NAME]' \
+   'SPECIES=Pongo tapanuliensis_GENUS=Pongo_FAMILY=_ORDER=Click to select..._CLASS=Click to select..._YEAR_DISCOVERED=_NAME=Tapanuli Orangutan'
+}

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-chained.bats

@@ -0,0 +1,9 @@
+#!/usr/bin/env bats
+
+load 'test_helper'
+
+@test 'A UX block requires other read-only UX blocks that operate on the computed value.' {
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-chained.md \
+   '[SPECIES]' \
+   'SPECIES=Pongo tapanuliensis_NAME=Pongo tapanuliensis - Pongo'
+}

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

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

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

@@ -0,0 +1,20 @@
+#!/usr/bin/env bats
+
+load 'test_helper'
+
+@test 'automatic block - default' {
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-echo.md \
+   'VAR=markdown_exec_IAB='
+}
+
+@test 'inherited lines' {
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-echo.md \
+   '(menu_with_inherited_lines)' \
+   'VAR=markdown_exec_VAR=markdown_exec_IAB='
+}
+
+@test 'selected block - output of wc includes whitespace' {
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-echo.md \
+   '(VAR_has_count)' '[IAB_has_count]' \
+   'VAR=      14_IAB=      14      14'
+}

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-hidden.bats

@@ -0,0 +1,9 @@
+#!/usr/bin/env bats
+
+load 'test_helper'
+
+@test 'a UX block requires a shell block and another UX block' {
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-hidden.md \
+   '[SPECIES]' \
+   'SPECIES=Pongo tapanuliensis_NAME=Pongo tapanuliensis - Pongo'
+}

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

@@ -0,0 +1,8 @@
+#!/usr/bin/env bats
+
+load 'test_helper'
+
+@test 'automatic block is invalid YAML' {
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-invalid.md \
+   '_Error: HashDelegator../docs/dev/block-type-ux-invalid.md_vmlpd_bfnf_b_3 - --- !ruby/object:NullResult_message: Invalid YAML_data: invalid_ --  -- '
+}

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

@@ -0,0 +1,8 @@
+#!/usr/bin/env bats
+
+load 'test_helper'
+
+@test 'An undefined variable is a precondition' {
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-ux-preconditions.md \
+   'A value must exist for: MISSING_VARIABLE_SPECIES='
+}

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

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

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_00000000  6d 61 72 6b 64 6f 77 6e  5f 65 78 65 63 0a        |markdown_exec.|__With validate and transform, output has no newline._Var1=markdown_exec_00000000  6d 61 72 6b 64 6f 77 6e  5f 65 78 65 63           |markdown_exec|__With transform :chomp, output has no newline._Var2=markdown_exec_00000000  6d 61 72 6b 64 6f 77 6e  5f 65 78 65 63           |markdown_exec|__With transform :upcase, output is in upper case w/ newline._Var3=MARKDOWN_EXEC_00000000  4d 41 52 4b 44 4f 57 4e  5f 45 58 45 43 0a        |MARKDOWN_EXEC.|'
+   '_Execution output has a trailing newline._Var0=markdown_exec__00000000  6d 61 72 6b 64 6f 77 6e  5f 65 78 65 63 0a        |markdown_exec.|_0000000e__With validate and transform, output has no newline._Var1=markdown_exec_00000000  6d 61 72 6b 64 6f 77 6e  5f 65 78 65 63           |markdown_exec|_0000000d__With transform :chomp, output has no newline._Var2=markdown_exec_00000000  6d 61 72 6b 64 6f 77 6e  5f 65 78 65 63           |markdown_exec|_0000000d__With transform :upcase, output is in upper case w/ newline._Var3=MARKDOWN_EXEC__00000000  4d 41 52 4b 44 4f 57 4e  5f 45 58 45 43 0a        |MARKDOWN_EXEC.|_0000000e'
 }

data/bats/block-type-vars.bats

@@ -7,8 +7,8 @@ load 'test_helper'
 # includes output from automatic vars blocks
 @test 'Vars block - auto load' {
   BATS_OUTPUT_FILTER=A
-  spec_mde_args_expect docs/dev/block-type-vars.md show \
-   'Species = Not specified Genus = Not specified  Species: Not specified VAULT:'
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/block-type-vars.md show \
+   'Species = Not specified_Genus = Not specified__Species: Not specified_VAULT: '
 }
 
 # includes output from assignment and from shell block
@@ -22,5 +22,5 @@ load 'test_helper'
 @test 'Vars block - invalid YAML' {
   BATS_OUTPUT_FILTER=A
   spec_mde_args_expect docs/dev/block-type-vars.md '[invalid_yaml]' show \
-   'Species = Not specified Genus = Not specified  Species: Not specified VAULT:'
+   'Species = Not specified Genus = Not specified  Species: Not specified VAULT: '
 }

data/bats/indented-block-type-vars.bats

@@ -0,0 +1,9 @@
+#!/usr/bin/env bats
+
+load 'test_helper'
+
+@test 'an indented block with multiple lines' {
+  BATS_OUTPUT_FILTER=A
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/indented-block-type-vars.md \
+   '  Species: Pongo tapanuliensis_  Genus: Pongo_'
+}

data/bats/indented-multi-line-output.bats

@@ -0,0 +1,9 @@
+#!/usr/bin/env bats
+
+load 'test_helper'
+
+@test 'Retain whitespace in output from shell blocks' {
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/indented-multi-line-output.md \
+   '[make-output]' \
+   '_Species_ Genus_  Family_Order'
+}

data/bats/line-decor-dynamic.bats

@@ -0,0 +1,8 @@
+#!/usr/bin/env bats
+
+load 'test_helper'
+
+@test 'Line decor, dynamic - new pattern, line_decor_pre, ansi' {
+  spec_mde_dname_doc_blocks_expect docs/dev/line-decor-dynamic.md \
+   $'\e[1m\e[3m\e[38;2;200;200;33m\e[48;2;60;60;32mSpecies\e[22;23;0m'
+}

data/bats/test_helper.bash

@@ -27,6 +27,9 @@ echo_hexdump_expected_output_filter () {
     echo_hexdump "$(remove_ansi_escape_sequences "$output")"
     echo "- expected"
     echo_hexdump "$expected"
+
+    # print the byte offset of the first difference
+    #diff <(remove_ansi_escape_sequences "$output") <(echo -n "$expected") | grep "^[0-9a-f]{8} " | cut -c 1-8
   fi
 } 
 
@@ -178,9 +181,13 @@ spec_mde_args_grep_filter_expect () {
   SL="${BATS_SLEEP}"
 
   if [[ -z $SL ]]; then
-    echo >&2 $EXE "${remaining[@]}"
+    debug_args=()
+    for arg in "${remaining[@]}"; do
+      escaped_arg=$(printf '%q' "$arg")
+      debug_args+=("$escaped_arg")
+    done
+    echo >&2 $EXE "${debug_args[@]}"
 
-    # Pass the exact arguments including empty and space-containing ones
     run $EXE "${remaining[@]}"
   else
     bash -c "
@@ -209,6 +216,16 @@ spec_mde_args_grep_filter_expect () {
   [[ -n $status ]]
 }
 
+spec_mde_dname_doc_blocks_expect () {
+  BATS_SAFE=_
+  spec_mde_args_expect "$1" \
+   "${@:2:$(($#-2))}" \
+   --list-blocks-message dname \
+   --list-blocks-type 3 \
+   --list-blocks \
+  "${!#}"
+}
+
 spec_mde_xansi_dname_doc_blocks_expect () {
   BATS_OUTPUT_FILTER=A
   BATS_SAFE=_

data/bats/variable-expansion-multiline.bats

@@ -0,0 +1,8 @@
+#!/usr/bin/env bats
+
+load 'test_helper'
+
+@test '' {
+  spec_mde_xansi_dname_doc_blocks_expect docs/dev/variable-expansion-multiline.md \
+   'Genus2 = Pongo_Pongo_UX block:_Genus2=Pongo_Pongo_Command substitution:_Genus2 hex: 00000000  50 6f 6e 67 6f 0a 50 6f  6e 67 6f                 |Pongo.Pongo|_0000000b_Command substitution:_Genus2 text: Pongo_Pongo_Command substitution:_Gemfile_Gemfile.lock_Variable expansion:_Genus2 text: Pongo_Pongo'
+}

data/bats/variable-expansion.bats

@@ -4,7 +4,7 @@ load 'test_helper'
 
 @test 'Variable expansion - default' {
   spec_mde_xansi_dname_doc_blocks_expect docs/dev/variable-expansion.md \
-   'EVIDENCE_SOURCE is:_SOURCE is:_SOURCE is:_| SOURCE |_| ------ |__name_with_${SOURCE}_in_name_load: file_.sh_SOURCES'
+   'EVIDENCE_SOURCE is:_SOURCE is:_SOURCE is: _| SOURCE |_| ------ |__name_with_${SOURCE}_in_name_load: file_.sh_SOURCES'
 }
 
 @test 'Variable expansion - LINK_LOAD_SOURCE' {

data/bin/tab_completion.sh

@@ -12,10 +12,6 @@ __filedirs_all()
   COMPREPLY='.'
 }
 
-_mde_echo_version() {
-  echo "2.8.2"
-}
-
 _mde() {
   local cur prev opts
   cur="${COMP_WORDS[COMP_CWORD]}"
@@ -213,4 +209,3 @@ _mde() {
 }
 
 complete -o filenames -o nospace -F _mde mde
-# _mde_echo_version

data/bin/tab_completion.sh.erb

@@ -12,10 +12,6 @@ __filedirs_all()
   COMPREPLY='.'
 }
 
-_mde_echo_version() {
-  echo "<%= MarkdownExec::VERSION %>"
-}
-
 _mde() {
   local cur prev opts
   cur="${COMP_WORDS[COMP_CWORD]}"
@@ -104,4 +100,3 @@ _mde() {
 }
 
 complete -o filenames -o nospace -F _mde mde
-# _mde_echo_version

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

@@ -0,0 +1,80 @@
+/ automatic block loads first allowed
+```ux :[document_ux_SPECIES]
+allowed:
+- Pongo tapanuliensis
+- Histiophryne psychedelica
+default: :allowed
+name: SPECIES
+```
+/ automatic block loads first line in output of exec
+```ux :[document_ux_GENUS]
+allowed: :exec
+default: :allowed
+exec: echo "Pongo\nHistiophryne psychedelica"
+name: GENUS
+```
+/ executed block presents a menu of the allowed list
+```ux :[FAMILY]
+allowed:
+- Hominidae
+- Antennariidae
+name: FAMILY
+```
+/ automatic block loads default value that is not in allowed list
+```ux :[document_ux_ORDER]
+allowed:
+- Primates
+- Lophiiformes
+default: Click to select...
+name: ORDER
+```
+/ automatic block loads default value, not in allowed list from echo
+```ux :[document_ux_CLASS]
+allowed: :echo
+default: Click to select...
+echo: |
+  Mammalia
+  Actinopterygii
+name: CLASS
+```
+/ executed block presents a menu of the lines in the output of exec
+```ux :[YEAR_DISCOVERED]
+allowed: :exec
+exec: echo "2017\n2009"
+name: YEAR_DISCOVERED
+```
+/ automatic block presents a menu of the lines in the output of echo
+```ux :[document_ux_NAME]
+allowed: :echo
+default: :allowed
+echo: |
+  Tapanuli Orangutan
+  Psychedelic Frogfish
+name: NAME
+```
+/
+/1. Tapanuli Orangutan
+/
+/* Species: Pongo tapanuliensis
+/* Genus: Pongo
+/* Family: Hominidae
+/* Order: Primates
+/* Class: Mammalia
+/* Phylum: Chordata
+/* Kingdom: Animalia
+/* Domain: Eukaryota
+/* Year: 2017
+/
+/2. Psychedelic Frogfish
+/
+/* Species: Histiophryne psychedelica
+/* Genus: Histiophryne
+/* Family: Antennariidae
+/* Order: Lophiiformes
+/* Class: Actinopterygii
+/* Phylum: Chordata
+/* Kingdom: Animalia
+/* Domain: Eukaryota
+/* Year: 2009
+/
+@import bats-document-configuration.md

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

@@ -0,0 +1,21 @@
+/ a UX block that requires a shell block and another UX block
+``` :(shell)
+ENTITY='Pongo tapanuliensis,Pongo'
+```
+```ux :[SPECIES] +(shell) +(GENUS)
+echo: "${ENTITY%%,*}"
+name: SPECIES
+```
+/ required ux block requires another
+```ux :(GENUS) +[NAME]
+echo: "${ENTITY##*,}"
+name: GENUS
+readonly: true
+```
+/ executed in context of prior ux blocks, uses their values
+```ux :[NAME]
+echo: "$SPECIES - $GENUS"
+name: NAME
+readonly: true
+```
+@import bats-document-configuration.md