Commands

Overview and API

• A console command is a "trigger phrase" mapped to a function closure
• A console statement is a string you type into the input field, and execute by pressing the enter key.
• The console core reads the statement, parses it for matching fields within the current scope and finally executes any referred methods or commands in hierarchical order.
• In a command statement, a trigger phrase can be succeeded by arguments that are passed into the mapped function.
• When the console executes a command or function, it attempts to write its final return value to the terminal output.

In the most basic terms, mapping a console command to a function gives you an easy way to globally access that function from any run-time context that allows console input to take place.

public function createCommand(
	triggerPhrase:String, 
    func:Function, 
    commandGroup:String = "Application", 
    helpText:String = ""):void

• triggerPhrase - The name of the command
• func - The function your command will be mapped to
• commandGroup - A name for a group this command should appear under in the index presented by the command "commands"
• helpText - A description of this command's functionality.

Examples

The following examples illustrate common command usage. When describing input and output, input statements are preceded with >>, while output statements are preceded with <<.

private function getUserByName(name:String):User{
	//return a User object
}

private function getUserByID(id:int):User{
	//return a User object
}

private function listUsers():Array{
	//return all the User objects
}

DConsole.createCommand("getUserByName", getUserByName);
DConsole.createCommand("getUserByID", getUserByID);
DConsole.createCommand("listUsers", listUsers);

In this example, we have two query methods used by our application. At run-time, we want the ability to run these methods with arbitrary values for testing purposes, perhaps because there is no GUI that calls these methods yet.

In the console, to run these functions we need to execute a statement. These are all valid statements:

>> getUserByName John
>> getUserByName "John"
>> getUserByID 20
>> getUserByID "20"

As you can see, the statement parser is capable of determining the argument type expected by the target function, so passing the int 20 as an explicit string argument or implicitly makes no difference. This is actually a necessity given the console core's nature as a string parser.

There is virtually no limit to the number of arguments you can pass into a command. The delimiter is a single space character.

>> setPositionXYZ 40 20 -40

In some cases you will want to pass in arguments with spaces in them. To escape the parser, in those instances, encase your argument in ear quotes.

>> setFullNameAndAge "John Doe" 43

For more details on arguments, see complex command arguments.

If the mapped function returns a value, the console will attempt to print it out using string concatenation.

>> listUsers
<< [User, User, User, User]

This also allows you to "decorate" functions that would otherwise return void with more informative text output for console use.

Return values can also be passed into other commands with "subcommand syntax".

private function setActiveUser(user:User):void{
	//logic omitted
}

DConsole.createCommand("setActiveUser", setActiveUser);

>> setActiveUser (getUserByName John)

See Subcommands for further details.

Summary

Creating a rich set of commands to poke and prod your application as it runs can be invaluable during development of anything dynamic, or even when testing an application on embedded hardware. Through smart use of the DConsole command system, hours upon hours of time can be saved during testing and debugging.