FEDMASK(1)

NAME
fedmask - masked terminal text input for shell scripts

SYNOPSIS
fedmask row col mask [options]

DESCRIPTION
fedmask is a curses-based masked input field designed as a subprocess component for shell scripts. It supports two modes:

Pattern masks define fixed-length input with literal characters and per-position character class validation (e.g., phone numbers, dates, SSNs). The cursor skips over literals; each fill slot accepts only characters matching its class.

Filter masks provide variable-length input with type-based character filtering (e.g., integers, floats, hex). They behave like fedline(1) but reject characters that don't match the type.

On exit, stdout receives the final text and stderr receives the exit reason. The editor draws inline within its field area, over whatever is already on the screen; it does not clear or restore the screen.

ARGUMENTS

row Screen row for field placement (0-indexed). Use @ for the current cursor row.

col Screen column for field placement (0-indexed). Use @ for the current cursor column.

mask
    Mask specification. One of: a pattern string, a named shortcut, or a filter type. See PATTERN MASKS, NAMED MASKS, and FILTER TYPES below.

OPTIONS

-v, --val TEXT
    Initial text value. For pattern masks, accepts either the formatted string (with literals) or raw fill characters.

-f, --fill CHAR
    Fill character for unfilled positions. Defaults to _ for pattern masks, none for filter masks.

-e, --exit KEYS
    Comma-separated list of exit key mnemonics. When omitted, all exit keys are active.

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

-c, --cursor POS
    Initial cursor position: start or end (default: end). For pattern masks, end positions at the first unfilled slot.

-m, --mode MODE
    Initial input mode for filter types: ins or ovr (default: ins). Pattern masks are always overwrite by nature. The Insert key toggles modes at runtime in filter mode.

-r, --reverse
    Display the field in reverse video.

--color FG,BG
    Field foreground/background colors. ANSI names, optional bright- prefix, or default.

-n, --noop
    Display the field with its content and exit immediately with code 0.

-h  Print brief usage and exit.

--help
    Print full help text and exit.

--version
    Print version and copyright information and exit.

TERMINAL
This field draws inline: it renders only within its own area, over whatever is already on the screen. It does not clear the screen and cannot restore it on exit — the calling script manages the surrounding display. fedform(1) is different: it owns and clears the screen and restores it on exit by default.

While the field 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 field with a configured exit key.

PATTERN MASKS
A pattern string defines fixed-length input. Each character is either a fill slot or a literal:

Character | Accepts
# | Digit (0-9)
@ | Letter (A-Z, a-z)
& | Alphanumeric (digit or letter)
* | Any printable character
\x | Escaped literal (next character is literal)

All other characters are literals: displayed in place, cursor skips over them. Typing overwrites the current fill slot and advances to the next.

Example: (###) ###-#### defines a US phone number input.

NAMED MASKS
Named shortcuts that expand to pattern strings:

Name | Pattern
phone:classic | (###) ###-####
phone:hyphen | ###-###-####
phone:period | ###.###.####
phone:digits | ##########
date:mdy | ##/##/####
date:ymd | ####-##-##
date:dmy | ##/##/####
time:24 | ##:##
time:12 | ##:## @@
ssn | ###-##-####
zip | #####
zip4 | #####-####
ein | ##-#######
cc | ####-####-####-####

FILTER TYPES
Variable-length input with character filtering. The format is type:N where N is the maximum field width.

Type | Accepts
int:N | Digits, optional leading -, max N chars
uint:N | Digits only, max N chars
float:N | Digits, one decimal point, max N chars
float:N.P | Float with max P decimal places
decimal:N | Unsigned, N decimal places, auto-width
decimal:W.N | Unsigned, W total width, N decimal places
hex:N | Hexadecimal (0-9, A-F, a-f), max N chars
alpha:N | Letters only, max N chars
alnum:N | Alphanumeric, max N chars
upper:N | Letters auto-uppercased, max N chars
lower:N | Letters auto-lowercased, max N chars

EXIT KEYS
Key | Mnemonic | Code
Escape | ESC | 1
Enter | ENTER | 2
Tab | TAB | 3
Shift+Tab | SHIFT-TAB | 4
F10 | F10 | 5
Up Arrow | UP_TOP | 6
Down Arrow | DOWN_BOTTOM | 7
Page Up | PGUP | 8
Page Down | PGDN | 9

EDITING KEYS

  Pattern Mode
Key | Action
Backspace | Move to previous fill slot, clear it
Delete | Clear current fill slot
Ctrl+E | Clear from cursor to end
Ctrl+T | Clear from start to cursor
Ctrl+Y | Clear all fill slots
Ctrl+Z | Undo

  Filter Mode
Key | Action
Insert | Toggle insert/overwrite mode
Backspace | Delete character before cursor
Delete | Delete character at cursor
Ctrl+E | Delete to end of text
Ctrl+T | Delete to start of text
Ctrl+Y | Clear all text
Ctrl+Z | Undo

  Both Modes
Key | Action
Home/End | Move to first/last position
Left/Right | Move cursor (skips literals in pattern mode)

OUTPUT

stdout
    The final text. For pattern masks, the formatted string with literals and spaces for unfilled positions. For filter masks, the raw text.

stderr
    The exit reason mnemonic (suppressed by --quiet).

exit code
    0 for --noop, 1-9 for exit keys (see EXIT KEYS).

EXAMPLES
# Phone number with classic format
python3 fedmask.py 0 0 phone:classic -v "5551234567"
# Date with dot fill character
python3 fedmask.py 0 0 date:mdy -f "."
# Custom SKU pattern
python3 fedmask.py 0 0 "SKU ####-@@-**:#" -v "2354AN2A7"
# Integer, restricted exit keys
python3 fedmask.py 0 0 int:8 -v "42" -e TAB,SHIFT-TAB
# Float with 2 decimal places
python3 fedmask.py 0 0 float:8.2 -v "99.95"
# Hex in reverse video
python3 fedmask.py 0 0 hex:6 -f "0" -r
# Display-only
python3 fedmask.py 5 10 phone:classic -v "5551234567" -n
# Colored mask
python3 fedmask.py 0 0 phone:classic --color yellow,blue

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

AUTHOR
smisco (fed@smisco.biz)

COPYRIGHT
Copyright © 2026 smisco. All rights reserved.