[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.
The general preferences are composed of two pages available at the top of the right area: General and Windows
Emacs
and Default
{}[]()
Each modified file is saved under a file called .#filename
, which is
removed on the next explicit save operation.
xterm -geo 80x50 -exe vi +%l %f |
The following substitutions are provided:
%l
%c
%f
%e
%p
%%
variable1, variable2, variable3 : Integer; |
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; |
Unchanged
will keep the casing as-is;
Upper
will change the casing of all reserved words to upper case;
Lower
will change the casing to lower case;
Mixed
will change the casing to mixed case (all characters to
lower case except first character and characters after an underscore
which are set to upper case).
Smart_Mixed
As above but do not force upper case characters to
lower case.
<=
, :=
, =>
, ...)
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.
rsh -l user
rcp -l user
This program is required under Unix systems in order to print, and is set to
a2ps
by default.
If a2ps
is not installed on your system, you can download it
from www.inf.enst.fr/~demaille/a2ps
Under Windows systems, this program is optional and is empty by default, since a built-in printing is provided. An external tool will be used if specified, such as the PrintFile freeware utility available from www.lerup.com/printfile/descr.html
-c
nor -u
switch).
Arguments of interest may include (this will depend on the version of diff
used):
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The key manager is accessible through the menu Edit->Key Shortcuts
.
This dialog provides an easy way to associate key shortcuts with actions.
These actions are either predefined in GPS, or defined in your own
customization files, as documented in 15.3 Customizing the Menu and Tool Bar.
It also provides an easy way to redefine the menu shortcuts.
Actions are referenced by their name, and are grouped into categories. These
categories indicate when the action applies. For instance, the indentation
command only applies in source editors, whereas the command to change the
current window applies anywhere in GPS. The categories correspond in fact to
filters that indicate when the action can be executed. You can create your own
new categories by using the <filter>
tag in the customization files
(see section 15.3 Customizing the Menu and Tool Bar).
Through the key manager, you can define key bindings similar to what Emacs
uses (control-x followed by control-k for instance). To register
such key bindings, you need to press the Grab
button as usual, and then
type the shortcut. The recording of the key binding will stop a short while
after the last key stroke.
This facility for creating complex shortcuts is not available for menu items yet.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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] | [ ? ] |
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] | [ ? ] |
The GPS menu bar can be customized through XML files. These files are found
through three possible mechanisms, described here in the order in which they
are searched. Files with the `.xml' extension found through
GPS_CUSTOM_PATH
or the user's directory can override any setup found in
the system directory. Likewise, files found in the user's directory can
override any file found in the GPS_CUSTOM_PATH
directories.
Note that only files with the `.xml' extension are considered.
The `INSTALL/share/gps/customize' directory, where `INSTALL' is the name of the GPS installation directory, should contain the files that will always be loaded whenever GPS is loaded, by any user on the system.
GPS_CUSTOM_PATH
This environment variable can be set before launching GPS. It should contain a list of directories, separated by semicolons (';') on Windows systems and colons (':') on Unix systems. All the files found in these directories will be searched for customization files.
This is a convenient way to have project-specific customization files. You can for instance create scripts, or icons, that set the appropriate value for the variable and then start GPS. Depending on your project, this allows you to load specific aliases which do not make sense for other projects.
The directory `$HOME/.gps/customize' on Unix systems, and `%HOME%\.gps\customize' on Windows systems, can also contain customization files which are parsed at startup. This is a convenient way for users to define their own customization, that they want to load no matter which project they are working on.
The format of these files have changed in GPS 1.3.0. A conversion program is provided that will automatically convert all files in the customization directory to the new format. This conversion tool is called `gps2custom-1.3', and must be run manually.
These files must be utf8-encoded by default. However, you can specify any
encoding you wish through the standard <?xml encoding="..." ?>
declaration, as in the following example:
<?xml version="1.0" encoding="iso-8859-1"> <submenu> <title>encoded text/title> </submenu> |
Any given XML file can contain customization for various aspects of GPS, mixing aliases, new languages or menus,... in a single file. This is a convenient way to distribute your customization to other users.
These files must be valid XML files, i.e. must start with the
<?xml?>
tag, and contain a single root XML node, the name of which is
left to your consideration. The general format is therefore
<?xml version="1.0" ?> <root_node> ... </root_node> |
XML comments are not supported in these files.
The list of valid XML child nodes that can be specified under <root> is described in later sections. This includes:
<action>
<key>
<submenu>
<alias>
<language>
<button>
<vsearch-pattern>
<tool>
<filter>
<contextual>
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These files distinguish the actions from their associated menus or key bindings. These actions can take on several forms: external commands, shell commands and predefined commands, as will be explained in more details below.
The general form to define new actions is to use the <action>
tag.
This tag accepts the following attributes:
name (mandatory)
output (optional)
<shell>
and <external>
tags,
See section 15.6.4.5 Redirecting the command output.
show-command (optional)
This attribute can be overriden for each command.
The <action>
can have one or
several children, all of which define a particular command to execute. All
of these commands are executed one after the other, unless one of them
fails in which case the following commands are not executed.
The following XML tags are valid children for <action>
.
<external>
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 external
tag would look like:
<action name="my_command"> <external>cmd /c c:\.gps\my_scripts\my_cmd.cmd</external> </action> |
This tag accepts the following attributes:
show-command (optional)
<action>
tag.
output (optional)
<action>
tag.
on-failure (optional)
For instance, the following action spawn an external tool, and parses its
output to the location window and the automatic fixing tool if the external
tool happens to fail. You must put the value of the on-failure
on a
single line in the XML file.
Remember also to quote special XML character like '"' in the value of the attribute. The output of the command that failed can be obtained through the "%1" parameter.
<action name="launch tool to location" > <external on-failure="locations_parse " ""%1 """ category; codefix_parse """%1 " "" category" >tool-path</external> </action> |
on-failure-lang (optional)
progress-regexp (optional)
The name of the action is printed in the progress bar while the action is executing.
<action name="progress" > <external progress-regexp="(\d+) out of (\d+).*$" progress-current="1" progress-final="2" progress-hide="true">gnatmake foo.adb </external> </action> |
progress-current (optional)
progress-regexp
that contains the current step.
progress-final (optional)
progress-regexp
that contains the current last step. This last index can grow as
needed. For example, gnatmake will output the number of
the file it is currently examining, and the total number of files to be
examined. However, that last number may grow up, since parsing a new file
might generate a list of additional files to parse later on.
progress-hide (optional)
progress-regexp
and are used to compute the progress will
not be displayed in the output console. For any other value of this
attribute, these lines are displayed along will the rest of the output.
<shell>
shell
tag. These are command written in one of the
shell scripts supported by GPS.
This tag supports the same show-command
and output
attributes
as the <action>
tag.
The following example shows how to
create two actions to invoke the help
interactive command and to open
the file `main.c'.
<action name="help"> <shell>help</shell> </action> <action name="edit"> <shell>edit main.c</shell> </action> |
By default, commands are expected to be written in the GPS shell language.
However, you can specify the language through the lang
attribute. Its
default value is "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.
<action name="current file uses"> <shell lang="shell">File %f</shell> <shell lang="shell">File.uses %1</shell> </action> |
<description>
<filter>, <filter_and>, <filter_or>
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.
<action "xterm in current directory"> <shell lang="shell">cd %d</shell> <external>xterm</external> </action> |
As seen in some of the examples above, some special strings are expanded by GPS just prior to executing the command. These are the "%f", "%d",.. See below for a full list.
More information on chaining commands is provided in See section 15.6.4.1 Chaining commands.
Some actions are also predefined in GPS itself. This include for instance
aliases expansion, manipulating MDI windows,... All known actions (predefined
and the ones you have defined in your own customization files) can be
discovered by opening the keyshortcut editor (Edit->Keyshortcuts
menu).
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
When an action is defined, you can use macro arguments to pass to your shell or external commands. Macro arguments are special parameters that are transformed every time the command is executed. The following macro arguments are provided.
%f
%F
%d
%p
%P
%pp
%PP
%pps
%pp
, except it returns the project name prepended
with -P
, or an empty string if there is no project file selected and the
current source file doesn't belong to any project. This is mostly for use with
the GNAT command line tools.
%PPs
%PP
, except it returns the project name prepended
with -P
, or an empty string if the root project is the default project.
This is mostly for use with the GNAT command line tools.
%(p|P)[r](d|s)[f]
P
p
r
d
s
f
%Ps
%prs
%prdf
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
By default, an action will execute in any context in GPS. The user just selects the menu or key, and GPS tries to execute the action.
It is possible to restrict when an action should be considered as valid. If the current context is incorrect for the action, GPS will not attempt to run anything, and will display an error message for the user.
Actions can be restricted in several ways:
For instance, if you have specified %F
as a parameter to one of the
commands, GPS will check prior to running the action that there is a current
file. This can be either a currently selected file editor, or for instance that
the project explorer is selected, and a file node inside it is also selected.
You do not have to specify anything else, this filtering is automatic
<filter>
, <filter_and>
and <filter_or>
tags, see below.
These tags can be used to further restrict when the command is valid. For instance, you can use them to specify that the command only applies to Ada files, or only if a source editor is currently selected.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Such filters can be defined in one of two places in the customization files:
<action>
, <menu>
or
<button>
tags, you can define named filters. These are general filters,
that can be referenced elsewhere without requiring code duplication. They
also appear explicitely in the keyshortcuts editor if at least one action is
depending on them.
<action>
tag
Such filters are anonymous, although they provide exactly the same capabilities
as the ones above. These are mostly meant for simple filters, or filters that
you use only once, or don't want to appear in the keyshortcuts manager.
There are three different kinds of tags:
<filter>
<filter_and>
<filter>
, <filter_and>
and <filter_or>
.
<filter_or>
<filter>
,
<filter_and>
and <filter_or>
.
If several such tags are found following one another under an <action>
tag, they are combined through "or", i.e. any of the filters may match for the
action to be executed.
The <filter>
, <filter_and>
and <filter_or>
tags accept the
following set of common attributes:
name (optional)
id
attribute. The name can
take any form. This is also the name that appears in the context of the
keyshortcuts editor.
error (optional)
<filter_and>
and <filter_or>
, only the error message of
the top-level filter will be printed.
In addition, the <filter>
has the following specific attributes:
id (optional)
<filter name="Test filter" language="ada" /> <action name="Test action" > <filter id="Test filter" /> <shell>pwd</shell> </action> |
A number of predefined filters are predefined by GPS itself. The full list appears in the keyshortcut editor, and is listed here:
Source editor
language (optional)
ada
,
you must have an Ada file selected, or the action won't execute. The language
for a file is found by GPS following several algorithms (file extensions, and
via the naming scheme defined in the project files).
shell_cmd (optional)
Note that currently no expansion of macro arguments (%f, %p,...) is done in this command.
shell_lang (optional)
module (optional)
The list of module names can be obtained by typing lsmod
in the shell
console at the bottom of the GPS window.
This attribute is mostly useful when creating new contextual menus.
When several attributes are specified for a <filter>
node (which is not
possible with id
), they must all match for the action to be executed.
<!-- The following filter will only match if the currently selected window is a text editor editing an Ada source file --> <filter_and name="Source editor in Ada" > <filter language="ada" /> <filter id="Source editor" /> </filter_and> <!-- The following action will only be executed for such an editor --> <action name="Test Ada action" > <filter id="Source editor in Ada" /> <shell>pwd</shell> </action> <!-- An action with an anonymous filter. It will be executed if the selected file is in Ada, even if the file was selected through the project explorer --> <action name="Test for Ada files" > <filter language="ada" /> <shell>pwd</shell> </action> |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
These commands can be associated with menus, tool bar buttons and keys. All of these use similar syntax.
Binding a menu to an action is done through the <menu>
tag.
This tag takes the following attributes:
action (mandatory)
before (optional)
after (optional)
before
, but has a lower priority. If it
is specified, and there is no before
attribute, it specifies a reference
menu after which the new menu should be inserted.
It should also have one XML child called <title>
which specifies the
label of the menu
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 specify which menu this new item is added to by putting the
<menu>
tag to a <submenu>
tag. The latter also takes a
<title>
as a child. You can add items or sub menus to existing menus,
using titles for menus that already exist.
For example, this adds an item named mymenu
to the standard
Edit
menu.
<submenu> <title>Edit</title> <menu action="current file uses"> <title>mymenu</title> </menu> </submenu> |
Use the /
separator to identify the submenu in a menu. For
example, this adds a new item "stats" to the standard "unit testing" submenu
in "tools".
<submenu> <title>Tools/unit testing</title> <menu action="execute my stats"> <title>stats</title> </menu> </submenu> |
Adding an item with an empty title or no title at all inserts a menu separator.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The actions can also be used to contribute new entries in the contextual menus everywhere in GPS. These menus are displayed when the user presses the right mouse button, and should only show actions relevant to the current context.
Such contributions are done through the <contextual>
tag, which takes
one mandatory attribute action
, which is the name of the action to
execute, and must be defined elsewhere in one of the customization files.
It accepts one child tag, <Title>
which specifies the name of the
menu entry. If this child is not specified, the menu entry will use the name
of the action itself.
The new contextual menu will only be shown if the filters associated with the action match the current context.
For instance, the following example inserts a new contextual menu which prints the name of the current file in the GPS console. This contextual menu is only displayed in source editors.
<action name="print current file name" > <filter module="Source_Editor" /> <shell>echo %f</shell> </action> <contextual action="print current file name" > <Title>Print Current File Name</Title> </contextual> |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
As an alternative to creating new menu items, you can create new
buttons on the tool bar, with a similar syntax, by using
the <button>
tag. As for the <menu>
tag, it requires an
action
attribute which specifies what should be done when the button
is pressed. The button is not created if no such action was created.
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
<button>
tag indicates a separator in the tool bar.
A title can also be specified with <title>
. This will be visible only
if the user choses to see both text and icons in the tool bar.
The following example defines a new button:
<button action="execute my stats"> <title>stats</title> <pixmap>/my_pixmaps/button.jpg</pixmap> </button> |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
All the actions defined above can be bound to specific key shortcuts through
the <key>
attribute. As usual, it requires one <action>
attribute to specify what to do when the key is pressed.
This tag doesn't contain any child tag. Instead, its text contents specified
the keyboard shortcut. The name
of the key can be prefixed by control-
, alt-
, shift-
or
any combination of these to specify the key modifiers to apply.
You can also define multiple key bindings similar to Emacs's by separating them
by a space. For instance, control-x control-k
means that the user should
press control-x, followed by a control-k to activate the
corresponding action.
Use an empty string to describe the keybinding if you wish to deactivate a preexisting binding. The second example below deactivates the standard binding.
<key action="expand alias">control-o</key> <key action="Jump to matching delimiter" /> |
Multiple actions can be bound to the same key binding. The first one with a filter valid for the current context is executed. If no action with a filter can be executed, then the first action with no filter will be executed.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The search dialog contains a number of predefined search patterns for Ada and C. These are generally complex regular expressions, presented in the dialog with a more descriptive name. This includes for instance "Ada assignment", which will match all such assignments.
You can define your own search patterns in the customization files. This is
done through the <vsearch-pattern>
tag. This tag can have a number of
children tags:
<name>
This tag is the string that is displayed in the search dialog to represent the new pattern. This is the text that the user will effectively see, instead of the often hard to understand regular expression.
<regexp>
This tag provides the regular expression to use when the pattern has been selected by the user. Be careful that you must protect reserved XML characters such as '<' and replace them by their equivalent expansion ("<" for this character).
This accepts one optional attribute, named case-sensitive
. This
attribute accepts one of two possible values ("true" or "false") which
indicates whether the search should distinguish lower case and upper
case letters. Its default value is "false".
<string>
This tag provides a constant string that should be searched.
Only one of <regexp>
and <string>
should be provided. If
both exists, the first <regep>
child found is used. If there is
none, the first <string>
child is used.
The tag accepts the same optional attribute case-sensitive
as
above
Here is a small example on how the "Ada assignment" pattern was defined.
<vsearch-pattern> <name>Ada: assignment</name> <regexp case-sensitive="false">\b(\w+)\s*:=</regexp> </vsearch-pattern> |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The following example is a full example for one of the files in the customization directory. The only thing that hasn't been described before is the first line of the file, which is required to make it a valid XML file.
<?xml version="1.0"?> <Custom> <action name="action1"> <external>external-command 1</external> </action> <action name="action2"> <shell>edit %f</shell> </action> <submenu> <title>custom menu</title> <menu action="action1"> <title>item 1</title> </menu> <submenu> <title>other menu</title> <menu action="action2"> <title> (etc..) </menu> <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
external command external-command 1
, a sub menu named other menu
,
etc...
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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), 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. Therefore, you can either define new languages in a separate file, or reuse a file where you already define actions and menus.
The following tags are available in a Language
section:
Name
Parent
Ada
, C++
) or
another custom language, this language will inherit by default all its
properties from this language. Any field explicitely defined for this language
will override the inherited settings.
Spec_Suffix
Extension
tag instead.
This tag must be unique.
Body_Suffix
Spec_Suffix
, so that the user
can choose to easily go from one file to the other.
This tag must be unique.
Extension
Keywords
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.
Engine
The name can be a full pathname, or a short name. E.g. under most Unix systems
if you specify custom
, GPS will look for libcustom.so
in
the LD_LIBRARY_PATH
run time search path. You can also specify
explicitly e.g. libcustom.so
or /usr/lib/libcustom.so
.
For each of the following five items, GPS will look for the corresponding
symbol in Engine
and if found, will call this symbol when needed.
Otherwise, it will default to the static behavior, as defined by the other
language-related items describing a language.
You will find the required specification for the C and Ada languages
to implement the following functions in the directory
`<prefix>/share/gps/doc/examples/language' of your GPS installation.
`language_custom.ads' is the Ada spec file; `language_custom.h' is
the C spec file; `gpr_custom.ad?' are example files showing a possible Ada
implementation of the function Comment_Line
for the GPS project files (`.gpr' files), or any other Ada-like language;
`gprcustom.c' is the C version of gpr_custom.adb.
Comment_Line
Edit->Un/Comment Lines
).
Parse_Constructs
This procedure is used by GPS to implement several capabilities such as listing constructs in the project explorer, highlighting the current block of code, going to the next or previous procedure, ...
Format_Buffer
This procedure is used to implement the auto indentation when hitting the enter key, or when using the format key on the current selection or the current line.
Parse_Entities
Context
node described below.
Context
Comment_Start
Comment_End
New_Line_Comment_Start
String_Delimiter
Quote_Character
\
in C).
Constant_Character
Can_Indent
Syntax_Highlighting
Case_Sensitive
Categories
Category
nodes,
each describing the characteristics of a given category, with the following
nodes:
Name
Pattern
Keywords
node, multiple Pattern
tags can be
specified and will be concatenated into a single regular expression.
Index
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> <Engine>gpr</Engine> <Comment_Line>gpr_comment_line</Comment_Line> </Language> </Custom> |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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, 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:
%_
%(name)
%D
%H
%l
%c
%f
%d
%p
%P
%O
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.
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:
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] | [ ? ] |
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.
However, 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 in them can be overriden by the user-defined file.
These files are standard customization files, See section 15.3.2 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
name
, which the text to type in the source editor
before pressing control-o.
param
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
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> |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Support for external tools can be provided through GPS. Typically, this would be done to specify different compilers, but it can also apply to a wide variety of tools.
GPS's support for external tools is enhancing with each release. Typically, the following things need to be achieved to successfully use a tool:
Each of these points is discussed in further sections. In all these cases, most
of the work can be done statically through XML customization files.
These files have the same format as other customization files
(see section 15.3.2 Customization files), and the tool descriptions are found in
<tool>
tags.
This tag accepts the following attributes:
name (mandatory)
package (Default value is ide)
If this attribute is set to "ide", then the switches cannot be set for a specific file, only at the project level. Support for file-specific switches currently requires modification of the GPS sources themselves.
attribute (Default vluae is default_switches)
index (Default value is the tool name)
This tag accepts the following children, described in separate sections:
<switches>
<language>
<default-cmd-line>
15.6.1 Defining supported languages 15.6.2 Defining the default command line 15.6.3 Defining tool switches 15.6.4 Executing external tools 15.6.5 Full tool example
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This is the language to which the tool applies. There can be from no to any
number of such nodes for one <tool>
tag.
If no language is specified, the tool applies to all languages. In particular, the switches editor page will be displayed for all languages, no matter what languages they support.
If at least one language is specified, the switches editor page will only be displayed if that language is supported by the project.
<tool name="My Tool" > <language>Ada</language> <language>C</language> </tool> |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
It is possible to define the command line that should be used for a tool when the user is using the default project, or hasn't overriden this command line in the project.
This is done through the <initial-cmd-line>
tag, as a child of the
<tool>
tag. Its value is the command line that would be passed to the
tool. This command line is parsed as usual, e.g. quotes are taken into account
to avoid splitting switches each time a space is encountered.
<tool name="My tool" > <initial-cmd-line>-a -b -c</initial-cmd-line> </tool> |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The user has to be able to specify which switches to use with the tool. If the tool is simply called through custom menus, you might want to hard code some or all of the switches. However, in the general case it is better to use the project properties editor, so that project-specific switches can be specified.
This is what GPS does by default for Ada, C and C++. You can find in the GPS installation directory how the switches for these languages are defined in an XML file. These provide extended examples of the use of customization files.
The switches editor in the project properties editor provides a powerful interface to the command line, where the user can edit the command line both as text and through GUI widgets.
The switches are declared through the <switches>
tag in the
customization file, which must be a child of a <tool>
tag as described
above.
This <switches>
tag accepts the following attributes:
lines (default value is 1)
columns (default value is 1)
This <switches>
tag can have any number of child tag, among the
following. They can be repeated multiple times if you need several check boxes.
For consistency, most of these child tags accept attributes among the
following:
line (default value is 1)
lines
above.
column (default value is 1)
columns
above.
label
switch
combo
and spin
below.
This switch shouldn't contain any space.
tip (default value is empty)
min (default value is 1)
<spin>
tags, and indicates the minimum
value authorized for that switch.
max (default value is 1)
<spin>
tags, and indicates the maximum
value authorized for that switch.
default (default value is 1)
<spin>
tags. See the description below.
noswitch (default is empty)
<combo>
tags, and described below.
nodigit (default is empty)
<combo>
tags, and described below.
value (mandatory)
<combo-entry>
tags.
Here are the valid children for <switches>
:
<title>
line
and column
attributes, is used
to give a name to a specific frame.
The value of the tag is the title itself. You do not have to specify
a name, and this can be left to an empty value.
Extra attributes for <title>
are:
line-span (default value is 1)
column-span (default value is 1)
<check>
line
, column
, label
, switch
and tip
attributes. It creates a toggle button. When the latter is
active, the text defined in the switch attribute is added as is
to the command line. This tag doesn't have any value or child tags.
<spin>
line
, column
, label
, switch
,
tip
, min
, max
and default
attributes.
This switch will add the contents of the switch
attribute followed by
the current numeric value of the widget to the command line. This is typically
used to indicate indentation length for instance.
If the current value of the widget is equal to the default
attribute,
then nothing is added to the command line.
<radio>
line
and column
attributes. It groups any
number of children, each of which is associated with its own switch. However,
only one of the children can be selected at any given time.
The children must have the tag radio-entry
. This tag accepts the
attributes label
, switch
and tip
.
<field>
line
, column
, label
, switch
and tip
attributes. This tag describes a text edition field, which can
contain any text the user types. This text will be prefixed by the value of
the switch
attribute, and a space. If no text is entered in the field
by the user, nothing is put on the command line.
This tag accepts two extra attributes:
as-directory (optional)
as-file (optional)
as-directory
, but opens a dialog to
select a file instead of a directory. If both attributes are set to "true",
the user will select a file.
<combo>
line
, column
, label
, switch
,
tip
, noswitch
and nodigit
attributes.
The text inserted in the command line is the text from the switch
attribute, concatenated with the text of the value
attribute for the
currently selected entry. If the value of the current entry is the same
as that of the nodigit
attribute, then only the text of the
switch
attribute is put on the command line. This is in fact necessary
to interpret the gcc switch "-O" as "-O1".
If the value of the current entry is that of the noswitch
attribute,
then nothing is put in the command line.
The tag <combo>
accepts any number of combo-entry
children tags,
each of which accepts the label
and value
attribute.
<popup>
line
, column
, label
, lines
and columns
attributes. This displays a simply button that, when
clicked, displays a dialog with some extra switches. This dialog, just as the
switches editor itself, is organizes into lines and columns of frames, the
number of which is provided by the lines
and columns
attributes.
This tag accepts any number of children, which are the same as the
<switches>
attribute itself.
<dependency>
It has its own set of attributes:
master-page master-switch
<check>
.
slave-page slave-switch
<check>
.
master-status slave-status
<expansion>
It is easier to explain it through an example. Specifying the GNAT switch "-gnaty" is equivalent to specifying "-gnatyabcefhiklmnprst". This is in fact a style check switch, with a number of default values. But it is also equivalent to decomposing it into several switches, as in "-gnatya", "-gnaty3", "-gnatyb",... With this information, GPS will try to keep the command line length as short as possible, to keep it readable.
Both these aspects are defined in a unique <expansion>
tag, which
accepts two attributes: switch
is mandatory, and alias
is
optional. Alias contains the text "gnatyabcefhiklmnprst" in our example.
It also accepts any number of <entry>
children, each has a mandatory
switch
access. The set of all these children define the expanded
equivalent of the switch. In our example, we need one <entry>
child
for "'gnaty3", one for "-gnatya",....
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The user has now specified the default switches he wants to use for the external tool. Spawning the external tool can be done in two ways:
Both cases are described in an XML customization file, as described previously,
and both are setup to execute what GPS calls an action, i.e. a set of commands
defined by the <action>
tag.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This action tag, as described previously, executes one or more commands, which can either be internal GPS commands (written in any of the scripting language supported by GPS), or external commands provided by executables found on the PATH.
The command line for each of these commands can either be hard-coded in the
customization file, or be the result of previous commands executed as part of
the same action. As GPS executes each command from the action in turn, it
saves its output on a stack as needed. If a command line contains a special
construct %1
, %2
... then these constructs will be replaced
by the result of respectively the last command executed, the previous from last
command, and so on.
Every time you execute a new command, it pushes the previous %1, %2... parameters one step further on the stack, so that they become respectively %2, %3... and the output of that command becomes %1.
The output of the previous commands is substituted exactly as is. However, if the output is surrounded by quotes, they are ignored when a substitution takes place, so you need to put them back if they are needed. The reason for this behavior is so that for scripting languages that systematically protect their output with quotes (simple or double), these quotes are sometimes in the way when calling external commands.
If one of the commands in the action raises an error, the execution of the action is stopped immediately, and no further command is performed.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Before launching the external tool, you might want to force GPS to save all
open files, the project.... This is done using the same command GPS itself
uses before starting a compilation. This command is called save_all
,
and takes one optional boolean argument which specifies whether an interactive
dialog should be displayed for the user.
Since this command aborts when the user presses cancel, you can
simply put it in its own <shell>
command, as in:
<action name="test save children"> <shell>save_all 0</shell> <external>echo Run unless Cancel was pressed</external> </action> |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Some GPS shell commands can be used to query the default switches set by the
user in the project file. These are get_tool_switches_as_string
,
get_tool_switches_as_list
, or, more generally,
get_attribute_as_string
and get_attribute_as_list
. The first
two require a unique parameter which is the name of the tool as specified in
the <tool>
tag. This name is case-sensitive. The last two commands are
more general and can be used to query the status of any attribute from the
project. See their description by typing the following in the GPS shell
console window:
help Project.get_attribute_as_string help Project.get_attribute_as_list |
The following is a short example on how to query the switches for the tool
"Find" from the project, See section 15.6.5 Full tool example. It first creates an object
representing the current project, then passes this object as the first
argument of the get_tool_switches_as_string
command. The last external
command is a simple output of these switches
<action name="Get switches for Find"> <shell>Project %p</shell> <shell>Project.get_tool_switches_as_string %1 Find </shell> <external>echo %1</external> </action> |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
Another solution to query the arguments for the tool is to ask the user interactively. The scripting languages provides a number of solutions for these.
They generally have their own native way to read input, possibly by creating a dialog.
In addition, the simplest solution is to use the predefined GPS commands for this. These are the two functions:
yes_no_dialog
input_dialog
From the GPS shell, it is only convenient to query one value at a time, since it doesn't have support for lists, and would return a concatenation of the values. However, this function is especially useful with other scripting languages.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The output of external commands is send by default to the GPS console window.
In addition, finer control can be exercised using the output
attribute
of the <external>
and <shell>
tags.
This attribute is a string that may take any value. Two values have specific meanings:
"none"
""
other values
This attribute can also be specified at the <action>
tag level, in which
case it defines the default value for all <shell>
and <external>
tags underneath. If it isn't specified for the action itself, its default value
will always be the empty string, i.e. output is sent to the GPS console.
<action name="ls current directory" output="default output" > <shell output="Current directory" >pwd</shell> <external output="Current directory contents" >/bin/ls </external> </action> |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
The output of the tool has now either been hidden or made visible to the user in one or more windows.
There are several additional things that can be done with this output, for further integration of the tool in GPS.
make
.
This can be done for your own tools using the shell command
locations_parse
. This command takes several arguments, so that you
can specify your own regular expression to find the file name, line number and
so on in the error message. By default, it is configured to work
seamlessly with error message of the forms:
file:line: message file:line:column: message |
Please refer to the online help for this command to get more information.
Here is a small example on how to run a make command and send the errors to the location window afterwards.
For languages that support it, it is also recommended that you quote the argument with triple quotes, so that any special character (newlines, quotes, ...) in the output of the tool are not specially interpreted by GPS. Note also that you should leave a space at the end, in case the output itself ends with a quote.
<action name="make example" > <external>make</external> <shell>locations_parse """%1 """ make_example</shell> </action> |
Codefix.parse
shell command, which takes the same arguments as for locations_parse
.
This will automatically add pixmaps to the relevant entries in the location
window, and therefore locations_parse
should be called first prior to
calling this command.
Errors can also be fixed automatically by calling the methods of the
Codefix
class. Several codefix sessions can be active at the same time,
each of which is associated with a specific category. The list of currently
active sessions can be retrieved through the Codefix.sessions()
command.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
This section provides an example that defines a new tool. This is only a short example, since Ada, C and C++ support themselves are provided through such a file, available in the GPS installation.
This example adds support for the "find" Unix utility, with a few switches. All these switches are editable through the project properties editor.
It also adds a new action and menu. The action associated with this menu gets the default switches from the currently selected project, and then ask the user interactively for the name of the file to search.
<?xml version="1.0" ?> <toolexample> <tool name="Find" > <switches columns="2" > <title column="1" >Filters</title> <title column="2" >Actions</title> <spin label="Modified less than n days ago" switch="-mtime-" min="0" max="365" default="0" /> <check label="Follow symbolic links" switch="-follow" /> <check label="Print matching files" switch="-print" column="2" /> </switches> </tool> <action name="action find"> <shell>Project %p</shell> <shell>Project.get_tool_switches_as_string %1 Find </shell> <shell>input_dialog "Name of file to search" Filename</shell> <external>find . -name %1 %2</external> </action> <Submenu> <Title>External</Title> <menu action="action find"> <Title>Launch find</Title> </menu> </Submenu> </toolexample> |
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
In addition to the GPS specific mechnisms described previousely, GPS can be configured through the low level Gtk+ mechanism of `RC files'.
As more customization capabilities are added in GPS, this mechanism will become less useful and built-in GPS capabilities should be prefered.
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] | [ ? ] |
#
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
pixmap_path path
style name [ = parent ] { ... }
style "my-style" = "default" { ... } |
See Defining new styles for more details.
binding name { ... }
class widget-name (binding | style) name
resource-name
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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
fg[state] = color
base[state] = color
text[state] = color
bg_pixmap[state] = pixmap
font_name = font
GtkTextView::cursor-aspect-ratio = value
GtkTextView::cursor-color = color
The colors and background pixmaps are specified as a function of the state of the visual object. The states are:
NORMAL
ACTIVE
PRELIGHT
SELECTED
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] | [ ? ] |
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
clicked ()
GtkDialog
close ()
GtkEntry
activate ()
move-cursor (movement-step, count, extend-selection)
insert-at-cursor (string)
delete-from-cursor (delete-type, count)
cut-clipboard ()
copy-clipboard ()
paste-clipboard ()
toggle-overwrite ()
GtkMenuItem
activate ()
GtkMenuShell
move-current (menu-direction)
GtkTextView
move-cursor (movement-step, count, extend-selection)
page-horizontally (count, extend-selection)
set-anchor ()
insert-at-cursor (string)
delete-from-cursor (delete-type, count)
cut-clipboard ()
copy-clipboard ()
paste-clipboard ()
toggle-overwrite ()
GtkTreeView
move-cursor (movement-step, count)
select-all ()
unselect-all ()
select-cursor-row (start-editing)
toggle-cursor-row ()
expand-collapse-cursor-row (logical, expand, expand-all)
select-cursor-parent ()
start-interactive-search ()
The possible values of the parameters listed above are:
count
string
extend-selection, start-editing, logical, expand, expand-all:
delete-type
chars
word-ends
paragraph-ends
paragraphs
whitespace
menu-direction
parent
child
next
prev
movement-step
logical-positions
visual-positions
words
display-lines
display-line-ends
paragraphs
paragraph-ends
pages
buffer-ends
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
15.8.1 Scripts 15.8.2 Scripts and GPS actions 15.8.3 The GPS Shell
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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,...
These languages all have a separate console associated with them,
which you can open from the Tools
menu. In each of these
console, GPS will display a prompt, at which you can type interactive
commands. These console provide completion of the command names
through the tab key.
For instance, in the GPS shell console you can start typing
GPS> File |
then press the tab key, which will list all the functions whose name starts with "File".
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' |
See the section 15.3 Customizing the Menu and Tool Bar on how to bind key shortcuts to shell commands.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
There is a strong relationship between GPS actions, as defined in the customization files, and scripting languages.
Actions can be bound to menus and keys through the customization files or
the Edit->Key shortcuts
dialog.
These actions can execute any script command, See section 15.3.3 Defining Actions. This is
done through the <shell>
XML tag.
But the opposite is also true. From a script, you can execute any action registered in GPS. This can for instance be used to split windows, highlight lines in the editor,... when no equivalent shell function exists. This can also be used to execute external commands, if the scripting language doesn't support this in an easy manner.
Such calls are made through a call to execute_action
, as in the
following example:
execute_action "Split horizontally" |
The list of actions known to GPS can be found through the
Edit->Key shortcuts
dialog. Action names are case sensitive.
[ < ] | [ > ] | [ << ] | [ Up ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |
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.3 Customizing the Menu and Tool Bar.
Arguments to commands can, but need not, be quoted. If they don't contain any space, double-quote ('"') or newline characters, you do not need to quote them. Otherwise, you should surround them with double-quotes, and protect any double-quote part of the argument by preceding it with a backslash.
There is another way to quote a command: use three double-quotes characters in a row. Any character loses its special meaning until the next three double-quotes characters set. This is useful if you do not know in advance the contents of the string you are quoting.
locations_parse """%1 """ category_name |
In future versions of GPS, it will be possible to use more advanced scripting
languages such as Python
.
[ << ] | [ >> ] | [Top] | [Contents] | [Index] | [ ? ] |