Merge pull request #5295 from elyalon/dirs

Fix user dirs, add docs

4 files changed, 222 insertions, 57 deletions

diff --git a/core/os/os2/errors.odin b/core/os/os2/errors.odin
index b50f04cab..0aff335bb 100644
--- a/core/os/os2/errors.odin
+++ b/core/os/os2/errors.odin
@@ -27,6 +27,8 @@ General_Error :: enum u32 {
 
 	Pattern_Has_Separator,
 
+	No_HOME_Variable,
+
 	Unsupported,
 }
 
@@ -73,6 +75,7 @@ error_string :: proc(ferr: Error) -> string {
 		case .Invalid_Command:   return "invalid command"
 		case .Unsupported:       return "unsupported"
 		case .Pattern_Has_Separator: return "pattern has separator"
+		case .No_HOME_Variable:  return "no $HOME variable"
 		}
 	case io.Error:
 		switch e {
diff --git a/core/os/os2/user.odin b/core/os/os2/user.odin
index 0f6134f21..e2a4ec4d0 100644
--- a/core/os/os2/user.odin
+++ b/core/os/os2/user.odin
@@ -2,64 +2,147 @@ package os2
 
 import "base:runtime"
 
+// ```
+// Windows:  C:\Users\Alice
+// macOS:    /Users/Alice
+// Linux:    /home/alice
+// ```
 @(require_results)
 user_home_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	return _user_home_dir(allocator)
 }
 
-// application caches, logs, temporary files
+// Files that applications can regenerate/refetch at a loss of speed, e.g. shader caches
+//
+// Sometimes deleted for system maintenance
+//
+// ```
+// Windows:  C:\Users\Alice\AppData\Local
+// macOS:    /Users/Alice/Library/Caches
+// Linux:    /home/alice/.cache
+// ```
 @(require_results)
 user_cache_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	return _user_cache_dir(allocator)
 }
 
-// application assets
+// User-hidden application data
+//
+// ```
+// Windows:  C:\Users\Alice\AppData\Local ("C:\Users\Alice\AppData\Roaming" if `roaming`)
+// macOS:    /Users/Alice/Library/Application Support
+// Linux:    /home/alice/.local/share
+// ```
+//
+// NOTE: (Windows only) `roaming` is for syncing across multiple devices within a *domain network*
 @(require_results)
-user_data_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
-	return _user_data_dir(allocator)
+user_data_dir :: proc(allocator: runtime.Allocator, roaming := false) -> (dir: string, err: Error) {
+	return _user_data_dir(allocator, roaming)
 }
 
-// application history, ui layout state, logs
+// Non-essential application data, e.g. history, ui layout state
+//
+// ```
+// Windows:  C:\Users\Alice\AppData\Local
+// macOS:    /Users/Alice/Library/Application Support
+// Linux:    /home/alice/.local/state
+// ```
 @(require_results)
 user_state_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	return _user_state_dir(allocator)
 }
 
+// Application log files
+//
+// ```
+// Windows:  C:\Users\Alice\AppData\Local
+// macOS:    /Users/Alice/Library/Logs
+// Linux:    /home/alice/.local/state
+// ```
 @(require_results)
-user_config_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
-	return _user_config_dir(allocator)
+user_log_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
+	return _user_log_dir(allocator)
 }
 
+// Application settings/preferences
+//
+// ```
+// Windows:  C:\Users\Alice\AppData\Local ("C:\Users\Alice\AppData\Roaming" if `roaming`)
+// macOS:    /Users/Alice/Library/Application Support
+// Linux:    /home/alice/.config
+// ```
+//
+// NOTE: (Windows only) `roaming` is for syncing across multiple devices within a *domain network*
+@(require_results)
+user_config_dir :: proc(allocator: runtime.Allocator, roaming := false) -> (dir: string, err: Error) {
+	return _user_config_dir(allocator, roaming)
+}
+
+// ```
+// Windows:  C:\Users\Alice\Music
+// macOS:    /Users/Alice/Music
+// Linux:    /home/alice/Music
+// ```
 @(require_results)
 user_music_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	return _user_music_dir(allocator)
 }
 
+// ```
+// Windows:  C:\Users\Alice\Desktop
+// macOS:    /Users/Alice/Desktop
+// Linux:    /home/alice/Desktop
+// ```
 @(require_results)
 user_desktop_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	return _user_desktop_dir(allocator)
 }
 
+// ```
+// Windows:  C:\Users\Alice\Documents
+// macOS:    /Users/Alice/Documents
+// Linux:    /home/alice/Documents
+// ```
 @(require_results)
 user_documents_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	return _user_documents_dir(allocator)
 }
 
+// ```
+// Windows:  C:\Users\Alice\Downloads
+// macOS:    /Users/Alice/Downloads
+// Linux:    /home/alice/Downloads
+// ```
 @(require_results)
 user_downloads_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	return _user_downloads_dir(allocator)
 }
 
+// ```
+// Windows:  C:\Users\Alice\Pictures
+// macOS:    /Users/Alice/Pictures
+// Linux:    /home/alice/Pictures
+// ```
 @(require_results)
 user_pictures_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	return _user_pictures_dir(allocator)
 }
 
+// ```
+// Windows:  C:\Users\Alice\Public
+// macOS:    /Users/Alice/Public
+// Linux:    /home/alice/Public
+// ```
 @(require_results)
 user_public_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	return _user_public_dir(allocator)
 }
 
+// ```
+// Windows:  C:\Users\Alice\Videos
+// macOS:    /Users/Alice/Movies
+// Linux:    /home/alice/Videos
+// ```
 @(require_results)
 user_videos_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	return _user_videos_dir(allocator)
diff --git a/core/os/os2/user_posix.odin b/core/os/os2/user_posix.odin
index 7541a99e1..2c31f7eb8 100644
--- a/core/os/os2/user_posix.odin
+++ b/core/os/os2/user_posix.odin
@@ -2,103 +2,114 @@
 package os2
 
 import "base:runtime"
+import "core:strings"
+import "core:sys/posix"
 
 _user_cache_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	#partial switch ODIN_OS {
 	case .Darwin:
-		return _xdg_lookup("", "HOME", "/Library/Caches", allocator)
-	case: // All other UNIX systems
-		return _xdg_lookup("XDG_CACHE_HOME", "HOME", "/.cache", allocator)
+		return _xdg_lookup("", "/Library/Caches", allocator)
+	case: // Unix
+		return _xdg_lookup("XDG_CACHE_HOME", "/.cache", allocator)
 	}
 }
 
-_user_config_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
+_user_config_dir :: proc(allocator: runtime.Allocator, _roaming: bool) -> (dir: string, err: Error) {
 	#partial switch ODIN_OS {
 	case .Darwin:
-		return _xdg_lookup("", "HOME", "/.config", allocator)
-	case: // All other UNIX systems
-		return _xdg_lookup("XDG_CONFIG_HOME", "HOME", "/.config", allocator)
+		return _xdg_lookup("", "/Library/Application Support", allocator)
+	case: // Unix
+		return _xdg_lookup("XDG_CONFIG_HOME", "/.config", allocator)
 	}
 }
 
 _user_state_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	#partial switch ODIN_OS {
 	case .Darwin:
-		return _xdg_lookup("", "HOME", "/.local/state", allocator)
-	case: // All other UNIX systems
-		return _xdg_lookup("XDG_STATE_HOME", "HOME", "/.local/state", allocator)
+		return _xdg_lookup("", "/Library/Application Support", allocator)
+	case: // Unix
+		return _xdg_lookup("XDG_STATE_HOME", "/.local/state", allocator)
 	}
 }
 
-_user_data_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
+_user_log_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	#partial switch ODIN_OS {
 	case .Darwin:
-		return _xdg_lookup("", "HOME", "/.local/share", allocator)
-	case: // All other UNIX systems
-		return _xdg_lookup("XDG_DATA_HOME", "HOME", "/.local/share", allocator)
+		return _xdg_lookup("", "/Library/Logs", allocator)
+	case: // Unix
+		return _xdg_lookup("XDG_STATE_HOME", "/.local/state", allocator)
+	}
+}
+
+_user_data_dir :: proc(allocator: runtime.Allocator, _roaming: bool) -> (dir: string, err: Error) {
+	#partial switch ODIN_OS {
+	case .Darwin:
+		return _xdg_lookup("", "/Library/Application Support", allocator)
+	case: // Unix
+		return _xdg_lookup("XDG_DATA_HOME", "/.local/share", allocator)
 	}
 }
 
 _user_music_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	#partial switch ODIN_OS {
 	case .Darwin:
-		return _xdg_lookup("", "HOME", "/Music", allocator)
-	case: // All other UNIX systems
-		return _xdg_lookup("XDG_MUSIC_DIR", "HOME", "/Music", allocator)
+		return _xdg_lookup("", "/Music", allocator)
+	case: // Unix
+		return _xdg_lookup("XDG_MUSIC_DIR", "/Music", allocator)
 	}
 }
 
 _user_desktop_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	#partial switch ODIN_OS {
 	case .Darwin:
-		return _xdg_lookup("", "HOME", "/Desktop", allocator)
-	case: // All other UNIX systems
-		return _xdg_lookup("XDG_DESKTOP_DIR", "HOME", "/Desktop", allocator)
+		return _xdg_lookup("", "/Desktop", allocator)
+	case: // Unix
+		return _xdg_lookup("XDG_DESKTOP_DIR", "/Desktop", allocator)
 	}
 }
 
 _user_documents_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	#partial switch ODIN_OS {
 	case .Darwin:
-		return _xdg_lookup("", "HOME", "/Documents", allocator)
-	case: // All other UNIX systems
-		return _xdg_lookup("XDG_DOCUMENTS_DIR", "HOME", "/Documents", allocator)
+		return _xdg_lookup("", "/Documents", allocator)
+	case: // Unix
+		return _xdg_lookup("XDG_DOCUMENTS_DIR", "/Documents", allocator)
 	}
 }
 
 _user_downloads_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	#partial switch ODIN_OS {
 	case .Darwin:
-		return _xdg_lookup("", "HOME", "/Downloads", allocator)
-	case: // All other UNIX systems
-		return _xdg_lookup("XDG_DOWNLOAD_DIR", "HOME", "/Downloads", allocator)
+		return _xdg_lookup("", "/Downloads", allocator)
+	case: // Unix
+		return _xdg_lookup("XDG_DOWNLOAD_DIR", "/Downloads", allocator)
 	}
 }
 
 _user_pictures_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	#partial switch ODIN_OS {
 	case .Darwin:
-		return _xdg_lookup("", "HOME", "/Pictures", allocator)
-	case: // All other UNIX systems
-		return _xdg_lookup("XDG_PICTURES_DIR", "HOME", "/Pictures", allocator)
+		return _xdg_lookup("", "/Pictures", allocator)
+	case: // Unix
+		return _xdg_lookup("XDG_PICTURES_DIR", "/Pictures", allocator)
 	}
 }
 
 _user_public_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	#partial switch ODIN_OS {
 	case .Darwin:
-		return _xdg_lookup("", "HOME", "/Public", allocator)
-	case: // All other UNIX systems
-		return _xdg_lookup("XDG_PUBLIC_DIR", "HOME", "/Public", allocator)
+		return _xdg_lookup("", "/Public", allocator)
+	case: // Unix
+		return _xdg_lookup("XDG_PUBLICSHARE_DIR", "/Public", allocator)
 	}
 }
 
 _user_videos_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	#partial switch ODIN_OS {
 	case .Darwin:
-		return _xdg_lookup("", "HOME", "/Movies", allocator)
-	case: // All other UNIX systems
-		return _xdg_lookup("XDG_VIDEOS_DIR", "HOME", "/Videos", allocator)
+		return _xdg_lookup("", "/Movies", allocator)
+	case: // Unix
+		return _xdg_lookup("XDG_VIDEOS_DIR", "/Videos", allocator)
 	}
 }
 
@@ -106,27 +117,89 @@ _user_home_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error
 	if v := get_env("HOME", allocator); v != "" {
 		return v, nil
 	}
-	return "", .Invalid_Path
+	err = .No_HOME_Variable
+	return
 }
 
-_xdg_lookup :: proc(xdg_env, fallback_env: string, fallback_suffix: string, allocator: runtime.Allocator) -> (dir: string, err: Error) {
+_xdg_lookup :: proc(xdg_key: string, fallback_suffix: string, allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	temp_allocator  := TEMP_ALLOCATOR_GUARD({ allocator })
 
-	if xdg_env == "" { // Darwin doesn't have XDG paths.
-		dir = get_env(fallback_env, temp_allocator)
+	if xdg_key == "" { // Darwin doesn't have XDG paths.
+		dir = get_env("HOME", temp_allocator)
 		if dir == "" {
-			return "", .Invalid_Path
+			err = .No_HOME_Variable
+			return
 		}
 		return concatenate({dir, fallback_suffix}, allocator)
 	} else {
-		dir = get_env(xdg_env, allocator)
+		if strings.ends_with(xdg_key, "_DIR") {
+			dir = _xdg_user_dirs_lookup(xdg_key, allocator) or_return
+		} else {
+			dir = get_env(xdg_key, allocator)
+		}
+
 		if dir == "" {
-			dir = get_env(fallback_env, temp_allocator)
+			dir = get_env("HOME", temp_allocator)
 			if dir == "" {
-				return "", .Invalid_Path
+				err = .No_HOME_Variable
+				return
 			}
 			dir = concatenate({dir, fallback_suffix}, allocator) or_return
 		}
 		return
 	}
+}
+
+// If `<config-dir>/user-dirs.dirs` doesn't exist, or `xdg_key` can't be found there: returns `""`
+_xdg_user_dirs_lookup :: proc(xdg_key: string, allocator: runtime.Allocator) -> (dir: string, err: Error) {
+	temp_allocator  := TEMP_ALLOCATOR_GUARD({ allocator })
+
+	config_dir := user_config_dir(temp_allocator) or_return
+
+	user_dirs_path := concatenate({config_dir, "/user-dirs.dirs"}, temp_allocator) or_return
+	user_dirs_content_bytes, read_err := read_entire_file(user_dirs_path, temp_allocator)
+	if read_err == .Not_Exist {
+		return
+	} else if read_err != nil {
+		err = read_err
+		return
+	}
+	user_dirs_content := string(user_dirs_content_bytes)
+
+	lines := strings.split_lines(user_dirs_content, temp_allocator) or_return
+
+	home_env := get_env("HOME", temp_allocator)
+	if home_env == "" {
+		err = .No_HOME_Variable
+		return
+	}
+
+	for line in lines {
+		ss := strings.split_n(line, "=", 2, temp_allocator) or_return
+		(len(ss) == 2) or_continue
+		sl := strings.trim_space(ss[0])
+		sr := ss[1]
+
+		(sl == xdg_key) or_continue
+
+		(len(sr) > 2) or_continue
+
+		lq := strings.index_byte(sr, '"')
+		(lq != -1) or_continue
+		rq := strings.index_byte(sr[lq+1:], '"') + lq+1
+		(rq != -1) or_continue
+
+		sr = sr[lq+1:rq]
+
+		we: posix.wordexp_t
+		we_err := posix.wordexp(strings.clone_to_cstring(sr, temp_allocator), &we, nil)
+		(we_err == nil) or_continue
+		defer posix.wordfree(&we)
+
+		(we.we_wordc == 1) or_continue
+
+		dir = strings.clone_from_cstring(we.we_wordv[0], allocator) or_return
+		return
+	}
+	return
 }
\ No newline at end of file
diff --git a/core/os/os2/user_windows.odin b/core/os/os2/user_windows.odin
index 94ac3c566..d68f933ce 100644
--- a/core/os/os2/user_windows.odin
+++ b/core/os/os2/user_windows.odin
@@ -3,25 +3,31 @@ package os2
 import "base:runtime"
 @(require) import win32 "core:sys/windows"
 
-_user_cache_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
+_local_appdata :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	guid := win32.FOLDERID_LocalAppData
 	return _get_known_folder_path(&guid, allocator)
 }
 
-_user_config_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
-	guid := win32.FOLDERID_RoamingAppData
+_local_appdata_or_roaming :: proc(allocator: runtime.Allocator, roaming: bool) -> (dir: string, err: Error) {
+	guid := win32.FOLDERID_LocalAppData
+	if roaming {
+		guid = win32.FOLDERID_RoamingAppData
+	}
 	return _get_known_folder_path(&guid, allocator)
 }
 
+_user_config_dir :: _local_appdata_or_roaming
+_user_data_dir :: _local_appdata_or_roaming
+
+_user_state_dir :: _local_appdata
+_user_log_dir :: _local_appdata
+_user_cache_dir :: _local_appdata
+
 _user_home_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	guid := win32.FOLDERID_Profile
 	return _get_known_folder_path(&guid, allocator)
 }
 
-_user_data_dir :: _user_config_dir
-
-_user_state_dir :: _user_cache_dir
-
 _user_music_dir :: proc(allocator: runtime.Allocator) -> (dir: string, err: Error) {
 	guid := win32.FOLDERID_Music
 	return _get_known_folder_path(&guid, allocator)