/usr/share/doc/gnat-gps/html/Defining-text-aliases.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<!-- 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 2 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/.

A copy of the license is included in the section entitled
"GNU General Public License". -->
<!-- Created by GNU Texinfo 5.1, http://www.gnu.org/software/texinfo/ -->
<head>
<title>Using the GNAT Programming Studio: Defining text aliases</title>

<meta name="description" content="Using the GNAT Programming Studio: Defining text aliases">
<meta name="keywords" content="Using the GNAT Programming Studio: Defining text aliases">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="makeinfo">
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link href="index.html#Top" rel="start" title="Top">
<link href="Index-table.html#Index-table" rel="index" title="Index table">
<link href="Customizing-through-XML-and-Python-files.html#Customizing-through-XML-and-Python-files" rel="up" title="Customizing through XML and Python files">
<link href="Defining-project-attributes.html#Defining-project-attributes" rel="next" title="Defining project attributes">
<link href="Adding-support-for-new-languages.html#Adding-support-for-new-languages" rel="previous" title="Adding support for new languages">
<style type="text/css">
<!--
   

a.summary-letter {text-decoration: none}
blockquote.smallquotation {font-size: smaller}
div.display {margin-left: 3.2em}
div.example {margin-left: 3.2em}
div.indentedblock {margin-left: 3.2em}
div.lisp {margin-left: 3.2em}
div.smalldisplay {margin-left: 3.2em}
div.smallexample {margin-left: 3.2em}
div.smallindentedblock {margin-left: 3.2em; font-size: smaller}
div.smalllisp {margin-left: 3.2em}
kbd {font-style:oblique}
pre.display {font-family: inherit}
pre.format {font-family: inherit}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: inherit; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: inherit; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.nocodebreak {white-space:nowrap}
span.nolinebreak {white-space:nowrap}
span.roman {font-family:serif; font-weight:normal}
span.sansserif {font-family:sans-serif; font-weight:normal}
ul.no-bullet {list-style: none}
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 lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Defining-text-aliases"></a>
<div class="header">
<p>
Next: <a href="Defining-project-attributes.html#Defining-project-attributes" accesskey="n" rel="next">Defining project attributes</a>, Previous: <a href="Adding-support-for-new-languages.html#Adding-support-for-new-languages" accesskey="p" rel="previous">Adding support for new languages</a>, Up: <a href="Customizing-through-XML-and-Python-files.html#Customizing-through-XML-and-Python-files" accesskey="u" rel="up">Customizing through XML and Python files</a> &nbsp; [<a href="Index-table.html#Index-table" title="Index" rel="index">Index</a>]</p>
</div>
<hr>
<a name="Defining-text-aliases-1"></a>
<h4 class="subsection">16.5.13 Defining text aliases</h4>
<a name="index-aliases-2"></a>
<a name="index-_003calias_003e"></a>

<p>GPS provides a mechanism known as <b>aliases</b>. These are defined
through the menu <code>Edit-&gt;Aliases</code>.
</p>
<p>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 <tt class="key">control-o</tt>, controlled by a
preference), this name is removed from the source editor, and replaced
by the text you have associated with it.
</p>
<p>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 (the comparison is case insensitive), this
alias is expanded.
</p>

<a name="index-screen-shot-55"></a>
<img src="aliases.jpg" alt="aliases">

<p>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.
</p>
<p>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.
</p>
<p>The following special entities are currently defined:
</p>
<dl compact="compact">
<dt><code>%_</code></dt>
<dd><p>This is the position where the cursor should be put once the
replacement text has been inserted in the editor.
</p>
</dd>
<dt><code>%(name)</code></dt>
<dd><p>This is the name of a parameter. <i>name</i> can be any string you want,
excluding closing parenthesis. See below for more information on
parameters.
</p>
</dd>
<dt><code>%D</code></dt>
<dd><p>This is the current date, in ISO format. The year is displayed first,
then the month and the day
</p>
</dd>
<dt><code>%H</code></dt>
<dd><p>This is the current time (hour, minutes and seconds)
</p>
</dd>
<dt><code>%l</code></dt>
<dd><p>If the expansion of the alias is done in a source editor, this is the
line on which the cursor is when pressing <tt class="key">control-o</tt>.
</p>
</dd>
<dt><code>%c</code></dt>
<dd><p>This is similar to <i>%l</i>, except it returns the current column.
</p>
</dd>
<dt><code>%f</code></dt>
<dd><p>If the expansion is done in a source editor, this is the name of the
current file (its base name only, this doesn&rsquo;t include the directory)
</p>
</dd>
<dt><code>%d</code></dt>
<dd><p>If the expansion is done in a source editor, this is the directory in
which the current file is
</p>
</dd>
<dt><code>%p</code></dt>
<dd><p>If the expansion is done in a source editor, this is the base name of
the project file to which the file belongs.
</p>
</dd>
<dt><code>%P</code></dt>
<dd><p>If the expansion is done in a source editor, this is the full path
name to the project file (directory and base name).
</p>
</dd>
<dt><code>%O</code></dt>
<dd><p>Used for recursive aliases expansion. This special character will expand
the text seen before it in the current alias, after replacement of the
parameters and possibly other recursive expansions. This is similar to pressing
<tt class="key">control-o</tt> (or any key you have defined for alias expansion) in the
expanded form of the alias.
</p>
</dd>
<dt><code>%%</code></dt>
<dd><p>Inserts a percent sign as part of the expanded text
</p>
<p>You cannot expand an alias recursively when already expanding that alias. For
instance, if the alias expansion for <i>procedure</i> contains <i>procedure%O</i>,
the inner procedure will not be expanded.
</p>
</dd>
</dl>

<p>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. You can override this default behavior
by selecting the check button <code>Indent source editor after expansion</code>.
In this case, GPS will replace the name of the alias by its expansion,
and then automatically recompute the position of each line with its
internal indentation engine, as if the text had been inserted manually.
</p>
<p>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
<i>%(name)</i> 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.
</p>
<p>Each parameters has three attributes:
</p>
<dl compact="compact">
<dt><b>name</b></dt>
<dd><p>This is the name you use in the expansion text of the alias in the
<i>%(name)</i> special entity.
</p>
</dd>
<dt><b>Environment</b></dt>
<dd><p>This specifies whether the default value of the parameter comes from
the list of environment variables set before GPS was started.
</p>
</dd>
<dt><b>default value</b></dt>
<dd><p>Instead of getting the default value from the environment variable,
you can also specify a fixed text.
Clicking on the initial value of the currently selected variable opens
a text entry which you can use to edit this default value.
</p>
</dd>
</dl>

<p>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 <i>%(name)</i>
entities in the expansion text.
</p>
<a name="Aliases-files"></a>
<h4 class="subsection">16.5.14 Aliases files</h4>

<p>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.
</p>
<p>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.
</p>
<p>There is one specific files, which must contain only aliases definition. This
is the file <samp>$HOME/.gps/aliases</samp>. 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.
</p>
<p>The system files are loaded first, and aliases defined there can be
overridden by the user-defined file.
</p>
<p>These files are standard XML customization files.
The specific XML tag to use is <i>&lt;alias&gt;</i>, one per new alias.
The following example contains a standalone customization file, but you might
wish to merge the <i>&lt;alias&gt;</i> tag in any other customization file.
</p>
<p>The following tags are available:
</p>
<dl compact="compact">
<dt><code>alias</code></dt>
<dd><p>This indicates the start of a new alias. It has one mandatory
attribute, <code>name</code>, which the text to type in the source editor
before pressing <tt class="key">control-o</tt>.
It has one optional attribute, <code>indent</code>, which, if set to <i>true</i>,
indicate that GPS should recompute the indentation of the newly inserted
paragraph after the expansion.
</p>
</dd>
<dt><code>param</code></dt>
<dd><p>These are children of the <code>alias</code> node. There is one per
parameter of the alias. They have one mandatory attribute,
<code>name</code>, which is the name to type between <i>%(name)</i> in the
alias expansion text.
</p>
<p>They have one optional attribute, <code>environment</code>, which indicates
the default value must be read from the environment variables if it is
set to true.
</p>
<p>These tags contain text, which is the default value for the parameter.
</p>
</dd>
<dt><code>text</code></dt>
<dd><p>This is a child of the <code>alias</code> node, whose value is the
replacement text for the alias.
</p></dd>
</dl>

<p>Here is an example of an alias file:
</p>
<div class="smallexample">
<pre class="smallexample">&lt;?xml version=&quot;1.0&quot;?&gt;
&lt;Aliases&gt;
  &lt;alias name=&quot;proc&quot; &gt;
    &lt;param name=&quot;p&quot; &gt;Proc1&lt;/param&gt;
    &lt;param environment=&quot;true&quot; name=&quot;env&quot; /&gt;
    &lt;text&gt;procedure %(p) is
%(env)%_
end %(p);&lt;/text&gt;
  &lt;/alias&gt;
&lt;/Aliases&gt;
</pre></div>

<hr>
<div class="header">
<p>
Next: <a href="Defining-project-attributes.html#Defining-project-attributes" accesskey="n" rel="next">Defining project attributes</a>, Previous: <a href="Adding-support-for-new-languages.html#Adding-support-for-new-languages" accesskey="p" rel="previous">Adding support for new languages</a>, Up: <a href="Customizing-through-XML-and-Python-files.html#Customizing-through-XML-and-Python-files" accesskey="u" rel="up">Customizing through XML and Python files</a> &nbsp; [<a href="Index-table.html#Index-table" title="Index" rel="index">Index</a>]</p>
</div>



</body>
</html>
gnat-gps-doc 5.0-16 / usr / share / doc / gnat-gps / html / Defining-text-aliases.html
