Next: , Previous: Defining Actions, Up: Customizing through XML and Python files


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.

%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.
%e
Name of the entity the user clicked on. Python equivalent:
          GPS.current_context().entity().name()

%ek
Krunched name of the entity the user clicked on. This is the same as %e, except long names are shorted as in %fk.
%d
The current directory. Python equivalent:
          GPS.current_context().directory()

%dk
The krunched name of the current directory.
%l
This is the line number on which the user clicked. Python equivalent:
          GPS.current_context().line()

%c
This is the column number on which the user clicked. Python equivalent:
          GPS.current_context().column()

%a
If the user clicked within the Locations Window, this is the name of the category to which the current line belongs
%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.
%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
%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()

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

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.
%%
Replaced by the % sign.

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.