cm.h

Go to the documentation of this file.

/** @file cm.h
 *  @brief Headder for C-Menu API library, libcm.so
 *  @author Bill Waller
 *  Copyright (c) 2025
 *  MIT License
 *  billxwaller@gmail.com
 *  @date 2026-02-09
 */
#ifndef _CM_H
#define _CM_H 1
 
#define _GNU_SOURCE
#define _XOPEN_SOURCE_EXTENDED 1 /**< Enable wide character support */
#define NCURSES_WIDECHAR 1       /**< Enable wide character support */
#include "version.h"
#include <argp.h>
#ifdef UAL_UI
#include "../ui/ui_ncurses_internal.h"
#include "ui_backend.h"
#include <ncursesw/ncurses.h>
#include <ncursesw/panel.h>
#endif
#ifdef NOTCURSES_UI
#include "ui_backend.h"
#include "ui_notcurses_internal.h"
#include <notcurses/notcurses.h>
#endif
#include <signal.h>
#include <stdbool.h>
#include <stddef.h>
#include <stdlib.h>
#include <time.h>
#include <wait.h>
#include <wchar.h>
 
extern int cmenu_log_fd;
 
#if __STDC_VERSION__ < 202311L
#define nullptr NULL
#endif
 
#define MAXWIN 30 /**< maximum number of windows that can be created */
 
#ifdef UI_NCURSES
extern SCREEN *screen;
#endif
extern FILE *tty_fp;
#define MAX_ARGS 64   /**< maximum number of arguments for external commands */
#define MAXLEN 256    /**< maximum length for strings and buffers */
#define MAXARGS 64    /**< maximum number of arguments */
#define SCR_COLS 1024 /**< maximum number of columns in the terminal screen */
#define MAX_DEPTH 3   /**< default depth for recursive file searching */
#define SCREEN_MAX_LINES 100
#define Ctrl(c) ((c) & 0x1f)
#include <stdio.h>
 
typedef struct {
    uint yyyy;
    uint mm;
    uint dd;
} Date;
 
typedef struct {
    uint hh;
    uint mm;
    uint ss;
} Time;
 
#define DIV_ROUND_UP(n, d) (((n) + (d) - 1) / (d))
 
/** @brief max macro evaluates two expressions, returning greatest result.
    @details These macros use compound statements to create local scopes for the
   temporary variables _x and _y, which store the values of x and y,
   respectively. This ensures that if x or y have side effects (such as being
   incremented), they will only be evaluated once when the macro is expanded.
    The use of typeof allows the macro to work with any data type.
    The line (void)(&_x == &_y) is a compile-time check to ensure that the
   types of the arguments are compatible.
    This implementation of the min and max macros provides a safer and
   more robust way to determine the minimum and maximum values between two
   expressions without risking unintended consequences from multiple
   evaluations.
 */
#define max(a, b)
    ({
        __typeof__(a) _a = (a);
        __typeof__(a) _b = (b);
        _a > _b ? _a : _b;
    })
/** @brief min macro evaluates two expressions, returning least result */
#define min(x, y)
    ({
        typeof(x) _x = (x);
        typeof(x) _y = (y);
        (void)(&_x == &_y);
        _x < _y ? _x : _y;
    })
/**
 */
/** @brief MIN macro for compatibility with code that uses the same name,
   while avoiding multiple evaluations of the arguments.
   @details /usr/include/sys/param.h contains implementations of the MIN and MAX
   macros, which are simple but can lead to issues with multiple evaluations of
   the arguments if they have side effects. These macros provides a safer
   alternative to param.h Here are the macros from /usr/include/sys/param.h. You
   may comment out the macros defined herein and use the macros in param.h if
   you prefer.
    @code
    #define MIN(a, b) (((a) < (b)) ? (a) : (b))
    #define MAX(a, b) (((a) > (b)) ? (a) : (b))
    @endcode
    @note The following macro provides a safer alternative to param.h
 */
#define MAX(a, b)
    ({
        typeof(a) _a = (a);
        typeof(y) _b = (b);
        _a > _b ? _a : _b;
    })
/** @brief MAX macro for compatibility with code that uses the same name,
   while avoiding multiple evaluations of the arguments.
    @note The following macro provides a safer alternative to param.h
 */
#define MIN(x, y)
    ({
        typeof(x) _x = (x);
        typeof(y) _y = (y);
        (void)(&_x == &_y);
        _x < _y ? _x : _y;
    })
/** @brief ABS macro for absolute value, which evaluates the expression once and
   returns the absolute value.
    @details This macro uses a compound statement to create a local scope for
   the temporary variable _a, which stores the value of x. This ensures that if
   x has side effects (such as being incremented), it will only be evaluated
   once when the macro is expanded. The use of typeof allows the macro to work
   with any data type that supports comparison with zero and negation.
 */
#define ABS(x)
    ({
        __typeof__(x) _a = (x);
        _a < 0 ? -_a : _a;
    })
#define S_TOLOWER(c)
    ({
        int __c = (c);
        (__c >= 'A' && __c <= 'Z') ? (__c + ('a' - 'A')) : __c;
    })
#define S_TOUPPER(c)
    ({
        int __c = (c);
        (__c >= 'a' && __c <= 'z') ? (__c - ('a' - 'A')) : __c;
    })
 
/** to_uppercase(c) - convert a lowercase letter to uppercase */
#define to_uppercase(c)
    if (c >= 'a' && c <= 'z')
    c -= ' '
/** to_lowercase(c) - convert an uppercase letter to lowercase */
#define to_lowercase(c)
    if (c >= 'A' && c <= 'Z')
    c += ' '
/**
    @brief Used for xterm256 color conversions
 */
typedef enum {
    CLR_BLACK,
    CLR_RED,
    CLR_GREEN,
    CLR_YELLOW,
    CLR_BLUE,
    CLR_MAGENTA,
    CLR_CYAN,
    CLR_WHITE,
    CLR_BBLACK,
    CLR_BRED,
    CLR_BGREEN,
    CLR_BYELLOW,
    CLR_BBLUE,
    CLR_BMAGENTA,
    CLR_BCYAN,
    CLR_BWHITE,
    CLR_BORANGE,
    CLR_FG,
    CLR_BG,
    CLR_BOX_FG,
    CLR_BOX_BG,
    CLR_IND_FG,
    CLR_IND_BG,
    CLR_BRACKETS_FG,
    CLR_BRACKETS_BG,
    CLR_FILL_CHAR_FG,
    CLR_FILL_CHAR_BG,
    CLR_LN_FG,
    CLR_LN_BG,
    CLR_CMDLN_FG,
    CLR_CMDLN_BG,
    CLR_NT_FG,
    CLR_NT_BG,
    CLR_NT_REV_FG,
    CLR_NT_REV_BG,
    CLR_NT_HL_FG,
    CLR_NT_HL_BG,
    CLR_NT_HL_REV_FG,
    CLR_NT_HL_REV_BG,
    CLR_TITLE_FG,
    CLR_TITLE_BG,
    CLR_NCOLORS
} ColorsEnum;
 
extern UiCell cell_default;
extern UiCell cell_fill_char;
extern UiCell cell_brktl;
extern UiCell cell_brktr;
extern UiCell cell_nt;
extern UiCell cell_nt_rev;
extern UiCell cell_nt_hl;
extern UiCell cell_nt_hl_rev;
extern UiCell cell_box;
extern UiCell cell_ind;
extern UiCell cell_cmdln;
extern UiCell cell_title;
extern UiCell cell_ln;
extern UiCell cell_ran;
extern UiCell cell_chk;
extern UiCell cell_ls;
extern UiCell cell_rs;
extern UiCell cell_ts;
extern UiCell cell_bs;
extern UiCell cell_tl;
extern UiCell cell_tr;
extern UiCell cell_ho;
extern UiCell cell_ve;
extern UiCell cell_bl;
extern UiCell cell_br;
extern UiCell cell_lt;
extern UiCell cell_rt;
extern UiCell cell_tt;
extern UiCell cell_bt;
extern UiCell cell_cr;
extern UiCell cell_sp;
 
typedef enum {
    /** byte 0 - bits 0-7  Selection Flags*/
    LF_HIDE = 0b00000001,      /**< 1 Don't list hidden files */
    LF_ICASE = 0b00000010,     /**< 2 Ignore case in search */
    LF_EXC_REGEX = 0b00000100, /**< 4 Exclude files matching regex */
    LF_REGEX = 0b00001000,     /**< 8 Include files matching regex */
    LF_EXEC = 0b00010000,      /**< 16 Execute command each file */
    LF_USER = 0b00100000,      /**< 32 Select User Name */
                               /** << 16 */
    /** byte 1 - bits 8-15 */
    LF_IXUSR = 0b00000001, /**< 1 Select Files with Execute Permission */
    LF_IWUSR = 0b00000010, /**< 2 Select Files with Write Permission */
    LF_IRUSR = 0b00000100, /**< 4 Select Files with Read Permission */
    LF_ISGID = 0b00010000, /**< 16 Select Setgid Files */
    LF_ISUID = 0b00100000, /**< 32 Select Setuid Files */
} LFFlags;
 
/** byte 2 - bits 16-23 File types*/
typedef enum {
    LF_FIFO = 0b00000001,   /**<   1 named pipe */
    LF_CHR = 0b00000010,    /**<   2 character device */
    LF_DIR = 0b00000100,    /**<   4 directory */
    LF_BLK = 0b00001000,    /**<   8 block */
    LF_REG = 0b00010000,    /**<  16 regular file */
    LF_LNK = 0b00100000,    /**<  32 link */
    LF_SOCK = 0b01000000,   /**<  64 socket */
    LF_UNKNOWN = 0b10000000 /**< 128 unknown */
} LFTypes;
 
typedef enum {
    F_F0,      // 0
    F_FIFO,    // 1
    F_CHR,     // 2
    F_F1,      // 3
    F_DIR,     // 4
    F_F2,      // 5
    F_BLK,     // 6
    F_F3,      // 7
    F_REG,     // 8
    F_F4,      // 9
    F_LNK,     // 10
    F_F5,      // 11
    F_SOCK,    // 12
    F_F6,      // 13
    F_UNKNOWN, // 14
} F_Type;
 
// int const lf_type[][15] = {
//      {0, 0b00000001, 0b00000010, 0, 0b00000100, 0, 0b00001000, 0, 0b00010000, 0,
//       0b00100000, 0,0b01000000, 0, 0b10000000}};
 
/*
 * dirent d_type to lf_type for reference
------------------------   --------------------
d_type      binary   dec   lf_type     binary   dec ordinal
---------   -------- ---   ----------- -------- --- -------
DT_FIFO:    00000001   1   LF_FIFO:    00000001   1     1
DT_CHR:     00000010   2   LF_CHR:     00000010   2     2
DT_DIR:     00000100   4   LF_DIR:     00000100   4     3
DT_BLK:     00000110   6   LF_BLK:     00001000   8     4
DT_REG:     00001000   8   LF_REG:     00010000  16     5
DT_LNK:     00001010  10   LF_LNK:     00100000  32     6
DT_SOCK:    00001100  12   LF_SOCK:    01000000  64     7
DT_UNKNOWN: 00001110  14   LF_UNKNOWN: 10000000 128     8
 
    */
 
#define F_NO_STDERR 1
 
/**
                      Include     Exclude
                     ----------  ----------
    LF_FIFO       1  0 00000001  7 11111110 named pipe
    LF_CHR        2  1 00000010  6 11111101 character device
    LF_DIR        4  2 00000100  5 11111011 directory
    LF_BLK        8  3 00001000  4 11110111 block device
    LF_REG       16  4 00010000  3 11101111 regular file
    LF_LNK       32  5 00100000  2 11011111 link
    LF_SOCK      64  6 01000000  1 10111111 socket
    LF_UNKNOWN  128  7 10000000  0 01111111 unknown
*/
 
#define COLOR_LEN 8 /**< length of color code strings */
#define DEFAULTSHELL "/bin/bash"
#define S_WCOK 0x1000  /**< write or create permitted */
#define S_QUIET 0x2000 /**< quiet mode flag for file validation */
 
/** @brief This macro registers the end_pgm function to be called when the
   program exits.
    @details It checks the return value of atexit() to ensure that the
    registration was successful, and if not, it prints an error message and
    exits with a failure status. Programs using libcm should call __atexit in
    their main function to ensure that the end_pgm function is registered to be
    called on program exit. This will help ensure that the terminal is properly
    restored to its original state, even if the program encounters an error or
    is terminated unexpectedly. */
#define __atexit
    {
        int rc;
        rc = atexit(end_pgm);
        if (rc != 0) {
            fprintf(stderr, "\nCannot set exit function\n");
            exit(EXIT_FAILURE);
        }
    }
 
/** @struct Chyron
    @details The Chyron structure represents a key binding for a command in the
   chyron, which is a status line or message area in the terminal interface.
    The ChyronKey structure includes fields for displayable text,
    the key code, and the end position of the command text in the chyron.
    This structure allows xwgetch to map mouse clicks to key codes
    as defined by NCursesw and the C-Menu program.
    The text field holds the displayable text associated with the command.
    xwgetch() translates a mouse click on the chyron with a particular key code
    stored in this table.
    The use case is when the developer wants a dynamic chyron that can be
   easily changed depending on the context of the program without having to
   worry about translating mouse click positions to key codes.
    While many key codes are defined by NCursesw, the developer is free to
   define their own key codes for custom commands in the chyron. However,
   xwgetch() will translate mouse clicks to the key codes defined in this table,
   even if they interfere with standard NCurses key codes, Unicode code points,
   or ASCII characters. Just use common sense.
    In addition to returning the key code associated with mouse clicks on
   the chyron, xwgetch() also returns the key codes for standard keyboard input,
   and sets the global variables cliek_y and click_x to the coordinates of the
   mouse click.
 */
#define CHYRON_KEY_MAXLEN
    64                 /**< maximum length of the command text for a key \
                          binding in the chyron */
#define CHYRON_KEYS 20 /**< maximum number of key bindings for the chyron */
 
typedef struct {
    bool active;                  /**< whether the key binding is active */
    char text[CHYRON_KEY_MAXLEN]; /**< command text associated with the key code
                                   */
    uint keycode;                 /**< key code associated with the command */
    uint end_pos;                 /**< end position of the command text in the chyron */
    UiCell cell_base;             /**< cell base for colors/attributes */
} ChyronKey;
 
typedef struct {
    ChyronKey *key[CHYRON_KEYS]; /**< array of key bindings for the chyron */
    char s[MAXLEN];              /**< the chyron string, for displaying messages in */
    UiCell cmplx_buf[MAXLEN];    /**< the chyron wide character string */
                                 //  wchar_t wstr[MAXLEN];        /**< the chyron wide character string */
    uint l;                      /**< length of the chyron string, for display */
    UiSurface *sfc;              /** pointer to surface for the chyron */
    uint win;                    /** index to window of surface */
    uint y;                      /** y coordinante of the chyron in the window */
} Chyron;
 
extern void activate_chyron_key(Chyron *, uint);
extern void activate_all_chyron_keys(Chyron *);
extern void deactivate_chyron_key(Chyron *, uint);
extern void deactivate_all_chyron_keys(Chyron *);
extern int click_y; /**< the y coordinate of a mouse click */
extern int click_x; /**< the x coordinate of a mouse click */
 
extern Chyron *wait_mk_chyron();
extern bool wait_destroy(Chyron *);
extern bool waitpid_with_timeout(pid_t, uint);
extern int wait_timeout;
extern bool action_disposition(char *eitle, char *action_str);
extern int fork_detach_execvp(char **);
extern bool is_hex_str(char *, uint);
extern bool unstr_hex_clr(char *, char *);
 
extern bool f_debug; /**< a flag to indicate whether debug
output should be printed, for debugging purposes */
 
#define FG_COLOR 2    /**< default foreground color */
#define BG_COLOR 0    /**< default background color */
#define BO_COLOR 1    /**< default bold foreground color */
#define LN_COLOR 4    /**< default line number color */
#define LN_BG_COLOR 7 /**< default line number background */
 
extern ushort cp_default;            /**< default color pair index */
extern ushort cp_box;                /**< box color pair index */
extern ushort cp_ind;                /**< indicator color pair index */
extern ushort cp_bold;               /**< bold color pair index */
extern ushort cp_title;              /**< title color pair index */
extern ushort cp_highlight;          /**< highlight color pair index */
extern ushort cp_fill_char;          /**< fill character color pair index */
extern ushort cp_brackets;           /**< color pair index for field brackets */
extern ushort cp_nt;                 /**< normal color pair index */
extern ushort cp_nt_rev;             /**< reverse color pair index */
extern ushort cp_nt_hl;              /**< highlight color pair index */
extern ushort cp_nt_hl_rev;          /**< highlight reverse color pair index */
extern ushort cp_ln_fg;              /**< line number color pair index */
extern ushort cp_ln_bg;              /**< line number background color pair index */
extern ushort cp_cmdln_fg;           /**< command line number color pair index */
extern ushort cp_cmdln_bg;           /**< command line number background color pair index */
extern ushort cp_red;                /**< red background color pair index */
extern ushort cp_green;              /**< green background color pair index */
extern ushort cp_yellow;             /**< yellow background color pair index */
extern ushort cp_blue;               /**< blue background color pair index */
extern uint clr_idx;                 /**< current color index */
extern uint clr_cnt;                 /**< number of colors used */
extern uint clr_pair_idx;            /**< current color pair index */
extern uint clr_pair_cnt;            /**< number of color pairs supported by the terminal */
extern char const colors_text[][10]; /**< color codes for the 16 basic colors */
 
/** @struct ColorPair
  @details The ColorPair structure is a simple structure that holds information
  about a color pair, including the foreground color index, background color
  index, and the color pair index. This structure can be used to manage and
  apply color pairs in the ncurses library, allowing for easy customization of
  the terminal's appearance. By using this structure, you can easily keep track
  of the different color pairs you have defined and apply them to various
  elements in your terminal interface. */
typedef struct {
    uint fg;      /**< foreground color index */
    uint bg;      /**< background color index */
    uint pair_id; /**< color pair index */
} ColorPair;
 
/**< see termios.h */
extern struct termios shell_tioctl, curses_tioctl;
extern struct termios shell_in_tioctl, curses_in_tioctl;
extern struct termios shell_out_tioctl, curses_out_tioctl;
extern struct termios shell_err_tioctl, curses_err_tioctl;
 
extern bool f_have_shell_tioctl;  /**< shell tioctl captured */
extern bool f_have_curses_tioctl; /**< curses tioctl captured */
extern bool f_curses_open;        /**< curses mode is active */
extern bool f_restore_screen;     /**< whether to restore the screen */
 
extern void dump_opts(); /**< dump options to stdout */
 
extern void dump_opts_by_use(char *, char *); /**< dump options to stdout */
extern bool capture_shell_tioctl();
extern bool restore_shell_tioctl();
extern bool capture_curses_tioctl();
extern bool restore_curses_tioctl();
extern bool mk_raw_tioctl(struct termios *);
extern bool set_sane_tioctl(struct termios *);
 
extern int surface_box_win_new(uint, uint, uint, uint, char *);
extern int surface_split_box_win_new(uint, uint, uint, uint, uint, uint, char *);
 
extern void win_resize(uint, uint, char *);
extern void signal_handler(int);
extern bool handle_signal(sig_atomic_t);
extern volatile sig_atomic_t sig_received;
extern void sig_prog_mode();
extern void sig_dfl_mode();
extern bool mk_dir(char *dir);
extern int segmentation_fault();
extern char *iso8601_time(char *, uint, time_t *, bool);
extern bool parse_local_timestamp(const char *, time_t *);
extern char *format_local_timestamp(time_t, char *, size_t);
extern char *get_local_timestamp();
extern char *get_user_str(char *, size_t);
extern char *get_ip_addresses(char *, uint);
extern bool is_newer(char *, char *);
 
#define KEY_ALTF0 0x138
#define KEY_ALTF(n) (KEY_ALTF0 + (n)) /**< define alt function keys */
#define XTERM_256COLOR                /**< use xterm-256color terminfo for altkey bindings */
/**
    EXTENDED NCURSES KEYS
 
    Key code bindings are customarily defined in terminfo.
    xterm-256color tends to be the most complete, and indeed, it seems to
    work with Ghostty, Kitty, and Alacritty. If you want to use the
    altkey bindings, you may need to set your terminal's TERM environment
    variable to xterm-256color. Here's why:
 
    Ghostty, Kitty, and Alacritty all come with their own terminfo files:
 
    Ghostty     with xterm-ghostty,
    Kitty       with xterm-kitty, and
    Alacritty   with alacritty
 
    None of the three produced the correct extended altkey bindings when
    paired with the terminfo provided in their distribution, yet all
    three worked with xterm-256color.
 
    The extended altkeys were not defined in any of the terminfo files, not
    even xterm-256color. Yet, xterm-256color produced consistent keycode
    bindings with all three emulators. The standard key bindings, ins, delete,
    up, down arrows, etc., were the same for all three terminfos, and all
    three emulators produced the correct key bindings for those keys.
 
    The fact that xterm-256color produced consistent keycode bindings for the
    altkeys, while the other three terminfos did not, is likely due to the fact
    that xterm-256color is more widely used and has better support for extended
    key bindings, even if they are not explicitly defined in the terminfo file.
    It's possible that xterm-256color has some default behavior or fallback
    mechanism that allows it to recognize and produce key codes for the altkeys,
    while the other terminfos do not have such a mechanism in place. This could
    explain why xterm-256color produced consistent keycode bindings for the
    altkeys across all three emulators, while the other terminfos did not.
    @code
    mapped                  altkey   ncurses
    2nd fld - 1    name     binding  keycode
    ------------- --------- -------- -------
    kIC=\E[2;2~,  key_ins   \E[2;3~,   223
    kHOM=\E[1;2H, key_home  \E[1;3H,   21e
    kPRV=\E[5;2~, key_pgup  \E[5;3~,   232
    kDC=\E[3;2~,  key_del   \E[3;3~,   20e
    kEND=\E[1;2F, key_end   \E[1;3F,   219
    kNXT=\E[6;2~, key_pgdn  \E[6;3~,   22d
    kri=\E[1;2A,  key_up    \E[1;3A,   23d
    kind=\E[1;2B, key_down  \E[1;3B,   214
    kRIT=\E[1;2C, key_right \E[1;3C,   237
    kLFT=\E[1;2D, key_left  \E[1;3D,   228
    @endcode
 */
#if defined(XTERM_256COLOR)
#define KEY_ALTINS 0x223
#define KEY_ALTHOME 0x21e
#define KEY_ALTPGUP 0x232
#define KEY_ALTDEL 0x20e
#define KEY_ALTEND 0x219
#define KEY_ALTPGDN 0x22d
#define KEY_ALTUP 0x23d
#define KEY_ALTLEFT 0x228
#define KEY_ALTDOWN 0x214
#define KEY_ALTRIGHT 0x237
#elif defined(XTERM_GHOSTTY)
#define KEY_ALTINS 0x228
#define KEY_ALTHOME 0x223
#define KEY_ALTPGUP 0x237
#define KEY_ALTDEL 0x213
#define KEY_ALTEND 0x21e
#define KEY_ALTPGDN 0x232
#define KEY_ALTUP 0x242
#define KEY_ALTLEFT 0x22d
#define KEY_ALTDOWN 0x219
#define KEY_ALTRIGHT 0x23c
#endif
 
extern void write_cmenu_log(char *);
extern void write_cmenu_log_ts(char *);
extern void open_cmenu_log();
extern FILE *cmenu_log_fp;
extern uint n_lines; /**< number of lines in the terminal */
extern uint n_cols;  /**< number of columns in the terminal */
// extern uint lines;   current number of lines (may be less than n_lines if
// the terminal is resized)
// extern uint cols;    current number of columns (may be less than n_cols
// if the
//                       terminal is resized) extern int begx;
//                       beginning x coordinate of the terminal */
// extern uint begy;      beginning y coordinate of the terminal
//
#define MAXWIN 30 /**< maximum number of windows that can be created */
typedef unsigned char uchar;
 
extern void sig_prog_mode();
extern void sig_shell_mode();
extern char di_getch();
extern uint enter_option();
 
extern uint16_t win_attr; /**< Ncurses attributes for the current window, such as
                        color pair, bold, etc. */
// extern bool win_pair; /**< Flag to indicate whether the current window is
// part of a window pair */
extern uint
    mlines; /**< number of lines in the current window, which may be less than
               the total number of lines in the terminal if the window is
               resized or if multiple windows are being used. */
extern uint
    mcols; /**< number of columns in the current window, which may be less than
              the total number of columns in the terminal if the window is
              resized or if multiple windows are being used. */
extern uint
    mbegy; /**< beginning y coordinate of the current window, which can be used
              to determine the position of the window on the terminal screen. */
extern uint
    mbegx;             /**< beginning x coordinate of the current window, which can be used
                          to determine the position of the window on the terminal screen. */
extern uint mg_action; /**< action in progress, which can be used to keep track
                         of the current state of the program and determine how
                         to respond to user input or other events. */
extern uint mg_col;    /**< window column, which can be used to determine the
                         current column position in the window for displaying text
                         or other content. */
extern uint mg_line;   /**< window line, which can be used to determine the current line
                  position in the window for displaying text or other content. */
extern int stdin_fd;   /**< the file descriptor for the terminal, for error messages */
extern int stdout_fd;  /**< the file descriptor for the terminal, for error messages */
extern int stderr_fd;  /**< the file descriptor for the terminal, for error messages
                        and other output */
extern uint
    dbgfd;               /**< the file descriptor for debug output, for debugging purposes */
extern uint src_line;    /**< the line number of the source file being processed,
                           for error messages */
extern char *src_name;   /**< the name of the source file being processed, for
                            error messages */
extern char fn[MAXLEN];  /**< function name for error messages */
extern char em0[MAXLEN]; /**< error message string for error messages */
extern char em1[MAXLEN]; /**< error message string for error messages */
extern char em2[MAXLEN]; /**< error message string for error messages */
extern char em3[MAXLEN]; /**< error message string for error messages */
 
extern int exit_code; /**< the exit code for the program, for error messages and
                         other output */
 
extern void win_del();
extern void restore_wins();
extern void win_init_attrs();
extern void win_Toggle_Attrs();
extern int display_curses_keys();
extern void init_stdscr();
extern bool get_argp_doc_by_name(char *comment, const struct argp_option *, const char *);
 
typedef struct {
    char *s;
    size_t l;
} Arg;
typedef struct {
    Arg **v;
    size_t n;
} Argv;
typedef struct {
    char *s;
    size_t l;
} String;
typedef struct {
    wchar_t *s;
    size_t l;
} WCStr;
/** simple macro to convert a character to uppercase */
#define to_uppercase(c)
    if (c >= 'a' && c <= 'z')
    c -= ' '
/** @struct SIO
    @brief The SIO structure encapsulates various aspects of the terminal's
   state and configuration, including color management, file pointers, and
   terminal device information.
   @details The SIO structure serves as a central repository for all relevant
   information needed to manage the terminal's appearance and behavior
   effectively, allowing for a highly customizable and visually appealing
   terminal experience. The SIO structure includes fields for managing colors,
   gamma correction values, color codes for different colors, file pointers and
   descriptors for standard input/output/error and the terminal device, as well
   as counters and indices for color management. Additionally, it contains a
   field for storing the name of the terminal device. This comprehensive
   structure allows for efficient management of the terminal's state and
   configuration in a structured way. */
typedef struct {
    double red_gamma;      /**< red gamma correction value */
    double green_gamma;    /**< green gamma correction value */
    double blue_gamma;     /**< blue gamma correction value */
    double gray_gamma;     /**< gray gamma correction value */
    uint32_t black;        /**< black */
    uint32_t red;          /**< red */
    uint32_t green;        /**< green */
    uint32_t yellow;       /**< yellow */
    uint32_t blue;         /**< blue */
    uint32_t magenta;      /**< magenta */
    uint32_t cyan;         /**< cyan */
    uint32_t white;        /**< white */
    uint32_t orange;       /**< orange */
    uint32_t bblack;       /**< bold black */
    uint32_t bred;         /**< bold red */
    uint32_t bgreen;       /**< bold green */
    uint32_t byellow;      /**< bold yellow */
    uint32_t bblue;        /**< bold blue */
    uint32_t bmagenta;     /**< bold magenta */
    uint32_t bcyan;        /**< bold cyan */
    uint32_t bwhite;       /**< bold white */
    uint32_t borange;      /**< bold orange */
    uint32_t abg;          /**< background with alpha */
    uint32_t fg;           /**< foreground color */
    uint32_t bg;           /**< background color */
    uint32_t box_fg;       /**< box foreground */
    uint32_t box_bg;       /**< box background */
    uint32_t ind_fg;       /**< indicator foreground */
    uint32_t ind_bg;       /**< indicator background */
    uint32_t brackets_fg;  /**< brackets foreground */
    uint32_t brackets_bg;  /**< brackets background */
    uint32_t fill_char_fg; /**< fill character foreground */
    uint32_t fill_char_bg; /**< fill character background */
    uint32_t ln_fg;        /**< line number color index */
    uint32_t ln_bg;        /**< line number background index */
    uint32_t cmdln_fg;     /**< line number color index */
    uint32_t cmdln_bg;     /**< line number background index */
    uint32_t nt_fg;        /**< color code for normal text foreground */
    uint32_t nt_bg;        /**< color code for normal text background */
    uint32_t nt_rev_fg;    /**< normal text reverse foreground */
    uint32_t nt_rev_bg;    /**< normal text reverse background */
    uint32_t nt_hl_fg;     /**< normal text highlight foreground */
    uint32_t nt_hl_bg;     /**< normal text highlight background */
    uint32_t nt_hl_rev_fg; /**< normal text highlight reverse foreground */
    uint32_t nt_hl_rev_bg; /**< normal text highlight reverse background */
    uint32_t title_fg;     /**< title foreground */
    uint32_t title_bg;     /**< title background */
    uint32_t ran_fg;       /**< right angle foreground */
    uint32_t ran_bg;       /**< right angle background */
    FILE *stdin_fp;        /**< stdin stream pointer */
    FILE *stdout_fp;       /**< stdout stream pointer */
    FILE *stderr_fp;       /**< stderr stream pointer */
    FILE *tty_fp;          /**< terminal device stream pointer */
    int stdin_fd;          /**< stdin file descriptor */
    int stdout_fd;         /**< stdout file descriptor */
    int stderr_fd;         /**< stderr file descriptor */
    int tty_fd;            /**< terminal device file descriptor */
    uint clr_cnt;          /**< number of colors currently in use */
    uint clr_pair_cnt;     /**< number of color pairs currently in use */
    uint clr_idx;          /**< current color index */
    uint clr_pair_idx;     /**< current color pair index */
    char brackets[3];
    char fill_char[2];
    char border;           /**< Rounded, Single, Double, None */
    char tty_name[MAXLEN]; /**< name of the terminal device */
    ushort cp_default;     /**< default color pair index */
    ushort cp_fill_char;   /**< fill character color pair index */
    ushort cp_brackets;    /**< brackets color pair index */
    ushort cp_nt;          /**< normal text color pair index */
    ushort cp_nt_rev;      /**< reverse color pair index */
    ushort cp_nt_hl;       /**< highlight color pair index */
    ushort cp_nt_hl_rev;   /**< reverse highlight color pair index */
    ushort cp_box;         /**< box color pair index */
    ushort cp_ind;         /**< indicator color pair index */
    ushort cp_cmdln;       /**< command line color pair index */
    ushort cp_title;       /**< title color pair index */
    ushort cp_ln;          /**< line number color pair index */
    ushort cp_ran;         /**< right angle color pair index */
    ushort cp_chk;         /**< checkmark color pair index */
    ushort cp_bold;        /**< bold color pair index */
} SIO;
typedef struct {
    uint flin;
    uint fcol;
    uint flen;
    uint ff;
    char fill_char;
    bool cf_erase_remainder;
} CmField;
extern void destroy_curses();
extern int a_toi(char *, bool *);
extern bool chrep(char *, char, char);
extern char *rep_substring(const char *, const char *, const char *);
extern size_t strip_ansi(char *, char *);
extern bool strip_quotes(char *);
extern bool stripz_quotes(char *);
extern int str_to_args(char **, char *, uint);
extern int destroy_argv(uint argc, char **argv);
extern bool str_to_bool(const char *);
extern bool str_to_lower(char *);
extern bool str_to_upper(char *);
extern bool strnfill(char *, char, uint);
extern bool str_subc(char *, char *, char, char *, uint);
extern size_t strnz(char *, size_t);
extern size_t strnlf(char *, size_t);
extern char *strnz_dup(char *, size_t);
extern size_t ssnprintf(char *, size_t, const char *, ...);
extern size_t strnz__cpy(char *, const char *, size_t);
extern size_t strnz__cat(char *, const char *, size_t);
extern double str_to_double(char *);
extern size_t string_cpy(String *, const String *);
extern size_t string_cat(String *, const String *);
extern size_t string_ncat(String *, const String *, size_t);
extern size_t string_ncpy(String *, const String *, size_t);
extern size_t trim(char *);
extern size_t rtrim(char *);
extern String to_string(const char *);
extern String mk_string(size_t);
extern String free_string(String);
extern void apply_gamma(RGB *);
extern uint rgb_to_xterm256_idx(RGB *);
extern bool init_clr_palette(SIO *);
extern bool open_curses(SIO *);
extern uint rgb_clr_to_cube(uint);
extern uint rgb_to_curses_clr(RGB *);
extern RGB xterm256_idx_to_rgb(uint);
extern int fork_exec(char **);
extern int full_screen_fork_exec(char **);
extern int full_screen_shell(char *);
extern int shell(char *);
extern char errmsg[];
extern void get_rfc3339_s(char *, size_t);
extern int open_log(char *);
extern void write_log(char *);
extern void compile_chyron(Chyron *);
extern void display_chyron(UiSurface *, uint n, Chyron *, uint, uint);
extern int get_chyron_key(Chyron *, uint);
extern bool is_set_chyron_key(Chyron *, uint);
extern void set_chyron_key(Chyron *, uint, char *, uint);
extern void set_chyron_key_cb(Chyron *, uint, char *, uint, UiCell);
extern void unset_chyron_key(Chyron *, uint);
extern Chyron *new_chyron();
extern Chyron *destroy_chyron(Chyron *chyron);
extern void abend(int, char *);
extern void display_argv_error_msg(char *, char **);
extern int display_error(char *, char *, char *, char *);
extern int answer_yn(char *, char *, char *, char *);
extern int display_ok_message(char *);
extern int Perror(char *);
extern void user_end();
extern unsigned long a_to_ul(const char *);
extern size_t canonicalize_file_spec(char *);
extern bool construct_file_spec(char *, char *, char *, char *, char *, uint);
extern bool file_spec_path(char *, char *);
extern bool file_spec_name(char *, char *);
extern bool is_directory(const char *);
extern bool is_symlink_to_dir(const char *);
extern bool is_valid_regex(const char *);
extern bool dir_name(char *, char *);
extern bool base_name(char *, char *);
extern bool expand_tilde(char *, uint);
extern bool locate_file_in_path(char *, char *);
extern bool normalize_file_spec(char *);
extern bool trim_ext(char *, char *);
extern bool trim_path(char *);
extern bool verify_file(char *, uint);
extern bool verify_file_q(char *, uint);
extern bool verify_dir(char *, uint);
extern bool verify_dir_q(char *, uint);
extern bool verify_spec_arg(char *, char *, char *, char *, uint);
extern int wccp_to_str(wchar_t, uint8_t *);
extern char *fdname(int, char *);
extern char *stdio_names(char *, char *);
extern char *stdio_fdnames(char *, char *);
extern char stdio_names_str[4096];
extern void check_panels(uint);
extern int bare_box_new(uint, uint, uint, uint, char *);
extern int win2_box_new(uint, uint, uint, uint, char *);
extern void left_justify(char *s);
extern void right_justify(char *, uint);
 
extern bool is_valid_date(uint yyyy, uint mm, uint dd);
extern bool is_valid_time(uint hh, uint mm, uint ss);
extern void numeric(char *d, char *s);
extern int cf_accept(UiSurface *, uint w, char *, uint, uint, uint);
extern char *fill_field(char *, char *, char, uint);
extern int cm_surface_destroy(UiSurface *sfc);
extern wchar_t *mbstr_to_wcstr(const char *mb_str);
 
extern int border_draw(UiSurface *sfc);
extern int border_title(UiSurface *sfc, char *title);
extern int border_ysplit(UiSurface *, uint);
extern int border_ysplit_text(UiSurface *, char *, uint);
extern void mbc_to_wc(wchar_t wc[2], const char mbc);
extern void initialize_styles(SIO *);
extern int assign_chyron_win(Chyron *chyron, UiSurface *s, uint w, char *);
extern void initialize_cells(SIO *sio);
extern size_t codepoint_to_utf8(uint32_t codepoint, uint8_t *utf8);
 
#endif