> For the complete documentation index, see [llms.txt](https://cyr1en.gitbook.io/commandprompter/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cyr1en.gitbook.io/commandprompter/features/input-validation.md).

# Input Validation

Validation rejects an answer, sends the configured error message, and reopens the same prompt. Apply a configured validator with the whitespace-delimited `-iv:<alias>` flag. Aliases are case-sensitive and must contain only word characters (letters, digits, or underscore); a hyphenated alias does not parse as one validator flag.

## Configured validators

Each entry under `Input-Validation` has an `Alias` and `Err-Message` and may enable one or more checks:

| Key             | Behavior                                                                                                                          |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `Regex`         | Java regular expression matched against the entire input.                                                                         |
| `Online-Player` | Uses Bukkit's online-player name lookup. An exact name matches, but a partial name may also resolve to the closest online player. |
| `JS-Expression` | Nashorn JavaScript expression that must evaluate to Boolean `true`.                                                               |

When an entry enables multiple checks, all of them must pass. Referencing an unknown validator alias aborts session start (the command is not executed), logs a severe fail-fast error to the server console, and sends `command.error.missing_validator` to the player ("Configuration error: An unknown input validator is referenced. See server console for details.").

```yaml
Input-Validation:
  Integer-Sample:
    Alias: is
    Regex: '^\d+$'
    Err-Message: '&cEnter an integer.'
  Online-Player:
    Alias: online
    Online-Player: true
    Err-Message: '&cThat player is not online.'
  Minimum-Level:
    Alias: level10
    JS-Expression: 'BukkitPlayer.getLevel() >= 10'
    Err-Message: '&cYou must be level 10.'
```

JavaScript expressions can reference:

* `%prompt_input%`, replaced with the submitted answer
* `BukkitServer`
* `BukkitPlayer`
* PlaceholderAPI placeholders when that integration is installed

{% hint style="danger" %}
`JS-Expression` runs as trusted, unsandboxed server-side Nashorn code with Java interoperability and Bukkit objects available. Only server administrators should edit it. In 3.1.1, `%prompt_input%` is inserted into the JavaScript source as raw, unescaped text; do not use that placeholder with untrusted player input. Prefer `Regex` or `Online-Player` validation until the runtime binds input as data instead of source code.
{% endhint %}

## Built-in flags

* `-int` accepts only values handled by Java `Integer.parseInt`: signed 32-bit integers.
* `-str` requires a nonblank answer.

```
/example <Count -int> <Player -iv:online>
```

For compound dialogs, block-level validators and type flags are checked against every row. Do not apply them to a compound containing `title` or `body` rows because layout rows submit empty answers.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://cyr1en.gitbook.io/commandprompter/features/input-validation.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.