[next] [prev] [prev-tail] [tail] [up]

### 6.10 Using Tools

The tools menu provides easy access to external tools. It also has three pre-defined tools for programmers: an ASCII table, a grep tool and a calculator. The output of the external tools can be accessed through this menu as well.

#### The messages window

The output of the external utilities is redirected by the IDE and it will be displayed in the messages window. The messages window is displayed automatically, if an external tool was run. The messages window can be also displayed manually by the selecting the menu item ”Tools--Messages” or by pressing the key F11. The messages window is shown in figure (6.17).

Figure 6.17: | The messages window

If the output of the tool contains filenames and line numbers, the messages window can be used to navigate the source as in a browse window:

1. Pressing EN T E R or double clicking the output line will jump to the specified source line and close the messages window.
2. Pressing the space bar will jump to the specified source line, but will leave the messages window open, with the focus on it. This allows to quickly select another message line with the arrow keys and jump to another location in the sources.

The algorithm which extracts the file names and line numbers from the tool output is quite sophisticated, but in some cases it may fail4.

#### Grep

One external tool in the Tools menu is already predefined: a menu item to call the grep utility (”Tools--Grep” or SH I F T-F2). Grep searches for a given string in files and returns the lines which contain the string. The search string can be even a regular expression. For this menu item to work, the grep program must be installed, since it does not come with Free Pascal.

The messages window displayed in figure (6.17) in the previous section shows the output of a typical grep session. The messages window can be used in combination with grep to find special occurrences in the text.

Grep supports regular expressions. A regular expression is a string with special characters which describe a whole class of expressions. The command line in D O S or L I N U X have limited support for regular expressions: entering ls *.pas (or dir *.pas) to get a list of all Pascal files in a directory. *.pas is something similar to a regular expression. It uses a wildcard to describe a whole class of strings: those which end on ”.pas”. Regular expressions offer much more: for example [A-Z][0-9]+ describes all strings which begin with a upper case letter followed by one or more digits.

It is outside the scope of this manual to describe regular expressions in great detail. Users of a L I N U X system can get more information on grep using man grep on the command-line.

#### The ASCII table

The tools menu provides also an ASCII table (”Tools--Ascii table”), The ASCII table can be used to look up ASCII codes as well as inserting characters into the window which was active when invoking the table. To get the ASCII code of a char move the cursor on this char or click with the mouse on it. To insert a char into an editor window either:

1. using the mouse, double click it,
2. using the keyboard, press EN T E R while the cursor is on it.

This is especially useful for pasting graphical characters in a constant string.

The ASCII table remains active till another window is explicitly activated, thus multiple characters can be inserted at once. The ASCII table is shown in figure (6.18).

Figure 6.18: | The ASCII table

#### The calculator

The calculator allows to do some quick calculations. It is a simple calculator, since it does not take care of operator precedence, and bracketing of operations is not (yet) supported.

The result of the calculations can be pasted into the text using the CT R L-EN T E R keystroke. The calculator dialog is shown in figure (6.19).

Figure 6.19: | The calculator dialog

The calculator supports all basic mathematical operations such as addition, subtraction, division and multiplication. They are summarised in table (6.1).

Table 6.1: | Advanced calculator commands
Operation | Button | Key
Add two numbers | + | +
Subtract two numbers |  |
Multiply two numbers | * | *
Divide two numbers | / | /
Delete the last typed digit | <- | BA C K S P A C E
Delete the display | C | C
Change the sign | + |
Do per cent calculation | % | %
Get result of operation | = | EN T E R

But also more sophisticated mathematical operations such as exponentiation and logarithms are supported. The available mathematical calculations are shown in table (6.2).

Table 6.2: | Advanced calculator commands
Operation | Button | Key
Calculate power | x^y |
Calculate the inverse value | 1/x |
Calculate the square root | sqr |
Calculate the natural logarithm | log |
Square the display contents | x^2 |
.

Like many calculators, the calculator in the IDE also supports storing a single value in memory, and several operations can be done on this memory value. The available operations are listed in table (6.3)

Table 6.3: | Advanced calculator commands
Operation | Button | Key
Add the displayed number to the memory | M+ |
Subtract the displayed number from the memory | M- |
Move the memory contents to the display | M-> |
Move the display contents to the memory | M<- |
Exchange display and memory contents | M<-> |

#### Adding new tools

The tools menu can be extended with any external program which is command-line oriented. The output of such a program will be caught and displayed in the messages window.

Adding a tool to the tools menu can be done using the ”Options--Tools” menu. This will display the tools dialog. The tools dialog is shown in figure (6.20).

Figure 6.20: | The tools configuration dialog

In the tools dialog, the following actions are available:

New
  Shows the tool properties dialog where the properties of a new tool can be entered.
Edit
  Shows the tool properties dialog where the properties of the highlighted tool can be edited.
Delete
  Removes the currently highlighted tool.
Cancel
  Discards all changes and closes the dialog.
OK
  Saves all changes and closes the dialog.

The definitions of the tools are written in the desktop configuration file, so unless auto-saving of the desktop file is enabled, the desktop file should be saved explicitly after the dialog is closed.

#### Meta parameters

When specifying the command line for the called tool, meta parameters can be used. Meta parameters are variables and and they are replaced by their contents before passing the command line to the tool.

$CAP
  Captures the output of the tool.
$CAP_MSG
  Captures the output of the tool and puts it in the messages window.
$CAP_EDIT
  Captures the output of the tool and puts it in a separate editor window.
$COL
  Replaced by the column of the cursor in the active editor window. If there is no active window or the active window is a dialog, then it is replaced by 0.
$CONFIG
  Replaced by the complete filename of the current configuration file.
$DIR()
  Replaced by the full directory of the filename argument, including trailing directory separator. e.g.

              $DIR('d:\data\myfile.pas')

  would return d:\data\.
$DRIVE()
  Replaced by the drive letter of the filename argument. e.g.

              $DRIVE('d:\data\myfile.pas')

  would return d:.
$EDNAME
  Replaced by the complete file name of the file in the active edit window. If there is no active edit window, this is an empty string.
$EXENAME
  Replaced by the executable name that would be created if the make command was used. (i.e. from the ’Primary File’ setting or the active edit window).
$EXT()
  Replaced by the extension of the filename argument. The extension includes the dot. e.g.

              $EXT('d:\data\myfile.pas')

  would return .pas.
$LINE
  Replaced by the line number of the cursor in the active edit window. If no edit window is present or active, this is 0.
$NAME()
  Replaced by the name part (excluding extension and dot) of the filename argument. e.g.

              $NAME('d:\data\myfile.pas')

  would return myfile.
$NAMEEXT()
  Replaced by the name and extension part of the filename argument. e.g.

              $NAMEEXT('d:\data\myfile.pas')

  would return myfile.pas.
$NOSWAP
  Does nothing in the IDE, it is provided for compatibility with Turbo Pascal only.
$PROMPT()
  Prompt displays a dialog bow that allows editing of all arguments that come after it. Arguments that appear before the $PROMPT keyword are not presented for editing.

  If a (optional) filename argument is present, $PROMPT() will load a dialog description from the filename argument, e.g.

            $PROMPT(cvsco.tdf)

  would parse the file cvsco.tdf, construct a dialog with it and display it. After the dialog closed, the information entered by the user is used to construct the tool command line.

  See section 6.10, page 209 for more information on how to create a dialog description.

$SAVE
  Before executing the command, the active editor window is saved, even if it is not modified.
$SAVE_ALL
  Before executing the command, all unsaved editor files are saved without prompting.
$SAVE_CUR
  Before executing the command the contents of the active editor window are saved without prompting if they are modified.
$SAVE_PROMPT
  Before executing the command, a dialog is displayed asking whether any unsaved files should be saved before executing the command.
$WRITEMSG()
  Writes the parsed tool output information to a file with name as in the argument.

#### Building a command line dialog box

When defining a tool, it is possible to show a dialog to the user, asking for additional arguments, using the $PROMPT(filename) command-macro. Free Pascal comes with some dialogs, such as a ’grep’ dialog, a ’cvs checkout’ dialog and a ’cvs check in’ dialog. The files for these dialogs are in the binary directory and have an extension .tdf.

In this section, the file format for the dialog description file is explained. The format of this file resembles a windows .INI file, where each section in the file describes an element (or control) in the dialog. An OK and an Cancel button will be added to the bottom of the dialog, so these should not be specified in the dialog definition.

A special section is the Main section. It describes how the result of the dialog will be passed on the command-line, and the total size of the dialog.

Remark: Keywords that contain a string value, should have the string value enclosed in double quotes as in

     Title="Dialog title"

The Main section should contain the following keywords:

Title
  The title of the dialog. This will appear in the frame title of the dialog. The string should be enclosed in quotes.
Size
  The size of the dialog, this is formatted as (Cols,Rows), so

            Size=(59,9)

  means the dialog is 59 characters wide, and 9 lines high. This size does not include the border of the dialog.
CommandLine
  specifies how the command-line will be passed to the program, based on the entries made in the dialog. The text typed here will be passed on after replacing some control placeholders with their values.

  A control placeholder is the name of some control in the dialog, enclosed in percent (%) characters. The name of the control will be replaced with the text, associated with the control. Consider the following example:

            CommandLine="-n %l% %v% %i% %w% %searchstr% %filemask%"

  Here the values associated with the controls named l, i, v, w and searchstr and filemask will be inserted in the command-line string.
Default
  The name of the control that is the default control, i.e. the control that has the focus when the dialog is opened.

The following is an example of a valid main section:

     [Main]
     Title="GNU Grep"
     Size=(56,9)
     CommandLine="-n %l% %v% %i% %w% %searchstr% %filemask%"
     Default="searchstr"

After the Main section, a section must be specified for each control that should appear on the dialog. Each section has the name of the control it describes, as in the following example:

     [CaseSensitive]
     Type=CheckBox
     Name="~C~ase sensitive"
     Origin=(2,6)
     Size=(25,1)
     Default=On
     On="-i"

Each control section must have at least the following keywords associated with it:

Type
  The type of control. Possible values are:
  Label
    A plain text label which will be shown on the dialog. A control can be linked to this label, so it will be focused when the user presses the highlighted letter in the label caption (if any).
  InputLine
    An edit field where a text can be entered.
  CheckBox
    A Checkbox which can be in a on or off state.
Origin
  Specifies where the control should be located in the dialog. The origin is specified as (left,Top) and the top-left corned of the dialog has coordinate (1,1) (not counting the frame).
Size
  Specifies the size of the control, which should be specified as (Cols,Rows).

Each control has some specific keywords associated with it; they will be described below.

A label (Type=Label) has the following extra keywords associated with it:

Text
  the text displayed in the label. If one of the letters should be highlighted so it can be used as a shortcut, then it should be enclosed in tilde characters (~), e.g. in

            Text="~T~ext to find"

  The T will be highlighted.
Link
  here the name of a control in the dialog may be specified. If specified, pressing the label’s highlighted letter in combination with the AL T key will put the focus on the control specified here.

A label does not contribute to the text of the command-line, it is for informational and navigational purposes only. The following is an example of a label description section:

     [label2]
     Type=Label
     Origin=(2,3)
     Size=(22,1)
     Text="File ~m~ask"
     Link="filemask"

An edit control (Type=InputLine) allows to enter arbitrary text. The text of the edit control will be pasted in the command-line if it is referenced there. The following keyword can be specified in a inputline control section:

Value
  here a standard value (text) for the edit control can be specified. This value will be filled in when the dialog appears.

The following is an example of a input line section:

     [filemask]
     Type=InputLine
     Origin=(2,4)
     Size=(22,1)
     Value="*.pas *.pp *.inc"

A combo-box control (Type=CheckBox) presents a checkbox which can be in one of two states, on or off. With each of these states, a value can be associated which will be passed on to the command-line. The following keywords can appear in a checkbox type section:

Name
  the text that appears after the checkbox. If there is a highlighted letter in it, this letter can be used to set or unset the checkbox using the AL T-letter combination.
Default
  specifies whether the checkbox is checked or not when the dialog appears (values on or off)
On
  the text associated with this checkbox if it is in the checked state.
Off
  the text associated with this checkbox if it is in the unchecked state.

The following is a example of a valid checkbox description:

     [i]
     Type=CheckBox
     Name="~C~ase sensitive"
     Origin=(2,6)
     Size=(25,1)
     Default=On
     On="-i"

If the checkbox is checked, then the value -i will be added on the command-line of the tool. If it is unchecked, no value will be added.

[next] [prev] [prev-tail] [front] [up]