commands: Add commands to compile text to specific types

Add commands that are similar to `Str→` but perform additional
validation on their input. These commands are mostly useful to
validate user `Input`.

The commands include:
* `Text→Algebraic` parses a single algebraic
* `Text→Number` parses a single number
* `Text→Integer` parses a single integer
* `Text→Positive` parses a single positive (non-negative) number
* `Text→Real` parses a single real number
* `Text→Object` parses a single object
* `Text→Expression` parses a single expression

Signed-off-by: Christophe de Dinechin <christophe@dinechin.org>

Author: c3d

doc/commands/text.md

@@ -17,7 +17,104 @@ Convert an object to its text representation.
 
 Compile and evaluate the text, as if it was typed on the command line.
 
-`"1 2 + 4" TEXT→` will push `3` and `4` on the stack.
+```rpl
+" 1 2 + 4 * " TEXT→
+@ Expecting 12
+```
+
+## CompileToNumber
+
+Compile and evaluate a text argument to get a number.
+If the argument is not a number, then an `Invalid input` error is generated.
+
+```rpl
+"25.5" Text→Number
+@ Expecting 25.5
+```
+
+## CompileToAlgebraic
+
+Compile and evaluate a text argument to get an algebraic value.
+If the argument is not an algebraic value, then an `Invalid input` error is
+generated.
+
+```rpl
+"[ 25.5 2 ]" Text→Algebraic
+@ Expecting [ 25.5 2 ]
+```
+
+## CompileToInteger
+
+Compile and evaluate a text argument to get an integer value.
+If the argument is not an integer, then an `Invalid input` error is generated.
+
+```rpl
+"25" Text→Integer
+@ Expecting 25
+```
+
+This command is typically used in validation code for the `Input` command. For
+example, the following code will only accept integers that are multiple of 3.
+
+```rpl
+«
+	"Enter a multiple of 3"
+    { 42 0 « Text→Integer → x « if x 3 mod 0 = then x end » » }
+    INPUT
+»
+```
+
+## CompileToPositive
+
+Compile and evaluate a text argument to get a positive integer.
+If the argument is not a positive integer, then an `Invalid input` error is
+generated.
+
+```rpl
+"25" Text→Positive
+@ Expecting 25
+```
+
+## CompileToReal
+
+Compile and evaluate a text argument to get an real number, which includes
+integers, fractions and decimal values.
+If the argument is not a real number, then an `Invalid input` error is
+generated.
+
+```rpl
+"25/3" Text→Real
+@ Expecting 8 ¹/₃
+```
+
+## CompileToObject
+
+Compile and evaluate a text argument to get a single object.
+If the argument is not a single object, then an `Invalid input` error is
+generated.
+
+```rpl
+"{ 1 2 3 }" Text→Object
+@ Expecting { 1 2 3 }
+```
+
+This command is typically used for `Input` validation. The HP48-compatible
+approach suggested the use of `Compile`, which made it difficult to prevent
+users from inputing values that would have bad side effects, e.g. placing
+additional values on the stack or changing global variables.
+
+## CompileToExpression
+
+Compile and evaluate a text argument to get an expression.
+If the argument is not an expression, then an `Invalid input` error is
+generated.
+
+```rpl
+"2+3*ABC" Text→Expression
+@ Expecting '3·ABC+2'
+```
+
+This command is typically used for `Input` validation.
 
 ## Char→Code
 

doc/commands/ui.md

@@ -120,7 +120,31 @@ In the more general case, the validation program is a program that drops a value
 on the stack if successful. The input is only accepted after the program pushes
 a single value on the stack.
 
+For example, the following program lets the user enter a number, with a default
+value of `42`, and then adds one to it:
 
+```rpl
+«
+	"Enter number" { 42 0 number } INPUT
+    1 +
+    "Next number" →Tag
+»
+```
+
+The program as written above will reject non-number input values.
+
+The program below shows how to use custom validation. It will only
+accept an input value that is a multiple of 42.
+
+```rpl
+«
+	"Enter multiple of 42"
+    { 42 0 « Text→Integer → x « if x 42 mod 0 = then x end » » }
+    INPUT
+    1 +
+    "Next number" →Tag
+»
+```
 
 ## KEYEVAL
 Simulate a keypress from within a program

help/db48x.md

@@ -12729,7 +12729,104 @@ Convert an object to its text representation.
 
 Compile and evaluate the text, as if it was typed on the command line.
 
-`"1 2 + 4" TEXT→` will push `3` and `4` on the stack.
+```rpl
+" 1 2 + 4 * " TEXT→
+@ Expecting 12
+```
+
+## CompileToNumber
+
+Compile and evaluate a text argument to get a number.
+If the argument is not a number, then an `Invalid input` error is generated.
+
+```rpl
+"25.5" Text→Number
+@ Expecting 25.5
+```
+
+## CompileToAlgebraic
+
+Compile and evaluate a text argument to get an algebraic value.
+If the argument is not an algebraic value, then an `Invalid input` error is
+generated.
+
+```rpl
+"[ 25.5 2 ]" Text→Algebraic
+@ Expecting [ 25.5 2 ]
+```
+
+## CompileToInteger
+
+Compile and evaluate a text argument to get an integer value.
+If the argument is not an integer, then an `Invalid input` error is generated.
+
+```rpl
+"25" Text→Integer
+@ Expecting 25
+```
+
+This command is typically used in validation code for the `Input` command. For
+example, the following code will only accept integers that are multiple of 3.
+
+```rpl
+«
+	"Enter a multiple of 3"
+    { 42 0 « Text→Integer → x « if x 3 mod 0 = then x end » » }
+    INPUT
+»
+```
+
+## CompileToPositive
+
+Compile and evaluate a text argument to get a positive integer.
+If the argument is not a positive integer, then an `Invalid input` error is
+generated.
+
+```rpl
+"25" Text→Positive
+@ Expecting 25
+```
+
+## CompileToReal
+
+Compile and evaluate a text argument to get an real number, which includes
+integers, fractions and decimal values.
+If the argument is not a real number, then an `Invalid input` error is
+generated.
+
+```rpl
+"25/3" Text→Real
+@ Expecting 8 ¹/₃
+```
+
+## CompileToObject
+
+Compile and evaluate a text argument to get a single object.
+If the argument is not a single object, then an `Invalid input` error is
+generated.
+
+```rpl
+"{ 1 2 3 }" Text→Object
+@ Expecting { 1 2 3 }
+```
+
+This command is typically used for `Input` validation. The HP48-compatible
+approach suggested the use of `Compile`, which made it difficult to prevent
+users from inputing values that would have bad side effects, e.g. placing
+additional values on the stack or changing global variables.
+
+## CompileToExpression
+
+Compile and evaluate a text argument to get an expression.
+If the argument is not an expression, then an `Invalid input` error is
+generated.
+
+```rpl
+"2+3*ABC" Text→Expression
+@ Expecting '3·ABC+2'
+```
+
+This command is typically used for `Input` validation.
 
 ## Char→Code
 
@@ -13050,7 +13147,31 @@ In the more general case, the validation program is a program that drops a value
 on the stack if successful. The input is only accepted after the program pushes
 a single value on the stack.
 
+For example, the following program lets the user enter a number, with a default
+value of `42`, and then adds one to it:
+
+```rpl
+«
+	"Enter number" { 42 0 number } INPUT
+    1 +
+    "Next number" →Tag
+»
+```
+
+The program as written above will reject non-number input values.
+
+The program below shows how to use custom validation. It will only
+accept an input value that is a multiple of 42.
 
+```rpl
+«
+	"Enter multiple of 42"
+    { 42 0 « Text→Integer → x « if x 42 mod 0 = then x end » » }
+    INPUT
+    1 +
+    "Next number" →Tag
+»
+```
 
 ## KEYEVAL
 Simulate a keypress from within a program