OpenEuphoria

@[:console:prompt_number|]
==== prompt_number
<eucode>
include console.e
namespace console
public function prompt_number(sequence prompt, sequence range)
</eucode>

prompts the user to enter a number and returns only validated input.

===== Parameters:
# ##prompt## : is a string of text that will be displayed on the screen.
# ##range## : is a sequence of two values {lower, upper} which determine the range of values
that the user may enter. It can be empty, {}, if there are no restrictions.
# ##st## : is a string of text that will be displayed on the screen.
# ##s## : is a sequence of two values {lower, upper} which determine the range of values
that the user may enter. s can be empty, {}, if there are no restrictions.

===== Returns:
An **integer**,
the value which the user typed in, when within the assigned ##range##.
An **atom**,
in the assigned range which the user typed in.

===== Errors:
If ##prompt## is not a printable string, or either element
of ##range## is not an atomic value, a runtime error will be raised.
If [[:puts]] cannot display ##st## on standard output, or if the first or second element
of ##s## is a sequence, a runtime error will be raised.

If the user tries cancelling the prompt by hitting Control+Z, the program will abort,
issuing a "Stopped" message.

If the user enters a decimal value a type-check failure occurs, but only if the value is within range.
If user tries cancelling the prompt by hitting Control+Z, the program will abort as well,
issuing a type check error.

===== Comments:
For as long as the user enters a number that is less than lower, or a number greater
As long as the user enters a number that is less than lower or greater
than upper, the user will be prompted again.

If this routine is too simple for your needs, feel free to copy it and make your
own more specialized version.

===== Example 1:
<eucode>include std/console.e
integer age = prompt_number("What is your age? ", {0, 150})
<eucode>
age = prompt_number("What is your age? ", {0, 150})
</eucode>

===== Example 2:
<eucode>include std/console.e
integer t = prompt_number("Enter a temperature in Celcius:\n", {})
<eucode>
t = prompt_number("Enter a temperature in Celcius:\n", {})
</eucode>

===== See Also:
[[:puts]], [[:prompt_string]]