diff --git a/include/fsm.h b/include/fsm.h new file mode 100644 index 0000000..cc466d0 --- /dev/null +++ b/include/fsm.h @@ -0,0 +1,303 @@ +/** + * @file + * FSM (Finite State Machine) header + * + * This file is part of Gem-graph. + * + * @cond LICENSE + * Copyright © 2021 Libre en Communs + * Copyright © 2021-2024 Adrien Bourmault + * Copyright © 2021-2024 Jean Sirmai + * + * This program is free software: you can redistribute it and/or modify it under + * the terms of the GNU Affero General Public License as published by the Free + * Software Foundation, eisrc/log/ther version 3 of the License, or (at your option) any + * later version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS + * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more + * details. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see . + * @endcond + * + * + * The fsm header lists all the structures that the log will need. + * + * The two structures and the two enums listed below will stay in the fsm header. + * + * All functions but the last one will be in a dedicated file: src/log/oper.c + * This file will contain the declaration of the log with the static attribute, + * which will force all the functions that read or write it to be in it. + * Forcing all functions that read or write to the log to be grouped together + * will prevent uncontrolled operations. + * + * The four most important functions are: + * - fsm_init_log() + * - fsm_publish_log() + * - fsm_clear_log() + * - fsm_add_log_event() + * . + * + * A typical list would also feature the last three functions: + * - fsm_get_log_length() + * - fsm_seek_log() + * - fsm_remove_log() + * . + * but in the case of a log, their usefulness remains to be demonstrated. + * + * + * A last function: fsm_add_log() will be in another file: src/log/manager.c. + * All events sent to the log must pass through this function, which allows them + * to be filtered before being published in the log. + * + * Here's how the procedure works. + * A message is send to the fsm_add_log() function for each documented event. + * If there are too many events, this is the only function that allows you to + * apply one or more filters before publication. This allows you to select the + * events of interest, which can vary depending on the type of session. + * These filters can operate on any the following five parameters: + * severity, source, file_source, function_source, string_value. + * They can be combined using any logical operators and parentheses. + * + * 'severity' is one of the following pre-defined values: + * FATAL - ERROR - WARN - INFO - DEBUG - TRACE + * + * 'source' is a pre-defined value (typically a name of a structure) that can be + * associated to each event. It can be set to 'NULL'. + * + * file_source, function_source and string_value are three strings. + * + * Here is the list of all the structures that the log will need. The functions + * will be documented in future commits. + * + * - fsm_log_struct() + * - fsm_log_struct_unit() + * . + * + * - fsm_enum_log_severity() + * - fsm_enum_log_source() + * . + * + * - fsm_init_log() + * - fsm_publish_log() + * - fsm_clear_log() + * - fsm_add_log_event() + * - fsm_get_log_length() + * - fsm_seek_log() + * - fsm_remove_log() + * . + * + * - fsm_add_log() + * . + */ + + +#pragma once + +/******************************************************************************/ +/* L O G / J O U R N A L */ +/******************************************************************************/ + +/** + * The 'severity' enum conforms to canonical log levels: + * FATAL, ERROR, WARN, INFO, DEBUG, TRACE + * + * https://betterstack.com/community/guides/logging/logging-best-practices/ + * https://en.wikipedia.org/wiki/Syslog + * + * All logs must contain at least one item from this enum and only one. + * This item can not be set to NULL. + * + * @see fsm_add_log() + */ +enum fsm_enum_log_severity { + FATAL, /**< (or CRITICAL) an unrecoverable failure that prevents the whole + application from doing any further useful work */ + ERROR, /**< an irremediable situation that hinders the execution of a + specific operation within the application */ + WARN, /**< something unexpected has occurred, but the application can + continue to function normally for the time being */ + INFO, /**< (or MESSAGE) a significant event occurs while the system is + operating normally */ + DEBUG, /**< a description of system states in sufficient detail to give + developers clues as to the cause of an error */ + TRACE /**< provides a systematic overview of code execution but comes at + a cost in terms of performance */ +}; + +/** + * A list of structures or states that may be involved in program events. + * + * All logs must contain at least one item from this list or the value NULL. + * + * Only some main items of this list are commented on today. Further comments + * will depend on its usage and structure which are just beginning to evolve. + * + * NB about PAGE: user_tree and selected_rule are two vertical panes which it + * is a good idea to place next to each other on the rules page so that you can + * switch between them more easily or have a parallel view of the two. + * + * @see fsm_add_log() + */ +enum fsm_enum_log_source { + AUTO_NOTIFICATION, /**< (not a source) */ + DESTINATION, /**< SOURCE, TARGET */ SOURCE, TARGET, + FSM_CONTENT, /**< LOG, FSM, PREFER */ LOG, FSM, PREFER, + SRC_CONTENT, /**< MAIN, APP, WIDGETS, SIGNAL */ MAIN, APP, WIDGETS, SIGNAL, + WINDOW, /**< MAIN, DIALOG, MODAL, TEXT */ + MAIN_WINDOW, DIALOG_WINDOW, MODAL_WINDOW, TEXT_WINDOW, + TOPBAR, /**< LEFT, CENTER, RIGHT */ TOPBAR_LEFT, TOPBAR_CENTER, TOPBAR_RIGHT, + PAGE, /**< SYNTH, STATE, RULES, [USER TREE], [SELECTED_RULE], MEASURES, RESULTS */ + SYNTH_PAGE, STATE_PAGE, RULES_PAGE, MEASURES_PAGE, RESULTS_PAGE, + SYNTHESIS, /**< GLAREA, CAMERA, CONTROLS, RESULTS (duplicates from other pages) */ + SYNTH_GLAREA, SYNTH_CAMERA, SYNTH_CONTROLS, SYNTH_RESULTS, + SYNTH_DATA, /**< SYNTH_TIME_DEP_RESULTS, SYNTH_TIME_INDEP_RESULTS */ + SYNTH_TIME_DEP_RESULTS, SYNTH_TIME_INDEP_RESULTS, + STATE_VIEW, /**< TOP, BOTTOM, GLAREA, CAMERA */ + STATE_TOP, STATE_BOTTOM, STATE_GLAREA, STATE_CAMERA, + SINGLE_RULE, /**< RULE_GEOMETRY, RULE_ALGEBRA */ + RULE_GEOMETRY, /**< VIEW_BEFORE, VIEW_AFTER, RULE_GLAREA, RULE_CAMERA */ + VIEW_BEFORE, VIEW_AFTER, RULE_GLAREA, RULE_CAMERA, + RULE_ALGEBRA, /**< LIST_CONDITIONS, LIST_ASSIGNMENTS, IDENTITY */ + RULE_LIST_CONDITION, RULE_LIST_ASSIGNMENTS, RULE_IDENTITY, + TREE_RULES, /**< TREE, COMPARE, USE */ + RULES_TREE, RULES_COMPARE, RULES_USE, + MEASURES, /**< TOOLS, ACTIVITY, DISPLAY */ + MEASURES_TOOLS, MEASURES_ACTIVITY, MEASURES_DISPLAY, + RESULTS, /**< TIME_DEPPENDENT, TIME_INDEPENDENT */ + TIME_DEP_RESULTS, TIME_INDEP_RESULTS, + GTK_WIDGETS, /**< LABEL, BUTTON, SCROLL, GLAREA, SLIDER, EXPANDER,... + * (non limitative) */ + WIDGET, BUTTON, SCROLL, GLAREA, TEXT, LABEL, TREE, SLIDER, EXPANDER, + ENTRY, SLIDER_X, SLIDER_Y, SLIDER_Z, SLIDER_A, SLIDER_B, SLIDER_C, + OTHERS, /**< fsm possible states: [EXEC / EDIT], [STATE / RULES / DATA], + * (non limitative) */ + ON_SWITCH_EXEC_EDIT, ON_SWITCH_STATE_RULES_DATA, +}; + +//----------------------------------------------------------------------------- + +/** + * Structure of a log unit. + * + * @callergraph + * @see fsm_log_struct + */ +typedef struct fsm_log_struct_unit + { + long yy_dd_mm; /**< * date of the event reported in the log */ + long usec; /**< * with microseconds precision */ + const char *file_source; /**< * emitter file */ + const char *function_source; /**< * emitter function */ + const char *string_value; /**< * any event descriptors */ + struct fsm_log_struct_unit *prev; /**< * chained list */ + struct fsm_log_struct_unit *next; /**< * chained list */ + } + fsm_log_struct_unit; + + +/** + * Two links towards the previous and the next unit are required to initialize + * and manage a double-chained list. + * + * @callgraph + * @see fsm_log_struct_unit + * + * @callergraph + * @see fsm_init_log() + * @see fsm_publish_log() + * @see fsm_clear_log() + * @see fsm_add_log_event() + * @see fsm_get_log_length() + * @see fsm_seek_log() + * @see fsm_remove_log() + */ +typedef struct { + fsm_log_struct_unit *first; /**< * required */ + fsm_log_struct_unit *last; /**< * required */ + } + fsm_log_struct; + +//----------------------------------------------------------------------------- + +void fsm_init_log (fsm_log_struct *jj); +void fsm_publish_log (fsm_log_struct jj); +void fsm_clear_log (fsm_log_struct *jj); + +void fsm_add_log_event (fsm_log_struct *jj, + const char *file_source, + const char *function_source, + const char *string_value); + +int fsm_get_log_length(fsm_log_struct jj); +void fsm_seek_log (fsm_log_struct jj, + long usec, + const char *file_source, + const char *function_source, + const char *string_value); +long fsm_remove_log (fsm_log_struct *jj, + const char *file_source, + const char *function_source, + const char *string_value); + + +/** + * @brief (1) This comment is not a duplicate: it will be displaced in the file: + * src/log/manager.c in next commits. + * + * It will be mandatory for any event to call the function fsm_add_log() + * to be published in the journal and it is here and only here that filters will + * be found. + * + * -- + * + * @details The fsm_struct_journal (gg_logs) will be a static instance in a + * dedicated file: src/log/manager.c + * Therefore, all the functions that read or write it will be in this file. + * This is to avoid uncontrolled operations on it. + * + * While the program is running, messages will be sent to the fsm_add_log() + * function for each documented event. + * If there are too many events, this is the only function that allows you to + * apply one or more filters before publication. This allows you to select the + * events of interest, which can vary depending on the type of session. + * + * These filters can operate on any of the following five parameters: + * severity, source, file_source, function_source, string_value . + * They can be combined using any logical operators and parentheses. + * + * -- + * + * @since 2024-08 + * + * @callgraph + * @see fsm_add_log_event() insertion into the log list + * + * @callergraph @see Almost all functions will have to report events and will + * therefore call fsm_add_log(). + * @see main() will send the first and last messages. + * + * + * @param severity: one of the following pre-defined values + * + * FATAL - ERROR - WARN - INFO - DEBUG - TRACE + * + * @param source: a pre-defined value (a name of a structure) that can be + * associated to each event. It can be set to 'NULL'. + * + * @param *file_source the name of the file that emits the event + * @param *function_source the function that emits the event + * @param *string_value any value that better specifies the event + * + * @see fsm_enum_log_severity + * @see fsm_enum_log_source + */ +void fsm_add_log (int severity, + int source, + const char *file_source, + const char *function_source, + const char *string_value); + diff --git a/src/main.c b/src/main.c index 2f3bafd..4a577d9 100644 --- a/src/main.c +++ b/src/main.c @@ -3,7 +3,7 @@ * * Gem-graph main file * - * This file is part of Gem-graph. + * This file is part of Gem-graph. It contains only the main() function. * * @cond LICENSE * Copyright © 2021 Libre en Communs @@ -23,6 +23,23 @@ * You should have received a copy of the GNU Affero General Public License * along with this program. If not, see . * @endcond + * + * --- + * + * The main() function will **initialise** the log, the finite state machine (fsm), + * the application and the windows and **close** all the elements it opened + * before the end of program execution. + * In this commit, it does not implement g_application_activate() and has no + * handlers connected to the 'activate' signal (which triggers an error message). + * + * The default values of the fsm initial state will be specified in: + * src/fsm/dispatch(). They are user preference and, in accordance, the overview + * page of the current model will be displayed as they specify it in: + * src/widget/main_window/designer/widget_design_main_window(). + * + * About code organization, see src/readme.dox + * + * --- */ #include @@ -32,9 +49,11 @@ int main (int argc, char **argv) GtkApplication *app; int status; - app = gtk_application_new ("org.jean.GTK4_GG_hack", G_APPLICATION_DEFAULT_FLAGS); + app = gtk_application_new ("org.gem-graph", G_APPLICATION_DEFAULT_FLAGS); + //g_signal_connect (app, "activate", G_CALLBACK (on_main_window_activation), NULL); //g_signal_connect (app, "activate", G_CALLBACK (on_dialog_window_activation), NULL); + status = g_application_run (G_APPLICATION (app), argc, argv); g_object_unref (app); diff --git a/src/readme.docs.c b/src/readme.docs.c new file mode 100644 index 0000000..00862d1 --- /dev/null +++ b/src/readme.docs.c @@ -0,0 +1,63 @@ +/** + * @file + * Gem-graph-client src/readme.docs file + * + * This file is part of Gem-graph. + * + * @cond LICENSE + * Copyright © 2021 Libre en Communs + * Copyright © 2021-2024 Adrien Bourmault + * Copyright © 2021-2024 Jean Sirmai + * + * This program is free software: you can redistribute it and/or modify it under + * the terms of the GNU Affero General Public License as published by the Free + * Software Foundation, either version 3 of the License, or (at your option) any + * later version. + * + * This program is distributed in the hope that it will be useful, but WITHOUT + * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS + * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more + * details. + * + * You should have received a copy of the GNU Affero General Public License + * along with this program. If not, see . + * @endcond + * + * @details + * The code files are all located in the src (sources) directory. + * + * They are divided according to several *types of organisation*: + * + * - *hierarchical*: the widgets that give the windows their appearance are + * organised in the form of a tree. + * Windows are the first level of depth. + * Next come the windows contents: the title bars and the pages. + * The pages are designed to occupy the windows space below the title bars. + * Each of these pages has its own hierarchical structure: it can be divided + * into horizontal or vertical strips, which can themselves be divided in the + * same way, with varying levels of depth right down to the last containers + * which contain lists of widgets such as buttons, bars, entries or images. + * + * - *list*: the main *sections* of the fsm (finite state machine) constitute + * a list of at least four elements, each of which defines a set of possible + * states : + * -# execute or edit (managing the appropriate tools states in both cases) + * -# measure, operate on data, prepare displayable results + * -# user preferences + * -# desired state of windows and widgets + * + * The state of the fsm is uniquely defined at all times by all the parameters + * listed in these sections. All program actions depend on this state. + * + * - *transversal*: the other functions that must be easily accessible by all + * the previous functions. They are therefore all located at the root. + * These are the functions that manage graphics, callbacks and utilities. + * Although 'transversal', the log is part of the fsm. + * + * --- + * + * @see + * Model–view–controller || Model–view–viewmodel || Action–domain–responder || + * Multitier_architecture https://en.wikipedia.org/wiki/Multitier_architecture + * (presentation, logic, data) + */