Debian Codegraph @

README

raw
1 NAME
2 File::UserConfig - Get a user's existing config directory, or copy in
3 defaults
4
5 # The most simple Do What I Mean usage.
6 $configdir = File::UserConfig->configdir;
7
8 # Or without taking advantage of convention-based defaults
9 $configdir = File::UserConfig->new(
10 dist => 'My-Application',
11 module => 'My::Application',
12 dirname => '.myapp',
13 sharedir => $defaults_here,
14 )->configdir;
15
16 DESCRIPTION
17 Many modules or applications maintain a user-spec configuration data
18 directory. And the implementation pattern is generally the same.
19
20 A directory like /home/myuser/.application is created and populating by
21 a set of default files the first time an application runs, and from
22 there on, the files in that directory are modified.
23
24 "File::UserConfig" provides standard, light and sub-classable default
25 implementation of this concept that Does The Right Thing with the
26 directory names.
27
28 Applying Perl Conventions
29 "File::UserConfig" applies and automates the following conventions.
30
31 1. We are using the distribution name?
32
33 The use of "File::ShareDir" is based on distribution name (more on that
34 later) so we need to know it.
35
36 The CPAN convention is for a dist to be named "Foo-Bar" after the main
37 module "Foo::Bar" in the distribution, but sometimes this varies, and
38 sometimes you will want to call "File::UserConfig" from other than the
39 main module. But unless you say otherwise, "File::UserConfig" will
40 assume that if you call it from "Module::Name", that is probably the
41 main module, and thus your dist is probably called "Module-Name".
42
43 2. What config directory name is used
44
45 On platforms which keep application-specific data in its own directory,
46 well away from the data the user actually create themself, we just use
47 the dist name.
48
49 On Unix, which has a combined home directory, we remap the dist name to
50 be a lowercase hidden name with all '-' chars as '_'.
51
52 So on unix only, "Module::Name" will become ".module_name". Most of the
53 time, this will end up what you would have used anyway.
54
55 3. Where does the config directory live
56
57 "File::UserConfig" knows where your home directory is by using
58 File::HomeDir. And more specifically, on platforms that support
59 application data being kept in a subdirectory, it will use that as well.
60
61 On Unix, Windows, and Mac OS X, it will just Do The Right Thing.
62
63 4. Where do the defaults come from?
64
65 The ability for a distribution to provide a directory full of default
66 files is provided in Perl by File::ShareDir.
67
68 Of course, we're also assuming you are using Module::Install so you have
69 access to its "install_share" command, and that the only thing your dist
70 is going to install to it will be the default config dir.
71
72 METHODS
73 The 6 accessors all feature implicit constructors.
74
75 In other words, the two following lines are equivalent.
76
77 # Explicitly
78 $configdir = File::UserConfig->new( ... )->configdir;
79
80 # Auto-construction
81 $configdir = File::UserConfig->configdir( ... );
82
83 # Thus, using all default params we can just
84 $configdir = File::UserConfig->configdir;
85
86 new
87 my $config = File::UserConfig->new(
88 dist => 'Not-This-Class',
89 dirname => '.myconfig',
90 sharedir => 'defaultconfig',
91 homedir => $username,
92 );
93
94 The "new" constructor takes a set of optional named params, and finds
95 the user's configuration directory, creating it by copying in a default
96 directory if an existing one cannot be found.
97
98 In almost every case, you will want to use all the defaults and let
99 everything be determined automatically for you. The sample above tries
100 to show some of the limited number of situations in which you might want
101 to consider providing your own values.
102
103 But most times, you don't want to or need to. Try it without params
104 first, and add some params if it isn't working for you.
105
106 If you want to do some custom actions after you copy in the directory,
107 the subclass and add it after you call the parent "new" method.
108
109 Returns a new "File::UserConfig" object, or dies on error.
110
111 dist
112 $name = File::UserConfig->new(...)->dist;
113
114 $name = File::UserConfig->dist(...);
115
116 The "dist" accessor returns the name of the distribution.
117
118 module
119 $name = File::UserConfig->new(...)->module;
120
121 $name = File::UserConfig->module(...);
122
123 The "module" accessor returns the name of the module.
124
125 Although the default dirname is based off the dist name, the module name
126 is the one used to find the shared dir.
127
128 dirname
129 $dir = File::UserConfig->new(...)->dirname;
130
131 $dir = File::UserConfig->dirname(...);
132
133 The "dirname" accessor returns the name to be used for the config
134 directory name, below the homedir. For example '.foo_bar'.
135
136 sharedir
137 $dir = File::UserConfig->new(...)->sharedir;
138
139 $dist = File::UserConfig->sharedir(...);
140
141 The "sharedir" accessor returns the name of the directory where the
142 shared default configuration is held.
143
144 Returns a path string, verified to exist before being returned.
145
146 homedir
147 $dir = File::UserConfig->new(...)->homedir;
148
149 $dist = File::UserConfig->homedir(...);
150
151 The "homedir" accessor returns the location of the home direcotry, that
152 the config dir will be created or found below.
153
154 Returns a path string, verified to exist before being returned.
155
156 configdir
157 $dir = File::UserConfig->new(...)->configdir;
158
159 $dist = File::UserConfig->configdir(...);
160
161 The "sharedir" accessor returns the name of the directory where the
162 shared default configuration is held.
163
164 Returns a path string, verified to exist before being returned.
165
166 SUPPORT
167 Bugs should always be submitted via the CPAN bug tracker
168
169 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=File-UserConfig>
170
171 For other issues, contact the maintainer
172
173 AUTHOR
174 Adam Kennedy <[email protected]>
175
176 SEE ALSO
177 File::HomeDir, File::ShareDir
178
179 COPYRIGHT
180 Copyright 2006 - 2008 Adam Kennedy.
181
182 This program is free software; you can redistribute it and/or modify it
183 under the same terms as Perl itself.
184
185 The full text of the license can be found in the LICENSE file included
186 with this module.
187