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.