4. Editing Files — GPS 6.0.1 documentation

### Navigation

- index
- modules |
- next |
- previous |
- GPS 6.0.1 documentation »

# 4. Editing Files

## 4.1. General Information

Source editing is one of the central parts of GPS, giving in turn access to many other functionalities, including extended source navigation and source analyzing tools.

The source editor provides an extensive set of features, including:

Title bar
  Showing the full name of the file including path information in the title bar of the GPS window.
Line number information
  This is the left area of the source editor. Line numbers can be disabled with the Editor ‣ Display line numbers preference. Note that this area can also display additional information, such as the current line of execution when debugging, or cvs annotations.
Scrollbar
  Located on the right of the editor, it allows you to scroll through the source file. When you scroll, GPS displays a convenient tooltip that shows the subprogram the cursor currently is in.
Speed column
  This column, when visible, is located on the left of the editor. It allows you to view all the highlighted lines in a file, at a glance. For example, all the lines containing compilation errors are displayed in the Speed Column. The preference Editor ‣ Speed column policy can be used to control the display of this area. It can sometimes be convenient to keep it visible at all time (to avoid resizing of the editors when new information becomes available), or on the other hand to hide it automatically when it is not needed to save some space on the screen.
Status bar

  Giving information about the file. It is divided in two sections, one on the left and one on the right of the window.

  - the left part of the status bar shows the current subprogram name for languages that support this capability. Currently Ada, C and C++ have this ability. The preference Editor ‣ Display subprogram names controls this display.

  - The right section contains multiple pieces of information:

    - The box displays the position of the cursor in the file by a line and a column number. When a selection is performed in the editor, this area also displays the size of the selection (number of lines and number of characters).

    - next to it is an icon that shows whether the file is writable or read-only. You can change this state by clicking on the icon directly: this will toggle between Writable and Read Only. Note that this will not change the permissions of the file on disk, it will only change the writable state of the source editor within GPS.

      When trying to save a file which is read only on the disk, GPS will ask for confirmation, and if possible, will force saving of the file, keeping its read only state.

    - If the file is maintained under version control, and version control is supported and enabled in GPS, the next icon will show VCS information on the file: the VCS kind (e.g. CVS or subversion), followed by the revision number, and if available, the status of the file.

Contextual menu
  Displayed when you right-click on any area of the source editor. See in particular Contextual Menus for Source Navigation for more details.
Syntax highlighting

  Based on the programming language associated with the file, reserved words and languages constructs such as comments and strings are highlighted in different colors and fonts.

  By default, GPS knows about many languages. You can also easily add support for other languages through plug-ins. Most languages supported by GPS will provide syntax highlighting in the editor.

Automatic indentation

  When enabled, lines are automatically indented each time you press the `Enter` key, or by pressing the indentation key. The indentation key is `Tab` by default, and can be changed in the key manager dialog, The Key Manager Dialog.

  If a set of lines is selected when you press the indentation key, this whole set of lines will be indented.

Tooltips

  When you leave the mouse over a word in the source editor, a small window will automatically pop up if there are relevant contextual information to display about the word.

  The type of information displayed depends on the current state of GPS.

  In normal mode, the entity kind and the location of declaration is displayed when this information is available. That is, when the cross-reference information about the current file has been generated. If there is no relevant information, no tooltip is displayed. See Support for Cross-References for more information.

  In addition, the documentation for the entity is displayed. This is the block of comments just before or just after the entity’s declaration of body. There mustn’t be any blank line between the two. For instance, the following are valid documentation for Ada and C:

      --  A comment for A
      A : Integer;

      B : Integer;
      --  A comment for B

      C : Integer;

      --  Not a comment for C, there is a blank linke

  When comments appear both before and after the entity, GPS will chose the one given by the preference Documentation ‣ Leading documentation.

  In debugging mode, the value of the variable under the mouse is displayed in the pop up window if the variable is known to the debugger. Otherwise, the normal mode information is displayed.

  You can disable the automatic pop up of tool tips via the preference Editor ‣ Tooltips.

Code completion

  GPS provides two kinds of code completion: a smart code completion based on semantic information, and a text completion.

  The simple text completion is useful when editing a file and using often the same words to get automatic word completion. This is possible by typing the `Ctrl-/` key combination (customizable through the key manager dialog) after a partial word: the next possible completion will be inserted in the editor. Typing this key again will cycle through the list of possible completions.

  Text completions are searched in all currently open source files, by first looking at the closest words and then looking further in the source as needed.

Delimiter highlighting

  When the cursor is moved before an opening delimiter or after a closing delimiter, then both delimiters will be highlighted. The following characters are considered delimiters: ()[]{}. You can disable highlighting of delimiters with the preference Editor ‣ Highlight delimiters.

  You can also jump to a corresponding delimiter by using the `Ctrl-'` key, that can be configured in the shortcuts editor. Typing twice on this key will move the cursor back to its original position.

Current line highlighting
  You can configure the editor to highlight the current line with a certain color (see the preference Editor ‣ Fonts & Colors ‣ Current line color).
Current block highlighting

  If the preference Editor ‣ Block highlighting is enabled, the editor will highlight the current block of code, e.g. the current begin...end block, or loop statement, etc... with a vertical bar to its left side.

  The block highlighting will also take into account the changes made in your source code, and will recompute automatically the current block when needed.

  This capability is currently implemented for Ada, C and C++ languages.

Block folding

  When the preference Editor ‣ Block folding is enabled, the editor will display - icons on the left side, corresponding to the beginning of subprograms. If you click on one of these icons, all the lines corresponding to this block are hidden, except the first one. As for the block highlighting, these icons are recomputed automatically when you modify your sources and are always kept up to date.

  This capability is currently implemented for Ada, C and C++ languages.

Auto save
  You can configure the editor to periodically save modified files. See Autosave delay for a full description of this capability.
Automatic highlighting of entities

  When the cursor is positioned on an entity in the source editor, GPS will highlight all references to this entity in the current editor.

  When the cursor moves away from the entity, the highlighting is removed.

  This is controlled by the plugin `auto_highlight_occurrences.py`: it can be deactivated by disabling the plugin (The Plug-ins Editor).

  Details such as presence of indications in the Speed Column or highlighting color can be customized in the Plugins section of The Preferences Dialog.

GPS also integrates with existing third party editors such as Emacs or vi. Using an External Editor.

## 4.2. Editing Sources

### 4.2.1. Key bindings

In addition to the standard keys used to navigate in the editor (up, down, right, left, page up, page down), the integrated editor provides a number of key bindings allowing easy navigation in the file.

There are also several ways to define new key bindings, see Defining text aliases and Binding actions to keys.

`Ctrl-Shift-u` | Pressing these three keys and then holding Ctrl-Shift allow you to enter characters using their hexadecimal value. For example, pressing
`Ctrl-Shift-u-2-0` | will insert a space character (ASCII 32, which is 20 in hexadecimal).
`Ctrl-x` `Shift-delete` | Cut to clipboard
`Ctrl-c` `Shift-insert` | Copy to clipboard
`Ctrl-v` `Shift-insert` | Paste from clipboard
`Ctrl-s` | Save file to disk
`Ctrl-z` | Undo previous insertion/deletion
`Ctrl-r` | Redo previous insertion/deletion
`Insert` | Toggle overwrite mode
`Ctrl-a` | Select the whole file
`Home` `Ctrl-Pgup` | Go to the beginning of the line
`End` `Ctrl-Pgdown` | Go to the end of the line
`Ctrl-Home` | Go to the beginning of the file
`Ctrl-End` | Go to the end of the file
`Ctrl-up` | Go to the beginning of the line, or to the previous line if already at the beginning of the line.
`Ctrl-down` | Go to the end of the line, or to the beginning of the next line if already at the end of the line.
`Ctrl-delete` | Delete end of the current word.
`Ctrl-backspace` | Delete beginning of the current word.

## 4.3. Menu Items

The main menus that give access to extended functionalities related to source editing are described in this section.

### 4.3.1. The File Menu

File ‣ New

  Open a new untitled source editor. No syntax highlighting is performed until the file is saved, since GPS needs to know the file name in order to choose the programming language associated with a file.

  When you save a new file for the first time, GPS will ask you to enter the name of the file. In case you have started typing Ada code, GPS will try to guess based on the first main entity in the editor and on the current naming scheme, what should be the default name of this new file.

File ‣ New View

  Create a new view of the current editor. The new view shares the same contents: if you modify one of the source views, the other view is updated at the same time. This is particularly useful when you want to display two separate parts of the same file, for example a function spec and its body.

  A new view can also be created by keeping the `shift` key pressed while drag-and-dropping the editor (see Moving Windows). This second method is preferred, since you can then specify directly where you want to put the new view. The default when using the menu is that the new view is put on top of the editor itself.

File ‣ Open...
  Open a file selection dialog where you can select a file to edit. On Windows, this is the standard file selector. On other platforms, this is a built-in file selector described in The File Selector.

File ‣ Open From Project...
  Moves the focus to the The omni-search field, where you can immediately start typing part of the file name you wish to open. This is the fastest way to select files to open.

File ‣ Open From Host...

  Open a file selector dialog where you can specify a remote host, as defined in The remote configuration dialog. You have access to a remote host file system, can specify a file which can be edited in GPS. When you hit the save button or menu, the file will be saved on the remote host.

  See also Using GPS for Remote Development for a more efficient way to work locally on remote files.

File ‣ Recent
  Open a sub menu containing a list of the ten most recent files opened in GPS, so that you can reopen them easily.

File ‣ Save
  Save the current source editor if needed.

File ‣ Save As...
  Same current file under a different name, using the file selector dialog. The File Selector.

File ‣ Save More

  Give access to extra save capabilities:

  - File ‣ Save More ‣ All

      Save all items, including projects, etc...

  - File ‣ Save More ‣Desktop

      Save the desktop to a file. The desktop includes information about files, graphs, ... and their window size and position in GPS. The desktop is saved per top level project, so that if you reload the same project you get back to the same situation you were in when you left GPS. Instead, if you load a different project another desktop will be loaded (or the default desktop). Through the preference General‣Save Desktop On Exit, you can also automatically save this desktop when you quit GPS.

File ‣ Change Directory...
  Open a directory selection dialog that lets you change the current working directory.

File ‣ Locations

  This sub menu gives access to functionalities related to the Locations window.

  - File ‣ Locations ‣ Export Locations to Editor

      List the contents of the Locations view in a standard text editor.

File ‣ Print

  Print the current window contents, optionally saving it interactively if it has been modified. The Print Command specified in the preferences is used if it is defined. On Unix this command is required; on Windows it is optional.

  On Windows, if no command is specified in the preferences the standard Windows print dialog box is displayed. This dialog box allows the user to specify the target printer, the properties of the printer, which pages to print (all, or a specific range of pages), the number of copies to print, and, when more than one copy is specified, whether the pages should be collated. Pressing the Cancel button on the dialog box returns to GPS without printing the window contents; otherwise the specified pages and copies are printed on the selected printer. Each page is printed with a header containing the name of the file (if the window has ever been saved). The page number is printed on the bottom of each page.

  See also:ref:Print Command <Print_Command>.

File ‣ Close
  Close the current window. This applies to all GPS windows, not just source editors.

File ‣ Exit
  Exit GPS after confirmation and if needed, confirmation about saving modified windows and editors.

### 4.3.2. The Edit Menu

Edit ‣ Cut
  Cut the current selection and store it in the clipboard.

Edit ‣ Copy
  Copy the current selection to the clipboard.

Edit ‣ Paste
  Paste the contents of the clipboard to the current cursor position.

Edit ‣ Paste previous

  GPS stores a list of all the text that was previously copied into the clipboard through the use of Copy or Cut.

  By default, if you press Paste, the newest text will be copied at the current position. But if you select Paste Previous immediately after (one or more times) you can instead paste text that was copied previously in the clipboard.

  For instance, if you copy through Edit ‣ Copy the text “First”, then copy the text “Second”, you can then select Edit ‣ Paste to insert “Second” at the current location. If you then select Edit ‣ Paste Previous, “Second” will be replaced by “First”.

  Selecting this menu several times will replace the text previously pasted by the previous one in the list saved in the clipboard. When reaching the end of this list, GPS will started from the beginning, and insert again the last text copied into the clipboard.

  The size of this list is controlled by the General ‣ Clipboard Size preference.

  For more information, The Clipboard view.

Edit ‣ Undo
  Undo previous insertion/deletion in the current editor.

Edit ‣ Redo
  Redo previous insertion/deletion in the current editor.

Edit ‣ Rectangles...
  See the section Rectangles for more information on rectangles.

Edit ‣ Rectangles... -> Serialize

  Increment a set of numbers found on adjacent lines. The exact behavior depends on whether there is a current selection or not.

  If there is no selection, then the set of lines considered is from the current line on and includes all adjacent lines that have at least one digit in the original columns. In the following example, ‘|’ marks the place where the cursor is at the beginning:

      AAA |10 AAA
      CCC 34567 CCC
      DDD DDD

  then only the first two lines will be modified, and will become:

      AAA 10 AAA
      CCC 11 CCC
      DDD DDD

  If there is a selection, all the lines in the selection are modified. For each line, the columns that had digits in the first line are modified, no matter what they actually contain. In the example above, if you select all three lines, the replacement becomes:

      AAA 10 AAA
      CCC 11567 CCC
      DDD 12D

  ie only the fifth and sixth columns are modified since only those columns contained digits in the first line. This feature assumes that you are selecting a relevant set of lines. But it allows you to transform blank lines more easily. For instance, if you have:

      AAA 1
      BBB
      CCC

  this is transformed into:

      AAA 1
      BBB 2
      CCC 3

Edit ‣ Select all
  Select the whole contents of the current source editor.

Edit ‣ Insert File...
  Open a file selection dialog and insert the contents of this file in the current source editor, at the current cursor location.

Edit ‣ Insert Shell Output...
  Open an input window at the bottom of the GPS window where you can specify any external command. The output of the command will be inserted at the current editor location in case of success. If text is selected, the text is passed to the external command and replaced by the command’s output.

Edit ‣ Format selection
  Indent and format the selection or the current line. The Preferences Dialog, for preferences related to source formatting.

Edit ‣ Smart completion

  Complete the identifier prefix under the cursor, and list the results in a pop-up list. Used with Ada sources this command can take advantage of an entity database as well as Ada parsers embedded in GPS which analyze the context, and offer completions from the entire project along with documentation extracted from comments surrounding declarations. To take full advantage of this feature, the smart completion preference must be enabled, which will imply the computation of the entity database at GPS startup.

  The support for C and C++ is not as powerful as the support for Ada since it relies completely on the xref information files generated by the compiler, does not have into account the C/C++ context around the cursor, and does not extract documentation from comments around candidate declarations. To take advantage of this feature, in addition to enable the smart completion preference, the C/C++ application must be built with -fdump-xref.

  In order to use this feature, open any Ada, C or C++ file, and begin to type an identifier. It has to be an identifier declared either in the current file (and accessible from the cursor location) or in one of the packages of the project loaded. Move the cursor right after the last character of the incomplete identifier and hit the completion key (which is `control-space` by default). GPS will open a popup displaying all the known identifiers beginning with the prefix you typed. You can then browse among the various proposals by clicking on the `up` and `down` keys, or using the left scrollbar. For each entity, a documentation box is filled. If the location of the entity is known, it’s displayed as an hyperlink, and you can jump directly to its declaration by clicking on it.

  Typing new letters will reduce the range of proposal, as long as there remain solutions. Once you’ve selected the expected completion, you can validate by pressing `Enter`.

  Typing control characters (ie, characters which cannot be used in identifiers) will also validate the current selection.

  GPS is also able to complete automatically subprogram parameter or dotted notations. For example, if you type:

      with Ada.

  the smart completion window will appear automatically, listing all the child and nested packages of Ada. You can configure the time interval after which the completion window appears (The Preferences Dialog).

  You can also write the beginning of the package, e.g.:

      with Ada.Text

  pressing the completion key will offer you Text_IO.

  If you are in a code section, you will be able to complete the fields of a record, or the contents of a package, e.g.:

       declare
         type R is record
            Field1 : Integer;
            Field2 : Integer;
         end record;

         V : R;
      begin
         V.

  Completing V. will propose Field1 and Field2.

  The smart completion can also give you the possible parameters of a call you’re currently making. For example, in the following code:

         procedure Proc (A, B, C : Integer);
      begin
         Proc (1,

  If you hit the completion key after the comma, the smart completion engine will propose you to complete with the named parameters “B =>”, “C =>” or directly to complete with all the remaining parameters, which in this case will be “B =>, C => )”.

  Limitations:

  - This feature is currently only available for Ada, C and C++. Using the smart completion on sources of other languages behaves as the identifier completion does.
  - Smart completion for C and C++ is based on the xref information generated by the compiler. Therefore, GPS has no knowledge on recently edited files. You must rebuild with -fdump-xref to update the completion database.
  - Smart completion for C and C++ is only triggered at the beginning of an expression (that is, it is not triggered on special characters such as ‘(‘, ‘->’, or the C++ operator ‘::’) and it may propose too much candidates since it does not have into account the C/C++ syntax context. Typing new letters will reduce the range of proposal, as long as there remain solutions.
  - Smart completion of subprogram parameters, fields and dotted notation are not available yet for C and C++.

Edit ‣ More Completion

  This submenu contains more ways to automatically complete code

  - Edit ‣ More Completion ‣ Expand alias

    Consider the current word as an alias and expand according to aliases defined in Defining text aliases.

  - Edit ‣ More Completion ‣ Completion Identifier

    Complete the identifier prefix under the cursor. This command will cycle through all identifiers starting with the given prefix.

  - Edit – >More Completion ‣ Complete block

    Close the current statement (if, case, loop) or unit (procedure, function, package). This action works only on an Ada buffer.

Edit ‣ Selection

  This submenu contains actions that apply to the current selection in the editor.

  - Edit ‣ Selection ‣ Comment lines

    > Comment the current selection or line based on the current programming language syntax.

  - Edit ‣ Selection ‣ Uncomment lines

    > Remove the comment delimiters from the current selection or line.

  - Edit ‣ Selection ‣ Refill

    > Refill text on the selection or current line: rearrange line breaks in the paragraph so that line lengths do not exceed the maximum length, as set in the “Right margin” preference (The Preferences Dialog).

  - Edit ‣ Selection ‣ Sort

    > Sort the selected lines alphabetically. This is particularly useful when editing non source code, or for specific parts of the code, like with clauses in Ada.

  - Edit ‣ Selection ‣ Sort Reverse

    > Sort the selected lines in reverse alphabetical order

  - Edit ‣ Selection ‣ Pipe in external program...

    > Open an input window at the bottom of the GPS window where you can specify any external command, which will take the current selection as input. The output of the command will replace the contents of the selection on success.

  - Edit ‣ Selection ‣ Untabify

    > Replace all tabs in the current selection (or in the whole buffer if there is no selection) by the appropriate number of spaces

  - Edit ‣ Selection ‣ Move Right

  - Edit ‣ Selection ‣ Move Left

    > Shift the currently selected lines (or the current line if there is no selection) one character to the right or to the left

Edit ‣ Fold all blocks
  Collapse all the blocks in the current file.

Edit ‣ Unfold all blocks
  Uncollapse all the blocks in the current file.

Edit ‣ Create bookmark
  Creates a new Bookmark at cursor position. For more information, The Bookmarks view.

Edit ‣ Pretty Print
  Pretty print the current source editor by calling the external tool gnatpp. It is possible to specify gnatpp switches in the switch editor. The Switches Editor.

Edit ‣ Generate Body
  Generate Ada body stub for the current source editor by calling the external tool gnatstub.

Edit ‣ Edit with external editor
  Using an External Editor.

Edit ‣ Aliases
  Display the Aliases editor. Defining text aliases.

Edit ‣ Key shortcuts
  Give access to the key manager dialog, to associate commands with special keys. The Key Manager Dialog.

Edit ‣ Preferences
  Give access to the preferences dialog. The Preferences Dialog.

## 4.4. Rectangles

Rectangle commands operate on a rectangular area of the text, that is all the characters between two columns in a certain range of lines.

A rectangle is selected using the standard selection mechanism. You can therefore use either the mouse to highlight the proper region, or `shift` and the cursor keys to extend the selection, or the Emacs selection (with the mark and the current cursor location) if you have activated the `emacs.py` plugin.

Visually, a selected rectangle is exactly the same as the standard selection. In particular, the characters after the last column, on each line, will also be highlighted. The way the selection is interpreted (either as a full text or as a rectangle) depends on the command you then chose to manipulate the selection.

If you chose one of the commands from the Edit ‣ Rectangles menu, the actual rectangle will extend from the top-left corner down to the bottom-right corner. All characters to the right of the right-most column, although they are highlighted, are not part of the rectangle.

Consider for instance the following initial text:

    package A is
       procedure P;

       procedure Q;
    end A;

and assume we have selected from the character “p” in “procedure P”, down to the character “c” in “procedure Q”.

The following commands can then be used (either from the menu, or you can assign key shortcuts to them via the usual Edit ‣ Key shortcuts menu.

- Edit ‣ Rectangles ‣ Cut or Edit ‣ Rectangles ‣ Delete

  These commands will remove the selected text (and have no effect on empty lines within the rectangle). The former will in addition copy the rectangle to the clipboard, so that you can paste it later. In our example, we end up with:

      package A is
         edure P;

         edure Q;
      end A;

- Edit ‣ Rectangles ‣ Copy This command has no visual effect, but copies the contents of the rectangle into the clipboard.

- Edit ‣ Rectangles ‣ Paste Pastes the contents of the clipboard as a rectangle: each line from the clipboard is treated independently, and inserted on successive lines in the current editor. They all start in the same column (the one where the cursor is initially in), and existing text in the editor lines is shifted to the right). If for instance you now place the cursor in the second line, first column, and paste, we end up with:

      package A is
      proc   edure P;

      proc   edure Q;
      end A;

- Edit ‣ Rectangles ‣ Clear Replaces the contents of the selected rectangle with spaces. If we start from our initial exmaple, we end up with the following. Note the difference with Edit ‣ Rectangles ‣ Delete:

      package A is
             edure P;

             edure Q;
      end A;

- Edit ‣ Rectangles ‣ Open Replaces the contents of the selected rectangle with spaces, but shifts the lines to the right to do so. Note the difference with Edit ‣ Rectangles ‣ Clear:

      package A is
             procedure P;

             procedure Q;
      end A;

- Edit ‣ Rectangles ‣ Replace With Text This is similar to Edit ‣ Rectangles ‣ Clear, but the rectangle is replaced with user-defined text. The lines will be shifted left or right if the text you insert is shorter (resp. longer) than the width of the rectangle. If for instance we replace our initial rectangle with the text TMP, we end up with the following. Note that the character “c” has disappeared, since TMP is shorter than our rectangle width (4 characters). This command will impact lines that are empty in the initial rectangle:

      package A is
         TMPedure P;
         TMP
         TMPedure Q;
      end A;

- Edit ‣ Rectangles ‣ Insert Text This inserts a text to the left of the rectangle on each line. The following example inserts TMP. Note the difference with Edit ‣ Rectangles ‣ Replace With Text. This command will also insert the text on lines that are empty in the initial rectangle:

      package A is
         TMPprocedure P;
         TMP
         TMPprocedure Q;
      end A;

- Edit ‣ Rectangles ‣ Sort This sorts the selected lines according to the key which starts and ends on the corresponding rectangle’s columns:

      aaa 15 aa
      bbb 02 bb
      ccc 09 cc

  With a selection starting from the 1 on the first line and ending on the 9 on the last one, sorting will result with the following content:

      bbb 02 bb
      ccc 09 cc
      aaa 15 aa

- Edit ‣ Rectangles ‣ Sort reverse

  As above but in the reverse order.

## 4.5. Recording and replaying macros

It is often convenient to be able to repeat a given key sequence a number of times.

GPS supports this with several different methods:

- Repeat the next action

  If there is a single key press that you wish to repeat a number of times, you should first use the GPS action “Repeat Next” (bound by default to `control-u`, but this can be changed as usual through the Edit ‣ Key Shortcuts menu), then entering the number of times you wish to repeat, and finally pressing the key you want.

  For instance, the following sequence `control-u 79 -` will insert 79 characters ‘-‘ in the current editor. This proves often useful to insert separators.

  If you are using the emacs mode (see Tools ‣ Plug-ins menu), you can also use the sequence `control-u 30 control-k` to delete 30 lines.

- Recording macros

  If you wish to repeat a sequence of more than 1 key, you should record this sequence as a macro. All macro-related menus are found in Tools ‣ Macros, although it is often more convenient to use these through key bindings, which you can of course override.

  You must indicate to GPS that it should start recording the keys you are pressing. This is done through the Tools ‣ Macros ‣ Start Keyboard Macro menu. As its name indicates, this only records keyboard events, not mouse events. Until you select Tools ‣ Macros ‣ Stop Macro, GPS will keep recording the events.

  In Emacs mode, the macro actions are bound to `control-x (`, `control-x )` and `control-x e` key shortcuts. For instance, you can execute the following to create a very simple macro that deletes the current line, wherever your cursor initially is on that line:

  - `control-x (` start recording
  - `control-a` go to beginning of line
  - `control-k` delete line
  - `control-x )` stop recording

## 4.6. Contextual Menus for Editing Files

Whenever you ask for a contextual menu (using e.g. the right button on your mouse) on a source file, you will get access to a number of entries, displayed or not depending on the current context.

Menu entries include the following categories:

Source Navigation
  Contextual Menus for Source Navigation.
Dependencies
  The Dependency Browser.
Entity browsing
  The Entity Browser.
Project view
  The Project view.
Version control
  The Version Control Contextual Menu.
Debugger
  Using the Source Editor when Debugging.
Case exceptions
  Handling of case exceptions.
Refactoring
  Refactoring.

In addition, an entry Properties... is always visible in this contextual menu. When you select it, a dialog pops up that allows you to override the language used for the file, or the character set.

This can be used for instance if you want to open a file that does not belong to the current project, but where you want to benefit from the syntax highlighting.

It is not recommended to override the language for source files that belong to the project. Instead, you should use the Project ‣ Edit Project Properties menu and change the naming scheme if appropriate. This will ensure better consistency between GPS and the compiler in the way they manipulate the file.

## 4.7. Handling of case exceptions

GPS keeps a set of case exceptions that is used by all case insensitive languages. When editing or reformatting a buffer for such a language the case exception dictionary will be checked first. If an exception is found for this word or a substring of the word, it will be used; otherwise the specified casing for keywords or identifiers is used. A substring is defined as a part of the word separated by underscores.

Note that this feature is not activated for entities (keywords or identifiers) for which the casing is set to Unchanged in the preferences Editor ‣ Ada ‣ Reserved word casing or Editor ‣ Ada ‣ Identifier casing.

A contextual menu named Casing has the following entries:

Casing ‣ Lower *entity*
  Set the selected entity in lower case.
Casing ‣ Upper *entity*
  Set the selected entity in upper case.
Casing ‣ Mixed *entity*
  Set the selected entity in mixed case (set the first letter and letters before an underscore in upper case, all other letters are set to lower case).
Casing ‣ Smart Mixed *entity*
  Set the selected entity in smart mixed case. Idem as above except that upper case letters are kept unchanged.
Casing ‣ Add exception for *entity*
  Add the current entity into the case exception dictionary.
Casing ‣ Remove exception for *entity*
  Remove the current entity from the case exception dictionary.

To add or remove a substring exception into/from the dictionary you need to first select the substring on the editor. In this case the last two contextual menu entries will be:

Casing ‣ Add substring exception for *str*
  Add the selected substring into the case substring exception dictionary.
Casing ‣ Remove substring exception for *str*
  Remove the selected substring from the case substring exception dictionary.

## 4.8. Refactoring

GPS includes basic facilities for refactoring your code. Refactoring is the standard term used to describe manipulation of the source code that do not affect the behavior of the application, but help reorganize the source code to make it more readable, more extendable, ...

Refactoring technics are generally things that programmers are used to do by hand, but which are faster and more secure to do automatically through a tool.

One of the basic recommendations when you refactor your code is to recompile and test your application very regularly, to make sure that each of the small modifications you made to it didn’t break the behavior of your application. This is particularly true with GPS, since it relies on the cross-references information that is generated by the compiler. If some of the source files have not been recompiled recently, GPS will print warning messages indicating that the renaming operation might be dangerous and/or only partial.

One of the reference books that was used in the choice of refactoring methods to implement is “Refactoring”, by Martin Fowler (Addison Wesley).

### 4.8.1. Rename Entity

Clicking on an entity in a source file and selecting the Refactoring ‣ Rename contextual menu will open a dialog asking for the new name of the entity. GPS will rename all instances of the entity in your application. This includes the definition of the entity, its body, all calls to it, etc... Of course, no comment is updated, and you should probably check manually that the comment for the entity still applies.

GPS will handle primitive operations by also renaming the operations it overrides or that overrides it. This means that any dispatching call to that operation will also be renamed, and the application should still work as before. If you are renaming a parameter to a subprogram, GPS can also rename parameters with similar names in overriding or overridden subprograms.

The behavior when handling read-only files can be specified: by default, GPS will not do any refactoring in these files, and will display a dialog listing all of them; but you can also choose to make them writable just as if you had clicked on the “Read-Only” button in the status bar of the editor and then have GPS perform the renaming in them as well.

### 4.8.2. Name Parameters

If you are editing Ada code and click on a call to a subprogram, GPS will display a contextual menu Refactoring ‣ Name parameters, which will replace all unnamed parameters by named parameters, as in:

       Call (1, 2)
    =>
       Call (Param1 => 1, Param2 => 2);

### 4.8.3. Extract Subprogram

This refactoring is used to move some code from one place to a separate subprogram. The goal is to simplify the original subprogram, by moving part of its code elsewhere.

Here is an example from the “Refactoring” book. The refactoring will take place in the body of the package `pkg.adb`, but the spec is needed so that you can compile the source code (a preliminary step mandatory before you can refactor the code):

    pragma Ada_05;

    with Ada.Containers.Indefinite_Doubly_Linked_Lists;
    with Ada.Strings.Unbounded;

    package Pkg is

       type Order is tagged null record;
       function Get_Amount (Self : Order) return Integer;

       package Order_Listsis new
          Ada.Containers.Indefinite_Doubly_Linked_Lists (Order);

       type Invoice is tagged record
          Orders : Order_Lists.List;
          Name   : Ada.Strings.Unbounded.Unbounded_String;
       end record;

       procedure Print_Owing (Self : Invoice);

    end Pkg;

The initial implementation for this code is given by the following code:

    pragma Ada_05;
    with Ada.Strings.Unbounded;  use Ada.Strings.Unbounded;
    with Ada.Text_IO;            use Ada.Text_IO;

    package body Pkg is
       use Order_Lists;

       ----------------
       -- Get_Amount --
       ----------------

       function Get_Amount (Self : Order) return Integer is
       begin
          return 0;
       end Get_Amount;

       -----------------
       -- Print_Owing --
       -----------------

       procedure Print_Owing (Self : Invoice) is
          E : Order_Lists.Cursor := First (Self.Orders);
          Outstanding : Natural := 0;
          Each : Order;
       begin
          --  <<< line 30
          --  Print Banner

          Put_Line ("");
          Put_Line (" Customer Owes         ");
          Put_Line ("");  --  << line 35

          --  Calculate Outstanding

          while Has_Element (E) loop
             Each := Element (E);
             Outstanding := Outstanding + Each.Get_Amount;
             Next (E);
          end loop;

          --  Print Details

          Put_Line ("Name: " & To_String (Self.Name));
          Put_Line ("Outstanding:" & Outstanding'Img);
       end Print_Owing;
    end Pkg;

The procedure Print_Owing is too long and does several independent actions. We will perform a series of three successive refactoring steps to extract the code and move it elsewhere.

The first is the code that prints the banner. Moving it is easy, since this code does not depend on any context. We could just do a copy-paste, but then we would have to create the new subprogram. Instead, we select lines 30 to 35, and then select the contextual menu Refactoring ‣ Extract Subprogram. GPS will then automatically change Print_Owing and create a new procedure Print_Banner (the name is specified by the user, GPS does not try to guess it). Also, since the chunk of code that is extracted starts with a comment, GPS automatically uses that comment as the documentation for the new subprogram. Here is part of the resulting file:

    package body Pkg is

       procedure Print_Banner;
       --  Print Banner

       ------------------
       -- Print_Banner --
       ------------------

       procedure Print_Banner is
       begin
          Put_Line ("");
          Put_Line (" Customer Owes         ");
          Put_Line ("");
       end Print_Banner;

       ... (code not shown)

       procedure Print_Owing (Self : Invoice) is
          E : Order_Lists.Cursor := First (Self.Orders);
          Outstanding : Natural := 0;
          Each : Order;
       begin
          Print_Banner;

          --  Calculate Outstanding

          while Has_Element (E) loop
             Each := Element (E);
             Outstanding := Outstanding + Each.Get_Amount;
             Next (E);
          end loop;

          --  Print Details   <<< line  54

          Put_Line ("Name: " & To_String (Self.Name));
          Put_Line ("Outstanding:" & Outstanding'Img);  --  line 57
       end Print_Owing;
    end Pkg;

A more interesting example is when we want to extract the code to print the details of the invoice. This code depends on one local variable and the parameter to Print_Owing. When we select lines 54 to 57 and extract it into a new Print_Details subprogram, we get the following result. GPS automatically decides which variables to extract, and whether they should become parameters of the new subprogram, or local variables. In the former case, it will also automatically decide whether to create “in”, “out” or “in out” parameters. If there is a single “out” parameter, it will automatically create a function rather than a procedure.

GPS will use, for the parameters, the same name that was used for the local variable. Very often, it will make sense to recompile the new version of the source, and then apply the Refactoring ‣ Rename Entity refactoring to have more specific names for the parameters, or the Refactoring ‣ Name Parameters refactoring so that the call to the new method uses named parameters to further clarify the code:

    ... code not shown

    procedure Print_Details
      (Self : Invoice'Class;
       Outstanding : Natural);
    --  Print Details

    -------------------
    -- Print_Details --
    -------------------

    procedure Print_Details
      (Self : Invoice'Class;
       Outstanding : Natural)
    is
    begin
       Put_Line ("Name: " & To_String (Self.Name));
       Put_Line ("Outstanding:" & Outstanding'Img);
    end Print_Details;

    procedure Print_Owing (Self : Invoice) is
       E : Order_Lists.Cursor := First (Self.Orders);
       Outstanding : Natural := 0;
       Each : Order;
    begin
       Print_Banner;

       --  Calculate Outstanding

       while Has_Element (E) loop
          Each := Element (E);
          Outstanding := Outstanding + Each.Get_Amount;
          Next (E);
       end loop;

       Print_Details (Self, Outstanding);
    end Print_Owing;

Finally, we want to extract the code that computes the outstanding amount. When this code is moved, the variables E and Each become useless in Print_Owing and are moved into the new subprogram (which we will call Get_Outstanding. Here is the result of that last refactoring (the initial selection should include the blank lines before and after the code, to keep the resulting Print_Owing simpler). GPS will automatically ignore those blank lines:

    ... code not shown

    procedure Get_Outstanding (Outstanding : in out Natural);
    --  Calculate Outstanding

    ---------------------
    -- Get_Outstanding --
    ---------------------

    procedure Get_Outstanding (Outstanding : in out Natural) is
       E : Order_Lists.Cursor := First (Self.Orders);
       Each : Order;
    begin
       while Has_Element (E) loop
          Each := Element (E);
          Outstanding := Outstanding + Each.Get_Amount;
          Next (E);
       end loop;
    end Get_Outstanding;

    procedure Print_Owing (Self : Invoice) is
       Outstanding : Natural := 0;
    begin
       Print_Banner;
       Get_Outstanding (Outstanding);
       Print_Details (Self, Outstanding);
    end Print_Owing;

Note that the final version of Print_Owing is not perfect. For instance, passing the initial value 0 to Get_Outstanding is useless, and in fact that should probably be a function with no parameter. But GPS already saves a lot of time and manipulation.

Finally, a word of caution: this refactoring does not check that you are giving a valid input. For instance, if the text you select includes a declare block, you should always include the full block, not just a part of it (or select text between begin and end). Likewise, GPS does not expect you to select any part of the variable declarations, just the code.

## 4.9. Using an External Editor

GPS is integrated with a number of external editors, in particular Emacs and vi. The choice of the default external editor is done in the preferences, via Editor ‣ External editor.

The following values are recognized:

gnuclient

  This is the recommended client. It is based on Emacs, but needs an extra package to be installed. This is the only client that provides a full integration in GPS, since any extended lisp command can be sent to the Emacs server.

  By default, gnuclient will open a new Emacs frame for every file that is opened. You might want to add the following code to your `.emacs` file (create one if needed) so that the same Emacs frame is reused every time:

      (setq gnuserv-frame (car (frame-list)))

  See http://www.hpl.hp.com/personal/ange/gnuserv/home.html for more information.

emacsclient
  This is a program that is always available if you have installed Emacs. As opposed to starting a new Emacs every time, it will reuse an existing Emacs session. It is then extremely fast to open a file.

emacs
  This client will start a new Emacs session every time a file needs to be opened. You should use emacsclient instead, since it is much faster, and makes it easier to copy and paste between multiple files. Basically, the only reason to use this external editor is if your system doesn’t support emacsclient.

vim

  Vim is a vi-like editor that provides a number of enhancements, for instance syntax highlighting for all the languages supported by GPS. Selecting this external editor will start an xterm (or command window, depending on your system) with a running vim process editing the file.

  Note that one limitation of this editor is that if GPS needs to open the same file a second time, it will open a new editor, instead of reusing the existing one.

  To enable this capability, the xterm executable must be found in the PATH, and thus is not supported on Windows systems. Under Windows systems, you can use the custom editor instead.

vi
  This editor works exactly like vim, but uses the standard vi command instead of vim.

custom
  You can specify any external editor by choosing this item. The full command line used to call the editor can be specified in the preference Editor ‣ Custom editor command.
none
  No external editor is used, and the contextual menus simply won’t appear.

In the cases that require an Emacs server, the project file currently used in GPS will be set appropriately the first time Emacs is spawned. This means that if you load a new project in GPS, or modify the paths of the current project, you should kill any running Emacs, so that a new one is spawned by GPS with the appropriate project.

Alternatively, you can reload explicitly the project from Emacs itself by using the menu Project ‣ Load in emacs (if the ada-mode was correctly installed).

The preference Editor ‣ Always use external editor lets you chose to always use an external editor every time you double-click on a file, instead of opening GPS’ own editor.

## 4.10. Using the Clipboard

This section concerns X-Window users who are used to cutting and pasting with the middle mouse button. In the GPS text editor, as in many recent X applications, the GPS clipboard is set by explicit cut/copy/paste actions, either through menu items or keyboard shortcuts, and the primary clipboard (i.e. the ‘middle button’ clipboard) is set by the current selection.

Therefore, copy/paste between GPS and other X applications using the primary clipboard will still work, provided that there is some text currently selected. The GPS clipboard, when set, will override the primary clipboard.

By default, GPS overrides the X mechanism. To prevent this, add the following line: OVERRIDE_MIDDLE_CLICK_PASTE = no to your `traces.cfg` file (typically in `~/.gps/`). Note, however, that the X mechanism pastes all attributes of text, including coloring and editability, which can be confusing.

See http://standards.freedesktop.org/clipboards-spec/clipboards-latest.txt for more information.

## 4.11. Saving Files

After you have finished modifying your files, you need to save them. The basic method to do that is to select the menu File ‣ Save, which saves the currently selected file.

You can also use the menu File ‣ Save As... if you want to save the file with another name, or in another directory.

If you have multiple files to save, another possibility is to use the menu File ‣ Save More ‣ All. This will open a dialog listing all the currently modified editors that need saving. You can then select individually which one should be saved, and click on Save to do the actual saving.

When calling external commands, such as compiling a file, if the Editor ‣ Autosave delay preference is set to 0, this same dialog is also used, to make sure that e.g. the compiler will take into account your local changes. If the preference is enabled, the saving is performed automatically.

You can conveniently select or unselect all the files at once by clicking on the title of the first column (labeled Select). This will toggle the selection status of the first line, and have the same status for all other editors.

If you press Cancel instead of Save, no saving will take place, and the action that displayed this dialog is also canceled. Such actions can be for instance starting a compilation command, a VCS operation, or quitting GPS with unsaved files.

### Navigation

- index
- modules |
- next |
- previous |
- GPS 6.0.1 documentation »