Merge pull request #88: User defined session name completion suggestions

README.md

@@ -227,6 +227,10 @@ By default the plug-in installs a top level menu. If you don't like this you can
 
     :let g:session_menu = 0
 
+### The `g:session_name_suggestion_function` option
+
+The default completion of the `:SaveSession` command is based on the names of the existing sessions. You can add your own suggestions using this option by setting the option to the name of a Vim script function. By default this option is set to an example function that suggests the name of the current git or Mercurial feature branch (when you're working in a version control repository).
+
 ### The `g:loaded_session` option
 
 This variable isn't really an option but if you want to avoid loading the vim-session plug-in you can set this variable to any value in your [vimrc script] [vimrc]:
@@ -251,8 +255,8 @@ Recently this plug-in switched from reimplementing [:mksession][mksession] to ac
 
 <!-- Start of generated documentation -->
 
-The documentation of the 34 functions below was extracted from
-1 Vim scripts on July  6, 2014 at 21:01.
+The documentation of the 37 functions below was extracted from
+2 Vim scripts on July  6, 2014 at 22:23.
 
 ### Public API for the vim-session plug-in
 
@@ -405,10 +409,20 @@ configured with `g:session_directory` for files that end with the suffix
 configured with `g:session_extension`, takes the base name of each file
 and decodes any URL encoded characters. Returns a list of strings.
 
+If the first argument is true (1) then the user defined function
+configured with `g:session_name_suggestion_function` is called to find
+suggested session names, which are prefixed to the list of available
+sessions, otherwise the argument should be false (0).
+
 #### The `xolox#session#complete_names()` function
 
 Completion function for user defined Vim commands. Used by commands like
-`:OpenSession` and `:DeleteSession` to support user friendly completion.
+`:OpenSession` and `:DeleteSession`  (but not `:SaveSession`) to support
+user friendly completion.
+
+#### The `xolox#session#complete_names_with_suggestions()` function
+
+Completion function for the Vim command `:SaveSession`.
 
 #### The `xolox#session#is_tab_scoped()` function
 
@@ -449,6 +463,16 @@ scoped session. Saves a copy of the original value to be restored later.
 
 Restore the original value of Vim's [sessionoptions] [] option.
 
+### Example function for session name suggestions
+
+#### The `xolox#session#suggestions#vcs_feature_branch()` function
+
+This function implements an example of a function that can be used with
+the `g:session_name_suggestion_function` option. It finds the name of the
+current git or Mercurial feature branch (if any) and suggests this name as
+the name for the session that is being saved with :SaveSession. Returns a
+list with one string on success and an empty list on failure.
+
 <!-- End of generated documentation -->
 
 ## Contact

autoload/xolox/session.vim

@@ -4,7 +4,7 @@
 " Last Change: July 6, 2014
 " URL: http://peterodding.com/code/vim/session/
 
-let g:xolox#session#version = '2.5'
+let g:xolox#session#version = '2.6'
 
 " Public API for session persistence. {{{1
 
@@ -403,7 +403,7 @@ function! xolox#session#auto_load() " {{{2
   if current_buffer_is_empty && (buffer_list_is_empty || buffer_list_is_persistent)
     " Check whether a session matching the user-specified server name exists.
     if v:servername !~ '^\cgvim\d*$'
-      for session in xolox#session#get_names()
+      for session in xolox#session#get_names(0)
         if v:servername ==? session
           call xolox#session#open_cmd(session, '', 'OpenSession')
           return
@@ -452,7 +452,7 @@ function! xolox#session#auto_save() " {{{2
   let name = xolox#session#find_current_session()
   " If no session is active and the user doesn't have any sessions yet, help
   " them get started by suggesting to create the default session.
-  if empty(name) && (empty(xolox#session#get_names()) || g:session_default_overwrite)
+  if empty(name) && (empty(xolox#session#get_names(0)) || g:session_default_overwrite)
     let name = g:session_default_name
   endif
   " Prompt the user to save the active/first/default session?
@@ -837,7 +837,7 @@ function! xolox#session#prompt_for_name(action) " {{{2
   "
   " If only a single session exists there's nothing to choose from so the name
   " of that session will be returned directly, without prompting the user.
-  let sessions = sort(xolox#session#get_names(), 1)
+  let sessions = sort(xolox#session#get_names(0), 1)
   if len(sessions) == 1
     return sessions[0]
   elseif !empty(sessions)
@@ -878,20 +878,37 @@ function! xolox#session#path_to_name(path) " {{{2
   return xolox#misc#path#decode(fnamemodify(a:path, ':t:r'))
 endfunction
 
-function! xolox#session#get_names() " {{{2
+function! xolox#session#get_names(include_suggestions) " {{{2
   " Get the names of all available sessions. This scans the directory
   " configured with `g:session_directory` for files that end with the suffix
   " configured with `g:session_extension`, takes the base name of each file
   " and decodes any URL encoded characters. Returns a list of strings.
+  "
+  " If the first argument is true (1) then the user defined function
+  " configured with `g:session_name_suggestion_function` is called to find
+  " suggested session names, which are prefixed to the list of available
+  " sessions, otherwise the argument should be false (0).
   let directory = xolox#misc#path#absolute(g:session_directory)
   let filenames = split(glob(xolox#misc#path#merge(directory, '*' . g:session_extension)), "\n")
-  return map(filenames, 'xolox#session#path_to_name(v:val)')
+  call map(filenames, 'xolox#session#path_to_name(v:val)')
+  if a:include_suggestions && !empty(g:session_name_suggestion_function)
+    let suggested_names = call(g:session_name_suggestion_function, [])
+    let filenames = suggested_names + filenames
+  endif
+  return filenames
 endfunction
 
 function! xolox#session#complete_names(arg, line, pos) " {{{2
   " Completion function for user defined Vim commands. Used by commands like
-  " `:OpenSession` and `:DeleteSession` to support user friendly completion.
-  let names = filter(xolox#session#get_names(), 'v:val =~ a:arg')
+  " `:OpenSession` and `:DeleteSession`  (but not `:SaveSession`) to support
+  " user friendly completion.
+  let names = filter(xolox#session#get_names(0), 'v:val =~ a:arg')
+  return map(names, 'fnameescape(v:val)')
+endfunction
+
+function! xolox#session#complete_names_with_suggestions(arg, line, pos) " {{{2
+  " Completion function for the Vim command `:SaveSession`.
+  let names = filter(xolox#session#get_names(1), 'v:val =~ a:arg')
   return map(names, 'fnameescape(v:val)')
 endfunction
 

autoload/xolox/session/suggestions.vim

@@ -0,0 +1,42 @@
+" Example function for session name suggestions.
+"
+" Author: Peter Odding
+" Last Change: July 6, 2014
+" URL: http://peterodding.com/code/vim/session/
+
+function! xolox#session#suggestions#vcs_feature_branch() " {{{1
+  " This function implements an example of a function that can be used with
+  " the `g:session_name_suggestion_function` option. It finds the name of the
+  " current git or Mercurial feature branch (if any) and suggests this name as
+  " the name for the session that is being saved with :SaveSession. Returns a
+  " list with one string on success and an empty list on failure.
+  let [kind, directory] = xolox#session#suggestions#find_vcs_repository()
+  if kind == 'git'
+    let command = 'git rev-parse --abbrev-ref HEAD'
+    let names_to_ignore = ['master']
+  elseif kind == 'hg'
+    let command = 'hg branch'
+    let names_to_ignore = ['default']
+  else
+    return []
+  endif
+  let result = xolox#misc#os#exec({'command': command, 'check': 0})
+  if result['exit_code'] == 0 && !empty(result['stdout'])
+    let branch_name = xolox#misc#str#trim(result['stdout'][0])
+    if !empty(branch_name) && index(names_to_ignore, branch_name) == -1
+      return [xolox#misc#str#slug(branch_name)]
+    endif
+  endif
+  return []
+endfunction
+
+function! xolox#session#suggestions#find_vcs_repository()
+  for name in ['git', 'hg']
+    let match = finddir('.' . name, '.;')
+    if !empty(match)
+      let directory = fnamemodify(match, ':h')
+      return [name, directory]
+    endif
+  endfor
+  return ['', '']
+endfunction

doc/session.txt

@@ -33,7 +33,8 @@ Contents ~
   13. The |g:session_restart_environment| option
   14. The |g:session_command_aliases| option
   15. The |g:session_menu| option
-  16. The |g:loaded_session| option
+  16. The |g:session_name_suggestion_function| option
+  17. The |g:loaded_session| option
  5. Compatibility with other plug-ins |session-compatibility-with-other-plug-ins|
  6. Known issues                                         |session-known-issues|
  7. Function reference                             |session-function-reference|
@@ -55,13 +56,16 @@ Contents ~
    15. The |xolox#session#path_to_name()| function
    16. The |xolox#session#get_names()| function
    17. The |xolox#session#complete_names()| function
-   18. The |xolox#session#is_tab_scoped()| function
-   19. The |xolox#session#find_current_session()| function
-   20. The |xolox#session#get_label()| function
-   21. The |xolox#session#options_include()| function
-   22. The |xolox#session#include_tabs()| function
-   23. The |xolox#session#change_tab_options()| function
-   24. The |xolox#session#restore_tab_options()| function
+   18. The |xolox#session#complete_names_with_suggestions()| function
+   19. The |xolox#session#is_tab_scoped()| function
+   20. The |xolox#session#find_current_session()| function
+   21. The |xolox#session#get_label()| function
+   22. The |xolox#session#options_include()| function
+   23. The |xolox#session#include_tabs()| function
+   24. The |xolox#session#change_tab_options()| function
+   25. The |xolox#session#restore_tab_options()| function
+  2. Example function for session name suggestions |example-function-for-session-name-suggestions|
+   1. The |xolox#session#suggestions#vcs_feature_branch()| function
  8. Contact                                                   |session-contact|
  9. License                                                   |session-license|
  10. Sample session script                              |sample-session-script|
@@ -458,6 +462,15 @@ can disable it by adding the following line to your |vimrc| script:
 >
   :let g:session_menu = 0
 <
+-------------------------------------------------------------------------------
+The *g:session_name_suggestion_function* option
+
+The default completion of the |:SaveSession| command is based on the names of
+the existing sessions. You can add your own suggestions using this option by
+setting the option to the name of a Vim script function. By default this option
+is set to an example function that suggests the name of the current git or
+Mercurial feature branch (when you're working in a version control repository).
+
 -------------------------------------------------------------------------------
 The *g:loaded_session* option
 
@@ -499,8 +512,8 @@ might take a while...)
                                                    *session-function-reference*
 Function reference ~
 
-The documentation of the 34 functions below was extracted from 1 Vim scripts on
-July 6, 2014 at 21:01.
+The documentation of the 37 functions below was extracted from 2 Vim scripts on
+July 6, 2014 at 22:23.
 
 -------------------------------------------------------------------------------
                                            *public-api-for-vim-session-plug-in*
@@ -650,11 +663,22 @@ with |g:session_directory| for files that end with the suffix configured with
 |g:session_extension|, takes the base name of each file and decodes any URL
 encoded characters. Returns a list of strings.
 
+If the first argument is true (1) then the user defined function configured
+with |g:session_name_suggestion_function| is called to find suggested session
+names, which are prefixed to the list of available sessions, otherwise the
+argument should be false (0).
+
 -------------------------------------------------------------------------------
 The *xolox#session#complete_names()* function
 
 Completion function for user defined Vim commands. Used by commands like
-|:OpenSession| and |:DeleteSession| to support user friendly completion.
+|:OpenSession| and |:DeleteSession| (but not |:SaveSession|) to support user
+friendly completion.
+
+-------------------------------------------------------------------------------
+The *xolox#session#complete_names_with_suggestions()* function
+
+Completion function for the Vim command |:SaveSession|.
 
 -------------------------------------------------------------------------------
 The *xolox#session#is_tab_scoped()* function
@@ -702,6 +726,19 @@ The *xolox#session#restore_tab_options()* function
 Restore the original value of Vim's sessionoptions (see |'sessionoptions'|)
 option.
 
+-------------------------------------------------------------------------------
+                                *example-function-for-session-name-suggestions*
+Example function for session name suggestions ~
+
+-------------------------------------------------------------------------------
+The *xolox#session#suggestions#vcs_feature_branch()* function
+
+This function implements an example of a function that can be used with the
+|g:session_name_suggestion_function| option. It finds the name of the current
+git or Mercurial feature branch (if any) and suggests this name as the name for
+the session that is being saved with :SaveSession. Returns a list with one
+string on success and an empty list on failure.
+
 ===============================================================================
                                                               *session-contact*
 Contact ~

plugin/session.vim

@@ -114,6 +114,11 @@ if !exists('g:session_persist_colors')
   let g:session_persist_colors = 1
 endif
 
+" Enable user defined session name completion suggestions for :SaveSession.
+if !exists('g:session_name_suggestion_function')
+  let g:session_name_suggestion_function = 'xolox#session#suggestions#vcs_feature_branch'
+endif
+
 " Make sure the sessions directory exists and is writable. {{{1
 
 let s:directory = fnamemodify(g:session_directory, ':p')
@@ -163,7 +168,7 @@ call xolox#misc#cursorhold#register({'function': 'xolox#session#auto_save_period
 " one or more tab pages).
 command! -bar -bang -nargs=? -complete=customlist,xolox#session#complete_names OpenSession call xolox#session#open_cmd(<q-args>, <q-bang>, 'OpenSession')
 command! -bar -nargs=? -complete=customlist,xolox#session#complete_names ViewSession call xolox#session#view_cmd(<q-args>)
-command! -bar -bang -nargs=? -complete=customlist,xolox#session#complete_names SaveSession call xolox#session#save_cmd(<q-args>, <q-bang>, 'SaveSession')
+command! -bar -bang -nargs=? -complete=customlist,xolox#session#complete_names_with_suggestions SaveSession call xolox#session#save_cmd(<q-args>, <q-bang>, 'SaveSession')
 command! -bar -bang -nargs=? -complete=customlist,xolox#session#complete_names DeleteSession call xolox#session#delete_cmd(<q-args>, <q-bang>)
 command! -bar -bang CloseSession call xolox#session#close_cmd(<q-bang>, 0, 1, 'CloseSession')