File-HomeDir-1.004/0000755000175000017500000000000013272255100012077 5ustar snosnoFile-HomeDir-1.004/t/0000755000175000017500000000000013272255100012342 5ustar snosnoFile-HomeDir-1.004/t/20_empty_home.t0000644000175000017500000000055713251234150015204 0ustar snosno#!/usr/bin/perl use strict; use warnings; BEGIN { $| = 1; $^W = 1; $ENV{HOME} = ''; } use Test::More; use File::HomeDir; plan skip_all => "Skipping empty \$ENV{HOME} test on $^O since there is no fallback" if ($^O eq 'MSWin32'); plan(tests => 1); my $home = (getpwuid($<))[7]; is scalar File::HomeDir->my_home, $home, 'my_home found'; File-HomeDir-1.004/t/02_main.t0000644000175000017500000002016213251731326013763 0ustar snosno#!/usr/bin/perl # Main testing for File::HomeDir # Testing "home directory" concepts is blood difficult, be delicate in # your changes and don't forget to test on every OS at multiple versions # (WinXP vs Win2003 etc) as both root and non-root users. use strict; BEGIN { $| = 1; $^W = 1; } use File::Spec::Functions ':ALL'; use Test::More; use File::HomeDir; # This module is destined for the core. # Please do NOT use convenience modules # use English; <-- don't do this sub is_dir($) { my $dir = shift or return; return 1 if -d $dir; return unless -l $dir; $dir = readlink $dir or return; return -d $dir; } ##################################################################### # Environment Detection and Plan # For what scenarios can we be sure that we have desktop/documents my $NO_GETPWUID = 0; my $HAVEHOME = 0; my $HAVEDESKTOP = 0; my $HAVEMUSIC = 0; my $HAVEPICTURES = 0; my $HAVEVIDEOS = 0; my $HAVEDOCUMENTS = 0; my $HAVEOTHERS = 0; # Various cases of things we should try to test for # Top level is entire classes of operating system. # Below that are more general things. if ($^O eq 'MSWin32') { $NO_GETPWUID = 1; $HAVEHOME = 1; $HAVEDESKTOP = 1; $HAVEPICTURES = 1; $HAVEDOCUMENTS = 1; $HAVEOTHERS = 1; # My Music does not exist on Win2000 require Win32; my @version = Win32::GetOSVersion(); my $v = ($version[4] || 0) + ($version[1] || 0) * 0.001 + ($version[2] || 0) * 0.000001; if ($v <= 2.005000) { $HAVEMUSIC = 0; $HAVEVIDEOS = 0; } else { $HAVEMUSIC = 1; $HAVEVIDEOS = 0; # If we ever support "maybe" this is a maybe } # System is unix-like # Nobody users on all unix systems generally don't have home directories } elsif (getpwuid($<) eq 'nobody') { $HAVEHOME = 0; $HAVEDESKTOP = 0; $HAVEMUSIC = 0; $HAVEPICTURES = 0; $HAVEVIDEOS = 0; $HAVEOTHERS = 0; } elsif ($^O eq 'darwin') { # "Unixes with proper desktops" special cases diag("\$<: $< -- \$(: $("); if ($ENV{AUTOMATED_TESTING}) { # Automated testers on Mac (notably BINGOS) will often have # super stripped down testing users. $HAVEHOME = 1; $HAVEDESKTOP = 1; $HAVEMUSIC = 0; $HAVEPICTURES = 0; $HAVEVIDEOS = 0; $HAVEDOCUMENTS = 0; $HAVEOTHERS = 1; } elsif ($< > 500) { # Normal user $HAVEHOME = 1; $HAVEDESKTOP = 1; $HAVEMUSIC = 1; $HAVEPICTURES = 1; $HAVEVIDEOS = 1; $HAVEDOCUMENTS = 1; $HAVEOTHERS = 1; } else { # Root can only be relied on to have a home $HAVEHOME = 1; $HAVEDESKTOP = 0; $HAVEMUSIC = 0; $HAVEPICTURES = 0; $HAVEVIDEOS = 0; $HAVEDOCUMENTS = 0; $HAVEOTHERS = 0; } } elsif ($File::HomeDir::IMPLEMENTED_BY eq 'File::HomeDir::FreeDesktop') { # On FreeDesktop we can't trust people to have a desktop (annoyingly) $HAVEHOME = 1; $HAVEDESKTOP = 0; $HAVEMUSIC = 0; $HAVEVIDEOS = 0; $HAVEPICTURES = 0; $HAVEDOCUMENTS = 0; $HAVEOTHERS = 0; } else { # Default to traditional Unix $HAVEHOME = 1; $HAVEDESKTOP = 1; $HAVEMUSIC = 1; $HAVEPICTURES = 1; $HAVEVIDEOS = 1; $HAVEDOCUMENTS = 1; $HAVEOTHERS = 1; } plan tests => 39; ##################################################################### # Test invalid uses eval { home(undef); }; like($@, qr{Can\'t use undef as a username}, 'home(undef)'); ##################################################################### # API Test # Check the methods all exist foreach (qw{ home desktop documents music pictures videos data }) { can_ok('File::HomeDir', "my_$_"); can_ok('File::HomeDir', "users_$_"); } ##################################################################### # Main Tests # Find this user's homedir my $home = home(); if ($HAVEHOME) { ok(!!($home and is_dir $home), 'Found our home directory'); } else { is($home, undef, 'Confirmed no home directory'); } # this call is not tested: # File::HomeDir->home # Find this user's home explicitly my $my_home = File::HomeDir->my_home; if ($HAVEHOME) { ok(!!($home and is_dir $home), 'Found our home directory'); } else { is($home, undef, 'Confirmed no home directory'); } # check that $ENV{HOME} is honored if set { local $ENV{HOME} = rel2abs('.'); is(File::HomeDir->my_home(), $ENV{HOME}, "my_home() returns $ENV{HOME}"); } my $my_home2 = File::HomeDir::my_home(); if ($HAVEHOME) { ok(!!($my_home2 and is_dir $my_home2), 'Found our home directory'); } else { is($home, undef, 'No home directory, as expected'); } is($home, $my_home2, 'Different APIs give same results'); # shall we test using -w if the home directory is writable ? # Find this user's documents SKIP: { my $my_documents = File::HomeDir->my_documents; my $my_documents2 = File::HomeDir::my_documents(); is($my_documents, $my_documents2, 'Different APIs give the same results'); skip("Cannot assume existence of documents", 2) unless $HAVEDOCUMENTS; ok(!!($my_documents and is_dir $my_documents), 'Found our documents directory'); ok(!!($my_documents2 and $my_documents2), 'Found our documents directory'); } # Find this user's pictures directory SKIP: { skip("Cannot assume existence of pictures", 3) unless $HAVEPICTURES; my $my_pictures = File::HomeDir->my_pictures; my $my_pictures2 = File::HomeDir::my_pictures(); is($my_pictures, $my_pictures2, 'Different APIs give the same results'); ok(!!($my_pictures and is_dir $my_pictures), 'Our pictures directory exists'); ok(!!($my_pictures2 and is_dir $my_pictures2), 'Our pictures directory exists'); } # Find this user's music directory SKIP: { skip("Cannot assume existence of music", 3) unless $HAVEMUSIC; my $my_music = File::HomeDir->my_music; my $my_music2 = File::HomeDir::my_music(); is($my_music, $my_music2, 'Different APIs give the same results'); ok(!!($my_music and is_dir $my_music), 'Our music directory exists'); ok(!!($my_music2 and is_dir $my_music2), 'Our music directory exists'); } # Find this user's video directory SKIP: { skip("Cannot assume existence of videos", 3) unless $HAVEVIDEOS; my $my_videos = File::HomeDir->my_videos; my $my_videos2 = File::HomeDir::my_videos(); is($my_videos, $my_videos2, 'Different APIs give the same results'); ok(!!($my_videos and is_dir $my_videos), 'Our videos directory exists'); ok(!!($my_videos2 and is_dir $my_videos2), 'Our videos directory exists'); } # Desktop cannot be assumed in all environments SKIP: { skip("Cannot assume existence of desktop", 3) unless $HAVEDESKTOP; # Find this user's desktop data my $my_desktop = File::HomeDir->my_desktop; my $my_desktop2 = File::HomeDir::my_desktop(); is($my_desktop, $my_desktop2, 'Different APIs give the same results'); ok(!!($my_desktop and is_dir $my_desktop), 'Our desktop directory exists'); ok(!!($my_desktop2 and is_dir $my_desktop2), 'Our desktop directory exists'); } # Find this user's local data SKIP: { skip("Cannot assume existence of application data", 3) unless $HAVEOTHERS; my $my_data = File::HomeDir->my_data; my $my_data2 = File::HomeDir::my_data(); is($my_data, $my_data2, 'Different APIs give the same results'); ok(!!($my_data and is_dir $my_data), 'Found our local data directory'); ok(!!($my_data2 and is_dir $my_data2), 'Found our local data directory'); } # Shall we check name space pollution by testing functions in main before # and after calling use ? # On platforms other than windows, find root's homedir SKIP: { if ($^O eq 'MSWin32' or $^O eq 'cygwin' or $^O eq 'darwin') { skip("Skipping root test on $^O", 1); } # Determine root my $root = getpwuid(0); unless ($root) { skip("Skipping, can't determine root", 1); } # Get root's homedir my $root_home1 = home($root); ok(!!($root_home1 and is_dir $root_home1), "Found root's home directory"); } File-HomeDir-1.004/t/10_test.t0000644000175000017500000000146013251234150014006 0ustar snosno#!/usr/bin/perl # Testing for the test driver use strict; BEGIN { $| = 1; $^W = 1; } use File::Spec::Functions ':ALL'; use Test::More tests => 30; use File::HomeDir::Test; use File::HomeDir; # Is the test driver enabled? is($File::HomeDir::Test::ENABLED, 1, 'File::HomeDir::Test is enabled'); is($File::HomeDir::IMPLEMENTED_BY, 'File::HomeDir::Test', 'IMPLEMENTED_BY is correct'); # Was everything hijacked correctly? foreach my $method ( qw{ my_home my_desktop my_documents my_data my_music my_pictures my_videos } ) { my $dir = File::HomeDir->$method(); ok($dir, "$method: Got a directory"); ok(-d $dir, "$method: Directory exists at $dir"); ok(-r $dir, "$method: Directory is readable"); ok(-w $dir, "$method: Directory is writeable"); } File-HomeDir-1.004/t/11_darwin.t0000644000175000017500000000426413251234150014321 0ustar snosno#!/usr/bin/perl use strict; BEGIN { $| = 1; $^W = 1; } use Test::More; use File::HomeDir; if ($File::HomeDir::IMPLEMENTED_BY->isa('File::HomeDir::Darwin')) { # Force pure perl since it should work everywhere $File::HomeDir::IMPLEMENTED_BY = 'File::HomeDir::Darwin'; plan(tests => 9); } else { plan(skip_all => "Not running on Darwin"); exit(0); } SKIP: { my $user; foreach (0 .. 9) { my $temp = sprintf 'fubar%04d', rand(10000); getpwnam $temp and next; $user = $temp; last; } $user or skip("Unable to find non-existent user", 1); $@ = undef; my $home = eval { File::HomeDir->users_home($user) }; $@ and skip("Unable to execute File::HomeDir->users_home('$user')", 1); ok(!defined $home, "Home of non-existent user should be undef"); } SCOPE: { # Reality Check my $music = File::HomeDir->my_music; my $videos = File::HomeDir->my_videos; my $pictures = File::HomeDir->my_pictures; my $data = File::HomeDir->my_data; SKIP: { skip("No music directory", 1) unless defined $music; like($music, qr/Music/); } SKIP: { skip("Have music directory", 1) if defined $music; is_deeply([File::HomeDir->my_music], [undef], "Returns undef in list context",); } SKIP: { skip("No videos directory", 1) unless defined $videos; like($videos, qr/Movies/); } SKIP: { skip("Have videos directory", 1) if defined $videos; is_deeply([File::HomeDir->my_videos], [undef], "Returns undef in list context",); } SKIP: { skip("No pictures directory", 1) unless defined $pictures; like($pictures, qr/Pictures/); } SKIP: { skip("Have pictures directory", 1) if defined $pictures; is_deeply([File::HomeDir->my_pictures], [undef], "Returns undef in list context",); } SKIP: { skip("No application support directory", 1) unless defined $data; like($data, qr/Application Support/); } SKIP: { skip("Have data directory", 1) if defined $data; is_deeply([File::HomeDir->my_data], [undef], "Returns undef in list context",); } } File-HomeDir-1.004/t/13_darwin_cocoa.t0000644000175000017500000000330513251234150015462 0ustar snosno#!/usr/bin/perl use strict; BEGIN { $| = 1; $^W = 1; } use Test::More; use File::HomeDir; if ($File::HomeDir::IMPLEMENTED_BY->isa('File::HomeDir::Darwin') and eval "require Mac::SystemDirectory; 1") { # Force Cocoa if you have Mac::SystemDirectory require File::HomeDir::Darwin::Cocoa; $File::HomeDir::IMPLEMENTED_BY = 'File::HomeDir::Darwin::Cocoa'; plan(tests => 5); } else { plan(skip_all => "Not running on Darwin with Cocoa API using Mac::SystemDirectory"); exit(0); } SKIP: { my $user; foreach (0 .. 9) { my $temp = sprintf 'fubar%04d', rand(10000); getpwnam $temp and next; $user = $temp; last; } $user or skip("Unable to find non-existent user", 1); $@ = undef; my $home = eval { File::HomeDir->users_home($user) }; $@ and skip("Unable to execute File::HomeDir->users_home('$user')", 1); ok(!defined $home, "Home of non-existent user should be undef"); } SCOPE: { # Reality Check my $music = File::HomeDir->my_music; my $video = File::HomeDir->my_videos; my $pictures = File::HomeDir->my_pictures; SKIP: { skip("No music directory", 1) unless defined $music; like(File::HomeDir->my_music, qr/Music/); } SKIP: { skip("No videos directory", 1) unless defined $video; like(File::HomeDir->my_videos, qr/Movies/); } SKIP: { skip("No pictures directory", 1) unless defined $pictures; like(File::HomeDir->my_pictures, qr/Pictures/); } SKIP: { my $data = File::HomeDir->my_data; skip("No application support directory", 1) unless defined $data; like($data, qr/Application Support/); } } File-HomeDir-1.004/t/12_darwin_carbon.t0000644000175000017500000000300613251234150015637 0ustar snosno#!/usr/bin/perl use strict; BEGIN { $| = 1; $^W = 1; } use Test::More; use File::HomeDir; if ($File::HomeDir::IMPLEMENTED_BY->isa('File::HomeDir::Darwin::Carbon')) { plan(tests => 5); } else { plan(skip_all => "Not running on 32-bit Darwin"); exit(0); } SKIP: { my $user; foreach (0 .. 9) { my $temp = sprintf 'fubar%04d', rand(10000); getpwnam $temp and next; $user = $temp; last; } $user or skip("Unable to find non-existent user", 1); $@ = undef; my $home = eval { File::HomeDir->users_home($user) }; $@ and skip("Unable to execute File::HomeDir->users_home('$user')"); ok(!defined $home, "Home of non-existent user should be undef"); } # CPAN Testers results suggest we can't reasonably assume these directories # will always exist SKIP: { my $dir = File::HomeDir->my_music; unless (defined $dir) { skip("Testing user does not have a Music directory", 1); } like($dir, qr/Music/); } SKIP: { my $dir = File::HomeDir->my_videos; unless (defined $dir) { skip("Testing user does not have a Movies directory", 1); } like($dir, qr/Movies/); } SKIP: { my $dir = File::HomeDir->my_pictures; unless (defined $dir) { skip("Testing user does not have a Pictures directory", 1); } like($dir, qr/Pictures/); } SKIP: { my $data = File::HomeDir->my_data; skip("No application support directory", 1) unless defined $data; like($data, qr/Application Support/); } File-HomeDir-1.004/t/01_compile.t0000644000175000017500000000165513251234150014465 0ustar snosno#!/usr/bin/perl # Compile-testing for File::HomeDir use strict; BEGIN { $| = 1; $^W = 1; } use File::Spec::Functions ':ALL'; use Test::More tests => 11; # This module is destined for the core. # Please do NOT use convenience modules # use English; <-- don't do this ok($] > 5.008003, 'Perl version is 5.005 or newer'); use_ok('File::HomeDir::Driver'); use_ok('File::HomeDir::Unix'); use_ok('File::HomeDir::FreeDesktop'); use_ok('File::HomeDir::Darwin'); use_ok('File::HomeDir::Darwin::Carbon'); use_ok('File::HomeDir::Darwin::Cocoa'); use_ok('File::HomeDir::Windows'); use_ok('File::HomeDir::MacOS9'); use_ok('File::HomeDir'); ok(defined &home, 'Using File::HomeDir exports home()'); # Note the driver we are using for the purposes of # understanding CPAN Testers failure reports. diag("Implemented by: $File::HomeDir::IMPLEMENTED_BY"); # Prevent a warning $File::HomeDir::IMPLEMENTED_BY = $File::HomeDir::IMPLEMENTED_BY; File-HomeDir-1.004/MANIFEST0000644000175000017500000000120013272255100013221 0ustar snosnoChanges lib/File/HomeDir.pm lib/File/HomeDir/Darwin.pm lib/File/HomeDir/Darwin/Carbon.pm lib/File/HomeDir/Darwin/Cocoa.pm lib/File/HomeDir/Driver.pm lib/File/HomeDir/FreeDesktop.pm lib/File/HomeDir/MacOS9.pm lib/File/HomeDir/Test.pm lib/File/HomeDir/Unix.pm lib/File/HomeDir/Windows.pm LICENSE Makefile.PL MANIFEST This list of files MANIFEST.SKIP README.md t/01_compile.t t/02_main.t t/10_test.t t/11_darwin.t t/12_darwin_carbon.t t/13_darwin_cocoa.t t/20_empty_home.t META.yml Module YAML meta-data (added by MakeMaker) META.json Module JSON meta-data (added by MakeMaker) File-HomeDir-1.004/Changes0000644000175000017500000003015413272255013013400 0ustar snosnoChanges for Perl extension File-HomeDir 1.004 2018-05-02 - release 1.003_002 without further changes 1.003_002 2018-03-13 - build distribution on Linux - add debug message because of RT#65301 - run author tests with installed spell-checker 1.003_001 2018-03-10 - skip root homedir test for cygwin (RT#104661) - document even undocumented fetchers for FreeDesktop implementation (RT#103305) and status quo (RT#88681) - Fix several typos (RT#86426, RT#67093, PR#1) - play with https://coveralls.io/ - remove tie interface (PR#4, Thanks Yanick) - determine ->my_home when $ENV{HOME} is empty (based on PR#3) - relocate repository 1.002 2017-04-06 - regenerate README.md with correct encoding settings 1.001_001 2017-03-29 - switch to ExtUtils::MakeMaker - compatibility with blead 1.00 2012-10-19 - No functional changes - Updating to Module::Install 1.06 - Don't require documents directory on Mac under AUTOMATED_TESTING 0.99 2012-01-26 - Updating to Module::Install 1.04 - Removed deprecated interfaces from the documentation - Don't require music and video directories in FreeDesktop tests - The use of deprecated %~ now emits a warning 0.98 2011-07-07 - Updating to Module::Install 1.01 - If Win32::GetFolderPath returns a \\UNC type path do not do the normal -d sanity check, as strange and unusual bugs may occur. 0.97 2011-02-20 - Looks good, moving to production release - This should finally pass on ActivePerl Mac 0.96_04 2011-02-01 - Typo in 11_darwin.t 0.96_03 2011-01-31 - Return undef in list context on Mac as per the documentation 0.96_02 2011-01-31 - No longer assume we have Application Support, sigh 0.96_01 2011-01-31 - Removed a dubious "different users have different data" test on Macs - Removed tests for legacy %~ interface 0.95 2011-01-31 - Switch to prod version 0.94_01 2010-12-14 - More special casing in tests to deal with stripped down non-root Mac environments (mostly to make BINGOS' automated testing pass) 0.93 2010-09-15 - Production release, no changes from 0.92_05 0.92_05 2010-09-13 - use Mac::SystemDirectory for each Darwin based MacOS. (REHSACK) 0.92_04 2010-09-10 - Be less strict about desktop and others on FreeDesktop (ADAMK) 0.92_03 2010-09-06 - Adding experimental support for my_dist_config() (JQUELIN) - Adding diag comment on which drivers gets used (ADAMK) 0.92_02 2010-06-28 - Updating to Module::Install 1.00 (ADAMK) - Add a bit more docs, and tweak the existing stuff a bit (ADAMK) - Deprecated the %~ interface. It will continue to exist as an undocumented legacy interface until 2015, warnings will be issued from 2013 (ADAMK) - On FreeDesktop.org systems, root often does not have the relevant directories. Skip tests for them in the same way as we do for the Mac root users on darwin (GARU) 0.92_01 2010-06-11 - Updating to Module::Install 0.99 (ADAMK) - Adding experimental support for my_dist_data() (JQUELIN) 0.91 2010-05-23 - Moving the FreeDesktop driver to prod - Adding File::HomeDir::Test driver 0.90_04 2010-02-12 - Adding missing prereq 0.90_03 2010-02-09 - Using FreeDesktop implementation only if xdg-user-script is present, since it's now what's been used internally. This should prevent test failures seen in _02. (JQUELIN) 0.90_02 2010-01-14 - Adding support for the alternate FreeBSD xdg directory (JQUELIN) - Improved specification compliance (DAXIM) 0.90_01 2010-01-07 - WARNING: This release introduces a major backwards incompatibility for Unix users. The results returned by most methods may change. - Added complete implementation of the FreeDesktop specification and auto-detection of the Unix hosts to which it applies (JQUELIN) - 01_compile.t now loads all backends (since on most platforms, most backends will never normally be loaded). 0.89 2010-01-03 - Loosen the testing intensity on Darwin Carbon backends to prevent issues with consumer directories prevent installation entirely. 0.88 2009-11-24 - Switching to a production release 0.87_01 2009-10-03 - First developer implementation of improved Mac support 0.86 2009-03-27 - Bug fix for the 64-bit implementation 0.85_01 2009-03-27 - For 64-bit perl on Darwin, fall back to File::HomeDir::Unix as Mac::Carbon is not available 0.84 2009-03-11 - Adds support for $ENV{HOME} on Darwin - Other bug fixes on Darwin (MIYAGAWA) 0.83_01 2008-11-01 - Patch from Darin McBride to fix user_home on Darwin. 0.82 2008-10-14 - When we get more than one warning, diag the warnings so that we have actually have a chance to get rid of the extra warnings. 0.81 2008-07-03 - Updating to Module::Install 0.77 - Localising $@ during evals - Updating Perl version dependency to 5.00503 0.80 2008-06-27 - All clear on the CPAN Testers front, flipping to production 0.71_03 2008-06-25 - Removing the Server 2003 and 2008 skips that should work now that we create directories on demand. - File::HomeDir should now support "Perl on a Stick" 0.71_02 2008-04-28 - Added `my_dot_config`. - Adding a base driver class. 0.71_01 2008-04-04 - Converted from Registry checks to Win32 calls. This includes giving it the "create directory" call. - Removing the dependency on the registry modules. 0.70 2008-02-28 - Windows Server 2003 does not have Music/Pictures/etc directories (correct the test to not expect them to exist) - Make the same assumption about Windows Server 2008 0.69 2008-02-03 - No changes, incrementing for production release 0.68_01 2008-01-22 - Fixed folder detection on Darwin so that symlinks that resolve to directories are considered valid folders. Patch from David Wheeler. 0.67 2007-12-06 - No functional changes, no need to upgrade. - Upgrading to Module::Install 0.68 - Updating bundled author tests 0.66 2007-08-25 - No functional changes, no need to upgrade. (This release attempts to regain 100% CPAN Testers results) - Spurious failures on some path-levels of 5.9.0 due to a warnings bug regression. Skip the relevant test on Perl 5.9.0. - Remove a -w flag in 02_main.t so test run under tainting 0.65 2007-03-21 - Add a special case to pass users_home(current user) on to my_home (This prevents tests failing when you manually set HOME to lie about your home directory. This was mostly preventing installation with "sudo cpan -i File::HomeDir". - Upgraded to Module::Install 0.65 0.64 2017-02-08 (Stephen Steneker) - Add Makefile prequisite for a version of Mac::Carbon that properly supports Intel macs .. default Tiger install includes a buggy version [RT#24222] - No other changes from 0.63 0.63 2017-01-09 - The ability to overload HOME on any platform, even Win32, is apparently desirable. So now we support the use of HOME on Win32 for that specific case. 0.62 2017-01-02 - On WinXP, the My Videos directory (and registry entry) does not exist by default. It is created the first time Windows Movie Maker is run. - Skip the My Videos test on WinXP as a result 0.61 2017-01-02 - Verified the previous version on Win2K, WinXP, Linux and Mac OS X. - Verified as a normal user, root and nobody on most of these. - No change other than converting the version to a release version. 0.60_13 2017-01-01 - Lets try that again 0.60_12 2017-01-01 - Skip an unreliable test on older Perls 0.60_11 2017-01-01 - Reduced the basic version dependencies on Mac OS because they were unnecessary on that platform, and now Mac users don't need to upgrade PathTools. 0.60_10 2017-01-01 - More testing problems on Win2K - Adding a dependency on Win32 to access Win32::GetOSName (Dependency issues could make this backfire, so maybe will need another test cycle or two to make sure it works) 0.60_09 2017-01-01 - Sigh... cases are now known to exist where users do not have home directories. Tests refactored AGAIN do allow the "nobody" user to pass the test suite. Don't ask me WHY people might need to install a module as nobody. I don't know. But now the test suite accommodates that. - On Unix, if the home directory does not exist, for example /nonexistant, it means the user does NOT have a home directory. So in those cases, return undef instead of the /nonexistant directory. 0.60_08 2017-01-01 - Problems with Win2k hopefully finally resolved 0.60_07 2006-12-19 - Problems with testing continue to plague the module... 0.60_06 2006-12-15 - Another attempt to fix the getpwuid problem 0.60_05 2006-12-12 - Removed a build-time dependency on getpwuid 0.60_04 2006-11-02 - win32: add support for my_pictures, my_videos - darwin: add support for my_music, my_pictures, my_videos - Skip "root" tests on darwin, not supported - add POD docs with examples for o/s specific implementations 0.60_03 2006-09-20 - Cleaned up the way unimplemented method exceptions are thrown. - Fleshed out the docs a bit more. - Added an initial implementation of my_music 0.60_02 2006-07-14 - Altered testing to allow cases where there are no "toys" directories - More cleanups for Darwin in the root case - Updating dependencies to something more modern (mostly to ensure certain fixes to certain problems exist) 0.60_01 2006 # Introduces back-compatibility issues - No longer treat lack of a home directory as an error - More test written on the Israel.pm monthly meeting - Major upgrade to Darwin driver (CNANDOR) 0.58 2006-05-10 # No functional changes, upgrading has no benefit. - Upgrade Module::Install to 0.62 final - AutoInstall is only needed for options, so remove auto_install 0.57 2006-03-10 Adam Kennedy adamk@cpan.org # No functional changes, upgrading has no benefit. - Upgraded Module::Install to 0.62 (M:I is relatively sane from 0.61) - Removing all use of UNIVERSAL::isa (the function) - Adding missing use Carp() in a couple of cases - Minor POD changes 0.56 2006-03-10 Adam Kennedy adamk@cpan.org # No functional changes, upgrading has no benefit. - I screwed up Module::Install 0.58 - Fixed that, then incremented version to fix this 0.55 2006-03-05 Adam Kennedy adamk@cpan.org # No functional changes, upgrading has no benefit. - Documentation bug fix - Documented the todo list - Updated Module::Install to 0.58 0.54 2006-02-27 Adam Kennedy adamk@cpan.org - Adding a dependency of Win32::TieRegistry's, so this installs. - Will remove it later when that bug is fixed in Win32::TieRegistry 0.53 2006-02-27 Adam Kennedy adamk@cpan.org - Typo caused Makefile.PL not to require Win32::TieRegistry on Win32 - Upgraded to Module::Install 0.57 0.52 2005-01-04 Adam Kennedy adamk@cpan.org - Added initial Darwin support. 0.51 2005-12-30 Adam Kennedy adamk@cpan.org - Fixed a typo where I left the require of the Windows module as Win32. (Randy Kobes) 0.50 2005-12-26 Adam Kennedy adamk@cpan.org - Rewrote the guts entirely to split functionality out into platform-specific submodules, and to add more specialised code for Win32. 0.07 2005-11-09 Adam Kennedy adamk@cpan.org - Near-complete rewrite to modernise and prepare to start merging in File::HomeDir::Win32. - "Traded" module in exchange for Data::JavaScript::Anon :) - Replaced Makefile.PL with Module::Install-based version that lists its dependencies in a platform-sensitive way. This also removes the need for evals. - Replaced tests with Test::More-based ones and improved coverage. - Put the platform-specific code into if ( CONSTANT ) blocks so they will compile out. - Otherwise cleaned up and improved the layout of the code - Added support for $ENV{HOMEDIR} and $ENV{HOMEPATH} on Win32 - More-explicit testing before we return a path - Keep caching user home, but NOT "my" home in case the process changes user. 0.06 2004-12-29 Sean M. Burke sburke@cpan.org # No functional changes, upgrading has no benefit. - just rebundling. No code changes. 0.05 2000-12-09 Sean M. Burke sburke@cpan.org - adding MSWin code to consult the registry, as helpfully suggested by Richard Soderberg . - Tweaked MacPerl code a bit. 0.04 2000-12-09 Sean M. Burke sburke@cpan.org - just fixing incidental typos in the POD. 0.03 2000-12-08 Sean M. Burke sburke@cpan.org - first public release. File-HomeDir-1.004/META.yml0000664000175000017500000000167613272255100013364 0ustar snosno--- abstract: 'Find your home and other directories on any platform' author: - 'Adam Kennedy ' build_requires: Test::More: '0.9' configure_requires: ExtUtils::MakeMaker: '0' POSIX: '0' dynamic_config: 1 generated_by: 'ExtUtils::MakeMaker version 7.32, CPAN::Meta::Converter version 2.150005' license: perl meta-spec: url: http://module-build.sourceforge.net/META-spec-v1.4.html version: '1.4' name: File-HomeDir no_index: directory: - t - inc requires: Carp: '0' Cwd: '3.12' File::Basename: '0' File::Path: '2.01' File::Spec: '3.12' File::Temp: '0.19' File::Which: '0.05' perl: v5.8.3 resources: bugtracker: http://rt.cpan.org/Public/Dist/Display.html?Name=File-HomeDir homepage: https://metacpan.org/release/File-HomeDir license: http://dev.perl.org/licenses/ repository: https://github.com/perl5-utils/File-HomeDir.git version: '1.004' x_serialization_backend: 'CPAN::Meta::YAML version 0.018' File-HomeDir-1.004/MANIFEST.SKIP0000644000175000017500000000051313251234150013773 0ustar snosno\B\.svn\b \B\.git\b \.gitignore$ .travis.yml \.[Bb][Aa][Kk]$ \.orig$ \.old$ \.tdy$ \.tmp$ \..*swp ^Makefile$ ^Build$ ^Build\.bat$ \.Inline/.* _Inline/.* \.bak$ \.tar$ \.tgz$ \.tar\.gz$ ^mess/ ^tmp/ ^testdata/ ^blib/ ^sandbox/ ^cover_db/ ^pm_to_blib$ ^_build/.* ~$ .*\.planner ^\..* File-HomeDir-.* \bxt ^MYMETA\.json$ ^MYMETA\..*$ File-HomeDir-1.004/META.json0000664000175000017500000000430213272255100013521 0ustar snosno{ "abstract" : "Find your home and other directories on any platform", "author" : [ "Adam Kennedy " ], "dynamic_config" : 1, "generated_by" : "ExtUtils::MakeMaker version 7.32, CPAN::Meta::Converter version 2.150005", "license" : [ "perl_5" ], "meta-spec" : { "url" : "http://search.cpan.org/perldoc?CPAN::Meta::Spec", "version" : "2" }, "name" : "File-HomeDir", "no_index" : { "directory" : [ "t", "inc" ] }, "prereqs" : { "build" : { "requires" : {} }, "configure" : { "requires" : { "ExtUtils::MakeMaker" : "0", "POSIX" : "0" } }, "develop" : { "requires" : { "Module::CPANTS::Analyse" : "0.96", "Test::CPAN::Changes" : "0", "Test::CheckManifest" : "0", "Test::Kwalitee" : "0", "Test::Perl::Critic" : "0", "Test::PerlTidy" : "0", "Test::Pod" : "0", "Test::Pod::Coverage" : "0", "Test::Pod::Spelling::CommonMistakes" : "0", "Test::Spelling" : "0" } }, "runtime" : { "requires" : { "Carp" : "0", "Cwd" : "3.12", "File::Basename" : "0", "File::Path" : "2.01", "File::Spec" : "3.12", "File::Temp" : "0.19", "File::Which" : "0.05", "perl" : "v5.8.3" } }, "test" : { "requires" : { "Test::More" : "0.9" } } }, "release_status" : "stable", "resources" : { "bugtracker" : { "mailto" : "bug-File-HomeDir@rt.cpan.org", "web" : "http://rt.cpan.org/Public/Dist/Display.html?Name=File-HomeDir" }, "homepage" : "https://metacpan.org/release/File-HomeDir", "license" : [ "http://dev.perl.org/licenses/" ], "repository" : { "type" : "git", "url" : "https://github.com/perl5-utils/File-HomeDir.git", "web" : "https://github.com/perl5-utils/File-HomeDir" } }, "version" : "1.004", "x_serialization_backend" : "JSON::PP version 2.27300_01" } File-HomeDir-1.004/README.md0000644000175000017500000003261213251234150013361 0ustar snosno# NAME File::HomeDir - Find your home and other directories on any platform # SYNOPSIS use File::HomeDir; # Modern Interface (Current User) $home = File::HomeDir->my_home; $desktop = File::HomeDir->my_desktop; $docs = File::HomeDir->my_documents; $music = File::HomeDir->my_music; $pics = File::HomeDir->my_pictures; $videos = File::HomeDir->my_videos; $data = File::HomeDir->my_data; $dist = File::HomeDir->my_dist_data('File-HomeDir'); $dist = File::HomeDir->my_dist_config('File-HomeDir'); # Modern Interface (Other Users) $home = File::HomeDir->users_home('foo'); $desktop = File::HomeDir->users_desktop('foo'); $docs = File::HomeDir->users_documents('foo'); $music = File::HomeDir->users_music('foo'); $pics = File::HomeDir->users_pictures('foo'); $video = File::HomeDir->users_videos('foo'); $data = File::HomeDir->users_data('foo'); # DESCRIPTION **File::HomeDir** is a module for locating the directories that are "owned" by a user (typically your user) and to solve the various issues that arise trying to find them consistently across a wide variety of platforms. The end result is a single API that can find your resources on any platform, making it relatively trivial to create Perl software that works elegantly and correctly no matter where you run it. ## Platform Neutrality In the Unix world, many different types of data can be mixed together in your home directory (although on some Unix platforms this is no longer the case, particularly for "desktop"-oriented platforms). On some non-Unix platforms, separate directories are allocated for different types of data and have been for a long time. When writing applications on top of **File::HomeDir**, you should thus always try to use the most specific method you can. User documents should be saved in `my_documents`, data that supports an application but isn't normally editing by the user directory should go into `my_data`. On platforms that do not make any distinction, all these different methods will harmlessly degrade to the main home directory, but on platforms that care **File::HomeDir** will always try to Do The Right Thing(tm). # METHODS Two types of methods are provided. The `my_method` series of methods for finding resources for the current user, and the `users_method` (read as "user's method") series for finding resources for arbitrary users. This split is necessary, as on most platforms it is **much** easier to find information about the current user compared to other users, and indeed on a number you cannot find out information such as `users_desktop` at all, due to security restrictions. All methods will double check (using a `-d` test) that a directory actually exists before returning it, so you may trust in the values that are returned (subject to the usual caveats of race conditions of directories being deleted at the moment between a directory being returned and you using it). However, because in some cases platforms may not support the concept of home directories at all, any method may return `undef` (both in scalar and list context) to indicate that there is no matching directory on the system. For example, most untrusted 'nobody'-type users do not have a home directory. So any modules that are used in a CGI application that at some level of recursion use your code, will result in calls to File::HomeDir returning undef, even for a basic home() call. ## my\_home The `my_home` method takes no arguments and returns the main home/profile directory for the current user. If the distinction is important to you, the term "current" refers to the real user, and not the effective user. This is also the case for all of the other "my" methods. Returns the directory path as a string, `undef` if the current user does not have a home directory, or dies on error. ## my\_desktop The `my_desktop` method takes no arguments and returns the "desktop" directory for the current user. Due to the diversity and complexity of implementations required to deal with implementing the required functionality fully and completely, the `my_desktop` method may or may not be implemented on each platform. That said, I am extremely interested in code to implement `my_desktop` on Unix, as long as it is capable of dealing (as the Windows implementation does) with internationalisation. It should also avoid false positive results by making sure it only returns the appropriate directories for the appropriate platforms. Returns the directory path as a string, `undef` if the current user does not have a desktop directory, or dies on error. ## my\_documents The `my_documents` method takes no arguments and returns the directory (for the current user) where the user's documents are stored. Returns the directory path as a string, `undef` if the current user does not have a documents directory, or dies on error. ## my\_music The `my_music` method takes no arguments and returns the directory where the current user's music is stored. No bias is made to any particular music type or music program, rather the concept of a directory to hold the user's music is made at the level of the underlying operating system or (at least) desktop environment. Returns the directory path as a string, `undef` if the current user does not have a suitable directory, or dies on error. ## my\_pictures The `my_pictures` method takes no arguments and returns the directory where the current user's pictures are stored. No bias is made to any particular picture type or picture program, rather the concept of a directory to hold the user's pictures is made at the level of the underlying operating system or (at least) desktop environment. Returns the directory path as a string, `undef` if the current user does not have a suitable directory, or dies on error. ## my\_videos The `my_videos` method takes no arguments and returns the directory where the current user's videos are stored. No bias is made to any particular video type or video program, rather the concept of a directory to hold the user's videos is made at the level of the underlying operating system or (at least) desktop environment. Returns the directory path as a string, `undef` if the current user does not have a suitable directory, or dies on error. ## my\_data The `my_data` method takes no arguments and returns the directory where local applications should store their internal data for the current user. Generally an application would create a subdirectory such as `.foo`, beneath this directory, and store its data there. By creating your directory this way, you get an accurate result on the maximum number of platforms. But see the documentation about `my_dist_config()` or `my_dist_data()` below. For example, on Unix you get `~/.foo` and on Win32 you get `~/Local Settings/Application Data/.foo` Returns the directory path as a string, `undef` if the current user does not have a data directory, or dies on error. ## my\_dist\_config File::HomeDir->my_dist_config( $dist [, \%params] ); # For example... File::HomeDir->my_dist_config( 'File-HomeDir' ); File::HomeDir->my_dist_config( 'File-HomeDir', { create => 1 } ); The `my_dist_config` method takes a distribution name as argument and returns an application-specific directory where they should store their internal configuration. The base directory will be either `my_config` if the platform supports it, or `my_documents` otherwise. The subdirectory itself will be `BASE/Perl/Dist-Name`. If the base directory is the user's homedir, `my_dist_config` will be in `~/.perl/Dist-Name` (and thus be hidden on all Unixes). The optional last argument is a hash reference to tweak the method behaviour. The following hash keys are recognized: - create Passing a true value to this key will force the creation of the directory if it doesn't exist (remember that `File::HomeDir`'s policy is to return `undef` if the directory doesn't exist). Defaults to false, meaning no automatic creation of directory. ## my\_dist\_data File::HomeDir->my_dist_data( $dist [, \%params] ); # For example... File::HomeDir->my_dist_data( 'File-HomeDir' ); File::HomeDir->my_dist_data( 'File-HomeDir', { create => 1 } ); The `my_dist_data` method takes a distribution name as argument and returns an application-specific directory where they should store their internal data. This directory will be of course a subdirectory of `my_data`. Platforms supporting data-specific directories will use `DATA_DIR/perl/dist/Dist-Name` following the common "DATA/vendor/application" pattern. If the `my_data` directory is the user's homedir, `my_dist_data` will be in `~/.perl/dist/Dist-Name` (and thus be hidden on all Unixes). The optional last argument is a hash reference to tweak the method behaviour. The following hash keys are recognized: - create Passing a true value to this key will force the creation of the directory if it doesn't exist (remember that `File::HomeDir`'s policy is to return `undef` if the directory doesn't exist). Defaults to false, meaning no automatic creation of directory. ## users\_home $home = File::HomeDir->users_home('foo'); The `users_home` method takes a single param and is used to locate the parent home/profile directory for an identified user on the system. While most of the time this identifier would be some form of user name, it is permitted to vary per-platform to support user ids or UUIDs as applicable for that platform. Returns the directory path as a string, `undef` if that user does not have a home directory, or dies on error. ## users\_documents $docs = File::HomeDir->users_documents('foo'); Returns the directory path as a string, `undef` if that user does not have a documents directory, or dies on error. ## users\_data $data = File::HomeDir->users_data('foo'); Returns the directory path as a string, `undef` if that user does not have a data directory, or dies on error. ## users\_desktop $docs = File::HomeDir->users_desktop('foo'); Returns the directory path as a string, `undef` if that user does not have a desktop directory, or dies on error. ## users\_music $docs = File::HomeDir->users_music('foo'); Returns the directory path as a string, `undef` if that user does not have a music directory, or dies on error. ## users\_pictures $docs = File::HomeDir->users_pictures('foo'); Returns the directory path as a string, `undef` if that user does not have a pictures directory, or dies on error. ## users\_videos $docs = File::HomeDir->users_videos('foo'); Returns the directory path as a string, `undef` if that user does not have a videos directory, or dies on error. # FUNCTIONS ## home use File::HomeDir; $home = home(); $home = home('foo'); $home = File::HomeDir::home(); $home = File::HomeDir::home('foo'); The `home` function is exported by default and is provided for compatibility with legacy applications. In new applications, you should use the newer method-based interface above. Returns the directory path to a named user's home/profile directory. If provided no param, returns the directory path to the current user's home/profile directory. # TO DO - Add more granularity to Unix, and add support to VMS and other esoteric platforms, so we can consider going core. - Add consistent support for users\_\* methods # SUPPORT This module is stored in an Open Repository at the following address. [http://svn.ali.as/cpan/trunk/File-HomeDir](http://svn.ali.as/cpan/trunk/File-HomeDir) Write access to the repository is made available automatically to any published CPAN author, and to most other volunteers on request. If you are able to submit your bug report in the form of new (failing) unit tests, or can apply your fix directly instead of submitting a patch, you are **strongly** encouraged to do so as the author currently maintains over 100 modules and it can take some time to deal with non-Critical bug reports or patches. This will guarantee that your issue will be addressed in the next release of the module. If you cannot provide a direct test or fix, or don't have time to do so, then regular bug reports are still accepted and appreciated via the CPAN bug tracker. [http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-HomeDir](http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-HomeDir) For other issues, for commercial enhancement or support, or to have your write access enabled for the repository, contact the author at the email address above. # ACKNOWLEDGEMENTS The biggest acknowledgement goes to Chris Nandor, who wielded his legendary Mac-fu and turned my initial fairly ordinary Darwin implementation into something that actually worked properly everywhere, and then donated a Mac OS X license to allow it to be maintained properly. # AUTHORS Adam Kennedy Sean M. Burke Chris Nandor Stephen Steneker # SEE ALSO [File::ShareDir](https://metacpan.org/pod/File::ShareDir), [File::HomeDir::Win32](https://metacpan.org/pod/File::HomeDir::Win32) (legacy) # COPYRIGHT Copyright 2005 - 2012 Adam Kennedy. Some parts copyright 2000 Sean M. Burke. Some parts copyright 2006 Chris Nandor. Some parts copyright 2006 Stephen Steneker. Some parts copyright 2009-2011 Jérôme Quelin. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of the license can be found in the LICENSE file included with this module. File-HomeDir-1.004/LICENSE0000644000175000017500000005014013251234150013103 0ustar snosno Terms of Perl itself a) the GNU General Public License as published by the Free Software Foundation; either version 1, or (at your option) any later version, or b) the "Artistic License" ---------------------------------------------------------------------------- GNU GENERAL PUBLIC LICENSE Version 2, June 1991 Copyright (C) 1989, 1991 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed. Preamble The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public License is intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users. This General Public License applies to most of the Free Software Foundation's software and to any other program whose authors commit to using it. (Some other Free Software Foundation software is covered by the GNU Lesser General Public License instead.) You can apply it to your programs, too. When we speak of free software, we are referring to freedom, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish), that you receive source code or can get it if you want it, that you can change the software or use pieces of it in new free programs; and that you know you can do these things. To protect your rights, we need to make restrictions that forbid anyone to deny you these rights or to ask you to surrender the rights. These restrictions translate to certain responsibilities for you if you distribute copies of the software, or if you modify it. For example, if you distribute copies of such a program, whether gratis or for a fee, you must give the recipients all the rights that you have. You must make sure that they, too, receive or can get the source code. And you must show them these terms so they know their rights. We protect your rights with two steps: (1) copyright the software, and (2) offer you this license which gives you legal permission to copy, distribute and/or modify the software. Also, for each author's protection and ours, we want to make certain that everyone understands that there is no warranty for this free software. If the software is modified by someone else and passed on, we want its recipients to know that what they have is not the original, so that any problems introduced by others will not reflect on the original authors' reputations. Finally, any free program is threatened constantly by software patents. We wish to avoid the danger that redistributors of a free program will individually obtain patent licenses, in effect making the program proprietary. To prevent this, we have made it clear that any patent must be licensed for everyone's free use or not licensed at all. The precise terms and conditions for copying, distribution and modification follow. GNU GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 0. This License applies to any program or other work which contains a notice placed by the copyright holder saying it may be distributed under the terms of this General Public License. The "Program", below, refers to any such program or work, and a "work based on the Program" means either the Program or any derivative work under copyright law: that is to say, a work containing the Program or a portion of it, either verbatim or with modifications and/or translated into another language. (Hereinafter, translation is included without limitation in the term "modification".) Each licensee is addressed as "you". Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running the Program is not restricted, and the output from the Program is covered only if its contents constitute a work based on the Program (independent of having been made by running the Program). Whether that is true depends on what the Program does. 1. You may copy and distribute verbatim copies of the Program's source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and give any other recipients of the Program a copy of this License along with the Program. You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee. 2. You may modify your copy or copies of the Program or any portion of it, thus forming a work based on the Program, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions: a) You must cause the modified files to carry prominent notices stating that you changed the files and the date of any change. b) You must cause any work that you distribute or publish, that in whole or in part contains or is derived from the Program or any part thereof, to be licensed as a whole at no charge to all third parties under the terms of this License. c) If the modified program normally reads commands interactively when run, you must cause it, when started running for such interactive use in the most ordinary way, to print or display an announcement including an appropriate copyright notice and a notice that there is no warranty (or else, saying that you provide a warranty) and that users may redistribute the program under these conditions, and telling the user how to view a copy of this License. (Exception: if the Program itself is interactive but does not normally print such an announcement, your work based on the Program is not required to print an announcement.) These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Program, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Program, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it. Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Program. In addition, mere aggregation of another work not based on the Program with the Program (or with a work based on the Program) on a volume of a storage or distribution medium does not bring the other work under the scope of this License. 3. You may copy and distribute the Program (or a work based on it, under Section 2) in object code or executable form under the terms of Sections 1 and 2 above provided that you also do one of the following: a) Accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, b) Accompany it with a written offer, valid for at least three years, to give any third party, for a charge no more than your cost of physically performing source distribution, a complete machine-readable copy of the corresponding source code, to be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange; or, c) Accompany it with the information you received as to the offer to distribute corresponding source code. (This alternative is allowed only for noncommercial distribution and only if you received the program in object code or executable form with such an offer, in accord with Subsection b above.) The source code for a work means the preferred form of the work for making modifications to it. For an executable work, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the executable. However, as a special exception, the source code distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable. If distribution of executable or object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place counts as distribution of the source code, even though third parties are not compelled to copy the source along with the object code. 4. You may not copy, modify, sublicense, or distribute the Program except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense or distribute the Program is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance. 5. You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Program or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Program (or any work based on the Program), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Program or works based on it. 6. Each time you redistribute the Program (or any work based on the Program), the recipient automatically receives a license from the original licensor to copy, distribute or modify the Program subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties to this License. 7. If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Program at all. For example, if a patent license would not permit royalty-free redistribution of the Program by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Program. If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply and the section as a whole is intended to apply in other circumstances. It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system, which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice. This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License. 8. If the distribution and/or use of the Program is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Program under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License. 9. The Free Software Foundation may publish revised and/or new versions of the General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. Each version is given a distinguishing version number. If the Program specifies a version number of this License which applies to it and "any later version", you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Program does not specify a version number of this License, you may choose any version ever published by the Free Software Foundation. 10. If you wish to incorporate parts of the Program into other free programs whose distribution conditions are different, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally. NO WARRANTY 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. END OF TERMS AND CONDITIONS ---------------------------------------------------------------------------- The Artistic License Preamble The intent of this document is to state the conditions under which a Package may be copied, such that the Copyright Holder maintains some semblance of artistic control over the development of the package, while giving the users of the package the right to use and distribute the Package in a more-or-less customary fashion, plus the right to make reasonable modifications. Definitions: - "Package" refers to the collection of files distributed by the Copyright Holder, and derivatives of that collection of files created through textual modification. - "Standard Version" refers to such a Package if it has not been modified, or has been modified in accordance with the wishes of the Copyright Holder. - "Copyright Holder" is whoever is named in the copyright or copyrights for the package. - "You" is you, if you're thinking about copying or distributing this Package. - "Reasonable copying fee" is whatever you can justify on the basis of media cost, duplication charges, time of people involved, and so on. (You will not be required to justify it to the Copyright Holder, but only to the computing community at large as a market that must bear the fee.) - "Freely Available" means that no fee is charged for the item itself, though there may be fees involved in handling the item. It also means that recipients of the item may redistribute it under the same conditions they received it. 1. You may make and give away verbatim copies of the source form of the Standard Version of this Package without restriction, provided that you duplicate all of the original copyright notices and associated disclaimers. 2. You may apply bug fixes, portability fixes and other modifications derived from the Public Domain or from the Copyright Holder. A Package modified in such a way shall still be considered the Standard Version. 3. You may otherwise modify your copy of this Package in any way, provided that you insert a prominent notice in each changed file stating how and when you changed that file, and provided that you do at least ONE of the following: a) place your modifications in the Public Domain or otherwise make them Freely Available, such as by posting said modifications to Usenet or an equivalent medium, or placing the modifications on a major archive site such as ftp.uu.net, or by allowing the Copyright Holder to include your modifications in the Standard Version of the Package. b) use the modified Package only within your corporation or organization. c) rename any non-standard executables so the names do not conflict with standard executables, which must also be provided, and provide a separate manual page for each non-standard executable that clearly documents how it differs from the Standard Version. d) make other distribution arrangements with the Copyright Holder. 4. You may distribute the programs of this Package in object code or executable form, provided that you do at least ONE of the following: a) distribute a Standard Version of the executables and library files, together with instructions (in the manual page or equivalent) on where to get the Standard Version. b) accompany the distribution with the machine-readable source of the Package with your modifications. c) accompany any non-standard executables with their corresponding Standard Version executables, giving the non-standard executables non-standard names, and clearly documenting the differences in manual pages (or equivalent), together with instructions on where to get the Standard Version. d) make other distribution arrangements with the Copyright Holder. 5. You may charge a reasonable copying fee for any distribution of this Package. You may charge any fee you choose for support of this Package. You may not charge a fee for this Package itself. However, you may distribute this Package in aggregate with other (possibly commercial) programs as part of a larger (possibly commercial) software distribution provided that you do not advertise this Package as a product of your own. 6. The scripts and library files supplied as input to or produced as output from the programs of this Package do not automatically fall under the copyright of this Package, but belong to whomever generated them, and may be sold commercially, and may be aggregated with this Package. 7. C or perl subroutines supplied by you and linked into this Package shall not be considered part of this Package. 8. The name of the Copyright Holder may not be used to endorse or promote products derived from this software without specific prior written permission. 9. THIS PACKAGE IS PROVIDED "AS IS" AND WITHOUT ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, WITHOUT LIMITATION, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR A PARTICULAR PURPOSE. The End File-HomeDir-1.004/Makefile.PL0000644000175000017500000001163613251234150014057 0ustar snosnouse strict; use warnings; use 5.008003; use Config; use ExtUtils::MakeMaker; my %RUN_DEPS = ( 'Carp' => 0, 'Cwd' => $^O eq 'darwin' ? '3' : '3.12', 'File::Basename' => 0, 'File::Path' => '2.01', 'File::Spec' => $^O eq 'darwin' ? '3' : '3.12', 'File::Temp' => '0.19', 'File::Which' => '0.05', # Dependencies for specific platforms ### Use variable twice to avoid a warning ( $MacPerl::Version and $MacPerl::Version or $^O eq 'darwin' and _check_old_mac_os_x() ) ? ('Mac::Files' => 0) : ($^O eq 'darwin' ? ('Mac::SystemDirectory' => '0.04') : ()), ($^O eq 'MSWin32') ? ('Win32' => '0.31') : (), ); my %CONFIGURE_DEPS = ( 'ExtUtils::MakeMaker' => 0, 'POSIX' => 0, ); my %BUILD_DEPS = (); my %TEST_DEPS = ( 'Test::More' => 0.90, ); WriteMakefile1( MIN_PERL_VERSION => '5.008003', META_ADD => { 'meta-spec' => {version => 2}, resources => { homepage => 'https://metacpan.org/release/File-HomeDir', repository => { url => 'https://github.com/perl5-utils/File-HomeDir.git', web => 'https://github.com/perl5-utils/File-HomeDir', type => 'git', }, bugtracker => { web => 'http://rt.cpan.org/Public/Dist/Display.html?Name=File-HomeDir', mailto => 'bug-File-HomeDir@rt.cpan.org', }, license => 'http://dev.perl.org/licenses/', }, prereqs => { develop => { requires => { 'Test::CPAN::Changes' => 0, 'Test::CheckManifest' => 0, 'Module::CPANTS::Analyse' => '0.96', 'Test::Kwalitee' => 0, 'Test::Perl::Critic' => 0, 'Test::PerlTidy' => 0, 'Test::Pod' => 0, 'Test::Pod::Coverage' => 0, 'Test::Pod::Spelling::CommonMistakes' => 0, 'Test::Spelling' => 0, }, }, configure => { requires => {%CONFIGURE_DEPS}, }, build => {requires => {%BUILD_DEPS}}, test => {requires => {%TEST_DEPS}}, runtime => { requires => { %RUN_DEPS, perl => '5.8.3', }, }, }, }, NAME => 'File::HomeDir', VERSION_FROM => 'lib/File/HomeDir.pm', ABSTRACT_FROM => 'lib/File/HomeDir.pm', LICENSE => 'perl', AUTHOR => q{Adam Kennedy }, CONFIGURE_REQUIRES => \%CONFIGURE_DEPS, PREREQ_PM => \%RUN_DEPS, BUILD_REQUIRES => \%BUILD_DEPS, TEST_REQUIRES => \%TEST_DEPS, test => {TESTS => 't/*.t xt/*.t'}, ); sub WriteMakefile1 { # originally written by Alexandr Ciornii, version 0.21. Added by eumm-upgrade. my %params = @_; my $eumm_version = $ExtUtils::MakeMaker::VERSION; $eumm_version = eval $eumm_version; die "EXTRA_META is deprecated" if (exists($params{EXTRA_META})); die "License not specified" if (!exists($params{LICENSE})); $params{TEST_REQUIRES} and $eumm_version < 6.6303 and $params{BUILD_REQUIRES} = {%{$params{BUILD_REQUIRES} || {}}, %{delete $params{TEST_REQUIRES}}}; #EUMM 6.5502 has problems with BUILD_REQUIRES $params{BUILD_REQUIRES} and $eumm_version < 6.5503 and $params{PREREQ_PM} = {%{$params{PREREQ_PM} || {}}, %{delete $params{BUILD_REQUIRES}}}; ref $params{AUTHOR} and "ARRAY" eq ref $params{AUTHOR} and $eumm_version < 6.5702 and $params{AUTHOR} = join(", ", @{$params{AUTHOR}}); delete $params{CONFIGURE_REQUIRES} if ($eumm_version < 6.52); delete $params{MIN_PERL_VERSION} if ($eumm_version < 6.48); delete $params{META_MERGE} if ($eumm_version < 6.46); delete $params{META_ADD}{prereqs} if ($eumm_version < 6.58); delete $params{META_ADD}{'meta-spec'} if ($eumm_version < 6.58); delete $params{META_ADD} if ($eumm_version < 6.46); delete $params{LICENSE} if ($eumm_version < 6.31); delete $params{AUTHOR} if ($] < 5.005); delete $params{ABSTRACT_FROM} if ($] < 5.005); delete $params{BINARY_LOCATION} if ($] < 5.005); WriteMakefile(%params); } sub _check_old_mac_os_x { local $@; $Config{ptrsize} == 8 and return; return eval { require POSIX; my $release = (POSIX::uname())[2]; my ($major) = split qr{ [.] }smx, $release; # 'old' means before darwin 8 = Mac OS 10.4 = Tiger $major < 8; }; } File-HomeDir-1.004/lib/0000755000175000017500000000000013272255100012645 5ustar snosnoFile-HomeDir-1.004/lib/File/0000755000175000017500000000000013272255100013524 5ustar snosnoFile-HomeDir-1.004/lib/File/HomeDir.pm0000644000175000017500000005224113272253612015423 0ustar snosnopackage File::HomeDir; # See POD at end for documentation use 5.008003; use strict; use warnings; use Carp (); use Config (); use File::Spec (); use File::Which (); # Globals use vars qw{$VERSION @EXPORT @EXPORT_OK $IMPLEMENTED_BY}; ## no critic qw(AutomaticExportation) use base qw(Exporter); BEGIN { $VERSION = '1.004'; # Inherit manually require Exporter; @EXPORT = qw{home}; @EXPORT_OK = qw{ home my_home my_desktop my_documents my_music my_pictures my_videos my_data my_dist_config my_dist_data users_home users_desktop users_documents users_music users_pictures users_videos users_data }; } # Inlined Params::Util functions sub _CLASS ($) ## no critic qw(SubroutinePrototypes) { (defined $_[0] and not ref $_[0] and $_[0] =~ m/^[^\W\d]\w*(?:::\w+)*\z/s) ? $_[0] : undef; } sub _DRIVER ($$) ## no critic qw(SubroutinePrototypes) { (defined _CLASS($_[0]) and eval "require $_[0]; 1" and $_[0]->isa($_[1]) and $_[0] ne $_[1]) ? $_[0] : undef; } # Platform detection if ($IMPLEMENTED_BY) { # Allow for custom HomeDir classes # Leave it as the existing value } elsif ($^O eq 'MSWin32') { # All versions of Windows $IMPLEMENTED_BY = 'File::HomeDir::Windows'; } elsif ($^O eq 'darwin') { # 1st: try Mac::SystemDirectory by chansen if (eval "require Mac::SystemDirectory; 1") { $IMPLEMENTED_BY = 'File::HomeDir::Darwin::Cocoa'; } elsif (eval "require Mac::Files; 1") { # 2nd try Mac::Files: Carbon - unmaintained since 2006 except some 64bit fixes $IMPLEMENTED_BY = 'File::HomeDir::Darwin::Carbon'; } else { # 3rd: fallback: pure perl $IMPLEMENTED_BY = 'File::HomeDir::Darwin'; } } elsif ($^O eq 'MacOS') { # Legacy Mac OS $IMPLEMENTED_BY = 'File::HomeDir::MacOS9'; } elsif (File::Which::which('xdg-user-dir')) { # freedesktop unixes $IMPLEMENTED_BY = 'File::HomeDir::FreeDesktop'; } else { # Default to Unix semantics $IMPLEMENTED_BY = 'File::HomeDir::Unix'; } unless (_DRIVER($IMPLEMENTED_BY, 'File::HomeDir::Driver')) { Carp::croak("Missing or invalid File::HomeDir driver $IMPLEMENTED_BY"); } ##################################################################### # Current User Methods sub my_home { $IMPLEMENTED_BY->my_home; } sub my_desktop { $IMPLEMENTED_BY->can('my_desktop') ? $IMPLEMENTED_BY->my_desktop : Carp::croak("The my_desktop method is not implemented on this platform"); } sub my_documents { $IMPLEMENTED_BY->can('my_documents') ? $IMPLEMENTED_BY->my_documents : Carp::croak("The my_documents method is not implemented on this platform"); } sub my_music { $IMPLEMENTED_BY->can('my_music') ? $IMPLEMENTED_BY->my_music : Carp::croak("The my_music method is not implemented on this platform"); } sub my_pictures { $IMPLEMENTED_BY->can('my_pictures') ? $IMPLEMENTED_BY->my_pictures : Carp::croak("The my_pictures method is not implemented on this platform"); } sub my_videos { $IMPLEMENTED_BY->can('my_videos') ? $IMPLEMENTED_BY->my_videos : Carp::croak("The my_videos method is not implemented on this platform"); } sub my_data { $IMPLEMENTED_BY->can('my_data') ? $IMPLEMENTED_BY->my_data : Carp::croak("The my_data method is not implemented on this platform"); } sub my_dist_data { my $params = ref $_[-1] eq 'HASH' ? pop : {}; my $dist = pop or Carp::croak("The my_dist_data method requires an argument"); my $data = my_data(); # If datadir is not defined, there's nothing we can do: bail out # and return nothing... return undef unless defined $data; # On traditional unixes, hide the top-level directory my $var = $data eq home() ? File::Spec->catdir($data, '.perl', 'dist', $dist) : File::Spec->catdir($data, 'Perl', 'dist', $dist); # directory exists: return it return $var if -d $var; # directory doesn't exist: check if we need to create it... return undef unless $params->{create}; # user requested directory creation require File::Path; File::Path::mkpath($var); return $var; } sub my_dist_config { my $params = ref $_[-1] eq 'HASH' ? pop : {}; my $dist = pop or Carp::croak("The my_dist_config method requires an argument"); # not all platforms support a specific my_config() method my $config = $IMPLEMENTED_BY->can('my_config') ? $IMPLEMENTED_BY->my_config : $IMPLEMENTED_BY->my_documents; # If neither configdir nor my_documents is defined, there's # nothing we can do: bail out and return nothing... return undef unless defined $config; # On traditional unixes, hide the top-level dir my $etc = $config eq home() ? File::Spec->catdir($config, '.perl', $dist) : File::Spec->catdir($config, 'Perl', $dist); # directory exists: return it return $etc if -d $etc; # directory doesn't exist: check if we need to create it... return undef unless $params->{create}; # user requested directory creation require File::Path; File::Path::mkpath($etc); return $etc; } ##################################################################### # General User Methods sub users_home { $IMPLEMENTED_BY->can('users_home') ? $IMPLEMENTED_BY->users_home($_[-1]) : Carp::croak("The users_home method is not implemented on this platform"); } sub users_desktop { $IMPLEMENTED_BY->can('users_desktop') ? $IMPLEMENTED_BY->users_desktop($_[-1]) : Carp::croak("The users_desktop method is not implemented on this platform"); } sub users_documents { $IMPLEMENTED_BY->can('users_documents') ? $IMPLEMENTED_BY->users_documents($_[-1]) : Carp::croak("The users_documents method is not implemented on this platform"); } sub users_music { $IMPLEMENTED_BY->can('users_music') ? $IMPLEMENTED_BY->users_music($_[-1]) : Carp::croak("The users_music method is not implemented on this platform"); } sub users_pictures { $IMPLEMENTED_BY->can('users_pictures') ? $IMPLEMENTED_BY->users_pictures($_[-1]) : Carp::croak("The users_pictures method is not implemented on this platform"); } sub users_videos { $IMPLEMENTED_BY->can('users_videos') ? $IMPLEMENTED_BY->users_videos($_[-1]) : Carp::croak("The users_videos method is not implemented on this platform"); } sub users_data { $IMPLEMENTED_BY->can('users_data') ? $IMPLEMENTED_BY->users_data($_[-1]) : Carp::croak("The users_data method is not implemented on this platform"); } ##################################################################### # Legacy Methods # Find the home directory of an arbitrary user sub home (;$) ## no critic qw(SubroutinePrototypes) { # Allow to be called as a method if ($_[0] and $_[0] eq 'File::HomeDir') { shift(); } # No params means my home return my_home() unless @_; # Check the param my $name = shift; if (!defined $name) { Carp::croak("Can't use undef as a username"); } if (!length $name) { Carp::croak("Can't use empty-string (\"\") as a username"); } # A dot also means my home ### Is this meant to mean File::Spec->curdir? if ($name eq '.') { return my_home(); } # Now hand off to the implementor $IMPLEMENTED_BY->users_home($name); } 1; __END__ =pod =encoding UTF-8 =head1 NAME File::HomeDir - Find your home and other directories on any platform =begin html Travis CI Coverage Status =end html =head1 SYNOPSIS use File::HomeDir; # Modern Interface (Current User) $home = File::HomeDir->my_home; $desktop = File::HomeDir->my_desktop; $docs = File::HomeDir->my_documents; $music = File::HomeDir->my_music; $pics = File::HomeDir->my_pictures; $videos = File::HomeDir->my_videos; $data = File::HomeDir->my_data; $dist = File::HomeDir->my_dist_data('File-HomeDir'); $dist = File::HomeDir->my_dist_config('File-HomeDir'); # Modern Interface (Other Users) $home = File::HomeDir->users_home('foo'); $desktop = File::HomeDir->users_desktop('foo'); $docs = File::HomeDir->users_documents('foo'); $music = File::HomeDir->users_music('foo'); $pics = File::HomeDir->users_pictures('foo'); $video = File::HomeDir->users_videos('foo'); $data = File::HomeDir->users_data('foo'); =head1 DESCRIPTION B is a module for locating the directories that are "owned" by a user (typically your user) and to solve the various issues that arise trying to find them consistently across a wide variety of platforms. The end result is a single API that can find your resources on any platform, making it relatively trivial to create Perl software that works elegantly and correctly no matter where you run it. =head2 Platform Neutrality In the Unix world, many different types of data can be mixed together in your home directory (although on some Unix platforms this is no longer the case, particularly for "desktop"-oriented platforms). On some non-Unix platforms, separate directories are allocated for different types of data and have been for a long time. When writing applications on top of B, you should thus always try to use the most specific method you can. User documents should be saved in C, data that supports an application but isn't normally editing by the user directory should go into C. On platforms that do not make any distinction, all these different methods will harmlessly degrade to the main home directory, but on platforms that care B will always try to Do The Right Thing(tm). =head1 METHODS Two types of methods are provided. The C series of methods for finding resources for the current user, and the C (read as "user's method") series for finding resources for arbitrary users. This split is necessary, as on most platforms it is B easier to find information about the current user compared to other users, and indeed on a number you cannot find out information such as C at all, due to security restrictions. All methods will double check (using a C<-d> test) that a directory actually exists before returning it, so you may trust in the values that are returned (subject to the usual caveats of race conditions of directories being deleted at the moment between a directory being returned and you using it). However, because in some cases platforms may not support the concept of home directories at all, any method may return C (both in scalar and list context) to indicate that there is no matching directory on the system. For example, most untrusted 'nobody'-type users do not have a home directory. So any modules that are used in a CGI application that at some level of recursion use your code, will result in calls to File::HomeDir returning undef, even for a basic home() call. =head2 my_home The C method takes no arguments and returns the main home/profile directory for the current user. If the distinction is important to you, the term "current" refers to the real user, and not the effective user. This is also the case for all of the other "my" methods. Returns the directory path as a string, C if the current user does not have a home directory, or dies on error. =head2 my_desktop The C method takes no arguments and returns the "desktop" directory for the current user. Due to the diversity and complexity of implementations required to deal with implementing the required functionality fully and completely, the C method may or may not be implemented on each platform. That said, I am extremely interested in code to implement C on Unix, as long as it is capable of dealing (as the Windows implementation does) with internationalization. It should also avoid false positive results by making sure it only returns the appropriate directories for the appropriate platforms. Returns the directory path as a string, C if the current user does not have a desktop directory, or dies on error. =head2 my_documents The C method takes no arguments and returns the directory (for the current user) where the user's documents are stored. Returns the directory path as a string, C if the current user does not have a documents directory, or dies on error. =head2 my_music The C method takes no arguments and returns the directory where the current user's music is stored. No bias is made to any particular music type or music program, rather the concept of a directory to hold the user's music is made at the level of the underlying operating system or (at least) desktop environment. Returns the directory path as a string, C if the current user does not have a suitable directory, or dies on error. =head2 my_pictures The C method takes no arguments and returns the directory where the current user's pictures are stored. No bias is made to any particular picture type or picture program, rather the concept of a directory to hold the user's pictures is made at the level of the underlying operating system or (at least) desktop environment. Returns the directory path as a string, C if the current user does not have a suitable directory, or dies on error. =head2 my_videos The C method takes no arguments and returns the directory where the current user's videos are stored. No bias is made to any particular video type or video program, rather the concept of a directory to hold the user's videos is made at the level of the underlying operating system or (at least) desktop environment. Returns the directory path as a string, C if the current user does not have a suitable directory, or dies on error. =head2 my_data The C method takes no arguments and returns the directory where local applications should store their internal data for the current user. Generally an application would create a subdirectory such as C<.foo>, beneath this directory, and store its data there. By creating your directory this way, you get an accurate result on the maximum number of platforms. But see the documentation about C or C below. For example, on Unix you get C<~/.foo> and on Win32 you get C<~/Local Settings/Application Data/.foo> Returns the directory path as a string, C if the current user does not have a data directory, or dies on error. =head2 my_dist_config File::HomeDir->my_dist_config( $dist [, \%params] ); # For example... File::HomeDir->my_dist_config( 'File-HomeDir' ); File::HomeDir->my_dist_config( 'File-HomeDir', { create => 1 } ); The C method takes a distribution name as argument and returns an application-specific directory where they should store their internal configuration. The base directory will be either C if the platform supports it, or C otherwise. The subdirectory itself will be C. If the base directory is the user's home directory, C will be in C<~/.perl/Dist-Name> (and thus be hidden on all Unixes). The optional last argument is a hash reference to tweak the method behaviour. The following hash keys are recognized: =over 4 =item * create Passing a true value to this key will force the creation of the directory if it doesn't exist (remember that C's policy is to return C if the directory doesn't exist). Defaults to false, meaning no automatic creation of directory. =back =head2 my_dist_data File::HomeDir->my_dist_data( $dist [, \%params] ); # For example... File::HomeDir->my_dist_data( 'File-HomeDir' ); File::HomeDir->my_dist_data( 'File-HomeDir', { create => 1 } ); The C method takes a distribution name as argument and returns an application-specific directory where they should store their internal data. This directory will be of course a subdirectory of C. Platforms supporting data-specific directories will use C following the common "DATA/vendor/application" pattern. If the C directory is the user's home directory, C will be in C<~/.perl/dist/Dist-Name> (and thus be hidden on all Unixes). The optional last argument is a hash reference to tweak the method behaviour. The following hash keys are recognized: =over 4 =item * create Passing a true value to this key will force the creation of the directory if it doesn't exist (remember that C's policy is to return C if the directory doesn't exist). Defaults to false, meaning no automatic creation of directory. =back =head2 users_home $home = File::HomeDir->users_home('foo'); The C method takes a single parameter and is used to locate the parent home/profile directory for an identified user on the system. While most of the time this identifier would be some form of user name, it is permitted to vary per-platform to support user ids or UUIDs as applicable for that platform. Returns the directory path as a string, C if that user does not have a home directory, or dies on error. =head2 users_documents $docs = File::HomeDir->users_documents('foo'); Returns the directory path as a string, C if that user does not have a documents directory, or dies on error. =head2 users_data $data = File::HomeDir->users_data('foo'); Returns the directory path as a string, C if that user does not have a data directory, or dies on error. =head2 users_desktop $docs = File::HomeDir->users_desktop('foo'); Returns the directory path as a string, C if that user does not have a desktop directory, or dies on error. =head2 users_music $docs = File::HomeDir->users_music('foo'); Returns the directory path as a string, C if that user does not have a music directory, or dies on error. =head2 users_pictures $docs = File::HomeDir->users_pictures('foo'); Returns the directory path as a string, C if that user does not have a pictures directory, or dies on error. =head2 users_videos $docs = File::HomeDir->users_videos('foo'); Returns the directory path as a string, C if that user does not have a videos directory, or dies on error. =head1 FUNCTIONS =head2 home use File::HomeDir; $home = home(); $home = home('foo'); $home = File::HomeDir::home(); $home = File::HomeDir::home('foo'); The C function is exported by default and is provided for compatibility with legacy applications. In new applications, you should use the newer method-based interface above. Returns the directory path to a named user's home/profile directory. If provided no parameter, returns the directory path to the current user's home/profile directory. =head1 TO DO =over 4 =item * Add more granularity to Unix, and add support to VMS and other esoteric platforms, so we can consider going core. =item * Add consistent support for users_* methods =back =head1 SUPPORT This module is stored in an Open Repository at the following address. L Write access to the repository is made available automatically to any published CPAN author, and to most other volunteers on request. If you are able to submit your bug report in the form of new (failing) unit tests, or can apply your fix directly instead of submitting a patch, you are B encouraged to do so as the author currently maintains over 100 modules and it can take some time to deal with non-Critical bug reports or patches. This will guarantee that your issue will be addressed in the next release of the module. If you cannot provide a direct test or fix, or don't have time to do so, then regular bug reports are still accepted and appreciated via the CPAN bug tracker. L For other issues, for commercial enhancement or support, or to have your write access enabled for the repository, contact the author at the email address above. =head1 ACKNOWLEDGEMENTS The biggest acknowledgement goes to Chris Nandor, who wielded his legendary Mac-fu and turned my initial fairly ordinary Darwin implementation into something that actually worked properly everywhere, and then donated a Mac OS X license to allow it to be maintained properly. =head1 AUTHORS Adam Kennedy Eadamk@cpan.orgE Sean M. Burke Esburke@cpan.orgE Chris Nandor Ecnandor@cpan.orgE Stephen Steneker Estennie@cpan.orgE =head1 SEE ALSO L, L (legacy) =head1 COPYRIGHT Copyright 2005 - 2012 Adam Kennedy. Some parts copyright 2000 Sean M. Burke. Some parts copyright 2006 Chris Nandor. Some parts copyright 2006 Stephen Steneker. Some parts copyright 2009-2011 Jérôme Quelin. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of the license can be found in the LICENSE file included with this module. =cut File-HomeDir-1.004/lib/File/HomeDir/0000755000175000017500000000000013272255100015053 5ustar snosnoFile-HomeDir-1.004/lib/File/HomeDir/MacOS9.pm0000644000175000017500000000645013272253612016457 0ustar snosnopackage File::HomeDir::MacOS9; # Half-assed implementation for the legacy Mac OS9 operating system. # Provided mainly to provide legacy compatibility. May be removed at # a later date. use 5.008003; use strict; use warnings; use Carp (); use File::HomeDir::Driver (); use vars qw{$VERSION}; use base "File::HomeDir::Driver"; BEGIN { $VERSION = '1.004'; } # Load early if in a forking environment and we have # prefork, or at run-time if not. SCOPE: { ## no critic qw(RequireInitializationForLocalVars, RequireCheckingReturnValueOfEval) local $@; eval "use prefork 'Mac::Files'"; } ##################################################################### # Current User Methods sub my_home { my $class = shift; # Try for $ENV{HOME} if we have it if (defined $ENV{HOME}) { return $ENV{HOME}; } ### DESPERATION SETS IN # We could use the desktop SCOPE: { ## no critic qw(RequireInitializationForLocalVars, RequireCheckingReturnValueOfEval) local $@; eval { my $home = $class->my_desktop; return $home if $home and -d $home; }; } # Desperation on any platform SCOPE: { # On some platforms getpwuid dies if called at all local $SIG{'__DIE__'} = ''; my $home = (getpwuid($<))[7]; return $home if $home and -d $home; } Carp::croak("Could not locate current user's home directory"); } sub my_desktop { my $class = shift; # Find the desktop via Mac::Files local $SIG{'__DIE__'} = ''; require Mac::Files; my $home = Mac::Files::FindFolder(Mac::Files::kOnSystemDisk(), Mac::Files::kDesktopFolderType(),); return $home if $home and -d $home; Carp::croak("Could not locate current user's desktop"); } ##################################################################### # General User Methods sub users_home { my ($class, $name) = @_; SCOPE: { # On some platforms getpwnam dies if called at all local $SIG{'__DIE__'} = ''; my $home = (getpwnam($name))[7]; return $home if defined $home and -d $home; } Carp::croak("Failed to find home directory for user '$name'"); } 1; =pod =head1 NAME File::HomeDir::MacOS9 - Find your home and other directories on legacy Macintosh systems =head1 SYNOPSIS use File::HomeDir; # Find directories for the current user $home = File::HomeDir->my_home; $desktop = File::HomeDir->my_desktop; =head1 DESCRIPTION This module provides implementations for determining common user directories on legacy Mac hosts. In normal usage this module will always be used via L. This module is no longer actively maintained, and is included only for extreme back-compatibility. Only the C and C methods are supported. =head1 SUPPORT See the support section the main L module. =head1 AUTHORS Adam Kennedy Eadamk@cpan.orgE Sean M. Burke Esburke@cpan.orgE =head1 SEE ALSO L =head1 COPYRIGHT Copyright 2005 - 2011 Adam Kennedy. Some parts copyright 2000 Sean M. Burke. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of the license can be found in the LICENSE file included with this module. =cut File-HomeDir-1.004/lib/File/HomeDir/Darwin.pm0000644000175000017500000000620113272253612016642 0ustar snosnopackage File::HomeDir::Darwin; use 5.008003; use strict; use warnings; use Cwd (); use Carp (); use File::HomeDir::Unix (); use vars qw{$VERSION}; use base "File::HomeDir::Unix"; BEGIN { $VERSION = '1.004'; } ##################################################################### # Current User Methods sub _my_home { my ($class, $path) = @_; my $home = $class->my_home; return undef unless defined $home; my $folder = "$home/$path"; unless (-d $folder) { # Make sure that symlinks resolve to directories. return undef unless -l $folder; my $dir = readlink $folder or return; return undef unless -d $dir; } return Cwd::abs_path($folder); } sub my_desktop { my $class = shift; $class->_my_home('Desktop'); } sub my_documents { my $class = shift; $class->_my_home('Documents'); } sub my_data { my $class = shift; $class->_my_home('Library/Application Support'); } sub my_music { my $class = shift; $class->_my_home('Music'); } sub my_pictures { my $class = shift; $class->_my_home('Pictures'); } sub my_videos { my $class = shift; $class->_my_home('Movies'); } ##################################################################### # Arbitrary User Methods sub users_home { my $class = shift; my $home = $class->SUPER::users_home(@_); return defined $home ? Cwd::abs_path($home) : undef; } sub users_desktop { my ($class, $name) = @_; return undef if $name eq 'root'; $class->_to_user($class->my_desktop, $name); } sub users_documents { my ($class, $name) = @_; return undef if $name eq 'root'; $class->_to_user($class->my_documents, $name); } sub users_data { my ($class, $name) = @_; $class->_to_user($class->my_data, $name) || $class->users_home($name); } # cheap hack ... not entirely reliable, perhaps, but ... c'est la vie, since # there's really no other good way to do it at this time, that i know of -- pudge sub _to_user { my ($class, $path, $name) = @_; my $my_home = $class->my_home; my $users_home = $class->users_home($name); defined $users_home or return undef; $path =~ s/^\Q$my_home/$users_home/; return $path; } 1; =pod =head1 NAME File::HomeDir::Darwin - Find your home and other directories on Darwin (OS X) =head1 DESCRIPTION This module provides Mac OS X specific file path for determining common user directories in pure perl, by just using C<$ENV{HOME}> without Carbon nor Cocoa API calls. In normal usage this module will always be used via L. =head1 SYNOPSIS use File::HomeDir; # Find directories for the current user $home = File::HomeDir->my_home; # /Users/mylogin $desktop = File::HomeDir->my_desktop; # /Users/mylogin/Desktop $docs = File::HomeDir->my_documents; # /Users/mylogin/Documents $music = File::HomeDir->my_music; # /Users/mylogin/Music $pics = File::HomeDir->my_pictures; # /Users/mylogin/Pictures $videos = File::HomeDir->my_videos; # /Users/mylogin/Movies $data = File::HomeDir->my_data; # /Users/mylogin/Library/Application Support =cut File-HomeDir-1.004/lib/File/HomeDir/Darwin/0000755000175000017500000000000013272255100016277 5ustar snosnoFile-HomeDir-1.004/lib/File/HomeDir/Darwin/Cocoa.pm0000644000175000017500000000727413272253612017701 0ustar snosnopackage File::HomeDir::Darwin::Cocoa; use 5.008003; use strict; use warnings; use Cwd (); use Carp (); use File::HomeDir::Darwin (); use vars qw{$VERSION}; use base "File::HomeDir::Darwin"; BEGIN { $VERSION = '1.004'; # Load early if in a forking environment and we have # prefork, or at run-time if not. local $@; ## no critic (Variables::RequireInitializationForLocalVars) eval "use prefork 'Mac::SystemDirectory'"; ## no critic (ErrorHandling::RequireCheckingReturnValueOfEval) } ##################################################################### # Current User Methods ## no critic qw(UnusedPrivateSubroutines) sub _guess_determined_home { my $class = shift; require Mac::SystemDirectory; my $home = Mac::SystemDirectory::HomeDirectory(); $home ||= $class->SUPER::_guess_determined_home($@); return $home; } # from 10.4 sub my_desktop { my $class = shift; require Mac::SystemDirectory; eval { $class->_find_folder(Mac::SystemDirectory::NSDesktopDirectory()) } || $class->SUPER::my_desktop; } # from 10.2 sub my_documents { my $class = shift; require Mac::SystemDirectory; eval { $class->_find_folder(Mac::SystemDirectory::NSDocumentDirectory()) } || $class->SUPER::my_documents; } # from 10.4 sub my_data { my $class = shift; require Mac::SystemDirectory; eval { $class->_find_folder(Mac::SystemDirectory::NSApplicationSupportDirectory()) } || $class->SUPER::my_data; } # from 10.6 sub my_music { my $class = shift; require Mac::SystemDirectory; eval { $class->_find_folder(Mac::SystemDirectory::NSMusicDirectory()) } || $class->SUPER::my_music; } # from 10.6 sub my_pictures { my $class = shift; require Mac::SystemDirectory; eval { $class->_find_folder(Mac::SystemDirectory::NSPicturesDirectory()) } || $class->SUPER::my_pictures; } # from 10.6 sub my_videos { my $class = shift; require Mac::SystemDirectory; eval { $class->_find_folder(Mac::SystemDirectory::NSMoviesDirectory()) } || $class->SUPER::my_videos; } sub _find_folder { my $class = shift; my $name = shift; require Mac::SystemDirectory; my $folder = Mac::SystemDirectory::FindDirectory($name); return undef unless defined $folder; unless (-d $folder) { # Make sure that symlinks resolve to directories. return undef unless -l $folder; my $dir = readlink $folder or return; return undef unless -d $dir; } return Cwd::abs_path($folder); } 1; =pod =head1 NAME File::HomeDir::Darwin::Cocoa - Find your home and other directories on Darwin (OS X) =head1 DESCRIPTION This module provides Darwin-specific implementations for determining common user directories using Cocoa API through L. In normal usage this module will always be used via L. Theoretically, this should return the same paths as both of the other Darwin drivers. Because this module requires L, if the module is not installed, L will fall back to L. =head1 SYNOPSIS use File::HomeDir; # Find directories for the current user $home = File::HomeDir->my_home; # /Users/mylogin $desktop = File::HomeDir->my_desktop; # /Users/mylogin/Desktop $docs = File::HomeDir->my_documents; # /Users/mylogin/Documents $music = File::HomeDir->my_music; # /Users/mylogin/Music $pics = File::HomeDir->my_pictures; # /Users/mylogin/Pictures $videos = File::HomeDir->my_videos; # /Users/mylogin/Movies $data = File::HomeDir->my_data; # /Users/mylogin/Library/Application Support =cut File-HomeDir-1.004/lib/File/HomeDir/Darwin/Carbon.pm0000644000175000017500000001125513272253612020053 0ustar snosnopackage File::HomeDir::Darwin::Carbon; # Basic implementation for the Dawin family of operating systems. # This includes (most prominently) Mac OS X. use 5.008003; use strict; use warnings; use Cwd (); use Carp (); use File::HomeDir::Darwin (); use vars qw{$VERSION}; # This is only a child class of the pure Perl darwin # class so that we can do homedir detection of all three # drivers at one via ->isa. use base "File::HomeDir::Darwin"; BEGIN { $VERSION = '1.004'; # Load early if in a forking environment and we have # prefork, or at run-time if not. local $@; ## no critic (Variables::RequireInitializationForLocalVars) eval "use prefork 'Mac::Files'"; ## no critic (ErrorHandling::RequireCheckingReturnValueOfEval) } ##################################################################### # Current User Methods ## no critic qw(UnusedPrivateSubroutines) sub _guess_determined_home { my $class = shift; require Mac::Files; my $home = $class->_find_folder(Mac::Files::kCurrentUserFolderType(),); $home ||= $class->SUPER::_guess_determined_home($@); return $home; } sub my_desktop { my $class = shift; require Mac::Files; $class->_find_folder(Mac::Files::kDesktopFolderType(),); } sub my_documents { my $class = shift; require Mac::Files; $class->_find_folder(Mac::Files::kDocumentsFolderType(),); } sub my_data { my $class = shift; require Mac::Files; $class->_find_folder(Mac::Files::kApplicationSupportFolderType(),); } sub my_music { my $class = shift; require Mac::Files; $class->_find_folder(Mac::Files::kMusicDocumentsFolderType(),); } sub my_pictures { my $class = shift; require Mac::Files; $class->_find_folder(Mac::Files::kPictureDocumentsFolderType(),); } sub my_videos { my $class = shift; require Mac::Files; $class->_find_folder(Mac::Files::kMovieDocumentsFolderType(),); } sub _find_folder { my $class = shift; my $name = shift; require Mac::Files; my $folder = Mac::Files::FindFolder(Mac::Files::kUserDomain(), $name,); return undef unless defined $folder; unless (-d $folder) { # Make sure that symlinks resolve to directories. return undef unless -l $folder; my $dir = readlink $folder or return; return undef unless -d $dir; } return Cwd::abs_path($folder); } ##################################################################### # Arbitrary User Methods sub users_home { my $class = shift; my $home = $class->SUPER::users_home(@_); return defined $home ? Cwd::abs_path($home) : undef; } # in theory this can be done, but for now, let's cheat, since the # rest is Hard sub users_desktop { my ($class, $name) = @_; return undef if $name eq 'root'; $class->_to_user($class->my_desktop, $name); } sub users_documents { my ($class, $name) = @_; return undef if $name eq 'root'; $class->_to_user($class->my_documents, $name); } sub users_data { my ($class, $name) = @_; $class->_to_user($class->my_data, $name) || $class->users_home($name); } # cheap hack ... not entirely reliable, perhaps, but ... c'est la vie, since # there's really no other good way to do it at this time, that i know of -- pudge sub _to_user { my ($class, $path, $name) = @_; my $my_home = $class->my_home; my $users_home = $class->users_home($name); defined $users_home or return undef; $path =~ s/^\Q$my_home/$users_home/; return $path; } 1; =pod =head1 NAME File::HomeDir::Darwin - Find your home and other directories on Darwin (OS X) =head1 DESCRIPTION This module provides Darwin-specific implementations for determining common user directories. In normal usage this module will always be used via L. Note -- since this module requires Mac::Carbon and Mac::Carbon does not work with 64-bit perls, on such systems, File::HomeDir will try L and then fall back to the (pure Perl) L. =head1 SYNOPSIS use File::HomeDir; # Find directories for the current user $home = File::HomeDir->my_home; # /Users/mylogin $desktop = File::HomeDir->my_desktop; # /Users/mylogin/Desktop $docs = File::HomeDir->my_documents; # /Users/mylogin/Documents $music = File::HomeDir->my_music; # /Users/mylogin/Music $pics = File::HomeDir->my_pictures; # /Users/mylogin/Pictures $videos = File::HomeDir->my_videos; # /Users/mylogin/Movies $data = File::HomeDir->my_data; # /Users/mylogin/Library/Application Support =head1 TODO =over 4 =item * Test with Mac OS (versions 7, 8, 9) =item * Some better way for users_* ? =back File-HomeDir-1.004/lib/File/HomeDir/Driver.pm0000644000175000017500000000217113272253612016653 0ustar snosnopackage File::HomeDir::Driver; # Abstract base class that provides no functionality, # but confirms the class is a File::HomeDir driver class. use 5.008003; use strict; use warnings; use Carp (); use vars qw{$VERSION}; BEGIN { $VERSION = '1.004'; } sub my_home { Carp::croak("$_[0] does not implement compulsory method $_[1]"); } 1; =pod =head1 NAME File::HomeDir::Driver - Base class for all File::HomeDir drivers =head1 DESCRIPTION This module is the base class for all L drivers, and must be inherited from to identify a class as a driver. It is primarily provided as a convenience for this specific identification purpose, as L supports the specification of custom drivers and an C<-Eisa> check is used during the loading of the driver. =head1 AUTHOR Adam Kennedy Eadamk@cpan.orgE =head1 SEE ALSO L =head1 COPYRIGHT Copyright 2009 - 2011 Adam Kennedy. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of the license can be found in the LICENSE file included with this module. =cut File-HomeDir-1.004/lib/File/HomeDir/Unix.pm0000644000175000017500000000735213272253612016351 0ustar snosnopackage File::HomeDir::Unix; # See POD at the end of the file for documentation use 5.008003; use strict; use warnings; use Carp (); use File::HomeDir::Driver (); use vars qw{$VERSION}; use base "File::HomeDir::Driver"; BEGIN { $VERSION = '1.004'; } ##################################################################### # Current User Methods sub my_home { my $class = shift; my $home = $class->_guess_home(@_); # On Unix in general, a non-existent home means "no home" # For example, "nobody"-like users might use /nonexistent if (defined $home and not -d $home) { $home = undef; } return $home; } sub _guess_env_home { my $class = shift; if (exists $ENV{HOME} and defined $ENV{HOME} and length $ENV{HOME}) { return $ENV{HOME}; } # This is from the original code, but I'm guessing # it means "login directory" and exists on some Unixes. if (exists $ENV{LOGDIR} and $ENV{LOGDIR}) { return $ENV{LOGDIR}; } return; } sub _guess_determined_home { my $class = shift; # Light desperation on any (Unixish) platform SCOPE: { my $home = (getpwuid($<))[7]; return $home if $home and -d $home; } return; } sub _guess_home { my $class = shift; my $home = $class->_guess_env_home($@); $home ||= $class->_guess_determined_home($@); return $home; } # On unix by default, everything is under the same folder sub my_desktop { shift->my_home; } sub my_documents { shift->my_home; } sub my_data { shift->my_home; } sub my_music { shift->my_home; } sub my_pictures { shift->my_home; } sub my_videos { shift->my_home; } ##################################################################### # General User Methods sub users_home { my ($class, $name) = @_; # IF and only if we have getpwuid support, and the # name of the user is our own, shortcut to my_home. # This is needed to handle HOME environment settings. if ($name eq getpwuid($<)) { return $class->my_home; } SCOPE: { my $home = (getpwnam($name))[7]; return $home if $home and -d $home; } return undef; } sub users_desktop { shift->users_home(@_); } sub users_documents { shift->users_home(@_); } sub users_data { shift->users_home(@_); } sub users_music { shift->users_home(@_); } sub users_pictures { shift->users_home(@_); } sub users_videos { shift->users_home(@_); } 1; =pod =head1 NAME File::HomeDir::Unix - Find your home and other directories on legacy Unix =head1 SYNOPSIS use File::HomeDir; # Find directories for the current user $home = File::HomeDir->my_home; # /home/mylogin $desktop = File::HomeDir->my_desktop; # All of these will... $docs = File::HomeDir->my_documents; # ...default to home... $music = File::HomeDir->my_music; # ...directory $pics = File::HomeDir->my_pictures; # $videos = File::HomeDir->my_videos; # $data = File::HomeDir->my_data; # =head1 DESCRIPTION This module provides implementations for determining common user directories. In normal usage this module will always be used via L. =head1 SUPPORT See the support section the main L module. =head1 AUTHORS Adam Kennedy Eadamk@cpan.orgE Sean M. Burke Esburke@cpan.orgE =head1 SEE ALSO L, L (legacy) =head1 COPYRIGHT Copyright 2005 - 2011 Adam Kennedy. Some parts copyright 2000 Sean M. Burke. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of the license can be found in the LICENSE file included with this module. =cut File-HomeDir-1.004/lib/File/HomeDir/Test.pm0000644000175000017500000000622213272253612016340 0ustar snosnopackage File::HomeDir::Test; use 5.008003; use strict; use warnings; use Carp (); use File::Spec (); use File::Temp (); use File::HomeDir::Driver (); use vars qw{$VERSION %DIR $ENABLED}; use base "File::HomeDir::Driver"; BEGIN { $VERSION = '1.004'; %DIR = (); $ENABLED = 0; } # Special magic use in test scripts sub import { my $class = shift; Carp::croak "Attempted to initialise File::HomeDir::Test trice" if %DIR; # Fill the test directories my $BASE = File::Temp::tempdir(CLEANUP => 1); %DIR = map { $_ => File::Spec->catdir($BASE, $_) } qw{ my_home my_desktop my_documents my_data my_music my_pictures my_videos }; # Hijack HOME to the home directory $ENV{HOME} = $DIR{my_home}; ## no critic qw(LocalizedPunctuationVars) # Make File::HomeDir load us instead of the native driver $File::HomeDir::IMPLEMENTED_BY = # Prevent a warning $File::HomeDir::IMPLEMENTED_BY = 'File::HomeDir::Test'; # Ready to go $ENABLED = 1; } ##################################################################### # Current User Methods sub my_home { mkdir($DIR{my_home}, oct(755)) unless -d $DIR{my_home}; return $DIR{my_home}; } sub my_desktop { mkdir($DIR{my_desktop}, oct(755)) unless -d $DIR{my_desktop}; return $DIR{my_desktop}; } sub my_documents { mkdir($DIR{my_documents}, oct(755)) unless -f $DIR{my_documents}; return $DIR{my_documents}; } sub my_data { mkdir($DIR{my_data}, oct(755)) unless -d $DIR{my_data}; return $DIR{my_data}; } sub my_music { mkdir($DIR{my_music}, oct(755)) unless -d $DIR{my_music}; return $DIR{my_music}; } sub my_pictures { mkdir($DIR{my_pictures}, oct(755)) unless -d $DIR{my_pictures}; return $DIR{my_pictures}; } sub my_videos { mkdir($DIR{my_videos}, oct(755)) unless -d $DIR{my_videos}; return $DIR{my_videos}; } sub users_home { return undef; } 1; __END__ =pod =head1 NAME File::HomeDir::Test - Prevent the accidental creation of user-owned files during testing =head1 SYNOPSIS use Test::More test => 1; use File::HomeDir::Test; use File::HomeDir; =head1 DESCRIPTION B is a L driver intended for use in the test scripts of modules or applications that write files into user-owned directories. It is designed to prevent the pollution of user directories with files that are not part of the application install itself, but were created during testing. These files can leak state information from the tests into the run-time usage of an application, and on Unix systems also prevents tests (which may be executed as root via sudo) from writing files which cannot later be modified or removed by the regular user. =head1 SUPPORT See the support section of the main L documentation. =head1 AUTHOR Adam Kennedy Eadamk@cpan.orgE =head1 COPYRIGHT Copyright 2005 - 2011 Adam Kennedy. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of the license can be found in the LICENSE file included with this module. =cut File-HomeDir-1.004/lib/File/HomeDir/Windows.pm0000644000175000017500000001515313272253612017056 0ustar snosnopackage File::HomeDir::Windows; # See POD at the end of the file for documentation use 5.008003; use strict; use warnings; use Carp (); use File::Spec (); use File::HomeDir::Driver (); use vars qw{$VERSION}; use base "File::HomeDir::Driver"; BEGIN { $VERSION = '1.004'; } sub CREATE () { 1 } ##################################################################### # Current User Methods sub my_home { my $class = shift; # A lot of unix people and unix-derived tools rely on # the ability to overload HOME. We will support it too # so that they can replace raw HOME calls with File::HomeDir. if (exists $ENV{HOME} and defined $ENV{HOME} and length $ENV{HOME}) { return $ENV{HOME}; } # Do we have a user profile? if (exists $ENV{USERPROFILE} and $ENV{USERPROFILE}) { return $ENV{USERPROFILE}; } # Some Windows use something like $ENV{HOME} if (exists $ENV{HOMEDRIVE} and exists $ENV{HOMEPATH} and $ENV{HOMEDRIVE} and $ENV{HOMEPATH}) { return File::Spec->catpath($ENV{HOMEDRIVE}, $ENV{HOMEPATH}, '',); } return undef; } sub my_desktop { my $class = shift; # The most correct way to find the desktop SCOPE: { require Win32; my $dir = Win32::GetFolderPath(Win32::CSIDL_DESKTOP(), CREATE); return $dir if $dir and $class->_d($dir); } # MSWindows sets WINDIR, MS WinNT sets USERPROFILE. foreach my $e ('USERPROFILE', 'WINDIR') { next unless $ENV{$e}; my $desktop = File::Spec->catdir($ENV{$e}, 'Desktop'); return $desktop if $desktop and $class->_d($desktop); } # As a last resort, try some hard-wired values foreach my $fixed ( # The reason there are both types of slash here is because # this set of paths has been kept from the original version # of File::HomeDir::Win32 (before it was rewritten). # I can only assume this is Cygwin-related stuff. "C:\\windows\\desktop", "C:\\win95\\desktop", "C:/win95/desktop", "C:/windows/desktop", ) { return $fixed if $class->_d($fixed); } return undef; } sub my_documents { my $class = shift; # The most correct way to find my documents SCOPE: { require Win32; my $dir = Win32::GetFolderPath(Win32::CSIDL_PERSONAL(), CREATE); return $dir if $dir and $class->_d($dir); } return undef; } sub my_data { my $class = shift; # The most correct way to find my documents SCOPE: { require Win32; my $dir = Win32::GetFolderPath(Win32::CSIDL_LOCAL_APPDATA(), CREATE); return $dir if $dir and $class->_d($dir); } return undef; } sub my_music { my $class = shift; # The most correct way to find my music SCOPE: { require Win32; my $dir = Win32::GetFolderPath(Win32::CSIDL_MYMUSIC(), CREATE); return $dir if $dir and $class->_d($dir); } return undef; } sub my_pictures { my $class = shift; # The most correct way to find my pictures SCOPE: { require Win32; my $dir = Win32::GetFolderPath(Win32::CSIDL_MYPICTURES(), CREATE); return $dir if $dir and $class->_d($dir); } return undef; } sub my_videos { my $class = shift; # The most correct way to find my videos SCOPE: { require Win32; my $dir = Win32::GetFolderPath(Win32::CSIDL_MYVIDEO(), CREATE); return $dir if $dir and $class->_d($dir); } return undef; } # Special case version of -d sub _d { my $self = shift; my $path = shift; # Window can legally return a UNC path from GetFolderPath. # Not only is the meaning of -d complicated in this situation, # but even on a local network calling -d "\\\\cifs\\path" can # take several seconds. UNC can also do even weirder things, # like launching processes and such. # To avoid various crazy bugs caused by this, we do NOT attempt # to validate UNC paths at all so that the code that is calling # us has an opportunity to take special actions without our # blundering getting in the way. if ($path =~ /\\\\/) { return 1; } # Otherwise do a stat as normal return -d $path; } 1; =pod =head1 NAME File::HomeDir::Windows - Find your home and other directories on Windows =head1 SYNOPSIS use File::HomeDir; # Find directories for the current user (eg. using Windows XP Professional) $home = File::HomeDir->my_home; # C:\Documents and Settings\mylogin $desktop = File::HomeDir->my_desktop; # C:\Documents and Settings\mylogin\Desktop $docs = File::HomeDir->my_documents; # C:\Documents and Settings\mylogin\My Documents $music = File::HomeDir->my_music; # C:\Documents and Settings\mylogin\My Documents\My Music $pics = File::HomeDir->my_pictures; # C:\Documents and Settings\mylogin\My Documents\My Pictures $videos = File::HomeDir->my_videos; # C:\Documents and Settings\mylogin\My Documents\My Video $data = File::HomeDir->my_data; # C:\Documents and Settings\mylogin\Local Settings\Application Data =head1 DESCRIPTION This module provides Windows-specific implementations for determining common user directories. In normal usage this module will always be used via L. Internally this module will use L::GetFolderPath to fetch the location of your directories. As a result of this, in certain unusual situations (usually found inside large organizations) the methods may return UNC paths such as C<\\cifs.local\home$>. If your application runs on Windows and you want to have it work comprehensively everywhere, you may need to implement your own handling for these paths as they can cause strange behaviour. For example, stat calls to UNC paths may work but block for several seconds, but opendir() may not be able to read any files (creating the appearance of an existing but empty directory). To avoid complicating the problem any further, in the rare situation that a UNC path is returned by C the usual -d validation checks will B be done. =head1 SUPPORT See the support section the main L module. =head1 AUTHORS Adam Kennedy Eadamk@cpan.orgE Sean M. Burke Esburke@cpan.orgE =head1 SEE ALSO L, L (legacy) =head1 COPYRIGHT Copyright 2005 - 2011 Adam Kennedy. Some parts copyright 2000 Sean M. Burke. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of the license can be found in the LICENSE file included with this module. =cut File-HomeDir-1.004/lib/File/HomeDir/FreeDesktop.pm0000644000175000017500000001017013272253612017631 0ustar snosnopackage File::HomeDir::FreeDesktop; # Specific functionality for unixes running free desktops # compatible with (but not using) File-BaseDir-0.03 # See POD at the end of the file for more documentation. use 5.008003; use strict; use warnings; use Carp (); use File::Spec (); use File::Which (); use File::HomeDir::Unix (); use vars qw{$VERSION}; use base "File::HomeDir::Unix"; BEGIN { $VERSION = '1.004'; } # xdg uses $ENV{XDG_CONFIG_HOME}/user-dirs.dirs to know where are the # various "my xxx" directories. That is a shell file. The official API # is the xdg-user-dir executable. It has no provision for assessing # the directories of a user that is different than the one we are # running under; the standard substitute user mechanisms are needed to # overcome this. my $xdgprog = File::Which::which('xdg-user-dir'); sub _my { # No quoting because input is hard-coded and only comes from this module my $thingy = qx($xdgprog $_[1]); chomp $thingy; return $thingy; } # Simple stuff sub my_desktop { shift->_my('DESKTOP') } sub my_documents { shift->_my('DOCUMENTS') } sub my_music { shift->_my('MUSIC') } sub my_pictures { shift->_my('PICTURES') } sub my_videos { shift->_my('VIDEOS') } sub my_data { $ENV{XDG_DATA_HOME} or File::Spec->catdir(shift->my_home, qw{ .local share }); } sub my_config { $ENV{XDG_CONFIG_HOME} or File::Spec->catdir(shift->my_home, qw{ .config }); } # Custom locations (currently undocumented) sub my_download { shift->_my('DOWNLOAD') } sub my_publicshare { shift->_my('PUBLICSHARE') } sub my_templates { shift->_my('TEMPLATES') } sub my_cache { $ENV{XDG_CACHE_HOME} || File::Spec->catdir(shift->my_home, qw{ .cache }); } ##################################################################### # General User Methods sub users_desktop { Carp::croak('The users_desktop method is not available on an XDG based system.'); } sub users_documents { Carp::croak('The users_documents method is not available on an XDG based system.'); } sub users_music { Carp::croak('The users_music method is not available on an XDG based system.'); } sub users_pictures { Carp::croak('The users_pictures method is not available on an XDG based system.'); } sub users_videos { Carp::croak('The users_videos method is not available on an XDG based system.'); } sub users_data { Carp::croak('The users_data method is not available on an XDG based system.'); } 1; =pod =head1 NAME File::HomeDir::FreeDesktop - Find your home and other directories on FreeDesktop.org Unix =head1 DESCRIPTION This module provides implementations for determining common user directories. In normal usage this module will always be used via L. This module can operate only when the command C is available and executable, which is typically achieved by installed a package named C or similar. One can find the latest spec at L. =head1 SYNOPSIS use File::HomeDir; # Find directories for the current user $home = File::HomeDir->my_home; # /home/mylogin $desktop = File::HomeDir->my_desktop; $docs = File::HomeDir->my_documents; $music = File::HomeDir->my_music; $pics = File::HomeDir->my_pictures; $videos = File::HomeDir->my_videos; $data = File::HomeDir->my_data; $config = File::HomeDir->my_config; # Some undocumented ones, expect they don't work - use with caution $download = File::HomeDir->my_download; $publicshare = File::HomeDir->my_publicshare; $templates = File::HomeDir->my_templates; $cache = File::HomeDir->my_cache; =head1 AUTHORS Jerome Quelin Ejquellin@cpan.org Adam Kennedy Eadamk@cpan.orgE =head1 SEE ALSO L, L (legacy) =head1 COPYRIGHT Copyright 2009 - 2011 Jerome Quelin. Some parts copyright 2010 Adam Kennedy. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself. The full text of the license can be found in the LICENSE file included with this module. =cut