Next: Filtering actions, Previous: Defining Actions, Up: Customizing through XML and Python files [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.
The equivalent python command is given for all tests. These commands are useful when you are writing a full python script, and want to test for yourself whether the context is properly defined.
%a
If the user clicked within the Locations Window, this is the name of the category to which the current line belongs
%builder
Replaced by the default builder configured in GPS.
This can be e.g. gnatmake
if your project contains only Ada code,
or gprbuild
for non Ada or multi-language projects, or gprmake
if you have set the multi language builder preference accordingly.
Note: this macro is only available in the commands defined in the Build
Manager and the Build Launcher dialogs.
%c
This is the column number on which the user clicked. Python equivalent:
GPS.current_context().column()
%d
The current directory. Python equivalent:
GPS.current_context().directory()
%dk
The krunched name of the current directory.
%e
Name of the entity the user clicked on. Python equivalent:
GPS.current_context().entity().name()
%E
The full path to the executable name corresponding to the target.
%ek
Krunched name of the entity the user clicked on.
This is the same as %e
, except long names are shorted as in %fk
.
%eL
Replaced by either an empty string, or -eL
, depending on whether the
Fast Project Loading
preference if set or not.
-eL
is used by GNAT tools to specify whether symbolink links
should be followed or not when parsing projects.
Note: this macro is only available in the commands defined in the Build
Manager and the Build Launcher dialogs.
%external
Replaced by the command line specified in the preference External Commands->Execute command.
%f
Base name of the currently selected file. Python equivalent:
import os.path os.path.basename (GPS.current_context().file().name())
%F
Absolute name of the currently opened file. Python equivalent:
GPS.current_context().file().name()
%fk
Krunched base name of the currently selected file. This is the same as %f, except that long names are shortened, and their middle letters are replaced by "[...]". This should be used in particular in menu labels, to keep the menus narrow.
%fp
Base name of the currently selected file. If the file is not part of the project tree, or no file is selected, generate an error on the Messages window. Note: this macro is only available in the commands defined in the Build Manager and the Build Launcher dialogs.
%gnatmake
Replaced by the gnatmake executable configured in your project file.
%gprbuild
Replaced by the gprbuild or gprmake command line configured in your project file.
%gprclean
Replaced by the default cleaner configured in GPS.
This can be e.g. gnat clean
, or gprclean
.
Note: this macro is only available in the commands defined in the Build
Manager and the Build Launcher dialogs.
%i
If the user clicked within the Project View, this is the name of the parent project, ie the one that is importing the one the user clicked on. Note that with this definition of parent project, a given project might have multiple parents. The one that is returned is read from the Project View itself.
%l
This is the line number on which the user clicked. Python equivalent:
GPS.current_context().line()
%o
The object directory of the current project.
%O
The object directory of the root project.
%p
The current project. This is the name of the project, not the project file, ie the .gpr extension is not included in this name, and the casing is the one found inside the project file, not the one of the file name itself. If the current context is an editor, this is the name of the project to which the source file belongs. Python equivalent:
GPS.current_context().project().name()
%P
The root project. This is the name of the project, not the project file. Python equivalent:
GPS.Project.root().name()
%Pb
The basename of the root project file.
%Pl
The name of the root project, all lower case.
%pp
The current project file pathname. If a file is selected, this is the project file to which the source file belongs. Python equivalent:
GPS.current_context().project().file().name()
%PP
The root project pathname. Python equivalent:
GPS.Project.root().file().name()
%pps
This is similar to %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. The project name is quoted if it contains spaces.
Python equivalent:
if GPS.current_context().project(): return "-P" & GPS.current_context().project().file().name()
%PPs
This is similar to %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]
Substituted by the list of sources or directories of a given project. This list is a list of space-separated, quoted names (all names are surrounded by double quotes, for proper handling of spaces in directories or file names).
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.
Python equivalent:
GPS.current_context().project().source_dirs()
s
list the source files.
Python equivalent:
GPS.current_context().project().sources()
f
output the list into a file and substitute the parameter with the name of that file. This file is never deleted by GPS, it is your responsibility to do so.
%s
This is the text selected by the user, if a single line was selected. When multiple lines were selected, this returns the empty string
%S
This is either the text selected by the user, of the current entity if there is no selection. If the entity is part of an expression ("A.B.C"), then the whole expression is used instead of the entity name.
%switches(tool)
Replaced by IDE'Default_Switches (tool)
, in other words, if you
have a tool whose switches are defined via an xml file in GPS, they
are stored as Default_Switches (xxx)
in the IDE
package
and can be retrieved using this macro. The value returned is a list of
switches, or an empty list if not set.
Note: This macro is only available in the commands defined in the Build Manager and Build Launcher dialogs.
%T
Replaced by the subtarget being considered for building. Depending on the context, this can correspond to e.g. the base filename of a Main source, or makefile targets. Note: this macro is only available in the commands defined in the Build Manager and the Build Launcher dialogs.
%TT
Same as %TT
, but returns the full path to main sources rather than
the base filename.
%attr(Package'Name[,default])
Replaced by the project attribute Package'Name
, in other words, the
attribute Name
from the package Package
. Package'
is
optional if Name
is a top level attribute (e.g. Object_Dir
).
If the attribute is not defined in the project, an optional default
value is returned, or an empty string if not.
Note: This macro is only available in the commands defined in the Build Manager and Build Launcher dialogs, and only supports single string attributes, not lists.
%dirattr(Package'Name[,default])
Replaced by the directory part of an attribute. The attribute is specified
as in %attr
above.
%baseattr(Package'Name[,default])
Replaced by the base name of an attribute. The attribute is specified
as in %attr
above.
%vars
Replaced by a list of switches of the form <variable>=<value>
, where
<variable> is the name of a scenario variable and <value> its current
value, as configured in the Scenario View. All the scenario variables
defined in the current project tree will be listed.
Alternatively, you can also use %vars(-D)
to generate a list of
switches of the form -D<variable>=<value>
.
Note: this macro is only available in the commands defined in the Build
Manager and the Build Launcher dialogs.
%X
Replaced by a list of switches of the form -X<variable>=<value>
, where
<variable> is the name of a scenario variable and <value> its current
value, as configured in the Scenario View. All the scenario variables
defined in the current project tree will be listed.
Note: this macro is only available in the commands defined in the Build
Manager and the Build Launcher dialogs.
%%
Replaced by the % sign.
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.
Another type of macros are expanded before commands are executed: These
all start with the $
character, and represent parameters passed to
the action by its caller. Depending on the context, GPS will give zero, one
or more arguments to the action. This is in particular used when you define
your own VCS system. See also the shell function execute_action
, which
you can use yourself to execute an action and pass it some arguments.
These arguments are the following
$1, $2, ... $n
Where n is a number. These are each argument passed to the action
$1-, $2-, ... $n-
This represents a string concatenating the specified argument and all arguments after it
$*
This represents a string concatenating all arguments passed to the action
$repeat
This is the number of times the action has been repeated in a row. It will in
general be 1 (ie this is the first execution of the action), unless the user
has first executed the action "Repeat Next"
, which allows automatic
repetition of an action.
By default, when the action "Repeat Next" is invoked by the user, it will repeat the following action as many times as the user specified. However, in some cases, either for efficiency reasons or simply for technical reasons, you might want to handle yourself the repear. This can be done with the following action declaration:
<action name="my_action"> <shell lang="python">if $repeat==1: my_function($remaining + 1)</shell> </action> def my_function (count): """Perform an action count times""" ...
Basically, the technics here is to only perform something the first time the
action is called (hence the if statement), but pass your shell function the
number of times that it should repeat (hence the $remaining
parameter).
$remaining
This is similar to $repeat, and indicates the number of times that the action remains to be executed. This will generally be 0, unless the user has chosen to automatically repeat the action a number of times.
Next: Filtering actions, Previous: Defining Actions, Up: Customizing through XML and Python files [Index]