FEDFORM(1)

NAME
fedform - terminal form manager for shell scripts

SYNOPSIS
fedform definition [options]

DESCRIPTION
fedform is a curses-based terminal form manager that hosts multiple input fields (line, area, mask, list, check, radio) on a shared screen within a single process. It reads a form definition, renders labels and fields, manages navigation between fields, and on form-level exit returns all field values.

Field engines are imported from fedline(1), fedarea(1), fedmask(1), fedlist(1), fedcheck(1), and fedradio(1) as library calls. No subprocesses are spawned for individual fields.

ARGUMENTS

definition
    Path to a form definition file, or - for stdin.

OPTIONS

-j, --json
    Parse the definition as JSON (default: line-oriented format).

-v, --values FILE
    Load initial field values from a JSON file (object keyed by field name). Use - for stdin. Cannot both be stdin if the definition is also stdin.

-o, --output FORMAT
    Output format: kv (key=value, default), json (JSON object), or shell (eval-safe single-quoted assignments).

-q, --quiet
    Suppress the exit reason mnemonic on stderr.

-f, --focus FIELD
    Field name to receive initial focus (default: first in tab order).

-e, --exit KEYS
    Comma-separated form-level exit key mnemonics. Default: ESC,F10.

--no-restore
    Keep the form on the main screen on exit so its final layout persists. By default fedform uses the terminal's alternate screen and restores the caller's screen on exit.

-h  Print brief usage and exit.

--help
    Print full help text and exit.

--version
    Print version and copyright information and exit.

TERMINAL
fedform owns the whole screen: it clears the screen on start and lays out all fields. By default it runs on the terminal's alternate screen and restores the caller's screen on exit. With --no-restore it stays on the main screen and its final layout persists.

This differs from the standalone field tools (fedline(1), fedarea(1), fedmask(1), fedlist(1), fedcheck(1), fedradio(1)), which draw inline over existing content and never clear or restore the screen.

While the form is active it runs in raw mode, so Ctrl+C does not interrupt it and flow-control keys (Ctrl+S/Ctrl+Q) are inert; leave the form with a configured exit key.

DEFINITION FORMAT

  Line-Oriented (default)
Each line defines one element. Blank lines and lines starting with # are ignored.

@<row>,<col> SAY "<text>" [COLOR fg,bg]
@<row>,<col> GET <name> LINE <width> <maxlen> [options]
@<row>,<col> GET <name> AREA <width> <rows> <maxlen> <v_scroll> <word_wrap> [options]
@<row>,<col> GET <name> MASK <mask_spec> [options]
@<row>,<col> GET <name> LIST <width> <rows> [options]
@<row>,<col> GET <name> CHECK <width> [options]
@<row>,<col> GET <name> RADIO <width> [options]

Field options: -v text, -f char, -i a|b|c, --items-file path, -c start|end, -m ins|ovr, -r | REVERSE, LOCKED, COLOR fg,bg, FOCUS fg,bg, SELECT fg,bg, LOCKED fg,bg, --required, --range MIN:MAX, --in v1|v2, --regex PATTERN, TAB n.

  Form-Level DEF

Without an @ prefix:
DEF SAY    fg,bg
DEF COLOR  fg,bg
DEF FOCUS  fg,bg
DEF SELECT fg,bg
DEF LOCKED fg,bg
DEF REVERSE fg,bg
DEF CLS    fg,bg

Per-field options override DEF values.

  Form-Level Commands

Lines without an @ prefix. Commands before the first @ run as pre-form actions; commands after the last @ run as post-form actions.

CLS [fg,bg], CLEAR [fg,bg]
    Clear the terminal, optionally setting the background color.

PUSH
    Save the current cursor position.

POP Restore the last pushed cursor position.

CURSOR row,col
    Move the terminal cursor without rendering.

  Color Tokens

ANSI names with optional bright- prefix, plus default: black, red, green, yellow, blue, magenta, cyan, white, bright-black, bright-red, ..., bright-white. Spec is fg,bg.

  Locked Fields

LOCKED (no fg,bg) marks a field read-only. Locked fields are skipped during Tab, Shift-Tab, spatial, and PgUp/PgDn navigation, and render in the LOCKED color.

  Scroll Indicators

LINE/MASK draw < and > arrows at the edges when content scrolls horizontally (only when width ≥ 5). AREA draws a vertical scrollbar (| track, # thumb) in the rightmost column when wrapped content exceeds the visible rows (only when rows ≥ 3).

  AREA Inactive Display

When focus moves away from an AREA field, its inactive render starts from line 1 (vy = 0). Editing resumes from the configured initial cursor on re-entry.

  JSON (with -j)
Top-level keys: elements (required), exit_keys (optional), focus (optional), def (optional defaults object: keys say, color, focus, select, locked, reverse, cls), pre_commands (optional array), post_commands (optional array). Element types: say, line, area, mask, list, check, radio. Per-element color keys: color, focus_color, select_color, locked_color. Per-element locked boolean marks a field locked.

NAVIGATION
Key | Action
Tab | Next field in tab order (wraps)
Shift+Tab | Previous field in tab order (wraps)
Enter | Next field (except in AREA, where it inserts newline)
Up Arrow | Nearest field above by screen position
Down Arrow | Nearest field below by screen position
PgUp | Nearest field above (or first field)
PgDn | Nearest field below (or last field)
ESC | Form-level cancel (if in exit keys)
F10 | Form-level submit (if in exit keys)

OUTPUT

stdout
    All field values in the selected format (kv, json, or shell).

stderr
    Form-level exit reason mnemonic (suppressed by --quiet).

exit code
    0 for submit (F10), 1 for cancel (ESC), 2 for CTRL-X.

EXAMPLES
# Basic form
python3 fedform.py customer.def
# Shell output with preloaded values
python3 fedform.py customer.def -o shell --values saved.json
# JSON definition with JSON output
python3 fedform.py form.json -j -o json
# Eval form results in bash
eval "$(python3 fedform.py customer.def -o shell 2>/dev/null)"

SEE ALSO
fedline(1), fedarea(1), fedmask(1), fedlist(1), fedcheck(1), fedradio(1), fedmake(1), fedsay(1), fedbox(1)

AUTHOR
smisco (fed@smisco.biz)

COPYRIGHT
Copyright © 2026 smisco. All rights reserved.