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.