\input texinfo  @c -*-texinfo-*-
@settitle gpr Mode

@copying
Copyright @copyright{} 2013, 2019  Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual'',
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled ``GNU Free Documentation License''.

(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
modify this GNU manual.  Buying copies from the FSF supports it in
developing GNU and promoting software freedom.''
@end quotation
@end copying

@dircategory Emacs
@direntry
* gpr mode: (gpr-mode).         Emacs mode for editing and navigating gpr files (gnat project files).
@end direntry

@titlepage
@sp 10
@title gpr Mode
@sp 2
@subtitle An Emacs major mode for editing and navigating gpr files
@sp 2
@page
@vskip 0pt plus 1filll
@insertcopying
@end titlepage

@contents

@ifnottex
@node Top, Overview, (dir), (dir)
@end ifnottex

@menu
* Overview::
* Installation::
* Customization::
* Moving Through Gpr Code::
* Identifier completion::
* Indentation::
* Statement skeletons::
* GNU Free Documentation License::
* Index::
@end menu

@node Overview, Installation, Top, Top
@chapter Overview
gpr files are the project files used by the GNAT compiler and
associated tools. They describe search paths, compiler options, etc.

@xref{GNAT Project Manager,,GNAT Project Manager,gnat_ugn,GNAT Pro
User's Guide}, for general information on gpr files.

The Emacs mode for gpr files helps the user in reading
existing code and facilitates writing new code.

When you open a file with a file extension of @file{.gpr}, Emacs will
automatically load and activate gpr mode.

@node Installation, Customization, Overview, Top
@chapter Installation

gpr mode is distributed in the Gnu ELPA package archive, bundled with
Ada mode; it can be installed via @code{M-x list-packages}
(@pxref{Packages,,,emacs,Emacs User Guide}).

gpr mode does not have a separate version; it uses the Ada mode
version number. To see what version of Ada mode you have installed, do
@kbd{M-x ada-mode-version}.

@node Customization, Moving Through Gpr Code, Installation, Top
@chapter Customization

Indentation variables for gpr mode can be set via the menu @samp{gpr |
Customize} from a gpr mode buffer.  Click on the @samp{Help} button
there for help on using customize. @xref{Indentation}.

To modify a specific variable, you can directly call the function
@code{customize-variable}; just type @kbd{M-x customize-variable
@key{RET} @var{variable-name} @key{RET}}).

Alternately, you can specify variable settings in the Emacs
configuration file, @file{~/.emacs}. This file is coded in Emacs lisp,
and the syntax to set a variable is the following:
@example
(setq variable-name value)
@end example

Some general Emacs settings that are useful for gpr files:
@table @code
@item delete-trailing-whitespace
Deletes space, tab at end of line and blank lines at end of buffer.
@item untabify
Deletes tab characters that have crept into the file.
@item indent-tabs-mode
Don't insert tab characters when indenting.
@item hippie-expand
Bind @code{hippie-expand} to a key; it expands the word before point,
using words from current buffer, other buffers, file names, etc; see
@code{hippie-expand-try-functions-list}. You can also add
@code{wisi-skel-hippie-try} to that list (@pxref{Statement skeletons}).
@end table

The above can all be set by the following code in your
@file{~/.emacs}. Note that some are functions are added to
@code{before-save-hook}; they run just before a buffer is written to disk.
@example
(setq-default indent-tabs-mode nil)
(require 'gpr-mode)
(add-to-list 'hippie-expand-try-functions-list 'wisi-skel-hippie-try)
(define-key gpr-mode-map "\C-e"     'hippie-expand)
(add-hook 'gpr-mode-hook
   (lambda ()
    (add-hook 'before-save-hook 'delete-trailing-whitespace nil t)
    (add-hook 'before-save-hook
              (lambda () (untabify (point-min) (point-max)))
               nil t)))
@end example

@node Moving Through Gpr Code, Identifier completion, Customization, Top
@chapter Moving Through Gpr Code

These commands navigate through gpr code. All these functions are
available through the gpr menu and keybindings.

@table @kbd
@item C-c C-o
@findex ff-find-other-file
If point is on a @code{with} clause, position point on the
corresponding package declaration.

@item C-u SPACE
Jump back to the previous location.

@item C-M-f
Move to the end of the current declaration.

@item C-M-b
Move to the start of the current declaration.

@end table

@node Identifier completion, Indentation, Moving Through Gpr Code, Top
@chapter Identifier completion

Emacs provides a general way of completing identifiers: @kbd{M-/}
(bound to @code{dabbrev-expand}). This is an easy way to type faster:
you just have to type the first few letters of an identifier, and then
loop through all the possible completions.

If you have bound @code{hippie-expand}, that also uses
@code{dabbrev-expand}.

@kbd{M-/} works by parsing all open gpr files for possible
completions.

For instance, if the words @samp{my_identifier} and @samp{my_subprogram}
are the only words starting with @samp{my} in any of the open gpr files,
then you will have this scenario:

@example
You type:  my@kbd{M-/}
Emacs inserts:  @samp{my_identifier}
If you press @kbd{M-/} once again, Emacs replaces @samp{my_identifier} with
@samp{my_subprogram}.
Pressing @kbd{M-/} once more will bring you back to @samp{my_identifier}.
@end example

This is a very fast way to do completion, and the casing of words will
also be respected.

@node Indentation, Statement skeletons, Identifier completion, Top
@chapter Indentation

gpr mode comes with a full set of rules for automatic indentation. You
can also configure the indentation, via the following variables:

@table @asis
@item @code{gpr-indent}                  (default value: 3)
Number of columns for default indentation.

@item @code{gpr-indent-broken}           (default value: 2)
Number of columns to indent the continuation of a broken line.

@item @code{gpr-indent-when}             (default value: 3)
Indentation for @code{when} relative to @code{case}.

@end table

The following keys indent portions of the text:
@table @kbd

@item RET
Insert and indent a new line.

@item TAB
Indent the current line, or the current region.

@item C-c TAB
Indent the current declaration.

@end table

The indentation algorithm relies on an error-correcting grammar parser
to identify the syntactic role for keywords and other words in the
code.

@node Statement skeletons, GNU Free Documentation License, Indentation, Top
@chapter Statement skeletons

@kbd{C-c C-e} expands the previous one or two words into a statment
skeleton. For example, @kbd{c a s e C-c C-e} expands to:

@example
case  is
when =>
end case;
@end example

For named packages, the name is taken from
the word before point, and the package keyword from the word
before that:

@example
package A_Package
@end example

expands to:

@example
package A_Package is
end A_Package;
@end example

Some expansions prompt for more information, such as
a choice of license.

@node GNU Free Documentation License, Index, Statement skeletons, Top
@appendix GNU Free Documentation License
@include doclicense.texi

@node Index,  , GNU Free Documentation License, Top
@unnumbered Index

@printindex fn

@bye
