diff options
Diffstat (limited to 'runtime/doc/ft_ada.txt')
| -rw-r--r-- | runtime/doc/ft_ada.txt | 515 |
1 files changed, 515 insertions, 0 deletions
diff --git a/runtime/doc/ft_ada.txt b/runtime/doc/ft_ada.txt new file mode 100644 index 0000000..fe00256 --- /dev/null +++ b/runtime/doc/ft_ada.txt @@ -0,0 +1,515 @@ +*ft_ada.txt* For Vim version 9.0. Last change: 2022 Mar 13 + + + ADA FILE TYPE PLUG-INS REFERENCE MANUAL~ + +ADA *ada.vim* + +1. Syntax Highlighting |ft-ada-syntax| +2. File type Plug-in |ft-ada-plugin| +3. Omni Completion |ft-ada-omni| + 3.1 Omni Completion with "gnat xref" |gnat-xref| + 3.2 Omni Completion with "ctags" |ada-ctags| +4. Compiler Support |ada-compiler| + 4.1 GNAT |compiler-gnat| + 4.2 Dec Ada |compiler-decada| +5. References |ada-reference| + 5.1 Options |ft-ada-options| + 5.2 Commands |ft-ada-commands| + 5.3 Variables |ft-ada-variables| + 5.4 Constants |ft-ada-constants| + 5.5 Functions |ft-ada-functions| +6. Extra Plug-ins |ada-extra-plugins| + +============================================================================== +1. Syntax Highlighting ~ + *ft-ada-syntax* + +This mode is designed for the 2005 edition of Ada ("Ada 2005"), which includes +support for objected-programming, protected types, and so on. It handles code +written for the original Ada language ("Ada83", "Ada87", "Ada95") as well, +though code which uses Ada 2005-only keywords will be wrongly colored (such +code should be fixed anyway). For more information about Ada, see +http://www.adapower.com. + +The Ada mode handles a number of situations cleanly. + +For example, it knows that the "-" in "-5" is a number, but the same character +in "A-5" is an operator. Normally, a "with" or "use" clause referencing +another compilation unit is coloured the same way as C's "#include" is coloured. +If you have "Conditional" or "Repeat" groups coloured differently, then "end +if" and "end loop" will be coloured as part of those respective groups. + +You can set these to different colours using vim's "highlight" command (e.g., +to change how loops are displayed, enter the command ":hi Repeat" followed by +the colour specification; on simple terminals the colour specification +ctermfg=White often shows well). + +There are several options you can select in this Ada mode. See |ft-ada-options| +for a complete list. + +To enable them, assign a value to the option. For example, to turn one on: + > + > let g:ada_standard_types = 1 +> +To disable them use ":unlet". Example: +> + > unlet g:ada_standard_types + +You can just use ":" and type these into the command line to set these +temporarily before loading an Ada file. You can make these option settings +permanent by adding the "let" command(s), without a colon, to your "~/.vimrc" +file. + +Even on a slow (90Mhz) PC this mode works quickly, but if you find the +performance unacceptable, turn on |g:ada_withuse_ordinary|. + +Syntax folding instructions (|fold-syntax|) are added when |g:ada_folding| is +set. + +============================================================================== +2. File type Plug-in ~ + *ft-ada-indent* *ft-ada-plugin* + +The Ada plug-in provides support for: + + - auto indenting (|indent.txt|) + - insert completion (|i_CTRL-N|) + - user completion (|i_CTRL-X_CTRL-U|) + - tag searches (|tagsrch.txt|) + - Quick Fix (|quickfix.txt|) + - backspace handling (|'backspace'|) + - comment handling (|'comments'|, |'commentstring'|) + +The plug-in only activates the features of the Ada mode whenever an Ada +file is opened and adds Ada related entries to the main and pop-up menu. + +============================================================================== +3. Omni Completion ~ + *ft-ada-omni* + +The Ada omni-completions (|i_CTRL-X_CTRL-O|) uses tags database created either +by "gnat xref -v" or the "Universal Ctags" (https://ctags.io). The complete +function will automatically detect which tool was used to create the tags +file. + +------------------------------------------------------------------------------ +3.1 Omni Completion with "gnat xref" ~ + *gnat-xref* + +GNAT XREF uses the compiler internal information (ali-files) to produce the +tags file. This has the advantage to be 100% correct and the option of deep +nested analysis. However the code must compile, the generator is quite +slow and the created tags file contains only the basic Ctags information for +each entry - not enough for some of the more advanced Vim code browser +plug-ins. + +NOTE: "gnat xref -v" is very tricky to use as it has almost no diagnostic + output - If nothing is printed then usually the parameters are wrong. + Here some important tips: + +1) You need to compile your code first and use the "-aO" option to point to + your .ali files. +2) "gnat xref -v ../Include/adacl.ads" won't work - use the "gnat xref -v + -aI../Include adacl.ads" instead. +3) "gnat xref -v -aI../Include *.ad?" won't work - use "cd ../Include" and + then "gnat xref -v *.ad?" +4) Project manager support is completely broken - don't even try "gnat xref + -Padacl.gpr". +5) Vim is faster when the tags file is sorted - use "sort --unique + --ignore-case --output=tags tags" . +6) Remember to insert "!_TAG_FILE_SORTED 2 %sort ui" as first line to mark + the file assorted. + +------------------------------------------------------------------------------ +3.2 Omni Completion with "ctags"~ + *ada-ctags* + +Universal/Exuberant Ctags use their own multi-language code parser. The +parser is quite fast, produces a lot of extra information and can run on files +which currently do not compile. + +There are also lots of other Vim-tools which use Universal/Exuberant Ctags. +Universal Ctags is preferred, Exuberant Ctags is no longer being developed. + +You will need to install Universal Ctags which is available from +https://ctags.io + +The Ada parser for Universal/Exuberant Ctags is fairly new - don't expect +complete support yet. + +============================================================================== +4. Compiler Support ~ + *ada-compiler* + +The Ada mode supports more than one Ada compiler and will automatically load the +compiler set in |g:ada_default_compiler| whenever an Ada source is opened. The +provided compiler plug-ins are split into the actual compiler plug-in and a +collection of support functions and variables. This allows the easy +development of specialized compiler plug-ins fine tuned to your development +environment. + +------------------------------------------------------------------------------ +4.1 GNAT ~ + *compiler-gnat* + +GNAT is the only free (beer and speech) Ada compiler available. There are +several versions available which differ in the licence terms used. + +The GNAT compiler plug-in will perform a compile on pressing <F7> and then +immediately shows the result. You can set the project file to be used by +setting: + > + > call g:gnat.Set_Project_File ('my_project.gpr') + +Setting a project file will also create a Vim session (|views-sessions|) so - +like with the GPS - opened files, window positions etc. will be remembered +separately for all projects. + + *gnat_members* +GNAT OBJECT ~ + + *g:gnat.Make()* +g:gnat.Make() + Calls |g:gnat.Make_Command| and displays the result inside a + |quickfix| window. + + *g:gnat.Pretty()* +g:gnat.Pretty() + Calls |g:gnat.Pretty_Program| + + *g:gnat.Find()* +g:gnat.Find() + Calls |g:gnat.Find_Program| + + *g:gnat.Tags()* +g:gnat.Tags() + Calls |g:gnat.Tags_Command| + + *g:gnat.Set_Project_File()* +g:gnat.Set_Project_File([{file}]) + Set gnat project file and load associated session. An open + project will be closed and the session written. If called + without file name the file selector opens for selection of a + project file. If called with an empty string then the project + and associated session are closed. + + *g:gnat.Project_File* +g:gnat.Project_File string + Current project file. + + *g:gnat.Make_Command* +g:gnat.Make_Command string + External command used for |g:gnat.Make()| (|'makeprg'|). + + *g:gnat.Pretty_Program* +g:gnat.Pretty_Program string + External command used for |g:gnat.Pretty()| + + *g:gnat.Find_Program* +g:gnat.Find_Program string + External command used for |g:gnat.Find()| + + *g:gnat.Tags_Command* +g:gnat.Tags_Command string + External command used for |g:gnat.Tags()| + + *g:gnat.Error_Format* +g:gnat.Error_Format string + Error format (|'errorformat'|) + +------------------------------------------------------------------------------ +4.2 Dec Ada ~ + *compiler-hpada* *compiler-decada* + *compiler-vaxada* *compiler-compaqada* + +Dec Ada (also known by - in chronological order - VAX Ada, Dec Ada, Compaq Ada +and HP Ada) is a fairly dated Ada 83 compiler. Support is basic: <F7> will +compile the current unit. + +The Dec Ada compiler expects the package name and not the file name to be +passed as a parameter. The compiler plug-in supports the usual file name +convention to convert the file into a unit name. Both '-' and '__' are allowed +as separators. + + *decada_members* +DEC ADA OBJECT ~ + + *g:decada.Make()* +g:decada.Make() function + Calls |g:decada.Make_Command| and displays the result inside a + |quickfix| window. + + *g:decada.Unit_Name()* +g:decada.Unit_Name() function + Get the Unit name for the current file. + + *g:decada.Make_Command* +g:decada.Make_Command string + External command used for |g:decada.Make()| (|'makeprg'|). + + *g:decada.Error_Format* +g:decada.Error_Format string + Error format (|'errorformat'|). + +============================================================================== +5. References ~ + *ada-reference* + +------------------------------------------------------------------------------ +5.1 Options ~ + *ft-ada-options* + + *g:ada_standard_types* +g:ada_standard_types bool (true when exists) + Highlight types in package Standard (e.g., "Float"). + + *g:ada_space_errors* + *g:ada_no_trail_space_error* + *g:ada_no_tab_space_error* + *g:ada_all_tab_usage* +g:ada_space_errors bool (true when exists) + Highlight extraneous errors in spaces ... + g:ada_no_trail_space_error + - but ignore trailing spaces at the end of a line + g:ada_no_tab_space_error + - but ignore tabs after spaces + g:ada_all_tab_usage + - highlight all tab use + + *g:ada_line_errors* +g:ada_line_errors bool (true when exists) + Highlight lines which are too long. Note: This highlighting + option is quite CPU intensive. + + *g:ada_rainbow_color* +g:ada_rainbow_color bool (true when exists) + Use rainbow colours for '(' and ')'. You need the + rainbow_parenthesis for this to work. + + *g:ada_folding* +g:ada_folding set ('sigpft') + Use folding for Ada sources. + 's': activate syntax folding on load + 'p': fold packages + 'f': fold functions and procedures + 't': fold types + 'c': fold conditionals + 'g': activate gnat pretty print folding on load + 'i': lone 'is' folded with line above + 'b': lone 'begin' folded with line above + 'p': lone 'private' folded with line above + 'x': lone 'exception' folded with line above + 'i': activate indent folding on load + + Note: Syntax folding is in an early (unusable) stage and + indent or gnat pretty folding is suggested. + + For gnat pretty folding to work the following settings are + suggested: -cl3 -M79 -c2 -c3 -c4 -A1 -A2 -A3 -A4 -A5 + + For indent folding to work the following settings are + suggested: shiftwidth=3 softtabstop=3 + + *g:ada_abbrev* +g:ada_abbrev bool (true when exists) + Add some abbreviations. This feature is more or less superseded + by the various completion methods. + + *g:ada_withuse_ordinary* +g:ada_withuse_ordinary bool (true when exists) + Show "with" and "use" as ordinary keywords (when used to + reference other compilation units they're normally highlighted + specially). + + *g:ada_begin_preproc* +g:ada_begin_preproc bool (true when exists) + Show all begin-like keywords using the colouring of C + preprocessor commands. + + *g:ada_omni_with_keywords* +g:ada_omni_with_keywords + Add Keywords, Pragmas, Attributes to omni-completions + (|compl-omni|). Note: You can always complete then with user + completion (|i_CTRL-X_CTRL-U|). + + *g:ada_extended_tagging* +g:ada_extended_tagging enum ('jump', 'list') + use extended tagging, two options are available + 'jump': use tjump to jump. + 'list': add tags quick fix list. + Normal tagging does not support function or operator + overloading as these features are not available in C and + tagging was originally developed for C. + + *g:ada_extended_completion* +g:ada_extended_completion + Uses extended completion for <C-N> and <C-R> completions + (|i_CTRL-N|). In this mode the '.' is used as part of the + identifier so that 'Object.Method' or 'Package.Procedure' are + completed together. + + *g:ada_gnat_extensions* +g:ada_gnat_extensions bool (true when exists) + Support GNAT extensions. + + *g:ada_with_gnat_project_files* +g:ada_with_gnat_project_files bool (true when exists) + Add gnat project file keywords and Attributes. + + *g:ada_default_compiler* +g:ada_default_compiler string + set default compiler. Currently supported are 'gnat' and + 'decada'. + +An "exists" type is a boolean considered true when the variable is defined and +false when the variable is undefined. The value to which the variable is set +makes no difference. + +------------------------------------------------------------------------------ +5.2 Commands ~ + *ft-ada-commands* + +:AdaRainbow *:AdaRainbow* + Toggles rainbow colour (|g:ada_rainbow_color|) mode for + '(' and ')'. + +:AdaLines *:AdaLines* + Toggles line error (|g:ada_line_errors|) display. + +:AdaSpaces *:AdaSpaces* + Toggles space error (|g:ada_space_errors|) display. + +:AdaTagDir *:AdaTagDir* + Creates tags file for the directory of the current file. + +:AdaTagFile *:AdaTagFile* + Creates tags file for the current file. + +:AdaTypes *:AdaTypes* + Toggles standard types (|g:ada_standard_types|) colour. + +:GnatFind *:GnatFind* + Calls |g:gnat.Find()| + +:GnatPretty *:GnatPretty* + Calls |g:gnat.Pretty()| + +:GnatTags *:GnatTags* + Calls |g:gnat.Tags()| + +------------------------------------------------------------------------------ +5.3 Variables ~ + *ft-ada-variables* + + *g:gnat* +g:gnat object + Control object which manages GNAT compiles. The object + is created when the first Ada source code is loaded provided + that |g:ada_default_compiler| is set to 'gnat'. See + |gnat_members| for details. + + *g:decada* +g:decada object + Control object which manages Dec Ada compiles. The object + is created when the first Ada source code is loaded provided + that |g:ada_default_compiler| is set to 'decada'. See + |decada_members| for details. + +------------------------------------------------------------------------------ +5.4 Constants ~ + *ft-ada-constants* + +All constants are locked. See |:lockvar| for details. + + *g:ada#WordRegex* +g:ada#WordRegex string + Regular expression to search for Ada words. + + *g:ada#DotWordRegex* +g:ada#DotWordRegex string + Regular expression to search for Ada words separated by dots. + + *g:ada#Comment* +g:ada#Comment string + Regular expression to search for Ada comments. + + *g:ada#Keywords* +g:ada#Keywords list of dictionaries + List of keywords, attributes etc. pp. in the format used by + omni completion. See |complete-items| for details. + + *g:ada#Ctags_Kinds* +g:ada#Ctags_Kinds dictionary of lists + Dictionary of the various kinds of items which the Ada support + for Ctags generates. + +------------------------------------------------------------------------------ +5.5 Functions ~ + *ft-ada-functions* + +ada#Word([{line}, {col}]) *ada#Word()* + Return full name of Ada entity under the cursor (or at given + line/column), stripping white space/newlines as necessary. + +ada#List_Tag([{line}, {col}]) *ada#Listtags()* + List all occurrences of the Ada entity under the cursor (or at + given line/column) inside the quick-fix window. + +ada#Jump_Tag ({ident}, {mode}) *ada#Jump_Tag()* + List all occurrences of the Ada entity under the cursor (or at + given line/column) in the tag jump list. Mode can either be + 'tjump' or 'stjump'. + +ada#Create_Tags ({option}) *ada#Create_Tags()* + Creates tag file using Ctags. The option can either be 'file' + for the current file, 'dir' for the directory of the current + file or a file name. + +gnat#Insert_Tags_Header() *gnat#Insert_Tags_Header()* + Adds the tag file header (!_TAG_) information to the current + file which are missing from the GNAT XREF output. + +ada#Switch_Syntax_Option ({option}) *ada#Switch_Syntax_Option()* + Toggles highlighting options on or off. Used for the Ada menu. + + *gnat#New()* +gnat#New () + Create a new gnat object. See |g:gnat| for details. + + +============================================================================== +6. Extra Plugins ~ + *ada-extra-plugins* + +You can optionally install the following extra plug-ins. They work well with +Ada and enhance the ability of the Ada mode: + +backup.vim + http://www.vim.org/scripts/script.php?script_id=1537 + Keeps as many backups as you like so you don't have to. + +rainbow_parenthsis.vim + http://www.vim.org/scripts/script.php?script_id=1561 + Very helpful since Ada uses only '(' and ')'. + +nerd_comments.vim + http://www.vim.org/scripts/script.php?script_id=1218 + Excellent commenting and uncommenting support for almost any + programming language. + +matchit.vim + http://www.vim.org/scripts/script.php?script_id=39 + '%' jumping for any language. The normal '%' jump only works for '{}' + style languages. The Ada mode will set the needed search patterns. + +taglist.vim + http://www.vim.org/scripts/script.php?script_id=273 + Source code explorer sidebar. There is a patch for Ada available. + +The GNU Ada Project distribution (http://gnuada.sourceforge.net) of Vim +contains all of the above. + +============================================================================== +vim: textwidth=78 nowrap tabstop=8 shiftwidth=4 softtabstop=4 noexpandtab +vim: filetype=help |