1 \input texinfo @c -*-texinfo-*-
2 @setfilename ../../info/gpr-mode
6 Copyright @copyright{} 2013 Free Software Foundation, Inc.
9 Permission is granted to copy, distribute and/or modify this document
10 under the terms of the GNU Free Documentation License, Version 1.3 or
11 any later version published by the Free Software Foundation; with no
12 Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
13 and with the Back-Cover Texts as in (a) below. A copy of the license
14 is included in the section entitled ``GNU Free Documentation License''.
16 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
17 modify this GNU manual. Buying copies from the FSF supports it in
18 developing GNU and promoting software freedom.''
22 @dircategory Emacs editing modes
24 * gpr mode: (gpr-mode). Emacs mode for editing and navigating gpr files (gnat project files).
31 @subtitle An Emacs major mode for editing and navigating gpr files
34 @vskip 0pt plus 1filll
40 @node Top, Overview, (dir), (dir)
50 * Moving Through Gpr Code::
51 * Identifier completion::
53 * Statement skeletons::
54 * GNU Free Documentation License::
58 @node Overview, Installation, Top, Top
60 gpr files are the project files used by the GNAT compiler and
61 associated tools. They describe search paths, compiler options, etc.
63 @xref{GNAT Project Manager,,GNAT Project Manager,gnat_ugn,GNAT Pro
64 User's Guide}, for general information on gpr files.
66 The Emacs mode for gpr files helps the user in reading
67 existing code and facilitates writing new code.
69 When you open a file with a file extension of @file{.gpr}, Emacs will
70 automatically load and activate gpr mode.
72 @node Installation, Customization, Overview, Top
75 gpr mode is distributed in the Gnu ELPA package archive, bundled with
76 Ada mode; it can be installed via @code{M-x list-packages}
77 (@pxref{Packages,,,emacs,Emacs User Guide}).
79 gpr mode is also available as a separate distribution bundled with
80 Ada mode, from the Emacs Ada mode website
81 @uref{http://stephe-leake.org/emacs/ada-mode/emacs-ada-mode.html}. The
82 separate distribution may be more recent.
84 For installing the separate distribution, see the @file{README} file
87 gpr mode does not have a separate version; it uses the Ada mode
88 version number. To see what version of Ada mode you have installed, do
89 @kbd{M-x ada-mode-version}.
91 @node Customization, Moving Through Gpr Code, Installation, Top
92 @chapter Customization
94 gpr mode uses the Ada mode indentation variables; they can be set via
95 the menu @samp{Ada | Customize} from an Ada mode buffer. Click on the
96 @samp{Help} button there for help on using customize.
98 To modify a specific variable, you can directly call the function
99 @code{customize-variable}; just type @kbd{M-x customize-variable
100 @key{RET} @var{variable-name} @key{RET}}).
102 Alternately, you can specify variable settings in the Emacs
103 configuration file, @file{~/.emacs}. This file is coded in Emacs lisp,
104 and the syntax to set a variable is the following:
106 (setq variable-name value)
109 Some general Emacs settings that are useful for gpr files:
111 @item delete-trailing-whitespace
112 Deletes space, tab at end of line and blank lines at end of buffer.
114 Deletes tab characters that have crept into the file.
115 @item indent-tabs-mode
116 Don't insert tab characters when indenting.
118 Bind @code{hippie-expand} to a key; it expands the word before point,
119 using words from current buffer, other buffers, file names, etc; see
120 @code{hippie-expand-try-functions-list}. You can also add
121 @code{skeleton-hippie-try} to that list (@pxref{Statement skeletons}).
124 The above can all be set by the following code in your
125 @file{~/.emacs}. Note that some are functions are added to
126 @code{before-save-hook}; they run just before a buffer is written to disk.
128 (setq-default indent-tabs-mode nil)
130 (add-to-list 'hippie-expand-try-functions-list 'skeleton-hippie-try)
131 (define-key gpr-mode-map "\C-e" 'hippie-expand)
132 (add-hook 'gpr-mode-hook
134 (add-hook 'before-save-hook 'delete-trailing-whitespace nil t)
135 (add-hook 'before-save-hook
136 (lambda () (untabify (point-min) (point-max)))
140 @node Moving Through Gpr Code, Identifier completion, Customization, Top
141 @chapter Moving Through Gpr Code
143 These commands navigate through gpr code. All these functions are
144 available through the gpr menu and keybindings.
148 @findex ff-find-other-file
149 If point is on a @code{with} clause, position point on the
150 corresponding package declaration.
153 Jump back to the previous location.
157 @node Identifier completion, Indentation, Moving Through Gpr Code, Top
158 @chapter Identifier completion
160 Emacs provides a general way of completing identifiers: @kbd{M-/}
161 (bound to @code{dabbrev-expand}). This is an easy way to type faster:
162 you just have to type the first few letters of an identifier, and then
163 loop through all the possible completions.
165 @kbd{M-/} works by parsing all open gpr files for possible
168 For instance, if the words @samp{my_identifier} and @samp{my_subprogram}
169 are the only words starting with @samp{my} in any of the open gpr files,
170 then you will have this scenario:
173 You type: my@kbd{M-/}
174 Emacs inserts: @samp{my_identifier}
175 If you press @kbd{M-/} once again, Emacs replaces @samp{my_identifier} with
176 @samp{my_subprogram}.
177 Pressing @kbd{M-/} once more will bring you back to @samp{my_identifier}.
180 This is a very fast way to do completion, and the casing of words will
183 @node Indentation, Statement skeletons, Identifier completion, Top
186 gpr mode comes with a full set of rules for automatic indentation. You
187 can also configure the indentation, via the following variables:
190 @item @code{ada-indent} (default value: 3)
191 Number of columns for default indentation.
193 @item @code{ada-indent-broken} (default value: 2)
194 Number of columns to indent the continuation of a broken line.
196 @item @code{ada-indent-when} (default value: 3)
197 Indentation for @code{when} relative to @code{exception}, @code{case},
198 or @code{or} in @code{select}.
200 @item @code{ada-indent-with} (default value: ada-indent-broken)
201 Indentation for the lines in a @code{with} context clause.
205 The following keys indent portions of the text:
209 Insert and indent a new line.
212 Indent the current line, or the current region.
215 Indent the current declaration.
219 The indentation algorithm relies on a grammar parser to identify the
220 syntactic role for keywords and other words in the code. If the code
221 is accepted by the parser, the indentation is done according to the
222 rules in the indentation engine.
224 If the code is not accepted (because it is partially complete during
225 editing), the indentation engine falls back to the trivial algorithm
226 of indenting each new line the same as the previous line. Once enough
227 new text has been entered to make the code acceptable to the parser,
228 the declaration is properly indented.
230 For example, if you are entering this code:
235 "../../system/test");
238 when you type @kbd{RET (}, @code{(} is indented to the same column as
239 @code{for}, because the parser does not find @code{);}. Then when
240 you type the final @code{;} followed by @key{TAB}, all three lines are
241 indented, putting @code{(} where it belongs.
243 To be more user friendly, the parser accepts a superset of the gpr
244 grammer. For example, the parser accepts this code for a @code{case}
252 In general, any sequence of statements, and many expressions, may be
255 One way to easily insert empty statements like this is using
256 @ref{Statement skeletons}.
258 In rare cases, the parser gets confused; it can be reset by invoking
259 menu @key{gpr | Misc | Reset parser}. Please report such cases as a
262 @node Statement skeletons, GNU Free Documentation License, Indentation, Top
263 @chapter Statement skeletons
265 @kbd{C-c C-e} expands the previous one or two words into a statment
266 skeleton. For example, @kbd{c a s e C-c C-e} expands to:
274 All skeleton expansions are accepted by the indentation parser, so
275 this is a convenient way to insert statements with correct
278 For named packages, the name is taken from
279 the word before point, and the package keyword from the word
293 Some expansions prompt for more information, such as
296 @node GNU Free Documentation License, Index, Statement skeletons, Top
297 @appendix GNU Free Documentation License
298 @include doclicense.texi
300 @node Index, , GNU Free Documentation License, Top