Package com.j3d.engine.interact.cmd.args

package com.j3d.engine.interact.cmd.args
Holds all possible Argument definitions that a command can use (except TaggedArgUtil)

Argument Definitions

Arguments are more so used to provide information to the user about what the Command expects more than it is type checking, as the Command still has to do type checking of the concrete objects before proceeding. All arguments implement the Argument base interface marking them as an argument.

The optionality of arguments are defined by the command in the defintion (except for Subcommand which is always required), however an optional argument cannot be between required arguments, they can only show up at the end of Command definitions.

The following are valid arguments:
  • TypedArg a generic argument which can take either a single type or multiple types. If it takes multiple types it creates a tree structure of the command for possible usage types. e.g.: 
    
             "engine" () {
                 new TypedArg(boolean),
                 new TypedArg(string)
             }
             // becomes
             engine <boolean> <string>
    whereas if i had multiple types 
    
             "engine" () {
                 new TypedArg(boolean, Vector3, number),
                 new TypedArg(string)
             }
             // becomes
             engine <boolean> <string>
             engine <Vector3> <string>
             engine <number> <string>
    This doesn't actually affect the command itself, but this is the output shown to the user.
  • ArgSet is a special type of argument which defines a closed list of string values that the argument can take. This functions almost identical to a TypedArg that takes a string however differs in that it tells the user there's a specific set that they are allowed to input instead of any string. A rigid argument.These arguments are denoted by the square bracket syntax followed by a list of strings. e.g. 
    
             "engine" () {
                 new ArgSet("clear", "remove"),
                 new TypedArg(boolean)
             }
             // becomes
             engine [clear|remove] <boolean>
    This argument is special as it also provides a method to check if a given input matches the rigid list, so usually instead of defining this argument within the constructor of a Command, it's better to have it be a private field for validation.
  • Subcommand is probably the most important type of argument, as it is itself a Command, functions exactly like a Command, except it is only called by its head Command or Subcommand and is itself an Argument, allowing complex chaining of commands. e.g. If we have the following subcommands: 
    
             "clear" () {
                 new TypedArg(boolean),
                 new ArgSet("all", "selected")
             }
             clear <boolean> [all|selected]
             "close" () {} // no arguments
             close
             "recalc" () {
                 new TypedArg(Vector3, number)
                 new TypedArg(number)
             }
             recalc <Vector3> <number>
             recalc <number> <number>
    and the head command: 
    
             "engine" () {
                 new ClearSubcommand(),
                 new CloseSubcommand(),
                 new RecalcSubcommand()
             }
    The usage strings of the subcommands themselves are generated first, and simply appended to the head command/subcommand and goes up the chain until we get to the base Command. 
    
             engine clear <boolean> [all|selected]
             engine close
             engine recalc <Vector3> <number>
             engine recalc <number> <number>

Tagged Arguments

This is a special type of argument, which is not part of the main argument list and can be typed by the user at any time. All Commands accept a variadic amount of tagged arguments, and there is a specific set of tagged arguments which a user can use, defined within TaggedArgUtil. See documentation in TaggedArgUtil and TaggedArgValue for more information.

Author:
Lehlogonolo Poole
  • Class
    Description
    ArgSet
    A special type of string argument that can take a set of predefined string values.
    Argument
    Defines the contract for a command argument in the command processing system.
    Subcommand
    Represents a command that is nested within another command, acting as both a Command in its own right and as an Argument to its parent command.
    TaggedArgUtil
    A utility class for parsing and managing "tagged arguments" within the command system.
    TaggedArgValue<T>
    Represents an instance of a parsed tagged argument, holding its name, its value, and its expected type.
    TypedArg
    Represents a command argument that is expected to be of a specific type or one of several allowed types.