Custom Commands

Custom commands are similar to command shell batch files. They allow Source Insight to spawn any command line driven tool, and to capture its output. Custom commands can also execute Windows programs.

Customs commands can execute, and then return to Source Insight. The output of shell custom commands can be captured into a file for editing, or can be pasted into the current selection. Custom commands are stored as part of the current configuration.

Custom commands can be used to spawn compilers, source control programs, and file filters, such as "sort".

A shortcut for editing a custom command is to hold down the Ctrl key while selecting the command. The Custom Commands dialog box will appear for that command.

Custom Command Dialog box

Command

Displays the name of the currently selected command. This pull-down list contains a list of all the custom commands defined.

Run

This is the command line to be executed when the custom command is invoked. The Run text box can contain special meta-characters. See: The 'Run' Field Format.

Dir

The working directory used when executing the script specified in the Run text box. Source Insight sets the current working directory to this location before running the command. If left blank, then Source Insight sets the current working directory to the project source directory. This field can also contain special meta-characters, just as with the Run field. See: The 'Run' Field Format.

Output Group

This group of options control what happens to the output of the command.

Iconic Window

If enabled, the spawned program will be put into a minimized window. If not enabled, then the program will launch normally.

Capture Output

If enabled, the standard output of the command will be captured and will appear in a new command output window when the command completes. The command output window's title will be the name of the custom command. If not enabled, the standard output will not be captured.

Paste Output

If enabled, the standard output of the command is pasted to the current selection.

Control Group

This group of options specifies what Source Insight does before and after the command runs.

Save Files First

If enabled, Source Insight will perform a Save All command prior to executing the command. The Save All command will prompt you for each file that has been edited to see if you want to save the file.

If not enabled, the command will be executed without saving any changed files. The unsaved changes will be retained when the command completes and control returns to Source Insight. If the command should cause a crash, Source Insight will be able to perform a recovery and all changes will be intact. See: Recovering From Crashes.

Pause When Done

If enabled, Source Insight will display this message in a command shell window when the command completes:

Press any key to return to Source Insight...

If not enabled, the shell window will terminate after the command completes.

Beep When Done

If enabled, Source Insight will beep when the command terminates.

Wait Until Done

If enabled, then Source Insight will suspend itself until the command finishes.

If not enabled, then Source Insight will run the command and continue. You will be able to switch back to the Source Insight window and continue working while the command runs in the background.

Exit Source Insight

Source Insight will exit after launching the program.

Source Links in Output

These options specify how the output is to be treated after the command finishes. You may tell Source Insight to parse through the captured output to find specific warning or error messages.

Parse Source Links

The command output will be searched for source link patterns. The patterns typically will match warning and error messages. If a pattern match is found, Source Insight inserts a source link at that line. The source link is used to link the warning or error message to its target source line. If Parse Source Links is enabled, you must have a valid search expression in the Pattern text box.

Pattern contains

File, then Line and Line, then File. This indicates the order of the groups in the pattern expression.

Select File, then Line if the first group in the pattern expression is the file name and the second group is the line number. With this setting, the second group, (i.e. the line number), is optional.

Select Line, then File if the first group in the pattern expression is the line number and the second group is the file name.

Pattern

Contains the regular expression used to search the command output for file names and line numbers. This is ignored if the Parse Source Links option is disabled. If the option is enabled, then this text box must contain a valid regular expression that contains "groups" for the file name and the line number. See: Regular Expressions.

Regular Expression Syntax

Selects the type of regular expression syntax to use with the pattern.

Define

Click this button to define the command named in the Name text box. If the command already exists, it is redefined.

Remove

Click this button to delete the command.

Run

Click this button to define and execute the command.

Cancel

Click this button to cancel the dialog box. Any definitions made in the dialog box will be retained.

Menu…

Click this button to define the current command and jump to the Menu Assignments dialog.

Keys…

Click this button to define the current command and jump to the Key Assignments dialog.

The 'Run' Field Format

The Run text box contains the command line to execute when the custom command is invoked. The Run text box can contain more than one command. Each command should be separated by a semi-colon. For example,

cat make.log;echotime

This string causes "cat make.log" to execute, followed by "echotime".

Running the Command Shell

If you want to run a shell command, such as "type", or "dir", or you want to run a batch file, then you have to run cmd.exe first. For example,

cmd /c mybat.bat or

cmd /c type foo.txt

If the Run string contains more than one command, separated by semi-colons, you don't need to run cmd.exe because Source Insight creates a batch file from the run string commands and runs cmd.exe automatically in that case. For example,

cat readme.txt;dir

This works fine because it is already running in a batch file inside a shell.

Command Line Substitutions

Both the Run text box, and the Dir text box can contain meta-characters that cause the following items to be substituted in the string.

Table 4.3: Custom Command Meta-Characters
Character	Expands to	Example
%f	full path name of the current file *	c:\myproj\file.c
%r	path name of current file relative to the project source directory *	file.c
%n	leaf name of the current file *	file.c
%d	directory path of the current file	c:\myproj
%h	directory path of current file without the drive letter	\myproj
%b	leaf name of current file w/o extension *	file
%e	extension of the current file	c
%c	drive letter of the current file	c:
%p	the current project name	c:\myproj\myproj
%j	the source directory of the current project	c:\myproj
%J	the data directory of the current project	C:\Documents and Settings\Jim Smith\Documents\Source Insight 4.0\Projects\Base
%v	the drive letter of the current project's source directory	c:
%o	leaf name of the project without path	myproj
%l	the current line number	any number
%w	first word in the selection, or the word under the cursor	any word
%s	name of a temp file where the current selection is saved while the custom command runs.	d:\tmp\vt0004.
%a	the current date	05-12-02
%t	the current time	08:23
%1 - %9	user is prompted for arguments	any strings

You can also postfix any of the above characters marked with * with either of the following modifier characters.

Character	Expands to	Example
%o	for all open files	%f%o
%m	for all modified files	%f%m

Path Variables

You can also use Path Variables in Run and Dir text fields. See: Predefined Path Variables.

ShellExecute Commands

ShellExecute lets you invoke Windows Shell commands.

Custom Commands support the "ShellExecute" function, which lets you tell the Windows shell to perform an operation on a specified file. The nice thing about ShellExecute is that you don't need to know what specific application is registered to handle a particular type of file. For technical background information, see the "ShellExecute" function in the Windows Shell API documentation.

To use this feature, the Run string in the custom command needs to start with "ShellExecute". The format should be:

ShellExecute <verb> <filespec> <optional parameters>

For example, to browse a website:

ShellExecute open http://www.somedomain.com

The verb is a single word, which can be one of the following:

edit Opens an editor for the file.
explore The function explores the folder specified.
open The function opens the file specified. The file can be an executable file or a document file. It can also be a folder.
print The function prints the document file specified. If filespec is not a document file, the function will fail.
properties Displays the file or folder's properties.
find Launches the Find Files application found on the Start menu.
"" (empty string) to skip this parameter to ShellExecute.

The filespec parameter can be any valid path. Use double quotes around complex path names with embedded spaces. You can also use a meta-character, such as %f (for the current file). It can also be the name of an executable file.

The optional parameters list is anything to the right of the filespec. It specifies the parameters to be passed to the application that ultimately runs. The format is determined by the verb that is to be invoked, and the application that runs. You can use custom command meta-characters here as well.

The working directory text box of the custom command is applied before the ShellExecute is invoked. However, output cannot be captured or parsed when using ShellExecute.

ShellExecute Examples

Here are some useful examples showing how to use ShellExecute.

Action	Custom Command Run String
To browse to a web site:	ShellExecute open http://www.somewebsite.com
To explore your Windows documents file folder:	ShellExecute explore "C:\Documents and Settings"
To launch Internet Explorer:	ShellExecute "" iexplore
To preview a file in Internet Explorer:	ShellExecute "" iexplore %f
To search for files in the current project folder:	ShellExecute find %j

Running Custom Commands in the Background

When Source Insight spawns a Custom Command shell program, it actually runs a program called Sihook4.exe. Sihook4.exe in turn spawns the command and performs the output capturing. You can run a custom command and click back on the Source Insight window to continue editing with Source Insight while the custom command runs in the background.

Creating a Compile and Build command

You can launch a compiler from Source Insight, using a custom command, and have the output captured and parsed for error messages. Then you can use Go To First Link and Go To Next Link to view each error in your source files.

To create a simple Compile command

To create a simple Compile command using the Microsoft ® C++ compiler:

1.Select Tools > Custom Command.

2.Type "Compile File" in the Name text box.

3.In the Run text box, type "cl %f". This invokes the compiler on the current file. You could also invoke a "make" program or a batch file here instead. If you use a batch file, you must run the command processor first. For example, "cmd /c mybatch.bat".

4.Turn on the Parse Source Links option. The default parse pattern is setup to parse the compiler error messages from the compiler output.

5.Turn on the Save Files First option so that your file is saved before running the compiler.

6.Click the Define button to save the new command. Alternatively, you can click the Menu or Keys buttons to define the new command and run the Menu Assignments or Keyboard Assignments commands, which will allow you to put the command on a menu or assign a key to it.

The Parse Source Links option causes Source Insight to search the compiler output and setup source links for each error message. In this case, the "link sources" are each error message in the compiler output file. The "link target" for each link is the file and line number given in each error message.

To Build a Project with Microsoft ® Developer Studio

1.Select Tools > Custom Command.

2.Select the Build Project command in the Command drop-down list. The Build Project custom command is predefined when you install Source Insight.

3.In the Run text box, type the following:

C:\MsDevPath\msdev project.dsp /make /rebuild

Where "MsDevPath" is the path to your msdev.exe program, and "project.dsp" is the name of the Developer Studio project.

This line invokes msdev.exe to rebuild the given project.

4.Turn on the Parse Source Links option. The default parse pattern is setup to parse the compiler error messages from the compiler output.

5.Turn on the Save Files First option so that your file is saved before building the project.

Viewing Compiler Errors

To view source lines with errors:

1.Run the Compile File custom command, which is defined as described above.

2.Assuming there are errors, when the compiler finishes the error messages will be in the "Compile File" window. Source Insight will automatically setup the source links and run the Go To First Link command. The first error message and the erroneous source line will be selected and made visible.

3.Use the Go To Next Link command (Shift+F9). The next error message in the "Compile File" window is selected, and the target of that link is shown, as was the first error.

4.Continue to use the Go To Next Link command until all the links (error messages) have been visited. If there are no more links, then Source Insight beeps and the message, "No links." will appear in the status bar.