markdown_exec 3.2.0 → 3.3.0

data/lib/ww.rb

@@ -5,65 +5,156 @@ require 'bundler/setup' # Bundler enforces gem versions
 require 'pp'
 require 'stringio'
 
+# call depth icons
+DEPTH_ICON = '›'
+
+# log levels
 LOG_LEVELS = %i[debug info warn error fatal].freeze
 
-$debug = $DEBUG || !ENV['WW'].nil?
+# is enabled
+def enable_debugging
+  ENV.fetch('WW', '0').to_i.positive?
+end
+
+# is enabled, not silent
+def env_show_attribution
+  ENV['WW'] != '0'
+end
+
+def is_new_alg?
+  # use the new algo only if env var is ALG is not empty
+  !ENV.fetch('ALG', '').empty?
+
+  # use the new algo if ALG != 0
+  # ENV.fetch('ALG', '') != '0'
+end
+
+# enable application-wide debugging
+$debug = $DEBUG || enable_debugging
+
+# no default category
+$ww_category = nil
+
+# no default log file
+$ww_log_file = nil
+
+# default output to $stderr
+$ww_output = $stderr
+unless ($id = ENV.fetch('WW_LOG', '')).empty?
+  alg = is_new_alg? ? '1' : '0'
+  # local log file with timestamp and algo name
+  $ww_log_file = "#{Time.now.utc.strftime '%H-%M-%S'}-#{$id}-#{alg}.log"
+end
 
 # attribution in output unless disabled
-if $debug && ENV['WW_MINIMUM'].nil?
-  warn "WW Debugging per $DEBUG ('ruby --debug')" if $DEBUG
-  warn 'WW Debugging per environment variable WW' unless ENV['WW'].nil?
+if env_show_attribution
+  if $debug
+    # not silent, display notice
+    if $DEBUG
+      # debugging triggered by Ruby debug
+      warn "WW Debugging per $DEBUG ('ruby --debug')"
+    else
+      # debugging triggered by WW environment variable
+      warn 'WW Debugging per environment variable WW'
+    end
+  end
+  if is_new_alg?
+    warn "WW Testing a new algorithm. Control with env var 'ALG'"
+  end
 end
 
+# selectively enabled, for general debugging
+# return the last item in the list
 def ww(*objs, **kwargs)
-  # return the last item in the list, as the label is usually first
+  # assume the final item is the significant one
+  # allows prefixing to an existing expression and forwarding the result
   return objs.last unless $debug
 
   locations = kwargs[:locations] || caller_locations
   ww0(*objs, **kwargs.merge(locations: locations))
 end
 
-# select enabled, for exceptions
-# print a data object for the error, and the failing line
+# output the object and backtrace for the error
+# abort
+def wwa(*objs, **kwargs)
+  ww0(*objs,
+      **kwargs.merge(full_backtrace: true,
+                     locations: caller_locations))
+
+  exit 1
+end
+
+# output the object and backtrace for the error
+# raise the error for the caller to handle
 def wwe(*objs, **kwargs)
   ww0(*objs,
       **kwargs.merge(full_backtrace: true,
                      locations: caller_locations))
 
-  raise StandardError, objs.first[:error]
+  # raise StandardError, objs.first.fetch(:error) || objs.first
+  raise StandardError, objs.first
 end
 
 # selectively enabled, for process tracking
-# print the failing line
+# output data and the caller's location
 def wwp(*objs, **kwargs)
   return objs.last unless $debug
 
-  ww(*objs, **kwargs.merge(locations: caller_locations[0..0]))
+  ww0(*objs,
+      **kwargs.merge(
+        locations: caller_locations[0..0],
+        location_offset: caller_locations.count
+      ))
+end
+
+# the return value for a function
+def wwr(*objs, **kwargs)
+  # assume the final item is the significant one
+  # allows prefixing to an existing expression and forwarding the result
+  return objs.last unless $debug
+
+  ww0(*objs,
+      **kwargs.merge(
+        locations: caller_locations[0..0],
+        location_offset: caller_locations.count
+      ))
 end
 
-# selectively enabled, for tagged
-# print the failing line
-# eg wwt :line, 'data:', data
+# selectively enabled, for tagged data
+# the first item is the tag, the rest is data
+# exclude tags in the list of tags to skip
+# output data and the caller's location
 def wwt(*objs, **kwargs)
-  return objs.last if !$debug || %i[env].include?(objs.first)
+  # tags to skip
+  return objs.last if !$debug || %i[blocks env fcb].include?(objs.first)
 
   formatted = ['Tagged', objs.first] + objs[1..]
-  ww(*formatted, **kwargs.merge(locations: caller_locations[0..0]))
+  ww0(*formatted,
+      **kwargs.merge(
+        locations: caller_locations[0..0],
+        location_offset: caller_locations.count
+      ))
 end
 
+# output the formatted data and location
 def ww0(*objs,
-        category: nil,
+        category: $ww_category,
         full_backtrace: false,
         level: :debug,
         locations: caller_locations,
-        log_file: nil,
-        output: $stderr,
+        log_file: $ww_log_file,
+        output: $ww_output,
         single_line: false,
-        timestamp: false)
+        timestamp: false,
+        location_offset: 0)
   # Format caller information line
-  def caller_info_line(caller_info)
-    "#{caller_info.lineno} : #{caller_info.path.sub(%r{^#{Dir.pwd}},
-                                                    '')} : #{caller_info.label}"
+  caller_info_line = lambda do |caller_info, ind|
+    [
+      DEPTH_ICON * (location_offset + locations.count - ind),
+      caller_info.path.deref,
+      caller_info.lineno,
+      caller_info.label
+    ].join(' : ')
   end
   # Validate log level
   raise ArgumentError,
@@ -71,9 +162,11 @@ def ww0(*objs,
 
   # Generate backtrace
   backtrace = if full_backtrace
-                locations.map { |caller_info| caller_info_line(caller_info) }
+                locations.map.with_index do |caller_info, ind|
+                  caller_info_line.call(caller_info, ind)
+                end
               else
-                [caller_info_line(locations.first)]
+                [caller_info_line.call(locations.first, 0)]
               end
 
   # Add optional timestamp
@@ -95,8 +188,12 @@ def ww0(*objs,
                         "#{header}\n#{io.string}"
                       end
 
+  # prefix each line in formatted_message
+  prefix = (' ' * 8).freeze
+  formatted_message = prefix + formatted_message.gsub("\n", "\n#{prefix}")
+
   # Output to $stderr or specified IO object
-  output.puts formatted_message
+  output.puts "\033[38;2;128;191;191m#{formatted_message}\033[0m"
   output.flush
 
   # Optionally log to a file
@@ -106,16 +203,22 @@ def ww0(*objs,
     file.puts(formatted_message)
   end
 
-  def wwb
-    binding.irb if $debug
-  end
-
   # return the last item in the list, as the label is usually first
   objs.last
 end
 
+# break into the debugger if enabled
+def wwb
+  binding.irb if $debug
+end
+
 class Array
   unless defined?(deref)
+
+    # trim the backtrace to project source files
+    # exclude vendor and .bundle directories
+    # limit the count to 4
+    # replace the home directory with a .
     def deref(count = 4)
       dir_pwd = Dir.pwd
       map(&:deref).reject do |line|
@@ -129,8 +232,201 @@ end
 
 class String
   unless defined?(deref)
+    # replace the app's directory with a .
     def deref
       sub(%r{^#{Dir.pwd}}, '')
     end
   end
 end
+
+class Array
+  # Count occurrences by method result using tally (Ruby 2.7+)
+  #
+  # @param method [Symbol, String] The method to call on each element
+  # @return [Hash] Hash of method result => count pairs
+  def count_by(method)
+    raise ArgumentError,
+          'Method must be a Symbol or String' unless method.is_a?(Symbol) || method.is_a?(String)
+
+    if respond_to?(:tally) # Ruby 2.7+
+      map do |item|
+        item.respond_to?(method) ? item.send(method) : nil
+      end.compact.tally
+    else
+      # Fallback for older Ruby versions
+      result = Hash.new(0)
+      each do |item|
+        if item.respond_to?(method)
+          value = item.send(method)
+          result[value] += 1
+        end
+      end
+      result
+    end
+  rescue NoMethodError => err
+    warn "Method #{method} not available on some items: #{err.message}"
+    {}
+  end
+
+  # Use filter_map for combined filtering and mapping (Ruby 2.7+)
+  # Filters elements and transforms them in one pass
+  #
+  # @param method [Symbol, String] The method to call on each element
+  # @param value [Object] The value to match against
+  # @param transform_method [Symbol, String, nil] Optional
+  #         method to call on matching elements
+  # @return [Array] Array of transformed matching elements
+  def filter_map_by(method, value, transform_method = nil)
+    raise ArgumentError,
+          'Method must be a Symbol or String' unless method.is_a?(Symbol) || method.is_a?(String)
+
+    if respond_to?(:filter_map) # Ruby 2.7+
+      filter_map do |item|
+        if item.respond_to?(method) && item.send(method) == value
+          transform_method ? item.send(transform_method) : item
+        end
+      end
+    else
+      # Fallback for older Ruby versions
+      result = []
+      each do |item|
+        if item.respond_to?(method) && item.send(method) == value
+          result << (transform_method ? item.send(transform_method) : item)
+        end
+      end
+      result
+    end
+  rescue NoMethodError => err
+    warn "Method #{method} not available on some items: #{err.message}"
+    []
+  end
+
+  # Find the first element where the specified method matches a value
+  # Supports both method-based and block-based filtering
+  #
+  # @param method [Symbol, String, nil] The method to call on each element
+  # @param value [Object, nil] The value to match against
+  # @param default [Object, nil] Default value if no match found
+  # @param block [Proc, nil] Optional block for custom filtering logic
+  # @return [Object, nil] The first matching element or default
+  def find_by(method = nil, value = nil, default = nil, &block)
+    if block_given?
+      find(&block)
+    else
+      raise ArgumentError,
+            'Method must be a Symbol or String' unless method.is_a?(Symbol) || method.is_a?(String)
+
+      find do |item|
+        item.respond_to?(method) && item.send(method) == value
+      end || default
+    end
+  rescue NoMethodError => err
+    warn "Method #{method} not available on some items: #{err.message}"
+    default
+  end
+
+  # Find elements using hash-based conditions
+  # All conditions must match for an element to be included
+  #
+  # @param conditions [Hash] Hash of method => value pairs
+  # @return [Array] Array of matching elements
+  def find_where(conditions = {})
+    find do |item|
+      conditions.all? do |method, value|
+        item.respond_to?(method) && item.send(method) == value
+      end
+    end
+  rescue NoMethodError => err
+    warn "Some methods not available on items: #{err.message}"
+    nil
+  end
+
+  # Match elements using pattern matching (Ruby 2.7+)
+  # Uses grep for pattern matching against method results
+  #
+  # @param method [Symbol, String] The method to call on each element
+  # @param pattern [Regexp, Object] Pattern to match against
+  # @return [Array] Array of matching elements
+  def match_by(method, pattern)
+    raise ArgumentError,
+          'Method must be a Symbol or String' unless method.is_a?(Symbol) || method.is_a?(String)
+
+    grep { |item| pattern === item.send(method) }
+  rescue NoMethodError => err
+    warn "Method #{method} not available on some items: #{err.message}"
+    []
+  end
+
+  # Partition elements based on method result
+  #
+  # @param method [Symbol, String] The method to call on each element
+  # @param value [Object] The value to partition by
+  # @return [Array] Array containing [matching_elements, non_matching_elements]
+  def partition_by(method, value)
+    raise ArgumentError,
+          'Method must be a Symbol or String' unless method.is_a?(Symbol) || method.is_a?(String)
+
+    partition { |item| item.respond_to?(method) && item.send(method) == value }
+  rescue NoMethodError => err
+    warn "Method #{method} not available on some items: #{err.message}"
+    [[], self]
+  end
+
+  # Reject elements where the specified method matches a value
+  # Supports both method-based and block-based filtering
+  #
+  # @param method [Symbol, String, nil] The method to call on each element
+  # @param value [Object, nil] The value to match against
+  # @param block [Proc, nil] Optional block for custom filtering logic
+  # @return [Array] Array of non-matching elements
+  def reject_by(method = nil, value = nil, &block)
+    if block_given?
+      reject(&block)
+    else
+      raise ArgumentError,
+            'Method must be a Symbol or String' unless method.is_a?(Symbol) || method.is_a?(String)
+
+      reject { |item| item.respond_to?(method) && item.send(method) == value }
+    end
+  rescue NoMethodError => err
+    warn "Method #{method} not available on some items: #{err.message}"
+    self
+  end
+
+  # Select elements where the specified method matches a value
+  # Supports both method-based and block-based filtering
+  #
+  # @param method [Symbol, String, nil] The method to call on each element
+  # @param value [Object, nil] The value to match against
+  # @param block [Proc, nil] Optional block for custom filtering logic
+  # @return [Array] Array of matching elements
+  def select_by(method = nil, value = nil, &block)
+    if block_given?
+      select(&block)
+    else
+      raise ArgumentError,
+            'Method must be a Symbol or String' unless method.is_a?(Symbol) || method.is_a?(String)
+
+      select { |item| item.respond_to?(method) && item.send(method) == value }
+    end
+  rescue NoMethodError => err
+    warn "Method #{method} not available on some items: #{err.message}"
+    []
+  end
+
+  # Select elements using hash-based conditions
+  # All conditions must match for an element to be included
+  #
+  # @param conditions [Hash] Hash of method => value pairs
+  # @return [Array] Array of matching elements
+  def select_where(conditions = {})
+    select do |item|
+      conditions.all? do |method, value|
+        item.respond_to?(method) && item.send(method) == value
+      end
+    end
+  rescue NoMethodError => err
+    warn "Some methods not available on items: #{err.message}"
+    []
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: markdown_exec
 version: !ruby/object:Gem::Version
-  version: 3.2.0
+  version: 3.3.0
 platform: ruby
 authors:
 - Fareed Stevenson
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-24 00:00:00.000000000 Z
+date: 2025-09-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: clipboard
@@ -120,7 +120,11 @@ files:
 - bats/block-type-ux-echo-hash-transform.bats
 - bats/block-type-ux-echo-hash.bats
 - bats/block-type-ux-echo.bats
+- bats/block-type-ux-exec-hash-transform.bats
+- bats/block-type-ux-exec-hash.bats
 - bats/block-type-ux-exec.bats
+- bats/block-type-ux-force.bats
+- bats/block-type-ux-formats.bats
 - bats/block-type-ux-hidden.bats
 - bats/block-type-ux-invalid.bats
 - bats/block-type-ux-readonly.bats
@@ -139,7 +143,9 @@ files:
 - bats/fail.bats
 - bats/history.bats
 - bats/import-conflict.bats
+- bats/import-directive-parameter-symbols.bats
 - bats/import-duplicates.bats
+- bats/import-parameter-symbols.bats
 - bats/import-with-text-substitution.bats
 - bats/import.bats
 - bats/indented-block-type-vars.bats
@@ -179,7 +185,11 @@ files:
 - docs/dev/block-type-ux-echo-hash-transform.md
 - docs/dev/block-type-ux-echo-hash.md
 - docs/dev/block-type-ux-echo.md
+- docs/dev/block-type-ux-exec-hash-transform.md
+- docs/dev/block-type-ux-exec-hash.md
 - docs/dev/block-type-ux-exec.md
+- docs/dev/block-type-ux-force.md
+- docs/dev/block-type-ux-formats.md
 - docs/dev/block-type-ux-hidden.md
 - docs/dev/block-type-ux-invalid.md
 - docs/dev/block-type-ux-readonly.md
@@ -196,11 +206,15 @@ files:
 - docs/dev/data-blocks.md
 - docs/dev/disable.md
 - docs/dev/document-shell.md
+- docs/dev/hexdump_format.md
 - docs/dev/import-conflict-0.md
 - docs/dev/import-conflict-1.md
+- docs/dev/import-directive-parameter-symbols.md
 - docs/dev/import-duplicates-0.md
 - docs/dev/import-duplicates-1.md
 - docs/dev/import-missing.md
+- docs/dev/import-parameter-symbols-template.md
+- docs/dev/import-parameter-symbols.md
 - docs/dev/import-substitution-basic.md
 - docs/dev/import-substitution-compare.md
 - docs/dev/import-substitution-export.md
@@ -214,12 +228,14 @@ files:
 - docs/dev/import-substitution-taxonomy.md
 - docs/dev/import-with-text-substitution.md
 - docs/dev/import.md
+- docs/dev/import/parameter-symbols.md
 - docs/dev/indented-block-type-vars.md
 - docs/dev/indented-multi-line-output.md
 - docs/dev/line-decor-dynamic.md
 - docs/dev/line-wrapping.md
 - docs/dev/linked-file.md
 - docs/dev/load-mode-demo.md
+- docs/dev/load-vars-state-demo.md
 - docs/dev/load1.sh
 - docs/dev/load_code.md
 - docs/dev/manage-saved-documents.md