1File::BaseDir(3) User Contributed Perl Documentation File::BaseDir(3)
2
6 File::BaseDir - Use the Freedesktop.org base directory specification
7
9 version 0.09
10
12 use File::BaseDir qw/xdg_data_files/;
13 for ( xdg_data_files('mime/globs') ) {
14 # do something
15 }
16
18 This module can be used to find directories and files as specified by
19 the Freedesktop.org Base Directory Specification. This specifications
20 gives a mechanism to locate directories for configuration, application
21 data and cache data. It is suggested that desktop applications for e.g.
22 the GNOME, KDE or Xfce platforms follow this layout. However, the same
23 layout can just as well be used for non-GUI applications.
24 This module forked from File::MimeInfo.
26 This module follows version 0.6 of BaseDir specification.
28
30 new
31 my $bd = File::BaseDir->new;
32 Simple constructor to allow calling functions as object oriented
34 methods.
35
37 None of these are exported by default, but all functions can be
38 exported by request. Also the groups ":lookup" and ":vars" are
39 defined. The ":vars" group contains all the routines with a "xdg_"
40 prefix. The ":lookup" group contains the routines to locate files and
41 directories.
42 data_home
44 my $path = data_home(@path);
45 my $path = $bd->data_home(@path);
46 Takes a list of file path elements and returns a new path by appending
48 them to the data home directory. The new path does not need to exist.
49 Use this when writing user specific application data.
50 Example:
52 # data_home is: /home/USER/.local/share
54 $path = $bd->data_home('Foo', 'Bar', 'Baz');
55 # returns: /home/USER/.local/share/Foo/Bar/Baz
56 data_dirs
58 # :lookup
59 my $dir = data_dirs(@path);
60 my $dir = $bd->data_dirs(@path);
61 my @dirs = data_dirs(@path);
62 my @dirs = $bd->data_dirs(@path);
63 Looks for directories specified by @path in the data home and other
65 data directories. Returns (possibly empty) list of readable
66 directories. In scalar context only the first directory found is
67 returned. Use this to lookup application data.
68 data_files
70 # :lookup
71 my $file = data_files(@path);
72 my $file = $bd->data_files(@path);
73 my @files = data_files(@path);
74 my @files = $bd->data_files(@path);
75 Looks for files specified by @path in the data home and other data
77 directories. Only returns files that are readable. In scalar context
78 only the first file found is returned. Use this to lookup application
79 data.
80 config_home
82 # :lookup
83 my $dir = config_home(@path);
84 my $dir = $bd->config_home(@path);
85 Takes a list of path elements and appends them to the config home
87 directory returning a new path. The new path does not need to exist.
88 Use this when writing user specific configuration.
89 config_dirs
91 # :lookup
92 my $dir = config_dirs(@path);
93 my $dir = $bd->config_dirs(@path);
94 my @dirs = config_dirs(@path);
95 my @dirs = $bd->config_dirs(@path);
96 Looks for directories specified by @path in the config home and other
98 config directories. Returns (possibly empty) list of readable
99 directories. In scalar context only the first directory found is
100 returned. Use this to lookup configuration.
101 config_files
103 # :lookup
104 my $file = config_files(@path);
105 my $file = $bd->config_files(@path);
106 my @files = config_files(@path);
107 my @files = $bd->config_files(@path);
108 Looks for files specified by @path in the config home and other config
110 directories. Returns a (possibly empty) list of files that are
111 readable. In scalar context only the first file found is returned. Use
112 this to lookup configuration.
113 cache_home
115 # :lookup
116 my $dir = cache_home(@path);
117 my $dir = $bd->cache_home(@path);
118 Takes a list of path elements and appends them to the cache home
120 directory returning a new path. The new path does not need to exist.
121 xdg_data_home
123 # :var
124 my $dir = xdg_data_home;
125 my $dir = $bd->xdg_data_home;
126 Returns either $ENV{XDG_DATA_HOME} or it's default value. Default is
128 $HOME/.local/share.
129 xdg_data_dirs
131 # :var
132 my @dirs = xdg_data_dirs;
133 my @dirs = $bd->xdg_data_dirs;
134 Returns either $ENV{XDG_DATA_DIRS} or it's default value as list.
136 Default is /usr/local/share, /usr/share.
137 xdg_config_home
139 # :var
140 my $dir = xdg_config_home;
141 my $dir = $bd->xdg_config_home;
142 Returns either $ENV{XDG_CONFIG_HOME} or it's default value. Default is
144 $HOME/.config.
145 xdg_config_dirs
147 # :var
148 my @dirs = xdg_config_dirs;
149 my @dirs = $bd->xdg_config_dirs;
150 Returns either $ENV{XDG_CONFIG_DIRS} or it's default value as list.
152 Default is /etc/xdg.
153 xdg_cache_home
155 # :var
156 my $dir = xdg_cache_home;
157 my $dir = $bd->xdg_cache_home;
158 Returns either $ENV{XDG_CACHE_HOME} or it's default value. Default is
160 $HOME/.cache.
161
163 The use of File::Spec ensures that all paths are returned in their
164 native formats regardless of platform. On Windows this module will use
165 the native environment variables, rather than the default on UNIX
166 (which is traditionally $HOME).
167 Please note that the specification is targeting Unix platforms only and
169 will only have limited relevance on other platforms. Any platform
170 dependent behavior in this module should be considered an extension of
171 the spec.
172
174 The methods xdg_data_files() and xdg_config_files() are exported for
175 backwards compatibility with version 0.02. They are identical to
176 data_files() and config_files() respectively but without the
177 "wantarray" behavior.
178
180 • Jaap Karssenberg || Pardus [Larus] <pardus@cpan.org>
181 • Graham Ollis <plicease@cpan.org>
183
185 This software is copyright (c) 2003-2021 by Jaap Karssenberg || Pardus
186 [Larus] <pardus@cpan.org>.
187 This is free software; you can redistribute it and/or modify it under
189 the same terms as the Perl 5 programming language system itself.
190perl v5.36.0 2023-01-20 File::BaseDir(3)