markdown_exec 2.8.5 → 3.0.0

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

data/lib/block_cache.rb

@@ -0,0 +1,197 @@
+#!/usr/bin/env -S bundle exec ruby
+# frozen_string_literal: true
+
+# encoding=utf-8
+
+# a ruby class contains a list of objects
+class BlockCache
+  attr_accessor :cache
+
+  def initialize(cache = [])
+    @cache = cache
+  end
+
+  # Find an object by id
+  def find_by_id(id)
+    @cache.find { |obj| obj.id == id }
+  end
+
+  # Get an existing object by id or create a new one
+  def get_or_create(id, new_obj_proc = nil)
+    obj = find_by_id(id)
+    return obj if obj
+
+    # Create a new object if not found
+    if block_given?
+      obj = yield(id)
+    elsif new_obj_proc
+      obj = new_obj_proc.call(id)
+    else
+      raise ArgumentError, 'Block or proc required to create new object'
+    end
+
+    @cache << obj
+    obj
+  end
+
+  # Add a new object to the cache
+  def add(obj)
+    raise ArgumentError,
+          'Object must respond to id method' unless obj.respond_to?(:id)
+
+    # Replace existing object with same id
+    if (existing = find_by_id(obj.id))
+      @cache[@cache.index(existing)] = obj
+    else
+      @cache << obj
+    end
+    obj
+  end
+
+  # Remove an object from the cache by id
+  def remove(id)
+    @cache.delete_if { |obj| obj.id == id }
+  end
+
+  # Clear the entire cache
+  def clear
+    @cache = []
+  end
+
+  # Get the size of the cache
+  def size
+    @cache.size
+  end
+end
+
+return unless $PROGRAM_NAME == __FILE__
+
+require 'bundler/setup'
+Bundler.require(:default)
+
+require 'minitest/autorun'
+require 'mocha/minitest'
+
+# require_relative 'ww'
+
+# A simple dummy object that responds to #id
+class DummyObject
+  attr_reader :id
+
+  def initialize(id)
+    @id = id
+  end
+end
+
+# Unit tests for the BlockCache class
+#
+# This test suite verifies correct behavior of:
+# - initialization (with and without initial cache)
+# - finding objects by id
+# - getting or creating objects via block or proc
+# - adding objects (including replacing existing ones)
+# - removing objects by id
+# - clearing the cache
+# - reporting cache size
+class TestBlockCache < Minitest::Test
+  def setup
+    @obj1 = DummyObject.new(1)
+    @obj2 = DummyObject.new(2)
+    @initial_cache = [@obj1]
+    @cache = BlockCache.new(@initial_cache.dup)
+  end
+
+  def test_initialize_defaults_to_empty_array
+    empty_cache = BlockCache.new
+    assert_equal [], empty_cache.cache
+  end
+
+  def test_initialize_with_provided_array
+    assert_equal @initial_cache, @cache.cache
+  end
+
+  def test_find_by_id_returns_matching_object
+    assert_equal @obj1, @cache.find_by_id(1)
+  end
+
+  def test_find_by_id_returns_nil_when_not_found
+    assert_nil @cache.find_by_id(999)
+  end
+
+  def test_get_or_create_returns_existing_object
+    found = @cache.get_or_create(1) { |id| DummyObject.new(id) }
+    assert_equal @obj1, found
+    assert_equal 1, @cache.size
+  end
+
+  def test_get_or_create_creates_with_block
+    new_obj = @cache.get_or_create(3) { |id| DummyObject.new(id) }
+    assert_instance_of DummyObject, new_obj
+    assert_equal 3, new_obj.id
+    assert_includes @cache.cache, new_obj
+    assert_equal 2, @cache.size
+  end
+
+  def test_get_or_create_creates_with_proc
+    factory = proc { |id| DummyObject.new(id * 10) }
+    new_obj = @cache.get_or_create(5, factory)
+    assert_instance_of DummyObject, new_obj
+    assert_equal 50, new_obj.id
+    assert_equal new_obj, @cache.find_by_id(50)
+    assert_equal 2, @cache.size
+  end
+
+  def test_get_or_create_raises_without_block_or_proc
+    assert_raises(ArgumentError) do
+      @cache.get_or_create(7)
+    end
+  end
+
+  def test_add_appends_new_object
+    result = @cache.add(@obj2)
+    assert_equal @obj2, result
+    assert_equal 2, @cache.size
+    assert_equal [@obj1, @obj2], @cache.cache
+  end
+
+  def test_add_replaces_existing_object_with_same_id
+    replacement = DummyObject.new(1)
+    result = @cache.add(replacement)
+    assert_equal replacement, result
+    assert_equal 1, @cache.size
+    assert_equal replacement, @cache.find_by_id(1)
+  end
+
+  def test_add_raises_for_object_without_id_method
+    invalid = Object.new
+    assert_raises(ArgumentError) do
+      @cache.add(invalid)
+    end
+  end
+
+  def test_remove_deletes_object_by_id
+    @cache.add(@obj2)
+    @cache.remove(1)
+    assert_nil @cache.find_by_id(1)
+    assert_equal 1, @cache.size
+    assert_equal [@obj2], @cache.cache
+  end
+
+  def test_remove_nonexistent_id_leaves_cache_unchanged
+    original = @cache.cache.dup
+    @cache.remove(999)
+    assert_equal original, @cache.cache
+  end
+
+  def test_clear_empties_the_cache
+    @cache.clear
+    assert_equal [], @cache.cache
+    assert_equal 0, @cache.size
+  end
+
+  def test_size_returns_number_of_cached_objects
+    assert_equal 1, @cache.size
+    @cache.add(@obj2)
+    assert_equal 2, @cache.size
+  end
+end