16.5.13 Defining text aliases

GPS provides a mechanism known as aliases. These are defined through the menu Edit->Aliases.

Each alias has a name, which is generally a short string of characters. When you type them in any textual entry in GPS (generally a source editor, but also entry fields for instance in the file selector), and then press the special activation key (by default <control-o>, controlled by a preference), this name is removed from the source editor, and replaced by the text you have associated with it.

Alias names may be composed of any character except newlines, but must start with a letter. GPS will jump to the start of each word before the current cursor position, and if the characters between this word start and the cursor position is an alias name (the comparison is case insensitive), this alias is expanded.

The alias editor is divided into three main parts: on the left side, the list of currently defined aliases is shown. Clicking on any of them will display the replacement text for this alias. If you click again the selected alias, GPS displays a text entry which you can use to rename an existing alias. Alias names must start with a letter. A check button at the bottom selects whether the read-only aliases (i.e. system-wide aliases) should be displayed.

The second part is the expansion text for the alias, at the bottom right corner. This replacement text can used multiple lines, and contain some special text that act as a special replacement. These special texts are highlighted in a different color. You can insert these special entities either by typing them, or by right-clicking in the editor, and select the entity in the contextual menu.

The following special entities are currently defined:

%_

This is the position where the cursor should be put once the replacement text has been inserted in the editor.

%(name)

This is the name of a parameter. name can be any string you want, excluding closing parenthesis. See below for more information on parameters.

%D

This is the current date, in ISO format. The year is displayed first, then the month and the day

%H

This is the current time (hour, minutes and seconds)

%l

If the expansion of the alias is done in a source editor, this is the line on which the cursor is when pressing <control-o>.

%c

This is similar to %l, except it returns the current column.

%f

If the expansion is done in a source editor, this is the name of the current file (its base name only, this doesn't include the directory)

%d

If the expansion is done in a source editor, this is the directory in which the current file is

%p

If the expansion is done in a source editor, this is the base name of the project file to which the file belongs.

%P

If the expansion is done in a source editor, this is the full path name to the project file (directory and base name).

%O

Used for recursive aliases expansion. This special character will expand the text seen before it in the current alias, after replacement of the parameters and possibly other recursive expansions. This is similar to pressing <control-o> (or any key you have defined for alias expansion) in the expanded form of the alias.

%%

Inserts a percent sign as part of the expanded text

You cannot expand an alias recursively when already expanding that alias. For instance, if the alias expansion for procedure contains procedure%O, the inner procedure will not be expanded.

The indentation as set in the expansion of the alias is preserved when the alias is expanded. All the lines will be indented the same amount to the right as the alias name. You can override this default behavior by selecting the check button Indent source editor after expansion. In this case, GPS will replace the name of the alias by its expansion, and then automatically recompute the position of each line with its internal indentation engine, as if the text had been inserted manually.

The third part of the aliases editor, at the top right corner, lists the parameters for the currently selected alias. Any time you insert a %(name) string in the expansion text, GPS automatically detects there is a new parameter reference (or an old reference has changed name or was removed); the list of parameters is automatically updated to show the current list.

Each parameters has three attributes:

name

This is the name you use in the expansion text of the alias in the %(name) special entity.

Environment

This specifies whether the default value of the parameter comes from the list of environment variables set before GPS was started.

default value

Instead of getting the default value from the environment variable, you can also specify a fixed text. Clicking on the initial value of the currently selected variable opens a text entry which you can use to edit this default value.

When an alias that contains parameters is expanded, GPS will first display a dialog to ask for the value of the parameters. You can interactively enter this value, which replaces all the %(name) entities in the expansion text.

16.5.14 Aliases files

The customization files described earlier can also contain aliases definition. This can be used for instance to create project or system wide aliases. All the customization files will be parsed to look for aliases definition.

All these customization files are considered as read-only by GPS, and therefore cannot be edited through the graphical interface. It is possible to override some of the aliases in your own custom files.

There is one specific files, which must contain only aliases definition. This is the file $HOME/.gps/aliases. Whenever you edit aliases graphically, or create new ones, they are stored in this file, which is the only one that GPS will ever modify automatically.

The system files are loaded first, and aliases defined there can be overridden by the user-defined file.

These files are standard XML customization files. The specific XML tag to use is <alias>, one per new alias. The following example contains a standalone customization file, but you might wish to merge the <alias> tag in any other customization file.

The following tags are available:

alias

This indicates the start of a new alias. It has one mandatory attribute, name, which the text to type in the source editor before pressing <control-o>. It has one optional attribute, indent, which, if set to true, indicate that GPS should recompute the indentation of the newly inserted paragraph after the expansion.

param

These are children of the alias node. There is one per parameter of the alias. They have one mandatory attribute, name, which is the name to type between %(name) in the alias expansion text.

They have one optional attribute, environment, which indicates the default value must be read from the environment variables if it is set to true.

These tags contain text, which is the default value for the parameter.

text

This is a child of the alias node, whose value is the replacement text for the alias.

Here is an example of an alias file:

     <?xml version="1.0"?>
     <Aliases>
       <alias name="proc" >
         <param name="p" >Proc1</param>
         <param environment="true" name="env" />
         <text>procedure %(p) is
     %(env)%_
     end %(p);</text>
       </alias>
     </Aliases>