bashsupport.txt Bash Support January 02 2013
bash Support bash-support bashsupport
Plugin version 3.12
for Vim version 7.0 and above
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 plugin can be used for Bash version 4.0.
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 Toggle comments |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.2.3 Code Snippets |bashsupport-stat-snippets|
1.2.4 Code Templates |bashsupport-templates-menu|
1.3 Menu 'set' |bashsupport-set|
1.4 Menu 'shopt' |bashsupport-shopt|
1.5 Menu 'Regex' |bashsupport-regex|
1.6 Menu 'I/O-Redir' |bashsupport-io-redir|
1.7 Menu 'Run' |bashsupport-run|
1.7.1 Save and run |bashsupport-run-script|
1.7.2 Save and check syntax |bashsupport-syntax-check|
1.7.3 Error format |bashsupport-errorformat|
1.7.4 Script command line arguments |bashsupport-cmdline-args|
1.7.5 Start debugger |bashsupport-debugger|
1.7.6 Bash command line arguments |bashsupport-bash-cmdline-args|
1.7.7 Hardcopy |bashsupport-hardcopy|
1.7.8 Xterm size |bashsupport-xterm|
1.7.9 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 names |bashsupport-templates-names|
5.3.2 Template definition |bashsupport-templates-definition|
5.3.3 Template expansion |bashsupport-templates-expansion|
5.3.4 The macros <+text+> etc. |bashsupport-templates-jump|
5.3.5 Command Ctrl-j |bashsupport-Ctrl-j|
5.4 Switching between template sets |bashsupport-templates-sets|
5.5 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 entry 'Line End Comm.' will append a comment to the current line. In VISUAL MODE, this item will append aligned comments to all marked lines. Marking the 4 lines x11=11; x1111=1111; x11111111=11111111; and choosing 'Line End Comm.' will yield x11=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 = 45 The starting column can also be set by the menu entry 'Comments->Set End Comm. Col.' . Just position the cursor in an arbitrary column (column number is shown in the Vim status line) and choose this menu entry. 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 path basename=${pathname##*/}# the basename dirname=${pathname%/*}# the pathname 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=$(pwd) # the complete path basename=${pathname##*/}# the basename dirname=${pathname%/*}# the pathname 1.1.3 TOGGLE COMMENTS bashsupport-comm-toggle
The comment sign # can be set or removed at the beginning of the current line or for a marked block. A single line needs not to be marked (normal mode). A marked block pathname=$(pwd) # the complete path basename=${pathname##*/}# the basename dirname=${pathname%/*}# the pathname will be changed into (and vice versa) #pathname=$(pwd) # the complete path #basename=${pathname##*/}# the basename #dirname=${pathname%/*}# the pathname Whitespaces in front of the hash sign will be preserved. 1.1.4 FRAME COMMENTS, FILE HEADER, ... bashsupport-comm-templates
Frame comments, function descriptions and file header comments are read as
templates from the appropriate files (see |bashsupport-tempfiles|).
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 be then 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. Longer sections of a script are better commented out with set options |bashsupport-set|. 1.1.6 KEYWORD+comment bashsupport-comm-keywords
Preliminary line end comments to document (and find again) places where work
will be resumed shortly, like
# :TODO:12.05.2004:Mn: <your comment>
Usually 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 entry 'if' will insert an if-statement: if | ; then fi The statements will be indented. 1.2.2 VISUAL MODE bashsupport-stat-visual
The highlighted area xxxxx xxxxx can be surrounded by one of the following statements ( '|' marks the cursor position after insertion): +--------------------------+---------------------------------------+ || | |for| in ; do |for (( CNTR=0; CNTR<0; 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. The highlighted area (...) will be surrounded by the following statements, parentheses, quotes or an echo with quotes: ${...}$(...) $((...)) $[[...]] echo -e "..." ${...[@]}${...[*]}${#...[*]}${!...[*]}1.2.3 CODE SNIPPETS bashsupport-stat-snippets
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 3 entries bash -> Statements -> read code snippet bash -> Statements -> write code snippet bash -> Statements -> edit code snippet from the Statements 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.sh.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 ~/.vimrc : let g:BASH_GuiSnippetBrowser = 'commandline' The default value is 'gui'. 1.2.4 Code Templates bashsupport-templates-menu
Nearly all menu entries 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 item 'edit local templates' opens the main template file in a local
plugin installation. This is usually the file
'~/.vim/bash-support/templates/Templates'. There may be dependent files
loaded from the main file. Now 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.
The menu item 'edit global templates' opens the main template file in a
system-wide plugin installation (see |bashsupport-system-wide|). This is
usually the file '$VIM./vimfiles/bash-support/templates/Templates'.
Template 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 ~/.vimrc :
let g:BASH_GuiTemplateBrowser = 'explorer'
The default value is 'gui'. 'explorer' will start the file explorer
(see help|:Explore|). To use the commandline asign 'commandline'.
1.3 MENU 'set' bashsupport-set
Calling a set-command (submenu "set") in NORMAL or INSERT MODE will set this option, e.g. set -o posix Calling a set-command (submenu "set") for a marked block (VISUAL MODE) rm "$alldirs" echo "$alldirs gone" will set this option above this block and unset it below: set -o posix # SetOptionNumber_1 rm "$alldirs" echo "$alldirs gone" set +o posix # SetOptionNumber_1 The option numbers SetOptionNumber_xxx are automatically incremented. They can be searched for with the vim star command (*).
1.4 MENU 'shopt' bashsupport-shopt
Calling a shopt-command (submenu "shopt") in NORMAL or INSERT MODE will set this option, e.g. shopt -s shift_verbose Calling a shopt-command (submenu "shopt") for a marked block (VISUAL MODE) function1 22 33 55 function2 "cc" will set this option above this block and unset it below: shopt -s shift_verbose # ShoptOptionNumber_1 function1 22 33 55 function2 "cc" shopt -u shift_verbose # ShoptOptionNumber_1 The option numbers ShoptOptionNumber_xxx are automatically incremented. They can be searched for with the vim star command (*).
1.5 MENU 'Regex' bashsupport-regex
This menu can be used to compose regular expressions with a few keystrokes. In normal mode the entries insert the shown constructs after the cursor. The first group ( "*(|)" , ... ) and the entry '[ ]' can enclose a marked text. The marked text xxxxx will be changed into *(xxxxx|) by the first choice.
1.6 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. << EOF xxxxxxxxxxx xxxxxxxxxxx EOF # ===== end of here-document =====
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 marked 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|).
1.7.2 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). Errors are listed in an error window; now the quickfix commands can be used. 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 nocaseglob after the prompt. The options entered this way are buffer related. The global options set in '.vimrc' and the buffer related options are checked. Only the shopts options for Bash (GNU Bash-4.0) are recognized: autocd cdable_vars cdspell checkhash checkjobs checkwinsize cmdhist compat31 dirspell dotglob execfail expand_aliases extdebug extglob extquote failglob force_fignore globstar gnu_errfmt histappend histreedit histverify hostcomplete huponexit interactive_comments lithist login_shell mailwarn no_empty_cmd_completion nocaseglob nocasematch nullglob progcomp promptvars restricted_shell shift_verbose sourcepath xpg_echo 1.7.3 Error format bashsupport-errorformat
The format used to parse runtime errors is '%f:\ %s\ %l:\ %m'. This format is appropriate for most locales including 'C' and 'POSIX'. The '%s' part looks for the English word 'line' or its one word translation in another language (e.g. 'Zeile' in German). If this does not work parsing fails and no errors will be reported. In this case add a line like let g:BASH_Errorformat = '%f:\ xyz\ %l:\ %m' to '~/.vimrc' to redefine the error format. Replace '%s' by the translation of this word in the current language. 1.7.4 Script command line arguments bashsupport-cmdline-args
The menu item 'menu com. line arg.' calls an input dialog which asks for command line arguments for the script in the actual buffer. These arguments are forwarded to the script which is run by the 'run' entry. The arguments are kept until you change them. For the first and only the first argument file name expansion will work (use the Tab-key). 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.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
:!bash --debugger <command line arguments>
The 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' :
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 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.7 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 otput destination will be shown in a message. The print header contains date and time for the current locale. The definition used is let s:BASH_Printheader = "%<%f%h%m%< %=%{strftime('%x %X')}Page %N" The current locale can be overwritten by changing the language, e.g. :language C or by setting a global variable in the file '.vimrc', e.g. : let g:BASH_Printheader = "%<%f%h%m%< %=%{strftime('%x %X')}SEITE %N" See :h printheader and :h strftime() for more details. 1.7.8 Xterm size bashsupport-xterm
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.9 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 assignment let 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 '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-hot-keys.pdf' (reference
card, part of this package).
* All mappings (except \lbs and \ubs) are filetype specific: they are only
* defined for buffers with filetype 'sh' to minimize conflicts with mappings
* from other plugins.
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 range (of lines). 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
-- 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 plugin.
-- 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)
\cfr frame comment (n, i)
\cfu function description (n, i)
\ch file header (n, i)
\ckb keyword comment BUG (n, i)
\ckt keyword comment TODO (n, i)
\ckr keyword comment TRICKY (n, i)
\ckw keyword comment WARNING (n, i)
\ckn keyword comment New_Keyword (n, i)
[n]\cc toggle comment (n, i, v)
\cd date (n, i, v)
\ct date & time (n, i, v)
\ce echo "..." (n, i)
\cr remove echo "..." (n, i)
\css script sections (tab completion) (n, i)
\ckc keyword comments(tab completion) (n, i)
\cv vim modeline (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 ${.[@]} (n, i, v)
\sa1 array elements, 1 word ${.[*]} (n, i, v)
\ssa subarray ${.[@]::} (n, i, v)
\san no. of array elements ${#.[@]} (n, i, v)
\sai list of arr. indices ${!.[*]} (n, i, v)
-- 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)
\ntl edit local templates (n, i)
\ntg edit global templates (n, i)
\ntr reread the templates (n, i)
\nts switch template style (n, i)
-- Test ------------------------------------------------
\t1 unary operator, 1 arg.: \verb'[ - ]' (n, i)
\t2 binary operator, 2 arg: \verb'[ - ]' (n, i)
-- Regular Expression ----------------------------------
\xm [[ =~ ]] (n, i)
-- POSIX Character Classes -----------------------------
\pan [:alnum:] (n, i)
\pal [:alpha:] (n, i)
\pas [:ascii:] (n, i)
\pb [:blank:] (n, i)
\pc [:cntrl:] (n, i)
\pd [:digit:] (n, i)
\pg [:graph:] (n, i)
\pl [:lower:] (n, i)
\ppr [:print:] (n, i)
\ppu [:punct:] (n, i)
\ps [:space:] (n, i)
\pu [:upper:] (n, i)
\pw [:word:] (n, i)
\px [:xdigit:] (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 (n, i)
\rh hardcopy buffer to FILENAME.ps (n, i)
\rs settings and hot keys (n, i)
\rt set xterm size (n, i)
\ro change output destination (n, i)
-- Load / Unload bash Support --------------------------
\lbs Load Bash Support (n, GUI only)
\ubs Unload Bash Support (n, GUI only)
File 'bash-hot-keys.pdf' contains a reference card for these key mappings.
Multiline inserts and code snippets will be indented after insertion.
The hot keys are defined in the file type plugin 'sh.vim' (part of this
bash-support plugin package).
Changing the default map leader '\'
The map leader can be changed by the user by setting a global variable in the file .vimrc let 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'.
3. HOT KEYS bashsupport-hotkeys
The following hot keys are defined in NORMAL, VISUAL and INSERT MODE:
Shift-F1 display help for this plugin
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
README.bashsupport Release notes, installation description.
ftplugin/sh.vim The filetype plugin. Defines hotkeys and more.
plugin/bash-support.vim The bash plugin 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|).
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/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/doc/* Hotkey reference card (PDF), changelog.
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_TemplateOverriddenMsg 'no'
g:BASH_Ctrl_j 'on'
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_Root 'B&ash.'
g:BASH_MenuHeader 'yes'
g:BASH_GuiSnippetBrowser 'gui'
g:BASH_GuiTemplateBrowser '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_BASH $SHELL (Linux/U**X)
'bash.exe' (Windows)
g:BASH_Man '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-tempfiles|).
g:BASH_GlobalTemplateFile : sets the global template file (see|bashsupport-templates|)
g:BASH_LocalTemplateFile : sets the local template file (see|bashsupport-templates|)
g:BASH_TemplateOverriddenMsg : message if a template is overridden
g:BASH_Ctrl_j : hotkey Ctrl-j 'on'/'off' (see|bashsupport-ad-mappings|)
2. group: g:BASH_CodeSnippets : The name of the code snippet directory
(see |bashsupport-stat-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_Root : The name of the root menu entry of this plugin
(see |bashsupport-custom-root|).
g:BASH_MenuHeader : Switch submenu titles on/off.
g:BASH_GuiSnippetBrowser : code snippet browser: 'gui', 'commandline'
g:BASH_GuiTemplateBrowser : code template browser: 'gui', 'explorer', '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 description comment for new files
g:BASH_BASH : the shell used
g:BASH_Man : 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 : add filename pattern to be considered as Bash file,
e.g. '.SlackBuild rc.' (separate with whitespaces)
To override the defaults add appropriate assignments in '.vimrc'.
This plugin sets the global variable is_bash:
let is_bash = 1
This assignment is necessary to avoid a wrong syntax highlighting for $(..) and
$((..)).
4.3 THE ROOT MENU bashsupport-custom-root
The variable g:BASH_Root, 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
'B&ash.'
Note the terminating dot.
If you want to set the plugin root menu into another menu, e.g. 'Plugin',
this is done by the following line in '.vimrc'
let g:BASH_Root = "&Plugin.B&ash."
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/doc SPECIAL CASES. Some Linux distributions use non-standard names for Vim directories. SUSE has a directory '/usr/share/vim/site' to put plugins in. These directories will not be found automatically. After installing the plugin 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 *** : The plugin tries to create a minimal template file 'Templates' (and the necessary directory '~/.vim/bash-support/templates') when the first buffer with filetype 'sh' will be opened. You should edit this file to personalize some templates, e.g. |AUTHOR| = Your Name |AUTHORREF| = YN |EMAIL| = ... |ORGANIZATION| = ... |COPYRIGHT| = ... You can also have local templates which override the global ones. To see a messages in this case set a global variable in '~/.vimrc' (Windows: '~\_vimrc'): let g:BASH_TemplateOverriddenMsg= 'yes' The default is 'no'. Create your private snippet directory: mkdir --parents ~/.vim/bash-support/codesnippets You may want to copy the snippets coming with this plugin (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-tempplates
5.1 TEMPLATE FILES bashsupport-templates-files
Nearly all menu entries 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 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 starts with a macro section followed by templates for
single menu items or better by including other template files grouping the
templates according to the menu structure of this plugin. The master file
could look like this:
§
§ =============================================================
§ ========== USER MACROS ======================================
§ =============================================================
§
|AUTHOR| = Dr. Fritz Mehner
|AUTHORREF| = mn
|EMAIL| = mehner.fritz@web.de
|COMPANY| = FH Südwestfalen, Iserlohn
|COPYRIGHT| = Copyright (c)|YEAR|,|AUTHOR|
§
§ =============================================================
§ ========== FILE INCLUDES ====================================
§ =============================================================
§
§ -- none --
§
§
§%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
== comment.end-of-line-comment == append ==
# <CURSOR>
§%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
... lot of other templates ...
Lines starting with a paragraph sign are comments. The section starting
with |AUTHOR| assigns values to predefined tags
(see|bashsupport-templates-macros|) to personalize some templates. Other
predefined tags with given default values can be used (e.g. |YEAR| ).
User defined tags are possible. They have the following syntax:
|macroname| = replacement
A macroname starts with a letter (uppercase or lowercase) followed by zero or
more letters, digits or underscores.
5.2 MACROS bashsupport-templates-macros
The following macro names are predefined. The first group is used to personalize templates.
PREDEFINED MACROS DEFAULT VALUE
|AUTHOR| ""
|AUTHORREF| ""
|EMAIL| ""
|COMPANY| ""
|LICENSE| ""
|ORGANIZATION| ""
|PROJECT| ""
|COPYRIGHTHOLDER| ""
|STYLE| ""
|includefile| ""
|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
|includefile| can be used to include an additional template file. A file
will be included only once. Commenting and uncommenting include macros is a
simple way to switch between several sets of templates. Overwriting existing
macros and templates is possible.
PREDEFINED TAGS
<CURSOR>The cursor position after insertion of a template<+text+>,<-text->, Jump targets in templates. Jump with Ctrl-j.{+text+},{-text-}See |bashsupport-templates-jump|.<SPLIT>The split point when inserting in visual mode (see|bashsupport-templates-definition|) A dependent template file can start with its own macro section. There is no need to have all user defined macros in the master file. When the first template definition is found (see below) macro definitions are no longer recognized.
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 global variables in
~/.vimrc , e.g.
let g:BASH_FormatDate = '%D'
let g:BASH_FormatTime = '%H:%M'
let g:BASH_FormatYear = 'year %Y'
5.3 TEMPLATES bashsupport-templates-names
5.3.1 Template names
The template behind a menu entry is identified by a given name. The first part
of the name identifies the menu, the second part identifies the item. The
modes are also hard coded (see|bashsupport-templates-definition|for the use of
<SPLIT>).
TEMPLATE NAME MODES
comment.end-of-line-comment normal, insert, visual comment.frame normal, insert comment.function normal, insert comment.file-description normal, insert comment.keyword-bug normal, insert comment.keyword-keyword normal, insert comment.keyword-todo normal, insert comment.keyword-tricky normal, insert comment.keyword-warning normal, insert comment.keyword-workaround normal, insert comment.file-sections-globals normal, insert comment.file-sections-cmdline normal, insert comment.file-sections-sanchecks normal, insert comment.file-sections-functdef normal, insert comment.file-sections-mainscript normal, insert comment.file-sections-statistics normal, insert statements.case normal, insert statements.elif normal, insert statements.for-in normal, insert, visual statements.for normal, insert, visual statements.if normal, insert, visual statements.if-else normal, insert, visual statements.select normal, insert, visual statements.until normal, insert, visual statements.while normal, insert, visual statements.function normal, insert, visual statements.echo normal, insert, visual statements.printf normal, insert, visual paramsub.substitution normal, insert, visual paramsub.use-default-value normal, insert paramsub.assign-default-value normal, insert paramsub.display-error normal, insert paramsub.use-alternate-value normal, insert paramsub.substring-expansion normal, insert paramsub.names-matching-prefix normal, insert paramsub.indirect-parameter-expansion normal, insert paramsub.parameter-length normal, insert paramsub.remove-matching-prefix-pattern normal, insert paramsub.remove-all-matching-prefix-pattern normal, insert paramsub.remove-matching-suffix-pattern normal, insert paramsub.remove-all-matching-suffix-pattern normal, insert paramsub.pattern-substitution normal, insert paramsub.pattern-substitution-all normal, insert paramsub.pattern-substitution-begin normal, insert paramsub.pattern-substitution-end normal, insert paramsub.first-lower-to-upper normal, insert paramsub.all-lower-to-upper normal, insert paramsub.first-upper-to-lower normal, insert paramsub.all-upper-to-lower normal, insert 5.3.2 Template definition bashsupport-templates-definition A template definition starts with a template head line with the following syntax: == templatename == [ position == ] The templatename is one of the above template identifiers. The position attribute is optional. Possible attribute values are: above insert the template before the current line append append the template to the current line below insert the template below the current line (default) insert insert the template at the cursor position start insert the template before the first line of the buffer An example: == comment.frame == #--------------------------------------------------------------------------- #<CURSOR>#--------------------------------------------------------------------------- The definition of a template ends at the next head line or at the end of the file. Templates for the visual mode can use<SPLIT>. The text before<SPLIT>will than be inserted above the marked area, the text after<SPLIT>will be inserted behind the marked area. An example: == statements.if-else == if<CURSOR>; then<SPLIT>else fi If applied to the marked block xxxxxxxxxxx xxxxxxxxxxx this template yields if ; then xxxxxxxxxxx xxxxxxxxxxx else fi The templates with a visual mode are shown in the table under |bashsupport-templates-names|. 5.3.3 Template expansion bashsupport-templates-expansion There are additional ways to control the expansion of a template. USER INPUT
If the usage of a yet undefined user macro starts with a question mark the
user will be asked for the replacement first, e.g. with the following template
== statements.function ==
|?FUNCTION_NAME| ()
{
<CURSOR><SPLIT>
} # ---------- end of function|FUNCTION_NAME| ----------
The user can specify the function name which then will be applied twice. If
the macro was already in use the old value will be suggested as default.
MACRO MANIPULATION
A macro expansion can be controlled by the following attributes :l change macro text to lowercase :u change macro text to uppercase :c capitalize macro text :L legalize name Legalization means: - replace all whitespaces by underscores - replace all non-word characters by underscores - replace '+' and '-' by underscore The keyword comment template is an example for the use of ':u' : == comment.keyword-keyword == append == # :|?KEYWORD:u| :|DATE| |TIME| :|AUTHORREF| :<CURSOR>The user specified keyword will be used in uppercase. 5.3.4 The macros<+text+>etc. bashsupport-templates-jump There are four macro 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. The text inside the brackets is userdefined and can be empty. The text can be composed from letters (uppercase and lowercase), digits, underscores and blanks. After the insertion of an template these jump targets will be highlighted. 5.3.5 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 == if<CURSOR>; then<SPLIT><-IF PART->else<+ELSE PART+>fi The 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. How to switch the mapping for Ctrl-j off
The original meaning of Ctrl-j is 'move [n] lines downward' (see |CTRL-j|).
If you are accustomed to use the default and don't like these jump targets you
can switch them off. Put the following line in the file '.vimrc' :
let g:BASH_Ctrl_j = 'off'
The default value of g:BASH_Ctrl_j is 'on'. You do not have to change the
template files. All jump targets will be removed before a template will be
inserted.
5.4 SWITCHING BETWEEN TEMPLATE SETS bashsupport-templates-sets
This plugin comes with a set of templates. These templates are suggestions. If one set is enough just edit these files to meet your needs if necessary. That's all. If you want to have additional sets for different projects use following method. To facilitate switching use the macro|STYLE| (|bashsupport-templates-files|) to define a unique name and the IF-ENDIF-construct to choose a particular set usually in the main templates file '~/.vim/bash-support/templates/Templates', for example: ... |STYLE| = my_style § § ============================================================= § ========== FILE INCLUDES ==================================== § ============================================================= § == IF |STYLE| IS generic == § |includefile| = bash.comments.template == ENDIF == § == IF |STYLE| IS my_style == |includefile| = my_comments.template == ENDIF == § |includefile| = bash.statements.template |includefile| = bash.paramsub.template § ... The syntax is as follows: == IF macro_name IS macro_value == == ENDIF == IF, IS, and ENDIF are keywords. All files will be read in. Use differnt filenames. Use the macro|STYLE| to define the style which shall be used when opening a new file. The number of styles is not limited. There should be at least one complete set of templates of course.
Switching between template sets
If there is more than one style switching can be done with the hotkey \nts or with the Ex command ':BashStyle '. Use tab expansion to choose one of the existing styles.
5.5 ADDITIONAL FILENAMES WITH FILETYPE 'sh' bashsupport-also-bash
The standard extension for shell script files used by this plugin 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 = [ '.sh', '.SlackBuild' , 'rc.*' ]
This is a Vim List. Please quote the entries and separate them with commas.
Start the list with the default extension '*.sh'.
You can relate each pattern with an existing style (|bashsupport-templates-sets|)
using a Vim Dictionary instead:
let g:BASH_AlsoBash = { '.sh' : 'default' , '.SlackBuild' : 'style1' , 'rc.*' : 'sytle2' }
The entries are pairs of the form 'PATTERN' : 'STYLE' . The pairs are
separated by commas. Please note that a Dictionary is enclosed in curly
braces. Start the list with the default pair '*.sh' : 'default' (the name of
the default style is 'default'). The given style will be set automatically
when switching to a buffer or opening a new buffer with the attached filename
pattern and supersedes the macro |STYLE| .
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.list
If 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. Note the 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 feature CTRL-X, CTRL-K (and CTRL-P, CTRL-N).
7. ADDITIONAL MAPPINGS bashsupport-ad-mappings
Ctrl-j
Ctrl-j can be used to jump behind closing brackets, parenthesis, braces, or
string terminators ('"`). This feature is limited to the current line. Ctrl-j
does not jump behind the last character in a line.
How to switch the mapping for Ctrl-j off
The original meaning of Ctrl-j is 'move [n] lines downward' (see |CTRL-j|).
If you are accustomed to use the deafult and don't like these jump targets you
can switch them off. Put the following line in the file .vimrc :
let g:BASH_Ctrl_j = 'off'
The default value of g:BASH_Ctrl_j is 'on'.
Quote WORDS in normal mode
Put single or double quotes around a WORD (non-whitespaces) using '' or "". In normal mode the WORD ${infiles}will be quoted as "${infiles}" using "" if the cursor is anywhere inside this WORD. The command '' masks the normal mode command '' (jump to the position before the latest jump).
8. WINDOWS PARTICULARITIES bashsupport-windows
For a user installation the plugin 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 $VIM or :echo $HOME The configuration files for a user are $HOME/_vimrc and $HOME/_gvimrc for the system $VIM/_vimrc and $VIM/_gvimrc A Bash shell is not a part of a Windows system and has to be installed in addition. This plugin 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_BASH = 'xyz-shell.exe' The run-menu and the corresponding hotkeys are restricted. Please see the document 'bash-hot-keys.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 plugin files must be enabled. If not use
:filetype plugin on
This 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 plugins are enabled. If not, add the line
filetype plugin on
to 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 file 'README.bashsupport'.
vim:tw=78:noet:ts=2:ft=help:norl:
Generated by vim2html on Sa 5. Jan 10:55:20 CET 2013