File::BaseDir(3pm)

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

SYNOPSIS

9               use File::BaseDir qw/xdg_data_files/;
10               for ( xdg_data_files('mime/globs') ) {
11                       # do something
12               }
13

DESCRIPTION

15       This module can be used to find directories and files as specified by
16       the Freedesktop.org Base Directory Specification. This specifications
17       gives a mechanism to locate directories for configuration, application
18       data and cache data. It is suggested that desktop applications for e.g.
19       the Gnome, KDE or Xfce platforms follow this layout. However, the same
20       layout can just as well be used for non-GUI applications.
21
22       This module forked from File::MimeInfo.
23
24       This module follows version 0.6 of BaseDir specification.
25

EXPORT

27       None by default, but all methods can be exported on demand.  Also the
28       groups ":lookup" and ":vars" are defined. The ":vars" group contains
29       all routines with a "xdg_" prefix; the ":lookup" group contains the
30       routines to locate files and directories.
31

METHODS

33       "new()"
34           Simple constructor to allow Object Oriented use of this module.
35
36   Lookup
37       The following methods are used to lookup files and folders in one of
38       the search paths.
39
40       "data_home(@PATH)"
41           Takes a list of file path elements and returns a new path by
42           appending them to the data home directory. The new path does not
43           need to exist.  Use this when writing user specific application
44           data.
45
46           Example:
47
48             # data_home is: /home/USER/.local/share
49             $path = $bd->data_home('Foo', 'Bar', 'Baz');
50             # returns: /home/USER/.local/share/Foo/Bar/Baz
51
52       "data_dirs(@PATH)"
53           Looks for directories specified by @PATH in the data home and other
54           data directories. Returns (possibly empty) list of readable
55           directories. In scalar context only the first directory found is
56           returned. Use this to lookup application data.
57
58       "data_files(@PATH)"
59           Looks for files specified by @PATH in the data home and other data
60           directories. Only returns files that are readable. In scalar
61           context only the first file found is returned. Use this to lookup
62           application data.
63
64       "config_home(@PATH)"
65           Takes a list of path elements and appends them to the config home
66           directory returning a new path. The new path does not need to
67           exist.  Use this when writing user specific configuration.
68
69       "config_dirs(@PATH)"
70           Looks for directories specified by @PATH in the config home and
71           other config directories. Returns (possibly empty) list of readable
72           directories. In scalar context only the first directory found is
73           returned. Use this to lookup configuration.
74
75       "config_files(@PATH)"
76           Looks for files specified by @PATH in the config home and other
77           config directories. Returns a (possibly empty) list of files that
78           are readable. In scalar context only the first file found is
79           returned.  Use this to lookup configuration.
80
81       "cache_home(@PATH)"
82           Takes a list of path elements and appends them to the cache home
83           directory returning a new path. The new path does not need to
84           exist.
85
86   Variables
87       The following methods only returns the value of one of the XDG
88       variables.
89
90       "xdg_data_home"
91           Returns either $ENV{XDG_DATA_HOME} or it's default value.  Default
92           is $HOME/.local/share.
93
94       "xdg_data_dirs"
95           Returns either $ENV{XDG_DATA_DIRS} or it's default value as list.
96           Default is /usr/local/share, /usr/share.
97
98       "xdg_config_home"
99           Returns either $ENV{XDG_CONFIG_HOME} or it's default value.
100           Default is $HOME/.config.
101
102       "xdg_config_dirs"
103           Returns either $ENV{XDG_CONFIG_DIRS} or it's default value as list.
104           Default is /etc/xdg.
105
106       "xdg_cache_home"
107           Returns either $ENV{XDG_CACHE_HOME} or it's default value.  Default
108           is $HOME/.cache.
109

NON-UNIX PLATFORMS

111       The use of File::Spec ensures that all paths are returned in the
112       appropriate form for the current platform. On Windows this module will
113       try to set $HOME to a sensible value if it is not defined yet. On other
114       platforms one can use e.g. File::HomeDir to set $HOME before loading
115       File::BaseDir.
116
117       Please note that the specification is targeting Unix platforms only and
118       will only have limited relevance on other platforms. Any platform
119       dependent behavior in this module should be considered an extension of
120       the spec.
121

BACKWARDS COMPATIBILITY

123       The methods "xdg_data_files()" and "xdg_config_files()" are exported
124       for backwards compatibility with version 0.02. They are identical to
125       "data_files()" and "config_files()" respectively but without the
126       "wantarray" behavior.
127

BUGS

129       Please mail the author if you encounter any bugs.
130

AUTHOR

132       Jaap Karssenberg || Pardus [Larus] <pardus@cpan.org>
133
134       Copyright (c) 2003, 2007 Jaap G Karssenberg. All rights reserved.  This
135       program is free software; you can redistribute it and/or modify it
136       under the same terms as Perl itself.
137
138       Currently being maintained by Kim Ryan
139