[Proposal] Parameterization and user input via @input tokens in magic commands

[jonsequitur]

Supplying a parameter to a notebook will necessarily behave differently when running the notebook interactively versus via automation. A gesture that can serve both purposes based on the context would be ideal.

Important goals would be:

1. When running a notebook interactively, the user should be prompted for a value.
2. It should allow for command-line validation and documentation (e.g. command line help) for parameters.
3. It should be possible to declare a default so that if the user cancels input (in case 1) or doesn't provide it on the command line (in case 2), some value is still present.
4. In the absence of a provided value or a default value, an error should be produced.
5. The value should be available to all subkernels via variable sharing.
6. Some consideration should be given to input validation, e.g. the accepted type and arity for a given parameter.

Update: I've adjusted the proposal to account for a few recent improvements. The original proposal limited this functionality to the #!value magic command but we can now enable this for all magic commands.

One approach that would satisfy all of the above would be to use the @input: prefix available in magic command tokens to declare required parameters. Consider the following example. (All API details here are for illustration only.)

#!value --name iterations --from-value @input:number_of_iterations`

Running this interactively currently produces a user input prompt:

Running the notebook non-interactively from the command line, the proposal is to allow the value to provided something like this:

> dotnet interactive run mynotebook.ipynb --iterations 123

When the notebook is exported as a command line app (#1275), these parameters would be explicitly converted into options for the command line interface.

The value in this example would be stored in the value kernel and be available for sharing to other kernels. Other magic commands could also take advantage of this, anywhere where an @input:- or @password:-prefixed token is valid.

Type safety and validation of these inputs can be known based on the target type designated by System.CommandLine, and potentially stored in the document model (Microsoft.DotNet.Interactive.Documents.InteractiveDocument) in order to be used for tooling (e.g. generating command line tools with input validation or forms with richer UI) without running the notebook.

[Szeraax]

Everything about this proposal looks great! In my vision of being able to author notebook and hand them off to non-technical people, the non technical people will likely prefer to run interactively at first and then may in the future want to swap to automated. If there is the same parameter validation across both invocation planes, then they will have a great experience.

It should allow for command-line validation

If command line validation is desired, you'll need some way to type the input. At least in powershell, we have types as well as various validation attributes like

[ValidateSet("one","other")]
[ValidateRange(10,99)]
[ValidatePattern("^\d\d$")]

In powershell, you can set multiple of these on a single parameter, though, I find that to be rarely needed.

So you'd possibly add another parameter to #!value and be able to use any .net type? And then probably a space separated keyed array of validation options. Something like these perhaps?

#!value --name iterations --prompt "The number of iterations" --type System.Int32
#!value --name iterations --prompt "The number of iterations" --validate range=10,100 --type System.Int32
#!value --name employee --prompt "Your full name" --validate "pattern=^(\w+ ){2,3}"
#!value --name oddNumber --prompt "Odd number between 1 and 10" --validate range=1,10 pattern=[13579] --type System.int32

I would think that for stuff like range validation, you'd cast a copy of the parameter to int and not change the actual type of the input to int. Sometimes people like to validate as numbers, but use as a string. You'd also want to make sure that you specify WHY user input is invalid: whether it was due to not being able to get cast or what validation rule it failed to pass (if a rule, also add why it failed the validation rule unable to cast "foo" to System.Int32 for validation rule 'range=10,100').

Hope this brainstorm helps flesh out the proposal of what things you do like and what you don't like from my thoughts.

[jonsequitur]

A few thoughts: We'd use System.CommandLine for the command line parsing and validation under the hood, but the magic commands should possibly avoid embedding .NET concepts such as types. Maybe we would use a constrained set of type signifiers that could be mapped easily into different kernel languages, e.g. "bool", "int", "float", "string", "file".

[Szeraax]

No strong feelings either way from me on that. Seems fine.

[jonsequitur]

Experimental support for this is available in dotnet repl.