Using the GNAT Programming System: Customizing and Extending GPS

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

# 15. Customizing and Extending GPS

> 15.1 The Preferences Dialog |  |
> 15.2 Customizing the Menu and Tool Bar |  |
> 15.3 Adding Support for New Languages |  |
> 15.4 Defining Text Aliases |  |
> 15.5 Defining New Styles and Key Bindings |  |
> 15.6 Scripting GPS |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 15.1 The Preferences Dialog

This dialog, available through the menu `Edit->Preferences`, allows you to modify the global preferences of GPS. To enable the new preferences, you simply need to confirm by pressing the `OK` button. To test your changes, you can use the `Apply` button. Pressing the `Cancel` button will undo all your changes.

Each preference is composed of a label displaying the name of the preference, and an editing area to modify its value. If you leave to mouse over the label, a tool tip will be displayed giving an on-line help on the preference.

The preferences dialog is composed of eight areas, accessible through the tabs at the left of the dialog, labeled General, Editor, Debugger, Helpers, Browsers, Visual Diff, Messages and Project. Each page corresponds to a section of preferences.

- General

  The general preferences are composed of two pages available at the top of the right area: General and Windows

  General

    Default font
      The default font used in GPS

    Key theme
      Name of key theme to use. The key themes determines the key bindings used by the various visual objects, in particular the source editor. Values currently supported are `Emacs` and `Default`

    Character set
      Name of character set to use for displaying text. The default value is ISO-8859-1, which corresponds to Latin-1 (Western European) characters.

    Dynamic key bindings
      Whether the menu key bindings can be changed interactively. See Redefining key bindings.

    Display splash screen
      Whether a splash screen should be displayed when starting GPS.

    Display welcome window
      Whether GPS should display the welcome window for the selection of the project to use.

    Show text in tool bar
      Whether the tool bar should show both text and icons, or only icons.

    Auto save
      Whether unsaved files and projects should be saved automatically before calling external tools (e.g. before a build).

    Save desktop on exit
      Whether the desktop (size and positions of all windows) should be saved when exiting.

    Aliases key
      Key to press to expand an alias in a source editor or a text entry anywhere in GPS.

  Windows
    This section specifies preferences that apply to the Multiple Document Interface described in 4. Multiple Document Interface.

    Opaque
      If True, items will be resized or moved opaquely when not maximized.

    Destroy floats
      If False, closing the window associated with a floating item will put the item back in the main GPS window, but will not destroy it. If True, the item is destroyed.

    All floating
      If True, then all the windows will be floating by default, i.e. be under the control of your system (Windows) or your window manager (Unix machines). This replaces the MDI.

    Background color
      Color to use for the background of the MDI.

    Title bar color
      Color to use for the title bar of unselected items.

    Selected title bar color
      Color to use for the title bar of selected items.

    Select Window
      The key shortcut used to switch between windows.

- Editor
  General

    Strip blanks
      Whether the editor should remove trailing blanks when saving a file.

    Line terminator
      Choose between Unix, Windows and Unchanged line terminators when saving files. Choosing Unchanged will use the original line terminator when saving the file; Unix will use LF line terminators; Windows will use CRLF line terminators.

    Display line numbers
      Whether the line numbers should be displayed in file editors.

    Tooltips
      Whether tool tips should be displayed automatically.

    Highlight delimiters
      Whether matching delimiters should be highlighting. The list of delimiters include: `{}[]()`

    Autosave delay
      The period (in seconds) after which a source editor is automatically saved. 0 if none.

      Each modified file is saved under a file called `.#filename`, which is removed on the next explicit save operation.

    Column highlight
      The column number to highlight and draw in the editors. 0 if none.

    External editor
      The default external editor to use.

    Custom editor command
      Specify the command line for launching a custom editor. It is assumed that the command will create a new window/terminal as needed. If the editor itself does not provide this capability (such as vi or pico), you can use an external terminal command, e.g:

          xterm -geometry 80x50 -exec vi +%l %f

      The following substitutions are provided:

      `%l`
        line to display

      `%c`
        column to display

      `%f`
        full pathname of file to edit

      `%e`
        extended lisp command

      `%p`
        top level project file name

      `%%`
        percent sign ('%')

    Always use external editor
      True if all editions should be done with the external editor. This will deactivate completely the internal editor. False if the external editor needs to be explicitly called by the user.

  Fonts & Colors

    Keywords
      Font and colors used to highlight keywords.

    Current line color
      Color for highlighting the current line. Leave it to blank for no highlighting. Setting the color to white will set a transparent color.

    Current block color
      Color for highlighting the current source block. Setting the color to white will disable the block highlighting (recommended on slow machines).

    Comments
      Font and colors used to highlight comments. Setting the color to white will set a transparent color.

    Strings
      Font and colors used to highlight strings. Setting the color to white will set a transparent color.

    Line highlighting color
      Color for highlighting lines.

    Default font
      The font used in the source editor.

  Ada

    Auto indentation
      How the editor should indent Ada sources. None means no indentation; Simple means that indentation from the previous line is used for the next line; Extended means that a language specific parser is used for indenting sources.

    Use tabulations
      Whether the editor should use tabulations when indenting.

    Default indentation
      The number of spaces for the default Ada indentation.

    Continuation lines
      The number of extra spaces for continuation lines.

    Declaration lines
      The number of extra spaces for multiple line declarations. For example, using a value of 4, here is how the following code would be indented:

          variable1,
              variable2,
              variable3 : Integer;

    RM style case indentation
      Whether GPS should indent case statements with an extra level, as used in the Ada Reference Manual, e.g:

          case Value is
             when others =>
                null;
          end case;

      If this preference is set to `False`, this would be indented as:

          case Value is
          when others =>
             null;
          end case;

  C/C++

    Auto indentation
      How the editor should indent C/C++ sources. None means no indentation; Simple means that indentation from the previous line is used for the next line; Extended means that a language specific parser is used for indenting sources.

    Use tabulations
      Whether the editor should use tabulations when indenting. If True, the editor will replace each occurrence of eight characters by a tabulation character.

    Default indentation
      The number of spaces for the default indentation.

  Keys

    Auto-indentation
      Key used for auto-indenting lines or block of lines.

    Completion
      Key used for automatic completion of identifiers.

    Jump to delimiter
      Key used for moving the cursor to the corresponding delimiter. Delimiters include parentheses, brackets, and braces.

- Debugger
  General

    Color highlighting
      Color used for highlighting in the debugger console.

    Break on exceptions
      Specifies whether a breakpoint on all exceptions should be set by default when loading a program.

    Execution window
      Whether the debugger should create a separate execution window for the program debugged. If true, a separate console will be created. Under Unix systems, this console is another window in the bottom part of the main window; under Windows, this is a separate window created by the underlying gdb, since Windows does not have the notion of separate terminals (aka ttys).

      Note that in this mode under Windows, the `Debug->Interrupt` menu will not interrupt the debugged program. Instead, you need to hit `Ctrl-C` in the separate execution window to interrupt it while it is running.

      If false, no execution window will be created. The debugger assumes that the program being debugged does not require input, or that if it does, input is handled outside GPS. For example, when you attach to a running process, this process already has a separate associated terminal.

    Show lines with code
      Specifies whether blue dots should be displayed in the source editor for lines that contain code. If set to False, gray dots will be displayed instead on each line, allowing breakpoint on any line. Disabling this option provides a faster feedback, since GPS does not need to query the debugger about which lines contain code.

  Assembly
    Current assembly line
      Color used to highlight the assembly code for the current line.

    Range size
      Number of assembly lines to display in the initial display of the assembly window. If the size is 0, then the whole subprogram is displayed, but this can take a very long time on slow machines.

  Data
    Lets you change the preferences of the Data Window, in particular the fonts and colors used to display the data graphically.

    Clickable item
      Indicates color to be used for the items that are click-able (e.g pointers).

    Changed data
      Indicates color to be used to highlight fields that have changed since the last update.

    Item name
      Indicates font to be used for the name of the item.

    Item type
      Indicates font to be used to display the type of the item.

    Detect aliases
      If enabled, do not create new items when an item with the same address is already present on the canvas.

  Memory
    Default color
      Color used by default in the memory view window.

    Color highlighting
      Color used for highlighted items.

    Selection
      Color used for selected items.

- Helpers
  List processes
    Command used to list processes running on the machine.

  Remote shell
    Program used to run a process on a remote machine. You can specify arguments, e.g. `rsh -l user`

  Remote copy
    Program used to copy a file from a remote machine. You can specify arguments, e.g. `rcp -l user`

  Execute command
    Program used to execute commands externally.

  Print command
    Program used to print files. By default `a2ps`, available under GNU/Linux systems. This utility can be used on most Unix systems, and can be downloaded from http://www.inf.enst.fr/~demaille/a2ps

    Under Windows systems, a possible replacement is the PrintFile freeware utility which is available from http://www.lerup.com/printfile/descr.html

- Browsers
  General

    Selected item color
      Color to use to draw the selected item.

    Background color
      Color used to draw the background of the browsers.

    Hyper link color
      Color used to draw the hyper links in the items.

    Selected link color
      Color to use for links between selected items.

    Default link color
      Color used to draw the links between unselected items.

    Ancestor items color
      Color to use for the background of the items linked to the selected item.

    Offspring items color
      Color to use for the background of the items linked from the selected item.

    Vertical layout
      Whether the layout of the graph should be vertical (True) or horizontal (False).

  File Dependencies

    Show system files
      Whether the system files (Ada runtime or standard C include files) should be visible in the browser.

    Show implicit dependencies
      If False, then only the explicit dependencies are shown in the browser. Otherwise, all dependencies, even implicit, are displayed.

- Visual diff
  Context length
    The number of lines displayed before and after each chunk of differences. Specifying -1 will display the whole file.

  Diff command
    Command used to compute differences between two files. Arguments can also be specified. The visual diff expects a standard diff output with no context (that is, no `-c` nor `-u` switch). Arguments of interest may include (this will depend on the version of diff used):

    -b
      Ignore changes in amount of white space.

    -B
      Ignore changes that just insert or delete blank lines.

    -i
      Ignore changes in case; consider upper and lower case letters equivalent.

    -w
      Ignore white space when comparing lines.

  Patch command
    Command used to apply a patch. Arguments can also be specified.

- Messages
  Color highlighting
    Color used to highlight text in the messages window.

  Color highlighting
    Color used to highlight lines causing compilation errors/warnings in the source editors. When this color is set to white, the errors/warnings are not highlighted. (9. Compilation/Build)

  Show build progress
    Whether the progress bar should show progress during builds.

  File pattern
    Pattern used to detect file locations from the messages window. This is particularly useful when using an external tool such as a compiler or a search tool, so that GPS will highlight and allow navigation through source locations. This is a standard system V regular expression containing two or three parenthesized subexpressions corresponding to the file, line and column patterns.

  File index
    Index of filename in the file pattern.

  Line index
    Index of the line number in the file pattern.

  Column index
    Index of the column number in the file pattern.

- Project
  Relative paths
    Whether paths should be absolute or relative when the projects are modified.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 15.2 Customizing the Menu and Tool Bar

You can customize the GPS menu bar in two different ways: you can redefine or add new key bindings to the existing menu items, and you can define new menu items.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.2.1 Redefining key bindings

In order to define or redefine key bindings, you first need to enable the dynamic key binding feature in the Preferences dialog. See Dynamic key bindings.

Then, you can simply navigate through the menus, and type the key binding you want to associate to a particular item. To remove a key binding, use the `Backspace` key. Your changes will be saved when GPS exits, in a file called ``$HOME/.gps/custom_keys'`. In particular, this means that if for some reason you need to edit the file manually, you need to do it outside of GPS, or save the file under a different name, and rename it after exiting GPS.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.2.2 Adding menu items

The GPS menu bar can be customized through an XML file put under the directory ``$HOME/.gps/customize'` on Unix systems, and ``%HOME%\.gps\customize'` on Windows systems. Any file in the ``customize'` directory will be loaded by GPS at start up. Alternatively, you can also put system wide customization files under the directory ``<INSTALL>/share/gps/customize'`, where ``<INSTALL>'` is the name of the GPS installation directory.

Here is an example for such a file:

    <?xml version="1.0"?>
    <Custom>
      <Submenu>
        <Title>custom menu</Title>
        <Menu_Item>
        <Title>item 1</Title>
          <Action>external-command 1</Action>
        </Menu_Item>

        <Submenu>
          <Title>other menu</Title>
          <Menu_Item>
            <Title> (etc..)
          </Menu_Item>

          <Submenu>
            (...)
          </Submenu>
        </Submenu>
      </Submenu>
    </Custom>

The example above creates a top-level menu named `custom menu`. This menu contains a menu item named `item 1`, which is associated to the shell command `external-command 1`, a sub menu named `other menu`, etc...

Note for Windows users: like under UNIX, scripts can be called from custom menu. In order to do that, you must write your script in a ``.bat'` or ``.cmd'` file, and call this file using `cmd /c`. Thus, the `Action` tag would look like:

    <Action>cmd /c c:\.gps\my_scripts\my_command.cmd</Action>

As well as external commands, you can use custom menu items to invoke GPS commands using the `GPS_Action` tag. The following example shows how to create a menu to invoke the `help` interactive command and to open the file ``main.c'`.

    <Submenu>
      <Title>Edit</Title>
      <Menu_Item>
        <Title>List GPS commands</Title>
        <GPS_Action>help</GPS_Action>
      </Menu_Item>
      <Menu_Item>
        <Title>Edit main.c</Title>
        <GPS_Action>edit main.c</GPS_Action>
      </Menu_Item>
    </Submenu>

See below for more information on this `GPS_Action` tag.

You can define the accelerator keys for your menus, using underscores in the titles. Thus, if you want an accelerator on the first letter in a menu named `File`, set its title as `_File`.

You can add items or sub menus to existing menus, using titles for menus that already exist. For example, this adds an item named `Robert` to the `Edit` menu.

    <Submenu>
      <Title>Edit</Title>
      <Menu_Item>
        <Title>Robert</Title>
      </Menu_Item>
    </Submenu>

Use the `/` separator to identify the sub menu in a menu. For example, this adds a sub menu named `Olga` containing an item named `Item` to the `Edit` menu.

    <Submenu>
      <Title>Edit/Olga</Title>
      <Menu_Item>
        <Title>Item</Title>
      </Menu_Item>
    </Submenu>

Adding an item with an empty title or no title at all inserts a menu separator.

The following tags are available in a `Submenu` section:

`Title`
  Found inside a `Submenu` or `Menu_Item`: set title of the submenu or menu item.

`Menu_Item`
  A menu item inside a submenu.

`Action`
  External command associated with a menu item.

`GPS_Action`
  GPS specific command associated with a menu item. This is a command written in one of the shell scripts supported by GPS. You can specify the language as an attribute of the XML node. The name of the attribute is `lang`. The default value for this attribute is `shell`, i.e. the command is written with the GPS shell.

  When programming with the GPS shell, you can execute multiple commands by separating them with semicolons. Therefore, the following example adds a menu which lists all the files used by the current file, in a project browser. Note: due to some current limitation of the parsing of the custom files, the '%' argument must be surrounded by spaces, as shown in the example.

      <Menu_Item>
        <Title>Current file uses</Title>
        <GPS_Action lang="shell">File %f ; File.uses $1</GPS_Action>
      </Menu_Item>

  It is possible to mix both shell commands and external commands. For instance, the following command opens an xterm (on Unix systems only) in the current directory, which depends on the context.

      <Menu_Item>
        <Title>_Xterm in current directory</Title>
        <GPS_Action lang="shell">cd %d</GPS_Action>
        <Action>xterm</Action>
      </Menu_Item>

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.2.3 Adding tool bar buttons

As an alternative to creating new menu items, you can create new buttons on the tool bar, with exactly the same syntax, by using the `<Toolbar_Item>` tag in place of the `<Submenu>` tag. Within this tag, the tag `<Pixmap>` can be used to indicate the location of an image file (of the type `jpeg, png, gif` or `xpm`) to be used as icon for the button. An empty `<Toolbar_Item>` tag indicates a separator in the tool bar.

    <Toolbar_Item>
      <Title>Custom Button</Title>
      <Pixmap>/my_pixmaps/button.jpg</Pixmap>
      <GPS_Action>my gps command</GPS_Action>
    </Toolbar_Item>

The following tags are available in a `Toolbar_Item` section:

`Title`
  Name of the custom button.

`Pixmap`
  Pixmap file associated with the tool bar button.

`Action`
  External command associated with a tool bar button.

`GPS_Action`
  GPS specific command associated with a tool bar button.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.2.4 Macro arguments

When using an `Action` node in a menu or tool bar item, you can use macro arguments to pass to your shell commands. Macro arguments are special parameters that are transformed every time the command is executed. The following macro arguments are provided:

`%f`
  Base name of the currently opened file.

`%F`
  Absolute name of the currently opened file.

`%p`
  The current project. This is the name of the project, not the project file.

`%pp`
  The current project file pathname.

`%PP`
  The root project pathname.

`%(p|P)[r](d|s)[f]`
  Substituted by the list of sources or directories of a given project:

  `P`
    the root project.

  `p`
    the selected project, or the root project if there is no project selected.

  `r`
    recurse through the projects: sub projects will be listed as well as their sub projects, etc...

  `d`
    list the source directories.

  `s`
    list the source files.

  `f`
    output the list into a file and substitute the parameter with the name of that file.

Examples:

`%Ps`
  Replaced by a list of source files in the root project.

`%prs`
  Replaced by a list of files in the current project, and all imported sub projects, recursively.

`%prdf`
  Replaced by the name of a file that contains a list of source directories in the current project, and all imported sub projects, recursively.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 15.3 Adding Support for New Languages

You can define new languages in a custom file by using the `Language` tag. Defining languages gives GPS the ability to highlight the syntax of a file, explore a file (using e.g. the project explorer), and find files associated with a given language.

As described previously for menu items, any file in the ``customize'` directory will be loaded by GPS at start up.

The following tags are available in a `Language` section:

`Name`
  A short string describing the name of the language.

`Spec_Suffix`
  A string describing the suffix of spec/definition files for this language. If the language does not have the notion of spec or definition file, you can ignore this value.

`Body_Suffix`
  A string describing the suffix of body/implementation files for this language.

`Keywords`
  A V7 style regular expression for recognizing and highlighting keywords. Multiple `Keywords` tags can be specified, and will be concatenated into a single regular expression.

  The full grammar of the regular expression can be found in the spec of the file ``g-regpat.ads'` in the GNAT run time.

`Context`
  Describes the context used to highlight the syntax of a file.

  `Comment_Start`
    A string defining the beginning of a multiple-line comment.

  `Comment_End`
    A string defining the end of a multiple-line comment.

  `New_Line_Comment_Start`
    A string defining the beginning of a single line comment (ended at the next end of line).

  `String_Delimiter`
    A character defining the string delimiter.

  `Quote_Character`
    A character defining the quote character, used for e.g. canceling the meaning of a string delimiter (`\` in C).

  `Constant_Character`
    A character defining the beginning of a character literal.

  `Can_Indent`
    A boolean indicating whether indentation should be enabled for this language. The indentation mechanism used will be the same for all languages: the number of spaces at the beginning of the current line is used when indenting the next line.

  `Syntax_Highlighting`
    A boolean indicating whether the syntax should be highlighted/colorized.

  `Case_Sensitive`
    A boolean indicating whether the language (and in particular the identifiers and keywords) is case sensitive.

`Categories`
  Optional node to describe the categories supported by the project explorer for the current language. This node contains a list of `Category` nodes, each describing the characteristics of a given category, with the following nodes:

  `Name`
    Name of the category, which can be one of: package, namespace, procedure, function, task, method, constructor, destructor, protected, entry, class, structure, union, type, subtype, variable, local_variable, representation_clause, with, use, include, loop_statement, case_statement, if_statement, select_statement, accept_statement, declare_block, simple_block, exception_handler.

  `Pattern`
    Regular expression used to detect a language category. As for the `Keywords` node, multiple `Pattern` tags can be specified and will be concatenated into a single regular expression.

  `Index`
    Index in the pattern used to extract the name of the entity contained in this category.

Here is an example of a language definition for the GPS project files:

    <?xml version="1.0"?>
    <Custom>
      <Language>
        <Name>Project File</Name>
        <Spec_Suffix>.gpr</Spec_Suffix>

        <Keywords>^(case|e(nd|xte(nds|rnal))|for|is|</Keywords>
        <Keywords>limited|null|others|</Keywords>
        <Keywords>p(ackage|roject)|renames|type|use|w(hen|ith))\b</Keywords>

        <Context>
          <New_Line_Comment_Start>--</New_Line_Comment_Start>
          <String_Delimiter>"</String_Delimiter>
          <Constant_Character>'</Constant_Character>
          <Can_Indent>True</Can_Indent>
          <Syntax_Highlighting>True</Syntax_Highlighting>
          <Case_Sensitive>False</Case_Sensitive>
        </Context>

        <Categories>
          <Category>
            <Name>package</Name>
            <Pattern>^[ \t]*package[ \t]+((\w|\.)+)</Pattern>
            <Index>1</Index>
          </Category>
          <Category>
            <Name>type</Name>
            <Pattern>^[ \t]*type[ \t]+(\w+)</Pattern>
            <Index>1</Index>
          </Category>
        </Categories>
      </Language>
    </Custom>

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 15.4 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, 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, 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).

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.

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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.4.1 Aliases files

GPS manages multiple aliases files. One of them is editable interactively by the user through the `Edit->Aliases` menu, whereas all the others are defined system-wide, and are not editable interactively.

The user-defined file is ``$HOME/.gps/aliases'`.

The system files are all the files stored in the directory ``<prefix>/share/gps/aliases'`, where ``<prefix>'` is the path in which GPS was installed. The aliases defined in these files are read-only, and indicated as such in the aliases editor.

All the files have the same XML format, which can be seen in the following example. Each alias has its own <alias> tag.

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

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`.

`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.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 15.5 Defining New Styles and Key Bindings

In addition to the preferences dialog, GPS can be configured through the Gtk+ mechanism of ``RC files'`. You can create a text file called ``gtkrc'` in the gps home directory (``~/.gps'` on Unix systems), or as a global change, in the directory etc/gps in the GPS installation.

This file follows the Gtk+ resource file syntax and gives the possibility in particular to define a number of styles and key bindings and attach them to particular visual objects such as text editors, menu items, ...

For example, you can set `Ctrl-v` in the source editors to scroll forward one page. The following code defines this new key binding:

    # Create new key bindings for text editors
    binding "custom-text-key"
    {
       # define Ctrl-v to scroll forward one page
       bind "<ctrl>v" { "move-cursor" (pages, 1, 0) }
    }

    # Associate the new binding created above with text editors
    class "GtkTextView" binding "custom-text-key"

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.5.1 Toplevel declarations

An RC file is a text file which is composed of a sequence of declarations. All the literals are case sensitive; `#` characters delimit comments and the portion of a line after a `#` is ignored when parsing an RC file. The syntax of the top-level declarations is described below. Opening/closing brackets on the same line ({ ... }) are used to represent a sequence of 0 or more elements. Brackets on their own line are real bracket characters.

    toplevel-declarations ::=
       { declaration }

    declaration ::=
       include-file | pixmap-path | style-definition | binding-definition |
       enable-resource

    include-file ::=
       include string_literal

    pixmap-path ::=
       pixmap_path string_literal

    style-definition ::=
       style resource-name [ = parent ]
       {
          sequence-of-style
       }

    binding-definition ::=
       binding resource-name
       {
          sequence-of-binding
       }

    enable-resource ::=
       class "widget-name" (binding | style) resource-name

    resource-name ::=
       string_literal

The table below describes the meaning of each of these toplevel declarations:

`include filename`
  Parses another file at this point. If filename is not an absolute filename, it is searched in the directories of the currently open RC file.

`pixmap_path path`
  Sets a path (a list of directories separated by colons) that will be searched for pixmaps referenced in RC files.

`style name [ = parent ] { ... }`
  Declares a style. If parent is specified, name inherits its default attributes from parent. You can specify "default" to designate the default style, e.g:

      style "my-style" = "default" { ... }

  See Defining new styles for more details.

`binding name { ... }`
  Declares a binding set. See Defining new key bindings for more details.

`class widget-name (binding | style) name`
  Specifies a binding or style set for a particular set of visual objects.

`resource-name`
  An arbitrary user defined name.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.5.2 Defining new styles

A RC style is specified by a style declaration in a RC file, and then bound to visual objects with a class declaration. Within each type of declaration, later declarations override earlier ones.

For example, the following code will change the background color of any button, when it is pressed. It will also set a background pixmap when it is not pressed. The style also inherits from the one above, so that the buttons also use the default font.

    pixmap_path "directory_that_contains_the_pixmap"
    style "custom-button" = "default"
    {
      bg_pixmap[NORMAL]="pixmap_file"
      bg[ACTIVE]="blue"
    }
    class "GtkButton" style "custom-button"

Here is the syntax for defining styles:

    sequence-of-style ::=
       { style | property }

    style ::=
       style-name[state] = string_literal

    style-name ::=
       bg | fg | base | text | bg_pixmap | font_name

    state ::=
       NORMAL | ACTIVE | PRELIGHT | SELECTED | INSENSITIVE

    property ::=
       widget-name::widget-property = value

    widget-property ::=
       cursor-aspect-ratio | cursor-color

The table below describes the meaning of each of these elements:

`bg[state] = color`
  Sets the color used for the background of most visual objects.

`fg[state] = color`
  Sets the color used for the foreground of most visual objects.

`base[state] = color`
  Sets the color used for the background of visual objects displaying editable text, for instance the text editor in GPS.

`text[state] = color`
  Sets the color used for foreground of visual objects using base for the background color.

`bg_pixmap[state] = pixmap`
  Sets a background pixmap to be used in place of the bg color. The special value "<parent>" may be used to indicate that the visual object should use the same background pixmap as its parent. The special value "<none>" may be used to indicate no background pixmap.

`font_name = font`
  Sets the font for a visual object. Font is a font name as listed in the font selector in the preferences dialog, e.g. "Sans Italic 10".

`GtkTextView::cursor-aspect-ratio = value`
  Width ratio with which to draw the insertion cursor. Value is a float value between 0.0 and 1.0. The default value is 0.04.

`GtkTextView::cursor-color = color`
  Color with which to draw insertion cursor

The colors and background pixmaps are specified as a function of the state of the visual object. The states are:

`NORMAL`
  A color used for a visual object in its normal state.

`ACTIVE`
  A variant of the NORMAL color used when the visual object is in the active state, and also for the trough of a ScrollBar, tabs of a NoteBook other than the current tab and similar areas. Frequently, this should be a darker variant of the NORMAL color.

`PRELIGHT`
  A color used for visual objects in the PRELIGHT state. This state is used for Buttons and MenuItems that have the mouse cursor over them, and for their children.

`SELECTED`
  A color used to highlight data selected by the user. For instance, the selected items in a list object, and the selection in an editable object.

`INSENSITIVE`
  A color used for the background of visual objects that have been set insensitive.

Colors can be specified as a string containing a color name (under Unix systems, GTK+ knows all names from the X color database /usr/lib/X11/rgb.txt), in one of the hexadecimal forms `#rrrrggggbbbb`, `#rrrgggbbb`, `#rrggbb`, or `#rgb`, where r, g and b are hex digits, or they can be specified as a triplet `{r, g, b}`, where r, g and b are either integers in the range 0-65535 or floats in the range 0.0-1.0.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.5.3 Defining new key bindings

Key bindings allow you to specify actions to be taken on a given key press. The syntax to define new key bindings is described below.

    sequence-of-binding ::=
       { binding }

    binding ::=
       bind "key-name"
       {
          sequence-of-commands
       }

    sequence-of-commands ::=
       { command }

    command ::=
       "command-kind" (parameters)

    parameters ::=
       [first-parameter {, number}]

    widget-name ::=
       GtkButton | GtkDialog | GtkEntry | GtkMenuItem |
       GtkMenuShell | GtkTextView | GtkTreeView

    command-kind ::=
       move-cursor | page-horizontally | set-anchor | insert-at-cursor |
       delete-from-cursor | cut-clipboard | copy-clipboard | paste-clipboard |
       toggle-overwrite | move-focus | activate | select-all | unselect-all |
       select-cursor-row | toggle-cursor-row | expand-collapse-cursor-row |
       select-cursor-parent | start-interactive-search | clicked | close |
       move-current

    first-parameter ::=
       movement-step | count | extend-selection | delete-type | start-editing |
       logical | expand | expand-all | menu-direction | string_litteral

    number ::=
       [-|+]digit{digit}

    key-name ::=
       {modifier}key

    modifier ::=
       <ctrl> | <alt> | <shift>

    key ::=
       letter | digit |
       BackSpace | Tab | Return | Pause | Scroll_Lock | Sys_Req | Escape |
       Delete | Home | Left | Up | Right | Down | Page_Up | Page_Down | End |
       Insert | Break | Num_Lock |
       F1 | F2 | F3 | F4 | F5 | F6 | F7 | F8 | F9 | F10 | F11 | F12 |
       Caps_Lock | space | exclam | quotedbl | numbersign | dollar | percent |
       ampersand | apostrophe | quoteright | parenleft | parenright | asterisk |
       plus | comma | minus | period | slash | colon | semicolon | less |
       equal | greater | question | at | bracketleft | backslash |
       bracketright | underscore | grave | quoteleft | braceleft | bar |
       braceright

The list of valid `command-kind` values and their parameters depend on the widget name:

`GtkButton`
  Applies to buttons.
  `clicked ()`
    Generate a button click event.

`GtkDialog`
  Applies to dialog windows.
  `close ()`
    Close the current dialog box.

`GtkEntry`
  Applies to single line text entries.
  `activate ()`
    Activate the text entry.
  `move-cursor (movement-step, count, extend-selection)`
    Move insertion point by count steps. If extend-selection is true, create or extend the selection.
  `insert-at-cursor (string)`
    Insert a given text string at the cursor.
  `delete-from-cursor (delete-type, count)`
    Delete count units from the cursor.
  `cut-clipboard ()`
    Cut the current selection to the clipboard.
  `copy-clipboard ()`
    Copy the current selection to the clipboard.
  `paste-clipboard ()`
    Paste the contents of the clipboard.
  `toggle-overwrite ()`
    Toggle the current overwrite mode.

`GtkMenuItem`
  Applies to menu items.
  `activate ()`
    Activate the menu item.

`GtkMenuShell`
  Applies to menus.
  `move-current (menu-direction)`
    Move the current menu entry to the given direction.

`GtkTextView`
  Applies to source and text editors.
  `move-cursor (movement-step, count, extend-selection)`
    Move insertion point by count steps. If extend-selection is true, create or extend the selection.
  `page-horizontally (count, extend-selection)`
    Move cursor to the beginning (count=-1) or the end (count=1) of the current line.
  `set-anchor ()`
    Move the anchor to the cursor position.
  `insert-at-cursor (string)`
    Insert a given text string at the cursor.
  `delete-from-cursor (delete-type, count)`
    Delete count units from the cursor.
  `cut-clipboard ()`
    Cut the current selection to the clipboard.
  `copy-clipboard ()`
    Copy the current selection to the clipboard.
  `paste-clipboard ()`
    Paste the contents of the clipboard.
  `toggle-overwrite ()`
    Toggle the current overwrite mode.

`GtkTreeView`
  Applies to tree and list objects, in particular the Location Tree, the Project View, the File View and the VCS Explorer.
  `move-cursor (movement-step, count)`
    Move insertion point.
  `select-all ()`
    Select all rows.
  `unselect-all ()`
    Unselect all rows.
  `select-cursor-row (start-editing)`
    Select or unselect the current row.
  `toggle-cursor-row ()`
    Toggle the selection of the current row.
  `expand-collapse-cursor-row (logical, expand, expand-all)`
    Expand (expand=1) or collapse (expand=0) the current row. If expand-all=1, also expand all children recursively. Parameter logical currently ignored.
  `select-cursor-parent ()`
    Select the parent row of the current selection.
  `start-interactive-search ()`
    @cindex interactive search Start interactive search on the tree view. This will open a small window at the bottom of the tree view where you can interactively type names. The first matching name in the tree will be selected while you type it. You can then also use the `up` and `down` keys to navigate through all the items matching the current text.

The possible values of the parameters listed above are:

`count`
  Signed integer value.

`string`
  Quoted string, e.g "text".

`extend-selection, start-editing, logical, expand, expand-all:`
  Boolean value. 0 means false, 1 means true.

`delete-type`
  `chars`
    Delete a given amount of characters.
  `word-ends`
    Delete only the portion of the word to the left/right of cursor if we're in the middle of a word.
  `paragraph-ends`
    Delete between cursor and the end (count=1) or beginning (count=-1) of current line.
  `paragraphs`
    Delete whole line.
  `whitespace`
    Delete all white spaces around the cursor.

`menu-direction`
  `parent`
    Select the parent menu item.
  `child`
    Select the first child menu item.
  `next`
    Select the next (sibling) menu item.
  `prev`
    Select the previous (sibling) menu item.

`movement-step`
  `logical-positions`
    Move by forward/back graphemes.
  `visual-positions`
    Move by left/right graphemes.
  `words`
    Move by forward/back words.
  `display-lines`
    Move up/down lines (wrapped lines).
  `display-line-ends`
    Move to either end of a line (wrapped lines).
  `paragraphs`
    Move up/down paragraphs (newline-ended lines).
  `paragraph-ends`
    Move to either end of a paragraph.
  `pages`
    Move by pages.
  `buffer-ends`
    Move to the end (count=1) or to the beginning (count=-1) of the file.

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

## 15.6 Scripting GPS

> 15.6.1 Scripts |  |
> 15.6.2 The GPS Shell |  |

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.6.1 Scripts

Scripts are small programs that interact with GPS and allow you to perform complex tasks repetitively and easily. GPS includes support for two scripting languages currently, although additional languages might be added in the future. These two languages are described in the following section.

Support for scripting is currently work in progress in GPS. As a result, not many commands are currently exported by GPS, although their number is increasing daily. These commands are similar to what is available to people who extend GPS directly in Ada, but with a strong advantage: they do not require any recompilation of the GPS core, and can be tested and executed interactively.

The goal of such scripts is to be able to help automate processes such as builds, automatic generation of graphs,...

All the scripting languages share the same set of commands exported by GPS, thanks to a abstract interface defined in the GPS core. As a result, GPS modules do not have to be modified when new scripting languages are added.

Scripts can be executed immediately upon startup of GPS by using the command line switch `--load`. Specifying the following command line:

    gps --load=shell:mytest.gps

will force the gps script ``mytest.gps'` to be executed immediately, before GPS starts reacting to user's requests. This is useful if you want to do some special initializations of the environment. It can also be used as a command line interface to GPS, if you script's last command is to exit GPS.

In line commands can also be given directly on the command line through `--eval` command line switch.

For instance, if you want to analyze an entity in the entity browser from the command line, you would pass the following command switches:

    gps --eval=shell:'Entity entity_name file_name; Entity.show %1'

[ < ] | [ > ] |  | [ << ] | [ Up ] | [ >> ] |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

### 15.6.2 The GPS Shell

The GPS shell is a very simple-minded, line-oriented language. It is accessible through the `Shell` window at the bottom of the GPS window. It is similar to a Unix shell, or a command window on Windows systems.

Type `help` at the prompt to get the list of available commands, or `help` followed by the name of a command to get more information on that specific command.

The following example shows how to get some information on a source entity, and find all references to this entity in the application. It searches for the entity "entity_name", which has at least one reference anywhere in the file "file_name.adb". After the first command, GPS returns an identifier for this entity, which can be used for all commands that need an entity as a parameter, as is the case for the second command. When run, the second command will automatically display all matching references in the location window.

    GPS> Entity my_entity file_name.adb
    <Entity_0x09055790>
    GPS> Entity.find_all_refs <Entity_0x09055790>

Since the GPS shell is very simple, it doesn't provide any reference counting for the result types. As a result, all the values returned by a command, such as `<Entity_0x09055790>` in the example above, are kept in memory.

The GPS shell provides the command `clear_cache` which removes all such values from the memory. After this command is run, you can no longer use references obtained from previous commands, although of course you can run these commands again to get a new reference.

The return value of the 9 previous commands can easily be recalled by passing `%1`, `%2`,... on the command line. For instance, the previous example could be rewritten as

    GPS> Entity my_entity file_name.adb
    <Entity_0x09055790>
    GPS> Entity.find_all_refs %1

These return values will be modified also for internal commands sent by GPS, so you should really only use this when you emit multiple commands at the same time, and don't do any other action in GPS. This is mostly useful when used for command-line scripts (see `--eval` and `--load`), or for custom files, See section 15.2 Customizing the Menu and Tool Bar.

In future versions of GPS, it will be possible to use more advanced scripting languages such as `Python`.

[ << ] | [ >> ] |  |  |  |  |  | [Top] | [Contents] | [Index] | [ ? ]

This document was generated by Mail Server on June, 15 2003 using texi2html