markdown_exec 2.8.4 → 3.0.0

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

data/lib/command_result.rb

@@ -0,0 +1,57 @@
+#!/usr/bin/env -S bundle exec ruby
+# frozen_string_literal: true
+
+# encoding=utf-8
+
+# Encapsulates the result of executing a system command, storing its output,
+# exit status, and any number of additional, arbitrary attributes.
+#
+# @example
+#   result = CommandResult.new(stdout: output, exit_status: $?.exitstatus, duration: 1.23)
+#   result.stdout        # => output
+#   result.exit_status   # => 0
+#   result.duration      # => 1.23
+#   result.new_field = 42
+#   result.new_field     # => 42
+#   result.success?      # => true
+class CommandResult
+  # @param attributes [Hash{Symbol=>Object}] initial named attributes
+  def initialize(**attributes)
+    @attributes = {}
+    @attributes[:exit_status] = 0
+    @attributes[:stdout] = ''
+    attributes.each { |name, value| @attributes[name] = value }
+  end
+
+  def failure?
+    !success?
+  end
+
+  # @return [Boolean] true if the exit status is zero
+  def success?
+    exit_status.zero?
+  end
+
+  def method_missing(name, *args)
+    key = name.to_s.chomp('=').to_sym
+
+    if name.to_s.end_with?('=') # setter
+      @attributes[key] = args.first
+    elsif attribute?(name) # getter
+      @attributes[name]
+    else
+      super
+    end
+  end
+
+  def respond_to_missing?(name, include_private = false)
+    key = name.to_s.chomp('=').to_sym
+    attribute?(key) || super
+  end
+
+  private
+
+  def attribute?(name)
+    @attributes.key?(name)
+  end
+end

data/lib/constants.rb

@@ -125,3 +125,21 @@ class TtyMenu
   ENABLE = nil
   DISABLE = ''
 end
+
+class ExportValueSource
+  ALLOW = ':allow'
+  DEFAULT = ':default'
+  ECHO = ':echo'
+  EDIT = ':edit'
+  EXEC = ':exec'
+  FALSE = false
+end
+
+class UxActSource
+  ALLOW = :allow
+  DEFAULT = :default
+  ECHO = :echo
+  EDIT = :edit
+  EXEC = :exec
+  FALSE = 'false'
+end

data/lib/error_reporting.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+# encoding=utf-8
+
+##
+# Module providing standardized error‐reporting:
+# logs either an Exception’s details or a simple
+# string message—optionally with context—and then
+# re‐raises either the original Exception or a new
+# RuntimeError for string messages.
+#
+# Including this module gives you:
+#  • instance method  → report_and_reraise(...)
+#  • class method     → report_and_reraise(...)
+module ErrorReporting
+  def self.included(base)
+    base.extend(self)
+  end
+
+  def report_and_reraise(error_or_message, context: nil)
+    if error_or_message.is_a?(Exception)
+      header = +"#{error_or_message.class}: #{error_or_message.message}"
+      header << " (#{context})" if context
+
+      ww header
+      ww error_or_message.backtrace.join("\n") if error_or_message.backtrace
+
+      raise error_or_message
+    else
+      header = +error_or_message.to_s
+      header << " (#{context})" if context
+
+      ww header
+
+      raise error_or_message.to_s
+    end
+  end
+end

data/lib/evaluate_shell_expressions.rb

@@ -10,12 +10,11 @@ class EvaluateShellExpression
 end
 
 def evaluate_shell_expressions(initial_code, expressions, shell: '/bin/bash',
-                               key_format: '%%<%s>',
-                               initial_code_required: false)
+                               initial_code_required: false,
+                               occurrence_expressions: nil)
   # !!p initial_code expressions key_format shell
   return if (initial_code_required && (initial_code.nil? || initial_code.empty?)) ||
-            expressions.nil? || expressions.empty? ||
-            key_format.nil? || key_format.empty?
+            expressions.nil? || expressions.empty?
 
   # token to separate output
   token = "__TOKEN__#{Time.now.to_i}__"
@@ -28,7 +27,7 @@ def evaluate_shell_expressions(initial_code, expressions, shell: '/bin/bash',
   end
 
   # Execute
-  stdout_str, stderr_str, status = Open3.capture3(shell, '-c', script)
+  stdout_str, _, status = Open3.capture3(shell, '-c', script)
 
   unless status.success?
     return EvaluateShellExpression::StatusFail
@@ -40,7 +39,7 @@ def evaluate_shell_expressions(initial_code, expressions, shell: '/bin/bash',
   unless part.empty?
     part[1..-1].tap do |output_parts|
       expressions.each_with_index do |(key, _expression), index|
-        result_hash[format(key_format, key)] = output_parts[index].chomp
+        result_hash[occurrence_expressions[key]] = output_parts[index].chomp
       end
     end
   end
@@ -54,7 +53,6 @@ require 'bundler/setup'
 Bundler.require(:default)
 
 require 'minitest/autorun'
-require 'open3'
 
 class TestShellExpressionEvaluator < Minitest::Test
   def setup
@@ -66,7 +64,11 @@ class TestShellExpressionEvaluator < Minitest::Test
 
   def test_single_expression
     expressions = { 'greeting' => "echo 'Hello, World!'" }
-    result = evaluate_shell_expressions(@initial_code, expressions)
+    occurrence_expressions = { 'greeting' => '%<greeting>' }
+    result = evaluate_shell_expressions(
+      @initial_code, expressions,
+      occurrence_expressions: occurrence_expressions
+    )
 
     assert_equal 'Hello, World!', result['%<greeting>']
   end
@@ -77,7 +79,15 @@ class TestShellExpressionEvaluator < Minitest::Test
       'date' => 'date +%Y-%m-%d',
       'kernel' => 'uname -r'
     }
-    result = evaluate_shell_expressions(@initial_code, expressions)
+    occurrence_expressions = {
+      'date' => '%<date>',
+      'greeting' => '%<greeting>',
+      'kernel' => '%<kernel>'
+    }
+    result = evaluate_shell_expressions(
+      @initial_code, expressions,
+      occurrence_expressions: occurrence_expressions
+    )
 
     assert_equal 'Hello, World!', result['%<greeting>']
     assert_match(/\d{4}-\d{2}-\d{2}/, result['%<date>'])
@@ -86,15 +96,22 @@ class TestShellExpressionEvaluator < Minitest::Test
 
   def test_empty_expressions_list
     expressions = {}
-    result = evaluate_shell_expressions(@initial_code, expressions)
+    occurrence_expressions = {}
+    result = evaluate_shell_expressions(
+      @initial_code, expressions,
+      occurrence_expressions: occurrence_expressions
+    )
 
     assert_nil result
   end
 
   def test_invalid_expression
     expressions = { 'invalid' => 'invalid_command' }
-
-    result = evaluate_shell_expressions(@initial_code, expressions)
+    occurrence_expressions = {}
+    result = evaluate_shell_expressions(
+      @initial_code, expressions,
+      occurrence_expressions: occurrence_expressions
+    )
 
     assert_equal EvaluateShellExpression::StatusFail, result
   end
@@ -105,18 +122,26 @@ class TestShellExpressionEvaluator < Minitest::Test
       echo "Custom setup message"
     BASH
     expressions = { 'test' => 'echo Test after initial setup' }
-
-    result = evaluate_shell_expressions(initial_code, expressions)
+    occurrence_expressions = { 'test' => '%<test>' }
+    result = evaluate_shell_expressions(
+      @initial_code, expressions,
+      occurrence_expressions: occurrence_expressions
+    )
 
     assert_equal 'Test after initial setup', result['%<test>']
   end
 
   def test_large_number_of_expressions
-    expressions = (1..100).map do |i|
+    expressions = (1..100).to_h do |i|
       ["expr_#{i}", "echo Expression #{i}"]
-    end.to_h
-
-    result = evaluate_shell_expressions(@initial_code, expressions)
+    end
+    occurrence_expressions = (1..100).to_h do |i|
+      ["expr_#{i}", "%<expr_#{i}>"]
+    end
+    result = evaluate_shell_expressions(
+      @initial_code, expressions,
+      occurrence_expressions: occurrence_expressions
+    )
 
     expressions.each_with_index do |(key, _expression), index|
       assert_equal "Expression #{index + 1}", result["%<#{key}>"]

data/lib/fcb.rb

@@ -4,7 +4,7 @@
 # encoding=utf-8
 require 'digest'
 require_relative 'namer'
-
+BT_UX_FLD_REQUIRED = 'required'
 def parse_yaml_of_ux_block(
   data,
   menu_format: nil,
@@ -18,15 +18,17 @@ def parse_yaml_of_ux_block(
   raise "Name is missing in UX block: #{data.inspect}" unless name.present?
 
   OpenStruct.new(
-    allowed: export['allowed'],
+    act: export['act'],
+    allow: export['allow'] || export['allowed'],
     default: export['default'],
     echo: export['echo'],
     exec: export['exec'],
-    menu_format: export['menu_format'] || menu_format,
+    init: export['init'],
+    menu_format: export['format'] || export['menu_format'] || menu_format,
     name: name,
-    preconditions: export['preconditions'],
     prompt: export['prompt'] || prompt,
     readonly: export['readonly'].nil? ? false : export['readonly'],
+    required: export['require'] || export['required'] || export[BT_UX_FLD_REQUIRED],
     transform: export['transform'],
     validate: export['validate'] || validate
   )
@@ -48,6 +50,7 @@ module MarkdownExec
         call: nil,
         dname: nil,
         headings: [],
+        id: object_id,
         indent: '',
         name: nil,
         nickname: nil,
@@ -62,6 +65,15 @@ module MarkdownExec
       }.merge(options)
     end
 
+    def pub_name(**kwargs)
+      self.class.pub_name(@attrs, **kwargs)
+    end
+
+    def self.pub_name(attrs, **kwargs)
+      full = attrs.fetch(:nickname, nil) || attrs.fetch(:oname, nil)
+      full&.to_s&.pub_name(**kwargs)
+    end
+
     def code_name_included?(*names)
       names.include?(@attrs[:oname])
     end
@@ -127,8 +139,10 @@ module MarkdownExec
       )&.fetch(1, nil)
       titlexcall = call ? @attrs[:title].sub("%#{call}", '') : @attrs[:title]
 
-      oname = if block_name_nick_match.present? &&
-                 @attrs[:oname] =~ Regexp.new(block_name_nick_match)
+      oname = if is_split?
+                @attrs[:text]
+              elsif block_name_nick_match.present? &&
+                    @attrs[:oname] =~ Regexp.new(block_name_nick_match)
                 @attrs[:nickname] = $~[0]
                 derive_title_from_body
               else
@@ -175,7 +189,61 @@ module MarkdownExec
     def self.format_multiline_body_as_title(body_lines)
       body_lines.map.with_index do |line, index|
         index.zero? ? line : "  #{line}"
-      end.join("\n") << "\n"
+      end.join("\n")
+    end
+
+    def self.act_source(export)
+      # If `false`, the UX block is not activated.
+      # If one of `:allow`, `:echo`, `:edit`, or `:exec` is specified,
+      # the value is calculated or the user is prompted.
+      # If not present, the default value is `:edit`.
+      if export.act.nil?
+        export.act = if export.init.to_s == 'false'
+                       if export.allow.present?
+                         UxActSource::ALLOW
+                       elsif export.echo.present?
+                         UxActSource::ECHO
+                       elsif export.edit.present?
+                         UxActSource::EDIT
+                       elsif export.exec.present?
+                         UxActSource::EXEC
+                       else
+                         UxActSource::EDIT
+                       end
+                     elsif export.allow.present?
+                       UxActSource::ALLOW
+                     else
+                       UxActSource::EDIT
+                     end
+      end
+
+      export.act
+    end
+
+    def self.init_source(export)
+      # If `false`, there is no initial value set.
+      # If a string, it is the initial value of the object variable.
+      # Otherwise, if one of `:allow`, `:echo`, or `:exec` is specified,
+      # the value is the output of the `echo` or `exec` evaluation
+      # or the first allowed value.
+      # If not present, the default value is whichever of
+      # `:allow`, `:default`, `:echo`, or `:exec` is present.
+      if export.init.nil?
+        export.init = case
+                      when export.allow.present?
+                        UxActSource::ALLOW
+                      when export.default.present?
+                        UxActSource::DEFAULT
+                      when export.echo.present?
+                        UxActSource::ECHO
+                      when export.exec.present?
+                        UxActSource::EXEC
+                      else
+                        UxActSource::FALSE
+                      end
+      end
+
+      export.init
     end
 
     # :reek:ManualDispatch
@@ -188,6 +256,14 @@ module MarkdownExec
         dependency_names.include?(@attrs[:s2title])
     end
 
+    def is_disabled?
+      @attrs[:disabled] == TtyMenu::DISABLE
+    end
+
+    def is_enabled?
+      !is_disabled?
+    end
+
     def is_named?(name)
       @attrs[:dname] == name ||
         @attrs[:nickname] == name ||
@@ -196,6 +272,31 @@ module MarkdownExec
         @attrs[:s2title] == name
     end
 
+    # true if this is a line split block
+    def is_split?
+      is_split_first? || is_split_rest?
+    end
+
+    # true if this block displays its split body
+    # names and nicknames are displayed instead of the body
+    # ux blocks display a single line for the named variable
+    # split blocks are: opts, shell, vars
+    def is_split_displayed?(opts)
+      @attrs[:type] != BlockType::UX &&
+        !(@attrs[:start_line] =~ Regexp.new(opts[:block_name_nick_match]) ||
+           @attrs[:start_line] =~ Regexp.new(opts[:block_name_match]))
+    end
+
+    # true if this is the first line in a split block
+    def is_split_first?
+      @attrs.fetch(:is_split_first, false)
+    end
+
+    # true if this is the second or later line in a split block
+    def is_split_rest?
+      @attrs.fetch(:is_split_rest, false)
+    end
+
     # :reek:ManualDispatch
     def method_missing(method, *args, &block)
       method_name = method.to_s
@@ -331,13 +432,15 @@ if $PROGRAM_NAME == __FILE__
     end
 
     def test_to_h_method
-      assert_equal_hash @fcb_data.merge({ random: @fcb.random }), @fcb.to_h
+      assert_equal_hash @fcb_data.merge(
+        { id: @fcb.id, random: @fcb.random }
+      ), @fcb.to_h
     end
 
     def test_to_yaml_method
-      assert_equal_hash YAML.load(@fcb_data.merge({ random: @fcb.random })
-                                           .to_yaml),
-                        YAML.load(@fcb.to_yaml)
+      assert_equal_hash YAML.load(@fcb_data.merge(
+        { id: @fcb.id, random: @fcb.random }
+      ).to_yaml), YAML.load(@fcb.to_yaml)
     end
 
     def test_method_missing_getter