This file is indexed.

/usr/share/doc/gnat-gps/html/Macro-arguments.html is in gnat-gps-doc 5.0-6.

This file is owned by root:root, with mode 0o644.

The actual contents of the file can be viewed below.

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
<html lang="en">
<head>
<title>Macro arguments - Using the GNAT Programming Studio</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="Using the GNAT Programming Studio">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="Customizing-through-XML-and-Python-files.html#Customizing-through-XML-and-Python-files" title="Customizing through XML and Python files">
<link rel="prev" href="Defining-Actions.html#Defining-Actions" title="Defining Actions">
<link rel="next" href="Filtering-actions.html#Filtering-actions" title="Filtering actions">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<!--
Copyright (C) 2002-2010 AdaCore.

This document is free; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or
(at your option) any later version.

This document is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License along
with this program; if not, see `http://www.gnu.org/licenses/'.-->
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
  pre.display { font-family:inherit }
  pre.format  { font-family:inherit }
  pre.smalldisplay { font-family:inherit; font-size:smaller }
  pre.smallformat  { font-family:inherit; font-size:smaller }
  pre.smallexample { font-size:smaller }
  pre.smalllisp    { font-size:smaller }
  span.sc    { font-variant:small-caps }
  span.roman { font-family:serif; font-weight:normal; } 
  span.sansserif { font-family:sans-serif; font-weight:normal; } 
pre.smallexample {background-color:rgb(240,240,240);
                     font-family: courier new,courier,fixed;
                     font-size: 14px;
                     margin: 0px 40px 0px 40px;
                     border-width: 1px 2px 2px 1px;
                     border-top-style: dotted;
                     border-left-style: dotted;
                     border-right-style: solid;
                     border-bottom-style: solid;
                     border-color: black;}
   code             {color:black;
                     font-family: courier new,courier,fixed;
                     font-size: 14px;}
   body             {font-family: arial,helvetica,sans-serif;
                     font-size: 16px;
                     max-width: 800px;
                     text-align: justify}
   samp             {font-family: courier new,courier,fixed;
                     font-size: 14px}
                    
--></style>
</head>
<body>
<div class="node">
<a name="Macro-arguments"></a>
<p>
Next:&nbsp;<a rel="next" accesskey="n" href="Filtering-actions.html#Filtering-actions">Filtering actions</a>,
Previous:&nbsp;<a rel="previous" accesskey="p" href="Defining-Actions.html#Defining-Actions">Defining Actions</a>,
Up:&nbsp;<a rel="up" accesskey="u" href="Customizing-through-XML-and-Python-files.html#Customizing-through-XML-and-Python-files">Customizing through XML and Python files</a>
<hr>
</div>

<h4 class="subsection">16.5.3 Macro arguments</h4>

<p><a name="index-menu-795"></a><a name="index-argument-796"></a><a name="index-substitution-797"></a><!--  -->

<p class="noindent">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.

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

     <dl>
<dt><code>%a</code><dd>If the user clicked within the Locations Window, this is the name of the
category to which the current line belongs

     <br><dt><code>%builder</code><dd>Replaced by the default builder configured in GPS. 
This can be e.g. <code>gnatmake</code> if your project contains only Ada code,
or <code>gprbuild</code> for non Ada or multi-language projects, or <code>gprmake</code>
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.

     <br><dt><code>%c</code><dd>This is the column number on which the user clicked. 
Python equivalent:
     <pre class="smallexample">          GPS.current_context().column()
</pre>
     <br><dt><code>%d</code><dd>The current directory. 
Python equivalent:
     <pre class="smallexample">          GPS.current_context().directory()
</pre>
     <br><dt><code>%dk</code><dd>The krunched name of the current directory.

     <br><dt><code>%e</code><dd>Name of the entity the user clicked on. 
Python equivalent:
     <pre class="smallexample">          GPS.current_context().entity().name()
</pre>
     <br><dt><code>%E</code><dd>The full path to the executable name corresponding to the target.

     <br><dt><code>%ek</code><dd>Krunched name of the entity the user clicked on. 
This is the same as <code>%e</code>, except long names are shorted as in <code>%fk</code>.

     <br><dt><code>%eL</code><dd>Replaced by either an empty string, or <code>-eL</code>, depending on whether the
<code>Fast Project Loading</code> preference if set or not. 
<code>-eL</code> 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.

     <br><dt><code>%external</code><dd>Replaced by the command line specified in the preference
  <i>External Commands-&gt;Execute command</i>.

     <br><dt><code>%f</code><dd>Base name of the currently selected file. 
Python equivalent:
     <pre class="smallexample">          import os.path
          os.path.basename (GPS.current_context().file().name())
</pre>
     <br><dt><code>%F</code><dd>Absolute name of the currently opened file. 
Python equivalent:
     <pre class="smallexample">          GPS.current_context().file().name()
</pre>
     <br><dt><code>%fk</code><dd>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.

     <br><dt><code>%fp</code><dd>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.

     <br><dt><code>%gnatmake</code><dd>Replaced by the gnatmake executable configured in your project file.

     <br><dt><code>%gprbuild</code><dd>Replaced by the gprbuild or gprmake command line configured in your project
file.

     <br><dt><code>%gprclean</code><dd>Replaced by the default cleaner configured in GPS. 
This can be e.g. <code>gnat clean</code>, or <code>gprclean</code>. 
Note: this macro is only available in the commands defined in the Build
Manager and the Build Launcher dialogs.

     <br><dt><code>%i</code><dd>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.

     <br><dt><code>%l</code><dd>This is the line number on which the user clicked. 
Python equivalent:
     <pre class="smallexample">          GPS.current_context().line()
</pre>
     <br><dt><code>%o</code><dd>The object directory of the current project.

     <br><dt><code>%O</code><dd>The object directory of the root project.

     <br><dt><code>%p</code><dd>The current project. This is the name of the project, not the project file, ie
the <samp><span class="file">.gpr</span></samp> 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:
     <pre class="smallexample">          GPS.current_context().project().name()
</pre>
     <br><dt><code>%P</code><dd>The root project. This is the name of the project, not the project file. 
Python equivalent:
     <pre class="smallexample">          GPS.Project.root().name()
</pre>
     <br><dt><code>%Pb</code><dd>The basename of the root project file.

     <br><dt><code>%Pl</code><dd>The name of the root project, all lower case.

     <br><dt><code>%pp</code><dd>The current project file pathname. If a file is selected, this is the project
file to which the source file belongs. 
Python equivalent:
     <pre class="smallexample">          GPS.current_context().project().file().name()
</pre>
     <br><dt><code>%PP</code><dd>The root project pathname. 
Python equivalent:
     <pre class="smallexample">          GPS.Project.root().file().name()
</pre>
     <br><dt><code>%pps</code><dd>This is similar to <code>%pp</code>, except it returns the project name prepended
with <code>-P</code>, 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:
     <pre class="smallexample">          if GPS.current_context().project():
             return "-P" &amp; GPS.current_context().project().file().name()
</pre>
     <br><dt><code>%PPs</code><dd>This is similar to <code>%PP</code>, except it returns the project name prepended
with <code>-P</code>, or an empty string if the root project is the default project. 
This is mostly for use with the GNAT command line tools.

     <br><dt><code>%(p|P)[r](d|s)[f]</code><dd>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).

          <dl>
<dt><code>P</code><dd>the root project.

          <br><dt><code>p</code><dd>the selected project, or the root project if there is no project selected.

          <br><dt><code>r</code><dd>recurse through the projects: sub projects will be listed as well as their
sub projects, etc<small class="dots">...</small>

          <br><dt><code>d</code><dd>list the source directories.

          <p>Python equivalent:
          <pre class="smallexample">               GPS.current_context().project().source_dirs()
</pre>
          <br><dt><code>s</code><dd>list the source files.

          <p>Python equivalent:
          <pre class="smallexample">               GPS.current_context().project().sources()
</pre>
          <br><dt><code>f</code><dd>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. 
</dl>

     <br><dt><code>%s</code><dd>This is the text selected by the user, if a single line was selected. When
multiple lines were selected, this returns the empty string

     <br><dt><code>%S</code><dd>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.

     <br><dt><code>%switches(tool)</code><dd>Replaced by <code>IDE'Default_Switches (tool)</code>, in other words, if you
have a tool whose switches are defined via an xml file in GPS, they
are stored as <code>Default_Switches (xxx)</code> in the <code>IDE</code> package
and can be retrieved using this macro. The value returned is a list of
switches, or an empty list if not set.

     <p>Note: This macro is only available in the commands defined in the Build
Manager and Build Launcher dialogs.

     <br><dt><code>%T</code><dd>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.

     <br><dt><code>%TT</code><dd>Same as <code>%TT</code>, but returns the full path to main sources rather than
the base filename.

     <br><dt><code>%attr(Package'Name[,default])</code><dd>Replaced by the project attribute <code>Package'Name</code>, in other words, the
attribute <code>Name</code> from the package <code>Package</code>. <code>Package'</code> is
optional if <code>Name</code> is a top level attribute (e.g. <code>Object_Dir</code>).

     <p>If the attribute is not defined in the project, an optional <code>default</code>
value is returned, or an empty string if not.

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

     <br><dt><code>%dirattr(Package'Name[,default])</code><dd>Replaced by the directory part of an attribute. The attribute is specified
as in <code>%attr</code> above.

     <br><dt><code>%baseattr(Package'Name[,default])</code><dd>Replaced by the base name of an attribute. The attribute is specified
as in <code>%attr</code> above.

     <br><dt><code>%vars</code><dd>Replaced by a list of switches of the form <code>&lt;variable&gt;=&lt;value&gt;</code>, where
&lt;variable&gt; is the name of a scenario variable and &lt;value&gt; 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 <code>%vars(-D)</code> to generate a list of
switches of the form <code>-D&lt;variable&gt;=&lt;value&gt;</code>. 
Note: this macro is only available in the commands defined in the Build
Manager and the Build Launcher dialogs.

     <br><dt><code>%X</code><dd>Replaced by a list of switches of the form <code>-X&lt;variable&gt;=&lt;value&gt;</code>, where
&lt;variable&gt; is the name of a scenario variable and &lt;value&gt; 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.

     <br><dt><code>%%</code><dd>Replaced by the % sign. 
</dl>

   <p><a name="index-example-798"></a>Examples:

     <dl>
<dt><code>%Ps</code><dd>Replaced by a list of source files in the root project.

     <br><dt><code>%prs</code><dd>Replaced by a list of files in the current project, and all imported
sub projects, recursively.

     <br><dt><code>%prdf</code><dd>Replaced by the name of a file that contains a list of source
directories in the current project, and all imported sub projects,
recursively. 
</dl>

   <p>Another type of macros are expanded before commands are executed: These
all start with the <code>$</code> 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 <code>execute_action</code>, which
you can use yourself to execute an action and pass it some arguments.

   <p>These arguments are the following
     <dl>
<dt><code>$1, $2, ... $n</code><dd>Where n is a number. These are each argument passed to the action

     <br><dt><code>$1-, $2-, ... $n-</code><dd>This represents a string concatenating the specified argument and all
arguments after it

     <br><dt><code>$*</code><dd>This represents a string concatenating all arguments passed to the action

     <br><dt><code>$repeat</code><dd>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 <code>"Repeat Next"</code>, which allows automatic
repetition of an action.

     <p>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:

     <pre class="smallexample">          &lt;action name="my_action"&gt;
             &lt;shell lang="python"&gt;if $repeat==1: my_function($remaining + 1)&lt;/shell&gt;
          &lt;/action&gt;
          
          def my_function (count):
             """Perform an action count times"""
             ...
</pre>
     <p>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 <code>$remaining</code> parameter).

     <br><dt><code>$remaining</code><dd>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.

   </dl>

<!--  -->
   </body></html>