# Examples

Working examples for every tool in the suite. Run all commands from the
repository root (the parent of this directory). Only `python3` is required —
no dependencies beyond the standard library.

## What's here

| File | Tool | Shows |
|------|------|-------|
| `demo.sh` | all editors | Interactive tour of every field type; the capture-stdout / check-exit-code calling pattern. |
| `customer.def` | fedform | A compact line-oriented form (line, area, mask fields). |
| `survey.def` | fedform | Every field type, validation, locked field, colors, `DEF` defaults, and pre/post-form commands. |
| `survey.json` | fedform | The same form expressed as a JSON definition (`-j`). |
| `survey-values.json` | fedform | A values file to pre-fill `survey.def`/`survey.json` (`--values`). |
| `customer.mockup` | fedmake | A visual mockup → fedform definition (two-column layout). |
| `registration.mockup` | fedmake | A mockup exercising all six field types (line, mask, area, list, radio, check). |

## Run the interactive tour

```bash
bash examples/demo.sh
```

Steps through one of each editor, then launches the full `survey.def` form
and prints the submitted values. Needs a real terminal (the editors use
curses) — run it directly, not through a pipe.

## fedform

```bash
# Render a form and print values as name=value pairs (default)
python3 fedform.py examples/survey.def

# Eval-safe shell assignments — use the values directly in a script
eval "$(python3 fedform.py examples/survey.def -o shell 2>/dev/null)"

# JSON output
python3 fedform.py examples/survey.def -o json

# Pre-fill fields from a values file
python3 fedform.py examples/survey.def --values examples/survey-values.json

# Use the JSON definition instead of the line-oriented one
python3 fedform.py examples/survey.json -j -o json

# Start focus on a specific field; only ESC/F10 exit the form
python3 fedform.py examples/survey.def -f email -e ESC,F10
```

The two `survey.*` definitions are equivalent — compare them to see how the
line-oriented `@SAY/@GET` syntax maps onto the JSON schema.

## fedmake

```bash
# Convert a visual mockup into a fedform definition
python3 fedmake.py examples/registration.mockup

# Emit JSON instead of the line-oriented form
python3 fedmake.py examples/registration.mockup -j

# Generate a definition, then render it (fedform reads input from the
# terminal, so convert to a file rather than piping the definition in)
python3 fedmake.py examples/registration.mockup > /tmp/registration.def
python3 fedform.py /tmp/registration.def
```

## Single editors (subprocess components)

Each editor writes its value to stdout and an exit-reason mnemonic to stderr.
The standard pattern: capture stdout, read stderr, branch on the exit code.

```bash
# fedline — single-line text:  row col width maxlen
python3 fedline.py 2 0 40 120 -v "edit me"

# fedarea — multi-line text:   row col width rows maxlen v_scroll word_wrap
python3 fedarea.py 2 0 50 6 2000 1 1 -v "type a long note; it word-wraps"

# fedmask — masked input:      row col mask
python3 fedmask.py 2 0 phone:classic
python3 fedmask.py 2 0 float:8.2 -v "99.95"

# fedlist — scrollable select: row col width rows
python3 fedlist.py 2 0 24 6 -i "Apple|Banana|Cherry|Date|Fig|Grape"

# fedcheck — multi-select:     row col width
python3 fedcheck.py 2 0 24 -i "Email|SMS|Push" -v "Email|Push"

# fedradio — single-select:    row col width
python3 fedradio.py 2 0 24 -i "Small|Medium|Large" -v "Medium"
```

Capture pattern:

```bash
reason_file="$(mktemp)"
value="$(python3 fedline.py 2 0 40 120 -v "hello" 2>"$reason_file")"
code=$?
reason="$(cat "$reason_file")"; rm -f "$reason_file"
echo "got '$value' (reason=$reason, code=$code)"
```

## Non-interactive companions (fedsay, fedbox)

These run no curses session — they emit ANSI to stdout, like `tput`. Use them to
draw the labels and frames *around* the inline editors (which draw only their own
field). Exit is 0/1; there is no value or exit-reason protocol.

```bash
# fedsay — positioned, colored text:  row col [text]
python3 fedsay.py 2 0 "Name:" --color bright-white,blue

# fedbox — frame / panel:             row col rows cols   (size incl. borders)
python3 fedbox.py 0 0 6 40 --style double --title "[ Customer ]"
python3 fedbox.py 0 0 6 40 --fill --color white,blue        # filled panel
python3 fedbox.py 3 3 5 24 --style half-in --fill .         # half-block frame

# Compose: draw a panel, label a row inside it, then run a field there.
python3 fedbox.py 1 2 5 40 --keep
python3 fedsay.py 2 4 "Name:" --color bright-white,default
python3 fedline.py 2 11 28 80 -v "edit me"
```
