runtime/doc/ada.txt

   1 *ada.txt*       For Vim version 7.1.  Last change: 2007 May 08
   2
   3
   4                     ADA FILE TYPE PLUG-INS REFERENCE MANUAL~
   5
   6 ADA                                                                   *ada.vim*
   7
   8 1.  Syntax Highlighting                     |ft-ada-syntax|
   9 2.  Plug-in                                 |ft-ada-plugin|
  10 3.  Omni Completion                         |ft-ada-omni|
  11     3.1 Omni Completion with "gnat xref"        |gnat-xref|
  12     3.2 Omni Completion with "ctags"            |ada-ctags|
  13 4.  Compiler Support                        |ada-compiler|
  14     4.1 GNAT                                    |compiler-gnat|
  15     4.1 Dec Ada                                 |compiler-decada|
  16 5.  References                              |ada-reference|
  17     5.1 Options                                 |ft-ada-options|
  18     5.2 Functions                               |ft-ada-functions|
  19     5.3 Commands                                |ft-ada-commands|
  20     5.4 Variables                               |ft-ada-variables|
  21     5.5 Constants                               |ft-ada-constants|
  22 8.  Extra Plug-ins                          |ada-extra-plugins|
  23
  24 ==============================================================================
  25 1. Syntax Highlighting ~
  26                                                                *ft-ada-syntax*
  27
  28 This mode is designed for the 2005 edition of Ada ("Ada 2005"), which includes
  29 support for objected-programming, protected types, and so on.  It handles code
  30 written for the original Ada language ("Ada83", "Ada87", "Ada95") as well,
  31 though code which uses Ada 2005-only keywords will be wrongly colored (such
  32 code should be fixed anyway).  For more information about Ada, see
  33 http://www.adapower.com.
  34
  35 The Ada mode handles a number of situations cleanly.
  36
  37 For example, it knows that the "-" in "-5" is a number, but the same character
  38 in "A-5" is an operator.  Normally, a "with" or "use" clause referencing
  39 another compilation unit is coloured the same way as C's "#include" is coloured.
  40 If you have "Conditional" or "Repeat" groups coloured differently, then "end
  41 if" and "end loop" will be coloured as part of those respective groups.
  42
  43 You can set these to different colours using vim's "highlight" command (e.g.,
  44 to change how loops are displayed, enter the command ":hi Repeat" followed by
  45 the colour specification; on simple terminals the colour specification
  46 ctermfg=White often shows well).
  47
  48 There are several options you can select in this Ada mode. See|ft-ada-options|
  49 for a complete list.
  50
  51 To enable them, assign a value to the option.  For example, to turn one on:
  52  >
  53     > let g:ada_standard_types = 1
  54 >
  55 To disable them use ":unlet".  Example:
  56 >
  57     > unlet g:ada_standard_types
  58
  59 You can just use ":" and type these into the command line to set these
  60 temporarily before loading an Ada file.  You can make these option settings
  61 permanent by adding the "let" command(s), without a colon, to your "~/.vimrc"
  62 file.
  63
  64 Even on a slow (90Mhz) PC this mode works quickly, but if you find the
  65 performance unacceptable, turn on |g:ada_withuse_ordinary|.
  66
  67 Syntax folding instructions (|fold-syntax|) are added when |g:ada_folding| is
  68 set.
  69
  70 ==============================================================================
  71 2. File type Plug-in ~
  72                                                *ft-ada-indent* *ft-ada-plugin*
  73
  74 The Ada plug-in provides support for:
  75
  76  - auto indenting       (|indent.txt|)
  77  - insert completion    (|i_CTRL-N|)
  78  - user completion      (|i_CTRL-X_CTRL-U|)
  79  - tag searches         (|tagsrch.txt|)
  80  - Quick Fix            (|quickfix.txt|)
  81  - backspace handling   (|'backspace'|)
  82  - comment handling     (|'comments'|, |'commentstring'|)
  83
  84 The plug-in only activates the features of the Ada mode whenever an Ada
  85 files is opened and add adds Ada related entries to the main and pop-up menu.
  86
  87 ==============================================================================
  88 3. Omni Completion ~
  89                                                                  *ft-ada-omni*
  90
  91 The Ada omni-completions (|i_CTRL-X_CTRL-O|) uses tags database created either
  92 by "gnat xref -v" or the "exuberant Ctags (http://ctags.sourceforge.net).  The
  93 complete function will automatically detect which tool was used to create the
  94 tags file.
  95
  96 ------------------------------------------------------------------------------
  97 3.1 Omni Completion with "gnat xref" ~
  98                                                                    *gnat-xref*
  99
 100 GNAT XREF uses the compiler internal informations (ali-files) to produce the
 101 tags file. This has the advantage to be 100% correct and the option of deep
 102 nested analysis. However the code must compile, the generator is quite
 103 slow and the created tags file contains only the basic Ctags informations for
 104 each entry - not enough for some of the more advanced Vim code browser
 105 plug-ins.
 106
 107 NOTE: "gnat xref -v" is very tricky to use as it has almost no diagnostic
 108        output - If nothing is printed then usually the parameters are wrong.
 109        Here some important tips:
 110
 111 1)  You need to compile your code first and use the "-aO" option to point to
 112     your .ali files.
 113 2)  "gnat xref -v ../Include/adacl.ads" won't work - use  the "gnat xref -v
 114     -aI../Include adacl.ads" instead.
 115 3)  "gnat xref -v -aI../Include *.ad?" won't work - use "cd ../Include" and
 116     then "gnat xref -v *.ad?"
 117 4)  Project manager support is completely broken - don't even try "gnat xref
 118     -Padacl.gpr".
 119 5)  VIM is faster when the tags file is sorted - use "sort --unique
 120     --ignore-case --output=tags tags" .
 121 6)  Remember to insert "!_TAG_FILE_SORTED 2 %sort ui" as first line to mark
 122     the file assorted.
 123
 124 ------------------------------------------------------------------------------
 125 3.2 Omni Completion with "ctags"~
 126                                                                    *ada-ctags*
 127
 128 Exuberant Ctags uses its own multi-language code parser. The parser is quite
 129 fast, produces a lot of extra informations (hence the name "Exuberant Ctags")
 130 and can run on files which currently do not compile.
 131
 132 There are also lots of other Vim-tools which use exuberant Ctags.
 133
 134 You will need to install a version of the Exuberant Ctags which has Ada
 135 support patched in. Such a version is available from the GNU Ada Project
 136 (http://gnuada.sourceforge.net).
 137
 138 The Ada parser for Exuberant Ctags is fairly new - don't expect complete
 139 support yet.
 140
 141 ==============================================================================
 142 4.  Compiler Support ~
 143                                                                 *ada-compiler*
 144
 145 The Ada mode supports more then one Ada compiler and will automatically load the
 146 compiler set in|g:ada_default_compiler|whenever an Ada source is opened. The
 147 provided compiler plug-ins are split into the actual compiler plug-in and a
 148 collection of support functions and variables. This allows the easy
 149 development of specialized compiler plug-ins fine tuned to your development
 150 environment.
 151
 152 ------------------------------------------------------------------------------
 153 4.1 GNAT ~
 154                                                                *compiler-gnat*
 155
 156 GNAT is the only free (beer and speech) Ada compiler available. There are
 157 several version available which differentiate in the licence terms used.
 158
 159 The GNAT compiler plug-in will perform a compile on pressing <F7> and then
 160 immediately shows the result. You can set the project file to be used by
 161 setting:
 162  >
 163  > call g:gnat.Set_Project_File ('my_project.gpr')
 164
 165 Setting a project file will also create a Vim session (|views-sessions|) so -
 166 like with the GPS - opened files, window positions etc. will remembered
 167 separately for all projects.
 168
 169                                                                 *gnat_members*
 170 GNAT OBJECT ~
 171
 172                                                                *g:gnat.Make()*
 173 g:gnat.Make()
 174                 Calls|g:gnat.Make_Command|and displays the result inside a
 175                |quickfix| window.
 176
 177                                                              *g:gnat.Pretty()*
 178 g:gnat.Pretty()
 179                 Calls|g:gnat.Pretty_Command|
 180
 181                                                                *g:gnat.Find()*
 182 g:gnat.Find()
 183                 Calls|g:gnat.Find_Command|
 184
 185                                                                *g:gnat.Tags()*
 186 g:gnat.Tags()
 187                 Calls|g:gnat.Tags_Command|
 188
 189                                                    *g:gnat.Set_Project_File()*
 190 g:gnat.Set_Project_File([{file}])
 191                 Set gnat project file and load associated session.  An open
 192                 project will be closed and the session written.  If called
 193                 without file name the file selector opens for selection of a
 194                 project file. If called with an empty string then the project
 195                 and associated session are closed.
 196
 197                                                          *g:gnat.Project_File*
 198 g:gnat.Project_File     string
 199                 Current project file.
 200
 201                                                          *g:gnat.Make_Command*
 202 g:gnat.Make_Command     string
 203                 External command used for|g:gnat.Make()| (|'makeprg'|).
 204
 205                                                        *g:gnat.Pretty_Program*
 206 g:gnat.Pretty_Program   string
 207                 External command used for|g:gnat.Pretty()|
 208
 209                                                          *g:gnat.Find_Program*
 210 g:gnat.Find_Program     string
 211                 External command used for|g:gnat.Find()|
 212
 213                                                          *g:gnat.Tags_Command*
 214 g:gnat.Tags_Command     string
 215                 External command used for|g:gnat.Tags()|
 216
 217                                                          *g:gnat.Error_Format*
 218 g:gnat.Error_Format     string
 219                 Error format (|'errorformat'|)
 220
 221 ------------------------------------------------------------------------------
 222 4.2 Dec Ada ~
 223                                             *compiler-hpada* *compiler-decada*
 224                                         *compiler-vaxada* *compiler-compaqada*
 225
 226 Dec Ada (also known by - in chronological order - VAX Ada, Dec Ada, Compaq Ada
 227 and HP Ada) is a fairly dated Ada 83 compiler. Support is basic: <F7> will
 228 compile the current unit.
 229
 230 The Dec Ada compiler expects the package name and not the file name to be
 231 passed a parameter. The compiler plug-in supports the usual file name
 232 convention to convert the file into a unit name. For separates both '-' and
 233 '__' are allowed.
 234
 235                                                               *decada_members*
 236 DEC ADA OBJECT ~
 237
 238                                                              *g:decada.Make()*
 239 g:decada.Make()         function
 240                 Calls|g:decada.Make_Command|and displays the result inside a
 241                |quickfix| window.
 242
 243                                                         *g:decada.Unit_Name()*
 244 g:decada.Unit_Name()    function
 245                 Get the Unit name for the current file.
 246
 247                                                        *g:decada.Make_Command*
 248 g:decada.Make_Command   string
 249                 External command used for|g:decadat.Make()| (|'makeprg'|).
 250
 251                                                        *g:decada.Error_Format*
 252 g:decada.Error_Format|  string
 253                 Error format (|'errorformat'|).
 254
 255 ==============================================================================
 256 5. References ~
 257                                                                *ada-reference*
 258
 259 ------------------------------------------------------------------------------
 260 5.1 Options ~
 261                                                               *ft-ada-options*
 262
 263                                                         *g:ada_standard_types*
 264 g:ada_standard_types    bool (true when exists)
 265                 Highlight types in package Standard (e.g., "Float")
 266
 267                                                           *g:ada_space_errors*
 268                                                   *g:ada_no_trail_space_error*
 269                                                     *g:ada_no_tab_space_error*
 270                                                          *g:ada_all_tab_usage*
 271 g:ada_space_errors       bool (true when exists)
 272                 Highlight extraneous errors in spaces ...
 273                 g:ada_no_trail_space_error
 274                     - but ignore trailing spaces at the end of a line
 275                 g:ada_no_tab_space_error
 276                     - but ignore tabs after spaces
 277                 g:ada_all_tab_usage
 278                     - highlight all tab use
 279
 280                                                            *g:ada_line_errors*
 281 g:ada_line_errors         bool (true when exists)
 282                 Highlight lines which are to long. Note: This highlighting
 283                 option is quite CPU intensive.
 284
 285                                                          *g:ada_rainbow_color*
 286 g:ada_rainbow_color       bool (true when exists)
 287                 Use rainbow colours for '(' and ')'. You need the
 288                 rainbow_parenthesis for this to work
 289
 290                                                                *g:ada_folding*
 291 g:ada_folding             set ('sigpft')
 292                 Use folding for Ada sources.
 293                     's':    activate syntax folding on load
 294                         'p':    fold packages
 295                         'f':    fold functions and procedures
 296                         't':    fold types
 297                         'c':    fold conditionals
 298                     'g':    activate gnat pretty print folding on load
 299                         'i':    lone 'is' folded with line above
 300                         'b':    lone 'begin' folded with line above
 301                         'p':    lone 'private' folded with line above
 302                         'x':    lone 'exception' folded with line above
 303                     'i':    activate indent folding on load
 304
 305                 Note: Syntax folding is in an early (unusable) stage and
 306                       indent or gnat pretty folding is suggested.
 307
 308                 For gnat pretty folding to work the following settings are
 309                 suggested: -cl3 -M79 -c2 -c3 -c4 -A1 -A2 -A3 -A4 -A5
 310
 311                 For indent folding to work the following settings are
 312                 suggested: shiftwidth=3 softtabstop=3
 313
 314                                                                 *g:ada_abbrev*
 315 g:ada_abbrev              bool (true when exists)
 316                 Add some abbreviations. This feature more or less superseded
 317                 by the various completion methods.
 318
 319                                                       *g:ada_withuse_ordinary*
 320 g:ada_withuse_ordinary    bool (true when exists)
 321                 Show "with" and "use" as ordinary keywords (when used to
 322                 reference other compilation units they're normally highlighted
 323                 specially).
 324
 325                                                          *g:ada_begin_preproc*
 326 g:ada_begin_preproc       bool (true when exists)
 327                 Show all begin-like keywords using the colouring of C
 328                 preprocessor commands.
 329
 330                                                     *g:ada_omni_with_keywords*
 331 g:ada_omni_with_keywords
 332                 Add Keywords, Pragmas, Attributes to omni-completions
 333                 (|compl-omni|). Note: You can always complete then with user
 334                 completion (|i_CTRL-X_CTRL-U|).
 335
 336                                                       *g:ada_extended_tagging*
 337 g:ada_extended_tagging    enum ('jump', 'list')
 338                 use extended tagging, two options are available
 339                     'jump': use tjump to jump.
 340                     'list': add tags quick fix list.
 341                 Normal tagging does not support function or operator
 342                 overloading as these features are not available in C and
 343                 tagging was originally developed for C.
 344
 345                                                    *g:ada_extended_completion*
 346 g:ada_extended_completion
 347                 Uses extended completion for <C-N> and <C-R> completions
 348                 (|i_CTRL-N|). In this mode the '.' is used as part of the
 349                 identifier so that 'Object.Method' or 'Package.Procedure' are
 350                 completed together.
 351
 352                                                        *g:ada_gnat_extensions*
 353 g:ada_gnat_extensions     bool (true when exists)
 354                  Support GNAT extensions.
 355
 356                                                *g:ada_with_gnat_project_files*
 357 g:ada_with_gnat_project_files    bool (true when exists)
 358                  Add gnat project file keywords and Attributes.
 359
 360                                                       *g:ada_default_compiler*
 361 g:ada_default_compiler    string
 362                 set default compiler. Currently supported is 'gnat' and
 363                 'decada'.
 364
 365 An "exists" type is a boolean is considered true when the variable is defined
 366 and false when the variable is undefined. The value which the variable is
 367 set makes no difference.
 368
 369 ------------------------------------------------------------------------------
 370 5.3 Commands ~
 371                                                              *ft-ada-commands*
 372
 373 :AdaRainbow                                                      *:AdaRainbow*
 374                 Toggles rainbow colour (|g:ada_rainbow_color|) mode for
 375                 '(' and ')'
 376
 377 :AdaLines                                                          *:AdaLines*
 378                 Toggles line error (|g:ada_line_errors|) display
 379
 380 :AdaSpaces                                                        *:AdaSpaces*
 381                 Toggles space error (|g:ada_space_errors|) display.
 382
 383 :AdaTagDir                                                        *:AdaTagDir*
 384                 Creates tags file for the directory of the current file.
 385
 386 :AdaTagFile                                                      *:AdaTagFile*
 387                 Creates tags file for the current file.
 388
 389 :AdaTypes                                                          *:AdaTypes*
 390                 Toggles standard types (|g:ada_standard_types|) colour.
 391
 392 :GnatFind                                                          *:GnatFind*
 393                 Calls |g:gnat.Find()|
 394
 395 :GnatPretty                                                      *:GnatPretty*
 396                 Calls |g:gnat.Pretty()|
 397
 398 :GnatTags                                                          *:GnatTags*
 399                 Calls |g:gnat.Tags()|
 400
 401 ------------------------------------------------------------------------------
 402 5.3 Variables ~
 403                                                             *ft-ada-variables*
 404
 405                                                                       *g:gnat*
 406 g:gnat                      object
 407                 Control object which manages GNAT compiles.  The object
 408                 is created when the first Ada source code is loaded provided
 409                 that |g:ada_default_compiler|is set to 'gnat'. See|gnat_members|
 410                 for details.
 411
 412                                                                     *g:decada*
 413 g:decada                      object
 414                 Control object which manages Dec Ada compiles.  The object
 415                 is created when the first Ada source code is loaded provided
 416                 that |g:ada_default_compiler|is set to 'decada'. See
 417                |decada_members|for details.
 418
 419 ------------------------------------------------------------------------------
 420 5.4 Constants ~
 421                                                             *ft-ada-constants*
 422
 423 All constants are locked. See |:lockvar| for details.
 424
 425                                                              *g:ada#WordRegex*
 426 g:ada#WordRegex         string
 427                 Regular expression to search for Ada words
 428
 429                                                           *g:ada#DotWordRegex*
 430 g:ada#DotWordRegex      string
 431                 Regular expression to search for Ada words separated by dots.
 432
 433                                                                *g:ada#Comment*
 434 g:ada#Comment           string
 435                 Regular expression to search for Ada comments
 436
 437                                                               *g:ada#Keywords*
 438 g:ada#Keywords          list of dictionaries
 439                 List of keywords, attributes etc. pp. in the format used by
 440                 omni completion. See |complete-items| for details.
 441
 442                                                            *g:ada#Ctags_Kinds*
 443 g:ada#Ctags_Kinds       dictionary of lists
 444                 Dictionary of the various kinds of items which the Ada support
 445                 for Ctags generates.
 446
 447 ------------------------------------------------------------------------------
 448 5.2 Functions ~
 449                                                             *ft-ada-functions*
 450
 451 ada#Word([{line}, {col}])                                         *ada#Word()*
 452                 Return full name of Ada entity under the cursor (or at given
 453                 line/column), stripping white space/newlines as necessary.
 454
 455 ada#List_Tag([{line}, {col}])                                 *ada#Listtags()*
 456                 List all occurrences of the Ada entity under the cursor (or at
 457                 given line/column) inside the quick-fix window
 458
 459 ada#Jump_Tag ({ident}, {mode})                                *ada#Jump_Tag()*
 460                 List all occurrences of the Ada entity under the cursor (or at
 461                 given line/column) in the tag jump list. Mode can either be
 462                 'tjump' or 'stjump'.
 463
 464 ada#Create_Tags ({option})                                 *ada#Create_Tags()*
 465                 Creates tag file using Ctags. The option can either be 'file'
 466                 for the current file, 'dir' for the directory of the current
 467                 file or a file name.
 468
 469 gnat#Insert_Tags_Header()                          *gnat#Insert_Tags_Header()*
 470                 Adds the tag file header (!_TAG_) informations to the current
 471                 file which are missing from the GNAT XREF output.
 472
 473 ada#Switch_Syntax_Option ({option})               *ada#Switch_Syntax_Option()*
 474                 Toggles highlighting options on or off. Used for the Ada menu.
 475
 476                                                                   *gnat#New()*
 477 gnat#New ()
 478                 Create a new gnat object. See |g:gnat| for details.
 479
 480
 481 ==============================================================================
 482 8. Extra Plugins ~
 483                                                            *ada-extra-plugins*
 484
 485 You can optionally install the following extra plug-in. They work well with Ada
 486 and enhance the ability of the Ada mode.:
 487
 488 backup.vim
 489         http://www.vim.org/scripts/script.php?script_id=1537
 490         Keeps as many backups as you like so you don't have to.
 491
 492 rainbow_parenthsis.vim
 493         http://www.vim.org/scripts/script.php?script_id=1561
 494         Very helpful since Ada uses only '(' and ')'.
 495
 496 nerd_comments.vim
 497         http://www.vim.org/scripts/script.php?script_id=1218
 498         Excellent commenting and uncommenting support for almost any
 499         programming language.
 500
 501 matchit.vim
 502         http://www.vim.org/scripts/script.php?script_id=39
 503         '%' jumping for any language. The normal '%' jump only works for '{}'
 504         style languages. The Ada mode will set the needed search patters.
 505
 506 taglist.vim
 507         http://www.vim.org/scripts/script.php?script_id=273
 508         Source code explorer sidebar. There is a patch for Ada available.
 509
 510 The GNU Ada Project distribution (http://gnuada.sourceforge.net) of Vim
 511 contains all of the above.
 512
 513 ==============================================================================
 514 vim: textwidth=78 nowrap tabstop=8 shiftwidth=4 softtabstop=4 noexpandtab
 515 vim: filetype=help encoding=latin1