System.Filepath: Introduce expand_home() function

Because sometimes you want to expand the path "~vim-jp/$EDITOR" to
"/home/vim-jp/$EDITOR", but that file name doesn't exist, making
fnamemodify(_, ':p') unpredictable, and the environment variable syntax
in the path makes expand(_) unwieldy.

Author: bb010g

autoload/vital/__vital__/System/Filepath.vim

@@ -197,12 +197,23 @@ function! s:is_case_tolerant() abort
 endfunction
 
 
+function! s:expand_home(path) abort
+  if a:path[:0] !=# '~'
+    return a:path
+  endif
+  let post_home_idx = match(a:path, s:path_sep_pattern)
+  return post_home_idx is# -1
+        \ ? s:remove_last_separator(expand(a:path))
+        \ : s:remove_last_separator(expand(a:path[0 : post_home_idx - 1]))
+        \   . a:path[post_home_idx :]
+endfunction
+
 function! s:abspath(path) abort
   if s:is_absolute(a:path)
     return a:path
   endif
-  " Note:
-  "   the behavior of ':p' for non existing file path/directory is not defined
+  " NOTE: The behavior of ':p' for a non existing file/directory path
+  " is not defined.
   return (filereadable(a:path) || isdirectory(a:path))
         \ ? fnamemodify(a:path, ':p')
         \ : s:join(fnamemodify(getcwd(), ':p'), a:path)

doc/vital/System/Filepath.txt

@@ -97,6 +97,15 @@ is_case_tolerant()		*Vital.System.Filepath.is_case_tolerant()*
 	Return non-zero if filesystem ignores alphabetic case of a filename,
 	zero otherwise.
 
+expand_home({path})		*Vital.System.Filepath.expand_home()*
+	Return a home-expanded path of {path}.  The home directory expansion
+	will not have a trailing directory separator.
+
+	Like |expand()|, but only expanding a leading "~" home directory
+	sequence, or like |fnamemodify()| with the ":p" modifier, but without
+	full path expansion or unpredictable results if a file name doesn't
+	exist and doesn't have an absolute path.  See |filename-modifiers|.
+
 abspath({path})			*Vital.System.Filepath.abspath()*
 	Return an absolute path of {path}.
 	If the {path} is already an absolute path, it returns the {path}.