NAME
File::HomeDir - Get the home directory for yourself or other users
SYNOPSIS
use File::HomeDir;
# Modern Interface (Current User)
$home = File::HomeDir->my_home;
$docs = File::HomeDir->my_documents;
$data = File::HomeDir->my_data;
# Modern Interface (Other Users)
$home = File::HomeDir->users_home('foo');
$docs = File::HomeDir->users_documents('foo');
$data = File::HomeDir->users_data('foo');
# Legacy Interfaces
print "My dir is ", home(), " and root's is ", home('root'), "\n";
print "My dir is $~{''} and root's is $~{root}\n";
# These both print the same thing, something like:
# "My dir is /home/user/mojo and root's is /"DESCRIPTION
File::HomeDir is a module for dealing with issues relating to the location of directories for various purposes that are "owned" by a user, and to solve these problems consistently across a wide variety of platforms.
This module provides two main interfaces.
The first is a modern File::Spec-style interface with a consistent OO API and different implementation modules to support various platforms, and the second is a legacy interface from version 0.07 that exported a home() function by default and tied the %~ variable.
Platform Neutrality
In the Unix world, many different types of data can be mixed together in your home directory. On some other platforms, seperate directories are allocated for different types of data.
When writing applications, you should try to use the most specific method you can. User documents should be saved in my_documents, data to support an application should go in my_data.
On platforms that do not make this distinction, all these methods will harmlessly degrade to the main home directory, but on platforms that care File::HomeDir will 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 necesary, as on many platforms it is MUCH easier to find information about the current user compared to other users.
All methods via a -d test that the directory actually exists before returning. However, because in some cases, certain platforms may not support the concept of home directories at all, a method may return undef (both in scalar and list context) to indicate that there is no matching directory on the system. But anything returned can be trusted to actually exist.
my_home
The my_home takes no arguments and returns the main home/profile directory for the current user.
Returns the directory path as a string, undef if the current user does not have a home direcotry, or dies on error.
my_documents
The my_documents 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_data
The my_data takes no arguments and returns the directory where local applications should stored 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.
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.
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
Returns the directory path as a string, undef if that user does not have a data 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.
TIED INTERFACE
%~
$home = $~{""};
$home = $~{undef};
$home = $~{$user};
$home = $~{username};
print "... $~{''} ...";
print "... $~{$user} ...";
print "... $~{username} ...";This calls home($user) or home('username') -- except that if you ask for $~{some_user} and there is no such user, it will die.
Note that this is especially useful in double-quotish strings, like:
print "Jojo's .newsrc is ", -s "$~{jojo}/.newsrc", "b long!\n";
# (helpfully dies if there is no user 'jojo')If you want to avoid the fatal errors, first test the value of home('jojo'), which will return undef (instead of dying) in case of there being no such user.
Note, however, that if the hash key is "" or undef (whether thru being a literal "", or a scalar whose value is empty-string or undef), then this returns zero-argument home(), i.e., your home directory:
TO DO
- Become generally clearer on situations in which a user might not have a particular resource.
- Add support for the root Mac user (requested by JKEENAN).
- Add support for my_desktop (requested by RRWO)
- Add support for my_music (requested by MIYAGAWA)
- Merge remaining edge case code in File::HomeDir::Win32
- Add more granularity to Unix, and add support to VMS and other esoteric platforms, so we can consider going core.
Anyone wishing to add support for the above are welcome to get an account to my SVN and add it directly.
SUPPORT
Bugs should be always be reported via the CPAN bug tracker at
http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-HomeDir
For other issues, or commercial enhancement or support, contact the author.
AUTHORS
Adam Kennedy <cpan@ali.as>
Original implementation by:
Sean M. Burke sburke@cpan.org
SEE ALSO
File::ShareDir, File::HomeDir::Win32 (legacy)
COPYRIGHT
Copyright 2005, 2006 Adam Kennedy. All rights reserved.
Some parts copyright 2000 Sean M. Burke. All rights reserved.
Some parts copyright 2006 Chris Nandor. All rights reserved.
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.