# Questions and keyboard input

[Programming guides](README.md)

**Input** is information a person gives your program. The **prompt** is the question it shows; the **reply** is the answer. The host may show a text question or a graphical input box. An **overlay** is a box displayed over the existing picture.

**Inclusive bounds** include the endpoints: a minimum of 1 and maximum of 5 allow 1 and 5 too. **Finite** excludes infinity and invalid numeric values. **Trimming whitespace** removes spaces and similar characters at the start and end. **Normalizing** changes an accepted spelling to one agreed form, such as the reply `"2,5"` becoming `2.5`.

**Exponent notation** in a number reply, such as `1e2`, means one times ten to the power two: 100. A sign is `+` or `-`. These are rules for answering a question; they do not make `1e2` a valid Pliro source-number literal. A particular input box may restrict what you can type.

## Input functions

| English call | Canonical ID | Returns | Requirements |
|---|---|---|---|
| `ask(prompt)` | `input.readLine` | `Text` | `prompt` is `Text`. |
| `askNumber(prompt, minimum, maximum)` | `input.readNumber` | `Number` | Prompt is `Text`; finite ordered numeric bounds. |
| `askYesNo(prompt)` | `input.readBoolean` | `Boolean` | `prompt` is `Text`. |
| `choose(prompt, options)` | `input.choose` | `Text` | A non-empty list of at most 100 unique, non-blank text options. |

Input waits cooperatively while the host displays a console question or
graphical overlay. The runtime validates and converts the reply. A numeric
answer must fall inside the inclusive bounds. Number replies are trimmed; one
decimal comma with no decimal point is normalized to a point. The finite numeric
reply parser also accepts an optional sign and exponent notation, although a
particular host control may restrict which characters can be typed. This input
grammar does not change Pliro's narrower source-number literal grammar. A choice
result is exactly one supplied option string. Option uniqueness is exact and
case-sensitive.

Console yes/no input accepts `true`, `yes`, `y`, `waar`, `ja`, `j`, or `1` for
true and `false`, `no`, `n`, `onwaar`, `nee`, or `0` for false, ignoring case
and surrounding whitespace. Graphical hosts present bounded yes/no and choice
controls instead.

```pliro
# language: en
let name = ask("What is your name?")
let age = askNumber("How old are you?", 5, 120)
let project = choose("What shall we make?", ["game", "drawing", "robot"])
let ready = askYesNo("Ready to start?")

if not ready:
    say "See you next time, " + name + "!"
    exitApp()

say name, "is", age, "and chose", project
```

Replies are bounded to 64 KiB of valid [UTF-8](../concepts/utf-8.md). Date input is not implemented
because Pliro does not yet have a specified `Date` value.

| English call | Canonical ID | Returns |
|---|---|---|
| `keyDown(key)` | `input.keyDown` | `Boolean` |

`key` is non-empty `Text`. The portable game names are `left`, `right`, `up`,
`down`, and `space`. Native graphical hosts additionally recognize common names
such as `enter`, `escape` or `esc`, `backspace`, and individual ASCII letters
and digits. A host that does not expose a requested key reports it as not down.

```text
if keyDown("left"):
    set x = x - speed
```

Keyboard polling is a host-mediated graphical capability; it does not read the
host keyboard directly from the interpreter.

## Related entries

[Syntax and values](../syntax/README.md) · [Built-ins](../builtins/README.md) · [Programming guides](README.md)