Class Documentation

Name:CommandLine
Version:1.0
ID:ID_COMMANDLINE
Status:Unspecified
Category:Tool
Date:January 2004
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2000-2004. All rights reserved.
Short:  Provides a command-line interface between the user and the system.



Description

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.
Action:Activate
Short: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.


Method:About()
Short: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.

Result
ERR_Okay  The method executed successfully.
ERR_FieldNotSet  The Output field has not been set.

Method:Erase()
Short: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.


Method:Help()
Short: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.


Method:Status()
Short: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.