@@@ tty cleanup

[mLib] / ui / ttyprogress.c

/* -*-c-*-
 *
 * Progress bars for terminal programs
 *
 * (c) 2025 Straylight/Edgeware
 */

/*----- Licensing notice --------------------------------------------------*
 *
 * This file is part of the mLib utilities library.
 *
 * mLib is free software: you can redistribute it and/or modify it under
 * the terms of the GNU Library General Public License as published by
 * the Free Software Foundation; either version 2 of the License, or (at
 * your option) any later version.
 *
 * mLib is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
 * License for more details.
 *
 * You should have received a copy of the GNU Library General Public
 * License along with mLib.  If not, write to the Free Software
 * Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307,
 * USA.
 */

/*----- Header files ------------------------------------------------------*/

#define _XOPEN_SOURCE
#include "config.h"

#include <assert.h>
#include <limits.h>
#include <stdarg.h>
#include <stdlib.h>
#include <string.h>
#include <wchar.h>

#include "alloc.h"
#include "arena.h"
#include "dstr.h"
#include "gprintf.h"
#include "growbuf.h"
#include "tty.h"
#include "ttycolour.h"
#include "ttyprogress.h"

/*----- Main code ---------------------------------------------------------*/

int ttyprogress_init(struct ttyprogress *progress, struct tty *tty)
{
#define GENATTR(want, attrs, fgspc, fgcol, bgspc, bgcol)                \
  { (want), (want),                                                     \
    { ((fgspc) << TTAF_FGSPCSHIFT) |                                    \
      ((bgspc) << TTAF_BGSPCSHIFT) | (attrs),                           \
      0, (fgcol), (bgcol) } }

#define FGBG(want, attrs, fgcol, bgcol)                                 \
  GENATTR(want | TTACF_FG | TTACF_BG, attrs,                            \
          TTCSPC_1BPCBR, TTCOL_##fgcol, TTCSPC_1BPCBR, TTCOL_##bgcol)
#define ATTR(want, attrs)                                               \
  GENATTR(want, attrs, TTCSPC_NONE, 0, TTCSPC_NONE, 0)

#define BOLD (TTWT_BOLD << TTAF_WTSHIFT)

  static const struct tty_attrlist
    bbar_attrs[] = { FGBG(0, 0, BLK, GRN), ATTR(0, TTAF_INVV) },
    ebar_attrs[] = { FGBG(0, 0, BLK, YLW), TTY_ATTRLIST_CLEAR },
    note_attrs[] = { FGBG(0, BOLD, WHT, BLU), ATTR(0, TTAF_INVV | BOLD) },
    warn_attrs[] = { FGBG(0, BOLD, WHT, MGN), ATTR(0, TTAF_INVV | BOLD) },
    err_attrs[] = { FGBG(0, BOLD, WHT, RED), ATTR(0, TTAF_INVV | BOLD) };
  static const struct ttycolour_style hltab[] =
    TTYCOLOUR_INITTAB(TTYPROGRESS_HIGHLIGHTS);

#undef GENATTR
#undef FGBG
#undef ATTR
#undef BOLD

  /* Clear the progress state. */
  progress->tty = tty;
  progress->items = progress->end_item = 0;
  progress->nitems = 0; progress->last_lines = 0;
  progress->line.a = arena_global; dstr_create(&progress->line.t);
  progress->line.p = 0; progress->line.sz = 0;
  progress->tv_update.tv_sec = 0; progress->tv_update.tv_usec = 0;

  /* Check that the terminal is sufficiently cromulent. */
  if (!tty || !(tty->ocaps&TTCF_RELMV) || !(tty->ocaps&TTCF_EREOD))
    { progress->tty = 0; return (-1); }

  /* Configure the highlight attributes. */
  ttycolour_config(progress->attr,
                   "MLIB_TTYPROGRESS_COLOURS", TCIF_GETENV, tty, hltab);

  /* All done. */
  return (0);
}

void ttyprogress_free(struct ttyprogress *progress)
{
  dstr_destroy(&progress->line.t);
  x_free(progress->line.a, progress->line.p);
}

/*----- Active item list maintenance --------------------------------------*/

int ttyprogress_additem(struct ttyprogress *progress,
                     struct ttyprogress_item *item)
{
  if (item->parent) return (-1);
  item->prev = progress->end_item; item->next = 0;
  if (progress->end_item) progress->end_item->next = item;
  else progress->items = item;
  progress->end_item = item; item->parent = progress;
  progress->nitems++;

  return (0);
}

int ttyprogress_removeitem(struct ttyprogress *progress,
                        struct ttyprogress_item *item)
{
  if (!item->parent) return (-1);
  if (item->next) item->next->prev = item->prev;
  else (progress->end_item) = item->prev;
  if (item->prev) item->prev->next = item->next;
  else (progress->items) = item->next;
  progress->nitems--; item->parent = 0;

  return (0);
}

/*----- Render state lifecycle --------------------------------------------*/

static void setup_render_state(struct ttyprogress *progress,
                               struct ttyprogress_render *render)
{
  struct tty *tty = progress->tty;

  /* Clear everything. */
  render->tty = tty;

  /* Update the current terminal size. */
  tty_resized(tty);

  /* We'll render progress bars with colour or standout if we can; otherwise,
   * we'll just insert a `|' in the right place, but that takes up an extra
   * column, so deduct one from the terminal's width to compensate.  Deduct
   * another one if the terminal doesn't let us leave the cursor in the final
   * column without scrolling or wrapping.
   */
  render->width = tty->wd;
  if (render->width && !(tty->acaps&(TTCF_MMARG | TTMF_AUTOM)))
    render->width--;
  if (render->width && !(tty->acaps&(TTACF_BG | TTACF_INVV)))
    render->width--;

  /* Borrow the line buffer and highlight table from the master state. */
  render->line = &progress->line;
  render->attr = progress->attr;
}

/*----- Measuring string widths -------------------------------------------*/

#if defined(HAVE_MBRTOWC) && defined(HAVE_WCWIDTH)

#include <wchar.h>

#define CONV_MORE ((size_t)-2)
#define CONV_BAD ((size_t)-1)

struct measure {
  mbstate_t ps;                         /* conversion state */
  const char *p; size_t i, sz;          /* input string, and cursor */
  unsigned wd;                          /* width accumulated so far */
};

static void init_measure(struct measure *m, const char *p, size_t sz)
        /* Set up M to measure the SZ-byte string P. */
{
  m->p = p; m->sz = sz; m->i = 0; m->wd = 0;
  memset(&m->ps, 0, sizeof(m->ps));
}

static int advance_measure(struct measure *m)
        /* Advance the measurement in M by one character.  Return zero if the
         * end of the string has been reached, or nonzero if there is more to
         * come.
         */
{
  wchar_t wch;
  unsigned chwd;
  size_t n;

  /* Determine the next character's code WCH, the length N of its encoding in
   * P in bytes, and the character's width CHWD in columns.
   */
  n = mbrtowc(&wch, m->p + m->i, m->sz - m->i, &m->ps);
  if (!n) { chwd = 0; n = m->sz - m->i; }
  else if (n == CONV_MORE) { chwd = 2; n = m->sz - m->i; }
  else if (n == CONV_BAD) { chwd = 2; n = 1; }
  else chwd = wcwidth(wch);

  /* Advance the state. */
  m->i += n; m->wd += chwd;

  /* Report whether there's more to come. */
  return (m->i < m->sz);
}

static unsigned string_width(const char *p, size_t sz)
        /* Return the width of the SZ-byte string P, in terminal columns. */
{
  struct measure m;

  init_measure(&m, p, sz);
  while (advance_measure(&m));
  return (m.wd);
}

static size_t split_string(const char *p, size_t sz,
                           unsigned *wd_out, unsigned maxwd)
        /* Return the size, in bytes, of the shortest prefix of the SZ-byte
         * string P which is no less than MAXWD columns wide, or SZ if it's
         * just too short.  Store the actual width in *WD_OUT.
         */
{
  struct measure m;
  size_t i; unsigned wd;
  int more;

  init_measure(&m, p, sz);

  /* Advance until we're past the bound. */
  for (;;) {
    if (!advance_measure(&m)) { *wd_out = m.wd; return (sz); }
    if (m.wd >= maxwd) break;
  }

  /* Now /continue/ advancing past zero-width characters until we find
   * something that wasn't zero-width.  These might be combining accents or
   * somesuch, and leaving them off would definitely be wrong.
   */
  wd = m.wd; i = m.i;
  for (;;) {
    more = advance_measure(&m);
    if (m.wd > wd) break;
    i = m.i;
    if (!more) break;
  }

  /* All done. */
  *wd_out = wd; return (i);
}

#else

static unsigned string_width(const char *p, size_t sz) { return (sz); }

static size_t split_string(const char *p, size_t sz,
                           unsigned *wd_out, unsigned maxwd)
{
  unsigned wd;

  if (sz <= maxwd) wd = sz;
  else wd = maxwd;
  *wd_out = wd; return (wd);
}

#endif

/*----- Output buffer handling --------------------------------------------*/

static void grow_linebuf(struct ttyprogress_render *render, size_t want)
        /* Extend the line buffer in RENDER so that it's at least WANT bytes
         * long.  Shuffle the accumulated left and right material in the
         * buffer as necessary.
         */
{
  struct ttyprogress_buffer *line = render->line;
  char *newbuf; size_t newsz;

  /* Return if there's already enough space. */
  if (want <= line->sz) return;

  /* Work out how much space to allocate.  The initial size is a rough guess
   * based on the size of UTF-8 encoded characters, though it's not an upper
   * bound because many characters have zero width.  Double the buffer size
   * if it's too small.  Sneakily insert a terminating zero byte just in
   * case.
   */
  newsz = line->sz;
  GROWBUF_SIZE(size_t, newsz, want, 4*render->width + 1, 1);
  newbuf = x_alloc(line->a, newsz + 1);
  newbuf[newsz] = 0;

  /* Copy the left and right strings into the new buffer. */
  if (render->leftsz)
    memcpy(newbuf, line->p, render->leftsz);
  if (render->rightsz)
    memcpy(newbuf + newsz - render->rightsz,
           line->p + line->sz - render->rightsz,
           render->rightsz);

  /* Free the old buffer and remember the new one. */
  x_free(line->a, line->p); line->p = newbuf; line->sz = newsz;
}

enum { LEFT, RIGHT, STOP };

static int putstr(struct ttyprogress_render *render, unsigned side,
                  const char *p, size_t n)
        /* Add the N-byte string P to SIDE of the line buffer in RENDER.
         * Return 0 on success or -1 if this fails for any reason.
         */
{
  unsigned newwd = string_width(p, n);
  size_t want;

  if (newwd >= render->width - render->leftwd - render->rightwd) return (-1);
  want = render->leftsz + render->rightsz + n;
  if (want > render->line->sz) grow_linebuf(render, want);
  switch (side) {
    case LEFT:
      memcpy(render->line->p + render->leftsz, p, n);
      render->leftsz += n; render->leftwd += newwd;
      break;
    case RIGHT:
      memcpy(render->line->p + render->line->sz - render->rightsz - n, p, n);
      render->rightsz += n; render->rightwd += newwd;
      break;
    default:
      assert(0);
  }
  return (0);
}

int ttyprogress_vputleft(struct ttyprogress_render *render,
                      const char *fmt, va_list *ap)
{
  dstr *t = &render->line->t;

  DRESET(t); dstr_vputf(t, fmt, ap);
  return (putstr(render, LEFT, t->buf, t->len));
}

int ttyprogress_vputright(struct ttyprogress_render *render,
                       const char *fmt, va_list *ap)
{
  dstr *t = &render->line->t;

  DRESET(t); dstr_vputf(t, fmt, ap);
  return (putstr(render, RIGHT, t->buf, t->len));
}

int ttyprogress_putleft(struct ttyprogress_render *render,
                        const char *fmt, ...)
{
  va_list ap;
  int rc;

  va_start(ap, fmt); rc = ttyprogress_vputleft(render, fmt, &ap); va_end(ap);
  return (rc);
}

int ttyprogress_putright(struct ttyprogress_render *render,
                      const char *fmt, ...)
{
  va_list ap;
  int rc;

  va_start(ap, fmt); rc = ttyprogress_vputright(render, fmt, &ap); va_end(ap);
  return (rc);
}

/*----- Maintaining the progress display ----------------------------------*/

#define CLRF_ALL 1u                     /* clear everything */
static void clear_progress(struct ttyprogress *progress, unsigned f)
        /* Clear the current progress display maintained by PROGRESS.
         *
         * If `CLRF_ALL' is set in F, then clear the entire display.
         * Otherwise, clear the bottom few lines if there are now fewer
         * progress items than there were last time we rendered the display,
         * and leave the cursor at the start of the top line ready to
         * overwrite it.
         */
{
  struct tty *tty = progress->tty;
  int ndel, nleave;

  if (progress->last_lines) {

    /* Decide how many lines to delete.  Set `ndel' to the number of lines
     * that will be entirely erased, and `nleave' to the number that we'll
     * leave.
     */
    if (f&CLRF_ALL)
      { ndel = progress->last_lines; nleave = 0; }
    else {
      if (progress->nitems >= progress->last_lines) ndel = 0;
      else ndel = progress->last_lines - progress->nitems;
      nleave = progress->last_lines - ndel;
    }

    /* Now actually do the clearing.  Remember that the cursor is still on
     * the last line.
     */
    if (!ndel)
      tty_move(tty, TTOF_YCUR | TTOF_XHOME, 1 - nleave, 0);
    else {
      tty_move(tty, TTOF_YCUR | TTOF_XHOME, 1 - ndel, 0);
      tty_erase(tty, TTEF_DSP | TTEF_END);
      tty_move(tty, TTORG_CUR, -nleave, 0);
    }
  }

  /* Remember that we're now at the top of the display. */
  progress->last_lines = 0;
}

int ttyprogress_clear(struct ttyprogress *progress)
{
  if (!progress->tty) return (-1);
  clear_progress(progress, CLRF_ALL);
  return (0);
}

int ttyprogress_update(struct ttyprogress *progress)
{
  struct ttyprogress_render render;
  struct ttyprogress_item *item;
  struct tty *tty = progress->tty;
  struct tty_state save;
  unsigned f = 0;
#define f_any 1u

  if (!tty) return (-1);

  setup_render_state(progress, &render);
  clear_progress(progress, 0);
  save = tty->st;

  for (item = progress->items; item; item = item->next) {
    if (f&f_any) tty_move(tty, TTOF_YCUR | TTOF_XHOME, 1, 0);
    render.leftsz = render.rightsz = 0;
    render.leftwd = render.rightwd = 0;
    item->render(item, &render); progress->last_lines++; f |= f_any;
    if (progress->last_lines > tty->ht) break;
  }
  tty_restore(tty, &save);
  fflush(tty->fpout);
  return (0);

#undef f_any
}

/*----- Rendering progress bars -------------------------------------------*/

/* The basic problem here is to render text, formed of several pieces, to the
 * terminal, placing some marker in the middle of it to indicate how much
 * progress has been made.  This marker might be a colour change, switching
 * off reverse-video mode, or a `|' character.
 */

struct bar {
        /* State to track progress through the output of a progress bar, so
         * that we insert the marker in the right place.
         *
         * This is a little state machine.  We remember the current column
         * position, the current state, and the column at which we'll next
         * change state.
         */

  const struct ttyprogress_render *render; /* render state */
  unsigned pos, nextpos, state;         /* as described */
};

static void advance_bar_state(struct bar *bar)
        /* If we've reached the column position for the next state change
         * then arrange to do whatever it is we're meant to do, and update
         * for the next change.
         */
{
  const struct ttyprogress_render *render = bar->render;
  struct tty *tty = render->tty;
  size_t here = bar->nextpos;

  while (bar->nextpos <= here) {
    switch (bar->state) {
      case LEFT:
        if (!(tty->acaps&(TTACF_BG | TTACF_INVV))) putc('|', tty->fpout);
        else tty_setattr(tty, &render->attr[TPHL_EBAR]);
        bar->state = RIGHT; bar->nextpos = render->width;
        break;
      case RIGHT:
        bar->state = STOP; bar->nextpos = UINT_MAX;
        break;
    }
  }
}

/* Little utility to output a chunk of text. */
static void put_str(FILE *fp, const char *p, size_t sz)
  { while (sz--) putc(*p++, fp); }

static void put_spc(struct tty *tty, unsigned n)
{
  if (!(~tty->ocaps&(TTCF_RELMV | TTCF_BGER | TTCF_ERCH)))
    { tty_erch(tty, n); tty_move(tty, TTORG_CUR, 0, n); }
  else
    tty_repeat(tty, ' ', n);
}

static void put_barstr(struct bar *bar, const char *p, size_t sz)
        /* Output the SZ-byte string P, driving the state machine BAR as we
         * go.
         */
{
  FILE *fp = bar->render->tty->fpout;
  unsigned wd;
  size_t n;

  for (;;) {
    /* Main loop.  Determine how much space there is to the next state
     * change, cut off that amount of space from the string, and advance.
     */

    n = split_string(p, sz, &wd, bar->nextpos - bar->pos);
    if (n == sz && wd < bar->nextpos - bar->pos) break;
    put_str(fp, p, n); bar->pos += wd; advance_bar_state(bar);
    p += n; sz -= n;
  }

  /* Write out the rest of the string, and update the position.  We know that
   * this won't reach the next transition.
   */
  put_str(fp, p, sz); bar->pos += wd;
}

static void put_barspc(struct bar *bar, unsigned n)
        /* Output N spaces, driving the state machine BAR as we go. */
{
  struct tty *tty = bar->render->tty;
  unsigned step;

  for (;;) {
    step = bar->nextpos - bar->pos;
    if (n < step) break;
    put_spc(tty, step); bar->pos += step; n -= step;
    advance_bar_state(bar);
  }
  put_spc(tty, n); bar->pos += n;
}

int ttyprogress_showbar(struct ttyprogress_render *render, double frac)
{
  struct tty *tty = render->tty;
  const struct ttyprogress_buffer *line = render->line;
  struct bar bar;

  /* If there's no terminal, then there's nothing to do. */
  if (!tty) return (-1);

  /* Clamp the fraction.  Rounding errors in the caller's calculation might
   * legitimately leave it slightly out of bounds.  The sense of the
   * comparisons also catches QNaNs, which are silently squashed to zero so
   * as to prevent anything untoward happening when we convert to integer
   * arithmetic below.
   */
  frac = !(frac >= 0.0) ? 0.0 : !(frac <= 1.0) ? 1.0 : frac;

  /* Set up the render state, with a transition where the bar should end. */
  bar.render = render; bar.pos = 0; bar.nextpos = frac*render->width + 0.5;

  /* Set the initial state for the render. */
  if (tty->acaps&(TTACF_BG | TTACF_INVV)) {
    /* We have highlighting.  If we have made only negligible progress then
     * advance the state machine immediately, which will set the correct
     * highlighting; otherwise, set the beginning-of-bar highlight.
     */

    bar.state = LEFT;
    if (bar.nextpos) tty_setattr(tty, &render->attr[TPHL_BBAR]);
    else advance_bar_state(&bar);
  } else {
    /* Nothing fancy.  We'll write `|' at the right place. */

    bar.state = LEFT;
  }

  /* Write the left string, spaces to fill the gap, and the right string. */
  put_barstr(&bar, line->p, render->leftsz);
  put_barspc(&bar, render->width - render->leftwd - render->rightwd);
  put_barstr(&bar, line->p + line->sz - render->rightsz, render->rightsz);

  /* All done. */
  return (0);
}

int ttyprogress_shownotice(struct ttyprogress_render *render,
                           const struct tty_attr *attr)
{
  struct tty *tty = render->tty;
  const struct ttyprogress_buffer *line = render->line;

  /* If there's no terminal, then there's nothing to do. */
  if (!tty->fpout) return (-1);

  /* Set the attributes. */
  tty_setattr(tty, attr);

  /* Print the left and right strings. */
  put_str(tty->fpout, line->p, render->leftsz);
  put_spc(tty, render->width - render->leftwd - render->rightwd);
  put_str(tty->fpout, line->p + line->sz - render->rightsz, render->rightsz);

  /* All done. */
  return (0);
}

/*----- That's all, folks -------------------------------------------------*/