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
21       simple plain text file to store the information of users.  The syntax
22       is described in the DETAILS section, below.
23
24       Extends "DESCRIPTION" in User::Identity::Archive.
25

OVERLOADED

27       Extends "OVERLOADED" in User::Identity::Archive.
28

METHODS

30       Extends "METHODS" in User::Identity::Archive.
31
32   Constructors
33       Extends "Constructors" in User::Identity::Archive.
34
35       User::Identity::Archive::Plain->new( [$name], %options )
36            -Option       --Defined in             --Default
37             abbreviations                           []
38             description    User::Identity::Item     undef
39             from           User::Identity::Archive  undef
40             name           User::Identity::Item     <required>
41             only                                    []
42             parent         User::Identity::Item     undef
43             tabstop                                 8
44
45           abbreviations => HASH|ARRAY
46             Adds a set of abbreviations for collections to the syntax of the
47             plain text archiver.  See section "Simplified class names" for a
48             list of predefined names.
49
50           description => STRING
51           from => FILEHANDLE|FILENAME
52           name => STRING
53           only => ARRAY|ABBREV
54             Lists the only information (as (list of) abbreviations) which
55             should be read.  Other information is removed before even
56             checking whether it is a valid abbreviation or not.
57
58           parent => OBJECT
59           tabstop => INTEGER
60             Sets the default tab-stop width.
61
62   Attributes
63       Extends "Attributes" in User::Identity::Archive.
64
65       $obj->abbreviation( $name, [$class] )
66           Returns the class which is capable of storing information which is
67           grouped as $name.  With $class argument, you add (or overrule) the
68           definitions of an abbreviation.  The $class is automatically
69           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           Returns a sorted list of all names which are known as
76           abbreviations.
77
78       $obj->defaultTabStop( [$integer] )
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           Inherited, see "Attributes" in User::Identity::Item
84
85       $obj->name( [$newname] )
86           Inherited, see "Attributes" in User::Identity::Item
87
88   Collections
89       Extends "Collections" in User::Identity::Archive.
90
91       $obj->add($collection, $role)
92           Inherited, see "Collections" in User::Identity::Item
93
94       $obj->addCollection( $object | <[$type], %options> )
95           Inherited, see "Collections" in User::Identity::Item
96
97       $obj->collection($name)
98           Inherited, see "Collections" in User::Identity::Item
99
100       $obj->parent( [$parent] )
101           Inherited, see "Collections" in User::Identity::Item
102
103       $obj->removeCollection($object|$name)
104           Inherited, see "Collections" in User::Identity::Item
105
106       $obj->type()
107       User::Identity::Archive::Plain->type()
108           Inherited, see "Collections" in User::Identity::Item
109
110       $obj->user()
111           Inherited, see "Collections" in User::Identity::Item
112
113   Searching
114       Extends "Searching" in User::Identity::Archive.
115
116       $obj->find($collection, $role)
117           Inherited, see "Searching" in User::Identity::Item
118
119   Access to the archive
120       Extends "Access to the archive" in User::Identity::Archive.
121
122       $obj->from( <$fh|$filename|ARRAY>, %options )
123           Read the plain text information from the specified $fh, $filename,
124           STRING, or ARRAY of lines.
125
126            -Option --Default
127             tabstop  <default from object>
128             verbose  0
129
130           tabstop => INTEGER
131           verbose => INTEGER
132

DETAILS

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

DIAGNOSTICS

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

SEE ALSO

281       This module is part of User-Identity distribution version 1.00, built
282       on October 14, 2020. Website: http://perl.overmeer.net/CPAN/
283

LICENSE

285       Copyrights 2003-2020 by [Mark Overmeer <markov@cpan.org>]. For other
286       contributors see ChangeLog.
287
288       This program is free software; you can redistribute it and/or modify it
289       under the same terms as Perl itself.  See http://dev.perl.org/licenses/
290
291
292
293perl v5.32.1                      2021-01-27 User::Identity::Archive::Plain(3)
Impressum