Config overhaul

.github/workflows/docgen.yml

@@ -15,7 +15,7 @@ jobs:
       - name: Generating help
         run: |
           curl -Lq https://github.com/numToStr/lemmy-help/releases/latest/download/lemmy-help-x86_64-unknown-linux-gnu.tar.gz | tar xz
-          ./lemmy-help ./lua/auto-session/init.lua ./lua/auto-session/autocmds.lua ./lua/auto-session/session-lens/init.lua ./lua/auto-session/session-lens/actions.lua > doc/${{env.PLUGIN_NAME}}.txt
+          ./lemmy-help ./lua/auto-session/config.lua ./lua/auto-session/autocmds.lua ./lua/auto-session/init.lua ./lua/auto-session/session-lens/init.lua ./lua/auto-session/session-lens/actions.lua > doc/${{env.PLUGIN_NAME}}.txt
 
       - name: Commit
         uses: stefanzweifel/git-auto-commit-action@v5

.gitignore

@@ -7,3 +7,4 @@ doc/tags
 tests/test_sessions
 tests/custom_sessions
 tests/test_git
+tests/symlink-test

doc/auto-session.txt

@@ -1,79 +1,107 @@
-defaultConf                                                        *defaultConf*
-    table default config for auto session
+==============================================================================
+Table of Contents                                                          *toc*
 
-    Fields: ~
-        {auto_session_enabled?}              (boolean)           Enables/disables auto saving and restoring
-        {auto_session_root_dir?}             (string)            root directory for session files, by default is `vim.fn.stdpath('data') .. '/sessions/'`
-        {auto_save_enabled?}                 (boolean)           Enables/disables auto saving session on exit
-        {auto_restore_enabled?}              (boolean)           Enables/disables auto restoring session on start
-        {auto_session_suppress_dirs?}        (table)             Suppress auto session for directories
-        {auto_session_allowed_dirs?}         (table)             Allow auto session for directories, if empty then all directories are allowed except for suppressed ones
-        {auto_session_create_enabled?}       (boolean|function)  Enables/disables auto creating new sessions. Can take a function that should return true/false if a session should be created or not
-        {auto_session_enable_last_session?}  (boolean)           On startup, loads the last saved session if session for cwd does not exist
-        {auto_session_use_git_branch?}       (boolean)           Include git branch name in session name to differentiate between sessions for different git branches
-        {auto_restore_lazy_delay_enabled?}   (boolean)           Automatically detect if Lazy.nvim is being used and wait until Lazy is done to make sure session is restored correctly. Does nothing if Lazy isn't being used. Can be disabled if a problem is suspected or for debugging
-        {log_level?}                         (string|integer)    "debug", "info", "warn", "error" or vim.log.levels.DEBUG, vim.log.levels.INFO, vim.log.levels.WARN, vim.log.levels.ERROR
-
-
-luaOnlyConf                                                        *luaOnlyConf*
-    Lua Only Configs for Auto Session
-
-    Fields: ~
-        {cwd_change_handling?}             (boolean|CwdChangeHandling)
-        {bypass_session_save_file_types?}  (table)                      List of file types to bypass auto save when the only buffer open is one of the file types listed, useful to ignore dashboards
-        {close_unsupported_windows?}       (boolean)                    Whether to close windows that aren't backed by a real file
-        {silent_restore?}                  (boolean)                    Suppress extraneous messages and source the whole session, even if there's an error. Set to false to get the line number of a restore error
-        {log_level?}                       (string|integer)             "debug", "info", "warn", "error" or vim.log.levels.DEBUG, vim.log.levels.INFO, vim.log.levels.WARN, vim.log.levels.ERROR
-        {args_allow_single_directory?}     (boolean)                    Follow normal sesion save/load logic if launched with a single directory as the only argument
-                                                                        Argv Handling
-        {args_allow_files_auto_save?}      (boolean|function)           Allow saving a session even when launched with a file argument (or multiple files/dirs). It does not load any existing session first. While you can just set this to true, you probably want to set it to a function that decides when to save a session when launched with file args. See documentation for more detail
-        {session_lens?}                    (session_lens_config)        Session lens configuration options
+Config ··················································· |auto-session.config|
+Commands ··············································· |auto-session.commands|
+API ························································· |auto-session.api|
 
+==============================================================================
+Config                                                     *auto-session.config*
 
-CwdChangeHandling                                            *CwdChangeHandling*
-    CWD Change Handling Config
+AutoSession.Config                                          *AutoSession.Config*
 
     Fields: ~
-        {restore_upcoming_session}  (boolean)  {true} restore session for upcoming cwd on cwd change
-        {pre_cwd_changed_hook?}     (boolean)  {true} This is called after auto_session code runs for the DirChangedPre autocmd
-        {post_cwd_changed_hook?}    (boolean)  {true} This is called after auto_session code runs for the DirChanged autocmd
-
-
-session_lens_config                                        *session_lens_config*
-    Session Lens Config
+        {enabled?}                      (boolean)           Enables/disables auto saving and restoring
+        {root_dir?}                     (string)            root directory for session files, by default is `vim.fn.stdpath('data') .. '/sessions/'`
+        {auto_save?}                    (boolean)           Enables/disables auto saving session on exit
+        {auto_restore?}                 (boolean)           Enables/disables auto restoring session on start
+        {auto_create?}                  (boolean|function)  Enables/disables auto creating new session files. Can take a function that should return true/false if a new session file should be created or not
+        {suppressed_dirs?}              (table)             Suppress auto session for directories
+        {allowed_dirs?}                 (table)             Allow auto session for directories, if empty then all directories are allowed except for suppressed ones
+        {auto_restore_last_lession?}    (boolean)           On startup, loads the last saved session if session for cwd does not exist
+        {use_git_branch?}               (boolean)           Include git branch name in session name to differentiate between sessions for different git branches
+        {lazy_support?}                 (boolean)           Automatically detect if Lazy.nvim is being used and wait until Lazy is done to make sure session is restored correctly. Does nothing if Lazy isn't being used. Can be disabled if a problem is suspected or for debugging
+        {bypass_save_filetypes?}        (table)             List of file types to bypass auto save when the only buffer open is one of the file types listed, useful to ignore dashboards
+        {close_unsupported_windows?}    (boolean)           Whether to close windows that aren't backed by a real file
+        {args_allow_single_directory?}  (boolean)           Follow normal sesion save/load logic if launched with a single directory as the only argument
+                                                            Argv Handling
+        {args_allow_files_auto_save?}   (boolean|function)  Allow saving a session even when launched with a file argument (or multiple files/dirs). It does not load any existing session first. While you can just set this to true, you probably want to set it to a function that decides when to save a session when launched with file args. See documentation for more detail
+        {continue_restore_on_error?}    (boolean)           Keep loading the session even if there's an error. Set to false to get the line number of an error when loading a session
+        {log_level?}                    (string|integer)    "debug", "info", "warn", "error" or vim.log.levels.DEBUG, vim.log.levels.INFO, vim.log.levels.WARN, vim.log.levels.ERROR
+        {cwd_change_handling?}          (boolean)           Follow cwd changes, saving a session before change and restoring after
+        {session_lens?}                 (SessionLens)       Session lens configuration options
+        {pre_save_cmds?}                (table)             executes before a session is saved
+
+                                                            Hooks
+        {save_extra_cmds?}              (table)             executes before a session is saved
+        {post_save_cmds?}               (table)             executes after a session is saved
+        {pre_restore_cmds?}             (table)             executes before a session is restored
+        {post_restore_cmds?}            (table)             executes after a session is restored
+        {pre_delete_cmds?}              (table)             executes before a session is deleted
+        {post_delete_cmds?}             (table)             executes after a session is deleted
+        {no_restore_cmds?}              (table)             executes at VimEnter when no session is restored
+        {pre_cwd_changed_cmds?}         (table)             executes before cwd is changed if cwd_change_handling is true
+        {post_cwd_changed_cmds?}        (table)             executes after cwd is changed if cwd_change_handling is true
+
+
+SessionLens                                                        *SessionLens*
+    Sessien Lens Cenfig
 
     Fields: ~
-        {load_on_setup?}       (boolean)
-        {shorten_path?}        (boolean)               Deprecated, pass { 'shorten' } to path_display
-        {path_display?}        (table)                 An array that specifies how to handle paths. Read :h telescope.defaults.path_display
-        {theme_conf?}          (table)
-        {buftypes_to_ignore?}  (table)                 Deprecated, if you're using this please report your usage on github
-        {previewer?}           (boolean)               Whether to show a preview of the session file (not very useful to most people)
-        {session_control?}     (session_control)
-        {mappings?}            (session_lens_mapping)
+        {load_on_setup?}    (boolean)
+        {shorten_path?}     (boolean)              Deprecated, pass { 'shorten' } to path_display
+        {path_display?}     (table)                An array that specifies how to handle paths. Read :h telescope.defaults.path_display
+        {theme_conf?}       (table)                Telescope theme options
+        {previewer?}        (boolean)              Whether to show a preview of the session file (not very useful to most people)
+        {session_control?}  (SessionControl)
+        {mappings?}         (SessionLensMappings)
 
 
-session_control                                                *session_control*
-    Session Control Config
+SessionControl                                                  *SessionControl*
 
     Fields: ~
         {control_dir}       (string)
         {control_filename}  (string)
 
 
-session_lens_mapping                                      *session_lens_mapping*
+SessionLensMappings                                        *SessionLensMappings*
     Session Lens Mapping
 
     Fields: ~
         {delete_session}     (table)  mode and key for deleting a session from the picker
         {alternate_session}  (table)  mode and key for swapping to alertnate session from the picker
 
 
+==============================================================================
+Commands                                                 *auto-session.commands*
+
+This plugin provides the following commands:
+
+  `:SessionSave` - saves a session based on the `cwd` in `root_dir`
+  `:SessionSave my_session` - saves a session called `my_session` in `root_dir`
+
+  `:SessionRestore` - restores a session based on the `cwd` from `root_dir`
+  `:SessionRestore my_session` - restores `my_session` from `root_dir`
+
+  `:SessionDelete` - deletes a session based on the `cwd` from `root_dir`
+  `:SessionDelete my_session` - deletes `my_sesion` from `root_dir`
+
+  `:SessionDisableAutoSave` - disables autosave
+  `:SessionDisableAutoSave!` - enables autosave (still does all checks in the config)
+  `:SessionToggleAutoSave` - toggles autosave
+
+  `:SessionPurgeOrphaned` - removes all orphaned sessions with no working directory left.
+
+  `:SessionSearch` - open a session picker, uses Telescope if installed, vim.ui.select otherwise
+
+==============================================================================
+API                                                           *auto-session.api*
+
 AutoSession.setup({config})                                  *AutoSession.setup*
     Setup function for AutoSession
 
     Parameters: ~
-        {config}  (defaultConf|nil)  Config for auto session
+        {config}  (AutoSession.Config|nil)  Config for auto session
 
 
 AutoSession.session_exists_for_cwd()        *AutoSession.session_exists_for_cwd*
@@ -104,10 +132,6 @@ AutoSession.AutoRestoreSession({session_name?})
         (boolean)  returns whether restoring the session was successful or not.
 
 
-AutoSession.PurgeOrphanedSessions()          *AutoSession.PurgeOrphanedSessions*
-     Deletes sessions where the original directory no longer exists
-
-
                                                        *AutoSession.SaveSession*
 AutoSession.SaveSession({session_name?}, {show_message?})
     Saves a session to the dir specified in the config. If no optional
@@ -209,16 +233,4 @@ AutoSession.DisableAutoSave({enable?})             *AutoSession.DisableAutoSave*
         (boolean)  autosaving is enabled or not
 
 
-SessionLens.setup()                                          *SessionLens.setup*
-
-
-                                                    *SessionLens.search_session*
-SessionLens.search_session({custom_opts})
-    Search session
-    Triggers the customized telescope picker for switching sessions
-
-    Parameters: ~
-        {custom_opts}  (any)
-
-
 vim:tw=78:ts=8:noet:ft=help:norl: