From efda9ea9dd8becedfd441cb8ffa957b88fd1bceb Mon Sep 17 00:00:00 2001
From: Kevin Day <Kevin@kevux.org>
Date: Thu, 13 Feb 2025 22:17:50 -0600
Subject: [PATCH] Update: Help printing functions and callbacks.

Have most of the help printing functions that might be used as `fl_print_call_t` be consistent with that prototype structure.

Fix some issues where `data.callback` is still used and should now instead be `data.call`.
---
 level_3/fss_read/c/main/print/message.c  |  6 ++++--
 level_3/fss_read/c/main/print/message.h  |  8 +++++++-
 level_3/fss_write/c/main/print/message.c |  6 ++++--
 level_3/fss_write/c/main/print/message.h |  8 +++++++-
 level_3/iki_read/c/eki/main.c            | 14 +++++++-------
 level_3/iki_read/c/eki/print.c           |  6 ++++--
 level_3/iki_read/c/eki/print.h           |  8 +++++++-
 level_3/iki_read/c/eki/process.c         | 32 ++++++++++++++++----------------
 level_3/iki_read/c/iki/main.c            | 14 +++++++-------
 level_3/iki_read/c/iki/print.c           |  6 ++++--
 level_3/iki_read/c/iki/print.h           |  8 +++++++-
 level_3/iki_read/c/iki/process.c         | 32 ++++++++++++++++----------------
 level_3/iki_write/c/main/print/message.c |  6 ++++--
 level_3/iki_write/c/main/print/message.h |  8 +++++++-
 14 files changed, 101 insertions(+), 61 deletions(-)

diff --git a/level_3/fss_read/c/main/print/message.c b/level_3/fss_read/c/main/print/message.c
index 3cd1cb9..34f3bcc 100644
--- a/level_3/fss_read/c/main/print/message.c
+++ b/level_3/fss_read/c/main/print/message.c
@@ -5,9 +5,9 @@ extern "C" {
 #endif
 
 #ifndef _di_fss_read_print_message_help_
-  void fss_read_print_message_help(fl_print_t * const print) {
+  f_status_t fss_read_print_message_help(fl_print_t * const print) {
 
-    if (!print) return;
+    if (!print) return F_status_set_error(F_output_not);
 
     fll_program_print_help_option_standard(print);
 
@@ -27,6 +27,8 @@ extern "C" {
     fll_program_print_help_option(print, fss_read_short_select_s, fss_read_long_select_s, f_console_symbol_short_normal_s, f_console_symbol_long_normal_s, "  Select sub-Content at this index.");
     fll_program_print_help_option(print, fss_read_short_total_s, fss_read_long_total_s, f_console_symbol_short_normal_s, f_console_symbol_long_normal_s, "   Print the total number of lines.");
     fll_program_print_help_option(print, fss_read_short_trim_s, fss_read_long_trim_s, f_console_symbol_short_normal_s, f_console_symbol_long_normal_s, "    Trim Object names on select or print.");
+
+    return F_okay;
   }
 #endif // _di_fss_read_print_message_help_
 
diff --git a/level_3/fss_read/c/main/print/message.h b/level_3/fss_read/c/main/print/message.h
index beeb4aa..4e705ee 100644
--- a/level_3/fss_read/c/main/print/message.h
+++ b/level_3/fss_read/c/main/print/message.h
@@ -27,9 +27,15 @@ extern "C" {
  *   The print.custom is expected to be of type fss_read_main_t.
  *
  *   This does not alter print.custom.setting.state.status.
+ *
+ * @return
+ *   F_okay on success.
+ *   F_output_not on success, but no printing is performed.
+ *
+ *   F_output_not (with error bit) if a parameter is NULL.
  */
 #ifndef _di_fss_read_print_message_help_
-  extern void fss_read_print_message_help(fl_print_t * const print);
+  extern f_status_t fss_read_print_message_help(fl_print_t * const print);
 #endif // _di_fss_read_print_message_help_
 
 /**
diff --git a/level_3/fss_write/c/main/print/message.c b/level_3/fss_write/c/main/print/message.c
index 2e5c349..139817f 100644
--- a/level_3/fss_write/c/main/print/message.c
+++ b/level_3/fss_write/c/main/print/message.c
@@ -5,9 +5,9 @@ extern "C" {
 #endif
 
 #ifndef _di_fss_write_print_message_help_
-  void fss_write_print_message_help(fl_print_t * const print) {
+  f_status_t fss_write_print_message_help(fl_print_t * const print) {
 
-    if (!print) return;
+    if (!print) return F_status_set_error(F_output_not);
 
     fll_program_print_help_option_standard(print);
 
@@ -26,6 +26,8 @@ extern "C" {
     fll_program_print_help_option(print, fss_write_short_prepend_s, fss_write_long_prepend_s, f_console_symbol_short_normal_s, f_console_symbol_long_normal_s, "     Prepend the given white space characters to the start of each multi-line Content.");
     fll_program_print_help_option(print, fss_write_short_single_s, fss_write_long_single_s, f_console_symbol_short_normal_s, f_console_symbol_long_normal_s, "      Use single quotes.");
     fll_program_print_help_option(print, fss_write_short_trim_s, fss_write_long_trim_s, f_console_symbol_short_normal_s, f_console_symbol_long_normal_s, "        Trim Object names.");
+
+    return F_okay;
   }
 #endif // _di_fss_write_print_message_help_
 
diff --git a/level_3/fss_write/c/main/print/message.h b/level_3/fss_write/c/main/print/message.h
index 6e00e71..0bb70e3 100644
--- a/level_3/fss_write/c/main/print/message.h
+++ b/level_3/fss_write/c/main/print/message.h
@@ -27,9 +27,15 @@ extern "C" {
  *   The print.custom is expected to be of type fss_read_main_t.
  *
  *   This does not alter print.custom.setting.state.status.
+ *
+ * @return
+ *   F_okay on success.
+ *   F_output_not on success, but no printing is performed.
+ *
+ *   F_output_not (with error bit) if a parameter is NULL.
  */
 #ifndef _di_fss_write_print_message_help_
-  extern void fss_write_print_message_help(fl_print_t * const print);
+  extern f_status_t fss_write_print_message_help(fl_print_t * const print);
 #endif // _di_fss_write_print_message_help_
 
 /**
diff --git a/level_3/iki_read/c/eki/main.c b/level_3/iki_read/c/eki/main.c
index 803fd9c..3c88a8f 100644
--- a/level_3/iki_read/c/eki/main.c
+++ b/level_3/iki_read/c/eki/main.c
@@ -22,13 +22,13 @@ int main(const int argc, const f_string_t *argv, const f_string_t *envp) {
   data.setting.state.custom = (void *) &data;
   data.setting.state.handle = &fll_program_standard_signal_handle;
 
-  data.callback.identify_alteration = &iki_read_eki_identify_alteration;
-  data.callback.print_data = &iki_read_eki_print_data;
-  data.callback.print_help = &iki_read_eki_print_message_help;
-  data.callback.process_buffer_ranges = &iki_read_eki_process_buffer_ranges;
-  data.callback.process_buffer_ranges_whole = &iki_read_eki_process_buffer_ranges_whole;
-  data.callback.process_buffer_total = &iki_read_eki_process_buffer_total;
-  data.callback.delete_data = &iki_read_eki_delete_data;
+  data.call.identify_alteration = &iki_read_eki_identify_alteration;
+  data.call.print_data = &iki_read_eki_print_data;
+  data.call.print_help = &iki_read_eki_print_message_help;
+  data.call.process_buffer_ranges = &iki_read_eki_process_buffer_ranges;
+  data.call.process_buffer_ranges_whole = &iki_read_eki_process_buffer_ranges_whole;
+  data.call.process_buffer_total = &iki_read_eki_process_buffer_total;
+  data.call.delete_data = &iki_read_eki_delete_data;
 
   f_console_parameter_t parameters[] = iki_read_console_parameter_t_initialize;
   data.program.parameters.array = parameters;
diff --git a/level_3/iki_read/c/eki/print.c b/level_3/iki_read/c/eki/print.c
index 35bada7..88b7bab 100644
--- a/level_3/iki_read/c/eki/print.c
+++ b/level_3/iki_read/c/eki/print.c
@@ -185,9 +185,9 @@ extern "C" {
 #endif // _di_iki_read_eki_print_data_
 
 #ifndef _di_iki_read_eki_print_message_help_
-  void iki_read_eki_print_message_help(fl_print_t * const print) {
+  f_status_t iki_read_eki_print_message_help(fl_print_t * const print) {
 
-    if (!print) return;
+    if (!print || !print->custom) return F_status_set_error(F_output_not);
 
     f_file_stream_lock(print->to);
 
@@ -203,6 +203,8 @@ extern "C" {
 
     f_file_stream_flush(print->to);
     f_file_stream_unlock(print->to);
+
+    return F_okay;
   }
 #endif // _di_iki_read_eki_print_message_help_
 
diff --git a/level_3/iki_read/c/eki/print.h b/level_3/iki_read/c/eki/print.h
index 3eeb09b..3900a28 100644
--- a/level_3/iki_read/c/eki/print.h
+++ b/level_3/iki_read/c/eki/print.h
@@ -52,9 +52,15 @@ extern "C" {
  *   The output structure to print to.
  *
  *   This does not alter print.custom.setting.state.status.
+ *
+ * @return
+ *   F_okay on success.
+ *   F_output_not on success, but no printing is performed.
+ *
+ *   F_output_not (with error bit) if a parameter is NULL.
  */
 #ifndef _di_iki_read_eki_print_message_help_
-  extern void iki_read_eki_print_message_help(fl_print_t * const print);
+  extern f_status_t iki_read_eki_print_message_help(fl_print_t * const print);
 #endif // _di_iki_read_eki_print_message_help_
 
 #ifdef __cplusplus
diff --git a/level_3/iki_read/c/eki/process.c b/level_3/iki_read/c/eki/process.c
index a08eb1c..6823e5a 100644
--- a/level_3/iki_read/c/eki/process.c
+++ b/level_3/iki_read/c/eki/process.c
@@ -284,8 +284,8 @@ extern "C" {
               else {
                 f_file_stream_lock(main->program.output.to);
 
-                if (main->callback.print_data) {
-                  main->callback.print_data(&main->program.output, i);
+                if (main->call.print_data) {
+                  main->call.print_data(&main->program.output, i);
                 }
 
                 f_print_dynamic_raw(f_string_eol_s, main->program.output.to);
@@ -352,8 +352,8 @@ extern "C" {
             else {
               f_file_stream_lock(main->program.output.to);
 
-              if (main->callback.print_data) {
-                main->callback.print_data(&main->program.output, main->setting.at);
+              if (main->call.print_data) {
+                main->call.print_data(&main->program.output, main->setting.at);
               }
 
               f_print_dynamic_raw(f_string_eol_s, main->program.output.to);
@@ -414,8 +414,8 @@ extern "C" {
 
             if (iki_read_signal_check(main)) return;
 
-            if (main->callback.print_data) {
-              main->callback.print_data(&main->program.output, i);
+            if (main->call.print_data) {
+              main->call.print_data(&main->program.output, i);
             }
 
             f_print_dynamic_raw(f_string_eol_s, main->program.output.to);
@@ -481,8 +481,8 @@ extern "C" {
       main->cache.buffer.string[data->delimits.array[i]] = f_iki_syntax_placeholder_s.string[0];
     } // for
 
-    if (main->callback.identify_alteration) {
-      main->callback.identify_alteration(main);
+    if (main->call.identify_alteration) {
+      main->call.identify_alteration(main);
     }
   }
 #endif // _di_iki_read_eki_process_buffer_ranges_prepare_
@@ -548,16 +548,16 @@ extern "C" {
         if (k < main->setting.names.used) {
           if (main->setting.flag & iki_read_main_flag_at_d) {
             if (at++ == main->setting.at) {
-              if (main->callback.print_data) {
-                main->callback.print_data(&main->program.output, j);
+              if (main->call.print_data) {
+                main->call.print_data(&main->program.output, j);
               }
             }
             else {
               f_print_dynamic_partial(main->cache.buffer, data->variable.array[j], main->program.output.to);
             }
           }
-          else if (main->callback.print_data) {
-            main->callback.print_data(&main->program.output, j);
+          else if (main->call.print_data) {
+            main->call.print_data(&main->program.output, j);
           }
         }
         else {
@@ -568,8 +568,8 @@ extern "C" {
       }
       else if (main->setting.flag & iki_read_main_flag_at_d) {
         if (at++ == main->setting.at) {
-          if (main->callback.print_data) {
-            main->callback.print_data(&main->program.output, j);
+          if (main->call.print_data) {
+            main->call.print_data(&main->program.output, j);
           }
         }
         else {
@@ -577,8 +577,8 @@ extern "C" {
         }
       }
       else {
-        if (main->callback.print_data) {
-          main->callback.print_data(&main->program.output, j);
+        if (main->call.print_data) {
+          main->call.print_data(&main->program.output, j);
         }
       }
 
diff --git a/level_3/iki_read/c/iki/main.c b/level_3/iki_read/c/iki/main.c
index 16bf564..531b035 100644
--- a/level_3/iki_read/c/iki/main.c
+++ b/level_3/iki_read/c/iki/main.c
@@ -23,13 +23,13 @@ int main(const int argc, const f_string_t *argv, const f_string_t *envp) {
   data.setting.state.custom = (void *) &data;
   data.setting.state.handle = &fll_program_standard_signal_handle;
 
-  data.callback.identify_alteration = &iki_read_iki_identify_alteration;
-  data.callback.print_data = &iki_read_iki_print_data;
-  data.callback.print_help = &iki_read_iki_print_message_help;
-  data.callback.process_buffer_ranges = &iki_read_iki_process_buffer_ranges;
-  data.callback.process_buffer_ranges_whole = &iki_read_iki_process_buffer_ranges_whole;
-  data.callback.process_buffer_total = &iki_read_iki_process_buffer_total;
-  data.callback.delete_data = &iki_read_iki_delete_data;
+  data.call.identify_alteration = &iki_read_iki_identify_alteration;
+  data.call.print_data = &iki_read_iki_print_data;
+  data.call.print_help = &iki_read_iki_print_message_help;
+  data.call.process_buffer_ranges = &iki_read_iki_process_buffer_ranges;
+  data.call.process_buffer_ranges_whole = &iki_read_iki_process_buffer_ranges_whole;
+  data.call.process_buffer_total = &iki_read_iki_process_buffer_total;
+  data.call.delete_data = &iki_read_iki_delete_data;
 
   f_console_parameter_t parameters[] = iki_read_console_parameter_t_initialize;
   data.program.parameters.array = parameters;
diff --git a/level_3/iki_read/c/iki/print.c b/level_3/iki_read/c/iki/print.c
index a948f0f..ef2ca06 100644
--- a/level_3/iki_read/c/iki/print.c
+++ b/level_3/iki_read/c/iki/print.c
@@ -150,9 +150,9 @@ extern "C" {
 #endif // _di_iki_read_iki_print_data_
 
 #ifndef _di_iki_read_iki_print_message_help_
-  void iki_read_iki_print_message_help(fl_print_t * const print) {
+  f_status_t iki_read_iki_print_message_help(fl_print_t * const print) {
 
-    if (!print) return;
+    if (!print || !print->custom) return F_status_set_error(F_output_not);
 
     f_file_stream_lock(print->to);
 
@@ -168,6 +168,8 @@ extern "C" {
 
     f_file_stream_flush(print->to);
     f_file_stream_unlock(print->to);
+
+    return F_okay;
   }
 #endif // _di_iki_read_iki_print_message_help_
 
diff --git a/level_3/iki_read/c/iki/print.h b/level_3/iki_read/c/iki/print.h
index 2b32584..ef1cb49 100644
--- a/level_3/iki_read/c/iki/print.h
+++ b/level_3/iki_read/c/iki/print.h
@@ -52,9 +52,15 @@ extern "C" {
  *   The output structure to print to.
  *
  *   This does not alter print.custom.setting.state.status.
+ *
+ * @return
+ *   F_okay on success.
+ *   F_output_not on success, but no printing is performed.
+ *
+ *   F_output_not (with error bit) if a parameter is NULL.
  */
 #ifndef _di_iki_read_iki_print_message_help_
-  extern void iki_read_iki_print_message_help(fl_print_t * const print);
+  extern f_status_t iki_read_iki_print_message_help(fl_print_t * const print);
 #endif // _di_iki_read_iki_print_message_help_
 
 #ifdef __cplusplus
diff --git a/level_3/iki_read/c/iki/process.c b/level_3/iki_read/c/iki/process.c
index 489ca45..f61530b 100644
--- a/level_3/iki_read/c/iki/process.c
+++ b/level_3/iki_read/c/iki/process.c
@@ -251,8 +251,8 @@ extern "C" {
             else {
               f_file_stream_lock(main->program.output.to);
 
-              if (main->callback.print_data) {
-                main->callback.print_data(&main->program.output, i);
+              if (main->call.print_data) {
+                main->call.print_data(&main->program.output, i);
               }
 
               f_print_dynamic_raw(f_string_eol_s, main->program.output.to);
@@ -311,8 +311,8 @@ extern "C" {
             else {
               f_file_stream_lock(main->program.output.to);
 
-              if (main->callback.print_data) {
-                main->callback.print_data(&main->program.output, main->setting.at);
+              if (main->call.print_data) {
+                main->call.print_data(&main->program.output, main->setting.at);
               }
 
               f_print_dynamic_raw(f_string_eol_s, main->program.output.to);
@@ -371,8 +371,8 @@ extern "C" {
 
             if (iki_read_signal_check(main)) return;
 
-            if (main->callback.print_data) {
-              main->callback.print_data(&main->program.output, i);
+            if (main->call.print_data) {
+              main->call.print_data(&main->program.output, i);
             }
 
             f_print_dynamic_raw(f_string_eol_s, main->program.output.to);
@@ -438,8 +438,8 @@ extern "C" {
       main->cache.buffer.string[data->delimits.array[i]] = f_iki_syntax_placeholder_s.string[0];
     } // for
 
-    if (main->callback.identify_alteration) {
-      main->callback.identify_alteration(main);
+    if (main->call.identify_alteration) {
+      main->call.identify_alteration(main);
     }
   }
 #endif // _di_iki_read_iki_process_buffer_ranges_prepare_
@@ -499,16 +499,16 @@ extern "C" {
         if (k < main->setting.names.used) {
           if (main->setting.flag & iki_read_main_flag_at_d) {
             if (at++ == main->setting.at) {
-              if (main->callback.print_data) {
-                main->callback.print_data(&main->program.output, j);
+              if (main->call.print_data) {
+                main->call.print_data(&main->program.output, j);
               }
             }
             else {
               f_print_dynamic_partial(main->cache.buffer, data->variable.array[j], main->program.output.to);
             }
           }
-          else if (main->callback.print_data) {
-            main->callback.print_data(&main->program.output, j);
+          else if (main->call.print_data) {
+            main->call.print_data(&main->program.output, j);
           }
         }
         else {
@@ -519,8 +519,8 @@ extern "C" {
       }
       else if (main->setting.flag & iki_read_main_flag_at_d) {
         if (at++ == main->setting.at) {
-          if (main->callback.print_data) {
-            main->callback.print_data(&main->program.output, j);
+          if (main->call.print_data) {
+            main->call.print_data(&main->program.output, j);
           }
         }
         else {
@@ -528,8 +528,8 @@ extern "C" {
         }
       }
       else {
-        if (main->callback.print_data) {
-          main->callback.print_data(&main->program.output, j);
+        if (main->call.print_data) {
+          main->call.print_data(&main->program.output, j);
         }
       }
 
diff --git a/level_3/iki_write/c/main/print/message.c b/level_3/iki_write/c/main/print/message.c
index 97a399b..26e2ec9 100644
--- a/level_3/iki_write/c/main/print/message.c
+++ b/level_3/iki_write/c/main/print/message.c
@@ -5,9 +5,9 @@ extern "C" {
 #endif
 
 #ifndef _di_iki_write_print_message_help_
-  void iki_write_print_message_help(fl_print_t * const print) {
+  f_status_t iki_write_print_message_help(fl_print_t * const print) {
 
-    if (!print) return;
+    if (!print || !print->custom) return F_status_set_error(F_output_not);
 
     fll_program_print_help_option(print, f_console_standard_short_help_s, f_console_standard_long_help_s, f_console_symbol_short_normal_s, f_console_symbol_long_normal_s, "    Print this help message.");
     fll_program_print_help_option(print, f_console_standard_short_dark_s, f_console_standard_long_dark_s, f_console_symbol_short_inverse_s, f_console_symbol_long_inverse_s, "    Output using colors that show up better on dark backgrounds.");
@@ -29,6 +29,8 @@ extern "C" {
     fll_program_print_help_option(print, iki_write_short_object_s, iki_write_long_object_s, f_console_symbol_short_normal_s, f_console_symbol_long_normal_s, " The Object to write.");
     fll_program_print_help_option(print, iki_write_short_single_s, iki_write_long_single_s, f_console_symbol_short_normal_s, f_console_symbol_long_normal_s, " Use single quotes (U+0027).");
     fll_program_print_help_option(print, iki_write_short_wrap_s, iki_write_long_wrap_s, f_console_symbol_short_normal_s, f_console_symbol_long_normal_s, "   Wrap the vocabulary name.");
+
+    return F_okay;
   }
 #endif // _di_iki_write_print_message_help_
 
diff --git a/level_3/iki_write/c/main/print/message.h b/level_3/iki_write/c/main/print/message.h
index 044739c..8a82b71 100644
--- a/level_3/iki_write/c/main/print/message.h
+++ b/level_3/iki_write/c/main/print/message.h
@@ -25,9 +25,15 @@ extern "C" {
  *   The print.custom is expected to be of type iki_write_main_t.
  *
  *   This does not alter print.custom.setting.state.status.
+ *
+ * @return
+ *   F_okay on success.
+ *   F_output_not on success, but no printing is performed.
+ *
+ *   F_output_not (with error bit) if a parameter is NULL.
  */
 #ifndef _di_iki_write_print_message_help_
-  extern void iki_write_print_message_help(fl_print_t * const print);
+  extern f_status_t iki_write_print_message_help(fl_print_t * const print);
 #endif // _di_iki_write_print_message_help_
 
 /**
-- 
1.8.3.1