bashsupport.txt Bash Support Jul 24 2016
Bash Support bash-support bashsupport
Plug-in version 4.3
for Vim version 7.0 and above
Wolfgang Mehner <wolfgang-mehner@web.de>
Fritz Mehner <mehner.fritz@web.de>
Bash Support implements a bash-IDE for Vim/gVim. It is written to considerably
speed up writing code in a consistent style. This is done by inserting
complete statements, comments, idioms, and code snippets. Syntax checking,
running a script, starting a debugger can be done with a keystroke. There
are many additional hints and options which can improve speed and comfort when
writing shell scripts. This plug-in can be used for Bash version 4.0.
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
++ The plug-in version 4.0+ is a rewriting of version 3.12.1. ++
++ The versions 4.0+ are based on a new and more powerful template system ++
++ (please see |template-support|for more information). ++
++ The template syntax has changed! ++
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1. Usage with GUI |bashsupport-usage-gvim|
1.1 Menu 'Comments' |bashsupport-comments|
1.1.1 Append aligned comments |bashsupport-aligned-comm|
1.1.2 Adjust end-of-line comments |bashsupport-comm-realign|
1.1.3 Comment/uncomment |bashsupport-comm-toggle|
1.1.4 Frame comments, file header, ... |bashsupport-comm-templates|
1.1.5 Comment/uncomment with echo |bashsupport-comm-echo|
1.1.6 KEYWORD + comment |bashsupport-comm-keywords|
1.2 Menu 'Statements' |bashsupport-statements|
1.2.1 Normal mode, insert mode |bashsupport-stat-norm-ins|
1.2.2 Visual mode |bashsupport-stat-visual|
1.3 Menus'Tests' ... 'Shopts' |bashsupport-tests|
1.4 Menu 'PatternMatching' |bashsupport-pattern|
1.5 Menu 'I/O-Redir' |bashsupport-io-redir|
1.6 Menu 'Snippets' |bashsupport-snippets|
1.6.1 Code Snippets |bashsupport-codesnippets|
1.6.2 Edit Templates |bashsupport-templates-edit|
1.7 Menu 'Run' |bashsupport-run|
1.7.1 Save and run |bashsupport-run-script|
1.7.2 Script command line arguments |bashsupport-cmdline-args|
1.7.3 Bash command line arguments |bashsupport-bash-cmdline-args|
1.7.4 Save and check syntax |bashsupport-syntax-check|
1.7.4.1 Error format |bashsupport-errorformat|
1.7.4.2 Syntax check options |bashsupport-syntax-check-options|
1.7.5 Start debugger |bashsupport-debugger|
1.7.6 Hardcopy |bashsupport-hardcopy|
1.7.7 Xterm size |bashsupport-xterm|
1.7.8 Output redirection |bashsupport-output|
1.8 Menu 'Help' |bashsupport-help|
2. Usage without GUI |bashsupport-usage-vim|
3. Hot keys |bashsupport-hotkeys|
4. Customization and configuration |bashsupport-customization|
4.1 Files |bashsupport-custom-files|
4.2 Global variables |bashsupport-custom-variables|
4.3 The root menu |bashsupport-custom-root|
4.4 System-wide installation |bashsupport-system-wide|
5. Template files and tags |bashsupport-templates|
5.1 Template files |bashsupport-templates-files|
5.2 Macros |bashsupport-templates-macros|
5.2.1 Formats for date and time |bashsupport-templates-date|
5.3 Templates |bashsupport-templates-names|
5.3.1 Template definition |bashsupport-templates-definition|
5.3.1 Template names |bashsupport-templates-names|
5.3.2 The jump tags <+text+> etc. |bashsupport-templates-jumptags|
5.3.3 Command Ctrl-j |bashsupport-Ctrl-j|
5.4 Additional filenames with filetype 'sh' |bashsupport-also-bash|
6. Bash dictionary |bashsupport-dictionary|
7. Additional Mappings |bashsupport-ad-mappings|
8. Windows particularities |bashsupport-windows|
9. TROUBLESHOOTING |bashsupport-troubleshooting|
10. Release Notes |bashsupport-release-notes|
How to add this help file to Vim's help |add-local-help|
1. USAGE with GUI (gVim) bashsupport-usage-gvim
If the menus are not visible call them with the entry "Load Bash Support" in the standard Tools-menu.
1.1 MENU 'Comments' bashsupport-comments
1.1.1 APPEND ALIGNED COMMENTS TO CONSECUTIVE LINES bashsupport-aligned-comm
In NORMAL MODE the menu item 'end-of-line comment' will append a comment to the current line. In VISUAL MODE, this item will append aligned comments to all marked lines. Marking the 4 linesx11=11;x1111=1111;x11111111=11111111;and choosing 'end-of-line comment' will yieldx11=11; # |x1111=1111; #x11111111=11111111; #The cursor position above is marked by '|' . Empty lines will be ignored. The default starting column is 49 ( = (multiple of 2,4, or 8) + 1 ). This can be changed by setting a global variable in the file '.vimrc', e.g. :let g:BASH_LineEndCommColDefault = 45The starting column can also be set by the menu item 'Comments->adjust end-of-line com.' . Just position the cursor in an arbitrary column (normal mode; column number is shown in the Vim status line) and choose this menu item. This setting is buffer related. If the cursor was at the end of a line you will be asked for a column number because this position is most likely not the desired starting column. Your choice will be confirmed. 1.1.2 ADJUST END-OF-LINE COMMENTS bashsupport-comm-realign
After some copy/paste/change actions comments may be misaligned:pathname=$(pwd) # the complete pathbasename=${pathname##*/}# the basenamedirname=$Realignment can be achieved with the menu item 'adjust end-of-line com.' In normal mode the comment (if any) in the current line will be aligned to the end-of-line comment column (see above) if possible. In visual mode the comments in the marked block will be aligned:{pathname%/*}# the pathnamepathname=$(pwd) # the complete pathbasename=${pathname##*/}# the basenamedirname=$Another way is to use the hotkey \cj. In normal and insert mode the current line will be adjusted. To adjust n lines starting with the current one use n\cj. 1.1.3 COMMENT/UNCOMMENT bashsupport-comm-toggle{pathname%/*}# the pathname
The comment sign # can be set or removed at the beginning of the current line or for a marked block using the menu items 'comment' (or \cc) and 'uncomment' (or \co). A single line needs not to be marked (normal mode, insert mode). A marked blockpathname=$(pwd) # the complete pathbasename=${pathname##*/}# the basenamedirname=$will be changed into (and vice versa){pathname%/*}# the pathname#pathname=$(pwd) # the complete path#basename=${pathname##*/}# the basename#dirname=$1.1.4 FRAME COMMENTS, FILE HEADER, ... bashsupport-comm-templates{pathname%/*}# the pathname
Frame comments, function descriptions and file header comments are read as templates from the appropriate files (see |bashsupport-templates|). 1.1.5 COMMENT/UNCOMMENT WITH echo bashsupport-comm-echo
The echo-entry in the Comments-menu can be used to put one or more statements
in a sort of comment. This is usually done for testing:
echo "rm -f $allfiles"
This can only be done in normal mode: The complete line (from the first
non-blank to the end) is framed with echo "..." ; the cursor will then be
moved to the next line. Now this line can be framed and so forth.
The remove-echo-entry removes an echo. The keyword echo, the following double
quotation mark, and the last double quotation mark in the current line will be
removed; the cursor will then be moved to the next line.
1.1.6 KEYWORD+comment bashsupport-comm-keywords
Preliminary end-of-line comments to document (and find again!) places where
work will be resumed shortly, like
# :BUG:23.05.2013 16:43:fgm:
Here 'fgm' is the authors reference (see section 4. for templates and tags).
Usually these comments are not meant for the final documentation.
1.2 MENU 'Statements' bashsupport-statements
1.2.1 NORMAL MODE, INSERT MODE. bashsupport-stat-norm-ins
An empty statement will be inserted and properly indented. The item 'if' will insert an if-statement:if | ; thenfiThe statement will be indented. 1.2.2 VISUAL MODE bashsupport-stat-visual
The highlighted areaxxxxxxxxxxcan be surrounded by one of the following statements ( '|' marks the cursor position after insertion):+--------------------------+---------------------------------------+|| ||for| in ; do |for (( CNTR=0; CNTR<|; CNTR++ )); do ||xxxxx| xxxxx ||xxxxx| xxxxx ||done| done ||| |+--------------------------+---------------------------------------+|| ||if| ; then |if| ; then ||xxxxx| xxxxx ||xxxxx| xxxxx ||fi| else ||| ||| fi ||| |+--------------------------+---------------------------------------+|| ||select| in ; do |until| ; do ||xxxxx| xxxxx ||xxxxx| xxxxx ||done| done ||| |+--------------------------+---------------------------------------+|| ||while| ; do |||xxxxx| ||xxxxx| ||done| ||| |+--------------------------+---------------------------------------+|||fname ()||{||xxxxx||xxxxx||} # ---------- end of function fname ----------|||+------------------------------------------------------------------+The whole statement will be indented after insertion.
1.3 MENUS 'Tests' ... 'Shopts' bashsupport-tests
Insert tests, parameter substitutions, ... I/O-redirections.
1.4 MENU 'PatternMatching' bashsupport-pattern
This menu can be used to compose globs and regular expressions with a few keystrokes. In normal and insert mode the items insert the shown constructs after the cursor. The first group ( "zero or more" ... "anything expect") can enclose a marked text. The marked textxxxxxwill be changed into*(xxxxx|)by the first choice.
1.5 MENU 'I/O-Redir' bashsupport-io-redir
This menu can be used to insert I/O redirectors. The cursor will be positioned at the obvious or most likely continuation point. The item 'here-document' has a visual mode. A few marked lines will be surrounded by the necessary statements, e.g.<< EOFxxxxxxxxxxxxxxxxxxxxxxEOF# ===== end of here-document =====
1.6 MENU 'SNIPPETS' bashsupport-snippets
1.6.1 Code Snippets bashsupport-codesnippets
Code snippets are pieces of code which are kept in separate files in a special directory. File names are used to identify the snippets. The default snippet directory is '$HOME/.vim/bash-support/codesnippets'. Snippets are managed with the 4 items'read code snippet''view code snippet''write code snippet''edit code snippet'from the Snipptes submenu. Creating a new snippet:
When nothing is marked, 'write code snippet' will write the whole buffer to a snippet file, otherwise the marked area will be written to a file. Insert a snippet:
Select the appropriate file from the snippet directory ('read code snippet').
The inserted lines will be indented.
Indentation / no indentation
Code snippets are normally indented after insertion. To suppress indentation
add the file extension "ni" or "noindent" to the snippet file name, e.g.
parameter_handling.noindent
Snippet browser
Under a GUI a file requester will be put up. Without GUI the filename will be
read from the command line. You can change this behavior by setting a global
variable in your $HOME/.vimrc :
let g:BASH_GuiSnippetBrowser = 'commandline'
The default value is 'gui'.
1.6.2 Edit Templates bashsupport-templates-edit
Nearly all menu items insert code snippets or comments. All of these are
contained within template files and can be changed by the user to meet their
requirements (see|bashsupport-templates|on how to use the template system).
The menu items 'edit ... templates' open various template files. The stock
templates are usually located in the "local" template file:
~/.vim/bash-support/templates/Templates
The template files named "custom" and "personal" can be used for
customization, which avoids editing the stock templates.
There may be dependent files loaded from the main files. Change whatever file
you want, save it, and click on the menu item 'reread templates' to read in
the file(s) and to rebuild the internal representation of the templates.
Template browser
When editing a template file, it is selected via |:Explore|. You can change this behavior by setting a global variable in your ~/.vimrc (see |g:Templates_TemplateBrowser|):let g:Templates_TemplateBrowser = 'browse'
1.7 MENU 'Run' bashsupport-run
1.7.1 Save and run bashsupport-run-script
Save the current buffer to his file and run this file. The command line, the applied parameters and the shell return code are shown in the bottom line. * In NORMAL MODE the whole buffer will be executed. * In VISUAL MODE only the selected lines will be executed. There are three output destinations (see|bashsupport-output|). If the output destination is VIM runtime errors are caught in an error window allowing quickfix commands to be used (see|quickfix|). The shell used can be set in the file '.vimrc', e.g. :let g:BASH_Executable = '/bin/zsh'The default is the value of $SHELL (Linux/U**X) or 'bash.exe' (Windows). 1.7.2 Script command line arguments bashsupport-cmdline-args
The item 'script cmd. line arg.' calls an input dialog which asks for command
line arguments. These arguments are forwarded to the script which is run by
the 'run' item. The arguments are kept until you change them. For file names
tab-expansion will work. The ex command
:BashScriptArguments ...
can also be used to set the command line arguments for the current script.
The arguments belong to the current buffer (that is, each buffer can have its
own arguments). The input dialog has a history.
If the buffer gets a new name with "save as" the arguments will now belong to
the buffer with the new name.
1.7.3 Bash command line arguments bashsupport-bash-cmdline-args
The menu item 'Bash com. line arg.' calls an input dialog which asks for command line options for the the Bash shell running the script in the actual buffer (like -x or -v; see the Bash manual for possible options). These arguments are forwarded to the invocation of Bash which is run by the 'run' entry. The arguments are kept until you change them. The arguments belong to the current buffer (that is, each buffer can have its own arguments). If the buffer gets a new name with "save as" the arguments will now belong to the buffer with the new name. 1.7.4 Save and check syntax bashsupport-syntax-check
Save the current buffer to this file and run this file with the -n flag (Bash: read commands but do not execute them; same for dash, ksh, zsh). Errors are listed in an error window; now the quickfix commands can be used. 1.7.4.1 ERROR FORMAT bashsupport-errorformat
The format used to parse runtime errors handle bash, dash, ksh, and zsh errors. This format is appropriate for most locales including 'C' and 'POSIX'. 1.7.4.2 SYNTAX CHECK OPTIONS bashsupport-syntax-check-options
The syntax check can be influenced by shopt options. Options which shall always take effect can be declared in '.vimrc' , e.g.let g:BASH_SyntaxCheckOptionsGlob = "-O extglob"These options can be augmented or canceled using the menu entry 'syntax check options' typing for instance+O extglob -O nocaseglobafter the prompt. The options entered this way are buffer related. The global options set in '.vimrc' and the buffer related options are checked. 1.7.5 START DEBUGGER bashsupport-debugger
Start the debugger 'bashdb' or the frontend 'ddd' from the menu entry Run->debug (GUI), with hotkey \rd or F9. Your version of the bash must be prepared for debugging and the debugger must be installed (see http://bashdb.sourceforge.net/). (1) Using bashdb When using gvim or vim running under a GUI the debugger will be started in an independent xterm. This is done because the shell integration in gvim has deficiencies (see also :h shell-window). When using vim from a console terminal the debugger will be started as:!xtermThe debugger now will be run inside vim. (2) Using ddd The frontend ddd can be started via the menu or the hotkeys instead of bashdb as described above. The preference can be set with the global variable g:BASH_Debugger (possible values: 'term', 'ddd' ) in '.vimrc' :<xterm defaults>-e bashdb --<script><arguments>&let g:BASH_Debugger = 'ddd'The default is 'term'. In all cases the command line arguments from the argument setting (|bashsupport-cmdline-args|) are passed to the debugger. 1.7.6 Hardcopy bashsupport-hardcopy
Generates a PostScript file from the whole buffer or from a marked region. The hardcopy goes to the current working directory. If the buffer contains documentation or other material from non-writable directories the hardcopy goes to the HOME directory. The output destination will be shown in a message. The print header contains date and time for the current locale. The definition used islet s:BASH_Printheader = "%<%f%h%m%< %=%The current locale can be overwritten by changing the language, e.g.{strftime('%x %X')}Page %N":language Cor by setting a global variable in the file '.vimrc', e.g. :let g:BASH_Printheader = "%<%f%h%m%< %=%See :h printheader and :h strftime() for more details. 1.7.7 Xterm size bashsupport-xterm{strftime('%x %X')}SEITE %N"
The size of the xterm (see below) can be changes for the current session. The size has to be specified as COLUMNS LINES (e.g. 96 32 ). 1.7.8 Output redirection bashsupport-output
The last menu entry 'output: ... ' has 3 states: 'output: VIM->buffer->xterm' 'output: BUFFER->xterm->vim' 'output: XTERM->vim->buffer' The first state (upper-case) is the current one. Target VIM
The script is run from the command line like ":!${SHELL}% arguments". This is suitable for scripts with dialog elements and few lines of output. When a script is started this way errors and warnings (if any) are caught in an error window allowing quickfix commands to be used (see|quickfix|). Target BUFFER
The shell output will be displayed in a window with name "Bash-Output". This buffer and its content will disappear when the window is closed. It is not writable and it has no file. The content could be saved with "save as". If the output fits completely into this window the cursor will stay in the script window otherwise the cursor will be set into the output window (you may want to scroll). When the script is run again and the output buffer is still open it will be reused. The buffer will not be opened if the script does not produce any output. This is for convenience; you do not have to close an empty buffer. * This is suitable for scripts without dialog elements and many lines of output * (e.g. from options like xtrace). Use Vim as pager (scroll, jump, search with * regular expressions, .. ) Target XTERM
The script will be run in a xterm-window. A wrapper script will ask you to
close this window with Return or <C-D> (bash).
The wrapper shows the complete command line and the return code of the script.
* This is suitable for scripts with dialog elements and many lines of output.
* The xterm is scrollable and independent from the editor window.
Appearance of the xterm
The appearance of the xterm can be controlled by the global variable g:BASH_XtermDefaults. The assignmentlet g:BASH_XtermDefaults = "-fa courier -fs 10 -geometry 96x32"placed in '.vimrc' would override the defaults. The defaults are"-fa courier -fs 12 -geometry 80x24"FreeType font 'courier', FreeType font size 12 point, window width 80 characters, window height 24 lines. The default output method is VIM. The preferred output method can be selected in '.vimrc' by the global variable g:BASH_OutputGvim, e.g.let g:BASH_OutputGvim = "xterm"The methods are "vim", "buffer" and "xterm".
1.8 MENU 'Help' bashsupport-help
Item 'Bash manual'
Open the Bash manual. Item 'help (Bash builtins)'
Look up Bash help for the word under the cursor. If there is no word under the cursor you will be asked for the name of a builtin. The tab expansion can be used. Item 'manual (utilities)'
Display the manual for the word under the cursor. If there is more than one hit a list of possibilities will be displayed to choose from. If there is no word under the cursor you will be asked for the name of a command line utility. In this case the command completion is on while entering a name. An interface to the on-line reference manuals must be installed (usually man(1) for Linux/Unix, see|bashsupport-custom-variables|). Item 'bash-support'
Display this help text if it was properly added with ':helptags'.
2. USAGE without GUI (Vim) bashsupport-usage-vim
The frequently used constructs can be inserted with key mappings. The
mappings are also described in the document 'bash-hotkeys.pdf' (reference
card, part of this package).
* All mappings are filetype specific: they are only
* defined for buffers with filetype 'sh' to minimize conflicts with mappings
* from other plug-ins.
Hint: Typing speed matters. The combination of a leader ('\') and the
following character(s) will only be recognized for a short time.
Some mappings can be used with line range. In normal mode
\cl
appends a end-of-line comment to the current line, whereas
4\cl
appends end-of-line comments to the 4 lines starting with the current line.
Legend: (i) insert mode, (n) normal mode, (v) visual mode
[n] range
-- Submenus ----------------------------------------------
\bps parameter substitution (list) (n, i)
\bsp special parameters (list) (n, i)
\ben environment (list) (n, i)
\bbu builtin (list) (n, i)
\bse set options (list) (n, i)
\bso shopts (list) (n, i)
-- Comments ----------------------------------------------
[n]\cl line end comment (n, i, v)
[n]\cj adjust end-of-line comments (n, i, v)
\cs set end-of-line comment column (n)
[n]\cc code -> comment (n, i, v)
[n]\co uncomment code (n, i, v)
\cfr frame comment (n, i)
\cfu function description (n, i)
\ch file header (n, i)
\cd date (n, i, v)
\ct date & time (n, i, v)
\css script sections (n, i)
\ckc keyword comments (n, i)
\cma plug-in macros (n, i)
\ce echo "..." (n, i)
\cr remove echo "..." (n, i)
-- Statements ---------------------------------------------
\sc case in ... esac (n, i)
\sei elif then (n, i)
\sf for in do done (n, i, v)
\sfo for ((...)) do done (n, i, v)
\si if then fi (n, i, v)
\sie if then else fi (n, i, v)
\ss select in do done (n, i, v)
\su until do done (n, i, v)
\sw while do done (n, i, v)
\sfu function (n, i, v)
\se echo -e "..." (n, i, v)
\sp printf "..." (n, i, v)
\sa array element, ${.[.]} (n, i, v)
\saa array elements (all), ${.[@]} (n, i, v)
\sas array elements (string), ${.[*]} (n, i, v)
\ssa subarray, ${.[@]::} (n, i, v)
\san no. of array elements, ${#.[@]} (n, i, v)
\sai array indices, ${!.[*]} (n, i, v)
-- Test ---------------------------------------------------
\ta arithmetic tests (n, i)
\tfp file permission (n, i)
\tft file types (n, i)
\tfc file characteristics (n, i)
\ts string comparison (n, i)
\toe option is enabled (n, i)
\tvs variables has been set (n, i)
\tfd file descriptor is open (n, i)
\tm string matches regexp (n, i)
-- I/O-Redirection ----------------------------------------
\ior IO-redirections (list) (n, i)
\ioh here-document (n, i)
-- Pattern Matching ---------------------------------------
\pzo zero or more, ?( | ) (n, i)
\pzm zero or more, *( | ) (n, i)
\pom one or more, +( | ) (n, i)
\peo exactly one, @( | ) (n, i)
\pae anything except, !( | ) (n, i)
\ppc POSIX classes (n, i)
\pbr BASH_REMATCH (n, i)
-- Snippets -----------------------------------------------
\nr read code snippet (n, i)
\nv view code snippet (readonly) (n, i)
\nw write code snippet (n, v, i)
\ne edit code snippet (n, i)
\ntg edit global template file (n, i)
\ntl edit local templates (n, i)
\ntc edit custom template file (n, i)
\ntp edit personal template file (n, i)
\ntr reread the templates (n, i)
\ntw template setup wizard (n, i)
\nts switch template style (n, i)
-- Run ----------------------------------------------------
[n]\rr update file, run script (n, i)
\ra set script cmd. line arguments (n, i)
\rba set Bash cmd. line arguments (n, i)
\rc update file, check syntax (n, i)
\rco syntax check options (n, i)
\rd start debugger (n, i)
\re make script executable/not exec.(*) (in )
\rh hardcopy buffer to FILENAME.ps (n, i)
\rs plug-in settings (n, i)
\rt set xterm size (*) (n, i)
\ro change output destination (n, i)
-- Bash help ----------------------------------------------
\hb Displays the Bash manual (n, i)
\hh Displays help for the builtin (n, i)
under the cursor (Bash help).
The tab expansion is active.
\hm displays the manual for the (n, i)
Bash command under the cursor
The tab expansion is active.
\hbs Displays the Vim help page for (n, i)
this plug-in.
(*) Linux/UNIX only
File 'bash-hotkeys.pdf' contains a reference card for these key mappings.
Multiline inserts and code snippets will be indented after insertion.
Changing the default map leader '\'
The map leader can be changed by the user by setting a global variable in the file .vimrclet g:BASH_MapLeader = ','The map leader is now a comma. The 'line end comment' command is now defined as ',cl'. This setting will be used as a so called local leader and influences only files with filetype 'sh'. The configured mapleader can also be used in the ftplugin, by calling the functions Bash_SetMapLeader() and Bash_ResetMapLeader() . The maps created between the two calls will use |g:BASH_MapLeader| as the |<LocalLeader>|:call Bash_SetMapLeader ()map<buffer><LocalLeader>eg :echo "Example Map :)"<CR>call Bash_ResetMapLeader ()
3. HOT KEYS bashsupport-hotkeys
The following hot keys are defined in NORMAL, VISUAL and INSERT MODE:
Ctrl-F9 run script
Alt-F9 run syntax check
Shift-F9 command line arguments (for the current buffer)
F9 start debugger (bashdb)
See |bashsupport-usage-vim| for more hotkeys.
4.0 CUSTOMIZATION bashsupport-customization
4.1 FILES bashsupport-custom-files
bash-support/README.md Release notes, installation description.
plugin/bash-support.vim The Bash plug-in for Vim/gVim.
bash-support/scripts/wrapper.sh A wrapper script for the use of an xterm.
doc/bashsupport.txt The help file for the local online help.
bash-support/codesnippets/* Some code snippets as a starting point.
bash-support/templates/* Bash template files (see |bashsupport-comm-templates|).
autoload/mmtemplates/* The template engine.
bash-support/wordlists/* Additional word lists (dictionaries).
-------------------------------------------------------------
The following files and extensions are for convenience only.
bash-support.vim will work without them.
-------------------------------------------------------------
bash-support/doc/* Hotkey reference card (PDF), changelog.
bash-support/rc/costumization.bashrc Additional settings I use in .bashrc:
set the prompt P2, P3, P4 (for debugging).
bash-support/rc/costumization.vimrc Additional settings I use in '.vimrc': incremental
search, tabstop, hot keys, font, use of dictionaries,
... The file is commented. Append it to your '.vimrc'
if you like.
bash-support/rc/costumization.gvimrc Additional settings I use in '.gvimrc': hot keys,
mouse settings, ... The file is commented.
Append it to your '.gvimrc' if you like.
bash-support/rc/sh.vim Suggestions for additional maps.
4.2 GLOBAL VARIABLES bashsupport-custom-variables
Several global variables are checked by the script to customize it:
global variable default value
g:BASH_GlobalTemplateFile root_dir.'bash-support/templates/Templates'
g:BASH_LocalTemplateFile $HOME.'/.vim/bash-support/templates/Templates'
g:BASH_CustomTemplateFile $HOME.'/.vim/templates/bash.templates'
g:BASH_CodeSnippets $HOME.'/.vim/bash-support/codesnippets' (Linux/U**X)
$VIM.'\vimfiles\bash-support/codesnippets/' (Windows)
g:BASH_LoadMenus 'yes'
g:BASH_CreateMenusDelayed 'no'
g:BASH_Dictionary_File $HOME."/.vim/bash-support/wordlists/bash.list"
g:BASH_RootMenu '&Bash.'
g:BASH_GuiSnippetBrowser 'gui'
g:BASH_OutputGvim 'vim' (Linux/U**X)
'xterm' (Windows)
g:BASH_XtermDefaults '-fa courier -fs 12 -geometry 80x24'
g:BASH_Debugger 'term'
g:BASH_LineEndCommColDefault 49
g:BASH_SyntaxCheckOptionsGlob ''
g:BASH_Printheader '%<%f%h%m%< %=%{strftime('%x %X')} Page %N'
g:BASH_InsertFileHeader 'yes'
g:BASH_Executable $SHELL (Linux/U**X)
'bash.exe' (Windows)
g:BASH_ManualReader 'man' (Linux/U**X)
'man.exe' (Windows)
g:BASH_MapLeader '\'
g:BASH_Errorformat '%f:\ line\ %l:\ %m'
g:BASH_AlsoBash ''
1. group: Defines the text which will be inserted for the tags when a
template is read in (see |bashsupport-templates|).
g:BASH_GlobalTemplateFile : sets the global template file
(see|bashsupport-templates|)
g:BASH_LocalTemplateFile : sets the local template file
(see|bashsupport-templates|)
g:BASH_CustomTemplateFile : sets the custom template file
(see|bashsupport-templates|)
2. group: g:BASH_CodeSnippets : The name of the code snippet directory
(see |bashsupport-snippets|).
g:BASH_LoadMenus : Load menus and mappings (yes/no) at start up.
g:BASH_CreateMenusDelayed : Load menus only with filetype 'sh'
g:BASH_Dictionary_File : Path and file name of the Bash word list used
for dictionary completion
(see |bashsupport-dictionary|).
g:BASH_RootMenu : Name of the root menu item of this plug-in
(see |bashsupport-custom-root|).
g:BASH_GuiSnippetBrowser : code snippet browser: 'gui', 'commandline'
3. group: g:BASH_OutputGvim : Target for a script output
(see |bashsupport-output|).
g:BASH_XtermDefaults : The xterm defaults (see |bashsupport-xterm|).
g:BASH_Debugger : the debugger called by F9 (term, ddd).
g:BASH_LineEndCommColDefault : default starting column for line end comments
g:BASH_SyntaxCheckOptionsGlob : shopt options used with syntax checking
g:BASH_Printheader : hardcopy header format
g:BASH_InsertFileHeader : suppress file header comment for new files
g:BASH_Executable : the shell used
g:BASH_ManualReader : the interface to the on-line manuals
g:BASH_MapLeader : the map leader for hotkeys
(see|bashsupport-usage-vim|)
g:BASH_Errorformat : errorforamat used to parse runtime errors
g:BASH_AlsoBash : filename patterns considered as Bash files
(see |bashsupport-also-bash|)
To override the defaults add appropriate assignments in '.vimrc'.
4.3 THE ROOT MENU bashsupport-custom-root
The variable g:BASH_RootMenu, if set (in '.vimrc' or in '.gvimrc'), gives the name of the single gVim root menu entry in which the Bash submenus will be put. The default is'&Bash'If you want to set the plug-in root menu into another menu, e.g. 'Plugin', this is done by the following line in '.vimrc'let g:BASH_RootMenu = "&Plugin.&Bash"
4.4 System-wide installation bashsupport-system-wide
A system-wide installation (one installation for all users) is done as follows. As *** SUPERUSER *** : (1) Find the Vim installation directory. The Vim ex command ':echo $VIM' gives '/usr/local/share/vim' or something like that. Beyond this directory you will find the Vim installation, e.g. in '/usr/local/share/vim/vim73' if Vim version 7.3 has been installed. (2) Create a new subdirectory 'vimfiles', e.g. '/usr/local/share/vim/vimfiles'. (3) Install Bash Support Copy the archive 'bash-support.zip' to this new directory and unpack it:unzip bash-support.zip(4) Generate the help tags::helptags $VIM/vimfiles/docSPECIAL CASES. Some Linux distributions use non-standard names for Vim directories. SUSE has a directory '/usr/share/vim/site' to put plug-ins in. These directories will not be found automatically. After installing the plug-in below '/usr/share/vim/site' the use of the templates will be enabled by the following line in '~/.vimrc':let g:BASH_GlobalTemplateFile = '/usr/share/vim/site/bash-support/templates/Templates'As ****** USER ****** : Use the template setup wizard: Bash -> Snippets -> template setup wizard to create a personalization file and/or a custom template file. The personalization file will be read by all plug-ins supporting this feature, and should contain only information relevant for all template libraries. You can set some macros in this file with your personal information in order to obtain personalized comments, e.g. something like this:SetMacro( 'AUTHOR', 'Wolfgang Mehner' )SetMacro( 'AUTHORREF', 'wm' )SetMacro( 'EMAIL', 'wolfgang-mehner@web.de' )SetMacro( 'COPYRIGHT', 'Copyright (c) |Use the custom template file for Bash templates which override the global templates or to add new ones. The old system (before version 4.3), using a "local" template file,YEAR|, |AUTHOR|' )~/.vim/bash-support/templatesis still supported for backwards compatibility. Create your private snippet directory:mkdir --parents $HOME/.vim/bash-support/codesnippetsYou may want to copy the snippets coming with this plug-in (in $VIM/vimfiles/bash-support/codesnippets) into the new directory or to set a link to the global directory.
5. TEMPLATE FILES AND TAGS bashsupport-templates
Nearly all menu items insert code snippets or comments. All of these are
contained within template files and can be changed by the user to meet their
requirements. The menu shortcuts (e.g. 'c' for the Comments menu) and the
menu item hotkeys (e.g. '\ct' insert date and time) are also defined in the
templates.
The template engine comes as a separate plug-in contributed by Wolfgang Mehner.
This section is a short introduction to this template system. Please see
|templatesupport| for more information.
The master template file is '$HOME/.vim/bash-support/templates/Templates' for
a user installation and '$VIM/vimfiles/bash-support/templates/Templates' for
a system-wide installation (see |bashsupport-system-wide|).
The master template file can be edited itself to adapt the templates/menus to
the users need. Alternatively, a custom template file can be added (see
g:BASH_CustomTemplateFile), which eliminates the need to edit stock templates.
The personalization (name, email, ..., date and time format) can be done in a
special personalization template file. It will be read by all plug-ins which
support this feature, so it should only contain basic information not
pertaining to a specific programming language. It can be set up using a
wizard, which is run by the map \ntw or the menu entry:
Bash -> Snippets -> template setup wizard
Further template files can be added using the call:
call mmtemplates#config#Add ( 'bash', '<PATH>/some.templates', 'example', 'nte' )
The first parameter adds the file to your Bash templates, the second is the
path. The remaining two optional parameters specify the symbolic name for
these templates and the map to edit them. The map is '\nte' in this example,
if the standard mapleader is set.
5.1 TEMPLATE FILES bashsupport-templates-files
The master template file starts with various settings followed by templates for single menu items or better by including other template files grouping the templates according to the menu structure of this plug-in. The master file usually looks like this:§ =============================================================§ User Macros§ =============================================================SetMacro( 'AUTHOR', 'YOUR NAME' )SetMacro( 'AUTHORREF', '' )SetMacro( 'EMAIL', '' )SetMacro( 'ORGANIZATION', '' )SetMacro( 'COMPANY', '' )SetMacro( 'COPYRIGHT', 'Copyright (c) |YEAR|, |AUTHOR|' )SetMacro( 'LICENSE', 'GNU General Public License' )SetStyle( 'default' )§ =============================================================§ File Includes and Shortcuts§ =============================================================MenuShortcut( 'Comments', 'c' )MenuShortcut( 'Statements', 's' )MenuShortcut( 'Tests', 't' )MenuShortcut( 'ParamSub', 'p' )MenuShortcut( 'PatternMatching', 'p' )MenuShortcut( 'IO-Redir', 'i' )IncludeFile( 'comments.templates' )IncludeFile( 'statements.templates' )IncludeFile( 'tests.templates' )IncludeFile( 'paramsub.templates' )IncludeFile( 'specialparams.templates' )IncludeFile( 'environment.templates' )IncludeFile( 'builtins.templates' )IncludeFile( 'set.templates' )IncludeFile( 'shelloptions.templates' )IncludeFile( 'io-redirection.templates' )IncludeFile( 'patternmatching.templates' )Lines starting with a paragraph sign are comments. The section starting withSetMacro( 'AUTHOR', 'YOUR NAME' )assigns values to predefined tags (macros). Arbitrary user-defined macros are possible. The macro name must follows the rules for a C language identifier: first character letter or underscore; case matters; digits are allowed beginning with the second character. Some of the macros assigned here are placeholders, they will be overwritten by template files read later on, which contain the user's configuration. The statementIncludeFile( 'comments.templates' )includes the templates from the file 'comments.templates' (in the same directory). An absolute path would also be possible. The statementMenuShortcut( 'Comments', 'c' )sets 'c' as the shortcut for the Comments menu.
5.2 Macros bashsupport-templates-macros
The following macro names are predefined. The first group of macros is used to
personalize templates.
----------------------------------------------------------------------------
PREDEFINED MACROS FOR PERSONALIZATION, DEFAULT VALUE is ''
----------------------------------------------------------------------------
|AUTHOR|
|AUTHORREF|
|COMPANY|
|COPYRIGHT|
|EMAIL|
|LICENSE|
|ORGANIZATION|
----------------------------------------------------------------------------
PREDEFINED MACROS DEFAULT VALUE
----------------------------------------------------------------------------
|BASENAME| filename without path and suffix
|DATE| the preferred date representation for the current locale
without the time
|FILENAME| filename without path
|PATH| path without filename
|SUFFIX| filename suffix
|TIME| the preferred time representation for the current locale
without the date and the time zone or name or abbreviation
|YEAR| the year as a decimal number including the century
----------------------------------------------------------------------------
PREDEFINED TAGS USED IN TEMPLATES
----------------------------------------------------------------------------
<CURSOR> The cursor position after insertion of a template.
<+text+>,<-text-> See |bashsupport-templates-jumptags|.
{+text+},{-text-}
[+text+],[-text-]
<SPLIT> The split point when inserting in visual mode
(see|bashsupport-templates|)
A dependent template file can start with its own command section. There is no
need to have all user defined macros in the master file.
5.2.1 User defined formats for date and time bashsupport-templates-date
The format for |DATE| ,|TIME| , and|YEAR| can be set by the user. The
defaults are
|DATE| '%x'
|TIME| '%X'
|YEAR| '%Y'
See the manual page of the C function strftime() for the format. The accepted
format depends on your system, thus this is not portable! The maximum length
of the result is 80 characters.
User defined formats can be set using the following function calls in the
master template file is '$HOME/.vim/bash-support/templates/Templates', e.g.
SetFormat( 'DATE', '%D' )
SetFormat( 'TIME', '%H:%M' )
SetFormat( 'YEAR', 'year %Y' )
5.3 Templates bashsupport-templates-names
5.3.1 Template Definition bashsupport-templates-definition The template behind a menu item is identified its name. The first part of the name identifies the menu name, the second part identifies the item. A template definition starts with a template header with the following syntax: == menu_name.template_name == options == The options are described here: |template-support-options|. 5.3.2 The jump tags<+text+>etc. bashsupport-templates-jumptags There are four jump tag types which can be used as jump targets in templates:<+text+>Can be jumped to by hitting Ctrl-j.{+text+}Same as<+text+>. Used in cases where indentation gives unwanted results with the first one.<-text->Same as the two above. Will be removed if the template is used{-text-}in visual mode. [+text+] The "optional" tag. Serves as a jump tag, but can be deleted using Ctrl-d. [-text-] Same as above, removed in visual mode. The text inside the brackets is userdefined and can be empty. The text can be composed from letters (uppercase and lowercase), digits, and underscores. After the insertion of an template these jump targets will be highlighted. 5.3.3 Command Ctrl-j bashsupport-Ctrl-j Use the command Ctrl-j to jump to the next target. The target will be removed and the mode will switched to insertion. Ctrl-j works in normal and in insert mode. The template for an if-else-statement can be written as follows:== Statements.if-else == map:sie, shortcut:i ==if<CURSOR>; then<SPLIT><-IF_PART->else<-ELSE_PART->fiThe cursor will be set as shown. When the condition is specified a Ctrl-j let you jump to the target<-IF_PART->and deletes it. When the block is written a Ctrl-j leads you to the else-part. The target<-ELSE_PART->disappears and you can type on.
5.4 ADDITIONAL FILENAMES WITH FILETYPE 'sh' bashsupport-also-bash
The standard extension for shell script files used by this plug-in is ".sh".
If you want to have other filenames recognized and treated as shell files
set the global variable g:BASH_AlsoBash in your '.vimrc' :
let g:BASH_AlsoBash = [ '.SlackBuild' , 'rc.' ]
This is a Vim List. Please quote the entries and separate them with commas.
Do not include the default extension '*.sh'.
6. BASH DICTIONARY bashsupport-dictionary
The file 'bash.list' contains words used as dictionary for automatic word completion. This feature is enabled by default. The default word list is$HOME/.vim/bash-support/wordlists/bash.listIf you want to use an additional list 'MyBash.List' put the following line into $HOME/.vimrc :let g:BASH_Dictionary_File = "$HOME/.vim/bash-support/wordlists/bash.list,".\ "$HOME/.vim/bash-support/wordlists/MyBash.List"The right side is a comma separated list of files.Notethe point at the end of the first line (string concatenation) and the backslash in front of the second line (continuation line). You can use Vim's dictionary featureCTRL-X,CTRL-K(andCTRL-P,CTRL-N).
7. ADDITIONAL MAPPINGS bashsupport-ad-mappings
Some suggestions are in 'bash-support/rc/sh.vim'. This is a filetype plug-in and would go to '$HOME/.vim/ftplugin/'.
8. WINDOWS PARTICULARITIES bashsupport-windows
For a user installation the plug-in should go into the directory structure below$HOME/vimfiles/for a system installation below$VIM/vimfiles/The values of the two variables can be found from inside Vim::echo $VIMor:echo $HOMEThe configuration files for a user are$HOME/_vimrc and $HOME/_gvimrcfor the system$VIM/_vimrc and $VIM/_gvimrcA Bash shell is not a part of a Windows system and has to be installed in addition. This plug-in assumes that the shell port bash.exe (http://www.cygwin.com) is present and the that command line utilities you want to use can be reached via your path variable. This shell can be changed to xyz-shell.exe by setting the following line into the file _vimrc:let g:BASH_Executable = 'xyz-shell.exe'The run-menu and the corresponding hotkeys are restricted. Please see the document 'bash-hotkeys.pdf' for this restrictions. The file format is switches to 'unix' on entering a buffer of type 'sh'. The filetype can be changed by setting a global variable in file _vimrc:let g:BASH_FileFormat = 'something_else'CYGWIN
Executing scripts with DOS style pathnames causes the error "MS-DOS style path detected". To turn these messages off add the CYGWIN environment variable CYGWIN with the value "nodosfilewarning".
9. TROUBLESHOOTING bashsupport-troubleshooting
* I do not see any new main menu item. - Was the archive extracted into the right directory? * How can I see what was loaded? - Use ':scriptnames' from the Vim command line. * No main menu item. - Loading of plug-in files must be enabled. If not use:filetype plugin onThis is the minimal content of the file '$HOME/.vimrc'. Create one if there is none, or better use customization.vimrc. * Most key mappings do not work. - They are defined in a filetype plugin in '$HOME/.vim/ftplugin/'. Use ':filetype' to check if filetype plug-ins are enabled. If not, add the linefiletype plugin onto the file '~/.vimrc'. * Some hotkeys do not work. - The hotkeys might be in use by your graphical desktop environment. Under KDE Ctrl-F9 is the hotkey which let you switch to the 9. desktop. The key settings can usually be redefined.
10. Release Notes bashsupport-release-notes
See files 'README.md' and 'ChangeLog'.
vim:tw=78:expandtab:ts=2:ft=help:norl:
Generated by vim2html (modified) on So 7. Aug 16:09:57 CEST 2016