noms de fonctions conformes à une convention de nommage simple (3 exceptions non corrigées dans graphics)

include/util.h

@@ -32,7 +32,7 @@
 char *util_read_file (char *filename);
 // Programmers using the strcat function can easily be recognized as lazy and reckless.
 // (quoted from:  The GNU C Library (glibc) manual - 5.5 Concatenating Strings)
-char *concat (const char *str, ...);
+char *util_concat (const char *str, ...);
 
 typedef struct pile {int value; struct pile *prev;} pile; // structure d'un élément
 
@@ -67,9 +67,9 @@ int  util_sorted_list_length (slist *sl);           //  renvoie le nombre d'él
 //------------------------------------------------------------------------------
 
 void util_trigger_test();       //  def: util/tests.c    calls: ...
-void util_pile_test();          //  called in fsm/measure.c
+void util_test_pile();          //  called in fsm/measure.c
-void util_double_list_test();   //          "       "
+void util_test_double_list();   //          "       "
-void util_sorted_list_test();   //          "       "
+void util_test_sorted_list();   //          "       "
 
 //------------------------------------------------------------------------------
 

include/widget.h

@@ -162,7 +162,7 @@ int  widget_get_object_transparency (int i);             //  top
 //    call: signal.c
 //    def: widget / state / middle
 
-void widget_state_XYZ_reset_all();
+void widget_reset_XYZ_in_state_pane();
 void widget_reset_XYZ_scrollbars_rule();
 void widget_reset_XYZ_scrollbars_state();
 void widget_reset_XYZ_scrollbars_synth();

instanced_cubes.c

@@ -1,3 +1,5 @@
+//  gcc `pkg-config --cflags --libs gtk4 epoxy glib-2.0` -lm -o instanced_cubes instanced_cubes.c
+
 #include <epoxy/gl.h>
 #include <cglm/cglm.h>
 #include <stdlib.h>

read_me.doc

@@ -32,7 +32,7 @@
  *  docstrings
  *  ----------
  *
- *  1)  localisées dans les headers
+ *  1)  localisées dans les headers; une avant chaque fonction;
  *
  *  2)  structure:
  *
@@ -63,6 +63,8 @@
  *           --track-origins=yes    ERROR SUMMARY: 896 errors from 4 contexts
  *           --show-leak-kinds=all
  *
+ * sanitize  <<
+ *
  *
  *  3)  TODO  des scripts devraient pouvoir recueillir ces informations
  *  pour produire automatiquement, à la demande, des listes comme celle qui suit.
@@ -77,61 +79,64 @@
 
 
 /*  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *
-*
+ *
-*   C O N V E N T I O N S   E T   R È G L E S   D E   N O M M A G E  -  2 0 2 4
+ *   C O N V E N T I O N S   E T   R È G L E S   D E   N O M M A G E  -  2 0 2 4
-*
+ *
-*        Le nom d'une fonction doit permettre d'identifier facilement:
+ *        Le nom d'une fonction doit permettre d'identifier facilement:
-*              - le lieu (le fichier) où elle est définie,
+ *              - le lieu (le fichier) où elle est définie,
-*              - le type d'action qu'elle exécute et
+ *              - le type d'action qu'elle exécute et
-*              - l'objet ou les objets modifié.s par cette action.
+ *              - les objets modifiés par son action.
-*
+ *
-*                              -    -    -
+ *                              -    -    -
-*
+ *
-*      Ces trois informations sont encodées au moyen de trois "préfixes"
+ *       Ces trois informations sont encodées au moyen de trois "préfixes"
-*          associés et concaténés dans cet ordre pour former le nom.
+ *          associés et concaténés dans cet ordre pour former le nom.
-*                                   ?
+ *
-*           L'ordre des deux derniers préfixes peut-il être inversé
+ *                              -    -    -
-*                   pour que le nom soit "human-readable".
+ *
-*              Faut-il autoriser l'usage des alias ? (ex: 'concat')
+ *   En octobre 2024, la première version de cet index classe en trois listes
-*                                   ?
+ *                    l'ensemble des préfixes utilisés.
-*
+ *
-*   En octobre 2024, la première version de cet index classe en trois listes
+ *                 Ces listes sont en cours d'élaboration.
-*                    l'ensemble des préfixes utilisés.
+ *         Elles ne sont ni limitatives ni exhaustives ni ordonnées.
-*
+ *                                 TODO
-*                 Ces listes sont en cours d'élaboration.
+ *
-*          Elles ne sont ni limitatives ni exhaustives ni ordonnées.
+ *                              -    -    -
-*                                 TODO
+ *
-*
+ *   Le premier préfixe est l'adresse du fichier dans la hiérarchie "src":
-*                              -    -    -
+ *   ex:  graphics_draw_
-*
+ *        fsm_measures_manager_
-*   Le premier préfixe est l'adresse du fichier dans la hiérarchie "src":
+ *        util_draw_gl_
-*   ex:  graphics_draw_
+ *        widget_one_rule_algebra_assign_
-*        fsm_measures_manager_
+ *
-*        util_draw_gl_
+ *   Le deuxième préfixe est choisi dans une liste de fonctions types:
-*        widget_one_rule_algebra_assign_
+ *        get, set, reset, read, write, print, edit, concat, design,
-*
+ *        init, create, add, remove, erase, restore, trigger, draw, push
-*   Le deuxième préfixe est choisi dans une liste de fonctions types:
+ *        setup, shutdown, update, list, sort, seek, select, fix, debug,
-*        get, set, reset, read, write, print, edit, concat, design,
+ *        render, realize, unrealize, activate, exec, stop, signal,
-*        init, create, add, remove, trigger, draw, erase, restore, push
+ *
-*        setup, shutdown, update, list, sort, seek, select, fix, debug,
+ *   Le troisième préfixe est choisi dans une liste d'objets.
-*        render, realize, unrealize, activate, exec, stop, signal,
+ *   Ces objets sont ceux sur lesquels agissent les fonctions:
-*
+ *        number, string, view, image, window, list, tree, stack,
-*   Le troisième préfixe est choisi dans une liste d'objets
+ *        file, buffer, callback, signal,
-*                                   sur lesquels agissent les fonctions:
+ *        widget, button, slider, color, glarea, shader,
-*        number, string, view, window, list, tree, stack,
+ *        point, line, plan, space_unit, site, arrow, slot, vertex, ridge,
-*        file, buffer, callback, signal,
+ *        state, rules, data, results, stock,
-*        state, rules, data, results, image, stock,
+ *
-*        widget, button, slider, color, glarea, shader,
+ *
-*        point, line, plan, space_unit, site, arrow, slot, vertex, ridge,
+ *
-*
+ *  Le 2024-10-05), seules trois fonctions ne sont pas nommées selon ces règles:
-*  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  */
+ *      >  create_axis_slider, free_stack_slot, free_stack_slot_size <
+ *
+ *  et les noms de cinq autres peuvent être améliorés.
+ *     graphics_shutdown_graphics_stack  >  graphics_shutdown_stack
+ *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  *  */
 
 
 
-concat                                          util/strings_op
+create_axis_slider                              util/draw/gl   223     <<   to rename
-create_axis_slider                              util/draw/gl   223
+free_stack_slot                                 graphics/init   36     <<   to rename
-free_stack_slot                                 graphics/init   36
+free_stack_slot_size                            graphics/init   37     <<   to rename
-free_stack_slot_size                            graphics/init   37
 get_user_tree_model                             util/tree       66  static
 get_user_tree_model_child                       util/tree       49  static
 graphics_create_shader                          187   ?
@@ -157,7 +162,7 @@ graphics_render_stack                           87     ?
 graphics_set_arrow                              401    ?
 graphics_setup_glarea                           89     ?
 graphics_shutdown                               graphics/init  169
-graphics_shutdown_graphics_stack                128
+graphics_shutdown_graphics_stack                128                    <<   to rename
 graphics_stack                                  graphics/init   34
 graphics_stack_size                             graphics/init   35
 graphics_stack_t                                graphics.h
@@ -214,8 +219,8 @@ fsm_struct_list_tool                            fsm.h
 on_auto_notification                            signal   37       static
 on_axis_value_change                            signal   181
 on_bind_user_tree_factory                       signal   81
-on_clicked_topbar_right_home                    signal   373  <  to rename
+on_clicked_topbar_right_home                    signal   373            <<  to rename
-on_clicked_topbar_right_search                  signal   364  <  to rename
+on_clicked_topbar_right_search                  signal   364            <<  to rename
 on_discard_current_model_before_editing         signal   228
 on_entry_name_delete_after                      signal   547
 on_entry_name_insert_after                      signal   542
@@ -231,8 +236,8 @@ on_select_rules_first                           signal   446
 on_setup_user_tree_factory                      signal   73
 on_situations_box_do_reset                      signal   412
 on_start_new_measure                            signal   439
-on_toggle_exec_edit                             signal   254  <  to rename
+on_toggle_exec_edit                             signal   254            <<  to rename
-on_toggle_state_rules_data                      signal   286  <  to rename
+on_toggle_state_rules_data                      signal   286            <<  to rename
 on_topbar_right_measure_clicked                 signal   426
 on_updating_objects_transparencies              signal   389
 on_user_tree_expander_toggled                   signal   64    static
@@ -255,6 +260,7 @@ stack_index_size                                stack_index      39
 stack_index_t                                   util/draw/gl.c   32
 switch_state_rules_data                         signal           305    static
 TreeNode_t                                      widget.h  (rename ?)
+util_concat                                     util/strings_op
 util_gl_clean_stack_index                       util/draw/gl.c   150
 util_gl_get_stack                               util/draw/gl.c   66
 util_gl_init_stack                              util/draw/gl.c   102
@@ -266,13 +272,13 @@ util_gl_setup_glarea                            util/draw/gl.c   364
 util_gl_shutdown_all_stacks                     util/draw/gl.c   207
 util_gl_shutdown_stack                          util/draw/gl.c   133
 util_gl_update_axis                             util/draw/gl.c   187
-util_double_list_test                           util/tests
 util_list_2x2_     ^c^v  (8 fonctions)          util/list_2x2
 util_pile_         ^c^v  (5 fonctions)          util/pile
-util_pile_test                                  util/tests
 util_read_file                                  util/io
 util_sorted_list_  ^c^v  (5 fonctions)          util/sorted_list
-util_sorted_list_test                           util/tests
+util_test_double_list                           util/tests
+util_test_pile                                  util/tests
+util_test_sorted_list                           util/tests
 util_trigger_test                               util/tests
 widget_add_tree_child_node                      util/tree   32
 widget_create_user_rules_tree_node              util/tree   41
@@ -329,13 +335,13 @@ widget_get_text_from_address                    widget/topbar/modal
 widget_get_text_window                          widget/dispatch
 widget_get_time_dependent                       widget/synth/time
 widget_get_user_rules_tree                      util/tree   88
+widget_reset_XYZ_in_state_pane                  widget/state/middle   TODO (dispatch)
 widget_reset_XYZ_scrollbars_rule                166   TODO
 widget_reset_XYZ_scrollbars_state               167   TODO
 widget_reset_XYZ_scrollbars_synth               168   TODO
 widget_set_item_text                            widget/one_rule/algebra/dispatch
 widget_set_objects_value                        widget/state/top
 widget_set_situations_value                     widget/state/top
-widget_state_XYZ_reset_all                      widget/state/middle   TODO (dispatch)
 window_design_topbar_left                       widget/dispatch
 window_design_topbar_right                      widget/dispatch
 

scripts/doctext

@@ -0,0 +1,5 @@
+#!/usr/bin/env python3
+uses scripts/doctext
+
+https://python.developpez.com/tutoriels/python-basic-par-exemple/?page=gestion-des-fichiers
+https://note.nkmk.me/en/python-docstring/

src/fsm/dispatch.c

@@ -163,7 +163,7 @@ void fsm_set_exec_edit (int choice)
     if (choice_EXEC_EDIT != choice)
     {
         fsm_journal_event (INFO, FSM, "fsm/dispatch", "set_exec_edit()",
-            concat (tab_0 [choice_EXEC_EDIT], " > ", tab_0 [choice], NULL));
+            util_concat (tab_0 [choice_EXEC_EDIT], " > ", tab_0 [choice], NULL));
         choice_EXEC_EDIT = choice;
     }
 }
@@ -173,7 +173,7 @@ void fsm_set_state_rules_data (int choice)
     if (choice_STATE_RULES_DATA != choice)
     {
         fsm_journal_event (INFO, FSM, "fsm/dispatch", "set_state_rules_data()",
-            concat (tab_1 [choice_STATE_RULES_DATA], " > ", tab_1 [choice], NULL));
+            util_concat (tab_1 [choice_STATE_RULES_DATA], " > ", tab_1 [choice], NULL));
         choice_STATE_RULES_DATA = choice;
     }
 }

src/signal.c

@@ -53,7 +53,7 @@ static void on_auto_notification (char *message)
     gtk_label_set_label(window->toast_text, message);
     gtk_revealer_set_reveal_child(window->toast_revealer, true);
   */
-    g_printerr("%s\n", message);  //  TODO  use the journal to display the message  (concat))
+    g_printerr("%s\n", message);  //  TODO  use the journal to display the message  (util_concat))
 }
 
 
@@ -288,7 +288,7 @@ void on_toggle_state_rules_data (GtkWidget *toggled_button, gpointer widget_all_
     const char *toggled_button_name
                 = gtk_check_button_get_label  (GTK_CHECK_BUTTON (toggled_button));
     fsm_journal_event (DEBUG, BUTTON, "signal", "toggle_state_rules_data()",
-        concat ("[", toggled_button_name, "]", NULL));
+        util_concat ("[", toggled_button_name, "]", NULL));
     int is_active = gtk_check_button_get_active (GTK_CHECK_BUTTON (toggled_button));
 
     if ( ! strcmp (toggled_button_name, widget_get_btt_label_synth())) fsm_set_state_rules_data (SYNTH);
@@ -404,7 +404,7 @@ void on_updating_objects_transparencies (GtkWidget *btt_source, GtkScrollbar *sc
 void on_resetting_XYZ_in_state_page ()
 {
     fsm_journal_event (DEBUG, BUTTON, "signal", "resetting XYZ in state page()", "");
-    widget_state_XYZ_reset_all();
+    widget_reset_XYZ_in_state_pane();
 }
 
 // --------------------------   S I T U A T I O N S   ----------------------- //
@@ -428,7 +428,7 @@ void on_topbar_right_measure_clicked (GtkWidget *btt, gpointer button_icon_name)
 //  ici, il faudrait surtout dire que: widget_get_measure_page
 //               devient un enfant de: widget_get_main_window.
     fsm_journal_event (DEBUG, BUTTON, "signal", "topbar right measure()",
-                       concat ("clicked;   icon = ", button_icon_name, NULL));
+                       util_concat ("clicked;   icon = ", button_icon_name, NULL));
 //  fsm_measures_sorted_list_do something ();    TODO
 //  ! WARNING !  ce qui suit n'est qu'une maquette:   (... delenda est !)
 //  la 'logique' qui va des mesures aux résultats doit changer de forme    TODO

src/util/strings_op.c

@@ -60,7 +60,7 @@
 #include <string.h>
 
 char *  // https://sourceware.org/glibc/manual/latest/html_mono/libc.html#Variadic-Prototypes
-concat (const char *str, ...) // ellipsis (‘…’) A.2.2.2 Receiving the Argument Values
+util_concat (const char *str, ...) // ellipsis (‘…’) A.2.2.2 Receiving the Argument Values
 {
   size_t allocated = 100;
   char *result = malloc (allocated);

src/util/tests.c

@@ -34,16 +34,16 @@
 
 void util_trigger_test ()
 {
-    if (0) fsm_list_tools_test();
+//  if (0) fsm_test_list_tools();
-    if (0) util_pile_test();
+    if (0) util_test_pile();
-    if (0) util_double_list_test();
+    if (0) util_test_double_list();
-    if (0) util_sorted_list_test();
+    if (0) util_test_sorted_list();
     char aaa [] = "Hello World", bbb [] = ", what's new ?";
-    if (0) printf("concat ([%s], [%s], NULL) --> '%s'\n",
+    if (0) printf("util_concat ([%s], [%s], NULL) --> '%s'\n",
-                  aaa, bbb, concat (aaa, bbb, NULL));
+                  aaa, bbb, util_concat (aaa, bbb, NULL));
 }
 
-void util_pile_test()
+void util_test_pile()
 {
     pile *exemple = NULL;   // doit être initialisée à NULL
     puts ("------");
@@ -65,7 +65,7 @@ void util_pile_test()
     util_pile_view (exemple);
 }
 
-void util_double_list_test()
+void util_test_double_list()
 {
     dblist exemple;
 
@@ -95,11 +95,11 @@ void util_double_list_test()
     util_list_2x2_view (exemple);
 }
 
-void util_sorted_list_test()
+void util_test_sorted_list()
 {
     slist *Mysl = NULL;
 
-    puts("\nfsm/util util_sorted_list_test() > création d'une liste de 10 elements :");
+    puts("\nfsm/util util_test_sorted_list() > création d'une liste de 10 elements :");
     util_sorted_list_insert (&Mysl,9);
     util_sorted_list_insert (&Mysl,-8);
     util_sorted_list_insert (&Mysl,3);

src/widget/measure/dispatch.c

@@ -301,12 +301,12 @@ void *widget_get_page_measure()
     btt_edit_a_new_measure = gtk_toggle_button_new_with_label (btt_lab);
     g_signal_connect (btt_edit_a_new_measure, "toggled",
                       G_CALLBACK (on_start_new_measure),
-                      concat ("label = ", btt_lab, "  (+/- caliper icon)", NULL));
+                      util_concat ("label = ", btt_lab, "  (+/- caliper icon)", NULL));
     gtk_box_append (edit_a_new_measure_box, GTK_WIDGET (caliper));
     gtk_box_append (edit_a_new_measure_box, GTK_WIDGET (btt_edit_a_new_measure));
     gtk_box_append (measure_page, GTK_WIDGET (edit_a_new_measure_box));
     fsm_journal_event (DEBUG, BUTTON, "widget/measure/dispatch", "widget_get_measure_page()",
-                       concat ("creates: ", btt_lab, "  in: measure_page", NULL));
+                       util_concat ("creates: ", btt_lab, "  in: measure_page", NULL));
 
     return measure_page;
  }

src/widget/one_rule/algebra/conditions.c

@@ -54,7 +54,7 @@ void *widget_get_selected_rule_conditions_list_btt()
         char str4[5]; sprintf(str4, "%d, ",    rand() % 10);
         char str5[8]; sprintf(str5, "%d) == ", rand() % 10);
         char str6[4]; sprintf(str6, "%d)",     rand() % 10);
-        one_condition = concat (str1, str2, str3, str4, str5, str6, NULL);
+        one_condition = util_concat (str1, str2, str3, str4, str5, str6, NULL);
         widget_set_item_text (list_box, one_condition, TRUE);
         fsm_journal_event (SPEW,
                            RULE_CONDITION,
@@ -77,8 +77,8 @@ void *widget_get_selected_rule_conditions_list_btt()
     fsm_journal_event (DEBUG,
                        RULE_CONDITION,
                        "one_rule/algebra/conditions",
-                       concat ("list; last of ", str_nb, " conditions: ", NULL),
+                       util_concat ("list; last of ", str_nb, " conditions: ", NULL),
-                       concat ("[", one_condition, "]", "  <-- a cond. sample", NULL));
+                       util_concat ("[", one_condition, "]", "  <-- a cond. sample", NULL));
 
     return conditions;
 }

src/widget/state/middle.c

@@ -33,9 +33,9 @@ static GtkAdjustment *X_adjust;
 static GtkAdjustment *Y_adjust;
 static GtkAdjustment *Z_adjust;
 
-void widget_state_XYZ_reset_all()
+void widget_reset_XYZ_in_state_pane()
 {
-    printf("WARNING state/middle/widget_state_XYZ_reset_all()\
+    printf("WARNING state/middle/widget_reset_XYZ_in_state_pane()\
   agit aussi sur synth/...\
   (tant que les GtkAdjustment *X_adjust, *Y_adjust, *Z_adjust ne sont pas distincts)\n");
     gtk_adjustment_set_value (X_adjust, 0);