File::ShareDir man page on Alpinelinux

Man page or keyword search:  
man Server   18016 pages
apropos Keyword Search (all sections)
Output format
Alpinelinux logo
[printable version]

File::ShareDir(3)     User Contributed Perl Documentation    File::ShareDir(3)

NAME
       File::ShareDir - Locate per-dist and per-module shared files

SYNOPSIS
	 use File::ShareDir ':ALL';

	 # Where are distribution-level shared data files kept
	 $dir = dist_dir('File-ShareDir');

	 # Where are module-level shared data files kept
	 $dir = module_dir('File::ShareDir');

	 # Find a specific file in our dist/module shared dir
	 $file = dist_file(  'File-ShareDir',  'file/name.txt');
	 $file = module_file('File::ShareDir', 'file/name.txt');

	 # Like module_file, but search up the inheritance tree
	 $file = class_file( 'Foo::Bar', 'file/name.txt' );

DESCRIPTION
       The intent of File::ShareDir is to provide a companion to
       Class::Inspector and File::HomeDir, modules that take a process that is
       well-known by advanced Perl developers but gets a little tricky, and
       make it more available to the larger Perl community.

       Quite often you want or need your Perl module (CPAN or otherwise) to
       have access to a large amount of read-only data that is stored on the
       file-system at run-time.

       On a linux-like system, this would be in a place such as /usr/share,
       however Perl runs on a wide variety of different systems, and so the
       use of any one location is unreliable.

       Perl provides a little-known method for doing this, but almost nobody
       is aware that it exists. As a result, module authors often go through
       some very strange ways to make the data available to their code.

       The most common of these is to dump the data out to an enormous Perl
       data structure and save it into the module itself. The result are
       enormous multi-megabyte .pm files that chew up a lot of memory
       needlessly.

       Another method is to put the data "file" after the __DATA__ compiler
       tag and limit yourself to access as a filehandle.

       The problem to solve is really quite simple.

	 1. Write the data files to the system at install time.

	 2. Know where you put them at run-time.

       Perl's install system creates an "auto" directory for both every
       distribution and for every module file.

       These are used by a couple of different auto-loading systems to store
       code fragments generated at install time, and various other modules
       written by the Perl "ancient masters".

       But the same mechanism is available to any dist or module to store any
       sort of data.

   Using Data in your Module
       "File::ShareDir" forms one half of a two part solution.

       Once the files have been installed to the correct directory, you can
       use "File::ShareDir" to find your files again after the installation.

       For the installation half of the solution, see Module::Install and its
       "install_share" directive.

FUNCTIONS
       "File::ShareDir" provides four functions for locating files and
       directories.

       For greater maintainability, none of these are exported by default and
       you are expected to name the ones you want at use-time, or provide the
       ':ALL' tag. All of the following are equivalent.

	 # Load but don't import, and then call directly
	 use File::ShareDir;
	 $dir = File::ShareDir::dist_dir('My-Dist');

	 # Import a single function
	 use File::ShareDir 'dist_dir';
	 dist_dir('My-Dist');

	 # Import all the functions
	 use File::ShareDir ':ALL';
	 dist_dir('My-Dist');

       All of the functions will check for you that the dir/file actually
       exists, and that you have read permissions, or they will throw an
       exception.

   dist_dir
	 # Get a distribution's shared files directory
	 my $dir = dist_dir('My-Distribution');

       The "dist_dir" function takes a single parameter of the name of an
       installed (CPAN or otherwise) distribution, and locates the shared data
       directory created at install time for it.

       Returns the directory path as a string, or dies if it cannot be located
       or is not readable.

   module_dir
	 # Get a module's shared files directory
	 my $dir = module_dir('My::Module');

       The "module_dir" function takes a single parameter of the name of an
       installed (CPAN or otherwise) module, and locates the shared data
       directory created at install time for it.

       In order to find the directory, the module must be loaded when calling
       this function.

       Returns the directory path as a string, or dies if it cannot be located
       or is not readable.

   dist_file
	 # Find a file in our distribution shared dir
	 my $dir = dist_file('My-Distribution', 'file/name.txt');

       The "dist_file" function takes two params of the distribution name and
       file name, locates the dist dir, and then finds the file within it,
       verifying that the file actually exists, and that it is readable.

       The filename should be a relative path in the format of your local
       filesystem. It will simply added to the directory using File::Spec's
       "catfile" method.

       Returns the file path as a string, or dies if the file or the dist's
       directory cannot be located, or the file is not readable.

   module_file
	 # Find a file in our module shared dir
	 my $dir = module_file('My::Module', 'file/name.txt');

       The "module_file" function takes two params of the module name and file
       name. It locates the module dir, and then finds the file within it,
       verifying that the file actually exists, and that it is readable.

       In order to find the directory, the module must be loaded when calling
       this function.

       The filename should be a relative path in the format of your local
       filesystem. It will simply added to the directory using File::Spec's
       "catfile" method.

       Returns the file path as a string, or dies if the file or the dist's
       directory cannot be located, or the file is not readable.

   class_file
	 # Find a file in our module shared dir, or in our parent class
	 my $dir = class_file('My::Module', 'file/name.txt');

       The "module_file" function takes two params of the module name and file
       name. It locates the module dir, and then finds the file within it,
       verifying that the file actually exists, and that it is readable.

       In order to find the directory, the module must be loaded when calling
       this function.

       The filename should be a relative path in the format of your local
       filesystem. It will simply added to the directory using File::Spec's
       "catfile" method.

       If the file is NOT found for that module, "class_file" will scan up the
       module's @ISA tree, looking for the file in all of the parent classes.

       This allows you to, in effect, "subclass" shared files.

       Returns the file path as a string, or dies if the file or the dist's
       directory cannot be located, or the file is not readable.

SUPPORT
       Bugs should always be submitted via the CPAN bug tracker

       <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-ShareDir>

       For other issues, contact the maintainer.

AUTHOR
       Adam Kennedy <adamk@cpan.org>

SEE ALSO
       File::HomeDir, Module::Install, Module::Install::Share,
       File::ShareDir::PAR

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.

perl v5.18.2			  2011-02-01		     File::ShareDir(3)
[top]

List of man pages available for Alpinelinux

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net