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 an User::Identity::Archive
11          is an 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 sim‐
21       ple plain text file to store the information of users.  The syntax is
22       described in the DETAILS section, below.
23

OVERLOADED

METHODS

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

DIAGNOSTICS

144       Error: $object is not a collection.
145
146       The first argument is an object, but not of a class which extends
147       User::Identity::Collection.
148
149       Error: Cannot load collection module for $type ($class).
150
151       Either the specified $type does not exist, or that module named $class
152       returns compilation errors.  If the type as specified in the warning is
153       not the name of a package, you specified a nickname which was not
154       defined.  Maybe you forgot the 'require' the package which defines the
155       nickname.
156
157       Warning: Cannot read archive from $source
158
159       Error: Creation of a collection via $class failed.
160
161       The $class did compile, but it was not possible to create an object of
162       that class using the options you specified.
163
164       Error: Don't know what type of collection you want to add.
165
166       If you add a collection, it must either by a collection object or a
167       list of options which can be used to create a collection object.  In
168       the latter case, the type of collection must be specified.
169
170       Warning: No collection $name
171
172       The collection with $name does not exist and can not be created.
173

DETAILS

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

LICENSE

302       Copyrights 2003,2004,2007 by Mark Overmeer <perl@overmeer.net>.For
303       other contributors see Changes.
304
305       This program is free software; you can redistribute it and/or modify it
306       under the same terms as Perl itself.  See
307       http://www.perl.com/perl/misc/Artistic.html
308
309
310
311perl v5.8.8                       2007-01-08 User::Identity::Archive::Plain(3)