Clarion Community Help

| **Navigation:**  [[advanced topics 1.htm|Advanced Topics]] > Customizing the IDE and Command Line Interface >====== Customizing the Command Line Interface (ClarionCL.EXE) ====== | [[customizing the ide menu text.htm|{{btn_prev_n.gif|Previous page}}]][[advanced topics 1.htm|{{btn_home_n.gif|Return to chapter overview}}]][[project system 1.htm|{{btn_next_n.gif|Next page}}]] |
|  ||

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>** |
|  |

{{notebox.jpg|NoteBox.jpg}}

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.