Public Member Functions | Public Attributes | Properties | List of all members
Prompt
MIT Licensed Code

Description

Prompt the user for an argument with completer, default input, history, etc.

Consider the following example command.

[Command]
public string HelloA(string str) {
return "Hello, " + str + "!";
}

By default the command M-x hello-a will ask the user to provide a String str: . This might be confusing for the user.

M-x hello-a
String str: umm?
Hello, umm?!

Now obviously, the name of the parameter "str" could be changed to, say, "name" which would help. However, sometimes one wants to control the entire prompting, which is what the Prompt attribute provides.

Set the prompt

It is used to decorate a parameter in a Command method. In its simplest usage, it defines how to prompt the user for input.

[Command]
public string HelloB([Prompt("Name: ")]
string str) {
return "Hello, " + str + "!";
}

M-x hello-b
Name: Mary
Hello, Mary!

Default Input

[Command]
public string HelloC([Prompt("Name: ",
input = "Susan")]
string str) {
return "Hello, " + str + "!";
}

M-x hello-c
Name: Susan
return
Hello, Susan!

History

History allows the user to quickly look up previous responses.

[Command]
public string HelloD([Prompt("Name: ", history = "first-name")] string str) {
return "Hello, " + str + "!";
}

M-x hello-d
Name:
M-uparrow
Name: Bob
M-uparrow
Name: Jordan
M-downarrow
Name: Bob
return
Hello, Bob!

Tab completion

Minibuffer offers extensive tab completion. The Prompt attribute is the main means of choosing which completion to offer.

Ad hoc completion

One can provide a list of completions.

[Command]
public string TweetScreenshot([Prompt("To twitter account: ",
completions = new []
{ "@shanecelis",
"@stupidmassive",
"@unormal" })]
string str) {
Minibuffer.instance.ExecuteCommand("capture-screenshot");
// ... Magic twitter code not included ...
return "Tweeted screenshot to " + str + ".";
}

M-x tweet-screenshot
To twitter account:
tab
->@shanecelis<-
@stupidmassive
@unormal
downarrow
@shanecelis
->@stupidmassive<-
@unormal
return
To twitter account: @stupidmassive
return
Tweeted screenshot to @stupidmassive.

Require match?

If requireMatch is set to true, the user input must match one of the completions, and it will not let the user continue. The user may always quit with C-g or escape.

M-x tweet-screenshot
To twitter account:
@curtisaube return
To twitter account: @curtisaube [No match]
return
To twitter account: @curtisaube [No match]
C-g
Quit.

If requireMatch is set to false, the user input does not have to match anything.

M-x tweet-screenshot
To twitter account:
@curtisaube
Tweeted screenshot to @curtisaube.

If requireMatch is not set, then it will try to choose a smart default: if there's a completer, it will default to true.

Completer

Minibuffer has many builtin completers: "buffer", "command", "directory", "file", "variable", AnimationClip, AudioClip, Color, Component, Font, GameObject, GUISkin, Material, Mesh, PhysicMaterial, Scene, Shader, Sprite, and Texture. And one can write their own using ICompleter. Type M-x describe-completers to see all available completers.

Suppose one wanted to select a directory for screenshots.

[Command]
public string ScreenshotDirectory([Prompt("Screenshot directory: ",
completer = "directory",
input = "~/")]
string dirName) {
this.screenshotDirectory = dirName;
return "Screenshot directory is " + dirName;
}

M-x screenshot-directory
Screenshot directory: ~/
D tab
->~/Desktop<-
~/Documents
~/Downloads
return
Screenshot directory is /Users/shane/Desktop

Coercion

In addition to tab completion Minibuffer offers type coercion and look up. So if a command needs, say, an integer, it does not need to do any string handling of its own. Suppose we had a command that plays a guess a number game.

[Command("quadrapus-color",
description = "Set color of quadrapus")]
public string SetColor([Prompt(requireMatch = false)]
Color c) {
quadrapus
.GetComponentsInChildren<MeshRenderer>()
.Each(x => x.material.SetColor("_Color", c));
return "Changed color to " + c + ".";
}
[Command("guess-a-number")]
public string GuessANumber(int guess) {
if (guess > 42)
return "Too high.";
else if (guess < 42)
return "Too low.";
else
return "You got it! 42, the answer to life, the universe and everything!";
}

M-x guess-a-number
int guess:
blah return
int guess: blah [Cannot coerce to int]
C-a C-k 10 return
Too low.

One does not actually need to specify a Prompt because it can infer one from the parameter type and name. However, it's instructive to see what the equivalent prompt is.

[Command("guess-a-number")]
public string GuessANumber([Prompt("int guess: ",
requireCoerce = true,
completer = "int",
desiredType = typeof(int),
int guess) {
...
}

In general, the desiredType property never needs to be set manually.

Require Coercion?

The property requireCoerce is like requireMatch. It requires that the input provided by the user can be coerced or looked up to the desiredType. If the parameter type is not string then a coercion is often mandatory, and the default for requireCoerce reflects that.

Ignore Parameters

One can mark certain parameters to be ignored so the user is never prompted for them. The method will instead receive a null if it's an object or the default value if it's a struct or enum. Optional parameters are by default ignored so these two code samples behave the same as commands:

[Command]
public void DontAsk1([Prompt(ignore = true)] string what) { ... }
[Command]
public void DontAsk2(string what = null) { ... }

Default Value

One can provide a default value for a parameter.

Even though defaultValue is an object, there are restrictions on what can be specified as attributes. This field has more practical uses when coupled with the Minibuffer.Read<T>(Prompt) method. And one can get a similar effect by using optional parameters anyhow. For instance these two code samples behave the same as commands:

[Command]
public void SomethingAbout1([Prompt(defaultValue = "Mary")] string what) { ... }
[Command]
public void SomethingAbout2(string what = "Mary") { ... }

Public Member Functions

 Prompt ()
 Create a prompt. More...
 
 Prompt (string prompt)
 Ask the user for something with the given prompt. More...
 

Public Attributes

string prompt
 The user prompt, e.g. "Your profession: ".
 
string input
 The default input if any, e.g. "Wizard".
 
string history
 The name of the command history to use, e.g. "profession-choice". More...
 
string completer
 The name of the completer to use, e.g. "profession". More...
 
string[] completions
 An ad hoc list of completions, e.g. new [] { "*random*", "Wizard", "Thief", "Warrior" }. More...
 
bool ignore
 If ignore is true, do not ask user for the argument and supply null by default. More...
 
object defaultValue
 If defaultValue is not null, do not ask the user for the argument and supply this value instead. More...
 
Type desiredType
 What type should the input be coerced to? The desiredType is often determined by the parameter type rather than setting it by hand. More...
 

Properties

bool requireMatch [get, set]
 Is a match with the completer required?
 
bool requireCoerce [get, set]
 Must the result coerce to the desiredType? (Not applicable if desiredType is a string.)
 

Constructor & Destructor Documentation

Prompt ( )

Create a prompt.

Prompt ( string  prompt)

Ask the user for something with the given prompt.

Member Data Documentation

string history

The name of the command history to use, e.g. "profession-choice".

New names will create new histories.

string completer

The name of the completer to use, e.g. "profession".

May be inferred based on the type of argument.

string [] completions

An ad hoc list of completions, e.g. new [] { "*random*", "Wizard", "Thief", "Warrior" }.

If completion and completions are both provided, the completers will be "concatenated" together. This allows one to provide some options that may not belong in the completer. For instance, M-x describe-variable uses this to add an 'all' option.

[Command("describe-variable",
description = "Show type, class, and description for a variable.")]
public void DescribeVariable([Prompt("Describe variable: ",
completions = new [] { "*all*" },
completer = "variable")]
string name) {
if (name == "*all*") {
...

In some cases, you may wish to add an option that won't be coercable to the desiredType. For instance, M-x describe-game-object adds a "*scene*" completion to essentially describe all the GameObjects in the scene instead of one GameObject. So "*scene*" will not coerce to a GameObject. In this case, we use PromptResult<GameObject> which holds two values: the string input given by the user, and what it was coerced to by the completer. This shows one example of how construct such commands.

[Command("describe-game-object",
description = "Show a game object's components and children.",
keyBinding = "C-h o")]
public void DescribeGameObject([Prompt("Describe GameObject: ",
completions = new [] { "*scene*" },
completer = "GameObject",
requireCoerce = false)]
PromptResult<GameObject> pr) {
string input = pr.str;
GameObject go = pr.obj;
if (go != null) {
// Got a game object.
...
} else if (input == "*scene*") {
// Show scene.
...
}
...
bool ignore

If ignore is true, do not ask user for the argument and supply null by default.

object defaultValue

If defaultValue is not null, do not ask the user for the argument and supply this value instead.

Type desiredType

What type should the input be coerced to? The desiredType is often determined by the parameter type rather than setting it by hand.