From a50cab27f0ca699781cb8201de44cf403a4c29c9 Mon Sep 17 00:00:00 2001 From: Kevin Day Date: Sat, 7 Jan 2023 19:06:10 -0600 Subject: [PATCH] Update: Add more detailed documentation to fss_status_code and status_code. --- level_3/status_code/c/fss/main.c | 2 ++ level_3/status_code/c/fss/print.c | 32 +++++++++++++++++++++++ level_3/status_code/c/fss/print.h | 39 +++++++++++++++++++++++++++++ level_3/status_code/c/main/common.h | 14 +++++++++-- level_3/status_code/c/main/main.c | 1 + level_3/status_code/c/main/print.c | 23 +++++++++++++++++ level_3/status_code/c/main/print.h | 20 +++++++++++++++ level_3/status_code/data/build/settings.fss | 2 +- 8 files changed, 130 insertions(+), 3 deletions(-) create mode 100644 level_3/status_code/c/fss/print.c create mode 100644 level_3/status_code/c/fss/print.h diff --git a/level_3/status_code/c/fss/main.c b/level_3/status_code/c/fss/main.c index baf7772..6da78bb 100644 --- a/level_3/status_code/c/fss/main.c +++ b/level_3/status_code/c/fss/main.c @@ -1,5 +1,6 @@ #include "status_code.h" #include "../main/status_code.h" +#include "print.h" int main(const int argc, const f_string_t *argv, const f_string_t *envp) { @@ -9,6 +10,7 @@ int main(const int argc, const f_string_t *argv, const f_string_t *envp) { setting.program_name_long = &status_code_fss_program_name_long_s; setting.status_string_from = &fll_fss_status_string_from; setting.status_string_to = &fll_fss_status_string_to; + setting.status_string_help_detail = &status_code_fss_print_help_detail; f_console_parameter_t parameters[] = status_code_console_parameter_t_initialize; data.parameters.array = parameters; diff --git a/level_3/status_code/c/fss/print.c b/level_3/status_code/c/fss/print.c new file mode 100644 index 0000000..f70e49c --- /dev/null +++ b/level_3/status_code/c/fss/print.c @@ -0,0 +1,32 @@ +#include "status_code.h" +#include "../main/status_code.h" +#include "print.h" + +#ifdef __cplusplus +extern "C" { +#endif + +#ifndef _di_status_code_fss_print_help_detail_ + void status_code_fss_print_help_detail(void * const setting, const fl_print_t print) { + + fl_print_format(" The FLL programs use a %[16-bit unsigned integer%] to represent the return status of programs and functions.%r%r", print.to, print.set->notable, print.set->notable, f_string_eol_s, f_string_eol_s); + + fl_print_format(" Programs may print a generic error with one of these codes.%r", print.to, f_string_eol_s); + fl_print_format(" This is a tool for converting to or converting from these codes.%r%r", print.to, f_string_eol_s, f_string_eol_s); + + fl_print_format(" The %[16-bit unsigned integer%] also has the first two high-order bits used to represent flags.%r", print.to, print.set->notable, print.set->notable, f_string_eol_s); + fl_print_format(" These flags are the %[error%] bit and the %[warning%] bit.%r", print.to, print.set->notable, print.set->notable, print.set->notable, print.set->notable, f_string_eol_s); + fl_print_format(" When neither of these flags are set, then the status is considered %[fine%].%r%r", print.to, print.set->notable, print.set->notable, f_string_eol_s, f_string_eol_s); + + fl_print_format(" This operates identical to the %[status_codes%] program except that this program handles additional codes regarding FSS.%r", print.to, print.set->notable, print.set->notable, f_string_eol_s); + fl_print_format(" These special codes numericaly appear after the %[F_status_code_last%] code.%r", print.to, print.set->notable, print.set->notable, f_string_eol_s); + fl_print_format(" These codes stop at the %[F_fss_status_code_last%] code.%r%r", print.to, print.set->notable, print.set->notable, f_string_eol_s, f_string_eol_s); + + fl_print_format(" Each code will be printed on its own line.%r", print.to, f_string_eol_s); + fl_print_format(" Errors regarding each code may be printed on its own line.%r", print.to, f_string_eol_s); + } +#endif // _di_status_code_fss_print_help_detail_ + +#ifdef __cplusplus +} // extern "C" +#endif diff --git a/level_3/status_code/c/fss/print.h b/level_3/status_code/c/fss/print.h new file mode 100644 index 0000000..5cb2e92 --- /dev/null +++ b/level_3/status_code/c/fss/print.h @@ -0,0 +1,39 @@ +/** + * FLL - Level 3 + * + * Project: Status Code + * API Version: 0.7 + * Licenses: lgpl-2.1-or-later + */ +#ifndef _status_code_fss_print_h +#define _status_code_fss_print_h + +#ifdef __cplusplus +extern "C" { +#endif + +/** + * Print help detailed part of the help for fss_status_code. + * + * This is designed to be called from within status_code_print_help(). + * This neither locks nor unlocks the stream and expects the stream to be unlocked. + * + * @param setting + * The main program settings. + * (Must be of type status_code_setting_t.) + * + * This does not alter setting.status. + * @param print + * The output structure to print to. + * + * @see status_code_print_help() + */ +#ifndef _di_status_code_fss_print_help_detail_ + extern void status_code_fss_print_help_detail(void * const setting, const fl_print_t print); +#endif // _di_status_code_fss_print_help_detail_ + +#ifdef __cplusplus +} // extern "C" +#endif + +#endif // _status_code_fss_print_h diff --git a/level_3/status_code/c/main/common.h b/level_3/status_code/c/main/common.h index fb45ade..94d0422 100644 --- a/level_3/status_code/c/main/common.h +++ b/level_3/status_code/c/main/common.h @@ -71,9 +71,16 @@ extern "C" { /** * The program defines. + * + * macro_status_code_setting: + * - Used to represent a cast to ((status_code_setting_t *) setting). + * - Simplifies the number of parenthesis used to make code slightly cleaner. + * - Is wrapped in a parenthesis and not a block. */ #ifndef _di_status_code_d_ #define status_code_signal_check_d 20000 + + #define macro_status_code_setting(setting) ((status_code_setting_t *) setting) #endif // _di_status_code_d_ /** @@ -222,8 +229,9 @@ extern "C" { * line_first: A string expected to represent either "\n" or NULL to allow for easy handling of when to print first new line or not. * line_last: A string expected to represent either "\n" or NULL to allow for easy handling of when to print last new line or not. * - * status_string_from: A pointer to the status string function (usually either fll_status_string_from() or fll_fss_status_string_from()). - * status_string_to: A pointer to the status string function (usually either f_status_string_to() or fll_fss_status_string_to()). + * status_string_from: A pointer to the status string function (usually either fll_status_string_from() or fll_fss_status_string_from()). + * status_string_to: A pointer to the status string function (usually either f_status_string_to() or fll_fss_status_string_to()). + * status_string_help_detail: Print additional, more detailed help, in the help page (The setting paramete must be of type status_code_setting_t). */ #ifndef _di_status_code_setting_t_ typedef struct { @@ -239,6 +247,7 @@ extern "C" { f_status_t (*status_string_from)(const f_string_static_t name, f_status_t * const code); f_status_t (*status_string_to)(const f_status_t code, f_string_static_t * const name); + void (*status_string_help_detail)(void * const setting, const fl_print_t print); } status_code_setting_t; #define status_code_setting_t_initialize \ @@ -251,6 +260,7 @@ extern "C" { 0, \ 0, \ 0, \ + 0, \ } #endif // _di_status_code_setting_t_ diff --git a/level_3/status_code/c/main/main.c b/level_3/status_code/c/main/main.c index 1771c67..205f557 100644 --- a/level_3/status_code/c/main/main.c +++ b/level_3/status_code/c/main/main.c @@ -8,6 +8,7 @@ int main(const int argc, const f_string_t *argv, const f_string_t *envp) { setting.program_name_long = &status_code_program_name_long_s; setting.status_string_from = &fll_status_string_from; setting.status_string_to = &f_status_string_to; + setting.status_string_help_detail = &status_code_print_help_detail; f_console_parameter_t parameters[] = status_code_console_parameter_t_initialize; data.parameters.array = parameters; diff --git a/level_3/status_code/c/main/print.c b/level_3/status_code/c/main/print.c index c3a9101..7b7b807 100644 --- a/level_3/status_code/c/main/print.c +++ b/level_3/status_code/c/main/print.c @@ -118,6 +118,10 @@ extern "C" { status_code_program_help_parameters_s ); + if (setting->status_string_help_detail) { + setting->status_string_help_detail(setting, print); + } + f_print_dynamic_raw(setting->line_last, print.to); f_file_stream_flush(print.to); @@ -127,6 +131,25 @@ extern "C" { } #endif // _di_status_code_print_help_ +#ifndef _di_status_code_print_help_detail_ + void status_code_print_help_detail(void * const void_setting, const fl_print_t print) { + + fl_print_format(" The FLL programs use a %[16-bit unsigned integer%] to represent the return status of programs and functions.%r%r", print.to, print.set->notable, print.set->notable, f_string_eol_s, f_string_eol_s); + + fl_print_format(" Programs may print a generic error with one of these codes.%r", print.to, f_string_eol_s); + fl_print_format(" This is a tool for converting to or converting from these codes.%r%r", print.to, f_string_eol_s, f_string_eol_s); + + fl_print_format(" The %[16-bit unsigned integer%] also has the first two high-order bits used to represent flags.%r", print.to, print.set->notable, print.set->notable, f_string_eol_s); + fl_print_format(" These flags are the %[error%] bit and the %[warning%] bit.%r", print.to, print.set->notable, print.set->notable, print.set->notable, print.set->notable, f_string_eol_s); + fl_print_format(" When neither of these flags are set, then the status is considered %[fine%].%r%r", print.to, print.set->notable, print.set->notable, f_string_eol_s, f_string_eol_s); + + fl_print_format(" These codes stop at the %[F_status_code_last%] code.%r%r", print.to, print.set->notable, print.set->notable, f_string_eol_s, f_string_eol_s); + + fl_print_format(" Each code will be printed on its own line.%r", print.to, print.set->notable, print.set->notable, f_string_eol_s); + fl_print_format(" Errors regarding each code may be printed on its own line.%r", print.to, f_string_eol_s); + } +#endif // _di_status_code_print_help_detail_ + #ifndef _di_status_code_print_line_first_locked_ f_status_t status_code_print_line_first_locked(status_code_setting_t * const setting, const fl_print_t print) { diff --git a/level_3/status_code/c/main/print.h b/level_3/status_code/c/main/print.h index 3caab26..9252fbe 100644 --- a/level_3/status_code/c/main/print.h +++ b/level_3/status_code/c/main/print.h @@ -108,6 +108,26 @@ extern "C" { #endif // _di_status_code_print_help_ /** + * Print help detailed part of the help. + * + * This is designed to be called from within status_code_print_help(). + * This neither locks nor unlocks the stream and expects the stream to be unlocked. + * + * @param setting + * The main program settings. + * (Must be of type status_code_setting_t.) + * + * This does not alter setting.status. + * @param print + * The output structure to print to. + * + * @see status_code_print_help() + */ +#ifndef _di_status_code_print_help_detail_ + extern void status_code_print_help_detail(void * const setting, const fl_print_t print); +#endif // _di_status_code_print_help_detail_ + +/** * Print first new line, unless verbosity says otherwise. * * This is generally either the first line in the program or the first line printed before an error message. diff --git a/level_3/status_code/data/build/settings.fss b/level_3/status_code/data/build/settings.fss index 8031b35..dd2da52 100644 --- a/level_3/status_code/data/build/settings.fss +++ b/level_3/status_code/data/build/settings.fss @@ -26,7 +26,7 @@ build_libraries-individual -lfll_error -lfll_print -lfll_program -lfll_status_st build_libraries-level -lfll_2 -lfll_1 -lfll_0 build_libraries-monolithic -lfll -build_sources_program fss/main.c +build_sources_program fss/main.c fss/print.c build_script yes build_shared yes -- 1.8.3.1