User::Identity::Archive::Plain(3pm)

1User::Identity::ArchiveU:s:ePrlaCionn(t3r)ibuted Perl DoUcsuemre:n:tIadteinotnity::Archive::Plain(3)
2
3
4

NAME

6       User::Identity::Archive::Plain - simple, plain text archiver
7

INHERITANCE

9        User::Identity::Archive::Plain
10          is a User::Identity::Archive
11          is a User::Identity::Item
12

SYNOPSIS

14        use User::Identity::Archive::Plain;
15        my $friends = User::Identity::Archive::Plain->new('friends');
16        $friends->from(\*FH);
17        $friends->from('.friends');
18

DESCRIPTION

20       This archiver, which extends User::Identity::Archive, uses a very
21       simple plain text file to store the information of users.  The syntax
22       is described in the DETAILS section, below.
23

OVERLOADED

METHODS

26   Constructors
27       User::Identity::Archive::Plain->new([NAME], OPTIONS)
28
29        Option       --Defined in     --Default
30        abbreviations                   []
31        description    User::Identity::Item  undef
32        from           User::Identity::Archive  undef
33        name           User::Identity::Item  <required>
34        only                            []
35        parent         User::Identity::Item  undef
36        tabstop                         8
37
38           . abbreviations => HASH|ARRAY
39
40               Adds a set of abbreviations for collections to the syntax of
41               the plain text archiver.  See section "Simplified class names"
42               for a list of predefined names.
43
44           . description => STRING
45
46           . from => FILEHANDLE|FILENAME
47
48           . name => STRING
49
50           . only => ARRAY|ABBREV
51
52               Lists the only information (as (list of) abbreviations) which
53               should be read.  Other information is removed before even
54               checking whether it is a valid abbreviation or not.
55
56           . parent => OBJECT
57
58           . tabstop => INTEGER
59
60               Sets the default tab-stop width.
61
62   Attributes
63       $obj->abbreviation(NAME, [CLASS])
64
65           Returns the class which is capable of storing information which is
66           grouped as NAME.  With CLASS argument, you add (or overrule) the
67           definitions of an abbreviation.  The CLASS is automatically loaded.
68
69           If CLASS is "undef", then the abbreviation is deleted.  The class
70           name which is deleted is returned.
71
72       $obj->abbreviations
73
74           Returns a sorted list of all names which are known as
75           abbreviations.
76
77       $obj->defaultTabStop([INTEGER])
78
79           Returns the width of a tab, optionally after setting it.  This must
80           be the same as set in your editor.
81
82       $obj->description
83
84           See "Attributes" in User::Identity::Item
85
86       $obj->name([NEWNAME])
87
88           See "Attributes" in User::Identity::Item
89
90   Collections
91       $obj->add(COLLECTION, ROLE)
92
93           See "Collections" in User::Identity::Item
94
95       $obj->addCollection(OBJECT | ([TYPE], OPTIONS))
96
97           See "Collections" in User::Identity::Item
98
99       $obj->collection(NAME)
100
101           See "Collections" in User::Identity::Item
102
103       $obj->find(COLLECTION, ROLE)
104
105           See "Collections" in User::Identity::Item
106
107       $obj->parent([PARENT])
108
109           See "Collections" in User::Identity::Item
110
111       $obj->removeCollection(OBJECT|NAME)
112
113           See "Collections" in User::Identity::Item
114
115       $obj->type
116
117       User::Identity::Archive::Plain->type
118
119           See "Collections" in User::Identity::Item
120
121       $obj->user
122
123           See "Collections" in User::Identity::Item
124
125   Access to the archive
126       $obj->from(FILEHANDLE|FILENAME|ARRAY, OPTIONS)
127
128           Read the plain text information from the specified FILEHANDLE,
129           FILENAME, STRING, or ARRAY of lines.
130
131            Option --Default
132            tabstop  <default from object>
133            verbose  0
134
135           . tabstop => INTEGER
136
137           . verbose => INTEGER
138

DETAILS

140   The Plain Archiver Format
141       Simplified class names
142
143       It is too much work to specify full class named on each spot where you
144       want to create a new object with data.  Therefore, abbreviations are
145       introduced.  Use new(abbreviations) or abbreviations() to add extra
146       abbreviations or to overrule some predefined.
147
148       Predefined names:
149         user         User::Identity
150         email        Mail::Identity
151         location     User::Identity::Location
152         system       User::Identity::System
153         list         User::Identity::Collection::Emails
154
155       It would have been nicer to refer to a person in stead of a user,
156       however that would add to the confusion with the name-space.
157
158       Indentation says all
159
160       The syntax is as simple as possible. An extra indentation on a line
161       means that the variable or class is a collection within the class on
162       the line before.
163
164        user markov
165          location home
166             country NL
167          email home
168             address  mark@overmeer.net
169             location home
170          email work
171             address  solutions@overmeer.bet
172
173        email tux
174           address tux@fish.net
175
176       The above defines two items: one User::Identity named "markov", and an
177       e-mail address "tux".  The user has two collections: one contains a
178       single location, and one stores two e-mail addresses.
179
180       To add to the confusion: the "location" is defined as field in "email"
181       and as collection.  The difference is easily detected: if there are
182       indented fields following the line it is a collection.  Mistakes will
183       in most cases result in an error message.
184
185       Long lines
186
187       If you want to continue on the next line, because your content is too
188       large, then add a backslash to the end, like this:
189
190        email home
191           description This is my home address,     \
192                       But I sometimes use this for \
193                       work as well
194           address tux@fish.aq
195
196       Continuations do not play the game of indentation, so what you also can
197       do is:
198
199        email home
200           description               \
201        This is my home address,     \
202        But I sometimes use this for \
203        work as well
204           address tux@fish.aq
205
206       The fields "comment" and "address" must be correctly indented.  The
207       line terminations are lost, which is useful for most fields.  However,
208       if you need them, you have to check the description of the applicable
209       field.
210
211       Comments
212
213       You may add comments and white spaces.  Comments start with a '#' as
214       first non-blank character on the line.  Comments are not allowed on the
215       same line as real data, as some languages (like Perl) permit.
216
217       You can insert comments and blank lines on all places where you need
218       them:
219
220        user markov
221
222           # my home address
223           email home
224
225              # useless comment statement
226              address tux@fish.aq
227              location #mind_the_hash
228
229       is equivalent to:
230
231        user markov
232           email home
233              address tux@fish.aq
234              location #mind_the_hash
235
236       References
237
238       Often you will have the need to add the same information to two items,
239       for instance, multiple people share the same address.  In this case,
240       you can create a reference.  However, this is only permitted for whole
241       items: you can refer to someone's location, but not to the person's
242       street.
243
244       To create a reference to an item of someone else, use
245
246        user markov
247           location home = user(cleo).location(home)
248           location work
249              organization   MARKOV Solutions
250
251       Configuration parameters
252
253       You can add some configuration lines as well.  On the moment, the only
254       one defined is
255
256        tabstop = 4
257
258       which can be used to change the meaning of tabs in the file.  The
259       default setting is 8, but some people prefer 4 (or other values).
260

DIAGNOSTICS

262       Error: $object is not a collection.
263
264           The first argument is an object, but not of a class which extends
265           User::Identity::Collection.
266
267       Error: Cannot load collection module for $type ($class).
268
269           Either the specified $type does not exist, or that module named
270           $class returns compilation errors.  If the type as specified in the
271           warning is not the name of a package, you specified a nickname
272           which was not defined.  Maybe you forgot the 'require' the package
273           which defines the nickname.
274
275       Warning: Cannot read archive from $source
276
277       Error: Creation of a collection via $class failed.
278
279           The $class did compile, but it was not possible to create an object
280           of that class using the options you specified.
281
282       Error: Don't know what type of collection you want to add.
283
284           If you add a collection, it must either by a collection object or a
285           list of options which can be used to create a collection object.
286           In the latter case, the type of collection must be specified.
287
288       Warning: No collection $name
289
290           The collection with $name does not exist and can not be created.
291

LICENSE

297       Copyrights 2003,2004,2007-2009 by Mark Overmeer <perl@overmeer.net>.
298       For other contributors see Changes.
299
300       This program is free software; you can redistribute it and/or modify it
301       under the same terms as Perl itself.  See
302       http://www.perl.com/perl/misc/Artistic.html
303
304
305
306perl v5.12.1                      2009-12-24 User::Identity::Archive::Plain(3)