File Coverage

blib/lib/File/HomeDir/FreeDesktop.pm
Criterion Covered Total %
statement 27 47 57.4
branch 0 6 0.0
condition n/a
subroutine 10 28 35.7
pod 0 17 0.0
total 37 98 37.7


line stmt bran cond sub pod time code
1             package File::HomeDir::FreeDesktop;
2              
3             # Specific functionality for unixes running free desktops
4             # compatible with (but not using) File-BaseDir-0.03
5              
6             # See POD at the end of the file for more documentation.
7              
8 1     1   735 use 5.008003;
  1         3  
9 1     1   4 use strict;
  1         2  
  1         24  
10 1     1   18 use warnings;
  1         3  
  1         22  
11 1     1   4 use Carp ();
  1         1  
  1         51  
12 1     1   6 use File::Spec ();
  1         2  
  1         19  
13 1     1   427 use File::Which ();
  1         827  
  1         16  
14 1     1   6 use File::HomeDir::Unix ();
  1         2  
  1         15  
15              
16 1     1   3 use vars qw{$VERSION};
  1         2  
  1         31  
17 1     1   5 use base "File::HomeDir::Unix";
  1         1  
  1         80  
18              
19             BEGIN
20             {
21 1     1   388 $VERSION = '1.003_002';
22             }
23              
24             # xdg uses $ENV{XDG_CONFIG_HOME}/user-dirs.dirs to know where are the
25             # various "my xxx" directories. That is a shell file. The official API
26             # is the xdg-user-dir executable. It has no provision for assessing
27             # the directories of a user that is different than the one we are
28             # running under; the standard substitute user mechanisms are needed to
29             # overcome this.
30              
31             my $xdgprog = File::Which::which('xdg-user-dir');
32              
33             sub _my
34             {
35             # No quoting because input is hard-coded and only comes from this module
36 0     0     my $thingy = qx($xdgprog $_[1]);
37 0           chomp $thingy;
38 0           return $thingy;
39             }
40              
41             # Simple stuff
42 0     0 0   sub my_desktop { shift->_my('DESKTOP') }
43 0     0 0   sub my_documents { shift->_my('DOCUMENTS') }
44 0     0 0   sub my_music { shift->_my('MUSIC') }
45 0     0 0   sub my_pictures { shift->_my('PICTURES') }
46 0     0 0   sub my_videos { shift->_my('VIDEOS') }
47              
48             sub my_data
49             {
50             $ENV{XDG_DATA_HOME}
51 0 0   0 0   or File::Spec->catdir(shift->my_home, qw{ .local share });
52             }
53              
54             sub my_config
55             {
56             $ENV{XDG_CONFIG_HOME}
57 0 0   0 0   or File::Spec->catdir(shift->my_home, qw{ .config });
58             }
59              
60             # Custom locations (currently undocumented)
61 0     0 0   sub my_download { shift->_my('DOWNLOAD') }
62 0     0 0   sub my_publicshare { shift->_my('PUBLICSHARE') }
63 0     0 0   sub my_templates { shift->_my('TEMPLATES') }
64              
65             sub my_cache
66             {
67             $ENV{XDG_CACHE_HOME}
68 0 0   0 0   || File::Spec->catdir(shift->my_home, qw{ .cache });
69             }
70              
71             #####################################################################
72             # General User Methods
73              
74 0     0 0   sub users_desktop { Carp::croak('The users_desktop method is not available on an XDG based system.'); }
75 0     0 0   sub users_documents { Carp::croak('The users_documents method is not available on an XDG based system.'); }
76 0     0 0   sub users_music { Carp::croak('The users_music method is not available on an XDG based system.'); }
77 0     0 0   sub users_pictures { Carp::croak('The users_pictures method is not available on an XDG based system.'); }
78 0     0 0   sub users_videos { Carp::croak('The users_videos method is not available on an XDG based system.'); }
79 0     0 0   sub users_data { Carp::croak('The users_data method is not available on an XDG based system.'); }
80              
81             1;
82              
83             =pod
84              
85             =head1 NAME
86              
87             File::HomeDir::FreeDesktop - Find your home and other directories on FreeDesktop.org Unix
88              
89             =head1 DESCRIPTION
90              
91             This module provides implementations for determining common user
92             directories. In normal usage this module will always be
93             used via L.
94              
95             This module can operate only when the command C is available
96             and executable, which is typically achieved by installed a package named
97             C or similar.
98              
99             One can find the latest spec at L.
100              
101             =head1 SYNOPSIS
102              
103             use File::HomeDir;
104            
105             # Find directories for the current user
106             $home = File::HomeDir->my_home; # /home/mylogin
107             $desktop = File::HomeDir->my_desktop;
108             $docs = File::HomeDir->my_documents;
109             $music = File::HomeDir->my_music;
110             $pics = File::HomeDir->my_pictures;
111             $videos = File::HomeDir->my_videos;
112             $data = File::HomeDir->my_data;
113             $config = File::HomeDir->my_config;
114            
115             # Some undocumented ones, expect they don't work - use with caution
116             $download = File::HomeDir->my_download;
117             $publicshare = File::HomeDir->my_publicshare;
118             $templates = File::HomeDir->my_templates;
119             $cache = File::HomeDir->my_cache;
120              
121             =head1 AUTHORS
122              
123             Jerome Quelin Ejquellin@cpan.org
124              
125             Adam Kennedy Eadamk@cpan.orgE
126              
127             =head1 SEE ALSO
128              
129             L, L (legacy)
130              
131             =head1 COPYRIGHT
132              
133             Copyright 2009 - 2011 Jerome Quelin.
134              
135             Some parts copyright 2010 Adam Kennedy.
136              
137             This program is free software; you can redistribute
138             it and/or modify it under the same terms as Perl itself.
139              
140             The full text of the license can be found in the
141             LICENSE file included with this module.
142              
143             =cut