markdown_exec 2.8.3 → 2.8.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: dfa1920cdbee40306492b597411dff701777c0ac158dc969a02d3ac2db7351b2
-  data.tar.gz: fe5c8229410f4263b9aa394c99f1d1be61b6a119684ca5c29e8f0a7851d4391a
+  metadata.gz: 7ace0bdaa8d2925a4274a4cfc039fdde5e9aaaf8bfbd761f21e0679417f71062
+  data.tar.gz: 0a9f38be8b322be828fe28cd19441da7a9bb032dd739aaa73ba0526456251503
 SHA512:
-  metadata.gz: e2566c1f28e9eb898c490aa9076d762fe76b8f2092a1b6b4a9d37ff889d02bea021cf84fad63c2f9598d7ba17d7a6ac63840d49958d6dfad9f45b57250a4d3b7
-  data.tar.gz: 44a40a84a65eb477951b6929307837cc8493e70b9fe76b5065bb86e54b2b10f07241de175552132979ddb00b5c8bdce031d64688189b78f5da9f953e74399f4a
+  metadata.gz: b0c0c4eea966bad0e29e0957e68049cfee1c61bd730fab880f63ea1501cba153dd1592ef415142a91a9aecd09802cf0bb48eac36607964b97ce372c9b249536f
+  data.tar.gz: d254a22305dd0d57f2048271d40f15d22b6f2473971cc3c398a6479d439fe80255f0dabb7cb94f9df8c21bc6214b2f60b5238c102e3048cbdbd3dd3dd18b693a

data/CHANGELOG.md

@@ -1,5 +1,31 @@
 # 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

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    markdown_exec (2.8.3)
+    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

@@ -13,8 +13,8 @@ load 'test_helper'
    'VAR=markdown_exec_VAR=markdown_exec_IAB='
 }
 
-@test 'selected block' {
+@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=1414'
+   '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-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/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/line-decor-dynamic.bats

@@ -4,5 +4,5 @@ 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[38;2;200;200;33m\e[48;2;60;60;32mSpecies\e[0m'
+   $'\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 "

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/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

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

@@ -0,0 +1,72 @@
+/ This automatic block sets multiple variables and displays the first variable.
+```ux :[document_ux_BASENAME]
+default: :echo
+echo:
+  BASENAME: "$(basename `pwd`)"
+  DOCUMENTS: "${BASENAME%%_*}"
+  OPERATION: "${BASENAME##*_}"
+name: BASENAME
+readonly: true
+```
+/ This block displays the second variable in the first block.
+```ux :[DOCUMENTS]
+name: DOCUMENTS
+readonly: true
+```
+/ This block displays the third variable in the first block.
+```ux :[OPERATION]
+name: OPERATION
+readonly: true
+```
+/ Multiple UX blocks to set many variables for a specific name.
+```ux
+echo:
+  Species: Pongo tapanuliensis
+  Genus: Pongo
+  Family: Hominidae
+  Order: Primates
+  Class: Mammalia
+  Phylum: Chordata
+  Kingdom: Animalia
+  Domain: Eukaryota
+  Year_Discovered: 2017
+menu_format: 'Load %{name}'
+name: Tapanuli Orangutan
+```
+```ux
+echo:
+  Species: Histiophryne psychedelica
+  Genus: Histiophryne
+  Family: Antennariidae
+  Order: Lophiiformes
+  Class: Actinopterygii
+  Phylum: Chordata
+  Kingdom: Animalia
+  Domain: Eukaryota
+  Year_Discovered: 2009
+menu_format: 'Load %{name}'
+name: Psychedelic Frogfish
+```
+/ Start a table to format the output of UX blocks
+| Variable| Value
+| -| -
+/ A read-only variable in a UX block in a table
+```ux
+menu_format: '| %{name}| ${%{name}}'
+name: Species
+readonly: true
+```
+/ A table row displays one variable in a table
+| Genus| ${Genus}
+/ An editable variable in a UX block in a table
+```ux
+menu_format: '| %{name}| ${%{name}}'
+name: Family
+```
+@import bats-document-configuration.md
+```opts :(document_opts)
+# menu_ux_row_format: '| %{name}| ${%{name}}'
+screen_width: 64
+table_center: false
+ux_auto_load_force_default: true
+```

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

@@ -0,0 +1,21 @@
+/ a UX block 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

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

@@ -0,0 +1,5 @@
+/ automatic block is invalid YAML
+```ux :[document_ux_SPECIES]
+invalid
+```
+@import bats-document-configuration.md

data/docs/dev/indented-block-type-vars.md

@@ -0,0 +1,6 @@
+/ All lines of an indented block must have equal indents.
+  ```vars
+  Species: Pongo tapanuliensis
+  Genus: Pongo
+  ```
+@import bats-document-configuration.md

data/docs/dev/line-decor-dynamic.md

@@ -4,6 +4,7 @@
 @import bats-document-configuration.md
 ```opts :(document_opts)
 line_decor_pre:
-  - :color_method: :ansi_38_2_200_200_33__48_2_60_60_32__0
+  # bold italicized bright yellow text on light yellow background
+  - :color_method: :ansi_1__3__38_2_200_200_33__48_2_60_60_32__22_23_0
     :pattern: '%([^_]{0,64})%'
 ```

data/docs/dev/variable-expansion-multiline.md

@@ -0,0 +1,31 @@
+/ assign a multiline string
+```vars :(document_vars)
+Genus2: |
+  Pongo
+  Pongo
+```
+/
+/ display the variable
+__UX block__:
+```ux
+name: Genus2
+readonly: true
+```
+/
+/ Confirm the string contains a newline `0a`
+__Command substitution__:
+Genus2 hex: $(printf "$Genus2" | hexdump -C)
+/
+/ output with substitution
+__Command substitution__:
+Genus2 text: $(printf "$Genus2")
+/
+/ output with substitution
+__Command substitution__:
+$(ls -1 G*)
+/
+/ output with expansion
+__Variable expansion__:
+Genus2 text: ${Genus2}
+/
+@import bats-document-configuration.md

data/lib/ansi_formatter.rb

@@ -1,4 +1,3 @@
-#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 # encoding=utf-8

data/lib/ansi_string.rb

@@ -20,7 +20,7 @@ class AnsiString < String
         segments[0..-2].each do |segment|
           codes += "\033[#{segment.split('_').join(';')}m"
         end
-        codes += self.to_s
+        codes += to_s
         codes += "\033[#{segments.last.split('_').join(';')}m"
         self.class.new(codes)
       when /^fg_bg_rgb_/

data/lib/array.rb

@@ -1,4 +1,3 @@
-#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 # encoding=utf-8

data/lib/array_util.rb

@@ -1,4 +1,3 @@
-#!/usr/bin/env ruby
 # frozen_string_literal: true
 
 # encoding=utf-8