form_engine.c

Go to the documentation of this file.

/** @file form_engine.c
    @brief The working part of C-Menu Form
    @author Bill Waller
    Copyright (c) 2025
    MIT License
    billxwaller@gmail.com
    @date 2026-02-09
 */
// #define DEBUG_IMMEDOK true
/** @defgroup form_engine Form Engine
    @brief Parses Form Descriptions, Handles User Input, and Integrates with
   External Commands for Calculations and Data Processing.
 */
 
#include "common.h"
#include <errno.h>
#include <fcntl.h>
#include <stdlib.h>
#include <string.h>
#include <sys/stat.h>
#include <termios.h>
#include <unistd.h>
#include <wait.h>
 
#define D_COMMENT '#'
#define D_CMD '!'
#define D_FIELD 'F'
#define D_TEXT 'T'
#define D_HELP '?'
#define D_HEADER 'H'
#define D_CALC 'C'
#define D_QUERY 'Q'
#define D_GETTER 'G'
 
unsigned int display_form(Init *);
void form_display_fields(Form *);
int field_navigator(Form *);
int form_parse_desc(Form *);
int form_read_data(Form *);
int form_write(Form *);
void form_usage();
int form_desc_error(Form *form, int, char *, char *);
int form_exec_cmd(Form *);
int form_exec_receiver(Init *);
int form_process(Init *);
int form_post(Init *);
int init_form(Init *, int, char **, uint, uint);
int form_engine(Init *);
uint form_yx_to_fidx(Form *, uint, uint);
void mk_filler(char *, uint);
 
/** @brief Initialize form data structure and parse description file
    @ingroup form_engine
    @param init A pointer to the Init structure containing form data and state.
    @param argc The number of command line arguments passed to the form.
    @param argv The array of command line arguments passed to the form.
    @param begy The y-coordinate for the top-left corner of the form window.
    @param begx The x-coordinate for the top-left corner of the form window.
    @return 0 on success, or a non-zero value if an error occurs during
*/
int init_form(Init *init, int argc, char **argv, uint begy, uint begx) {
    int rc;
    char tmp_str[MAXLEN];
    if (init->form != nullptr)
        destroy_form(init);
    init->form = new_form(init, argc, argv, begy, begx);
    Form *form = init->form;
    if (!form->f_mapp_spec) {
        if (form->mapp_spec[0] == '\0') {
            rc = Perror("Error: No form specification file given");
        } else {
            strnz__cpy(tmp_str, "form->mapp_spec: ", MAXLEN - 1);
            strnz__cat(tmp_str, form->mapp_spec, MAXLEN - 1);
            strnz__cat(tmp_str, " not found", MAXLEN - 1);
            rc = Perror(tmp_str);
        }
        destroy_form(init);
        return rc;
    }
    if (begy != 0)
        form->begy = begy;
    if (begx != 0)
        form->begx = begx;
    if ((form->f_in_spec && (form->in_spec[0] == '\0')) ||
        (strcmp(form->in_spec, "-") == 0) ||
        strcmp(form->in_spec, "/dev/stdin") == 0) {
        strnz__cpy(form->in_spec, "/dev/stdin", MAXLEN - 1);
        form->f_in_pipe = true;
    }
    if (form->title[0] == '\0')
        strnz__cpy(form->title, form->in_spec, MAXLEN - 1);
    rc = form_engine(init);
    UiSurface *sfc = ui_surface[sfc_ptr];
    destroy_chyron(form->chyron);
    if (sfc)
        cm_surface_destroy(sfc);
    destroy_form(init);
    return rc;
}
/** @brief Form main processing loop
    @ingroup form_engine
    @param init A pointer to the Init structure containing form data and state.
    @return 0 on successful completion, or a non-zero value if the user cancels
    the form or if an error occurs during processing.
        1. Parse the form description file to populate the form data structure.
        2. Read any initial data for the form fields from a specified input
        source.
        3. Display the form on the screen with the initial field values.
        4. Enter a loop to handle user input for field entry, calculation, help,
        and cancellation:
          a. If the user selects the accept action, perform any necessary
          calculations or post-processing, and then either return to field entry
          or exit the loop if the form is accepted.
          b. If the user selects the help action, display the help screen and
          return to the form after the user exits the help screen.
          c. If the user selects the cancel action, exit the loop and return a
          cancel status. */
int form_engine(Init *init) {
    char tmp_str[MAXLEN];
    int form_action;
    char *eargv[MAXARGS];
    int eargc;
 
    Form *form = init->form;
    if (form == nullptr) {
        Perror("FORM: form data structure is nullptr");
    }
    if (form_parse_desc(form)) {
        return 0;
    }
    form_read_data(form);
    display_form(init);
    form->chyron = new_chyron();
    set_chyron_key(form->chyron, 1, "F1 Help", KEY_F01);
    set_chyron_key_cb(form->chyron, 2, "F2 Process", KEY_F02, cell_nt_hl_rev);
    set_chyron_key_cb(form->chyron, 3, "F3 Calculate", KEY_F03, cell_nt_hl_rev);
    set_chyron_key_cb(form->chyron, 4, "F4 Query", KEY_F04, cell_nt_hl_rev);
    set_chyron_key_cb(form->chyron, 5, "F5 Edit", KEY_F05, cell_nt_hl_rev);
    set_chyron_key(form->chyron, 9, "F9 Cancel", KEY_F09);
    set_chyron_key(form->chyron, 10, "F10 Accept", KEY_F10);
    set_chyron_key(form->chyron, 18, "INS", KEY_IC);
    form->chyron->key[2]->active = false;  // F2 Process
    form->chyron->key[3]->active = false;  // F3 Calculate
    form->chyron->key[4]->active = false;  // F4 Query
    form->chyron->key[5]->active = false;  // F5 Edit
    form->chyron->key[18]->active = false; // Insert
    compile_chyron(form->chyron);
    UiSurface *sfc = ui_surface[sfc_ptr];
    display_chyron(sfc, 1, form->chyron, form->lines - 1, form->chyron->l);
    // 1 F1 Help
    // 2 F2 Process
    // 3 F3 Calculate
    // 4 F4 Query
    // 5 F5 Edit
    // 9 F9 Cancel
    // 10 F10 Accept
    form->fidx = 0;
    form_action = 0;
    while (1) {
        if (form_action == 0 || form_action == FA_CONTINUE)
            form_action = field_navigator(form);
        form->chyron->key[18]->active = false; // Insert
        switch (form_action) {
        case FA_ACCEPT:
            if (form->f_process || form->f_calculate || form->f_query)
                form_action = form_process(init);
            else
                form_action = form_post(init);
            if (form_action == FA_HELP || form_action == FA_CANCEL ||
                form_action == FA_CONTINUE || form_action == FA_END)
                continue;
            if (form_action == FA_ACCEPT) {
                form_action = FA_END;
                continue;
            }
            break;
        case FA_END:
            if (form->f_out_spec || form->out_spec[0] != '\0')
                form_write(form);
            if (form->f_receiver_cmd || form->receiver_cmd[0] != '\0')
                form_exec_receiver(init);
            break;
        case FA_HELP:
            if (form->f_help_spec && form->help_spec[0] != '\0')
                strnz__cpy(tmp_str, form->help_spec, MAXLEN - 1);
            else {
                strnz__cpy(tmp_str, init->mapp_help, MAXLEN - 1);
                strnz__cat(tmp_str, "/", MAXLEN - 1);
                strnz__cat(tmp_str, FORM_HELP_FILE, MAXLEN - 1);
            }
            eargc = 0;
            eargv[eargc++] = strdup("view");
            eargv[eargc++] = strdup("-Nf");
            eargv[eargc++] = strdup(tmp_str);
            eargv[eargc] = nullptr;
            init->lines = 30;
            init->cols = 66;
            init->begy = form->begy + 1;
            init->begx = form->begx + 1;
            strnz__cpy(init->title, "Form Help", MAXLEN - 1);
            popup_view(init, eargc, eargv, init->lines, init->cols, init->begy,
                       init->begx);
            destroy_argv(eargc, eargv);
            form_action = FA_CONTINUE;
            break;
        case FA_CANCEL:
            return FA_CANCEL;
        default:
            form_action = FA_CONTINUE;
            break;
        }
        if (form_action == FA_END)
            break;
    }
    return 0;
}
/** @brief Handle post-processing after field entry, allowing user to edit data,
    execute a provider command, or write data to an output file.
    @ingroup form_engine
    @param init A pointer to the Init structure containing form data and state.
    @return An integer status code indicating the next action for the form
    processing loop (e.g., FA_CONTINUE, FA_CANCEL, FA_ACCEPT, FA_HELP). */
int form_post(Init *init) {
    bool loop = true;
    int c, rc;
    click_y = click_x = -1;
    Form *form = init->form;
    UiSurface *sfc = ui_surface[sfc_ptr];
    UiEvent event;
    uint maxy, maxx;
    ui_cursor_move(sfc, WIN, form->lines - 1, 0);
    ui_wclrtoeol(sfc, WIN);
    // 1 F1 Help
    // 2 F2 Process
    // 3 F3 Calculate
    // 4 F4 Query
    // 5 F5 Edit
    // 9 F9 Cancel
    // 10 F10 Continue
    // 11 F10 Commit
    // 18 INS Insert
    form->chyron->key[5]->active = true;   // F5 Edit
    form->chyron->key[10]->active = false; // F10 Continue
    form->chyron->key[18]->active = false; // INS Insert
    compile_chyron(form->chyron);
    rc = -1;
    while (loop) {
        if (rc == -1) {
            display_chyron(sfc, WIN, form->chyron, form->lines - 1, form->chyron->l);
            tcflush(2, TCIFLUSH);
            ui_render();
            c = ui_get_event_multi(sfc, WIN, &event, -1);
            ui_getmaxyx(sfc, WIN, &maxy, &maxx);
            if (event.in_win == 1 && event.y == maxy - 1)
                c = get_chyron_key(form->chyron, event.x);
        }
        switch (c) {
        case KEY_F01:
            return FA_HELP;
        case KEY_F05: // F5 Edit
            if (is_set_chyron_key(form->chyron, 5)) {
                loop = false;
                rc = FA_CONTINUE;
                break;
            }
            continue;
        case KEY_F09:
            loop = false;
            rc = FA_CANCEL;
            break;
        case KEY_F10:
            loop = false;
            rc = FA_ACCEPT;
            break;
        case KEY_MOUSE:
            continue;
        default:
            break;
        }
    }
    form->chyron->key[5]->active = false; // F5 Edit
    return rc;
}
 
/** @brief Handle integration with a getter program which will provide field
   data.
    @ingroup form_engine
    @param init A pointer to the Init structure containing form data and state.
    @return An integer status code indicating the next action for the form
    processing loop (e.g., FA_CONTINUE, FA_CANCEL, FA_ACCEPT, FA_HELP).
    @details This function provides integration with getter programs.
        The requirements are:
        1. The form description file must have a line containing only 'C'
   (calculate), 'Q' (query), org 'G' (getter) to indicate that the form supports
   a getter.
        2. The form description file must specify the provider command using a
        line starting with '!' followed by the command and its arguments.
        3. The getter program must be able to accept field data from a file,
        from standard input, or as command line parameters.
        4. The getter program must output field values in a format that can be
   read by the form (e.g., one value per line), either to a file or to standard
   output.
 
        The sequence of operations is as follows:
 
        1. The 'C', 'Q', or 'G' option causes Form to pause and display an
   KEY_F05 Calculate, Query, or Getter. option on the chyron.
        2. The user can then cancel the operation by pressing KEY_F09 or
        activate the getter option by pressing KEY_F05.
        3. Form outputs its data to file, standard output, or as command line
        parameters.
        4. Form executes the getter program.
        5. The getter program processes the data and outputs the results.
        6. Form reads the results and populates the appropriate form fields.
        7. Form presents the user with an option to edit the data, and the
        sequence restarts at 1.
 
        This function forks and executes the getter executable as a child
        process, creates a pipe to read the output from the provider command,
        reads the output, and updates the Form fields.
            */
int form_process(Init *init) {
    uint i, c;
    int rc;
    char earg_str[MAXLEN + 1];
    char *eargv[MAXARGS];
    int eargc;
    char file_spec[MAXLEN];
    bool loop = true;
    pid_t pid;
    int pipe_fd[2];
    UiSurface *sfc = ui_surface[sfc_ptr];
    UiEvent event;
    Form *form = init->form;
    ui_cursor_move(sfc, WIN, form->lines - 1, 0);
    uint maxy, maxx;
    //
    // 1 F1 Help
    // 2 F2 Process
    // 3 F3 Calculate
    // 4 F4 Query
    // 5 F5 Edit
    // 9 F9 Cancel
    // 10 F10 Continue
    // 11 F10 Commit
    form->chyron->key[2]->active = form->f_process > 0 ? true : false;
    form->chyron->key[3]->active = form->f_calculate > 0 ? true : false;
    form->chyron->key[4]->active = form->f_query > 0 ? true : false; // PgUp
    form->chyron->key[10]->active = false;                           // F10 Continue
    form->chyron->key[18]->active = false;                           // INS Insert
 
    while (loop) {
        compile_chyron(form->chyron);
        display_chyron(sfc, 1, form->chyron, form->lines - 1, form->chyron->l);
        click_y = click_x = -1;
        tcflush(2, TCIFLUSH);
        ui_render();
        c = ui_get_event_multi(sfc, WIN, &event, -1);
        ui_getmaxyx(sfc, WIN, &maxy, &maxx);
        if (event.in_win == 1 && event.y == maxy - 1)
            c = get_chyron_key(form->chyron, event.x);
 
        switch (c) {
        case KEY_F01:
            return FA_HELP;
        case KEY_F02: // F2 Process
        case KEY_F03: // F3 Calculate
        case KEY_F04: // F4 Query
            if (form->f_out_spec)
                form_write(form);
            if (form->f_provider_cmd) {
                strnz__cpy(earg_str, form->provider_cmd, MAXLEN - 1);
                for (i = 0; i < form->fcnt; i++) {
                    strnz__cat(earg_str, " ", MAXLEN - 1);
                    strnz__cat(earg_str, form->field[i]->accept_s, MAXLEN - 1);
                }
                eargc = str_to_args(eargv, earg_str, MAXARGS);
                strnz__cpy(file_spec, eargv[0], MAXLEN - 1);
                base_name(eargv[0], file_spec);
                if (pipe(pipe_fd) == -1) {
                    destroy_argv(eargc, eargv);
                    Perror("pipe(pipe_fd) failed in init_form");
                    return (1);
                }
                if ((pid = fork()) == -1) {
                    destroy_argv(eargc, eargv);
                    Perror("fork() failed in init_form");
                    return (1);
                }
                if (pid == 0) { // Child
                    /** Prevent child process from writing to terminal */
                    int dev_null = open("/dev/null", O_WRONLY);
                    if (dev_null == -1) {
                        Perror("open(/dev/null) failed in init_pick child "
                               "process");
                        exit(EXIT_FAILURE);
                    }
                    dup2(dev_null, STDERR_FILENO);
                    close(dev_null);
                    close(pipe_fd[P_READ]);
                    dup2(pipe_fd[P_WRITE], STDOUT_FILENO);
                    stdio_fdnames(stdio_names_str, "form_engine.c:367");
                    close(pipe_fd[P_WRITE]);
                    execvp(eargv[0], eargv);
                    ssnprintf(em0, MAXLEN, "%s, line: %d", __FILE__,
                              __LINE__ - 2);
                    strnz__cpy(em1, "execvp(", MAXLEN - 1);
                    strnz__cat(em1, eargv[0], MAXLEN - 1);
                    strnz__cat(em1, ", ", MAXLEN - 1);
                    strnz__cat(em1, earg_str, MAXLEN - 1);
                    strnz__cat(em1, ")", MAXLEN - 1);
                    strerror_r(errno, em2, MAXLEN);
                    display_error(em0, em1, em2, nullptr);
                    exit(EXIT_FAILURE);
                } // Back to parent
                close(pipe_fd[P_WRITE]);
                form->in_fp = fdopen(pipe_fd[P_READ], "rb");
                form->f_in_pipe = true;
                form_read_data(form);
                close(pipe_fd[P_READ]);
                waitpid(pid, nullptr, 0);
                stdio_fdnames(stdio_names_str, "form_engine.c:387");
                destroy_argv(eargc, eargv);
                form_display_fields(form);
                form->chyron->key[2]->active = false; // F2 Process
                form->chyron->key[3]->active = false; // F3 Calculate
                form->chyron->key[4]->active = false; // F4 Query
                form->chyron->key[5]->active = true;  // F5 Edit
                form->chyron->key[10]->active = true; // F10 Accept
                compile_chyron(form->chyron);
                continue;
            }
            break;
        case KEY_F05:
            if (is_set_chyron_key(form->chyron, 5)) {
                loop = false;
                rc = FA_CONTINUE;
                break;
            }
            continue;
        case KEY_F09:
            loop = false;
            rc = FA_CANCEL;
            break;
        case KEY_F10:
            loop = false;
            rc = FA_ACCEPT;
            break;
        case KEY_MOUSE:
            break;
        default:
            break;
        }
    }
    form->chyron->key[2]->active = false; // F2 Process
    form->chyron->key[3]->active = false; // F3 Calculate
    form->chyron->key[4]->active = false; // F4 Query
    form->chyron->key[5]->active = false; // F5 Edit
    return rc;
}
/** @brief Handle user input for field entry, allowing navigation between fields
    and looping until an exit action is selected.
    @ingroup form_engine
    @param form A pointer to the Form structure containing form data and state.
    @return An integer status code indicating the next action for the form
    processing loop (e.g., FA_ACCEPT, FA_HELP, FA_CALC, FA_CANCEL).
    @details This function manages user input for field entry, including
   navigation between fields and handling of special keys for accepting,
   canceling, requesting help, or performing calculations. The function loops
   until the user selects an exit action (e.g., accept or cancel). */
int field_navigator(Form *form) {
 
    if (form->fidx >= form->fcnt)
        form->fidx = 0;
    while (1) {
        int cmd_key = field_editor(form);
        switch (cmd_key) {
        case KEY_F01: // F1 Help
            return (FA_HELP);
        case KEY_F02: // F2 Process
        case KEY_F03: // F3 Calculate
        case KEY_F04: // F4 Query
            if (form->f_process)
                return (FA_CALC);
            break;
        case KEY_F09: // F9 Cancel
            return (FA_CANCEL);
        case KEY_F10: // F10 Accept
            return (FA_ACCEPT);
        case 'k':
        case KEY_UP:
            if (form->fidx != 0)
                form->fidx--;
            break;
        case '\r':
        case KEY_ENTER:
            if (form->fidx < form->fcnt - 1)
                form->fidx++;
            else if (form->fidx == form->fcnt - 1)
                return (FA_ACCEPT);
            break;
        case 'j':
        case KEY_DOWN:
            if (form->fidx < form->fcnt - 1)
                form->fidx++;
            else if (form->fidx == form->fcnt - 1)
                return (FA_ACCEPT);
            break;
        case KEY_MOUSE:
            break;
        default:
            break;
        }
    }
}
uint form_yx_to_fidx(Form *form, uint y, uint x) {
    for (uint i = 0; i < form->fcnt; i++) {
        if (y == form->field[i]->line && x >= form->field[i]->col &&
            x < form->field[i]->col + form->field[i]->len) {
            return i;
        }
    }
    return -1; // No field found at the given coordinates
}
 
/** @brief Display the form on the screen, including text elements and fields,
    and set up the form window based on the form configuration.
    @ingroup form_engine
    @param init A pointer to the Init structure containing form data and state.
    @return 0 on success, or a non-zero value if an error occurs while
    creating the form window or rendering the form elements. */
unsigned int display_form(Init *init) {
    uint n, flin, fcol;
    char tmp_str[MAXLEN];
 
    Form *form = init->form;
    form->lines = 0;
    for (n = 0; n < form->dcnt; n++)
        if (form->text[n]->line > form->lines)
            form->lines = form->text[n]->line;
    for (n = 0; n < form->fcnt; n++)
        if (form->field[n]->line > form->lines)
            form->lines = form->field[n]->line;
    form->lines += 3;
    if (form->lines > (LINES - form->begy))
        form->lines = LINES - form->begy;
    for (n = 0; n < form->fcnt; n++) {
        if (form->field[n]->line >= (form->lines - 2))
            form->fcnt = n;
    }
    form->cols += 2;
    if (form->cols > (COLS - form->begx - 3))
        form->cols = COLS - form->begx - 3;
    if (surface_box_win_new(form->lines, form->cols, form->begy, form->begx, form->title)) {
        strnz__cpy(tmp_str, "surface_box_win_new failed: ", MAXLEN - 1);
        strnz__cat(tmp_str, form->title, MAXLEN - 1);
        Perror(tmp_str);
        return (1);
    }
    UiSurface *sfc = ui_surface[sfc_ptr];
#ifdef DEBUG_IMMEDOK
    ui_immedok(sfc, WIN, true);
    ui_immedok(sfc, BOX, true);
#endif
    for (form->fidx = 0; form->fidx < form->fcnt; form->fidx++) {
        if (form->brackets[0] != '\0' && form->brackets[1] != '\0') {
            flin = form->field[form->fidx]->line + 1;
            fcol = form->field[form->fidx]->col;
            ui_mvwadd_wch(sfc, BOX, flin, fcol, &cell_brktl);
            fcol += form->field[form->fidx]->len + 1;
            ui_mvwadd_wch(sfc, BOX, flin, fcol, &cell_brktr);
        }
    }
    for (n = 0; n < form->dcnt; n++) {
        strnz(form->text[n]->str, form->cols - 3);
        ui_mvwaddstr(sfc, WIN, form->text[n]->line, form->text[n]->col,
                     form->text[n]->str);
    }
    ui_render();
    form_display_fields(form);
    return 0;
}
/** @brief Display form fields on the screen, populating field values and
    formatting them according to the form configuration.
    @ingroup form_engine
    @param form A pointer to the Form structure containing form data and
   state.
    @details This function iterates through the defined form fields, formats
   their display values based on the specified fill character and field
   length, and renders them on the form window. It also updates the chyron
   with available commands for user interaction. */
void form_display_fields(Form *form) {
    uint y, x;
    uint pos = 0;
    for (form->fidx = 0; form->fidx < form->fcnt; form->fidx++) {
        if (form->field[form->fidx]->col + form->field[form->fidx]->len + 2 >
            form->cols)
            form->field[form->fidx]->len =
                form->cols - (form->field[form->fidx]->col + 2);
        // Make filler_cc
        size_t fl = form->field[form->fidx]->len;
        char *d = form->field[form->fidx]->filler_s;
        size_t char_bytes = strlen(form->fill_char);
        for (size_t i = 0; i < fl; i++) {
            memcpy(d, form->fill_char, char_bytes);
            d += char_bytes;
        }
        d = nullptr;
 
        if (form->field[form->fidx]->accept_s[0] != '\0') {
            strnz(form->field[form->fidx]->accept_s, form->field[form->fidx]->len);
            // d = form->field[form->fidx]->accept_s;
        } else {
            memset(form->field[form->fidx]->accept_s, 0, MAXLEN);
            // d = form->field[form->fidx]->accept_s;
        }
        strnz(form->field[form->fidx]->display_s, form->field[form->fidx]->len);
 
        y = form->field[form->fidx]->line;
        x = form->field[form->fidx]->col;
 
        pos = 0;
        mbstr_to_cellstr(form->field[form->fidx]->filler_cc, form->field[form->fidx]->filler_s, &cell_fill_char, &pos, form->field[form->fidx]->len + 1);
 
        UiSurface *sfc = ui_surface[sfc_ptr];
        ui_mvwadd_wchstr(sfc, WIN, y, x, form->field[form->fidx]->filler_cc);
        ui_render();
 
        pos = 0;
        mbstr_to_cellstr(form->field[form->fidx]->display_cc, form->field[form->fidx]->display_s, &cell_nt, &pos, form->field[form->fidx]->len + 1);
 
        ui_mvwadd_wchnstr(sfc, WIN, y, x, form->field[form->fidx]->display_cc, form->field[form->fidx]->len);
        ui_render();
    }
    return;
}
/** @brief Parse the form description file to populate the Form data
   structure with field definitions, text elements, and other configuration
   specified in the description file.
    @ingroup form_engine
    @param form A pointer to the Form structure containing form data and
   state.
    @return 0 on success, or a non-zero value if an error occurs while
   parsing the description file (e.g., file not found, invalid format,
   missing directives). */
int form_parse_desc(Form *form) {
    FILE *form_desc_fp;
    char *token;
    char *s;
    uint cols = 0;
    uint i, l;
    int in_line_num = 0;
    char in_buf[BUFSIZ];
    char tmp_buf[BUFSIZ];
    char *tmp_buf_p;
    char tmp_str[BUFSIZ];
    char delim[5];
    char directive;
 
    form_desc_fp = fopen(form->mapp_spec, "r");
    if (form_desc_fp == nullptr) {
        ssnprintf(em0, MAXLEN - 1, "%s, line: %d", __FILE__, __LINE__ - 2);
        strnz__cpy(em1, "fopen ", MAXLEN - 1);
        strnz__cat(em1, form->mapp_spec, MAXLEN - 1);
        strerror_r(errno, em2, MAXLEN);
        display_error(em0, em1, em2, nullptr);
        return (1);
    }
    for (i = 0; i < FIELD_MAXCNT; i++) {
        form->field[i] = calloc(1, sizeof(Field));
        if (!form->field[i]) {
            sprintf(tmp_str, "FORM: calloc failed for fields");
            abend(EXIT_FAILURE, tmp_str);
        }
    }
    for (i = 0; i < FIELD_MAXCNT; i++) {
        form->text[i] = calloc(1, sizeof(Text));
        if (!form->text[i]) {
            sprintf(tmp_str, "FORM: calloc failed for text");
            abend(EXIT_FAILURE, tmp_str);
        }
    }
    form->didx = 0;
    form->fidx = 0;
    form->fcnt = 0;
    form->cols = 34;
    while ((fgets(in_buf, MAXLEN, form_desc_fp)) != nullptr) {
        s = in_buf;
        in_line_num++;
        l = trim(in_buf);
        if (l == 0)
            continue;
        if (*s == D_COMMENT)
            continue;
        delim[0] = '\n';
        delim[1] = in_buf[1];
        delim[2] = '\0';
        strnz__cpy(tmp_buf, in_buf, MAXLEN - 1);
        tmp_buf_p = tmp_buf;
        if (!(token = strtok(tmp_buf_p, delim))) {
            continue;
        }
        directive = *token;
        switch ((int)directive) {
        case D_COMMENT:
            break;
        case D_CALC:
            form->f_calculate = true;
            break;
        case D_QUERY:
            form->f_query = true;
            break;
        case D_GETTER:
            form->f_process = true;
            break;
        case D_CMD:
            if (!(token = strtok(nullptr, delim))) {
                form_desc_error(form, in_line_num, in_buf,
                                "FORM: receiver_cmd delimiter");
                continue;
            }
            strnz__cpy(form->receiver_cmd, token, MAXLEN - 1);
            break;
        case D_HELP:
            if (!(token = strtok(nullptr, delim))) {
                form_desc_error(form, in_line_num, in_buf,
                                "FORM: help_spec delimiter");
            }
            strnz__cpy(form->help_spec, token, MAXLEN - 1);
            break;
        case D_FIELD:
            if (form->field[form->fidx] == nullptr) {
                sprintf(tmp_str, "FORM: calloc failed for fields");
                abend(EXIT_FAILURE, tmp_str);
            }
            if (!(token = strtok(nullptr, delim))) {
                form_desc_error(form, in_line_num, in_buf,
                                "FORM: line number delimiter");
                return 1;
            }
            form->field[form->fidx]->line = atoi(token);
            if (form->field[form->fidx]->line >= FIELD_MAXCNT) {
                form_desc_error(form, in_line_num, in_buf,
                                "FORM: invalid line number");
                return 1;
            }
            if (!(token = strtok(nullptr, delim))) {
                form_desc_error(form, in_line_num, in_buf,
                                "FORM: column number delimiter");
                return 1;
            }
            form->field[form->fidx]->col = atoi(token);
            if (form->field[form->fidx]->col >= FIELD_MAXLEN) {
                form_desc_error(form, in_line_num, in_buf,
                                "FORM: invalid column number");
                break;
            }
            if (!(token = strtok(nullptr, delim))) {
                strnz__cpy(tmp_str, in_buf, MAXLEN - 1);
                form_desc_error(form, in_line_num, tmp_str, "FORM: length delimiter");
                break;
            }
            form->field[form->fidx]->len = atoi(token);
            if (form->field[form->fidx]->len > FIELD_MAXLEN) {
                form_desc_error(form, in_line_num, in_buf, "FORM: invalid length");
                break;
            }
            if (!(token = strtok(nullptr, delim))) {
                form_desc_error(form, in_line_num, in_buf,
                                "FORM: validation code delimiter");
                break;
            }
            form->field[form->fidx]->ff = 0;
            for (i = 0; i < FF_INVALID; i++) {
                str_to_lower(token);
                str_to_lower(ff_tbl[i]);
                if (!strcmp(token, ff_tbl[i])) {
                    form->field[form->fidx]->ff = i;
                    break;
                }
            }
            if (form->field[form->fidx]->ff >= FF_INVALID) {
                form_desc_error(form, in_line_num, in_buf,
                                "FORM: invalid format code");
                break;
            }
            cols =
                form->field[form->fidx]->col + form->field[form->fidx]->len + 1;
            if (cols > form->cols)
                form->cols = cols;
            form->fidx++;
            form->fcnt = form->fidx;
            break;
        case D_TEXT:
            if (form->text[form->didx] == nullptr) {
                sprintf(tmp_str, "FORM: calloc failed for text");
                abend(EXIT_FAILURE, tmp_str);
            }
            if (!(token = strtok(nullptr, delim))) {
                form_desc_error(form, in_line_num, in_buf,
                                "FORM: line number delimiter");
                break;
            }
            form->text[form->didx]->line = atoi(token);
            if (form->text[form->didx]->line >= FIELD_MAXCNT) {
                form_desc_error(form, in_line_num, in_buf,
                                "FORM: invalid line number");
                break;
            }
            if (!(token = strtok(nullptr, delim))) {
                form_desc_error(form, in_line_num, in_buf,
                                "FORM: column number delimiter");
                break;
            }
            form->text[form->didx]->col = atoi(token);
            if (form->text[form->didx]->col >= FIELD_MAXLEN) {
                form_desc_error(form, in_line_num, in_buf,
                                "FORM: invalid column number");
                break;
            }
            if (!(token = strtok(nullptr, delim))) {
                form_desc_error(form, in_line_num, in_buf, "FORM: text delimiter");
                break;
            }
            strnz__cpy(form->text[form->didx]->str, token, MAXLEN - 1);
            form->text[form->didx]->len = strlen(form->text[form->didx]->str);
            if (form->text[form->didx]->len > FIELD_MAXLEN) {
                form_desc_error(form, in_line_num, in_buf, "FORM: invalid length");
                break;
            }
            cols =
                form->text[form->didx]->col + form->text[form->didx]->len + 1;
            if (cols > form->cols)
                form->cols = cols;
            form->didx++;
            form->dcnt = form->didx;
            break;
        case D_HEADER:
            if ((token = strtok(nullptr, delim))) {
                strnz__cpy(form->title, token, MAXLEN - 1);
            }
            break;
        default:
            form_desc_error(form, in_line_num, in_buf, "invalid directive");
            break;
        }
    }
    fclose(form_desc_fp);
    if (form->didx < 1 && form->fidx < 1) {
        ssnprintf(em0, MAXLEN - 1, "%s, line: %d", __FILE__, __LINE__);
        ssnprintf(em1, MAXLEN - 1, "%s", "Error in description file:");
        ssnprintf(em2, MAXLEN - 1, "%s", form->mapp_spec);
        display_error(em0, em1, em2, nullptr);
        return (1);
    }
    return (0);
}
/** @brief Read initial data for form fields from a specified input source,
   such as a file or standard input, and populate the form fields with the
   data.
    @ingroup form_engine
    @param form A pointer to the Form structure containing form data and
   state.
    @return 0 on success, or a non-zero value if an error occurs while
   reading the data or if the specified input source is invalid or empty. */
int form_read_data(Form *form) {
    struct stat sb;
    char in_buf[MAXLEN];
    char field[MAXLEN];
    int cmd_key;
 
    if (!form->f_in_pipe) {
        if (form->f_in_spec && form->in_spec[0] != '\0') {
            if ((lstat(form->in_spec, &sb) == -1) || (sb.st_size == 0) ||
                ((form->in_fp = fopen(form->in_spec, "rb")) == nullptr)) {
                strnz__cat(em0, form->in_spec, MAXLEN - 1);
                if (sb.st_size == 0)
                    strnz__cpy(em1, "File is empty", MAXLEN - 1);
                else
                    strnz__cpy(em1, "File does not exist", MAXLEN - 1);
                strnz__cpy(em2, "Fields will be blank or zero", MAXLEN - 1);
                cmd_key = display_error(em0, em1, em2, nullptr);
                if (cmd_key == KEY_F09)
                    return (1);
            }
            if (form->in_fp == nullptr)
                return (1);
        } else
            return (0);
    }
    form->fidx = 0;
    if (form->in_fp != nullptr) {
        while ((fgets(in_buf, MAXLEN, form->in_fp)) != nullptr) {
            if (form->fidx < FIELD_MAXCNT)
                strnz__cpy(field, in_buf, MAXLEN - 1);
            form_fmt_field(form, field);
            form->fidx++;
        }
        fclose(form->in_fp);
    }
    return (0);
}
/** @brief Execute a command specified in the form description file, passing
   form field values as arguments, and optionally redirecting output to a file.
    @ingroup form_engine
    @param form A pointer to the Form structure containing form data and state.
    @return 0 on success, or a non-zero value if an error occurs while
    constructing or executing the command. */
int form_exec_cmd(Form *form) {
    char earg_str[MAXLEN + 1];
    uint i;
    strnz__cpy(earg_str, form->receiver_cmd, MAXLEN - 1);
    for (i = 0; i < form->fcnt; i++) {
        strnz__cat(earg_str, " ", MAXLEN - 1);
        strnz__cat(earg_str, form->field[i]->accept_s, MAXLEN - 1);
    }
    if (form->f_out_spec && form->f_process) {
        strnz__cat(earg_str, " >", MAXLEN - 1);
        strnz__cat(earg_str, form->out_spec, MAXLEN - 1);
    }
    shell(earg_str);
    return 0;
}
/** @brief Execute a command specified by the -R option on the form command line
    @ingroup form_engine
    @param init A pointer to the Init structure
    @return 0 on success, or a non-zero value if an error occurs while
   constructing or executing the command.
    @details This function constructs a command by taking the receiver_cmd
   appending field values as arguments, and handling special cases such as
   multiple command arguments or placeholder substitution. It then executes the
   command, either displaying the output in a popup view if the command is
   "view", or executing it directly in a child process for other commands. The
   function also handles error cases and ensures that resources are properly
   freed. */
int form_exec_receiver(Init *init) {
    int rc = -1;
    uint eargc;
    char *eargv[MAXARGS];
    char tmp_str[MAXLEN] = {'\0'};
    char title[MAXLEN];
    char sav_arg[MAXLEN];
    char *out_s;
    uint eargx = 0;
    uint i = 0;
    pid_t pid = 0;
    bool f_append_values = false;
 
    title[0] = '\0';
    Form *form = init->form;
    if (form->receiver_cmd[0] == '\0')
        return -1;
    // Eliminate leading and trailing quotes
    if (form->receiver_cmd[0] == '\\' || form->receiver_cmd[0] == '\"') {
        size_t len = strlen(form->receiver_cmd);
        if (len > 1 && form->receiver_cmd[len - 1] == '\"') {
            memmove(form->receiver_cmd, form->receiver_cmd + 1, len - 2);
            form->receiver_cmd[len - 2] = '\0';
        }
    }
    eargc = str_to_args(eargv, form->receiver_cmd, MAXARGS - 1);
    tmp_str[0] = '\0';
    if (form->f_multiple_cmd_args) {
        // concatenate fields into a single argument
        for (i = 0; i < form->fcnt; i++) {
            if (form->field[i]->accept_s[0] && eargc < MAXARGS) {
                if (tmp_str[0] != '\0')
                    strnz__cat(tmp_str, " ", MAXLEN - 1);
                strnz__cat(tmp_str, form->field[i]->accept_s, MAXLEN - 1);
            }
        }
        eargv[eargc++] = strdup(tmp_str);
    } else {
        f_append_values = false;
        // find lines with "%%" to determine where to insert field values
        i = 0;
        while (i < eargc) {
            /** This is the line that gets the selected objects */
            if (strstr(eargv[i], "%%") != nullptr) {
                tmp_str[0] = '\0';
                f_append_values = true;
                strnz__cpy(sav_arg, eargv[i], MAXLEN - 1);
                eargx = i;
                break;
            }
            i++;
        }
        for (i = 0; i < form->fcnt; i++) {
            // concatenate field values onto tmp_str
            if (form->field[i]->accept_s[0] && eargc < MAXARGS - 1) {
                if (f_append_values == true) {
                    if (tmp_str[0] != '\0')
                        strnz__cat(tmp_str, " ", MAXLEN - 1);
                    strnz__cat(tmp_str, form->field[i]->accept_s, MAXLEN - 1);
                    continue;
                }
                eargv[eargc++] = strdup(form->field[i]->accept_s);
            }
        }
        // replace "%%" with concatenated field values
        if (f_append_values == true) {
            if (eargv[eargx] != nullptr) {
                free(eargv[eargx]);
                eargv[eargx] = nullptr;
            }
            out_s = rep_substring(sav_arg, "%%", tmp_str);
            if (out_s == nullptr || out_s[0] == '\0') {
                i = 0;
                while (i < eargc) {
                    if (eargv[i] != nullptr)
                        free(eargv[i]);
                    i++;
                }
                Perror("rep_substring() failed in form_exec_objects");
                return 1;
            }
            strnz__cpy(title, out_s, MAXLEN - 1);
            eargv[eargx] = strdup(out_s);
            if (out_s != nullptr) {
                free(out_s);
                out_s = nullptr;
            }
        }
    }
    if (eargc > 0)
        eargv[eargc] = nullptr;
    base_name(tmp_str, eargv[0]);
    if (tmp_str[0] != '\0' && (strcmp(tmp_str, "view") == 0)) {
        /** initialize popup_view arguments and execute popup_view to display
           command output within form interface */
        init->lines = 60;
        init->cols = 80;
        init->begy = form->begy + 1;
        init->begx = form->begx + 1;
        if (title[0] != '\0')
            strnz__cpy(init->title, title, MAXLEN - 1);
        else
            strnz__cpy(init->title, eargv[eargc], MAXLEN - 1);
        popup_view(init, eargc, eargv, init->lines, init->cols, init->begy,
                   init->begx);
        i = 0;
        while (i < eargc) {
            if (eargv[i] != nullptr)
                free(eargv[i]);
            i++;
        }
        return 0;
    } else {
        ui_endwin();
        if ((pid = fork()) == -1) {
            /** fork failed, free eargv and return error */
            i = 0;
            while (i < eargc) {
                if (eargv[i] != nullptr)
                    free(eargv[i]);
                i++;
            }
            Perror("fork() failed in form_exec_objects");
            return (1);
        }
        if (pid == 0) {
            /** Prevent child process from writing to terminal */
            int dev_null = open("/dev/null", O_WRONLY);
            if (dev_null == -1) {
                Perror("open(/dev/null) failed in init_form child process");
                exit(EXIT_FAILURE);
            }
            dup2(dev_null, STDERR_FILENO);
            close(dev_null);
            /** Child process to execute command */
            execvp(eargv[0], eargv);
            /** If execvp returns, it means execution failed, so free eargv
               and print error message before exiting */
            strnz__cpy(tmp_str, "Can't exec form cmd: ", MAXLEN - 1);
            strnz__cat(tmp_str, eargv[0], MAXLEN - 1);
            Perror(tmp_str);
            exit(EXIT_FAILURE);
        }
    }
    waitpid(pid, nullptr, 0);
    destroy_argv(eargc, eargv);
    sig_prog_mode();
    ui_restore_wins();
    return rc;
}
/** @brief Write form field values to a specified output destination, such
   as a file or standard output, based on the form configuration and user
   input.
    @ingroup form_engine
    @param form A pointer to the Form structure containing form data and
   state.
    @return 0 on success, or a non-zero value if an error occurs while
   writing the data or if the specified output destination is invalid. */
int form_write(Form *form) {
    uint n;
    if (form->out_spec[0] == '\0' || strcmp(form->out_spec, "-") == 0 ||
        strcmp(form->out_spec, "/dev/stdout") == 0) {
        strnz__cpy(form->out_spec, "/dev/stdout", MAXLEN - 1);
        close(form->out_fd);
        form->out_fd = open(form->out_spec, O_CREAT | O_RDWR | O_TRUNC, 0644);
        if (form->out_fd == -1) {
            ssnprintf(em0, MAXLEN - 1, "%s, line: %d", __FILE__, __LINE__ - 1);
            strnz__cpy(em1, "open ", MAXLEN - 1);
            strnz__cat(em1, form->out_spec, MAXLEN - 1);
            strerror_r(errno, em2, MAXLEN);
            display_error(em0, em1, em2, nullptr);
            return (1);
        }
        dup2(form->out_fd, STDOUT_FILENO);
        form->out_fp = fdopen(STDOUT_FILENO, "w");
        form->f_out_spec = true;
        form->f_out_pipe = true;
    } else {
        if ((form->out_fp = fopen(form->out_spec, "w")) == nullptr) {
            ssnprintf(em0, MAXLEN - 1, "%s, line: %d", __FILE__, __LINE__ - 1);
            strerror_r(errno, em2, MAXLEN);
            display_error(em0, em1, em2, nullptr);
            return (1);
        }
    }
    if (form->out_fp == nullptr) {
        ssnprintf(em0, MAXLEN - 1, "%s, line: %d", __FILE__, __LINE__ - 1);
        strnz__cpy(em1, "fopen ", MAXLEN - 1);
        strnz__cat(em1, form->out_spec, MAXLEN - 1);
        strerror_r(errno, em2, MAXLEN);
        display_error(em0, em1, em2, nullptr);
        return (1);
    }
    for (n = 0; n < form->fcnt; n++)
        fprintf(form->out_fp, "%s\n", form->field[n]->accept_s);
    if (form->out_fp != nullptr)
        fclose(form->out_fp);
    return (0);
}
/** @brief Handle errors encountered while parsing the form description
   file, providing detailed error messages that include the file name, line
   number, and the specific error encountered.
   @ingroup form_engine
    @param form A pointer to the Form structure containing form data and
   state.
    @param in_line_num The line number in the description file where the
   error occurred.
    @param in_buf The content of the line that caused the error, for
   context.
    @param em A specific error message describing the nature of the error.
    @return An integer status code indicating how the user responded to the
   error message (e.g., which key they pressed to acknowledge the error). */
int form_desc_error(Form *form, int in_line_num, char *in_buf, char *em) {
    int cmd_key;
    ssnprintf(em0, MAXLEN - 1, "%s: %s", __FILE__, em);
    ssnprintf(em1, MAXLEN - 1, "Desc file: %s, line: %d", form->mapp_spec,
              in_line_num);
    strnz__cpy(em2, in_buf, MAXLEN - 1);
    cmd_key = display_error(em0, em1, em2, nullptr);
    return cmd_key;
}