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
 */
 
/** @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(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 **, int, int);
int form_engine(Init *);
int form_yx_to_fidx(Form *, int, int);
 
/** @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, int begy, int begx) {
    int rc;
    char tmp_str[MAXLEN];
    if (init->form != nullptr)
        destroy_form(init);
    init->form = new_form(init, argc, argv, begy, begx);
    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);
#ifdef DEBUG_IMMEDOK
    immedok(form->win, true);
    immedok(form->box, true);
#endif
    rc = form_engine(init);
    destroy_chyron(form->chyron);
    if (form->win)
        win_del();
    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 = 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_F(1));
    set_chyron_key(form->chyron, 9, "F9 Cancel", KEY_F(9));
    set_chyron_key(form->chyron, 10, "F10 Continue", KEY_F(10));
    compile_chyron(form->chyron);
    display_chyron(form->win, form->chyron, form->lines - 1, form->chyron->l);
    form->fidx = 0;
    form_action = 0;
    while (1) {
        if (form_action == 0 || form_action == FA_CONTINUE)
            form_action = field_navigator(form);
        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 = init->form;
    wmove(form->win, form->lines - 1, 0);
    wclrtoeol(form->win);
    unset_chyron_key(form->chyron, 18);
    set_chyron_key(form->chyron, 8, "F8 Edit", KEY_F(8));
    set_chyron_key(form->chyron, 10, "F10 Commit", KEY_F(10));
    compile_chyron(form->chyron);
    rc = -1;
    while (loop) {
        if (rc == -1) {
            display_chyron(form->win, form->chyron, form->lines - 1,
                           form->chyron->l);
            tcflush(2, TCIFLUSH);
            wrefresh(form->box);
            c = xwgetch(form->win, form->chyron, -1);
        }
        switch (c) {
        case KEY_F(1):
            return FA_HELP;
        case KEY_F(8):
            if (is_set_chyron_key(form->chyron, 8)) {
                loop = false;
                rc = FA_CONTINUE;
                break;
            }
            continue;
        case KEY_F(9):
            loop = false;
            rc = FA_CANCEL;
            break;
        case KEY_F(10):
            loop = false;
            rc = FA_ACCEPT;
            break;
        case KEY_MOUSE:
            continue;
        default:
            break;
        }
    }
    unset_chyron_key(form->chyron, 8);
    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_F(5) Calculate, Query, or Getter. option on the chyron.
        2. The user can then cancel the operation by pressing KEY_F(9) or
        activate the getter option by pressing KEY_F(5).
        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) {
    int i, c, rc;
    char tmp_str[MAXLEN];
    char earg_str[MAXLEN + 1];
    char *eargv[MAXARGS];
    int eargc;
    char file_spec[MAXLEN];
    bool loop = true;
    pid_t pid;
    int pipe_fd[2];
 
    form = init->form;
    wmove(form->win, form->lines - 1, 0);
    wclrtoeol(form->win);
    unset_chyron_key(form->chyron, 18);
    unset_chyron_key(form->chyron, 10);
    strnz__cpy(tmp_str, "F5 ", MAXLEN - 1);
 
    if (form->f_process)
        strnz__cat(tmp_str, "Process", MAXLEN - 1);
    else if (form->f_calculate)
        strnz__cat(tmp_str, "Calculate", MAXLEN - 1);
    else if (form->f_query)
        strnz__cat(tmp_str, "Query", MAXLEN - 1);
    set_chyron_key_cp(form->chyron, 5, tmp_str, KEY_F(5), cp_nt_hl_rev);
 
    while (loop) {
        compile_chyron(form->chyron);
        display_chyron(form->win, form->chyron, form->lines - 1,
                       form->chyron->l);
        click_y = click_x = -1;
        tcflush(2, TCIFLUSH);
        wrefresh(form->box);
        c = xwgetch(form->win, form->chyron, -1);
        switch (c) {
        case KEY_F(1):
            return FA_HELP;
        case KEY_F(5):
            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);
                    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_with_timeout(pid, wait_timeout);
                destroy_argv(eargc, eargv);
                form_display_fields(form);
                set_chyron_key_cp(form->chyron, 5, "F5 Edit", KEY_F(5),
                                  cp_nt_hl_rev);
                set_chyron_key(form->chyron, 10, "F10 Commit", KEY_F(10));
                compile_chyron(form->chyron);
                continue;
            }
            break;
        case KEY_F(8):
            if (is_set_chyron_key(form->chyron, 8)) {
                loop = false;
                rc = FA_CONTINUE;
                break;
            }
            continue;
        case KEY_F(9):
            loop = false;
            rc = FA_CANCEL;
            break;
        case KEY_F(10):
            loop = false;
            rc = FA_ACCEPT;
            break;
        case KEY_MOUSE:
            break;
        default:
            break;
        }
    }
    unset_chyron_key(form->chyron, 8);
    unset_chyron_key(form->chyron, 5);
    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 < 0)
        return (-1);
    while (1) {
        cmd_key = field_editor(form);
 
        switch (cmd_key) {
        case KEY_F(10):
            return (FA_ACCEPT);
        case KEY_F(1):
            return (FA_HELP);
        case KEY_F(5):
            if (form->f_process)
                return (FA_CALC);
            break;
        case KEY_F(9):
            return (FA_CANCEL);
        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;
        }
    }
}
int form_yx_to_fidx(Form *form, int y, int x) {
    for (int 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) {
    int n, flin, fcol;
    char tmp_str[MAXLEN];
 
    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 (box_new(form->lines, form->cols, form->begy, form->begx, form->title,
                true)) {
        strnz__cpy(tmp_str, "box_new failed: ", MAXLEN - 1);
        strnz__cat(tmp_str, form->title, MAXLEN - 1);
        Perror(tmp_str);
        return (1);
    }
#ifdef DEBUG_IMMEDOK
    immedok(form->win, TRUE);
#endif
    form->box = win_box[win_ptr];
    form->win = win_win[win_ptr];
    wnoutrefresh(form->win);
    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;
            // mvwadd_wch(form->box, flin, fcol, &form->brktl);
            mvwaddch(form->box, flin, fcol, form->brackets[0]);
            fcol += form->field[form->fidx]->len + 1;
            // mvwadd_wch(box, flin, fcol, &form->brktr);
            mvwaddch(form->box, flin, fcol, form->brackets[1]);
        }
    }
    wnoutrefresh(form->box);
    for (n = 0; n < form->dcnt; n++) {
        strnz(form->text[n]->str, form->cols - 3);
        mvwaddstr(form->win, form->text[n]->line, form->text[n]->col,
                  form->text[n]->str);
        wnoutrefresh(form->win);
    }
    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) {
    int flin, fcol;
    char fill_char = form->fill_char[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);
        strnfill(form->field[form->fidx]->filler_s, fill_char,
                 form->field[form->fidx]->len);
        strnz(form->field[form->fidx]->display_s, form->field[form->fidx]->len);
        flin = form->field[form->fidx]->line;
        fcol = form->field[form->fidx]->col;
        mvwaddstr(form->win, flin, fcol, form->field[form->fidx]->filler_s);
        mvwaddstr(form->win, flin, fcol, form->field[form->fidx]->display_s);
        wnoutrefresh(form->win);
    }
    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;
    int cols = 0;
    int 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(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(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(in_line_num, in_buf,
                                "FORM: line number delimiter");
                return 1;
            }
            form->field[form->fidx]->line = atoi(token);
            if (form->field[form->fidx]->line < 0 ||
                form->field[form->fidx]->line >= FIELD_MAXCNT) {
                form_desc_error(in_line_num, in_buf,
                                "FORM: invalid line number");
                return 1;
            }
            if (!(token = strtok(nullptr, delim))) {
                form_desc_error(in_line_num, in_buf,
                                "FORM: column number delimiter");
                return 1;
            }
            form->field[form->fidx]->col = atoi(token);
            if (form->field[form->fidx]->col < 0 ||
                form->field[form->fidx]->col >= FIELD_MAXLEN) {
                form_desc_error(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(in_line_num, tmp_str, "FORM: length delimiter");
                break;
            }
            form->field[form->fidx]->len = atoi(token);
            if (form->field[form->fidx]->len < 0 ||
                form->field[form->fidx]->len > FIELD_MAXLEN) {
                form_desc_error(in_line_num, in_buf, "FORM: invalid length");
                break;
            }
            if (!(token = strtok(nullptr, delim))) {
                form_desc_error(in_line_num, in_buf,
                                "FORM: validation code delimiter");
                break;
            }
            form->field[form->fidx]->ff = -1;
            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 < 0 ||
                form->field[form->fidx]->ff >= FF_INVALID) {
                form_desc_error(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(in_line_num, in_buf,
                                "FORM: line number delimiter");
                break;
            }
            form->text[form->didx]->line = atoi(token);
            if (form->text[form->didx]->line < 0 ||
                form->text[form->didx]->line >= FIELD_MAXCNT) {
                form_desc_error(in_line_num, in_buf,
                                "FORM: invalid line number");
                break;
            }
            if (!(token = strtok(nullptr, delim))) {
                form_desc_error(in_line_num, in_buf,
                                "FORM: column number delimiter");
                break;
            }
            form->text[form->didx]->col = atoi(token);
            if (form->text[form->didx]->col < 0 ||
                form->text[form->didx]->col >= FIELD_MAXLEN) {
                form_desc_error(in_line_num, in_buf,
                                "FORM: invalid column number");
                break;
            }
            if (!(token = strtok(nullptr, delim))) {
                form_desc_error(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 < 0 ||
                form->text[form->didx]->len > FIELD_MAXLEN) {
                form_desc_error(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(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];
 
    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_F(9))
                    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];
    int 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;
    int eargc;
    char *eargv[MAXARGS];
    char tmp_str[MAXLEN] = {'\0'};
    char title[MAXLEN];
    char sav_arg[MAXLEN];
    char *out_s;
    int eargx = 0;
    int i = 0;
    pid_t pid = 0;
    bool f_append_values = false;
 
    title[0] = '\0';
    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 {
        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);
    restore_curses_tioctl();
    sig_prog_mode();
    werase(stdscr);
    wrefresh(stdscr);
    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) {
    int 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 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(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;
}