reader.h File Reference

Read ANSI ASCII frames from file descriptor, chunked by height. More...

Go to the source code of this file.

Functions
asciichat_error_t	terminal_fd_reader_create (int fd, int frame_height, terminal_fd_reader_t **out)
	Create a terminal FD reader from a file descriptor.
asciichat_error_t	terminal_fd_reader_next (terminal_fd_reader_t *reader, char **out_frame)
	Read next frame from file descriptor.
void	terminal_fd_reader_destroy (terminal_fd_reader_t *reader)
	Destroy terminal FD reader.

Detailed Description

Read ANSI ASCII frames from file descriptor, chunked by height.

Reads ASCII frames from any file descriptor (stdin, file, pipe) and chunks them by height (number of lines) as specified. Supports reading ANSI-colored ASCII art frames in batches.

Author

Zachary Fogg me@zf.nosp@m.o.gg

Date

February 2026

Definition in file reader.h.

Function Documentation

terminal_fd_reader_create()

asciichat_error_t terminal_fd_reader_create	(	int	fd,
		int	frame_height,
		terminal_fd_reader_t **	out )

Create a terminal FD reader from a file descriptor.

Parameters

fd	File descriptor to read from (e.g., STDIN_FILENO, open file)
frame_height	Number of lines per frame (required - used for frame boundaries)
out	Pointer to store reader context

Returns

ASCIICHAT_OK on success

Width is auto-detected from the first frame's line length.

Definition at line 33 of file reader.c.

                                                                                                  {
  if (fd < 0 || frame_height <= 0 || !out) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid reader parameters: fd=%d, height=%d, output=%p", fd, frame_height,
                     (void *)out);
  }
 
  FILE *fp = platform_fdopen("terminal_fd_reader", fd, "r");
  if (!fp) {
    return SET_ERRNO_SYS(ERROR_INVALID_PARAM, "fdopen failed for FD %d", fd);
  }
 
  terminal_fd_reader_t *reader = SAFE_CALLOC(1, sizeof(*reader), terminal_fd_reader_t *);
  reader->fp = fp;
  reader->frame_height = frame_height;
  reader->frame_width = 0; // Will be detected from first frame
  reader->line_buffer = SAFE_MALLOC(LINE_BUFFER_SIZE, char *);
  reader->line_buffer_size = LINE_BUFFER_SIZE;
  reader->eof_reached = false;
  reader->first_frame_processed = false;
 
  log_debug("created with fd=%d, frame height %d (width auto-detect)", fd, frame_height);
  *out = reader;
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, terminal_fd_reader_s::eof_reached, ERROR_INVALID_PARAM, terminal_fd_reader_s::first_frame_processed, terminal_fd_reader_s::fp, terminal_fd_reader_s::frame_height, terminal_fd_reader_s::frame_width, terminal_fd_reader_s::line_buffer, LINE_BUFFER_SIZE, terminal_fd_reader_s::line_buffer_size, log_debug, out, SAFE_CALLOC, SAFE_MALLOC, SET_ERRNO, and SET_ERRNO_SYS.

terminal_fd_reader_destroy()

void terminal_fd_reader_destroy

(

terminal_fd_reader_t *

reader

)

Destroy terminal FD reader.

Parameters

reader

Reader context to destroy

Definition at line 148 of file reader.c.

                                                              {
  if (!reader)
    return;
  if (reader->fp) {
    fclose(reader->fp);
    reader->fp = NULL;
  }
  SAFE_FREE(reader->line_buffer);
  SAFE_FREE(reader);
}

References terminal_fd_reader_s::fp, terminal_fd_reader_s::line_buffer, and SAFE_FREE.

terminal_fd_reader_next()

asciichat_error_t terminal_fd_reader_next	(	terminal_fd_reader_t *	reader,
		char **	out_frame )

Read next frame from file descriptor.

Reads frame_height lines from the FD and returns them as a single frame string. Returns NULL in out_frame when EOF is reached.

Parameters

reader	Reader context
out_frame	Pointer to store frame data (NULL when EOF, must free with SAFE_FREE)

Returns

ASCIICHAT_OK on success (including EOF)

Definition at line 58 of file reader.c.

                                                                                          {
  if (!reader || !out_frame) {
    return SET_ERRNO(ERROR_INVALID_PARAM, "Invalid parameters");
  }
 
  if (reader->eof_reached) {
    *out_frame = NULL;
    return ASCIICHAT_OK; // EOF, but no error
  }
 
  // Allocate buffer for complete frame (frame_height lines)
  // Estimate: 16KB per line should be enough for ANSI + ASCII
  size_t frame_capacity = reader->frame_height * LINE_BUFFER_SIZE;
  char *frame_data = SAFE_MALLOC(frame_capacity, char *);
  size_t frame_pos = 0;
 
  // Read exactly frame_height lines from FD
  for (int line_num = 0; line_num < reader->frame_height; line_num++) {
    // Read one line from FD
    char *line = fgets(reader->line_buffer, (int)reader->line_buffer_size, reader->fp);
 
    if (!line) {
      // EOF reached
      reader->eof_reached = true;
 
      // If we read some lines but not a complete frame, that's ok - return partial
      if (frame_pos > 0) {
        log_debug("EOF reached after %d/%d lines, returning partial frame", line_num, reader->frame_height);
        // Remove trailing newline from last line if present
        if (frame_pos > 0 && frame_data[frame_pos - 1] == '\n') {
          frame_pos--;
        }
        frame_data[frame_pos] = '\0';
        *out_frame = frame_data;
        return ASCIICHAT_OK;
      }
 
      SAFE_FREE(frame_data);
      *out_frame = NULL;
      return ASCIICHAT_OK; // EOF
    }
 
    // Append line to frame
    size_t line_len = strlen(line);
    if (frame_pos + line_len >= frame_capacity) {
      log_warn("frame buffer overflow, line %d too large", line_num);
      // Realloc and continue
      frame_capacity *= 2;
      char *new_frame = SAFE_MALLOC(frame_capacity, char *);
      memcpy(new_frame, frame_data, frame_pos);
      SAFE_FREE(frame_data);
      frame_data = new_frame;
    }
 
    memcpy(frame_data + frame_pos, line, line_len);
    frame_pos += line_len;
  }
 
  // Remove trailing newline from last line (we'll add it back in display)
  if (frame_pos > 0 && frame_data[frame_pos - 1] == '\n') {
    frame_pos--;
  }
  frame_data[frame_pos] = '\0';
 
  // Detect frame width from first frame (count visible chars in first line)
  if (!reader->first_frame_processed && frame_pos > 0) {
    reader->first_frame_processed = true;
 
    // Find first line by looking for newline
    char *first_newline = strchr(frame_data, '\n');
    if (first_newline) {
      // Null-terminate first line temporarily for width calculation
      char saved_char = *first_newline;
      *first_newline = '\0';
      reader->frame_width = display_width(frame_data);
      *first_newline = saved_char; // Restore
    } else {
      // Only one line in frame, use it for width
      reader->frame_width = display_width(frame_data);
    }
 
    log_info("detected frame width %d from first frame", reader->frame_width);
  }
 
  *out_frame = frame_data;
  log_debug_every(NS_PER_SEC_INT, "read frame (%zu bytes, %dx%d)", frame_pos, reader->frame_width,
                  reader->frame_height);
  return ASCIICHAT_OK;
}

References ASCIICHAT_OK, display_width(), terminal_fd_reader_s::eof_reached, ERROR_INVALID_PARAM, terminal_fd_reader_s::first_frame_processed, terminal_fd_reader_s::fp, terminal_fd_reader_s::frame_height, terminal_fd_reader_s::frame_width, terminal_fd_reader_s::line_buffer, LINE_BUFFER_SIZE, terminal_fd_reader_s::line_buffer_size, log_debug, log_debug_every, log_info, log_warn, NS_PER_SEC_INT, SAFE_FREE, SAFE_MALLOC, and SET_ERRNO.