markdown_exec 2.8.4 → 3.0.0

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

@@ -1,6 +1,5 @@
 / This automatic block sets VAR and displays the current value in the menu.
 ```ux :[document_ux_VAR]
-default: :echo
 echo: $(basename `pwd`)
 name: VAR
 ```
@@ -10,11 +9,14 @@ menu_with_inherited_lines: true
 ```
 / This block is not visible. Execute to set a new value, displayed by the block above.
 ```ux :(VAR_has_count)
+init: false
 echo: $(basename `pwd` | wc -c)
+force: false
 name: VAR
 ```
 / This block is visible. Execute to set a new value, displayed by the block above.
 ```ux :[IAB_has_count]
+init: false
 echo: $VAR$VAR
 name: IAB
 ```

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

@@ -1,20 +1,21 @@
 / auto-load block, does not execute command to calculate
 / click block to calculate
 ```ux :[document_ux0]
+init: ''
 exec: basename $(pwd)
 name: ux0
 ```
 / auto-load block and execute command to calculate
 / click block to recalculate
 ```ux :[document_ux1]
-default: Unknown
+init: Unknown
 exec: basename $(pwd)
 name: ux1
 ```
 / auto-load block and execute command to calculate
 / click block to recalculate
 ```ux :[document_ux2]
-default: :exec
+act: :exec
 exec: basename $(pwd)
 name: ux2
 ```
@@ -24,7 +25,6 @@ name: ux2
 val () { basename $(pwd) ; }
 ```
 ```ux :[document_ux3] +(bash3)
-default: :exec
 exec: val
 name: ux3
 ```
@@ -32,7 +32,6 @@ name: ux3
 / output of execution is validated/parsed
 / parsing is transformed
 ```ux :[document_ux4]
-default: :exec
 exec: basename $(pwd)
 name: ux4
 transform: "Xform: '%{name}'"

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

@@ -4,17 +4,20 @@ ENTITY='Pongo tapanuliensis,Pongo'
 ```
 ```ux :[SPECIES] +(shell) +(GENUS)
 echo: "${ENTITY%%,*}"
+init: false
 name: SPECIES
 ```
 / required ux block requires another
 ```ux :(GENUS) +[NAME]
 echo: "${ENTITY##*,}"
+init: false
 name: GENUS
 readonly: true
 ```
 / executed in context of prior ux blocks, uses their values
 ```ux :[NAME]
 echo: "$SPECIES - $GENUS"
+init: false
 name: NAME
 readonly: true
 ```

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

@@ -1,32 +1,23 @@
-/ an automatic UX block requires a shell block and another UX block
+/ This is an hidden shell block that is required by UX blocks.
 ``` :(shell)
 ENTITY='Pongo tapanuliensis,Pongo'
 ```
-```ux :[document_ux_SPECIES] +(shell) +[ux_GENUS]
-default: :exec
-exec: echo "${ENTITY%%,*}"
+```ux +(shell)
+echo: "${ENTITY%%,*}"
 name: SPECIES
-transform: :chomp
 ```
-/ required ux block requires another
-```ux :[ux_GENUS] +[ux_NAME]
-default: :exec
-exec: echo "${ENTITY##*,}"
+```ux +(shell)
+echo: "${ENTITY##*,}"
 name: GENUS
-transform: :chomp
 ```
 / executed in context of prior ux blocks, uses their initial values
-```ux :[ux_NAME]
-default: :exec
-exec: echo "$SPECIES - $GENUS"
+```ux
+echo: "$SPECIES - $GENUS"
 name: NAME
-transform: :chomp
 ```
 / executed after other ux blocks, uses their initial values
-```ux :[document_ux_NAME2]
-default: :exec
-exec: echo "$NAME"
+```ux
+echo: "$NAME"
 name: NAME2
-transform: :chomp
 ```
 @import bats-document-configuration.md

data/docs/dev/{block-type-ux-preconditions.md → block-type-ux-required-variables.md}

@@ -1,9 +1,8 @@
 / an automatic UX block that has a precondition that must be met before it is executed
 ```ux :[document_ux_SPECIES]
-default: :exec
 exec: printf "$MISSING_VARIABLE"
 name: SPECIES
-preconditions:
+required:
 - MISSING_VARIABLE
 ```
 @import bats-document-configuration.md

data/docs/dev/block-type-ux-row-format.md

@@ -10,7 +10,7 @@ allowed:
 - Pongo tapanuliensis
 - Histiophryne psychedelica
 - Phyllopteryx dewysea
-default: Pongo tapanuliensis
+init: Pongo tapanuliensis
 name: Species
 prompt: New species?
 ```
@@ -24,7 +24,6 @@ allowed:
 - 1. Pongo
 - 2. Histiophryne
 - 3. Phyllopteryx
-default: Pongo
 menu_format: "| Name: %{name}| Value: ${%{name}}| Prompt: %{prompt}"
 name: Genus
 prompt: New genus?
@@ -35,13 +34,13 @@ validate: |
 / default
 / auto-load default value
 ```ux :[document_ux_Family]
-default: Hominidae
+init: Hominidae
 name: Family
 ```
 @import bats-document-configuration.md
 ```opts :(document_opts)
 menu_ux_row_format: '| %{name}| ${%{name}}| %{prompt}'
-screen_width: 64
+screen_width: 72
 table_center: true
 ux_auto_load_force_default: true
 ```

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

@@ -0,0 +1,57 @@
+/ 1. Simple variable display and edit:
+```ux
+name: USER_NAME
+prompt: Enter your name
+default: Guest
+```
+/Behavior: Displays the USER_NAME variable. When clicked, prompts for input with "Enter your name" and defaults to "Guest" if no input is provided.
+/
+/2. Command output initialization:
+```ux
+name: CURRENT_DIR
+init: :exec
+exec: basename $(pwd)
+transform: :chomp
+```
+/Behavior: Initializes CURRENT_DIR with the output of the `pwd` command when the document loads.
+/
+/3. Echo-based initialization:
+```ux
+name: SHELL_VERSION
+init: :echo
+echo: $SHELL
+```
+/Behavior: Sets SHELL_VERSION to the value of the $SHELL environment variable when the document loads.
+/
+/4. Selection from allowed values:
+```ux
+name: ENVIRONMENT
+allow:
+  - development
+  - staging
+  - production
+prompt: Select environment
+```
+/Behavior: When activated, presents a menu to select from development, staging, or production environments.
+/
+/## Validation Examples
+/
+/5. Email validation:
+```ux
+name: USER_EMAIL
+prompt: Enter email address
+validate: '(?<local>[^@]+)@(?<domain>[^@]+)'
+transform: '%{local}@%{domain}'
+```
+/Behavior: Validates input as an email address, capturing local and domain parts. The transform ensures proper formatting.
+/
+/6. Version number validation:
+```ux
+name: VERSION
+prompt: Enter version number
+validate: '(?<major>\d+)\.(?<minor>\d+)\.(?<patch>\d+)'
+transform: '%{major}.%{minor}.%{patch}'
+```
+/Behavior: Ensures input follows semantic versioning format (e.g., 1.2.3).
+/
+@import bats-document-configuration.md

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

@@ -1,7 +1,6 @@
 :::
 **Execution output has a trailing newline.**
 ```ux :[document_ux_transform_0]
-default: :exec
 exec: basename $(pwd)
 name: Var0
 ```
@@ -9,7 +8,6 @@ $(echo -n "$Var0" | hexdump -C)
 :::
 **With validate and transform, output has no newline.**
 ```ux :[document_ux_transform_1]
-default: :exec
 exec: basename $(pwd)
 name: Var1
 transform: '%{name}'
@@ -19,7 +17,6 @@ $(echo -n "$Var1" | hexdump -C)
 :::
 **With transform `:chomp`, output has no newline.**
 ```ux :[document_ux_transform_2]
-default: :exec
 exec: basename $(pwd)
 name: Var2
 transform: :chomp
@@ -28,7 +25,6 @@ $(echo -n "$Var2" | hexdump -C)
 :::
 **With transform `:upcase`, output is in upper case w/ newline.**
 ```ux :[document_ux_transform_3]
-default: :exec
 exec: basename $(pwd)
 name: Var3
 transform: :upcase

data/docs/dev/command-substitution-options.md

@@ -0,0 +1,61 @@
+/ command substitution options to use different patterns
+/
+@import bats-document-configuration.md
+/
+```vars :(document_vars)
+Common_Name: Tapanuli Orangutan
+Species: Pongo tapanuliensis
+```
+/
+::: Command substitution
+
+The current value of environment variable `Common_Name` is displayed using two different operators.
+The command `echo $SHLVL` is executed via command substitution, using two different operators.
+
+| Operator| Variable Expansion| Command Substitution
+| -| -| -
+| $| ${Common_Name}| $(echo $Species)
+| @| @{Common_Name}| @(echo $Species)
+
+::: Toggle between operators.
+
+/| MDE Option| Value
+/| -| -
+/| command_substitution_regexp| &{command_substitution_regexp}
+/| menu_ux_row_format| &{menu_ux_row_format}
+/| variable_expansion_regexp| &{variable_expansion_regexp}
+
+/ This block requires a hidden block.
+```opts :operator_$ +(operator_$2)
+command_substitution_regexp: '(?<expression>\$\((?<command>([^()]*(\([^()]*\))*[^()]*)*)\))'
+```
+```opts :(operator_$2)
+menu_ux_row_format: '%{name}=${%{name}}'
+variable_expansion_regexp: '(?<expression>\${(?<variable>[A-Z0-9a-z_]+)})'
+```
+
+```opts :operator_@
+command_substitution_regexp: '(?<expression>@\((?<command>([^()]*(\([^()]*\))*[^()]*)*)\))'
+menu_ux_row_format: '%{name}=@{%{name}}'
+variable_expansion_regexp: '(?<expression>@{(?<variable>[A-Z0-9a-z_]+)})'
+```
+
+```opts :(both)
+command_substitution_regexp: '(?<expression>[\$\@]\((?<command>([^()]*(\([^()]*\))*[^()]*)*)\))'
+menu_ux_row_format: '%{name}=${%{name}}'
+variable_expansion_regexp: '(?<expression>[\$\@]{(?<variable>[A-Z0-9a-z_]+)})'
+```
+/
+/ Require the block that sets @ as the operator.
+```opts :(document_opts) +operator_@
+divider4_collapsible: false
+heading1_center: false
+heading2_center: false
+heading3_center: false
+menu_final_divider:
+menu_for_saved_lines: false
+menu_initial_divider:
+menu_vars_set_format:
+screen_width: 64
+table_center: false
+```

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

@@ -1,4 +1,5 @@
 / All lines of an indented block must have equal indents.
+/ The block is indented with 2 spaces.
   ```vars
   Species: Pongo tapanuliensis
   Genus: Pongo

data/docs/dev/menu-pagination-indent.md

@@ -0,0 +1,123 @@
+# Menu pagination indent
+
+| Option| Value
+| -| -
+| select_page_height| &{select_page_height}
+| screen_width| &{screen_width}
+
+/ An Opts block
+::: Indented with 2 spaces
+  ```opts
+  option1: 1
+  option2: 2
+  option3: 3
+  option4: 4
+  ```
+::: Indented with 4 spaces
+    ```opts
+    option1: 1
+    option2: 2
+    option3: 3
+    option4: 4
+    ```
+::: Indented with 1 tab
+	```opts
+	option1: 1
+	option2: 2
+	option3: 3
+	option4: 4
+	```
+
+/ A shell block
+::: Indented with 2 spaces
+  ```
+  : 1
+  : 2
+  : 3
+  : 4
+  ```
+::: Indented with 4 spaces
+    ```
+    : 1
+    : 2
+    : 3
+    : 4
+    ```
+::: Indented with 1 tab
+	```
+	: 1
+	: 2
+	: 3
+	: 4
+	```
+
+| Variable| Value
+| -| -
+| VARIABLE| ${VARIABLE}
+
+/ An UX block
+::: Indented with 2 spaces
+  ```ux
+  init: false
+  echo:
+    VARIABLE1: 1
+    VARIABLE2: 2
+    VARIABLE3: 3
+    VARIABLE4: 4
+  name: VARIABLE1
+  ```
+::: Indented with 4 spaces
+    ```ux
+    init: false
+    echo:
+      VARIABLE1: 1
+      VARIABLE2: 2
+      VARIABLE3: 3
+      VARIABLE4: 4
+    name: VARIABLE1
+    ```
+::: Indented with 1 tab
+	```ux
+	init: false
+	echo:
+	  VARIABLE1: 1
+	  VARIABLE2: 2
+	  VARIABLE3: 3
+	  VARIABLE4: 4
+	name: VARIABLE1
+	```
+
+
+| Variable| Value
+| -| -
+| VARIABLE1| ${VARIABLE1}
+| VARIABLE2| ${VARIABLE2}
+
+/ A VARS block
+::: Indented with 2 spaces
+  ```vars
+  VARIABLE1: 1
+  VARIABLE2: 2
+  VARIABLE3: 3
+  VARIABLE4: 4
+  ```
+::: Indented with 4 spaces
+    ```vars
+    VARIABLE1: 1
+    VARIABLE2: 2
+    VARIABLE3: 3
+    VARIABLE4: 4
+    ```
+::: Indented with 1 tab
+	```vars
+	VARIABLE1: 1
+	VARIABLE2: 2
+	VARIABLE3: 3
+	VARIABLE4: 4
+	```
+
+@import bats-document-configuration.md
+```opts :(document_opts)
+screen_width: 48
+select_page_height: 12
+```

data/docs/dev/menu-pagination.md

@@ -0,0 +1,111 @@
+# Menu pagination
+
+::: ˆ
+MDE detects the screen's dimensions: height (lines) and width (characters)
+
+| Option| Value
+| -| -
+| select_page_height| &{select_page_height}
+| screen_width| &{screen_width}
+
+Normal document text is displayed as disabled menu lines. The width of these lines is limited according to the screen's width.
+
+::: ˆ
+/ A sequence of text blocks
+: 1
+: 2
+: 3
+: 4
+: 5
+: 6
+: 7
+: 8
+: 9
+: 10
+: 11
+: 12
+
+::: ˆ
+/ A shell block
+```
+: 1
+: 2
+: 3
+: 4
+: 5
+: 6
+: 7
+: 8
+: 9
+: 10
+: 11
+: 12
+```
+::: ˆ
+/ An Opts block
+```opts
+option1: 1
+option2: 2
+option3: 3
+option4: 4
+option5: 5
+option6: 6
+option7: 7
+option8: 8
+option9: 9
+option10: 10
+option11: 11
+option12: 12
+```
+::: ˆ
+
+| Variable| Value
+| -| -
+| VARIABLE1| ${VARIABLE1}
+| VARIABLE2| ${VARIABLE2}
+
+/ A Vars block
+```vars
+VARIABLE1: 1
+VARIABLE2: 2
+VARIABLE3: 3
+VARIABLE4: 4
+VARIABLE5: 5
+VARIABLE6: 6
+VARIABLE7: 7
+VARIABLE8: 8
+VARIABLE9: 9
+VARIABLE10: 10
+VARIABLE11: 11
+VARIABLE12: 12
+```
+::: ˆ
+
+| Variable| Value
+| -| -
+| VARIABLE| ${VARIABLE}
+
+/ An UX block
+```ux
+init: false
+echo:
+  VARIABLE1: 1
+  VARIABLE2: 2
+  VARIABLE3: 3
+  VARIABLE4: 4
+  VARIABLE5: 5
+  VARIABLE6: 6
+  VARIABLE7: 7
+  VARIABLE8: 8
+  VARIABLE9: 9
+  VARIABLE10: 10
+  VARIABLE11: 11
+  VARIABLE12: 12
+name: VARIABLE1
+```
+::: ˆ
+@import bats-document-configuration.md
+```opts :(document_opts)
+screen_width: 48
+select_page_height: 12
+```

data/docs/dev/option-expansion.md

@@ -0,0 +1,10 @@
+
+| Option| Description| Value Length| Value| Default
+| -| -| -| -| -
+| screen_width| &{screen_width.description}| &{screen_width.length}| &{screen_width}| &{screen_width.default}
+| table_center| &{table_center.description}| &{table_center.length}| &{table_center}| &{table_center.default}
+@import bats-document-configuration.md
+```opts :(document_opts)
+screen_width: 64
+table_center: false
+```

data/lib/ansi_formatter.rb

@@ -116,6 +116,8 @@ class AnsiFormatter
   # @param default [String] Default color method to use if color_sym is not found in @options.
   # @return [String] The string with the applied color method.
   def string_send_color(string, color_sym, default: 'plain')
+    return string.to_s unless @options.fetch(:ansi_formatter_color, true)
+
     color_method = @options.fetch(color_sym, default).to_sym
     AnsiString.new(string.to_s).send(color_method)
   end