vim: add extline plugin

Allows easy over/under-lining text, useful mainly for ReST.

Imported directly, since it has no history to speak of.

4 files changed, 522 insertions, 0 deletions

diff --git a/vim/extline/README.rst b/vim/extline/README.rst
new file mode 100644
index 0000000..470d81c
--- /dev/null
+++ b/vim/extline/README.rst
@@ -0,0 +1,50 @@
+**************************************************************
+Extline - plugin for extending lines (e.g., underlined titles)
+**************************************************************
+
+When writing titles in a plain text document, a common convention is to use
+repeated punctuation characters to draw lines under (and sometimes over) the
+title text.  This plugin helps maintain those title lines more easily, and
+it provides support for standalone horizontal lines as well.
+
+Titles are marked up in a manner compatible with reStructuredText[1], and the
+various heading levels are chosen to coincide with the Sphinx[2] project's
+conventions as follows::
+
+    ##############
+    Part (level 9)
+    ##############
+
+    *****************
+    Chapter (level 0)
+    *****************
+
+    Section (level 1)
+    =================
+
+    Subsection (level 2)
+    --------------------
+
+    Subsubsection (level 3)
+    ^^^^^^^^^^^^^^^^^^^^^^^
+
+    Paragraph (level 4)
+    """""""""""""""""""
+
+    Level-5 heading
+    '''''''''''''''
+
+Extline provides methods for adding these lines, adjusting them to fit as the
+section names changes, and for converting one level to another.
+
+[1]: http://docutils.sourceforge.net/rst.html
+[2]: http://sphinx-doc.org/
+
+See documentation in doc/extline.txt for installation, customization, and
+usage instructions.
+
+Developed by Michael Henry (vim at drmikehenry.com).
+
+Distributed under Vim's license.
+
+Git repository:   https://github.com/drmikehenry/vim-extline
diff --git a/vim/extline/autoload/extline.vim b/vim/extline/autoload/extline.vim
new file mode 100644
index 0000000..ea9ec1a
--- /dev/null
+++ b/vim/extline/autoload/extline.vim
@@ -0,0 +1,195 @@
+" Autoloads for Vim extline plugin.
+
+if exists("g:autoloaded_extline")
+    finish
+endif
+let g:autoloaded_extline = 1
+
+" Save 'cpoptions' and set Vim default to enable line continuations.
+let s:save_cpoptions = &cpoptions
+set cpoptions&vim
+
+function! extline#lstrip(s)
+    return substitute(a:s, '^\s*', '', '')
+endfunction
+
+function! extline#rstrip(s)
+    return substitute(a:s, '\s*$', '', '')
+endfunction
+
+function! extline#strip(s)
+    return extline#lstrip(extline#rstrip(a:s))
+endfunction
+
+function! extline#leadingWhitespace(s)
+    return substitute(a:s, '^\s*\zs\(.*\)$', '', '')
+endfunction
+
+function! extline#getMonochar(s)
+    let monochar = substitute(extline#strip(a:s), '^\(\S\)\1*$', '\1', '')
+    if len(monochar) > 1
+        let monochar = ''
+    endif
+    return monochar
+endfunction
+
+" Return monochar that is non-alphanumeric.
+function! extline#getPuncMonochar(s)
+    let monochar = extline#getMonochar(a:s)
+    if match(monochar, '[:alnum:]') >= 0
+        let monochar = ''
+    endif
+    return monochar
+endfunction
+
+function! extline#firstNonEmpty(strings)
+    for s in a:strings
+        if s != ''
+            return s
+        endif
+    endfor
+    return a:strings[0]
+endfunction
+
+function! extline#probeTitle(titleLineNum)
+    let titleText = getline(a:titleLineNum)
+    let title = extline#strip(titleText)
+    let titlePrefix = extline#leadingWhitespace(titleText)
+    if extline#getPuncMonochar(title) != ''
+        " Title cannot be a line of monochar punctuation characters.
+        let title = ''
+    endif
+    " Title Group
+    let tg = {
+                \ 'titleLineNum': a:titleLineNum,
+                \ 'title': title,
+                \ 'titlePrefix': titlePrefix,
+                \ 'overChar': '',
+                \ 'underChar': '',
+                \ }
+
+    if title != ''
+        " Consider non-existing line numbers.
+        let overText = extline#strip(getline(a:titleLineNum - 1))
+        let underText = extline#strip(getline(a:titleLineNum + 1))
+        let tg['overChar'] = extline#getPuncMonochar(overText)
+        let tg['underChar'] = extline#getPuncMonochar(underText)
+    endif
+    return tg
+endfunction
+
+function! extline#probeTitleNearby()
+    let lineNum = line('.')
+    let text = extline#strip(getline(lineNum))
+    let monochar = extline#getPuncMonochar(text)
+    if text == '' || monochar != ''
+        let tg = extline#probeTitle(lineNum - 1)
+        if tg['title'] == ''
+            let tg = extline#probeTitle(lineNum + 1)
+        endif
+    else
+        let tg = extline#probeTitle(lineNum)
+    endif
+    return tg
+endfunction
+
+function! extline#changeTitleLine(tg, lineType, lineTypePresent)
+    " lineType is 'over' or 'under'
+    " lineTypePresent is 1 or 0 to use or not use lineType.
+    let charType = a:lineType . 'Char'
+    if a:lineTypePresent && a:tg[charType] == ''
+        if charType == 'overChar'
+            let otherCharType = 'underChar'
+            exe a:tg['titleLineNum'] . 'copy ' . (a:tg['titleLineNum'] - 1)
+            let a:tg['titleLineNum'] = (a:tg['titleLineNum'] + 1)
+        else
+            let otherCharType = 'overChar'
+            exe a:tg['titleLineNum'] . 'copy ' . a:tg['titleLineNum']
+        endif
+        let a:tg[charType] = a:tg[otherCharType]
+        if a:tg[charType] == ''
+            let a:tg[charType] = '='
+        endif
+    endif
+    if !a:lineTypePresent && a:tg[charType] != ''
+        if charType == 'overChar'
+            exe (a:tg['titleLineNum'] - 1) . 'del'
+            let a:tg['titleLineNum'] = (a:tg['titleLineNum'] - 1)
+        else
+            exe (a:tg['titleLineNum'] + 1) . 'del'
+        endif
+        let a:tg[charType] = ''
+    endif
+endfunction
+
+function! extline#updateTitle(tg)
+    let titleLineNum = a:tg['titleLineNum']
+    let titleLen = len(a:tg['title'])
+    let underChar = a:tg['underChar']
+    let overChar = a:tg['overChar']
+    let titlePrefix = a:tg['titlePrefix']
+
+    if overChar != ''
+        let lineText = titlePrefix . repeat(overChar, titleLen)
+        exe (titleLineNum - 1) . 's/^.*/\=lineText/g'
+    endif
+    exe titleLineNum
+    normal! $
+    if underChar != ''
+        let lineText = titlePrefix . repeat(underChar, titleLen)
+        exe (titleLineNum + 1) . 's/^.*/\=lineText/g'
+        normal! $
+    endif
+endfunction
+
+function! extline#makeTitle(forceMonochar, useOver, useUnder)
+    let tg = extline#probeTitleNearby()
+    if tg['title'] != ''
+        " Always add a line before removing the other line.
+        if a:useOver
+            call extline#changeTitleLine(tg, 'over', a:useOver)
+            call extline#changeTitleLine(tg, 'under', a:useUnder)
+        else
+            call extline#changeTitleLine(tg, 'under', a:useUnder)
+            call extline#changeTitleLine(tg, 'over', a:useOver)
+        endif
+        if a:forceMonochar != ''
+            if a:useOver
+                let tg['overChar'] = a:forceMonochar
+            endif
+            if a:useUnder
+                let tg['underChar'] = a:forceMonochar
+            endif
+        endif
+        call extline#updateTitle(tg)
+    endif
+    return tg['title'] != ''
+endfunction
+
+function! extline#makeHline()
+    let lineNum = line('.')
+    let t = extline#rstrip(getline(lineNum))
+    let monochar = extline#getMonochar(t)
+    if monochar != ''
+        let lineText = (t . repeat(monochar, 80))[:77]
+        exe 's/^.*/' . escape(lineText, '/') . '/g'
+        normal! $
+    endif
+endfunction
+
+function! extline#autoTitle()
+    let tg = extline#probeTitleNearby()
+    if tg['title'] != ''
+        if tg['overChar'] == '' && tg['underChar'] == ''
+            if tg['titleLineNum'] > line(".")
+                " Title was after cursor line, use overTitle.
+                call extline#changeTitleLine(tg, 'over', 1)
+            else
+                call extline#changeTitleLine(tg, 'under', 1)
+            endif
+        endif
+        call extline#updateTitle(tg)
+    else
+        call extline#makeHline()
+    endif
+endfunction
diff --git a/vim/extline/doc/extline.txt b/vim/extline/doc/extline.txt
new file mode 100644
index 0000000..2ff2c70
--- /dev/null
+++ b/vim/extline/doc/extline.txt
@@ -0,0 +1,136 @@
+*extline.txt*      Plugin for extending lines (e.g., underlined titles)
+*extline*          Version 0.2.0
+
+==============================================================================
+1.  Introduction                                    |extline-intro|
+2.  Installation                                    |extline-installation|
+3.  Usage                                           |extline-usage|
+4.  Customization                                   |extline-customization|
+5.  ChangeLog                                       |extline-changelog|
+6.  Credits                                         |extline-credits|
+
+==============================================================================
+1.  Introduction                                    *extline-intro*
+
+When writing titles in a plain text document, a common convention is to use
+repeated punctuation characters to draw lines under (and sometimes over) the
+title text.  This plugin helps maintain those title lines more easily, and
+it provides support for standalone horizontal lines as well.
+
+Titles are marked up in a manner compatible with reStructuredText[1], and the
+various heading levels are chosen to coincide with the Sphinx[2] project's
+conventions as follows:
+
+    ##############
+    Part (level 9)
+    ##############
+
+    *****************
+    Chapter (level 0)
+    *****************
+
+    Section (level 1)
+    =================
+
+    Subsection (level 2)
+    --------------------
+
+    Subsubsection (level 3)
+    ^^^^^^^^^^^^^^^^^^^^^^^
+
+    Paragraph (level 4)
+    """""""""""""""""""
+
+    Level-5 heading
+    '''''''''''''''
+
+Extline provides methods for adding these lines, adjusting them to fit as the
+section names changes, and for converting one level to another.
+
+[1]: http://docutils.sourceforge.net/rst.html
+[2]: http://sphinx-doc.org/
+
+===============================================================================
+2.  Installation                                    *extline-installation*
+
+Unzip the downloaded file in your personal |vimfiles| directory (~/.vim under
+unix or %HOMEPATH%\vimfiles under windows).  The following files will
+be unpacked: >
+
+  doc/extline.txt
+  plugin/extline.vim
+
+Finally, re-generate your help tags with the |:helptags| command, e.g.: >
+
+  :helptags ~/.vim/doc
+
+==============================================================================
+3.  Usage                                           *extline-usage*
+
+The following mappings apply in Visual and Insert modes (but, notably, NOT in
+Normal mode):
+
+CTRL-L CTRL-L     Auto-line update
+CTRL-L CTRL-H     Horizontal line update
+CTRL-L CTRL-U     Change to underlined title
+CTRL-L CTRL-O     Change to overlined title
+CTRL-L CTRL-I     Change to underlined and overlined title
+
+CTRL-L =          Force Section heading (level 1)
+CTRL-L 1
+CTRL-L -          Force Subsection heading (level 2)
+CTRL-L 2
+CTRL-L ^          Force Subsubsection heading (level 3)
+CTRL-L 3
+CTRL-L "          Force Paragraph heading (level 4)
+CTRL-L 4
+CTRL-L '          Force level 5 heading (level 5)
+CTRL-L 5
+
+To insert a literal CTRL-L in Insert mode, use CTRL-V CTRL-L (or CTRL-Q CTRL-L
+if CTRL-V has been remapped as happens on Windows by default).
+
+Because Normal-mode CTRL-L already serves a useful function (redrawing the
+screen), extline does not create Normal-mode mappings.  To invoke from Normal
+mode, it's convenient to first enter blockwise Visual mode via CTRL-V (or
+CTRL-Q on Windows), then press CTRL-L CTRL-L (for example) to invoke the
+desired mapping from Visual mode.
+
+Each of the "change to xxx title" commands will convert an existing title to
+the desired format.
+
+The "horizontal line update" command will update an existing horizontal line
+of punctuation characters to reach column 78.
+
+The "auto-line update" command will update an existing title or horizontal.
+
+If a title has no pre-existing underline or overline, by default a Section
+heading will be used with a row of equals signs as an underline.
+
+===============================================================================
+4.  Customization                                   *extline-customization*
+
+At present, nothing is conveniently customizable.
+
+===============================================================================
+5.  ChangeLog                                       |extline-changelog|
+
+Version 0.2.0    Date    2013-10-03                 *extline-changelog-0.2.0*
+
+  - Partition into plugin and autoload components.
+
+  - Reorganize documentation.
+
+  - First public release.
+
+===============================================================================
+6.  Credits                                         *extline-credits*
+
+Developed by Michael Henry (vim at drmikehenry.com).
+
+Distributed under Vim's |license|.
+
+Git repository:       https://github.com/drmikehenry/vim-extline
+
+===============================================================================
+vim:sts=2:et:ai:tw=78:fo=tcq2:ft=help:spell:
diff --git a/vim/extline/plugin/extline.vim b/vim/extline/plugin/extline.vim
new file mode 100644
index 0000000..4eea793
--- /dev/null
+++ b/vim/extline/plugin/extline.vim
@@ -0,0 +1,141 @@
+" Vim global plugin for extending lines (e.g., underlined titles).
+
+if exists('g:loaded_extline')
+    finish
+endif
+let g:loaded_extline = 1
+
+" Save 'cpoptions' and set Vim default to enable line continuations.
+let s:save_cpoptions = &cpoptions
+set cpoptions&vim
+
+xnoremap <silent> <C-L><C-L>  <ESC>:call extline#autoTitle()<CR>^
+inoremap <silent> <C-L><C-L>  <C-G>u<C-O>:call extline#autoTitle()<CR>
+xnoremap <silent> <C-L><C-H>  <ESC>:call extline#makeHline()<CR>^
+inoremap <silent> <C-L><C-H>  <C-G>u<C-O>:call extline#makeHline()<CR>
+
+xnoremap <silent> <C-L><C-U>  <ESC>:call extline#makeTitle("",  0, 1)<CR>^
+xnoremap <silent> <C-L><C-O>  <ESC>:call extline#makeTitle("",  1, 0)<CR>^
+xnoremap <silent> <C-L><C-I>  <ESC>:call extline#makeTitle("",  1, 1)<CR>^
+xnoremap <silent> <C-L>1      <ESC>:call extline#makeTitle("=", 0, 1)<CR>^
+xnoremap <silent> <C-L>=      <ESC>:call extline#makeTitle("=", 0, 1)<CR>^
+xnoremap <silent> <C-L>2      <ESC>:call extline#makeTitle("-", 0, 1)<CR>^
+xnoremap <silent> <C-L>-      <ESC>:call extline#makeTitle("-", 0, 1)<CR>^
+xnoremap <silent> <C-L>3      <ESC>:call extline#makeTitle("^", 0, 1)<CR>^
+xnoremap <silent> <C-L>^      <ESC>:call extline#makeTitle("^", 0, 1)<CR>^
+xnoremap <silent> <C-L>4      <ESC>:call extline#makeTitle('"', 0, 1)<CR>^
+xnoremap <silent> <C-L>"      <ESC>:call extline#makeTitle('"', 0, 1)<CR>^
+xnoremap <silent> <C-L>5      <ESC>:call extline#makeTitle("'", 0, 1)<CR>^
+xnoremap <silent> <C-L>'      <ESC>:call extline#makeTitle("'", 0, 1)<CR>^
+xnoremap <silent> <C-L>9      <ESC>:call extline#makeTitle("#", 1, 1)<CR>^
+xnoremap <silent> <C-L>#      <ESC>:call extline#makeTitle("#", 1, 1)<CR>^
+xnoremap <silent> <C-L>0      <ESC>:call extline#makeTitle("*", 1, 1)<CR>^
+xnoremap <silent> <C-L>*      <ESC>:call extline#makeTitle("*", 1, 1)<CR>^
+
+" Undo-break via CTRL-G u.
+inoremap <silent> <C-L><C-I>  <C-G>u<C-O>:call extline#makeTitle("",  1, 1)<CR>
+inoremap <silent> <C-L><C-O>  <C-G>u<C-O>:call extline#makeTitle("",  1, 0)<CR>
+inoremap <silent> <C-L><C-U>  <C-G>u<C-O>:call extline#makeTitle("",  0, 1)<CR>
+inoremap <silent> <C-L>1      <C-G>u<C-O>:call extline#makeTitle("=", 0, 1)<CR>
+inoremap <silent> <C-L>=      <C-G>u<C-O>:call extline#makeTitle("=", 0, 1)<CR>
+inoremap <silent> <C-L>2      <C-G>u<C-O>:call extline#makeTitle("-", 0, 1)<CR>
+inoremap <silent> <C-L>-      <C-G>u<C-O>:call extline#makeTitle("-", 0, 1)<CR>
+inoremap <silent> <C-L>3      <C-G>u<C-O>:call extline#makeTitle("^", 0, 1)<CR>
+inoremap <silent> <C-L>^      <C-G>u<C-O>:call extline#makeTitle("^", 0, 1)<CR>
+inoremap <silent> <C-L>4      <C-G>u<C-O>:call extline#makeTitle('"', 0, 1)<CR>
+inoremap <silent> <C-L>"      <C-G>u<C-O>:call extline#makeTitle('"', 0, 1)<CR>
+inoremap <silent> <C-L>5      <C-G>u<C-O>:call extline#makeTitle("'", 0, 1)<CR>
+inoremap <silent> <C-L>'      <C-G>u<C-O>:call extline#makeTitle("'", 0, 1)<CR>
+inoremap <silent> <C-L>9      <C-G>u<C-O>:call extline#makeTitle("#", 1, 1)<CR>
+inoremap <silent> <C-L>#      <C-G>u<C-O>:call extline#makeTitle("#", 1, 1)<CR>
+inoremap <silent> <C-L>0      <C-G>u<C-O>:call extline#makeTitle("*", 1, 1)<CR>
+inoremap <silent> <C-L>*      <C-G>u<C-O>:call extline#makeTitle("*", 1, 1)<CR>
+
+" Restore saved 'cpoptions'.
+let &cpoptions = s:save_cpoptions
+
+finish
+
+" ----------------------------------------------------------------------------
+
+
+Types of single lines of text
+-----------------------------
+
+- Monoline:
+
+  - Start of line
+  - Optional leading whitespace
+  - One or more identical non-alphanumeric non-white characters, c
+  - Optional trailing whitespace
+  - End of line
+
+- Genline:
+    prefix <longest run of characters> postfix
+
+    postfix might contain optional column number
+
+  - Start of line
+  - Optional leading whitespace
+  - Optional prefix with final character, L
+  - One or more identical non-white characters, c, with c != L
+  - Optional suffix with first character, R, with R != c
+  - Optional white (ignored)
+  - Optional integer column number
+  --------------------------------
+
+- Title:
+
+  - Non-blank
+
+Title types
+-----------
+
+- NoTitle:
+
+
+- BareTitle::
+
+
+    Title
+
+
+- UnderTitle::
+
+
+    Title
+    =====
+
+
+- OverTitle::
+
+
+    =====
+    Title
+
+
+- OverUnderTitle::
+
+
+    =====
+    Title
+    =====
+
+
+HLine types
+-----------
+
+    =============================
+
+    /****************************
+
+    ****************************/
+
+    /***************************/
+
+    # ---------------------------
+    # --------------------------- #
+
+
+
+" vim: sts=4 sw=4 tw=80 et ai: