markdown_exec 3.2.0 → 3.3.0

data/lib/markdown_exec/version.rb

@@ -8,5 +8,5 @@ module MarkdownExec
   BIN_NAME = 'mde'
   GEM_NAME = 'markdown_exec'
   TAP_DEBUG = 'MDE_DEBUG'
-  VERSION = '3.2.0'
+  VERSION = '3.3.0'
 end

data/lib/markdown_exec.rb

@@ -1045,6 +1045,8 @@ module MarkdownExec
     def simple_commands(options)
       # !!b
       {
+        # [stage, function]
+        blocks: [2, -> { list_blocks }],
         doc_glob: [1, -> { @fout.fout options[:md_filename_glob] }],
         history: [1, -> { history }],
         list_blocks: [2, -> { list_blocks }],

data/lib/mdoc.rb

@@ -119,22 +119,22 @@ module MarkdownExec
         raise "Named code block `#{anyname}` not found. (@#{__LINE__})"
       end
 
-      # nickname = name_block.pub_name
-      ####
-      nickname = name_block.id
+      nickname = name_block.pub_name
+      ref = name_block.id
+      dependencies = collect_dependencies(pubname: ref)
+      wwt :dependencies, 'dependencies.count:', dependencies.count
 
-      dependencies = collect_dependencies(pubname: nickname)
-      # !!t dependencies.count
       all_dependency_names =
-        collect_unique_names(dependencies).push(nickname).uniq
-      # !!t all_dependency_names.count
+        collect_unique_names(dependencies).push(ref).uniq
+      wwt :dependencies, 'all_dependency_names.count:',
+          all_dependency_names.count
 
       # select blocks in order of appearance in source documents
       #
       blocks = table_not_split.select do |fcb|
         fcb.is_dependency_of?(all_dependency_names)
       end
-      # !!t blocks.count
+      wwt :blocks, 'blocks.count:', blocks.count
 
       ## add cann key to blocks, calc unmet_dependencies
       #
@@ -149,12 +149,16 @@ module MarkdownExec
           []
         end + [fcb]
       end.flatten(1)
-      # !!t unmet_dependencies.count
+      wwt :unmet_dependencies, 'unmet_dependencies.count:',
+          unmet_dependencies.count
+      wwt :dependencies, 'dependencies.keys:', dependencies.keys
 
       { all_dependency_names: all_dependency_names,
         blocks: blocks,
         dependencies: dependencies,
         unmet_dependencies: unmet_dependencies }
+    rescue StandardError
+      wwe $!
     end
 
     # Collects recursively required code blocks and returns them as an array of strings.
@@ -166,8 +170,6 @@ module MarkdownExec
       anyname:, block_source:,
       label_body: true, label_format_above: nil, label_format_below: nil
     )
-      ww 'anyname:', anyname
-      ww 'block_source:', block_source
       block_search = collect_block_dependencies(anyname: anyname)
       if block_search[:blocks]
         blocks = collect_wrapped_blocks(block_search[:blocks])

data/lib/menu.src.yml

@@ -115,6 +115,14 @@
   :default: ": ${%{key}:=%{value}}"
   :procname: val_as_str
 
+- :opt_name: blocks
+  :arg_name: MESSAGE
+  :default:
+  :description: List the blocks displayed
+  :env_var: MDE_BLOCKS_LIST_MESSAGE
+  :long_name: blocks
+  :procname: val_as_str
+
 - :opt_name: clear_screen_for_select_block
   :env_var: MDE_CLEAR_SCREEN_FOR_SELECT_BLOCK
   :description: clear_screen_for_select_block
@@ -147,13 +155,6 @@
   :default: true
   :procname: val_as_bool
 
-- :opt_name: tables_into_columns
-  :env_var: MDE_TABLES_INTO_COLUMNS
-  :description: Format tables as columns
-  :arg_name: BOOL
-  :default: true
-  :procname: val_as_bool
-
 - :long_name: debug
   :short_name: d
   :env_var: MDE_DEBUG
@@ -250,16 +251,9 @@
   :default: document_configurations/%{document_filename}_*.sh
   :procname: val_as_str
 
-- :opt_name: menu_for_saved_lines
-  :env_var: MDE_MENU_FOR_SAVED_LINES
-  :description: Add menu options for saved lines
-  :arg_name: BOOL
-  :default: true
-  :procname: val_as_bool
-
-- :opt_name: menu_for_history
-  :env_var: MDE_MENU_FOR_HISTORY
-  :description: Add menu options for history
+- :opt_name: document_save_make_directory
+  :env_var: MDE_DOCUMENT_SAVE_MAKE_DIRECTORY
+  :description: Make the directory if it does not exist when saving
   :arg_name: BOOL
   :default: true
   :procname: val_as_bool
@@ -578,10 +572,46 @@
   :default:
   :procname: val_as_str
 
-- :opt_name: import_pattern
+- :opt_name: import_directive_line_pattern
   :env_var: MDE_IMPORT_PATTERN
   :default: >-
-    ^(?<indention> *)@import +(?<name>\S+)(?<params>(?: +[A-Za-z_]\w*=(?:"[^"]*"|'[^']*'|\S+))*) *$
+    ^(?<indention> *)@import +(?<name>\S+)(?<params>(?: +\w+(?::c=|:e=|:q=|:v=|=)(?:"[^"]*"|'[^']*'|\S+))*) *$
+  :procname: val_as_str
+
+- :opt_name: import_directive_parameter_scan
+  :env_var: MDE_IMPORT_PATTERN_SCAN
+  :default: >-
+    (\w+)(:c=|:e=|:q=|:v=|=)(?:"([^"]*)"|'([^']*)'|(\S+))
+  :procname: val_as_str
+
+- :opt_name: import_parameter_variable_assignment
+  :env_var: MDE_IMPORT_PARAMETER_VARIABLE_ASSIGNMENT
+  :default: "%{key}=%{value}"
+  :procname: val_as_str
+
+- :opt_name: import_symbol_command_substitution
+  :env_var: MDE_IMPORT_SYMBOL_COMMAND_SUBSTITUTION
+  :default: ':c='
+  :procname: val_as_str
+
+- :opt_name: import_symbol_evaluated_expression
+  :env_var: MDE_IMPORT_SYMBOL_EVALUATED_EXPRESSION
+  :default: ':e='
+  :procname: val_as_str
+
+- :opt_name: import_symbol_raw_literal
+  :env_var: MDE_IMPORT_SYMBOL_RAW_LITERAL
+  :default: '='
+  :procname: val_as_str
+
+- :opt_name: import_symbol_force_quoted_literal
+  :env_var: MDE_IMPORT_SYMBOL_FORCE_QUOTED_LITERAL
+  :default: ':q='
+  :procname: val_as_str
+
+- :opt_name: import_symbol_variable_reference
+  :env_var: MDE_IMPORT_SYMBOL_VARIABLE_REFERENCE
+  :default: ':v='
   :procname: val_as_str
 
 - :opt_name: line_decor_main
@@ -691,7 +721,7 @@
 - :opt_name: local_name_pattern
   :env_var: MDE_LOCAL_NAME_PATTERN
   :description: Pattern for variables not exported in a series of evaluations
-  :default: '^.{1,3}$'
+  :default: '^_\S{0,12}$'
   :procname: val_as_str
 
 - :opt_name: logged_stdout_filename_prefix
@@ -805,6 +835,20 @@
   :default:
     :line: "~~~"
 
+- :opt_name: menu_for_history
+  :env_var: MDE_MENU_FOR_HISTORY
+  :description: Add menu options for history
+  :arg_name: BOOL
+  :default: true
+  :procname: val_as_bool
+
+- :opt_name: menu_for_saved_lines
+  :env_var: MDE_MENU_FOR_SAVED_LINES
+  :description: Add menu options for saved lines
+  :arg_name: BOOL
+  :default: true
+  :procname: val_as_bool
+
 - :opt_name: menu_heading1_color
   :env_var: MDE_MENU_HEADING1_COLOR
   :description: Color for heading 1 in menu
@@ -864,7 +908,7 @@
   :env_var: MDE_MENU_INCLUDE_IMPORTED_NOTES
   :description: Whether imported blocks should be included in the menu
   :arg_name: BOOL
-  :default: false
+  :default: true
   :procname: val_as_bool
 
 - :opt_name: menu_inherited_lines_at_top
@@ -1031,12 +1075,6 @@
   # :default: fg_rgbh_e0_e0_20
   :procname: val_as_str
 
-- :opt_name: menu_table_rows_match
-  :env_var: MDE_MENU_TABLE_ROWS_MATCH
-  :description: Pattern for table rows
-  :default: '^(?<indent>[ \t]*)(?<line>(?<text>\|.*?)(?<trailing>[ \t]*))$'
-  :procname: val_as_str
-
 - :opt_name: menu_task_color
   :env_var: MDE_MENU_TASK_COLOR
   :description: Color of menu task
@@ -1063,10 +1101,40 @@
 
 - :opt_name: menu_ux_color
   :env_var: MDE_MENU_UX_COLOR
-  :description: Color of menu ux
+  :description: Default color of menu ux
   :default: fg_rgbh_df_c0_df
   :procname: val_as_str
 
+- :opt_name: menu_ux_color_allow
+  :env_var: MDE_MENU_UX_COLOR_ALLOW
+  :description: Color of menu ux when it is allow
+  :default:
+  :procname: val_as_str
+
+- :opt_name: menu_ux_color_echo
+  :env_var: MDE_MENU_UX_COLOR_ECHO
+  :description: Color of menu ux when it is echo
+  :default:
+  :procname: val_as_str
+
+- :opt_name: menu_ux_color_edit
+  :env_var: MDE_MENU_UX_COLOR_EDIT
+  :description: Color of menu ux when it is edit
+  :default:
+  :procname: val_as_str
+
+- :opt_name: menu_ux_color_exec
+  :env_var: MDE_MENU_UX_COLOR_EXEC
+  :description: Color of menu ux when it is exec
+  :default:
+  :procname: val_as_str
+
+- :opt_name: menu_ux_color_readonly
+  :env_var: MDE_MENU_UX_COLOR_READONLY
+  :description: Color of menu ux when it is read-only
+  :default:
+  :procname: val_as_str
+
 - :opt_name: menu_ux_row_format
   :env_var: MDE_MENU_UX_ROW_FORMAT
   :description: Format for UX row
@@ -1368,12 +1436,6 @@
   :default: "\nChoose a file:"
   :procname: val_as_str
 
-- :opt_name: prompt_select_output
-  :env_var: MDE_PROMPT_SELECT_OUTPUT
-  :default: "\nChoose a file:"
-  :description: Prompt to select a saved file
-  :procname: val_as_str
-
 - :opt_name: prompt_ux_enter_a_value
   :env_var: MDE_PROMPT_UX_ENTER_A_VALUE
   :description: Prompt to enter a value for UX blocks
@@ -1434,6 +1496,12 @@
   :long_name: pwd
   :description: Print the gem's home directory
 
+- :opt_name: required_lines_with_source_comments
+  :env_var: MDE_REQUIRED_LINES_WITH_SOURCE_COMMENTS
+  :description: Add comments about source to blocks of required lines
+  :default: false
+  :procname: val_as_bool
+
 - :opt_name: run_last_script
   :long_name: run-last-script
   :description: Run most recently saved script
@@ -1537,6 +1605,12 @@
   :default: 0
   :procname: val_as_int
 
+- :opt_name: script_comment_block_name_format
+  :env_var: MDE_SCRIPT_COMMENT_BLOCK_NAME_FORMAT
+  :description: format for block name in script comments
+  :default: "%{block} %{time}"
+  :procname: val_as_str
+
 - :opt_name: script_execution_frame_color
   :env_var: MDE_SCRIPT_EXECUTION_FRAME_COLOR
   :description: script_execution_frame_color
@@ -1687,11 +1761,42 @@
   - fg_bg_rgbh_cf_cf_cf_14_18_1c
   - fg_bg_rgbh_df_df_df_24_24_24
 
+- :opt_name: table_row_multi_line_delimiter
+  :env_var: MDE_TABLE_ROW_MULTI_LINE_DELIMITER
+  :description: Multi-line-table delimiter
+  :default: '|'
+  :procname: val_as_str
+
+- :opt_name: table_row_multi_line_match
+  :env_var: MDE_TABLE_ROW_MULTI_LINE_MATCH
+  :description: Pattern for multi-line-table rows
+  :default: '^(?<indent>[ \t]*)(?<line>(?<text>\|.*?)(?<trailing>[ \t]*))$'
+  :procname: val_as_str
+
+- :opt_name: table_row_single_line_delimiter
+  :env_var: MDE_TABLE_ROW_SINGLE_LINE_DELIMITER
+  :description: Single-line-table delimiter
+  :default: '!'
+  :procname: val_as_str
+
+- :opt_name: table_row_single_line_match
+  :env_var: MDE_TABLE_ROW_SINGLE_LINE_MATCH
+  :description: Pattern for single-line-table rows
+  :default: '^(?<indent>[ \t]*)(?<line>(?<text>!.*?)(?<trailing>[ \t]*))$'
+  :procname: val_as_str
+
 - :opt_name: table_separator_line_color
   :env_var: MDE_TABLE_SEPARATOR_LINE_COLOR
   :description: Color for table separator line
   :default: fg_bg_rgbh_df_df_00_14_18_1c
 
+- :opt_name: tables_into_columns
+  :env_var: MDE_TABLES_INTO_COLUMNS
+  :description: Format tables as columns
+  :arg_name: BOOL
+  :default: true
+  :procname: val_as_bool
+
 - :opt_name: user_must_approve
   :long_name: user-must-approve
   :short_name: q

data/lib/menu.yml

@@ -94,6 +94,13 @@
   :env_var: MDE_BLOCK_TYPE_PORT_SET_FORMAT
   :default: ": ${%{key}:=%{value}}"
   :procname: val_as_str
+- :opt_name: blocks
+  :arg_name: MESSAGE
+  :default:
+  :description: List the blocks displayed
+  :env_var: MDE_BLOCKS_LIST_MESSAGE
+  :long_name: blocks
+  :procname: val_as_str
 - :opt_name: clear_screen_for_select_block
   :env_var: MDE_CLEAR_SCREEN_FOR_SELECT_BLOCK
   :description: clear_screen_for_select_block
@@ -121,12 +128,6 @@
   :arg_name: BOOL
   :default: true
   :procname: val_as_bool
-- :opt_name: tables_into_columns
-  :env_var: MDE_TABLES_INTO_COLUMNS
-  :description: Format tables as columns
-  :arg_name: BOOL
-  :default: true
-  :procname: val_as_bool
 - :long_name: debug
   :short_name: d
   :env_var: MDE_DEBUG
@@ -208,15 +209,9 @@
   :arg_name: GLOB
   :default: document_configurations/%{document_filename}_*.sh
   :procname: val_as_str
-- :opt_name: menu_for_saved_lines
-  :env_var: MDE_MENU_FOR_SAVED_LINES
-  :description: Add menu options for saved lines
-  :arg_name: BOOL
-  :default: true
-  :procname: val_as_bool
-- :opt_name: menu_for_history
-  :env_var: MDE_MENU_FOR_HISTORY
-  :description: Add menu options for history
+- :opt_name: document_save_make_directory
+  :env_var: MDE_DOCUMENT_SAVE_MAKE_DIRECTORY
+  :description: Make the directory if it does not exist when saving
   :arg_name: BOOL
   :default: true
   :procname: val_as_bool
@@ -488,11 +483,39 @@
   :env_var: MDE_IMPORT_PATHS
   :default:
   :procname: val_as_str
-- :opt_name: import_pattern
+- :opt_name: import_directive_line_pattern
   :env_var: MDE_IMPORT_PATTERN
-  :default: '^(?<indention> *)@import +(?<name>\S+)(?<params>(?: +[A-Za-z_]\w*=(?:"[^"]*"|''[^'']*''|\S+))*)
+  :default: '^(?<indention> *)@import +(?<name>\S+)(?<params>(?: +\w+(?::c=|:e=|:q=|:v=|=)(?:"[^"]*"|''[^'']*''|\S+))*)
     *$'
   :procname: val_as_str
+- :opt_name: import_directive_parameter_scan
+  :env_var: MDE_IMPORT_PATTERN_SCAN
+  :default: (\w+)(:c=|:e=|:q=|:v=|=)(?:"([^"]*)"|'([^']*)'|(\S+))
+  :procname: val_as_str
+- :opt_name: import_parameter_variable_assignment
+  :env_var: MDE_IMPORT_PARAMETER_VARIABLE_ASSIGNMENT
+  :default: "%{key}=%{value}"
+  :procname: val_as_str
+- :opt_name: import_symbol_command_substitution
+  :env_var: MDE_IMPORT_SYMBOL_COMMAND_SUBSTITUTION
+  :default: ":c="
+  :procname: val_as_str
+- :opt_name: import_symbol_evaluated_expression
+  :env_var: MDE_IMPORT_SYMBOL_EVALUATED_EXPRESSION
+  :default: ":e="
+  :procname: val_as_str
+- :opt_name: import_symbol_raw_literal
+  :env_var: MDE_IMPORT_SYMBOL_RAW_LITERAL
+  :default: "="
+  :procname: val_as_str
+- :opt_name: import_symbol_force_quoted_literal
+  :env_var: MDE_IMPORT_SYMBOL_FORCE_QUOTED_LITERAL
+  :default: ":q="
+  :procname: val_as_str
+- :opt_name: import_symbol_variable_reference
+  :env_var: MDE_IMPORT_SYMBOL_VARIABLE_REFERENCE
+  :default: ":v="
+  :procname: val_as_str
 - :opt_name: line_decor_main
   :env_var: MDE_LINE_DECOR_MAIN
   :description: Line-oriented text decoration (Main)
@@ -585,7 +608,7 @@
 - :opt_name: local_name_pattern
   :env_var: MDE_LOCAL_NAME_PATTERN
   :description: Pattern for variables not exported in a series of evaluations
-  :default: "^.{1,3}$"
+  :default: "^_\\S{0,12}$"
   :procname: val_as_str
 - :opt_name: logged_stdout_filename_prefix
   :env_var: MDE_LOGGED_STDOUT_FILENAME_PREFIX
@@ -681,6 +704,18 @@
   :description: closing demarcations for menu
   :default:
     :line: "~~~"
+- :opt_name: menu_for_history
+  :env_var: MDE_MENU_FOR_HISTORY
+  :description: Add menu options for history
+  :arg_name: BOOL
+  :default: true
+  :procname: val_as_bool
+- :opt_name: menu_for_saved_lines
+  :env_var: MDE_MENU_FOR_SAVED_LINES
+  :description: Add menu options for saved lines
+  :arg_name: BOOL
+  :default: true
+  :procname: val_as_bool
 - :opt_name: menu_heading1_color
   :env_var: MDE_MENU_HEADING1_COLOR
   :description: Color for heading 1 in menu
@@ -731,7 +766,7 @@
   :env_var: MDE_MENU_INCLUDE_IMPORTED_NOTES
   :description: Whether imported blocks should be included in the menu
   :arg_name: BOOL
-  :default: false
+  :default: true
   :procname: val_as_bool
 - :opt_name: menu_inherited_lines_at_top
   :env_var: MDE_MENU_INHERITED_LINES_AT_TOP
@@ -867,11 +902,6 @@
   :description: Color of Save link
   :default: fg_rgbh_ff_ff_20
   :procname: val_as_str
-- :opt_name: menu_table_rows_match
-  :env_var: MDE_MENU_TABLE_ROWS_MATCH
-  :description: Pattern for table rows
-  :default: "^(?<indent>[ \\t]*)(?<line>(?<text>\\|.*?)(?<trailing>[ \\t]*))$"
-  :procname: val_as_str
 - :opt_name: menu_task_color
   :env_var: MDE_MENU_TASK_COLOR
   :description: Color of menu task
@@ -894,9 +924,34 @@
   :procname: val_as_str
 - :opt_name: menu_ux_color
   :env_var: MDE_MENU_UX_COLOR
-  :description: Color of menu ux
+  :description: Default color of menu ux
   :default: fg_rgbh_df_c0_df
   :procname: val_as_str
+- :opt_name: menu_ux_color_allow
+  :env_var: MDE_MENU_UX_COLOR_ALLOW
+  :description: Color of menu ux when it is allow
+  :default:
+  :procname: val_as_str
+- :opt_name: menu_ux_color_echo
+  :env_var: MDE_MENU_UX_COLOR_ECHO
+  :description: Color of menu ux when it is echo
+  :default:
+  :procname: val_as_str
+- :opt_name: menu_ux_color_edit
+  :env_var: MDE_MENU_UX_COLOR_EDIT
+  :description: Color of menu ux when it is edit
+  :default:
+  :procname: val_as_str
+- :opt_name: menu_ux_color_exec
+  :env_var: MDE_MENU_UX_COLOR_EXEC
+  :description: Color of menu ux when it is exec
+  :default:
+  :procname: val_as_str
+- :opt_name: menu_ux_color_readonly
+  :env_var: MDE_MENU_UX_COLOR_READONLY
+  :description: Color of menu ux when it is read-only
+  :default:
+  :procname: val_as_str
 - :opt_name: menu_ux_row_format
   :env_var: MDE_MENU_UX_ROW_FORMAT
   :description: Format for UX row
@@ -1164,13 +1219,6 @@
 
     Choose a file:
   :procname: val_as_str
-- :opt_name: prompt_select_output
-  :env_var: MDE_PROMPT_SELECT_OUTPUT
-  :default: |2-
-
-    Choose a file:
-  :description: Prompt to select a saved file
-  :procname: val_as_str
 - :opt_name: prompt_ux_enter_a_value
   :env_var: MDE_PROMPT_UX_ENTER_A_VALUE
   :description: Prompt to enter a value for UX blocks
@@ -1223,6 +1271,11 @@
 - :opt_name: pwd
   :long_name: pwd
   :description: Print the gem's home directory
+- :opt_name: required_lines_with_source_comments
+  :env_var: MDE_REQUIRED_LINES_WITH_SOURCE_COMMENTS
+  :description: Add comments about source to blocks of required lines
+  :default: false
+  :procname: val_as_bool
 - :opt_name: run_last_script
   :long_name: run-last-script
   :description: Run most recently saved script
@@ -1311,6 +1364,11 @@
   :description: Screen width for document and interface. 0 to use the actual dimension.
   :default: 0
   :procname: val_as_int
+- :opt_name: script_comment_block_name_format
+  :env_var: MDE_SCRIPT_COMMENT_BLOCK_NAME_FORMAT
+  :description: format for block name in script comments
+  :default: "%{block} %{time}"
+  :procname: val_as_str
 - :opt_name: script_execution_frame_color
   :env_var: MDE_SCRIPT_EXECUTION_FRAME_COLOR
   :description: script_execution_frame_color
@@ -1440,10 +1498,36 @@
   :default:
   - fg_bg_rgbh_cf_cf_cf_14_18_1c
   - fg_bg_rgbh_df_df_df_24_24_24
+- :opt_name: table_row_multi_line_delimiter
+  :env_var: MDE_TABLE_ROW_MULTI_LINE_DELIMITER
+  :description: Multi-line-table delimiter
+  :default: "|"
+  :procname: val_as_str
+- :opt_name: table_row_multi_line_match
+  :env_var: MDE_TABLE_ROW_MULTI_LINE_MATCH
+  :description: Pattern for multi-line-table rows
+  :default: "^(?<indent>[ \\t]*)(?<line>(?<text>\\|.*?)(?<trailing>[ \\t]*))$"
+  :procname: val_as_str
+- :opt_name: table_row_single_line_delimiter
+  :env_var: MDE_TABLE_ROW_SINGLE_LINE_DELIMITER
+  :description: Single-line-table delimiter
+  :default: "!"
+  :procname: val_as_str
+- :opt_name: table_row_single_line_match
+  :env_var: MDE_TABLE_ROW_SINGLE_LINE_MATCH
+  :description: Pattern for single-line-table rows
+  :default: "^(?<indent>[ \\t]*)(?<line>(?<text>!.*?)(?<trailing>[ \\t]*))$"
+  :procname: val_as_str
 - :opt_name: table_separator_line_color
   :env_var: MDE_TABLE_SEPARATOR_LINE_COLOR
   :description: Color for table separator line
   :default: fg_bg_rgbh_df_df_00_14_18_1c
+- :opt_name: tables_into_columns
+  :env_var: MDE_TABLES_INTO_COLUMNS
+  :description: Format tables as columns
+  :arg_name: BOOL
+  :default: true
+  :procname: val_as_bool
 - :opt_name: user_must_approve
   :long_name: user-must-approve
   :short_name: q

data/lib/string_util.rb

@@ -29,3 +29,83 @@ class String
     end
   end
 end
+
+# String.delete_even_chars / String.delete_even_chars!
+#
+# Class methods that remove the 2nd, 4th, 6th, ... characters from a string.
+#
+# Behavior
+# - Operates on Unicode grapheme clusters via /\X/ to avoid splitting emoji
+#   and combining sequences—“user-visible characters” are treated as units.
+# - .delete_even_chars(str) returns a new string consisting of the 1st, 3rd,
+#   5th, ... clusters from +str+.
+# - .delete_even_chars!(str) modifies +str+ in place using #replace and
+#   returns it (raises FrozenError if +str+ is frozen).
+#
+# Examples
+#   String.delete_even_chars("abcdef")      # => "ace"
+#   String.delete_even_chars("áb̂c̆")        # keeps 1st, 3rd, ... clusters intact
+#   s = "👨‍👩‍👧‍👦🙂x"; String.delete_even_chars!(s)  # modifies s
+#
+class String
+  def delete_even_chars
+    clusters = scan(/\X/)
+    return dup if clusters.length <= 1
+
+    clusters.each_with_index
+            .select { |_, i| i.even? } # keep 1st, 3rd, 5th... (0-based even)
+            .map(&:first)
+            .join
+  end
+
+  def delete_even_chars!
+    replace(delete_even_chars)
+  end
+end
+
+# String#sort_chars / String#sort_chars!
+#
+# Adds methods to order a string's user-visible characters (Unicode grapheme
+# clusters) and return the joined result.
+#
+# Behavior
+# - Sorts by Ruby’s default ordering of the grapheme cluster strings.
+# - Preserves emoji and combining sequences by splitting on /\X/.
+# - Optional case-insensitive key and reverse ordering.
+# - Optional custom comparator block; if given, it takes precedence.
+#
+# API
+#   String#sort_chars(reverse: false, casefold: false) { |a, b| ... } -> String
+#   String#sort_chars!(reverse: false, casefold: false) { |a, b| ... } -> self
+#
+# Examples
+#   "cba".sort_chars                     #=> "abc"
+#   "Baß".sort_chars(casefold: true)     #=> "aBß"
+#   "👩‍💻🚀a".sort_chars                  #=> "a👩‍💻🚀" (clusters kept intact)
+#   "bca".sort_chars { |a,b| b <=> a }   #=> "cba" (custom comparator)
+#
+# Notes
+# - For locale-aware collation, integrate a collator and use the block form.
+#
+class String
+  def sort_chars(reverse: false, casefold: false, &block)
+    clusters = scan(/\X/)
+    return self if clusters.length <= 1
+
+    sorted =
+      if block
+        clusters.sort(&block)
+      elsif casefold
+        clusters.sort_by(&:downcase)
+      else
+        clusters.sort
+      end
+
+    sorted.reverse! if reverse
+    sorted.join
+  end
+
+  def sort_chars!(reverse: false, casefold: false, &block)
+    replace(sort_chars(reverse: reverse, casefold: casefold, &block))
+  end
+end