diff options
| -rw-r--r-- | lib/stdlib/doc/src/filename.xml | 156 | ||||
| -rw-r--r-- | lib/stdlib/src/filename.erl | 160 | ||||
| -rw-r--r-- | lib/stdlib/test/filename_SUITE.erl | 182 |
3 files changed, 495 insertions, 3 deletions
diff --git a/lib/stdlib/doc/src/filename.xml b/lib/stdlib/doc/src/filename.xml index 77e262dbe6..65009753f3 100644 --- a/lib/stdlib/doc/src/filename.xml +++ b/lib/stdlib/doc/src/filename.xml @@ -47,7 +47,12 @@ <p>The module supports raw file names in the way that if a binary is present, or the file name cannot be interpreted according to the return value of <seealso marker="kernel:file#native_name_encoding/0">file:native_name_encoding/0</seealso>, a raw file name will also be returned. For example filename:join/1 provided with a path component being a binary (and also not being possible to interpret under the current native file name encoding) will result in a raw file name being returned (the join operation will have been performed of course). For more information about raw file names, see the <seealso marker="kernel:file">file</seealso> module.</p> </description> - + <datatypes> + <datatype> + <name name="basedir_type"/> + </datatype> + </datatypes> + <funcs> <func> <name name="absname" arity="1"/> @@ -102,6 +107,155 @@ </desc> </func> <func> + <name name="basedir" arity="2"/> + <fsummary>Equivalent to <c>basedir(<anno>Type</anno>,<anno>Application</anno>,#{})</c>.</fsummary> + <desc> + <p> + Equivalent to <seealso marker="#basedir-3"> + basedir(<anno>Type</anno>, <anno>Application</anno>, #{})</seealso>. + </p> + </desc> + </func> + <func> + <name name="basedir" arity="3"/> + <fsummary></fsummary> + <desc><marker id="basedir-3"/> + <p> + Returns a suitable path, or paths, for a given type. + If <c>os</c> is not set in <c><anno>Opts</anno></c> the function will default to + the native option, i.e. <c>'linux'</c>, <c>'darwin'</c> or <c>'windows'</c>, as understood + by <c>os:type/0</c>. Anything not recognized as <c>'darwin'</c> or <c>'windows'</c> is + interpreted as <c>'linux'</c>.</p> + <p> + The options <c>'author'</c> and <c>'version'</c> are only used with <c>'windows'</c> option mode. + </p> + <list type="bulleted"> + <item><c>user_cache</c> + <p>The path location is intended for transient data files on a local machine.</p> + <p> + On Linux: + Respects the os environment variable <c>XDG_CACHE_HOME</c>. + </p> + <pre> +1> <input>filename:basedir(user_cache, "my_application", #{os=>linux}).</input> +"/home/otptest/.cache/my_application"</pre> + On Darwin: <pre> +1> <input>filename:basedir(user_cache, "my_application", #{os=>darwin}).</input> +"/home/otptest/Library/Caches/my_application"</pre> + On Windows: <pre> +1> <input>filename:basedir(user_cache, "My App").</input> +"c:/Users/otptest/AppData/Local/My App/Cache" +2> <input>filename:basedir(user_cache, "My App").</input> +"c:/Users/otptest/AppData/Local/My App/Cache" +3> <input>filename:basedir(user_cache, "My App", #{author=>"Erlang"}).</input> +"c:/Users/otptest/AppData/Local/Erlang/My App/Cache" +4> <input>filename:basedir(user_cache, "My App", #{version=>"1.2"}).</input> +"c:/Users/otptest/AppData/Local/My App/1.2/Cache" +5> <input>filename:basedir(user_cache, "My App", #{author=>"Erlang",version=>"1.2"}).</input> +"c:/Users/otptest/AppData/Local/Erlang/My App/1.2/Cache"</pre> + </item> + <item><c>user_config</c> + <p> + The path location is intended for persistent configuration files. + </p> + <p> + On Linux: + Respects the os environment variable <c>XDG_CONFIG_HOME</c>. + </p> + <pre> +2> <input>filename:basedir(user_config, "my_application", #{os=>linux}).</input> +"/home/otptest/.config/my_application"</pre> + On Darwin:<pre> +2> <input>filename:basedir(user_config, "my_application", #{os=>darwin}).</input> +"/home/otptest/Library/Application Support/my_application"</pre> + On Windows:<pre> +1> <input>filename:basedir(user_config, "My App").</input> +"c:/Users/otptest/AppData/Roaming/My App" +2> <input>filename:basedir(user_config, "My App", #{author=>"Erlang", version=>"1.2"}).</input> +"c:/Users/otptest/AppData/Roaming/Erlang/My App/1.2"</pre> + </item> + <item><c>user_data</c> + <p> + The path location is intended for persistent data files. + </p> + <p> + On Linux: + Respects the os environment variable <c>XDG_DATA_HOME</c>. + </p> + <pre> +3> <input>filename:basedir(user_data, "my_application", #{os=>linux}).</input> +"/home/otptest/.local/my_application"</pre> + On Darwin:<pre> +3> <input>filename:basedir(user_data, "my_application", #{os=>darwin}).</input> +"/home/otptest/Library/Application Support/my_application"</pre> + On Windows:<pre> +8> <input>filename:basedir(user_data, "My App").</input> +"c:/Users/otptest/AppData/Local/My App" +9> <input>filename:basedir(user_data, "My App",#{author=>"Erlang",version=>"1.2"}).</input> +"c:/Users/otptest/AppData/Local/Erlang/My App/1.2"</pre> + </item> + <item><c>user_log</c> + <p>The path location is intended for transient log files on a local machine.</p> + <p> + On Linux: + Respects the os environment variable <c>XDG_CACHE_HOME</c>.</p> + <pre> +4> <input>filename:basedir(user_log, "my_application", #{os=>linux}).</input> +"/home/otptest/.cache/my_application/log"</pre> + On Darwin:<pre> +4> <input>filename:basedir(user_log, "my_application", #{os=>darwin}).</input> +"/home/otptest/Library/Caches/my_application"</pre> + On Windows:<pre> +12> <input>filename:basedir(user_log, "My App").</input> +"c:/Users/otptest/AppData/Local/My App/Logs" +13> <input>filename:basedir(user_log, "My App",#{author=>"Erlang",version=>"1.2"}).</input> +"c:/Users/otptest/AppData/Local/Erlang/My App/1.2/Logs"</pre> + </item> + <item><c>site_config</c><p> + On Linux: + Respects the os environment variable <c>XDG_CONFIG_DIRS</c>.</p> +<pre> +5> <input>filename:basedir(site_data, "my_application", #{os=>linux}).</input> +["/usr/local/share/my_application", + "/usr/share/my_application"] +6> <input>os:getenv("XDG_CONFIG_DIRS").</input> +"/etc/xdg/xdg-ubuntu:/usr/share/upstart/xdg:/etc/xdg" +7> <input>filename:basedir(site_config, "my_application", #{os=>linux}).</input> +["/etc/xdg/xdg-ubuntu/my_application", + "/usr/share/upstart/xdg/my_application", + "/etc/xdg/my_application"] +8> <input>os:unsetenv("XDG_CONFIG_DIRS").</input> +true +9> <input>filename:basedir(site_config, "my_application", #{os=>linux}).</input> +["/etc/xdg/my_application"]</pre> + On Darwin:<pre> +5> <input>filename:basedir(site_config, "my_application", #{os=>darwin}).</input> +["/Library/Application Support/my_application"]</pre> + </item> + <item><c>site_data</c><p> + On Linux: + Respects the os environment variable <c>XDG_DATA_DIRS</c>.</p> + <pre> +10> <input>os:getenv("XDG_DATA_DIRS").</input> +"/usr/share/ubuntu:/usr/share/gnome:/usr/local/share/:/usr/share/" +11> <input>filename:basedir(site_data, "my_application", #{os=>linux}).</input> +["/usr/share/ubuntu/my_application", + "/usr/share/gnome/my_application", + "/usr/local/share/my_application", + "/usr/share/my_application"] +12> <input>os:unsetenv("XDG_DATA_DIRS").</input> +true +13> <input>filename:basedir(site_data, "my_application", #{os=>linux}).</input> +["/usr/local/share/my_application", + "/usr/share/my_application"]</pre> + On Darwin:<pre> +5> <input>filename:basedir(site_data, "my_application", #{os=>darwin}).</input> +["/Library/Application Support/my_application"]</pre> + </item> + </list> + </desc> + </func> + <func> <name name="basename" arity="1"/> <fsummary>Return the last component of a filename</fsummary> <desc> diff --git a/lib/stdlib/src/filename.erl b/lib/stdlib/src/filename.erl index 008beb8b67..d921a69108 100644 --- a/lib/stdlib/src/filename.erl +++ b/lib/stdlib/src/filename.erl @@ -36,6 +36,7 @@ extension/1, join/1, join/2, pathtype/1, rootname/1, rootname/2, split/1, nativename/1]). -export([find_src/1, find_src/2, flatten/1]). +-export([basedir/2, basedir/3]). %% Undocumented and unsupported exports. -export([append/2]). @@ -139,6 +140,7 @@ absname_join(AbsBase, Name) -> -spec basename(Filename) -> file:filename_all() when Filename :: file:name_all(). + basename(Name) when is_binary(Name) -> case os:type() of {win32,_} -> @@ -954,3 +956,161 @@ filename_string_to_binary(List) -> Bin end. +%% Application Base Directories +%% basedir +%% http://standards.freedesktop.org/basedir-spec/basedir-spec-latest.html + +-type basedir_type() :: 'user_cache' | 'user_config' | 'user_data' + | 'user_log' + | 'site_config' | 'site_data'. + +-spec basedir(Type,Application) -> file:filename_all() when + Type :: basedir_type(), + Application :: string() | binary(). + +basedir(Type,Application) when is_atom(Type), is_list(Application) orelse + is_binary(Application) -> + basedir(Type, Application, #{}). + +-spec basedir(Type,Application,Opts) -> file:filename_all() when + Type :: basedir_type(), + Application :: string() | binary(), + Opts :: #{author => string() | binary(), + os => 'windows' | 'darwin' | 'linux', + version => string() | binary()}. + +basedir(Type,Application,Opts) when is_atom(Type), is_map(Opts), + is_list(Application) orelse + is_binary(Application) -> + Os = basedir_os_from_opts(Opts), + Name = basedir_name_from_opts(Os,Application,Opts), + Base = basedir_from_os(Type,Os), + case {Type,Os} of + {user_log,linux} -> + filename:join([Base,Name,"log"]); + {user_log,windows} -> + filename:join([Base,Name,"Logs"]); + {user_cache,windows} -> + filename:join([Base,Name,"Cache"]); + {Type,_} when Type =:= site_config orelse Type =:= site_data -> + [filename:join([B,Name]) || B <- Base]; + _ -> + filename:join([Base,Name]) + end. + +basedir_os_from_opts(#{os := linux}) -> linux; +basedir_os_from_opts(#{os := windows}) -> windows; +basedir_os_from_opts(#{os := darwin}) -> darwin; +basedir_os_from_opts(#{}) -> basedir_os_type(). + +basedir_name_from_opts(windows,App,#{author:=Author,version:=Vsn}) -> + filename:join([Author,App,Vsn]); +basedir_name_from_opts(windows,App,#{author:=Author}) -> + filename:join([Author,App]); +basedir_name_from_opts(_,App,#{version:=Vsn}) -> + filename:join([App,Vsn]); +basedir_name_from_opts(_,App,_) -> + App. + +basedir_from_os(Type,Os) -> + case Os of + linux -> basedir_linux(Type); + darwin -> basedir_darwin(Type); + windows -> basedir_windows(Type) + end. + +-define(basedir_linux_user_data, ".local/share"). +-define(basedir_linux_user_config, ".config"). +-define(basedir_linux_user_cache, ".cache"). +-define(basedir_linux_user_log, ".cache"). %% .cache/App/log +-define(basedir_linux_site_data, "/usr/local/share/:/usr/share/"). +-define(basedir_linux_site_config, "/etc/xdg"). + +basedir_linux(Type) -> + case Type of + user_data -> getenv("XDG_DATA_HOME", ?basedir_linux_user_data, true); + user_config -> getenv("XDG_CONFIG_HOME",?basedir_linux_user_config,true); + user_cache -> getenv("XDG_CACHE_HOME", ?basedir_linux_user_cache, true); + user_log -> getenv("XDG_CACHE_HOME", ?basedir_linux_user_log, true); + site_data -> + Base = getenv("XDG_DATA_DIRS",?basedir_linux_site_data,false), + string:tokens(Base,":"); + site_config -> + Base = getenv("XDG_CONFIG_DIRS",?basedir_linux_site_config,false), + string:tokens(Base,":") + end. + +-define(basedir_darwin_user_data, "Library/Application Support"). +-define(basedir_darwin_user_config, "Library/Application Support"). +-define(basedir_darwin_user_cache, "Library/Caches"). +-define(basedir_darwin_user_log, "Library/Logs"). +-define(basedir_darwin_site_data, "/Library/Application Support"). +-define(basedir_darwin_site_config, "/Library/Application Support"). + +basedir_darwin(Type) -> + case Type of + user_data -> basedir_join_home(?basedir_darwin_user_data); + user_config -> basedir_join_home(?basedir_darwin_user_config); + user_cache -> basedir_join_home(?basedir_darwin_user_cache); + user_log -> basedir_join_home(?basedir_darwin_user_log); + site_data -> [?basedir_darwin_site_data]; + site_config -> [?basedir_darwin_site_config] + end. + +%% On Windows: +%% ex. C:\Users\egil\AppData\Local\Ericsson\Erlang +%% %LOCALAPPDATA% is defined on Windows 7 and onwards +%% %APPDATA% is used instead of %LOCALAPPDATA% if it's not defined. +%% %APPDATA% is used for roaming, i.e. for user_config on Windows 7 and beyond. +%% +%% user_data %LOCALAPPDATA%[/$author]/$appname[/$version] +%% user_config %APPDATA%[/$author]/$appname[/$version] +%% user_cache %LOCALAPPDATA%[/$author]/$appname[/$version]/Cache +%% user_log %LOCALAPPDATA%[/$author]/$appname[/$version]/Logs + +basedir_windows(Type) -> + %% If LOCALAPPDATA is not defined we are likely on an + %% XP machine. Use APPDATA instead. + AppData = basedir_windows_appdata(), + case Type of + user_data -> getenv("LOCALAPPDATA", AppData); + user_config -> AppData; + user_cache -> getenv("LOCALAPPDATA", AppData); + user_log -> getenv("LOCALAPPDATA", AppData); + site_data -> []; + site_config -> [] + end. + +basedir_windows_appdata() -> + case os:getenv("APPDATA") of + Invalid when Invalid =:= false orelse Invalid =:= [] -> + erlang:error(noappdata); + Val -> Val + end. + +%% basedir aux + +getenv(K,Def,false) -> getenv(K,Def); +getenv(K,Def,true) -> getenv(K,basedir_join_home(Def)). + +getenv(K,Def) -> + case os:getenv(K) of + [] -> Def; + false -> Def; + Val -> Val + end. + +basedir_join_home(Dir) -> + case os:getenv("HOME") of + false -> + {ok,[[Home]]} = init:get_argument(home), + filename:join(Home,Dir); + Home -> filename:join(Home,Dir) + end. + +basedir_os_type() -> + case os:type() of + {unix,darwin} -> darwin; + {win32,_} -> windows; + _ -> linux + end. diff --git a/lib/stdlib/test/filename_SUITE.erl b/lib/stdlib/test/filename_SUITE.erl index ad7206ceae..7f2e4771f3 100644 --- a/lib/stdlib/test/filename_SUITE.erl +++ b/lib/stdlib/test/filename_SUITE.erl @@ -28,6 +28,7 @@ basename_bin_1/1, basename_bin_2/1, dirname_bin/1, extension_bin/1, join_bin/1, t_nativename_bin/1]). -export([pathtype_bin/1,rootname_bin/1,split_bin/1]). +-export([t_basedir_api/1, t_basedir_xdg/1, t_basedir_windows/1]). -include_lib("common_test/include/ct.hrl"). @@ -37,7 +38,8 @@ all() -> [absname, absname_2, find_src, absname_bin, absname_bin_2, - {group,p}]. + {group,p}, + t_basedir_xdg, t_basedir_windows]. groups() -> [{p, [parallel], @@ -47,7 +49,8 @@ groups() -> basename_1, basename_2, basename_bin_1, basename_bin_2, dirname_bin, join_bin, pathtype_bin, rootname_bin, split_bin, - t_nativename_bin]}]. + t_nativename_bin, + t_basedir_api]}]. init_per_suite(Config) -> Config. @@ -770,3 +773,178 @@ t_nativename_bin(Config) when is_list(Config) -> <<"/usr/tmp/arne">> = filename:nativename(<<"/usr/tmp//arne/">>) end. + +%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%% +%% basedirs +t_basedir_api(Config) when is_list(Config) -> + true = is_list(filename:basedir(site_data, "My App")), + true = is_list(filename:basedir(site_config, "My App")), + true = is_list(filename:basedir(user_data, "My App")), + true = is_list(filename:basedir(user_log, "My App")), + true = is_list(filename:basedir(user_config, "My App")), + true = is_list(filename:basedir(user_cache, "My App")), + + true = is_list(filename:basedir(site_data, <<"My App">>)), + true = is_list(filename:basedir(site_config, <<"My App">>)), + true = is_binary(filename:basedir(user_data, <<"My App">>)), + true = is_binary(filename:basedir(user_log, <<"My App">>)), + true = is_binary(filename:basedir(user_config, <<"My App">>)), + true = is_binary(filename:basedir(user_cache, <<"My App">>)), + + %% simulate for windows + case os:type() of + {win32,_} -> ok; + _ -> + os:putenv("APPDATA", "C:\\Documents and Settings\\otptest\\Application Data") + end, + + true = is_list(filename:basedir(site_data, "My App", #{})), + true = is_list(filename:basedir(site_config, "My App", #{os=>linux})), + true = is_list(filename:basedir(user_data, "My App", #{os=>darwin})), + true = is_list(filename:basedir(user_log, "My App", #{os=>windows})), + true = is_list(filename:basedir(user_config, "My App",#{author=>"Erl"})), + true = is_list(filename:basedir(user_config, "My App",#{os=>darwin, + author=>"Erl"})), + true = is_list(filename:basedir(user_config, "My App",#{os=>linux, + author=>"Erl"})), + true = is_list(filename:basedir(user_cache, "My App",#{os=>windows, + author=>"Erl"})), + true = is_list(filename:basedir(user_config, "My App",#{os=>darwin, + author=>"Erla", + version=>"1.0"})), + true = is_list(filename:basedir(user_config, "My App",#{os=>linux, + version=>"2.0.1", + author=>"Erl"})), + true = is_list(filename:basedir(user_cache, "My App",#{os=>windows, + version=>"3.1.2", + author=>"Erl"})), + true = is_binary(filename:basedir(user_config, "My App",#{os=>darwin, + author=>"Erla", + version=><<"1.0">>})), + true = is_binary(filename:basedir(user_config, "My App",#{os=>windows, + version=>"2.0.1", + author=><<"Erl">>})), + true = is_binary(filename:basedir(user_cache, "My App",#{os=>linux, + version=><<"3.1.2">>, + author=>"Erl"})), + %% simulate for windows + case os:type() of + {win32,_} -> ok; + _ -> os:unsetenv("APPDATA") + end, + + {'EXIT', _} = (catch filename:basedir(wrong_config, "My App")), + {'EXIT', _} = (catch filename:basedir(user_cache, {bad,name})), + {'EXIT', _} = (catch filename:basedir(user_cache, "My App", badopts)), + {'EXIT', _} = (catch filename:basedir(user_cache, "My App", [])), + ok. + +t_basedir_windows(Config) when is_list(Config) -> + Types = [user_data,user_log,user_config,user_cache], + case os:type() of + {win32,_} -> + ok = check_basedir_windows(Types, #{}); + _ -> + %% Windows 7 and beyond + os:putenv("APPDATA", "C:\\Users\\otptest\\AppData\\Roaming"), + os:putenv("LOCALAPPDATA", "C:\\Users\\otptest\\AppData\\Local"), + io:format("APPDATA ~p~n", [os:getenv("APPDATA")]), + io:format("LOCALAPPDATA ~p~n", [os:getenv("LOCALAPPDATA")]), + ok = check_basedir_windows(Types,#{os=>windows}), + %% Windows XP + os:unsetenv("LOCALAPPDATA"), + os:putenv("APPDATA", "C:\\Documents and Settings\\otptest\\Application Data"), + io:format("APPDATA ~p~n", [os:getenv("APPDATA")]), + io:format("APPLOCALDATA ~p~n", [os:getenv("APPLOCALDATA")]), + ok = check_basedir_windows(Types,#{os=>windows}), + os:unsetenv("APPDATA") + end, + ok. + +check_basedir_windows([],_) -> ok; +check_basedir_windows([Type|Types],Opt) -> + Name = "Some Application", + io:format("type: ~p~n", [Type]), + ok = check_basedir_windows_path(Type, + [Name], + filename:basedir(Type, Name, Opt)), + ok = check_basedir_windows_path(Type, + ["Erl",Name], + filename:basedir(Type, Name, Opt#{author=>"Erl"})), + ok = check_basedir_windows_path(Type, + [Name,"1.0"], + filename:basedir(Type, Name, Opt#{version=>"1.0"})), + ok = check_basedir_windows_path(Type, + ["Erl",Name,"1.0"], + filename:basedir(Type, Name, Opt#{author=>"Erl", + version=>"1.0"})), + check_basedir_windows(Types, Opt). + +check_basedir_windows_path(Type,Check0,Basedir) -> + BDR = lists:reverse(filename:split(Basedir)), + Check = lists:reverse(Check0), + io:format("~w: ~p ~p~n", [Type,Check,BDR]), + case Type of + user_log -> check_basedir_windows_path_split(["Logs"|Check],BDR); + user_cache -> check_basedir_windows_path_split(["Cache"|Check],BDR); + _ -> check_basedir_windows_path_split(Check,BDR) + end. + +check_basedir_windows_path_split([],_) -> ok; +check_basedir_windows_path_split([Same|Check],[Same|BDR]) -> + check_basedir_windows_path_split(Check,BDR). + + +t_basedir_xdg(Config) when is_list(Config) -> + check_basedir_xdg([user_data,user_log,user_config,user_cache, + site_data,site_config]), + ok. + +check_basedir_xdg([]) -> ok; +check_basedir_xdg([Type|Types]) -> + Name = "some_app", + Opt = #{os=>linux}, + Key = basedir_xdg_env(Type), + io:format("type: ~p~n", [Type]), + Home = os:getenv("HOME"), + NDir = "/some/absolute/path", + DefPath = basedir_xdg_def(Type,Home,Name), + EnvPath = case Type of + user_log -> filename:join([NDir,Name,"log"]); + site_data -> [filename:join([NDir,Name])]; + site_config -> [filename:join([NDir,Name])]; + _ -> filename:join([NDir,Name]) + end, + os:unsetenv(Key), + ok = check_basedir(Type, DefPath, filename:basedir(Type, Name, Opt)), + os:putenv(Key, NDir), + ok = check_basedir(Type, EnvPath, filename:basedir(Type, Name, Opt)), + os:unsetenv(Key), + ok = check_basedir(Type, DefPath, filename:basedir(Type, Name, Opt)), + check_basedir_xdg(Types). + +check_basedir(Type, Path, Basedir) -> + io:format("~w: ~p = ~p~n", [Type,Path,Basedir]), + Path = Basedir, + ok. + +basedir_xdg_env(Type) -> + case Type of + user_data -> "XDG_DATA_HOME"; + user_config -> "XDG_CONFIG_HOME"; + user_cache -> "XDG_CACHE_HOME"; + user_log -> "XDG_CACHE_HOME"; + site_data -> "XDG_DATA_DIRS"; + site_config -> "XDG_CONFIG_DIRS" + end. + +basedir_xdg_def(Type,Home,Name) -> + case Type of + user_data -> filename:join([Home,".local","share",Name]); + user_config -> filename:join([Home,".config",Name]); + user_cache -> filename:join([Home,".cache",Name]); + user_log -> filename:join([Home,".cache",Name,"log"]); + site_data -> [filename:join([Dir,Name]) || + Dir <- ["/usr/local/share/","/usr/share/"]]; + site_config -> [filename:join(["/etc/xdg",Name])] + end. |