markdown_exec 2.8.4 → 3.0.0

data/lib/markdown_exec/version.rb

@@ -7,5 +7,5 @@ module MarkdownExec
   BIN_NAME = 'mde'
   GEM_NAME = 'markdown_exec'
   TAP_DEBUG = 'MDE_DEBUG'
-  VERSION = '2.8.4'
+  VERSION = '3.0.0'
 end

data/lib/markdown_exec.rb

@@ -21,6 +21,7 @@ require_relative 'cli'
 require_relative 'color_scheme'
 require_relative 'directory_searcher'
 require_relative 'env'
+require_relative 'error_reporting'
 require_relative 'exceptions'
 require_relative 'fcb'
 require_relative 'filter'
@@ -110,11 +111,16 @@ module MarkdownExec
     # Prepends the age of the file in days to the file name for display in a menu.
     # @param filename [String] the name of the file
     # @return [String] modified file name with age prepended
-    def self.for_menu(filename)
+    def self.for_menu(filename, colorize: true, histogram: true)
       file_age = (Time.now - File.mtime(filename)) / (60 * 60 * 24 * 30)
-      filename = ColorScheme.colorize_path(filename)
+      filename = ColorScheme.colorize_path(filename) if colorize
 
-      "  #{Histogram.display(file_age, 0, 11, 12, inverse: false)}: #{filename}"
+      if histogram
+        "  #{Histogram.display(file_age, 0, 11, 12,
+                               inverse: false)}: #{filename}"
+      else
+        filename
+      end
     end
 
     # Removes the age from the string to retrieve the original file name.
@@ -165,33 +171,30 @@ module MarkdownExec
     end
 
     def build_menu(file_names, directory_names, found_in_block_names,
-                   file_name_choices, choices_from_block_names)
+                   file_name_choices, choices_from_block_names,
+                   colorize: true)
       choices = []
 
       # Adding section title and data for file names
-      choices << {
-        disabled: '',
-        name: AnsiString.new("in #{file_names[:section_title]}")
-                        .send(@chrome_color)
-      }
-      choices += file_names[:data].map { |str| FileInMenu.for_menu(str) }
+      text = "in #{file_names[:section_title]}"
+      text = AnsiString.new(text).send(@chrome_color) if colorize
+      choices << { disabled: '', name: text }
+      choices += file_names[:data].map do |str|
+        FileInMenu.for_menu(str, colorize: colorize)
+      end
 
       # Conditionally add directory names if data is present
       if directory_names[:data].any?
-        choices << {
-          disabled: '',
-          name: AnsiString.new("in #{directory_names[:section_title]}")
-                          .send(@chrome_color)
-        }
+        text = "in #{directory_names[:section_title]}"
+        text = AnsiString.new(text).send(@chrome_color) if colorize
+        choices << { disabled: '', name: text }
         choices += file_name_choices
       end
 
       # Adding found in block names
-      choices << {
-        disabled: '',
-        name: AnsiString.new("in #{found_in_block_names[:section_title]}")
-                        .send(@chrome_color)
-      }
+      text = "in #{found_in_block_names[:section_title]}"
+      text = AnsiString.new(text).send(@chrome_color) if colorize
+      choices << { disabled: '', name: text }
       choices += choices_from_block_names
 
       choices
@@ -199,6 +202,8 @@ module MarkdownExec
   end
 
   class SearchResultsReport < DirectorySearcher
+    include ErrorReporting
+
     def directory_names(search_options, highlight_value)
       matched_directories = find_directory_names
       {
@@ -238,6 +243,8 @@ module MarkdownExec
           end,
         matched_contents: matched_contents
       }
+    rescue StandardError => err
+      report_and_reraise(err)
     end
 
     def file_names(search_options, highlight_value)
@@ -346,6 +353,8 @@ module MarkdownExec
       }
     end
 
+    public
+
     def choices_from_block_names(value, found_in_block_names)
       found_in_block_names[:matched_contents].map do |matched_contents|
         filename, details, = matched_contents
@@ -360,14 +369,16 @@ module MarkdownExec
       end.flatten
     end
 
-    def choices_from_file_names(directory_names)
+    def choices_from_file_names(directory_names, colorize: true,
+                                histogram: true, pattern: '*')
       directory_names[:data].map do |dn|
-        find_files('*', [dn], exclude_dirs: true)
-      end.flatten(1).map { |str| FileInMenu.for_menu(str) }
+        find_files(pattern, [dn], exclude_dirs: true)
+      end.flatten(1).map do |str|
+        FileInMenu.for_menu(str, colorize: colorize,
+                                 histogram: histogram)
+      end
     end
 
-    public
-
     ## Determines the correct filename to use for searching files
     #
     def determine_filename(
@@ -658,6 +669,32 @@ module MarkdownExec
       @options.merge(@options.run_state.to_h)
     end
 
+    def iter_source_blocks(source, &block)
+      case source
+      when 1
+        HashDelegator.new(@options).blocks_from_nested_files.each(&block)
+      when 2
+        blocks_in_file, =
+          HashDelegator.new(@options)
+                       .mdoc_menu_and_blocks_from_nested_files(LinkState.new)
+        blocks_in_file.each(&block)
+      when 3
+        _, menu_blocks, =
+          HashDelegator.new(@options)
+                       .mdoc_menu_and_blocks_from_nested_files(LinkState.new)
+        menu_blocks.each(&block)
+      else
+        @options.iter_blocks_from_nested_files do |btype, fcb|
+          case btype
+          when :blocks
+            yield fcb
+          when :filter
+            %i[blocks]
+          end
+        end
+      end
+    end
+
     ##
     # Returns a lambda expression based on the given procname.
     # @param procname [String] The name of the process to generate a lambda for.
@@ -782,7 +819,7 @@ module MarkdownExec
     # Reports and executes block logic
     def mde_vux_main_loop(files)
       @options[:filename] = select_document_if_multiple(files)
-      @options.vux_main_loop do |type, data|
+      @options.vux_main_loop(menu_from_yaml: @menu_from_yaml) do |type, data|
         case type
         when :command_names
           simple_commands(data).keys
@@ -802,12 +839,13 @@ module MarkdownExec
     # Generates a menu suitable for OptionParser from the menu items defined in YAML format.
     # @return [Array<Hash>] The array of option hashes for OptionParser.
     def menu_for_optparse
-      menu_from_yaml.map do |menu_item|
-        menu_item.merge(
-          opt_name: menu_item[:opt_name]&.to_sym,
-          proccode: lambda_for_procname(menu_item[:procname], options)
-        )
-      end
+      @menu_from_yaml =
+        menu_from_yaml.map do |menu_item|
+          menu_item.merge(
+            opt_name: menu_item[:opt_name]&.to_sym,
+            proccode: lambda_for_procname(menu_item[:procname], options)
+          )
+        end
     end
 
     def menu_help
@@ -963,6 +1001,8 @@ module MarkdownExec
                                            @options[:saved_filename_replacement])
     end
 
+    public
+
     def select_document_if_multiple(files = list_markdown_files_in_path,
                                     cycle: true,
                                     prompt: options[:prompt_select_md].to_s)
@@ -984,6 +1024,8 @@ module MarkdownExec
       )
     end
 
+    private
+
     # Presents a TTY prompt to select an option or exit, returns selected option or nil
     def select_option_or_exit(prompt_text, strings, opts = {})
       @options.select_option_with_metadata(
@@ -1049,21 +1091,70 @@ module MarkdownExec
   end # class MarkParse
 end # module MarkdownExec
 
-if $PROGRAM_NAME == __FILE__
-  require 'bundler/setup'
-  Bundler.require(:default)
+return if $PROGRAM_NAME != __FILE__
 
-  require 'minitest/autorun'
+require 'bundler/setup'
+Bundler.require(:default)
 
-  module MarkdownExec
-    def test_select_block
-      blocks = [block1, block2]
-      menu = [m1, m2]
+require 'minitest/autorun'
 
-      block, state = obj.select_block(blocks, menu, nil, {})
+module MarkdownExec
+  class TestMarkdownTableFormatter < Minitest::Test
+    def test_select_document_if_multiple
+      find_path = "#{`pwd`.chomp}/fixtures"
+      value = 'document'
+      searcher = SearchResultsReport.new(value, [find_path])
+      options = {
+        ansi_formatter_color: false,
+        block_name_match: ':(?<title>\\S+)( |$)',
+        block_name_nick_match: '^\[.*\]$',
+        fenced_start_and_end_regex: '^(?<indent>[ \t]*)`{3,}',
+        menu_active_color_pastel_messages: %w[inverse]
+      }
+
+      file_names = searcher.file_names(options, value)
+      assert_equal ({ section_title: 'file names', data: [], formatted_text: [{ content: '' }] }),
+                   file_names
 
-      assert_equal block1, block
-      assert_equal MenuState::CONTINUE, state
+      found_in_block_names = searcher.found_in_block_names(options, value,
+                                                           formspec: '%<line>s')
+      assert_equal ({ section_title: 'block names',
+                      data: [],
+                      formatted_text: [],
+                      matched_contents: [] }), found_in_block_names
+
+      directory_names = searcher.directory_names(options, value)
+      assert_equal ({ section_title: 'directory names',
+                      data: ["#{Dir.getwd}/fixtures"],
+                      formatted_text: [{ content: ["#{Dir.getwd}/fixtures"] }] }), directory_names
+
+      mp = MarkdownExec::MarkParse.new(options)
+
+      file_name_choices = mp.choices_from_file_names(
+        directory_names, colorize: false, histogram: false, pattern: 'y*'
+      )
+      assert_equal ['fixtures/yaml1.md',
+                    'fixtures/yaml2.md'], file_name_choices
+
+      choices = MenuBuilder.new.build_menu(
+        file_names, directory_names, found_in_block_names,
+        file_name_choices, mp.choices_from_block_names(value, found_in_block_names),
+        colorize: false
+      )
+      assert_equal [{ disabled: '', name: 'in file names' },
+                    { disabled: '', name: 'in directory names' },
+                    'fixtures/yaml1.md',
+                    'fixtures/yaml2.md',
+                    { disabled: '', name: 'in block names' }], choices
+
+      # @options[:filename] = FileInMenu.from_menu(
+      #   mp.select_document_if_multiple(
+      #     choices,
+      #     # test_select: 0,
+      #     prompt: options[:prompt_select_md].to_s +
+      #      AnsiString.new(' ¤ Age in months').fg_rgbh_AF_AF_00
+      #   )
+      # )
     end
-  end # module MarkdownExec
-end # if
+  end # if
+end # module MarkdownExec

data/lib/mdoc.rb

@@ -10,6 +10,45 @@ require_relative 'filter'
 $pd = false unless defined?($pd)
 
 module MarkdownExec
+  class MenuFilter
+    def initialize(opts)
+      @opts = opts.merge(block_name_hidden_match: nil)
+    end
+
+    def fcb_in_menu?(fcb)
+      in_menu = Filter.fcb_select?(@opts, fcb)
+      unless @opts[:menu_include_imported_blocks]
+        in_menu = fcb.fetch(:depth, 0).zero?
+      end
+      if in_menu && @opts[:hide_blocks_by_name]
+        in_menu = !hide_menu_block_on_name(fcb)
+      end
+      in_menu
+    end
+
+    # Checks if a code block should be hidden based on the given options.
+    #
+    # @param opts [Hash] The options used for hiding code blocks.
+    # @param block [Hash] The code block to check for hiding.
+    # @return [Boolean] True if the code block should be hidden; false otherwise.
+    #
+    # :reek:UtilityFunction
+    def hide_menu_block_on_name(block)
+      if block.fetch(:chrome, false)
+        false
+      else
+        @opts[:hide_blocks_by_name] &&
+          ((@opts[:block_name_hidden_match]&.present? &&
+            block.s2title&.match(Regexp.new(@opts[:block_name_hidden_match]))) ||
+           (@opts[:block_name_include_match]&.present? &&
+            block.s2title&.match(Regexp.new(@opts[:block_name_include_match]))) ||
+           (@opts[:block_name_wrapper_match]&.present? &&
+            block.s2title&.match(Regexp.new(@opts[:block_name_wrapper_match])))) &&
+          (block.s2title&.present? || block[:label]&.present?)
+      end
+    end
+  end
+
   ##
   # MDoc represents an imported markdown document.
   #
@@ -26,7 +65,6 @@ module MarkdownExec
     #
     def initialize(table = [])
       @table = table
-      # !!t @table.count
     end
 
     def collect_block_code_cann(fcb)
@@ -83,7 +121,7 @@ module MarkdownExec
 
       nickname = name_block.pub_name
 
-      dependencies = collect_dependencies(nickname)
+      dependencies = collect_dependencies(source: nickname)
       # !!t dependencies.count
       all_dependency_names =
         collect_unique_names(dependencies).push(nickname).uniq
@@ -91,7 +129,7 @@ module MarkdownExec
 
       # select blocks in order of appearance in source documents
       #
-      blocks = @table.select do |fcb|
+      blocks = table_not_split.select do |fcb|
         fcb.is_dependency_of?(all_dependency_names)
       end
       # !!t blocks.count
@@ -177,15 +215,19 @@ module MarkdownExec
     # @return [Array<Hash>] An array of code blocks required by the specified code blocks.
     #
     def collect_wrapped_blocks(blocks)
-      blocks.map do |block|
-        (block[:wraps] || []).map do |wrap|
+      blocks.map do |fcb|
+        next if fcb.is_split_rest?
+
+        (fcb[:wraps] || []).map do |wrap|
           wrap_before = wrap.sub('}', '-before}') ### hardcoded wrap name
-          @table.select { |fcb| fcb.code_name_included?(wrap_before, wrap) }
+          table_not_split.select { |fcb|
+            fcb.code_name_included?(wrap_before, wrap)
+          }
         end.flatten(1) +
-          [block] +
-          (block[:wraps] || []).reverse.map do |wrap|
+          [fcb] +
+          (fcb[:wraps] || []).reverse.map do |wrap|
             wrap_after = wrap.sub('}', '-after}') ### hardcoded wrap name
-            @table.select { |fcb| fcb.code_name_included?(wrap_after) }
+            table_not_split.select { |fcb| fcb.code_name_included?(wrap_after) }
           end.flatten(1)
       end.flatten(1).compact
     end
@@ -325,7 +367,7 @@ module MarkdownExec
     # @return [Hash] The code block as a hash or the default value if not found.
     #
     def get_block_by_anyname(name, default = {})
-      @table.select do |fcb|
+      table_not_split.select do |fcb|
         fcb.is_named?(name)
       end.fetch(0, default)
     end
@@ -405,21 +447,23 @@ module MarkdownExec
     # @param source [String] The name of the initial source block.
     # @param memo [Hash] A memoization hash to store resolved dependencies.
     # @return [Hash] A hash mapping sources to their respective dependencies.
-    def collect_dependencies(source, memo = {})
-      return memo unless source
+    def collect_dependencies(block: nil, memo: {}, source: nil)
+      if block.nil?
+        return memo unless source
 
-      block = get_block_by_anyname(source)
-      if block.nil? || block.instance_of?(Hash)
-        raise "Named code block `#{source}` not found. (@#{__LINE__})"
+        block = get_block_by_anyname(source)
+        if block.nil? || block.instance_of?(Hash)
+          raise "Named code block `#{source}` not found. (@#{__LINE__})"
+        end
       end
-
       return memo unless block.reqs
 
-      memo[source] = block.reqs
+      memo[block.id] = block.reqs
 
       block.reqs.each do |req|
-        collect_dependencies(req, memo) unless memo.key?(req)
+        collect_dependencies(source: req, memo: memo) unless memo.key?(req)
       end
+
       memo
     end
 
@@ -446,6 +490,12 @@ module MarkdownExec
 
       selected_elements
     end
+
+    # exclude blocks with duplicate code
+    # the first block in each split contains the same data as the rest of the split
+    def table_not_split
+      @table.reject(&:is_split_rest?)
+    end
   end
 end
 
@@ -463,24 +513,25 @@ if $PROGRAM_NAME == __FILE__
       end
 
       def test_collect_dependencies_with_no_source
-        assert_empty @mdoc.collect_dependencies(nil)
+        assert_empty @mdoc.collect_dependencies
       end
 
       ### must raise error
       def test_collect_dependencies_with_nonexistent_source
         assert_raises(RuntimeError) do
-          @mdoc.collect_dependencies('nonexistent')
+          @mdoc.collect_dependencies(source: 'nonexistent')
         end
       end if false
 
       def test_collect_dependencies_with_valid_source
         @mdoc.stubs(:get_block_by_anyname)
-             .with('source1').returns(OpenStruct.new(reqs: ['source2']))
+             .with('source1').returns(OpenStruct.new(id: 'source1',
+                                                     reqs: ['source2']))
         @mdoc.stubs(:get_block_by_anyname)
-             .with('source2').returns(OpenStruct.new(reqs: []))
+             .with('source2').returns(OpenStruct.new(id: 'source2', reqs: []))
 
         expected = { 'source1' => ['source2'], 'source2' => [] }
-        assert_equal expected, @mdoc.collect_dependencies('source1')
+        assert_equal expected, @mdoc.collect_dependencies(source: 'source1')
       end
     end
 

data/lib/menu.src.yml

@@ -103,6 +103,12 @@
   :default: true
   :procname: val_as_bool
 
+- :opt_name: command_substitution_name_capture_group
+  :env_var: MDE_COMMAND_SUBSTITUTION_NAME_CAPTURE_GROUP
+  :description: command_substitution_name_capture_group
+  :default: command
+  :procname: val_as_str
+
 - :opt_name: command_substitution_regexp
   :env_var: MDE_COMMAND_SUBSTITUTION_REGEXP
   :description: command_substitution_regexp
@@ -207,12 +213,6 @@
   :default: "(document_shell)"
   :procname: val_as_str
 
-- :opt_name: document_load_ux_block_name
-  :env_var: MDE_DOCUMENT_LOAD_UX_BLOCK_NAME
-  :description: Name of UX block to load with the document
-  :default: "\\[.*document_ux.*\\]"
-  :procname: val_as_str
-
 - :opt_name: document_load_vars_block_name
   :env_var: MDE_DOCUMENT_LOAD_VARS_BLOCK_NAME
   :description: Name of Vars block to load with the document
@@ -1111,6 +1111,18 @@
   :default: ''
   :procname: open
 
+- :opt_name: option_expansion_expression_regexp
+  :env_var: MDE_OPTION_EXPANSION_EXPRESSION_REGEXP
+  :description: option_expansion_expression_regexp
+  :default: '(?<expression>&{(?<payload>(?<option>[A-Z0-9a-z_]+)(?:\.(?<property>[A-Z0-9a-z_]+))?)})'
+  :procname: val_as_str
+
+- :opt_name: option_expansion_payload_regexp
+  :env_var: MDE_OPTION_EXPANSION_PAYLOAD_REGEXP
+  :description: option_expansion_payload_regexp
+  :default: '^(?<option>[A-Z0-9a-z_]+)(?:\.(?<property>[A-Z0-9a-z_]+))?$'
+  :procname: val_as_str
+
 - :opt_name: output_assignment_begin
   :env_var: MDE_OUTPUT_ASSIGNMENT_BEGIN
   :description: Expression to match to start collecting lines
@@ -1663,9 +1675,15 @@
   :default: true
   :procname: val_as_bool
 
-- :opt_name: variable_expression_regexp
-  :env_var: MDE_VARIABLE_EXPRESSION_REGEXP
-  :description: variable_expression_regexp
+- :opt_name: variable_expansion_name_capture_group
+  :env_var: MDE_VARIABLE_EXPANSION_NAME_CAPTURE_GROUP
+  :description: variable_expansion_name_capture_group
+  :default: variable
+  :procname: val_as_str
+
+- :opt_name: variable_expansion_regexp
+  :env_var: MDE_VARIABLE_EXPANSION_REGEXP
+  :description: variable_expansion_regexp
   :default: "(?<expression>\\${(?<variable>[A-Z0-9a-z_]+)})"
   :procname: val_as_str
 

data/lib/menu.yml

@@ -84,6 +84,11 @@
   :arg_name: BOOL
   :default: true
   :procname: val_as_bool
+- :opt_name: command_substitution_name_capture_group
+  :env_var: MDE_COMMAND_SUBSTITUTION_NAME_CAPTURE_GROUP
+  :description: command_substitution_name_capture_group
+  :default: command
+  :procname: val_as_str
 - :opt_name: command_substitution_regexp
   :env_var: MDE_COMMAND_SUBSTITUTION_REGEXP
   :description: command_substitution_regexp
@@ -172,11 +177,6 @@
   :description: Name of shell block to load with the document
   :default: "(document_shell)"
   :procname: val_as_str
-- :opt_name: document_load_ux_block_name
-  :env_var: MDE_DOCUMENT_LOAD_UX_BLOCK_NAME
-  :description: Name of UX block to load with the document
-  :default: "\\[.*document_ux.*\\]"
-  :procname: val_as_str
 - :opt_name: document_load_vars_block_name
   :env_var: MDE_DOCUMENT_LOAD_VARS_BLOCK_NAME
   :description: Name of Vars block to load with the document
@@ -934,6 +934,16 @@
   :arg_name: OPEN
   :default: ''
   :procname: open
+- :opt_name: option_expansion_expression_regexp
+  :env_var: MDE_OPTION_EXPANSION_EXPRESSION_REGEXP
+  :description: option_expansion_expression_regexp
+  :default: "(?<expression>&{(?<payload>(?<option>[A-Z0-9a-z_]+)(?:\\.(?<property>[A-Z0-9a-z_]+))?)})"
+  :procname: val_as_str
+- :opt_name: option_expansion_payload_regexp
+  :env_var: MDE_OPTION_EXPANSION_PAYLOAD_REGEXP
+  :description: option_expansion_payload_regexp
+  :default: "^(?<option>[A-Z0-9a-z_]+)(?:\\.(?<property>[A-Z0-9a-z_]+))?$"
+  :procname: val_as_str
 - :opt_name: output_assignment_begin
   :env_var: MDE_OUTPUT_ASSIGNMENT_BEGIN
   :description: Expression to match to start collecting lines
@@ -1419,9 +1429,14 @@
   :arg_name: BOOL
   :default: true
   :procname: val_as_bool
-- :opt_name: variable_expression_regexp
-  :env_var: MDE_VARIABLE_EXPRESSION_REGEXP
-  :description: variable_expression_regexp
+- :opt_name: variable_expansion_name_capture_group
+  :env_var: MDE_VARIABLE_EXPANSION_NAME_CAPTURE_GROUP
+  :description: variable_expansion_name_capture_group
+  :default: variable
+  :procname: val_as_str
+- :opt_name: variable_expansion_regexp
+  :env_var: MDE_VARIABLE_EXPANSION_REGEXP
+  :description: variable_expansion_regexp
   :default: "(?<expression>\\${(?<variable>[A-Z0-9a-z_]+)})"
   :procname: val_as_str
 - :opt_name: vars_block_filename_view

data/lib/namer.rb

@@ -9,9 +9,7 @@ class Hash
   # block name in commands and documents
   def pub_name(**kwargs)
     full = fetch(:nickname, nil) || fetch(:oname, nil)
-    full&.to_s&.pub_name(**kwargs).tap do |ret|
-      pp [__LINE__, 'Hash.pub_name() ->', ret] if $pd
-    end
+    full&.to_s&.pub_name(**kwargs)
   end
 end
 

data/lib/value_or_exception.rb

@@ -0,0 +1,76 @@
+#!/usr/bin/env -S bundle exec ruby
+# frozen_string_literal: true
+
+# encoding=utf-8
+
+# == ValueOrException
+#
+# Encapsulates either a valid String value or an exception Symbol,
+# and provides methods to query and update the stored value.
+#
+# === Examples
+#
+#   obj = ValueOrException.new("foo")
+#   obj.valid?       # => true
+#   obj.exception?   # => false
+#   obj.get          # => "foo"
+#
+#   obj.set(:error)  # now holds an exception
+#   obj.valid?       # => false
+#   obj.exception?   # => true
+#   obj.get          # => :error
+class ValueOrException
+  # @return [String, Symbol] the stored value or exception
+  attr_accessor :message
+  attr_reader :value
+
+  # @param [String, Symbol] val a valid string or an exception symbol
+  # @raise [ArgumentError] if val is neither String nor Symbol
+  def initialize(val, message = nil)
+    validate!(val)
+    @value = val
+    @message = message
+  end
+
+  # @return [Boolean] true if the stored value is a Symbol (an exception)
+  def exception?
+    value.is_a?(Symbol)
+  end
+
+  # @return [Boolean] true if the stored value is a String (a valid value)
+  def valid?
+    !exception?
+  end
+
+  # Retrieve the current stored value or exception.
+  #
+  # @return [String, Symbol]
+  def get
+    valid? ? value : message
+  end
+
+  # Update the stored value or exception.
+  #
+  # @param [String, Symbol] new_val the new value or exception
+  # @raise [ArgumentError] if new_val is neither String nor Symbol
+  def set(new_val)
+    validate!(new_val)
+    @value = new_val
+  end
+
+  def to_s
+    valid? ? value.to_s : message
+  end
+
+  private
+
+  # Ensure the provided value is of an allowed type.
+  #
+  # @param [Object] val the value to check
+  # @raise [ArgumentError] if val is not a String or Symbol
+  def validate!(val)
+    return if val.is_a?(String) || val.is_a?(Symbol)
+
+    raise ArgumentError, "Expected a String or Symbol, got #{val.class}"
+  end
+end