The CommandLine class is a tool that can be used to create
text-based Command Line Interfaces (CLI's). Creating a valid CommandLine
object only requires a reference to an object capable of receiving text based
output (usually a Text object). Whenever a command is executed, the
CommandLine object will process it and then send the results to the output
object you specify. For example, the command "print athene:documents/readme.txt"
would send the readme.txt file to the Output object as text information.
If an invalid command is used, the CommandLine object will print a human
readable error to the Output object. This ensures that feedback is always
sent to the user even when there is no success.
A number of methods are provided by this class which are useful for
creating menu-based interfaces to CommandLine objects. For further
information as to the arguments required for the execution of these
methods, refer to the relevant documented sections.
This document does not describe any of the available commands supported by
this class (except those also supported via methods). If you need
information on the commands available to the user, open the Athene CLI
application and type 'help' for an index. It is also recommended that you
view the DML code to the CLI application, which you can find in the
scripts:tools/commandline/ directory.
Actions
The CommandLine class supports the following actions:
Activate | Executes the instructions set in a CommandLine's Command field. |
Methods
The CommandLine class implements the following methods:
About | Prints summarised information about the CommandLine class. |
Erase | Destroys all objects created from the CommandLine. |
Help | Prints the user instructions for using the Command Line Interface. |
Status | Prints a list of all the objects created from the CommandLine. |
Structure
The CommandLine object consists of the following public fields:
Command | Set this field prior to activation for a command to be executed. |
Output | Set this field to give the CommandLine an object to send output to. |
Activate |
Executes the instructions set in a CommandLine's Command field. |
Activating a CommandLine object causes it to analyse the
Command field and print the results to the object
specified in the Output field.
|
|
About() |
Prints summarised information about the CommandLine class. |
If this method is called the CommandLine object will print a summary of
what the CommandLine does, who wrote it, copyright information and so on.
ERR_Okay | The method executed successfully. |
ERR_FieldNotSet | The Output field has not been set. |
|
|
Erase() |
Destroys all objects created from the CommandLine. |
Calling the Erase method will destroy every object that has been
instantiated through use of the 'create' command. This is useful if the
user has created a number of objects and wants to clean them away to start
afresh.
|
|
Help() |
Prints the user instructions for using the Command Line Interface. |
Calling this method will output the instructions on how the user should
use the CommandLine class.
|
|
Status() |
Prints a list of all the objects created from the CommandLine. |
Calling the Status method prints a list of all the objects that have been
created by the CommandLine object. This allows the user to know exactly
what is lingering in memory as a result of using the 'create' command.
All objects listed by the Status method are freed from the system when the
CommandLine object terminates, or the 'erase' command can be used to destroy
them early.
|
|
Field: | Command |
Short: | Set this field prior to activation for a command to be executed. |
Type: | STRING |
Status: | Read/Write |
Before a CommandLine object is Activated, this field must be set so that
the object will know what command to perform. Setting this field will not
result in a validation of the command - it will simply buffer the request and
translate it once the Activate action is called on the CommandLine object.
To get a list of valid commands, type 'help' into the Athene CLI
application.
|
|
Field: | Output |
Short: | Set this field to give the CommandLine an object to send output to. |
Type: | OBJECTID |
Status: | Read/Write |
The Output field must be set in order for a CommandLine object to
process the commands sent from the user. If it is not set then commands
will not be executed when the CommandLine object is Activated. The Output
object must accept text-based information via data channels in order for the
data to be interpreted correctly. If the Output object does not support
text based information, the CommandLine will still process the command but
the user will not receive any text based output.
It is recommended that this field points to an object that is a member
of the Text class.
|
|