diff --git a/README.md b/README.md index 0915439..4658e40 100644 --- a/README.md +++ b/README.md @@ -231,6 +231,130 @@ If your favorite plug-in doesn't work with the vim-session plug-in drop me a mai Recently this plug-in switched from reimplementing [:mksession][mksession] to actually using it because this was the only way to support complex split window layouts. Only after making this change did I realize [:mksession][mksession] doesn't support [quickfix](http://vimdoc.sourceforge.net/htmldoc/quickfix.html#quickfix) and [location list](http://vimdoc.sourceforge.net/htmldoc/quickfix.html#location-list) windows and of course it turns out that bolting on support for these after the fact is going to complicate the plug-in significantly (in other words, I'm working on it but it might take a while...) +## Function reference + + + +The documentation of the 34 functions below was extracted from +2 Vim scripts on June 24, 2013 at 22:18. + +### Public API for vim-notes plug-in + +#### The `xolox#session#save_special_windows()` function + +Integration between :mksession, :NERDTree and :Project. + +#### The `xolox#session#auto_load()` function + +Automatically load the default / last used session when Vim starts. + +#### The `xolox#session#auto_save()` function + +We won't save the session if Vim is not terminating normally. + +#### The `xolox#session#auto_save_periodic()` function + +Automatically save the session every few minutes? + +#### The `xolox#session#auto_unlock()` function + +Automatically unlock all sessions when Vim quits. + +#### The `xolox#session#view_cmd()` function + +Name of session given as command argument? + +#### The `xolox#session#prompt_for_name()` function + +Prompt the user to select one of the existing sessions. The first argument +is expected to be a string describing what will be done to the session +once it's been selected. Returns the name of the selected session as a +string. If no session is selected an empty string is returned. Here's +an example of what the prompt looks like: + + :call xolox#session#prompt_for_name('trash') + + Please select the session to trash: + + 1. first-session + 2. second-session + 3. third-session + + Type number and or click with mouse (empty cancels): + +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. + +#### The `xolox#session#name_to_path()` function + +Convert the name of a session (the first argument, expected to be a +string) to an absolute pathname. Any special characters in the session +name will be encoded using URL encoding. This means you're free to use +whatever naming conventions you like (regardless of special characters +like slashes). Returns a string. + +#### The `xolox#session#path_to_name()` function + +Convert the absolute pathname of a session script (the first argument, +expected to be a string) to a session name. This function assumes the +absolute pathname refers to the configured session directory, but it does +not check for it nor does it require it (it simple takes the base name +of the absolute pathname of the session script and decodes it). Returns a +string. + +#### The `xolox#session#get_names()` function + +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. + +#### 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. + +#### The `xolox#session#is_tab_scoped()` function + +Determine whether the current session is tab scoped or global. Returns 1 +(true) when the session is tab scoped, 0 (false) otherwise. + +#### The `xolox#session#find_current_session()` function + +Find the name of the current tab scoped or global session. Returns a +string. If no session is active an empty string is returned. + +#### The `xolox#session#get_label()` function + +Get a human readable label based on the scope (tab scoped or global) and +name of a session. The first argument is the name (a string) and the +second argument is a boolean indicating the scope of the session; 1 (true) +means tab scoped and 0 (false) means global scope. Returns a string. + +#### The `xolox#session#options_include()` function + +Check whether Vim's [sessionoptions] [] option includes the keyword given +as the first argument (expected to be a string). Returns 1 (true) when it +does, 0 (false) otherwise. + +[sessionoptions]: http://vimdoc.sourceforge.net/htmldoc/options.html#'sessionoptions' + +#### The `xolox#session#include_tabs()` function + +Check whether Vim's [sessionoptions] [] option includes the `tabpages` +keyword. Returns 1 (true) when it does, 0 (false) otherwise. + +#### The `xolox#session#change_tab_options()` function + +Temporarily change Vim's [sessionoptions] [] option so we can save a tab +scoped session. Saves a copy of the original value to be restored later. + +#### The `xolox#session#restore_tab_options()` function + +Restore the original value of Vim's [sessionoptions] [] option. + + + ## Contact If you have questions, bug reports, suggestions, etc. the author can be contacted at . The latest version is available at and . If you like the script please vote for it on [Vim Online](http://www.vim.org/scripts/script.php?script_id=3150). diff --git a/autoload/xolox/session.vim b/autoload/xolox/session.vim index 0e74063..0cdba08 100644 --- a/autoload/xolox/session.vim +++ b/autoload/xolox/session.vim @@ -1,4 +1,5 @@ -" Vim script +" Public API for vim-notes plug-in. +" " Author: Peter Odding " Last Change: June 24, 2013 " URL: http://peterodding.com/code/vim/session/ @@ -712,7 +713,7 @@ function! xolox#session#prompt_for_name(action) " {{{2 " Prompt the user to select one of the existing sessions. The first argument " is expected to be a string describing what will be done to the session " once it's been selected. Returns the name of the selected session as a - " string (if no session is selected an empty string is returned). Here's + " string. If no session is selected an empty string is returned. Here's " an example of what the prompt looks like: " " :call xolox#session#prompt_for_name('trash') @@ -748,33 +749,52 @@ function! xolox#session#prompt_for_name(action) " {{{2 endfunction function! xolox#session#name_to_path(name) " {{{2 + " Convert the name of a session (the first argument, expected to be a + " string) to an absolute pathname. Any special characters in the session + " name will be encoded using URL encoding. This means you're free to use + " whatever naming conventions you like (regardless of special characters + " like slashes). Returns a string. let directory = xolox#misc#path#absolute(g:session_directory) let filename = xolox#misc#path#encode(a:name) . g:session_extension return xolox#misc#path#merge(directory, filename) endfunction function! xolox#session#path_to_name(path) " {{{2 + " Convert the absolute pathname of a session script (the first argument, + " expected to be a string) to a session name. This function assumes the + " absolute pathname refers to the configured session directory, but it does + " not check for it nor does it require it (it simple takes the base name + " of the absolute pathname of the session script and decodes it). Returns a + " string. return xolox#misc#path#decode(fnamemodify(a:path, ':t:r')) endfunction function! xolox#session#get_names() " {{{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. 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)') 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') return map(names, 'fnameescape(v:val)') endfunction function! xolox#session#is_tab_scoped() " {{{2 - " Determine whether the current session is tab scoped or global. + " Determine whether the current session is tab scoped or global. Returns 1 + " (true) when the session is tab scoped, 0 (false) otherwise. return exists('t:this_session') endfunction function! xolox#session#find_current_session() " {{{2 - " Find the name of the current tab scoped or global session. + " Find the name of the current tab scoped or global session. Returns a + " string. If no session is active an empty string is returned. for variable in ['t:this_session', 'v:this_session'] if exists(variable) let filename = eval(variable) @@ -790,21 +810,33 @@ function! xolox#session#find_current_session() " {{{2 endfunction function! xolox#session#get_label(name, is_tab_scoped) " {{{2 + " Get a human readable label based on the scope (tab scoped or global) and + " name of a session. The first argument is the name (a string) and the + " second argument is a boolean indicating the scope of the session; 1 (true) + " means tab scoped and 0 (false) means global scope. Returns a string. return printf('%s session %s', a:is_tab_scoped ? 'tab scoped' : 'global', string(a:name)) endfunction function! xolox#session#options_include(value) " {{{2 + " Check whether Vim's [sessionoptions] [] option includes the keyword given + " as the first argument (expected to be a string). Returns 1 (true) when it + " does, 0 (false) otherwise. + " + " [sessionoptions]: http://vimdoc.sourceforge.net/htmldoc/options.html#'sessionoptions' return index(xolox#misc#option#split(&sessionoptions), a:value) >= 0 endfunction " Tab scoped sessions: {{{2 function! xolox#session#include_tabs() " {{{3 + " Check whether Vim's [sessionoptions] [] option includes the `tabpages` + " keyword. Returns 1 (true) when it does, 0 (false) otherwise. return xolox#session#options_include('tabpages') endfunction function! xolox#session#change_tab_options() " {{{3 - " Save the original value of 'sessionoptions'. + " Temporarily change Vim's [sessionoptions] [] option so we can save a tab + " scoped session. Saves a copy of the original value to be restored later. let s:ssop_save = &sessionoptions " Only persist the current tab page. set sessionoptions-=tabpages @@ -813,7 +845,7 @@ function! xolox#session#change_tab_options() " {{{3 endfunction function! xolox#session#restore_tab_options() " {{{3 - " Restore the original value of 'sessionoptions'. + " Restore the original value of Vim's [sessionoptions] [] option. if exists('s:ssop_save') let &ssop = s:ssop_save unlet s:ssop_save diff --git a/doc/session.txt b/doc/session.txt index 21774db..708fe08 100644 --- a/doc/session.txt +++ b/doc/session.txt @@ -33,10 +33,30 @@ Contents ~ 13. The |g:loaded_session| option 5. Compatibility with other plug-ins |session-compatibility-with-other-plug-ins| 6. Known issues |session-known-issues| - 7. Contact |session-contact| - 8. License |session-license| - 9. Sample session script |sample-session-script| - 10. References |session-references| + 7. Function reference |session-function-reference| + 1. Public API for vim-notes plug-in |session-public-api-for-vim-notes-plug-in| + 1. The |xolox#session#save_special_windows()| function + 2. The |xolox#session#auto_load()| function + 3. The |xolox#session#auto_save()| function + 4. The |xolox#session#auto_save_periodic()| function + 5. The |xolox#session#auto_unlock()| function + 6. The |xolox#session#view_cmd()| function + 7. The |xolox#session#prompt_for_name()| function + 8. The |xolox#session#name_to_path()| function + 9. The |xolox#session#path_to_name()| function + 10. The |xolox#session#get_names()| function + 11. The |xolox#session#complete_names()| function + 12. The |xolox#session#is_tab_scoped()| function + 13. The |xolox#session#find_current_session()| function + 14. The |xolox#session#get_label()| function + 15. The |xolox#session#options_include()| function + 16. The |xolox#session#include_tabs()| function + 17. The |xolox#session#change_tab_options()| function + 18. The |xolox#session#restore_tab_options()| function + 8. Contact |session-contact| + 9. License |session-license| + 10. Sample session script |sample-session-script| + 11. References |session-references| =============================================================================== *session-introduction* @@ -446,6 +466,147 @@ turns out that bolting on support for these after the fact is going to complicate the plug-in significantly (in other words, I'm working on it but it might take a while...) +=============================================================================== + *session-function-reference* +Function reference ~ + +The documentation of the 34 functions below was extracted from 2 Vim scripts on +June 24, 2013 at 22:18. + +------------------------------------------------------------------------------- + *session-public-api-for-vim-notes-plug-in* +Public API for vim-notes plug-in ~ + +------------------------------------------------------------------------------- +The *xolox#session#save_special_windows()* function + +Integration between :mksession, :NERDTree and :Project. + +------------------------------------------------------------------------------- +The *xolox#session#auto_load()* function + +Automatically load the default / last used session when Vim starts. + +------------------------------------------------------------------------------- +The *xolox#session#auto_save()* function + +We won't save the session if Vim is not terminating normally. + +------------------------------------------------------------------------------- +The *xolox#session#auto_save_periodic()* function + +Automatically save the session every few minutes? + +------------------------------------------------------------------------------- +The *xolox#session#auto_unlock()* function + +Automatically unlock all sessions when Vim quits. + +------------------------------------------------------------------------------- +The *xolox#session#view_cmd()* function + +Name of session given as command argument? + +------------------------------------------------------------------------------- +The *xolox#session#prompt_for_name()* function + +Prompt the user to select one of the existing sessions. The first argument is +expected to be a string describing what will be done to the session once it's +been selected. Returns the name of the selected session as a string. If no +session is selected an empty string is returned. Here's an example of what the +prompt looks like: +> + :call xolox#session#prompt_for_name('trash') + + Please select the session to trash: + + 1. first-session + 2. second-session + 3. third-session + + Type number and or click with mouse (empty cancels): +< +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. + +------------------------------------------------------------------------------- +The *xolox#session#name_to_path()* function + +Convert the name of a session (the first argument, expected to be a string) to +an absolute pathname. Any special characters in the session name will be +encoded using URL encoding. This means you're free to use whatever naming +conventions you like (regardless of special characters like slashes). Returns a +string. + +------------------------------------------------------------------------------- +The *xolox#session#path_to_name()* function + +Convert the absolute pathname of a session script (the first argument, expected +to be a string) to a session name. This function assumes the absolute pathname +refers to the configured session directory, but it does not check for it nor +does it require it (it simple takes the base name of the absolute pathname of +the session script and decodes it). Returns a string. + +------------------------------------------------------------------------------- +The *xolox#session#get_names()* function + +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. + +------------------------------------------------------------------------------- +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. + +------------------------------------------------------------------------------- +The *xolox#session#is_tab_scoped()* function + +Determine whether the current session is tab scoped or global. Returns 1 (true) +when the session is tab scoped, 0 (false) otherwise. + +------------------------------------------------------------------------------- +The *xolox#session#find_current_session()* function + +Find the name of the current tab scoped or global session. Returns a string. If +no session is active an empty string is returned. + +------------------------------------------------------------------------------- +The *xolox#session#get_label()* function + +Get a human readable label based on the scope (tab scoped or global) and name +of a session. The first argument is the name (a string) and the second argument +is a boolean indicating the scope of the session; 1 (true) means tab scoped and +0 (false) means global scope. Returns a string. + +------------------------------------------------------------------------------- +The *xolox#session#options_include()* function + +Check whether Vim's sessionoptions (see |'sessionoptions'|) option includes the +keyword given as the first argument (expected to be a string). Returns 1 (true) +when it does, 0 (false) otherwise. + +------------------------------------------------------------------------------- +The *xolox#session#include_tabs()* function + +Check whether Vim's sessionoptions (see |'sessionoptions'|) option includes the +'tabpages' keyword. Returns 1 (true) when it does, 0 (false) otherwise. + +------------------------------------------------------------------------------- +The *xolox#session#change_tab_options()* function + +Temporarily change Vim's sessionoptions (see |'sessionoptions'|) option so we +can save a tab scoped session. Saves a copy of the original value to be +restored later. + +------------------------------------------------------------------------------- +The *xolox#session#restore_tab_options()* function + +Restore the original value of Vim's sessionoptions (see |'sessionoptions'|) +option. + =============================================================================== *session-contact* Contact ~