{
    "content": [
        {
            "type": "text",
            "text": "# File::HomeDir (perldoc)\n\n## NAME\n\nFile::HomeDir - Find your home and other directories on any platform\n\n## SYNOPSIS\n\nuse File::HomeDir;\n# Modern Interface (Current User)\n$home     = File::HomeDir->myhome;\n$desktop  = File::HomeDir->mydesktop;\n$docs     = File::HomeDir->mydocuments;\n$music    = File::HomeDir->mymusic;\n$pics     = File::HomeDir->mypictures;\n$videos   = File::HomeDir->myvideos;\n$data     = File::HomeDir->mydata;\n$dist     = File::HomeDir->mydistdata('File-HomeDir');\n$dist     = File::HomeDir->mydistconfig('File-HomeDir');\n# Modern Interface (Other Users)\n$home    = File::HomeDir->usershome('foo');\n$desktop = File::HomeDir->usersdesktop('foo');\n$docs    = File::HomeDir->usersdocuments('foo');\n$music   = File::HomeDir->usersmusic('foo');\n$pics    = File::HomeDir->userspictures('foo');\n$video   = File::HomeDir->usersvideos('foo');\n$data    = File::HomeDir->usersdata('foo');\n\n## DESCRIPTION\n\nFile::HomeDir is a module for locating the directories that are \"owned\" by a user (typically\nyour user) and to solve the various issues that arise trying to find them consistently across a\nwide variety of platforms.\n\n## Sections\n\n- **NAME**\n- **SYNOPSIS**\n- **DESCRIPTION** (1 subsections)\n- **METHODS**\n- **FUNCTIONS**\n- **TO DO**\n- **SUPPORT**\n- **ACKNOWLEDGEMENTS**\n- **AUTHORS**\n- **SEE ALSO**\n- **COPYRIGHT**\n\nUse structuredContent.sections for detailed options, examples, and full documentation.\n"
        }
    ],
    "structuredContent": {
        "command": "File::HomeDir",
        "section": "",
        "mode": "perldoc",
        "summary": "File::HomeDir - Find your home and other directories on any platform",
        "synopsis": "use File::HomeDir;\n# Modern Interface (Current User)\n$home     = File::HomeDir->myhome;\n$desktop  = File::HomeDir->mydesktop;\n$docs     = File::HomeDir->mydocuments;\n$music    = File::HomeDir->mymusic;\n$pics     = File::HomeDir->mypictures;\n$videos   = File::HomeDir->myvideos;\n$data     = File::HomeDir->mydata;\n$dist     = File::HomeDir->mydistdata('File-HomeDir');\n$dist     = File::HomeDir->mydistconfig('File-HomeDir');\n# Modern Interface (Other Users)\n$home    = File::HomeDir->usershome('foo');\n$desktop = File::HomeDir->usersdesktop('foo');\n$docs    = File::HomeDir->usersdocuments('foo');\n$music   = File::HomeDir->usersmusic('foo');\n$pics    = File::HomeDir->userspictures('foo');\n$video   = File::HomeDir->usersvideos('foo');\n$data    = File::HomeDir->usersdata('foo');",
        "tldr_summary": null,
        "tldr_examples": [],
        "tldr_source": null,
        "flags": [],
        "examples": [],
        "see_also": [],
        "section_outline": [
            {
                "name": "NAME",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "SYNOPSIS",
                "lines": 22,
                "subsections": []
            },
            {
                "name": "DESCRIPTION",
                "lines": 8,
                "subsections": [
                    {
                        "name": "Platform Neutrality",
                        "lines": 15
                    }
                ]
            },
            {
                "name": "METHODS",
                "lines": 206,
                "subsections": []
            },
            {
                "name": "FUNCTIONS",
                "lines": 15,
                "subsections": []
            },
            {
                "name": "TO DO",
                "lines": 5,
                "subsections": []
            },
            {
                "name": "SUPPORT",
                "lines": 22,
                "subsections": []
            },
            {
                "name": "ACKNOWLEDGEMENTS",
                "lines": 4,
                "subsections": []
            },
            {
                "name": "AUTHORS",
                "lines": 8,
                "subsections": []
            },
            {
                "name": "SEE ALSO",
                "lines": 2,
                "subsections": []
            },
            {
                "name": "COPYRIGHT",
                "lines": 17,
                "subsections": []
            }
        ],
        "sections": {
            "NAME": {
                "content": "File::HomeDir - Find your home and other directories on any platform\n",
                "subsections": []
            },
            "SYNOPSIS": {
                "content": "use File::HomeDir;\n\n# Modern Interface (Current User)\n$home     = File::HomeDir->myhome;\n$desktop  = File::HomeDir->mydesktop;\n$docs     = File::HomeDir->mydocuments;\n$music    = File::HomeDir->mymusic;\n$pics     = File::HomeDir->mypictures;\n$videos   = File::HomeDir->myvideos;\n$data     = File::HomeDir->mydata;\n$dist     = File::HomeDir->mydistdata('File-HomeDir');\n$dist     = File::HomeDir->mydistconfig('File-HomeDir');\n\n# Modern Interface (Other Users)\n$home    = File::HomeDir->usershome('foo');\n$desktop = File::HomeDir->usersdesktop('foo');\n$docs    = File::HomeDir->usersdocuments('foo');\n$music   = File::HomeDir->usersmusic('foo');\n$pics    = File::HomeDir->userspictures('foo');\n$video   = File::HomeDir->usersvideos('foo');\n$data    = File::HomeDir->usersdata('foo');\n",
                "subsections": []
            },
            "DESCRIPTION": {
                "content": "File::HomeDir is a module for locating the directories that are \"owned\" by a user (typically\nyour user) and to solve the various issues that arise trying to find them consistently across a\nwide variety of platforms.\n\nThe end result is a single API that can find your resources on any platform, making it\nrelatively trivial to create Perl software that works elegantly and correctly no matter where\nyou run it.\n",
                "subsections": [
                    {
                        "name": "Platform Neutrality",
                        "content": "In the Unix world, many different types of data can be mixed together in your home directory\n(although on some Unix platforms this is no longer the case, particularly for \"desktop\"-oriented\nplatforms).\n\nOn some non-Unix platforms, separate directories are allocated for different types of data and\nhave been for a long time.\n\nWhen writing applications on top of File::HomeDir, you should thus always try to use the most\nspecific method you can. User documents should be saved in \"mydocuments\", data that supports an\napplication but isn't normally editing by the user directory should go into \"mydata\".\n\nOn platforms that do not make any distinction, all these different methods will harmlessly\ndegrade to the main home directory, but on platforms that care File::HomeDir will always try to\nDo The Right Thing(tm).\n"
                    }
                ]
            },
            "METHODS": {
                "content": "Two types of methods are provided. The \"mymethod\" series of methods for finding resources for\nthe current user, and the \"usersmethod\" (read as \"user's method\") series for finding resources\nfor arbitrary users.\n\nThis split is necessary, as on most platforms it is much easier to find information about the\ncurrent user compared to other users, and indeed on a number you cannot find out information\nsuch as \"usersdesktop\" at all, due to security restrictions.\n\nAll methods will double check (using a \"-d\" test) that a directory actually exists before\nreturning it, so you may trust in the values that are returned (subject to the usual caveats of\nrace conditions of directories being deleted at the moment between a directory being returned\nand you using it).\n\nHowever, because in some cases platforms may not support the concept of home directories at all,\nany method may return \"undef\" (both in scalar and list context) to indicate that there is no\nmatching directory on the system.\n\nFor example, most untrusted 'nobody'-type users do not have a home directory. So any modules\nthat are used in a CGI application that at some level of recursion use your code, will result in\ncalls to File::HomeDir returning undef, even for a basic home() call.\n\nmyhome\nThe \"myhome\" method takes no arguments and returns the main home/profile directory for the\ncurrent user.\n\nIf the distinction is important to you, the term \"current\" refers to the real user, and not the\neffective user.\n\nThis is also the case for all of the other \"my\" methods.\n\nReturns the directory path as a string, \"undef\" if the current user does not have a home\ndirectory, or dies on error.\n\nmydesktop\nThe \"mydesktop\" method takes no arguments and returns the \"desktop\" directory for the current\nuser.\n\nDue to the diversity and complexity of implementations required to deal with implementing the\nrequired functionality fully and completely, the \"mydesktop\" method may or may not be\nimplemented on each platform.\n\nThat said, I am extremely interested in code to implement \"mydesktop\" on Unix, as long as it is\ncapable of dealing (as the Windows implementation does) with internationalization. It should\nalso avoid false positive results by making sure it only returns the appropriate directories for\nthe appropriate platforms.\n\nReturns the directory path as a string, \"undef\" if the current user does not have a desktop\ndirectory, or dies on error.\n\nmydocuments\nThe \"mydocuments\" method takes no arguments and returns the directory (for the current user)\nwhere the user's documents are stored.\n\nReturns the directory path as a string, \"undef\" if the current user does not have a documents\ndirectory, or dies on error.\n\nmymusic\nThe \"mymusic\" method takes no arguments and returns the directory where the current user's\nmusic is stored.\n\nNo bias is made to any particular music type or music program, rather the concept of a directory\nto hold the user's music is made at the level of the underlying operating system or (at least)\ndesktop environment.\n\nReturns the directory path as a string, \"undef\" if the current user does not have a suitable\ndirectory, or dies on error.\n\nmypictures\nThe \"mypictures\" method takes no arguments and returns the directory where the current user's\npictures are stored.\n\nNo bias is made to any particular picture type or picture program, rather the concept of a\ndirectory to hold the user's pictures is made at the level of the underlying operating system or\n(at least) desktop environment.\n\nReturns the directory path as a string, \"undef\" if the current user does not have a suitable\ndirectory, or dies on error.\n\nmyvideos\nThe \"myvideos\" method takes no arguments and returns the directory where the current user's\nvideos are stored.\n\nNo bias is made to any particular video type or video program, rather the concept of a directory\nto hold the user's videos is made at the level of the underlying operating system or (at least)\ndesktop environment.\n\nReturns the directory path as a string, \"undef\" if the current user does not have a suitable\ndirectory, or dies on error.\n\nmydata\nThe \"mydata\" method takes no arguments and returns the directory where local applications\nshould store their internal data for the current user.\n\nGenerally an application would create a subdirectory such as \".foo\", beneath this directory, and\nstore its data there. By creating your directory this way, you get an accurate result on the\nmaximum number of platforms. But see the documentation about \"mydistconfig()\" or\n\"mydistdata()\" below.\n\nFor example, on Unix you get \"~/.foo\" and on Win32 you get \"~/Local Settings/Application\nData/.foo\"\n\nReturns the directory path as a string, \"undef\" if the current user does not have a data\ndirectory, or dies on error.\n\nmydistconfig\nFile::HomeDir->mydistconfig( $dist [, \\%params] );\n\n# For example...\n\nFile::HomeDir->mydistconfig( 'File-HomeDir' );\nFile::HomeDir->mydistconfig( 'File-HomeDir', { create => 1 } );\n\nThe \"mydistconfig\" method takes a distribution name as argument and returns an\napplication-specific directory where they should store their internal configuration.\n\nThe base directory will be either \"myconfig\" if the platform supports it, or \"mydocuments\"\notherwise. The subdirectory itself will be \"BASE/Perl/Dist-Name\". If the base directory is the\nuser's home directory, \"mydistconfig\" will be in \"~/.perl/Dist-Name\" (and thus be hidden on\nall Unixes).\n\nThe optional last argument is a hash reference to tweak the method behaviour. The following hash\nkeys are recognized:\n\n*   create\n\nPassing a true value to this key will force the creation of the directory if it doesn't\nexist (remember that \"File::HomeDir\"'s policy is to return \"undef\" if the directory doesn't\nexist).\n\nDefaults to false, meaning no automatic creation of directory.\n\nmydistdata\nFile::HomeDir->mydistdata( $dist [, \\%params] );\n\n# For example...\n\nFile::HomeDir->mydistdata( 'File-HomeDir' );\nFile::HomeDir->mydistdata( 'File-HomeDir', { create => 1 } );\n\nThe \"mydistdata\" method takes a distribution name as argument and returns an\napplication-specific directory where they should store their internal data.\n\nThis directory will be of course a subdirectory of \"mydata\". Platforms supporting data-specific\ndirectories will use \"DATADIR/perl/dist/Dist-Name\" following the common\n\"DATA/vendor/application\" pattern. If the \"mydata\" directory is the user's home directory,\n\"mydistdata\" will be in \"~/.perl/dist/Dist-Name\" (and thus be hidden on all Unixes).\n\nThe optional last argument is a hash reference to tweak the method behaviour. The following hash\nkeys are recognized:\n\n*   create\n\nPassing a true value to this key will force the creation of the directory if it doesn't\nexist (remember that \"File::HomeDir\"'s policy is to return \"undef\" if the directory doesn't\nexist).\n\nDefaults to false, meaning no automatic creation of directory.\n\nusershome\n$home = File::HomeDir->usershome('foo');\n\nThe \"usershome\" method takes a single parameter and is used to locate the parent home/profile\ndirectory for an identified user on the system.\n\nWhile most of the time this identifier would be some form of user name, it is permitted to vary\nper-platform to support user ids or UUIDs as applicable for that platform.\n\nReturns the directory path as a string, \"undef\" if that user does not have a home directory, or\ndies on error.\n\nusersdocuments\n$docs = File::HomeDir->usersdocuments('foo');\n\nReturns the directory path as a string, \"undef\" if that user does not have a documents\ndirectory, or dies on error.\n\nusersdata\n$data = File::HomeDir->usersdata('foo');\n\nReturns the directory path as a string, \"undef\" if that user does not have a data directory, or\ndies on error.\n\nusersdesktop\n$docs = File::HomeDir->usersdesktop('foo');\n\nReturns the directory path as a string, \"undef\" if that user does not have a desktop directory,\nor dies on error.\n\nusersmusic\n$docs = File::HomeDir->usersmusic('foo');\n\nReturns the directory path as a string, \"undef\" if that user does not have a music directory, or\ndies on error.\n\nuserspictures\n$docs = File::HomeDir->userspictures('foo');\n\nReturns the directory path as a string, \"undef\" if that user does not have a pictures directory,\nor dies on error.\n\nusersvideos\n$docs = File::HomeDir->usersvideos('foo');\n\nReturns the directory path as a string, \"undef\" if that user does not have a videos directory,\nor dies on error.\n",
                "subsections": []
            },
            "FUNCTIONS": {
                "content": "home\nuse File::HomeDir;\n$home = home();\n$home = home('foo');\n$home = File::HomeDir::home();\n$home = File::HomeDir::home('foo');\n\nThe \"home\" function is exported by default and is provided for compatibility with legacy\napplications. In new applications, you should use the newer method-based interface above.\n\nReturns the directory path to a named user's home/profile directory.\n\nIf provided no parameter, returns the directory path to the current user's home/profile\ndirectory.\n",
                "subsections": []
            },
            "TO DO": {
                "content": "*   Add more granularity to Unix, and add support to VMS and other esoteric platforms, so we can\nconsider going core.\n\n*   Add consistent support for users* methods\n",
                "subsections": []
            },
            "SUPPORT": {
                "content": "This module is stored in an Open Repository at the following address.\n\n<http://svn.ali.as/cpan/trunk/File-HomeDir>\n\nWrite access to the repository is made available automatically to any published CPAN author, and\nto most other volunteers on request.\n\nIf you are able to submit your bug report in the form of new (failing) unit tests, or can apply\nyour fix directly instead of submitting a patch, you are strongly encouraged to do so as the\nauthor currently maintains over 100 modules and it can take some time to deal with non-Critical\nbug reports or patches.\n\nThis will guarantee that your issue will be addressed in the next release of the module.\n\nIf you cannot provide a direct test or fix, or don't have time to do so, then regular bug\nreports are still accepted and appreciated via the CPAN bug tracker.\n\n<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-HomeDir>\n\nFor other issues, for commercial enhancement or support, or to have your write access enabled\nfor the repository, contact the author at the email address above.\n",
                "subsections": []
            },
            "ACKNOWLEDGEMENTS": {
                "content": "The biggest acknowledgement goes to Chris Nandor, who wielded his legendary Mac-fu and turned my\ninitial fairly ordinary Darwin implementation into something that actually worked properly\neverywhere, and then donated a Mac OS X license to allow it to be maintained properly.\n",
                "subsections": []
            },
            "AUTHORS": {
                "content": "Adam Kennedy <adamk@cpan.org>\n\nSean M. Burke <sburke@cpan.org>\n\nChris Nandor <cnandor@cpan.org>\n\nStephen Steneker <stennie@cpan.org>\n",
                "subsections": []
            },
            "SEE ALSO": {
                "content": "File::ShareDir, File::HomeDir::Win32 (legacy)\n",
                "subsections": []
            },
            "COPYRIGHT": {
                "content": "Copyright 2005 - 2012 Adam Kennedy.\n\nCopyright 2017 - 2020 Jens Rehsack\n\nSome parts copyright 2000 Sean M. Burke.\n\nSome parts copyright 2006 Chris Nandor.\n\nSome parts copyright 2006 Stephen Steneker.\n\nSome parts copyright 2009-2011 Jérôme Quelin.\n\nThis program is free software; you can redistribute it and/or modify it under the same terms as\nPerl itself.\n\nThe full text of the license can be found in the LICENSE file included with this module.\n",
                "subsections": []
            }
        }
    }
}