layout.h File Reference

Two-column layout helpers for help text and option formatting. More...

Go to the source code of this file.

Macros
#define	LAYOUT_COLUMN_WIDTH   75
#define	LAYOUT_DESCRIPTION_START_COL   79
#define	LAYOUT_NARROW_TERMINAL_THRESHOLD   55

Functions
void	layout_print_wrapped_description (FILE *stream, const char *text, int indent_width, int term_width, int continuation_indent_extra)
	Print text with wrapping and proper indentation.
void	layout_print_two_column_row (FILE *stream, const char *first_column, const char *second_column, int first_col_len, int term_width, int continuation_indent_extra)
	Print two-column row with automatic wrapping.

Detailed Description

Two-column layout helpers for help text and option formatting.

Provides reusable functions for formatting two-column layouts with proper alignment and text wrapping. Used by both mode-level help and binary-level help.

Definition in file layout.h.

Macro Definition Documentation

LAYOUT_COLUMN_WIDTH

#define LAYOUT_COLUMN_WIDTH   75

Maximum width for first column before description moves to next line

Definition at line 19 of file layout.h.

LAYOUT_DESCRIPTION_START_COL

#define LAYOUT_DESCRIPTION_START_COL   79

Starting column for description text (column 79 = 2 spaces + 75 chars + 2 spacing)

Definition at line 22 of file layout.h.

LAYOUT_NARROW_TERMINAL_THRESHOLD

#define LAYOUT_NARROW_TERMINAL_THRESHOLD   55

Terminal width threshold for switching to vertical layout

Definition at line 25 of file layout.h.

Function Documentation

layout_print_two_column_row()

void layout_print_two_column_row	(	FILE *	stream,
		const char *	first_column,
		const char *	second_column,
		int	first_col_len,
		int	term_width,
		int	continuation_indent_extra
	)

Print two-column row with automatic wrapping.

Prints first column text, then second column description with proper alignment. If first column is too long (>45 chars), description moves to next line. Second column wraps at description start column.

Parameters

stream	Output file stream
first_column	Text for first column
second_column	Description for second column
first_col_len	Length of first column text (excluding ANSI codes)
term_width	Terminal width
continuation_indent_extra	Extra spaces for continuation lines (0 for none, 2 for options)

Definition at line 220 of file layout.c.

                                                                                {
  if (!stream || !first_column || !second_column)
    return;
 
  // Strip ANSI escape codes before calculating display width
  char *stripped = ansi_strip_escapes(first_column, strlen(first_column));
 
  // Calculate actual display width of first column (accounts for UTF-8, excluding ANSI codes)
  int display_width = utf8_display_width(stripped ? stripped : first_column);
  if (display_width < 0)
    display_width = first_col_len; // Fallback to provided value if available
 
  SAFE_FREE(stripped);
 
  // Use calculated first_col_len if provided (accounts for UTF-8 and ANSI codes),
  // otherwise default to 35. The provided width respects both colored text and UTF-8 characters.
  // Allow the first column to expand up to 60% of terminal width, but leave room for description.
  int fixed_first_col_width = (first_col_len > 0) ? first_col_len : 35;
  int max_first_col_width = (term_width * 6) / 10;
  if (max_first_col_width < 40)
    max_first_col_width = 40;
  if (fixed_first_col_width > max_first_col_width) {
    fixed_first_col_width = max_first_col_width;
  }
 
  // Second column starts after first column (with 2 spaces padding)
  // This allows descriptions to be quite wide for wrapping
  int second_col_start = 2 + fixed_first_col_width + 2;
 
  // At narrow terminal widths, force single-column layout
  bool force_single_column = (term_width <= 90);
 
  // Position where first column ends (including leading spaces)
  int first_col_end = 2 + display_width;
 
  // Check if first column fits within the fixed width
  bool fits_in_first_column_width = (display_width <= fixed_first_col_width);
 
  // If first column fits within its width and we're not forcing single column, try same-line layout
  if (fits_in_first_column_width && !force_single_column) {
    // Print first column
    fprintf(stream, "  %s", first_column);
 
    // Pad to second column start position
    int padding = second_col_start - first_col_end;
    if (padding > 0) {
      fprintf(stream, "%*s", padding, "");
    } else {
      fprintf(stream, " ");
    }
 
    // Print description with wrapping at second column position
    layout_print_wrapped_description(stream, second_column, second_col_start, term_width, continuation_indent_extra);
    fprintf(stream, "\n");
  } else if (force_single_column) {
    // Terminal too narrow, put description on next line with indent
    fprintf(stream, "  %s\n", first_column);
 
    // Only print description if it exists
    if (second_column && second_column[0] != '\0') {
      int description_indent = 4;
      for (int i = 0; i < description_indent; i++)
        fprintf(stream, " ");
 
      layout_print_wrapped_description(stream, second_column, description_indent, term_width,
                                       continuation_indent_extra);
      fprintf(stream, "\n");
    }
  } else {
    // First column overflows its fixed width - bump description to next line
    // Print first column as-is (it will overflow)
    fprintf(stream, "  %s\n", first_column);
 
    // Only print description if it exists
    if (second_column && second_column[0] != '\0') {
      // Print description on next line at second column position, with wide wrapping
      for (int i = 0; i < second_col_start; i++)
        fprintf(stream, " ");
      layout_print_wrapped_description(stream, second_column, second_col_start, term_width, continuation_indent_extra);
      fprintf(stream, "\n");
    }
  }
}

References ansi_strip_escapes(), display_width(), layout_print_wrapped_description(), SAFE_FREE, and utf8_display_width().

Referenced by options_config_print_options_sections_with_width(), options_config_print_usage(), and options_print_help_for_mode().

layout_print_wrapped_description()

void layout_print_wrapped_description	(	FILE *	stream,
		const char *	text,
		int	indent_width,
		int	term_width,
		int	continuation_indent_extra
	)

Print text with wrapping and proper indentation.

Wraps text to fit within terminal width, maintaining specified indentation for wrapped lines. Applies color formatting to metadata labels.

Parameters

stream	Output file stream
text	Plain text to print (may contain wrapping markers)
indent_width	Number of spaces to indent wrapped lines
term_width	Terminal width (0 for default 80)
continuation_indent_extra	Extra spaces to add to continuation lines (0 for none, 2 for options)

Definition at line 98 of file layout.c.

                                                                     {
  if (!text || !stream)
    return;
 
  // Default terminal width if not specified
  if (term_width <= 0)
    term_width = 80;
 
  // Available width for text after indentation, capped at 130 for readability
  // Account for continuation lines having extra indent, so reduce available width accordingly
  // This allows the description column itself to be up to 130 chars wide,
  // starting from indent_width, for a max total line of indent_width + 130 (first line)
  // or indent_width + continuation_indent_extra + 130 (continuation lines)
  int available_width = term_width - indent_width - continuation_indent_extra;
  if (available_width > 130)
    available_width = 130;
  if (available_width < 20)
    available_width = 20;
 
  const char *line_start = text;
  const char *last_space = NULL;
  const char *p = text;
  bool inside_metadata = false;
 
  while (*p) {
    // Check for explicit newline
    if (*p == '\n') {
      // Print everything up to the newline
      int text_len = p - line_start;
      if (text_len > 0) {
        char seg[BUFFER_SIZE_MEDIUM];
        SAFE_STRNCPY(seg, line_start, text_len + 1);
        layout_print_colored_segment(stream, seg);
      }
 
      fprintf(stream, "\n");
      if (*(p + 1)) {
        // Continuation lines get extra indent if specified
        int continuation_indent = indent_width + continuation_indent_extra;
        for (int i = 0; i < continuation_indent; i++)
          fprintf(stream, " ");
      }
      p++;
      line_start = p;
      last_space = NULL;
      inside_metadata = false;
      continue;
    }
 
    // Check for start of metadata blocks (must check before space tracking)
    // Use helper that accounts for ANSI codes in the metadata
    if (!inside_metadata && is_metadata_start(p)) {
      inside_metadata = true;
    }
 
    // Check for end of metadata blocks - always exit on )
    // We'll re-enter when we see the next metadata marker
    if (inside_metadata && *p == ')') {
      inside_metadata = false;
    }
 
    // Track spaces for word wrapping, including inside metadata blocks
    // Prefer breaks before metadata blocks by updating last_space even if we already have one
    if (*p == ' ') {
      const char *next = p + 1;
      while (*next == ' ')
        next++;
      // Track space as break point if it's before metadata or a normal space (not before parenthetical)
      if (is_metadata_start(next) || !last_space || *next != '(') {
        last_space = p;
      }
    }
 
    // Decode UTF-8 character length
    int char_bytes = utf8_next_char_bytes(p, strlen(p));
 
    if (char_bytes <= 0) {
      // Invalid UTF-8 or end of string, stop
      break;
    }
 
    // Advance to next character first
    p += char_bytes;
 
    // Calculate actual display width from line_start to current position (excluding ANSI codes)
    int actual_width = calculate_segment_display_width(line_start, p - line_start);
 
    // Check if we need to wrap
    if (actual_width >= available_width && last_space && last_space > line_start) {
      // Print text up to break point with colors applied
      int text_len = last_space - line_start;
      char seg[BUFFER_SIZE_MEDIUM];
      SAFE_STRNCPY(seg, line_start, text_len + 1);
      layout_print_colored_segment(stream, seg);
 
      fprintf(stream, "\n");
      // Continuation lines get extra indent if specified
      int continuation_indent = indent_width + continuation_indent_extra;
      for (int i = 0; i < continuation_indent; i++)
        fprintf(stream, " ");
 
      p = last_space + 1;
      line_start = p;
      last_space = NULL;
      continue;
    }
  }
 
  // Print remaining text
  if (p > line_start) {
    char seg[BUFFER_SIZE_MEDIUM];
    int text_len = p - line_start;
    SAFE_STRNCPY(seg, line_start, text_len + 1);
    layout_print_colored_segment(stream, seg);
  }
}

References BUFFER_SIZE_MEDIUM, SAFE_STRNCPY, and utf8_next_char_bytes().

Referenced by layout_print_two_column_row(), and options_print_help_for_mode().