=encoding utf8

=head1 NAME

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

=head1 INHERITANCE

 User::Identity::Archive::Plain
   is a User::Identity::Archive
   is a User::Identity::Item

=head1 SYNOPSIS

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

=head1 DESCRIPTION

This archiver, which extends L<User::Identity::Archive|User::Identity::Archive>, uses a very
simple plain text file to store the information of users.  The syntax
is described in the DETAILS section, below.

Extends L<"DESCRIPTION" in User::Identity::Archive|User::Identity::Archive/"DESCRIPTION">.
 
=head1 OVERLOADED

Extends L<"OVERLOADED" in User::Identity::Archive|User::Identity::Archive/"OVERLOADED">.
 
=head1 METHODS

Extends L<"METHODS" in User::Identity::Archive|User::Identity::Archive/"METHODS">.
 
=head2 Constructors

Extends L<"Constructors" in User::Identity::Archive|User::Identity::Archive/"Constructors">.
 
=over 4

=item User::Identity::Archive::Plain-E<gt>B<new>( [$name], %options )

 -Option       --Defined in             --Default
  abbreviations                           []
  description    User::Identity::Item     undef
  from           User::Identity::Archive  undef
  name           User::Identity::Item     <required>
  only                                    []
  parent         User::Identity::Item     undef
  tabstop                                 8

=over 2

=item abbreviations => HASH|ARRAY

Adds a set of abbreviations for collections to the syntax of the
plain text archiver.  See section L</Simplified class names> for
a list of predefined names.

=item description => STRING

=item from => FILEHANDLE|FILENAME

=item name => STRING

=item only => ARRAY|ABBREV

Lists the only information (as (list of) abbreviations) which should be
read.  Other information is removed before even checking whether it is
a valid abbreviation or not.

=item parent => OBJECT

=item tabstop => INTEGER

Sets the default tab-stop width.

=back

=back

=head2 Attributes

Extends L<"Attributes" in User::Identity::Archive|User::Identity::Archive/"Attributes">.
 
=over 4

=item $obj-E<gt>B<abbreviation>( $name, [$class] )

Returns the class which is capable of storing information which is
grouped as $name.  With $class argument, you add (or overrule) the
definitions of an abbreviation.  The $class is automatically loaded.

If $class is C<undef>, then the abbreviation is deleted.  The class
name which is deleted is returned.

=item $obj-E<gt>B<abbreviations>()

Returns a sorted list of all names which are known as abbreviations.

=item $obj-E<gt>B<defaultTabStop>( [$integer] )

Returns the width of a tab, optionally after setting it.  This must be
the same as set in your editor.

=item $obj-E<gt>B<description>()

Inherited, see L<User::Identity::Item/"Attributes">

=item $obj-E<gt>B<name>( [$newname] )

Inherited, see L<User::Identity::Item/"Attributes">

=back

=head2 Collections

Extends L<"Collections" in User::Identity::Archive|User::Identity::Archive/"Collections">.
 
=over 4

=item $obj-E<gt>B<add>($collection, $role)

Inherited, see L<User::Identity::Item/"Collections">

=item $obj-E<gt>B<addCollection>( $object | <[$type], %options> )

Inherited, see L<User::Identity::Item/"Collections">

=item $obj-E<gt>B<collection>($name)

Inherited, see L<User::Identity::Item/"Collections">

=item $obj-E<gt>B<parent>( [$parent] )

Inherited, see L<User::Identity::Item/"Collections">

=item $obj-E<gt>B<removeCollection>($object|$name)

Inherited, see L<User::Identity::Item/"Collections">

=item $obj-E<gt>B<type>()

=item User::Identity::Archive::Plain-E<gt>B<type>()

Inherited, see L<User::Identity::Item/"Collections">

=item $obj-E<gt>B<user>()

Inherited, see L<User::Identity::Item/"Collections">

=back

=head2 Searching

Extends L<"Searching" in User::Identity::Archive|User::Identity::Archive/"Searching">.
 
=over 4

=item $obj-E<gt>B<find>($collection, $role)

Inherited, see L<User::Identity::Item/"Searching">

=back

=head2 Access to the archive

Extends L<"Access to the archive" in User::Identity::Archive|User::Identity::Archive/"Access to the archive">.
 
=over 4

=item $obj-E<gt>B<from>( <$fh|$filename|ARRAY>, %options )

Read the plain text information from the specified $fh, $filename,
STRING, or ARRAY of lines.

 -Option --Default
  tabstop  <default from object>
  verbose  0

=over 2

=item tabstop => INTEGER

=item verbose => INTEGER

=back

=back

=head1 DETAILS

=head2 The Plain Archiver Format

=head3 Simplified class names

It is too much work to specify full class named on each spot where you
want to create a new object with data.  Therefore, abbreviations are
introduced.  Use L<new(abbreviations)|User::Identity::Archive::Plain/"METHODS"> or L<abbreviations()|User::Identity::Archive::Plain/"Attributes"> to add extra
abbreviations or to overrule some predefined.

Predefined names:
  user         User::Identity
  email        Mail::Identity
  location     User::Identity::Location
  system       User::Identity::System
  list         User::Identity::Collection::Emails

It would have been nicer to refer to a I<person> in stead of a I<user>,
however that would add to the confusion with the name-space.

=head3 Indentation says all

The syntax is as simple as possible. An extra indentation on a line
means that the variable or class is a collection within the class on
the line before.

 user markov
   location home
      country NL
   email home
      address  mark@overmeer.net
      location home
   email work
      address  solutions@overmeer.bet

 email tux
    address tux@fish.net

The above defines two items: one L<User::Identity|User::Identity> named C<markov>, and
an e-mail address C<tux>.  The user has two collections: one contains
a single location, and one stores two e-mail addresses.

To add to the confusion: the C<location> is defined as field in C<email>
and as collection.  The difference is easily detected: if there are
indented fields following the line it is a collection.  Mistakes will
in most cases result in an error message.

=head3 Long lines

If you want to continue on the next line, because your content is too
large, then add a backslash to the end, like this:

 email home
    description This is my home address,     \
                But I sometimes use this for \
                work as well
    address tux@fish.aq

Continuations do not play the game of indentation, so what you also
can do is:

 email home
    description               \
 This is my home address,     \
 But I sometimes use this for \
 work as well
    address tux@fish.aq

The fields C<comment> and C<address> must be correctly indented.
The line terminations are lost, which is useful for most fields.  However,
if you need them, you have to check the description of the applicable field.

=head3 Comments

You may add comments and white spaces.  Comments start with a C<'#'> as
first non-blank character on the line.  Comments are B<not allowed> on
the same line as real data, as some languages (like Perl) permit.

You can insert comments and blank lines on all places where you need
them:

 user markov

    # my home address
    email home

       # useless comment statement
       address tux@fish.aq
       location #mind_the_hash

is equivalent to:

 user markov
    email home
       address tux@fish.aq
       location #mind_the_hash

=head3 References

Often you will have the need to add the same information to two items,
for instance, multiple people share the same address.  In this case,
you can create a reference.  However, this is only permitted for
whole items: you can refer to someone's location, but not to the person's
street.

To create a reference to an item of someone else, use

 user markov
    location home = user(cleo).location(home)
    location work
       organization   MARKOV Solutions

=head3 Configuration parameters

You can add some configuration lines as well.  On the moment, the only
one defined is

 tabstop = 4

which can be used to change the meaning of tabs in the file.  The default
setting is 8, but some people prefer 4 (or other values).

=head1 DIAGNOSTICS

=over 4

=item Error: $object is not a collection.

The first argument is an object, but not of a class which extends
L<User::Identity::Collection|User::Identity::Collection>.

=item Error: Cannot load collection module for $type ($class).

Either the specified $type does not exist, or that module named $class returns
compilation errors.  If the type as specified in the warning is not
the name of a package, you specified a nickname which was not defined.
Maybe you forgot the 'require' the package which defines the nickname.

=item Warning: Cannot read archive from $source

=item Error: Creation of a collection via $class failed.

The $class did compile, but it was not possible to create an object
of that class using the options you specified.

=item Error: Don't know what type of collection you want to add.

If you add a collection, it must either by a collection object or a
list of options which can be used to create a collection object.  In
the latter case, the type of collection must be specified.

=item Warning: No collection $name

The collection with $name does not exist and can not be created.

=back

=head1 SEE ALSO

This module is part of User-Identity distribution version 1.02,
built on April 17, 2023. Website: F<http://perl.overmeer.net/CPAN/>

=head1 LICENSE

Copyrights 2003-2023 by [Mark Overmeer <markov@cpan.org>]. For other contributors see ChangeLog.

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See F<http://dev.perl.org/licenses/>