NAME

       Sympa::Archive - Archives of Sympa

SYNOPSIS

         use Sympa::Archive;
         $archive = Sympa::Archive->new(context => $list);

         @arcs = $archive->get_archives;

         $archive->store($message);
         $archive->html_store($message);

         $archive->select_archive('2015-04');
         ($message, $handle) = $archive->next;

         $archive->select_archive('2015-04');
         ($message, $handle) = $archive->fetch(message_id => $message_id);
         $archive->html_remove($message_id);
         $archive->remove($handle);

         $archive->html_rebuild('2015-04');

DESCRIPTION

       Sympa::Archive implements the interface to handle archives.

   Methods and functions
       new ( context => $list, [ create => 1 ] )
           Constructor.  Creates new instance of Sympa::Archive.

           Parameter:

           context => $list
               Context of object, a Sympa::List instance.

           create => 1
               If  necessary,  creates  directory structure of archive.  Dies if creation fails.  This parameter
               was introduced on Sympa 6.2.47b.

       add_archive ( $arc )
           Instance method.  Adds archive directory named $arc.  Currently, archive directory must have the form
           "YYYY-MM".

       purge_archive ( $arc )
           Instance method.  Removes archive directory and its content entirely.  removed  content  can  not  be
           recovered.

       select_archive ( $arc, [ info => 1 ] )
           Instance method.  Selects an archive directory.  It will be referred by consequent operations.

       fetch ( message_id => $message_id )
           Instance method.  Gets a message from archive.  select_archive() must be called in advance.

           Message will be locked to prevent multiple processing of a single message.

           Parameter:

           message_id => $message_id
               Message ID of the message to be fetched.

           Returns:

           Two-elements list of Sympa::Message instance and filehandle locking a message.

       html_fetch ( file => $filename )
           Instance  method.   Gets a metadata of formatted message from HTML archive.  select_archive() must be
           called in advance.

           Parameter:

           file => $filename
               File name of the message to be fetched.

           Returns:

           Hashref.  Note that message won't be locked.

       get_size ( )
           Instance method.  Gets total size of messages in archives.   This  method  was  introduced  on  Sympa
           6.2.17.

       next ( [ reverse => 1 ] )
           Instance method.  Gets next message in archive.  select_archive() must be called in advance.

           Message will be locked to prevent multiple processing of a single message.

           Parameters:

           None.

           Returns:

           Two-elements list of Sympa::Message instance and filehandle locking a message.

       html_next ( [ reverse => 1 ] )
           Instance  method.   Gets  next  metadata  of  formatted message in archive.  select_archive() must be
           called in advance.

           Parameters:

           None.

           Returns:

           Hashref.  Note that message will not be locked.

       remove ( $handle )
           Instance method.  Removes a message from archive.

           Parameter:

           $handle
               Filehandle, Sympa::LockedFile  instance,  locking  message.   It  is  returned  by  "fetch"()  or
               "next"().

           Returns:

           True value if message could be removed.  Otherwise false value.

       html_remove ( $message_id )
           Instance method.  TBD.

       store ( $message )
           Instance method.  Stores the message into archive.

           Parameters:

           $message
               A Sympa::Message instance to be stored.  Following attributes and metadata are referred:

               {date}
                   Unix time when the message would be delivered.

           Returns:

           If storing succeeded, marshalled metadata (file name) of the message.  Otherwise "undef".

       html_store ( $message )
           Instance method.  TBD.

       get_archives ( )
           Instance  method.  Gets a list of archive directories this archive contains.  Items of returned value
           may be fed to select_archive() and so on.

       html_rebuild ( $arc )
           Instance method.  Rebuilds archives for the list the name of which is given in the argument $arc.

           Parameters:

           $arc
               A character string containing the name of archive directory in the list which we want to rebuild.

           Returns:

           undef if something goes wrong.

       html_format ( $message, destination_dir => $destination_dir, attachment_url => $attachment_url )
           Function.  Converts a message to HTML.

           Parameters:

           $message
               Message to be formatted.  Sympa::Message instance.

           $destination_dir
               The directory result is stored in.

           $attachment_url
               Base URL used to link attachments.

               Note: On 6.2.13 and earlier, this option was named ""attachement_url"".

               Note: On 6.2.17 and later, this option may take an arrayref value.  In such case  items  will  be
               percent-encoded and conjuncted.  Otherwise if a string is given, it will not be encoded.

       get_id ( )
           Instance method.  Gets unique identifier of instance.

SEE ALSO

       archived(8), mhonarc(1), wwsympa(8), Sympa::Message.

HISTORY

       Archive was renamed to Sympa::Archive on Sympa 6.2.

6.2.70                                             2023-01-26                             Sympa::Archive(3Sympa)