16.5.3 Macro arguments

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.