Updated the help file to reflect the latest changes

README.markdown

@@ -1,15 +1,17 @@
 # Indent Guides
-Indent Guides is a plugin for visually displaying indent levels in vim.
+Indent Guides is a plugin for visually displaying indent levels in Vim.
 
 ## Features:
 * Can detect both tab and space indent styles.
-* Automatically inspects your colorscheme and picks appropriate colors (gvim only).
+* Automatically inspects your colorscheme and picks appropriate colors (gVim only).
 * Will highlight indent levels with alternating colors.
-* Full support for gvim and basic support for terminal vim.
-* Seems to work on Windows gvim 7.3 (haven't done any extensive tests though).
+* Full support for gVim and basic support for Terminal Vim.
+* Seems to work on Windows gVim 7.3 (haven't done any extensive tests though).
+* **NEW:** Customizable size for indent guides, eg. skinny guides (soft-tabs only).
+* **NEW:** Customizable start indent level.
 
 ## Requirements
-* vim 7.2+
+* Vim 7.2+
 
 ## Installation
 To install the plugin just copy `autoload`, `plugin`, `doc` directories into your `.vim` directory.
@@ -22,8 +24,11 @@ Alternatively if you have [Pathogen](http://www.vim.org/scripts/script.php?scrip
 ## Usage
 The default mapping to toggle the plugin is `<Leader>ig`
 
+### gVim
+**This plugin should work with gVim out of the box, no configuration needed.** It will automatically inspect your colorscheme and pick appropriate colors.
+
 ### Setting custom indent colors
-Here's an example of how to define custom colors instead using of the ones the plugin automatically generates for you. Add this to your `.vimrc` file:
+Here's an example of how to define custom colors instead of using the ones the plugin automatically generates for you. Add this to your `.vimrc` file:
 
     let g:indent_guides_auto_colors = 0
     autocmd VimEnter,Colorscheme * :hi IndentGuidesOdd  guibg=red   ctermbg=3
@@ -53,8 +58,8 @@ Alternatively you can manually setup the highlight colors yourself, see `:help i
 `:help indent-guides`
 
 ## Screenshots
-<img src="https://dl.dropbox.com/u/1019520/vim-indent-guides/rdark.png" width="400" height="400" alt="Indent Guides screenshot: rdark" />
-<img src="https://dl.dropbox.com/u/1019520/vim-indent-guides/bclear.png" width="400" height="400" alt="Indent Guides screenshot: bclear" />
-<img src="https://dl.dropbox.com/u/1019520/vim-indent-guides/clarity.png" width="400" height="400" alt="Indent Guides screenshot: clarity" />
-<img src="https://dl.dropbox.com/u/1019520/vim-indent-guides/moss.png" width="400" height="400" alt="Indent Guides screenshot: moss" />
+<img src="http://i.imgur.com/ONgoj.png" width="448" height="448" alt="" />
+<img src="http://i.imgur.com/7tMBl.png" width="448" height="448" alt="" />
+<img src="http://i.imgur.com/EvrqK.png" width="448" height="448" alt="" />
+<img src="http://i.imgur.com/hHqp2.png" width="448" height="448" alt="" />
 

autoload/color_helper.vim

@@ -39,7 +39,7 @@ endfunction
 function! color_helper#hex_color_to_rgb(hex_color)
   let l:rgb = []
 
-  if a:hex_color =~ g:indent_guides_hex_color_pattern
+  if a:hex_color =~ g:indent_guides_color_hex_pattern
     let l:red   = color_helper#hex_to_dec(strpart(a:hex_color, 1, 2))
     let l:green = color_helper#hex_to_dec(strpart(a:hex_color, 3, 2))
     let l:blue  = color_helper#hex_to_dec(strpart(a:hex_color, 5, 2))

autoload/indent_guides.vim

@@ -32,16 +32,17 @@ endfunction
 "
 function! indent_guides#enable()
   let g:indent_guides_autocmds_enabled = 1
+
+  call indent_guides#init_script_vars()
   call indent_guides#highlight_colors()
   call indent_guides#clear_matches()
 
   " loop through each indent level and define a highlight pattern
   " will automagically figure out whether to use tabs or spaces
-  for l:level in range(1, g:indent_guides_indent_levels)
+  for l:level in range(s:start_level, s:indent_levels)
     let l:group      = 'IndentGuides' . ((l:level % 2 == 0) ? 'Even' : 'Odd')
-    let l:multiplier = (&l:expandtab == 1) ? &l:shiftwidth : 1
-    let l:pattern    = '^\s\{' . (l:level * l:multiplier - l:multiplier) . '\}\zs'
-    let l:pattern   .= '\s\{' . l:multiplier . '\}'
+    let l:pattern    = '^\s\{' . (l:level * s:indent_size - s:indent_size) . '\}\zs'
+    let l:pattern   .= '\s\{' . s:guide_size . '\}'
     let l:pattern   .= '\ze'
 
     " define the higlight pattern and add to list
@@ -77,27 +78,25 @@ endfunction
 " Automagically calculates and defines the indent highlight colors.
 "
 function! indent_guides#highlight_colors()
-  if g:indent_guides_auto_colors
+  if s:auto_colors
     if has('gui_running')
       call indent_guides#gui_highlight_colors()
     else
-      call indent_guides#cterm_highlight_colors()
+      call indent_guides#basic_highlight_colors()
     endif
   endif
 endfunction
 
 "
-" Defines the indent highlight colors for terminal vim.
+" Defines some basic indent highlight colors that work for Terminal Vim and
+" gVim when colors can't be automatically calculated.
 "
-" NOTE: This function contains no magic at the moment, it will simply use some
-" light or dark preset colors depending on the `set background=` value.
-"
-function! indent_guides#cterm_highlight_colors()
-  let l:colors = (&g:background == 'dark') ?
-    \ ['darkgrey', 'black'] : ['lightgrey', 'white']
+function! indent_guides#basic_highlight_colors()
+  let l:cterm_colors = (&g:background == 'dark') ? ['darkgrey', 'black'] : ['lightgrey', 'white']
+  let l:gui_colors   = (&g:background == 'dark') ? ['grey15', 'grey30']  : ['grey70', 'grey85']
 
-  exe 'hi IndentGuidesEven ctermbg=' . l:colors[0]
-  exe 'hi IndentGuidesOdd  ctermbg=' . l:colors[1]
+  exe 'hi IndentGuidesEven guibg=' . l:gui_colors[0] . ' ctermbg=' . l:cterm_colors[0]
+  exe 'hi IndentGuidesOdd  guibg=' . l:gui_colors[1] . ' ctermbg=' . l:cterm_colors[1]
 endfunction
 
 "
@@ -105,22 +104,24 @@ endfunction
 " vim.
 "
 function! indent_guides#gui_highlight_colors()
-  let l:hi_normal       = indent_guides#capture_highlight('Normal')
-  let l:hex_pattern     = 'guibg=\zs'. g:indent_guides_hex_color_pattern . '\ze'
-  let l:name_pattern    = "guibg='\\?\\zs[0-9A-Za-z ]\\+\\ze'\\?"
   let l:hi_normal_guibg = ''
 
   " capture the backgroud color from the normal highlight
-  if l:hi_normal =~ l:hex_pattern
+  if s:hi_normal =~ s:color_hex_bg_pat
     " hex color code is being used, eg. '#FFFFFF'
-    let l:hi_normal_guibg = matchstr(l:hi_normal, l:hex_pattern)
-  elseif l:hi_normal =~ l:name_pattern
+    let l:hi_normal_guibg = matchstr(s:hi_normal, s:color_hex_bg_pat)
+
+  elseif s:hi_normal =~ s:color_name_bg_pat
     " color name is being used, eg. 'white'
-    let l:color_name      = matchstr(l:hi_normal, l:name_pattern)
+    let l:color_name = matchstr(s:hi_normal, s:color_name_bg_pat)
     let l:hi_normal_guibg = color_helper#color_name_to_hex(l:color_name)
+
+  else
+    " background color could not be detected, default to basic colors
+    call indent_guides#basic_highlight_colors()
   endif
 
-  if l:hi_normal_guibg =~ g:indent_guides_hex_color_pattern
+  if l:hi_normal_guibg =~ s:color_hex_pat
     " calculate the highlight background colors
     let l:hi_odd_bg  = indent_guides#lighten_or_darken_color(l:hi_normal_guibg)
     let l:hi_even_bg = indent_guides#lighten_or_darken_color(l:hi_odd_bg)
@@ -136,15 +137,92 @@ endfunction
 " colorscheme is being used.
 "
 function! indent_guides#lighten_or_darken_color(color)
-  let l:percent = g:indent_guides_color_change_percent
+  let l:new_color = ''
 
-  let l:new_color = (&g:background == 'dark') ?
-    \ color_helper#hex_color_lighten(a:color, l:percent) :
-    \ color_helper#hex_color_darken (a:color, l:percent)
+  if (&g:background == 'dark')
+    let l:new_color = color_helper#hex_color_lighten(a:color, s:change_percent)
+  else
+    let l:new_color = color_helper#hex_color_darken (a:color, s:change_percent)
+  endif
 
   return l:new_color
 endfunction
 
+"
+" Define default highlights.
+"
+function! indent_guides#define_default_highlights()
+  exe 'hi IndentGuidesOdd  guibg=NONE ctermbg=NONE'
+  exe 'hi IndentGuidesEven guibg=NONE ctermbg=NONE'
+endfunction
+
+"
+" Init the w:indent_guides_matches variable.
+"
+function! indent_guides#init_matches()
+  let w:indent_guides_matches = exists('w:indent_guides_matches') ? w:indent_guides_matches : []
+endfunction
+
+"
+" We need to initialize these vars every time a buffer is entered while the
+" plugin is enabled.
+"
+function! indent_guides#init_script_vars()
+  let s:indent_size = indent_guides#get_indent_size()
+  let s:guide_size  = indent_guides#calculate_guide_size()
+  let s:hi_normal   = indent_guides#capture_highlight('Normal')
+
+  " shortcuts to the global variables - this makes the code easier to read
+  let s:debug             = g:indent_guides_debug
+  let s:indent_levels     = g:indent_guides_indent_levels
+  let s:auto_colors       = g:indent_guides_auto_colors
+  let s:change_percent    = g:indent_guides_color_change_percent / 100.0
+  let s:color_hex_pat     = g:indent_guides_color_hex_pattern
+  let s:color_hex_bg_pat  = g:indent_guides_color_hex_guibg_pattern
+  let s:color_name_bg_pat = g:indent_guides_color_name_guibg_pattern
+  let s:start_level       = g:indent_guides_start_level
+
+  if s:debug
+    echo 's:indent_size = '       . s:indent_size
+    echo 's:guide_size = '        . s:guide_size
+    echo 's:hi_normal = '         . s:hi_normal
+    echo 's:indent_levels = '     . s:indent_levels
+    echo 's:auto_colors = '       . s:auto_colors
+    echo 's:change_percent = '    . string(s:change_percent)
+    echo 's:color_hex_pat = '     . s:color_hex_pat
+    echo 's:color_hex_bg_pat = '  . s:color_hex_bg_pat
+    echo 's:color_name_bg_pat = ' . s:color_name_bg_pat
+    echo 's:start_level = '       . s:start_level
+  endif
+endfunction
+
+"
+" Calculate the indent guide size. Ensures the guide size is less than or
+" equal to the actual indent size, otherwise some weird things can occur.
+"
+" NOTE: Currently, this only works when soft-tabs are being used.
+"
+function! indent_guides#calculate_guide_size()
+  let l:guide_size  = g:indent_guides_guide_size
+  let l:indent_size = indent_guides#get_indent_size()
+
+  if l:indent_size > 1 && l:guide_size >= 1
+    let l:guide_size = (l:guide_size > s:indent_size) ? s:indent_size : l:guide_size
+  else
+    let l:guide_size = s:indent_size
+  endif
+
+  return l:guide_size
+endfunction
+
+"
+" Gets the indent size, which depends on whether soft-tabs or hard-tabs are
+" being used.
+"
+function! indent_guides#get_indent_size()
+  return (&l:expandtab == 1) ? &l:shiftwidth : 1
+endfunction
+
 "
 " Captures and returns the output of highlight group definitions.
 "
@@ -156,22 +234,7 @@ function! indent_guides#capture_highlight(group_name)
   exe "silent hi " . a:group_name
   redir END
 
+  let l:output = substitute(l:output, "\n", "", "")
   return l:output
 endfunction
 
-"
-" Init the w:indent_guides_matches variable.
-"
-function! indent_guides#init_matches()
-  let w:indent_guides_matches =
-    \ exists('w:indent_guides_matches') ? w:indent_guides_matches : []
-endfunction
-
-"
-" Define default highlights.
-"
-function! indent_guides#define_default_highlights()
-  exe 'hi IndentGuidesOdd  guibg=NONE ctermbg=NONE'
-  exe 'hi IndentGuidesEven guibg=NONE ctermbg=NONE'
-endfunction
-

doc/indent_guides.txt

@@ -1,4 +1,4 @@
-*indent_guides.txt*  A plugin for visually displaying indent levels in vim.
+*indent_guides.txt*  A plugin for visually displaying indent levels in Vim.
 
                                                                  *indent-guides*
       ____           __            __     ______       _      __
@@ -9,8 +9,8 @@
 
 
 Author:      Nate Kane <nathanaelkane AT gmail DOT com>
-Version:     1.1
-Last Change: 29 Dec 2010
+Version:     1.3
+Last Change: 17 Jan 2011
 
 ==============================================================================
 CONTENTS                                                *indent-guides-contents*
@@ -27,16 +27,20 @@ CONTENTS                                                *indent-guides-contents*
 ==============================================================================
 1. INTRODUCTION                                     *indent-guides-introduction*
 
-Indent Guides is a plugin for visually displaying indent levels in vim.
+Indent Guides is a plugin for visually displaying indent levels in Vim.
+
+This plugin should work with gVim out of the box, no configuration needed.
 
 Features:~
   * Can detect both tab and space indent styles.
-  * Automatically inspects your colorscheme and picks appropriate colors (gvim
+  * Automatically inspects your colorscheme and picks appropriate colors (gVim
     only).
   * Will highlight indent levels with alternating colors.
-  * Full support for gvim and basic support for terminal vim.
-  * Seems to work on Windows gvim 7.3 (haven't done any extensive tests
+  * Full support for gVim and basic support for Terminal Vim.
+  * Seems to work on Windows gVim 7.3 (haven't done any extensive tests
     though).
+  * Customizable size for indent guides, eg. skinny guides (soft-tabs only).
+  * Customizable start indent level.
 
 ==============================================================================
 2. COMMANDS                                             *indent-guides-commands*
@@ -61,6 +65,7 @@ Features:~
 ------------------------------------------------------------------------------
                                                  *'indent_guides_indent_levels'*
 Use this option to control how many indent levels to display guides for.
+
 Default: 30. Values: integer.
 >
   let g:indent_guides_indent_levels = 30
@@ -71,6 +76,7 @@ Default: 30. Values: integer.
 Use this option to control whether or not the plugin automatically calculates
 the highlight colors. Will use the current colorscheme's background color as a
 base color.
+
 Default: 1. Values: 0 or 1.
 >
   let g:indent_guides_auto_colors = 1
@@ -88,9 +94,36 @@ in an autocmd.
                                           *'indent_guides_color_change_percent'*
 Use this option to control the percent at which the highlight colors will be
 lightened or darkened.
-Default: 0.05. Values: between 0 and 1.
+
+Default: 10 (10%). Values: between 0 and 100.
 >
-  let g:indent_guides_color_change_percent = 0.05
+  let g:indent_guides_color_change_percent = 10
+<
+
+------------------------------------------------------------------------------
+                                                    *'indent_guides_guide_size'*
+Use this option to customize the size of the indent guide. By default the
+value is set to 0, which will set the guide size to be the same as the
+|shiftwidth|. Setting this value to be larger than the |shiftwidth| is essentially
+the same as setting it to 0.
+
+A common use of this setting is to create skinny indent guides, which look
+great with a |shiftwidth| of 4 or more.
+
+NOTE: This option only works for soft-tabs (spaces) and not hard-tabs.
+
+Default: 0. Values: between 0 and |shiftwidth|.
+>
+  let g:indent_guides_guide_size = 1
+<
+
+------------------------------------------------------------------------------
+                                                   *'indent_guides_start_level'*
+Use this option to control which indent level to start showing guides from.
+
+Default: 1. Values: between 1 and g:|indent_guides_indent_levels|.
+>
+  let g:indent_guides_start_level = 2
 <
 
 ==============================================================================
@@ -148,7 +181,7 @@ Alternatively you can manually setup the highlight colors yourself, see
 
 Why did I build this plugin?~
   * I believe indent guides make nested code easier to read and understand.
-  * Other editors have them and it's high time vim did.
+  * Other editors have them and it's high time Vim did.
   * None of the existing indent guide plugins on the market suited my needs.
   * I wanted to learn me some VimL.
 
@@ -170,8 +203,18 @@ Bug reports, feedback, suggestions etc are welcomed.
 ==============================================================================
 7. CHANGELOG                                           *indent-guides-changelog*
 
+1.3~
+  * Changed the default value of g:|indent_guides_color_change_percent| to 10.
+  * Added support for gVim themes that don't specify a `hi Normal guibg`
+    color.
+
+1.2~
+  * Customizable size for indent guides, eg. skinny guides (soft-tabs only).
+  * Customizable start indent level.
+  * Refactored some internal logic.
+
 1.1~
-  * Added basic support for terminal vim. See |indent-guides-terminal-vim| for
+  * Added basic support for Terminal Vim. See |indent-guides-terminal-vim| for
     more information.
   * Cut down on rgb to hex color conversions by adding a big dictionary of
     color names and hex codes.
@@ -186,7 +229,7 @@ Bug reports, feedback, suggestions etc are welcomed.
 The MIT Licence
 http://www.opensource.org/licenses/mit-license.php
 
-Copyright (c) 2010 Nate Kane
+Copyright (c) 2010-2011 Nate Kane
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

plugin/indent_guides.vim

@@ -24,34 +24,33 @@ command! IndentGuidesToggle  call s:IndentGuidesToggle()
 command! IndentGuidesEnable  call s:IndentGuidesEnable()
 command! IndentGuidesDisable call s:IndentGuidesDisable()
 
-" Default options
-let g:indent_guides_indent_levels =
-  \ exists('g:indent_guides_indent_levels') ?
-  \ g:indent_guides_indent_levels : 30
-
-let g:indent_guides_auto_colors =
-  \ exists('g:indent_guides_auto_colors') ?
-  \ g:indent_guides_auto_colors : 1
-
-let g:indent_guides_color_change_percent =
-  \ exists('g:indent_guides_color_change_percent') ?
-  \ g:indent_guides_color_change_percent : 0.05
-
-let g:indent_guides_debug =
-  \ exists('g:indent_guides_debug') ?
-  \ g:indent_guides_debug : 0
-
-let g:indent_guides_autocmds_enabled = 0
-
 "
-" Regex pattern for a hex color.
+" Initializes a given variable to a given value. The variable is only
+" initialized if it does not exist prior.
 "
-" Example matches:
-" - '#123ABC'
-" - '#ffffff'
-" - '#000000'
-"
-let g:indent_guides_hex_color_pattern = '#[0-9A-Fa-f]\{6\}'
+function s:InitVariable(var, value)
+  if !exists(a:var)
+    if type(a:var) == type("")
+      exec 'let ' . a:var . ' = ' . "'" . a:value . "'"
+    else
+      exec 'let ' . a:var . ' = ' .  a:value
+    endif
+  endif
+endfunction
+
+" Fixed global variables
+let g:indent_guides_autocmds_enabled         = 0
+let g:indent_guides_color_hex_pattern        = '#[0-9A-Fa-f]\{6\}'
+let g:indent_guides_color_hex_guibg_pattern  = 'guibg=\zs' . g:indent_guides_color_hex_pattern . '\ze'
+let g:indent_guides_color_name_guibg_pattern = "guibg='\\?\\zs[0-9A-Za-z ]\\+\\ze'\\?"
+
+" Configurable global variables
+call s:InitVariable('g:indent_guides_indent_levels',        30)
+call s:InitVariable('g:indent_guides_auto_colors',          1 )
+call s:InitVariable('g:indent_guides_color_change_percent', 10) " ie. 10%
+call s:InitVariable('g:indent_guides_guide_size',           0 )
+call s:InitVariable('g:indent_guides_start_level',          1 )
+call s:InitVariable('g:indent_guides_debug',                0 )
 
 " Default mapping
 nmap <Leader>ig :IndentGuidesToggle<CR>