BASHSUPPORT

bashsupport.txt                Bash Support                February 13 2009

bash Support                                      bash-support bashsupport
                            Plugin version 3.1.1
                        for Vim version 7.0 and above
                       Fritz Mehner  <mehner@fh-swf.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    Command line arguments                 |bashsupport-cmdline-args|
 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|
 4.5     Non-standard installation               |bashsupport-non-standard|
 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.     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 entry 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. The nontrivial of
these stuff is taken from template files and can be changed by the user to
meet his 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 Command line arguments                        bashsupport-cmdline-args

The entry 'com. 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' 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 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:C_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:C_Printheader = "%<%f%h%m%<  %=%{strftime('%x %X')}     SEITE %N"

See :h printheader and :h strftime()  for more details.


1.7.7 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.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 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 is active.

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.

  Legend:  (i) insert mode, (n) normal mode, (v) visual mode

  -- 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.
  \hp     Displays the Vim help page for  (n, i)
          this plugin.

  -- Comments -------------------------------------------

  \cl     line end comment                (n, i, v)
  \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)
  \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)
  \cv     vim modeline                    (n, i)

  -- Statements ------------------------------------------

  \sc     case in ... esac                (n, i)
  \sl     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)
  \st     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)

  -- Snippets - ------------------------------------------

  \nr     read code snippet               (n)
  \nw     write code snippet              (n, v)
  \ne     edit code snippet               (n)

  \ntl    edit local templates            (n)
  \ntg    edit global templates           (n)
  \ntr    reread the templates            (n)
  \nts    switch template style           (n)

  -- 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 -------------------------------------------------

  \rr     update file, run script         (n, i)
  \rc     update file, check syntax       (n, i)
  \rco    syntax check options            (n, i)
  \ra     set command line arguments      (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_TemplateOverwrittenMsg  'yes'
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_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_BASH                    $SHELL         (Linux/U**X)
                               'win-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_TemplateOverwrittenMsg : message if a template is overwritten
           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_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_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. A single root menu entry is appropriate if the
screen is limited or several plugins are in use.

If g:BASH_Root is set to "", this single root menu entry will not appear.  Put
the following line in '.vimrc'

  let g:BASH_Root = ""

Now all submenus are put into the gVim root menu. Nice for a
Bash-only-programmer and Bash courses.

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/vim72' if Vim version 7.2 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


As *** USER *** :

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.


4.5  Non-standard installation                      bashsupport-non-standard

The place to install this plugin package is the directory "$HOME/.vim".  For
convenience the directory tree "$HOME/.vim/bash-support/..." can be moved to
another place. In this case the new base directory has to be specified in
"$HOME/.vimrc", e.g.

 let g:BASH_Support_Root_Dir  = "/home/lastname/xyz"

Please note that there is no trailing slash.


5.  TEMPLATE FILES AND TAGS                           bashsupport-tempplates


5.1  TEMPLATE FILES                              bashsupport-templates-files

Nearly all menu entries insert code snippets or comments. A part of this stuff
is taken from template files and can be changed by the user to meet his
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@fh-swf.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|         ""
|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

 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

The plugin should go into the directory structure below the local
installation directory $HOME/.vim/ for LINUX/UNIX and $VIM/vimfiles/ for
Windows. The values of the two variables can be found from inside Vim:
   :echo $VIM
or
   :echo $HOME

Configuration files:

  LINUX/UNIX :   $HOME/.vimrc  and  $HOME/.gvimrc
  Windows    :   $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 win-bash.exe
(http://win-bash.sourceforge.net/) and the 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.


9.  Release Notes                                  bashsupport-release-notes

See file 'README.bashsupport'.


vim:tw=78:noet:ts=2:ft=help:norl:

Generated by vim2html on Sa 13. Feb 18:48:15 CET 2010