1File::BaseDir(3)      User Contributed Perl Documentation     File::BaseDir(3)
2
3
4

NAME

6       File::BaseDir - Use the Freedesktop.org base directory specification
7

VERSION

9       version 0.09
10

SYNOPSIS

12        use File::BaseDir qw/xdg_data_files/;
13        for ( xdg_data_files('mime/globs') ) {
14          # do something
15        }
16

DESCRIPTION

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
25       This module forked from File::MimeInfo.
26
27       This module follows version 0.6 of BaseDir specification.
28

CONSTRUCTOR

30   new
31        my $bd = File::BaseDir->new;
32
33       Simple constructor to allow calling functions as object oriented
34       methods.
35

FUNCTIONS

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
43   data_home
44        my $path = data_home(@path);
45        my $path = $bd->data_home(@path);
46
47       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
51       Example:
52
53        # 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
57   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
64       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
69   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
76       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
81   config_home
82        # :lookup
83        my $dir = config_home(@path);
84        my $dir = $bd->config_home(@path);
85
86       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
90   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
97       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
102   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
109       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
114   cache_home
115        # :lookup
116        my $dir = cache_home(@path);
117        my $dir = $bd->cache_home(@path);
118
119       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
122   xdg_data_home
123        # :var
124        my $dir = xdg_data_home;
125        my $dir = $bd->xdg_data_home;
126
127       Returns either $ENV{XDG_DATA_HOME} or it's default value.  Default is
128       $HOME/.local/share.
129
130   xdg_data_dirs
131        # :var
132        my @dirs = xdg_data_dirs;
133        my @dirs = $bd->xdg_data_dirs;
134
135       Returns either $ENV{XDG_DATA_DIRS} or it's default value as list.
136       Default is /usr/local/share, /usr/share.
137
138   xdg_config_home
139        # :var
140        my $dir = xdg_config_home;
141        my $dir = $bd->xdg_config_home;
142
143       Returns either $ENV{XDG_CONFIG_HOME} or it's default value.  Default is
144       $HOME/.config.
145
146   xdg_config_dirs
147        # :var
148        my @dirs = xdg_config_dirs;
149        my @dirs = $bd->xdg_config_dirs;
150
151       Returns either $ENV{XDG_CONFIG_DIRS} or it's default value as list.
152       Default is /etc/xdg.
153
154   xdg_cache_home
155        # :var
156        my $dir = xdg_cache_home;
157        my $dir = $bd->xdg_cache_home;
158
159       Returns either $ENV{XDG_CACHE_HOME} or it's default value.  Default is
160       $HOME/.cache.
161

NON-UNIX PLATFORMS

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
168       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

BACKWARDS COMPATIBILITY

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

AUTHORS

180       •   Jaap Karssenberg || Pardus [Larus] <pardus@cpan.org>
181
182       •   Graham Ollis <plicease@cpan.org>
183
185       This software is copyright (c) 2003-2021 by Jaap Karssenberg || Pardus
186       [Larus] <pardus@cpan.org>.
187
188       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.
190
191
192
193perl v5.36.0                      2023-01-20                  File::BaseDir(3)
Impressum