Customizing the Command Line Interface (ClarionCL.EXE)

Top  Previous  Next

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.