Navigation: Advanced Topics > Customizing the IDE and Command Line Interface >====== Customizing the Command Line Interface (ClarionCL.EXE) ====== | |
The Command Line Interface Utility (ClarionCL) allows users to execute common IDE tasks from the command line without the need to start the Clarion IDE.
ClarionCL is data driven, allowing anyone to add commands that can be executed by it.
To add a command to ClarionCL, add a CommandLine element to an add in (.addin) file. The CommandLine element must be located in the /SharpDevelop/Workbench/CommandLines path.
The CommandLine element has the following attributes:
Element | Required/Optional | Description |
class | Required | The name of the class that implements ICommandLine |
id | Required | A string identifying this command line switch |
switch | Required | The string that follows the /, - or ' on the command line that links the command line switch to the class |
description | Required | Text that describes the command. Displayed to the user if he enters /? or no commands.The text can be split over multiple lines. A line cannot be more than 61 characters long |
insertafter | Optional | A comma separated list of other CommandLine items that this item must appear after when help is requested |
insertbefore | Optional | A comma separated list of other CommandLine items that this item must appear before when help is requested |
multi | Optional | Indicates if the switch can appear multiple times in the command line. The default is true. If false and the switch is supplied multiple times, the second and subsequent occurrences are ignored. The user is informed of this. |
optionalparameters | Optional | Specifies the number of optional parameters that may follow the switch. The default is 0. |
parameters | Optional | Specifies the number of parameters that must follow the switch. The default is 1 |
runafter | Optional | Specifies that the switch command will be executed after the passed command line elements. |
runbefore | Optional | Specifies that the switch command will be executed before the passed command line elements. |
Example:
<;Path name = “/SharpDevelop/Workbench/CommandLines”> |
<;CommandLine id = “RegisterTemplates” |
class = “SoftVelocity.Generator.RegisterTemplatesCommandLine” |
switch = “gr” |
description = “${res:SoftVelocity.Generator.RegisterTemplate.Description}“ |
multi = true/> |
<;CommandLine id = “GenerateApplication” |
class = “SoftVelocity.Generator.CommandLine.GenerateApplication” |
switch = “ag” |
insertbefore =“RegisterTemplate” |
description = “${res:Clarion.Generator.CommandLine.Application.Generate}”/> |
<;CommandLine id = “SetConditionalGeneration” |
class = “SoftVelocity.Generator.CommandLine.SetConditionalGeneration” |
switch = “agc” |
multi = “false” |
runbefore = “GenerateApplication” |
insertafter =“GenerateApplication” |
insertbefore =“RegisterTemplate” |
description = “${res:Clarion.Generator.CommandLine.Application.SetConditionalGeneration}”/> |
<;CommandLine id = “SetDebugGeneration” |
class = “SoftVelocity.Generator.CommandLine.SetDebugGeneration” |
switch = “agd” |
multi = “false” |
runbefore = “GenerateApplication” |
insertafter =“SetConditionalGeneration” |
insertbefore =“RegisterTemplate” |
description = “${res:Clarion.Generator.CommandLine.Application.SetDebugGeneration}”/> |
<;/Path> |
The description should be stored in a resources (.resources) file to allow for internationalization.
ICommandLine
The class attribute of the CommandLine element must specify a class that implements the ICommandLine interface. This is a very simple interface with only one property and one method:
bool Enabled { get; } |
void Run(List<;List<;string» parameters, ICommandLineLogger logger, Object redFile, bool forWindows); |
Regarding the Run method, the redFile parameter is actually of type Clarion.Core.Redirection.RedirectionFile.
The parameters parameter will contain the list of parameters supplied by the user.
Logger is an interface that can be used to return details to the user.
Each element of the outer list represents one instance of the command line switch. Each element of the inner list represents a parameter of a switch.
Example:
ClarionCL /x p1 p2 /x p3 p4
causes Run to be called with
parameters[0] = {p1, p2} and
parameters[1] = {p3, p4}
The Enabled property is called by ClarionCL to determine if the command should be visible during the current running of the program. For example, a command might return false if a template is not registered.
ICommandLineLogger
The ICommandLineLogger interface is used to send information to the user. The methods of ICommandLineLogger are as follows:
Message(STRING message)
message | A message to display to the user |
Description: Displays the message to the user
Error(STRING errorcode, STRING error)
errorcode | An identifier that uniquely identifies the error |
error | A language specific error message |
Description: Displays the error message to the user
Error(STRING errorcode, STRING error, STRING fileName, INT line)
errorcode | An identifier that uniquely identifies the error |
error | A language specific error message |
fileName | The name of the file where the error occurred |
line | The line where the error occurred. The first line is line 1 |
Description: Displays the error message to the user indicating the error is related to the passed file on the passed line number.
Error(STRING errorcode, STRING error, STRING fileName, INT line, INT column)
errorcode | An identifier that uniquely identifies the error |
error | A language specific error message |
filename | The name of the file where the error occurred |
line | The line where the error occurred. The first line is line 1 |
column | The column where the error occurred. The first character is in column position 1 |
Description: Displays the error message to the user indicating the error is related to the passed file on the passed line number at the passed column.
Warning(STRING warningcode, STRING warning)
warningcode | An identifier that uniquely identifies the warning |
warning | A language specific warning message |
Description: Displays the warning message to the user.
Warning(STRING warningcode, STRING warning, STRING fileName, INT line)
warningcode | An identifier that uniquely identifies the warning |
Warning | A language specific warning message |
filename | The name of the file where the warning occurred |
Line | The line where the warning occurred. The first line is line 1 |
Description: Displays the warning message to the user indicating the warning is related to the passed file on the passed line number.
Warning(STRING warningcode, STRING warning, STRING fileName, INT line, INT column)
warningcode | An identifier that uniquely identifies the error |
warning | A language specific error message |
filename | The name of the file where the error occurred |
line | The line where the error occurred. The first line is line 1 |
column | The column where the error occurred. The first character is in column position 1 |
Description: Displays the warning message to the user indicating the error is related to the passed file on the passed line number at the passed column.