Provided by: sympa_6.2.70~dfsg-2_amd64 bug

NAME

       Sympa::List - Mailing list

DESCRIPTION

       Sympa::List represents the mailing list on Sympa.

   Methods
       new( $name, [ $domain [ {options...} ] ] )
           Constructor.  Creates a new object which will be used for a list and eventually loads
           the list if a name is given. Returns a List object.

           Parameters

           FIXME @todo doc

       add_list_admin ( $role, $user, ..., [ replace => 1 ],  [ stash => $arrayref ] )
           Instance method.  Adds new admin user(s) to the list.  If "replace => 1" is specified,
           may overwrite existing entries.  TBD.

       add_list_header ( $message, $field_type )
           FIXME @todo doc

       add_list_member ( $user, ..., [ stash => $arrayref ] )
           Instance method.  Adds new user(s) to the list.  TBD.

       available_reception_mode ( )
           Instance method.  FIXME @todo doc

           Note: Since Sympa 6.1.18, this returns an array under array context.

       delete_list_admin ( $role, \@emails, [ stash => \@stash ] )
           Delete the indicated admin user with the predefined role from the list.  $role may be
           'owner' or 'editor'.

       delete_list_member ( \@emails, [ exclude => 1 ], [ operation => $operation ], [ stash =>
       \@stash ] )
           Delete the indicated users from the list.

           Options:

           \@emails
               The emails to be deleted.

           exclude => 1
               TBD.

           operation => $operation
               Case of deleting: 'auto_del' (bounce management), 'signoff' (manual signoff) or
               'del' (deleted by admin).

           stash => \@stash
               TBD.

       delete_list_member_picture ( $email )
           Deletes a member's picture file.

       destroy_multiton ( ) Instance method. Destroy multiton instance. FIXME
       dump_users ( ROLE )
           Dump user information in user store into file "$role.dump" under list directory. ROLE
           may be 'member', 'owner' or 'editor'.

       find_picture_filenames ( $email )
           Returns the type of a pictures according to the user.

       find_picture_paths ( )
           Instance method.  FIXME @todo doc

       find_picture_url ( $email )
           Find pictures URL

       get_admins ( $role, [ filter => \@filters ] )
           Instance method.  Gets users of the list with one of following roles.

           "actual_editor"
               Editors belonging to the list.  If there are no such users, owners of the list.

           "editor"
               Editors belonging to the list.

           "owner"
               Owners of the list.

           "privileged_owner"
               Owners whose "profile" attribute is "privileged".

           "receptive_editor"
               Editors belonging to the list and whose reception mode is "mail".  If there are no
               such users, owners whose reception mode is "mail".

           "receptive_owner"
               Owners whose reception mode is "mail".

           Optional filter may be:

           [email => $email]
               Limit result to the user with their e-mail $email.

           Returns:

           In array context, returns (possibly empty or single-item) array of users.  In scalar
           context, returns reference to it.  In case of database error, returns empty array or
           undefined value.

       get_admins_email ( $role )
           Instance method.  Gets an array of emails of list admins with role "receptive_editor",
           "actual_editor", "receptive_owner" or "owner".

       get_archive_dir ( )
           Instance method.  FIXME @todo doc

       get_available_msg_topic ( )
           Instance method.  FIXME @todo doc

       get_bounce_address ( WHO, [ OPTS, ... ] )
           Return the VERP address of the list for the user WHO.

           FIXME: VERP addresses have the name of originating robot, not mail host.

       get_bounce_dir ( )
           Instance method.  FIXME @todo doc

       get_cert ( )
           Instance method.  FIXME @todo doc

       get_config_changes ( )
           Instance method.  FIXME @todo doc

       get_cookie ()
           Returns the cookie for a list, if available.

       get_current_admins ( ... )
           Instance method.  FIXME @todo doc

       get_default_user_options ()
           Returns a default option of the list for subscription.

       get_first_list_member ()
           Returns a hash to the first user on the list.

       get_id ( )
           Return the list ID, different from the list address (uses the robot name)

       get_including_lists ( $role )
           Instance method.  List of lists including specified list and hosted by a whole site.

           Parameter:

           $role
               Role of included users.  'member', 'owner' or 'editor'.

           Returns:

           Arrayref of <Sympa::List> instances.  Return "undef" on failure.

       get_list_member ( USER )
           Returns a subscriber of the list.

       get_max_size ()
           Returns the maximum allowed size for a message.

       get_members ( $role, [ offset => $offset ], [ order => $order ], [ limit => $limit ])
           Instance method.  Gets users of the list with one of following roles.

           "member"
               Members of the list, either subscribed or included.

           "unconcealed_member"
               Members whose "visibility" property is not "conceal".

           Optional parameters:

           limit => $limit
           offset => $offset
           order => $order
               TBD.

           Returns:

           In array context, returns (possibly empty or single-item) array of users.  In scalar
           context, returns reference to it.  In case of database error, returns empty array or
           undefined value.

       get_msg_count ( )
           Instance method.  Returns the number of messages sent to the list.  FIXME

       get_first_bouncing_list_member ( )
           Instance method.  Get first bouncing user.  FIXME

       get_next_bouncing_list_member ( )
           Instance method.  Loop for all subsequent bouncing users.  FIXME

       get_next_delivery_date ( )
           Instance method.  Returns the date epoch for next delivery planned for a list.

           Note: As of 6.2a.41, returns "undef" if parameter is not set or invalid.  Previously
           it returned current time.

       get_next_list_member ()
           Returns a hash to the next users, until we reach the end of the list.

       get_param_value ( $param, [ $as_arrayref ] )
           instance method.  Returns the list parameter value.  the parameter is simple (name) or
           composed (name"."minor) the value is a scalar or a ref on an array of scalar (for
           parameter digest : only for days).

       get_picture_path ( )
           Instance method.  FIXME

       get_recipients_per_mode ( )
           Instance method.  FIXME @todo doc

       get_reply_to ()
           Returns an array with the Reply-To values.

       get_resembling_members ( $role, $searchkey )
           instance method.  TBD.

       get_stats ( )
           Returns array of the statistics.

       get_total ( [ 'nocache' ] )
           Returns the number of subscribers to the list.

       get_total_bouncing ( )
           Instance method.  Gets total number of bouncing subscribers.

       has_data_sources ( )
           Instance method.  Checks if a list has data sources.

       has_included_users ( $role )
           Instance method.  FIXME @todo doc

       insert_delete_exclusion ( $email, "insert"|"delete" )
           Instance method.  Update the exclusion table.  FIXME @todo doc

       is_admin ( $role, $user )
           Instance method.  Returns true if $user has $role ("privileged_owner", "owner",
           "actual_editor" or "editor") on the list.

       is_archived ()
           Returns true is the list is configured to keep archives of its messages.

       is_archiving_enabled ( )
           Returns true is the list is configured to keep archives of its messages, i.e.
           process_archive parameter is set to "on".

       is_available_msg_topic ( $topic )
           Instance method.  Checks for a topic if it is available in the list (look for each
           list parameter "msg_topic.name").

       is_available_reception_mode ( $mode )
           Instance method.  Is a reception mode in the parameter reception of the
           available_user_options section?

       is_subscription_allowed ( )
           Instance method.  Is it allowed to add or remove subscribers of the list?  Added on
           Sympa 6.2.67b.1.

       is_digest ( )
           Instance method.  Does the list support digest mode?

       is_included ( )
           Returns true value if the list is included in another list(s).

       is_list_member ( USER )
           Returns true if the indicated user is member of the list.

       is_moderated ()
           Returns true if the list is moderated.  FIXME this may not be useful.

       is_msg_topic_tagging_required ( )
           Instance method.  Checks for the list parameter msg_topic_tagging if it is set to
           'required'.

       is_there_msg_topic ( )
           Instance method.  Tests if some msg_topic are defined.

       is_web_archived ( )
           Instance method.  Is the list web archived?

           FIXME: Broken. Use scenario or is_archiving_enabled().

       load ( )
           Loads the indicated list into the object.

       load_data_sources_list ( $robot )
           Instance method.  Loads all data sources.  FIXME: Used only in wwsympa.fcgi.

       may_edit ( $param, $who, [ options, ... ] )
           Instance method.  May the indicated user edit the indicated list parameter or not?
           FIXME @todo doc

       parse_list_member_bounce ( $user )
           Instance method.  FIXME @todo doc

       restore_suspended_subscription ( $email )
           Instance method.  FIXME @todo doc

       restore_users ( ROLE )
           Import user information into user store from file "$role.dump" under list directory.
           ROLE may be 'member', 'owner' or 'editor'.

       save_config ( LIST )
           Saves the indicated list object to the disk files.

       search_list_among_robots ( $listname )
           Instance method.  FIXME @todo doc

       select_list_members_for_topic ( $topic, \@emails )
           Instance method.  FIXME @todo doc

       send_notify_to_owner ( $operation, $params )
           Instance method.  FIXME @todo doc

       send_probe_to_user ( $type, $who )
           Instance method.  FIXME @todo doc

       set_status_error_config ( $msg, parameters, ... )
           Instance method.  FIXME @todo doc

       suspend_subscription ( $email, $list, $data, $robot )
           Function.  FIXME This should be a instance method.  FIXME @todo doc

       sync_include ( $role, options... )
           Instance method.  FIXME would be obsoleted.  FIXME @todo doc

       update_config_changes ( )
           Instance method.  FIXME @todo doc

       update_list_admin ( USER, ROLE, HASHPTR )
           Sets the new values given in the hash for the admin user.

       update_list_member ( $email, key => value, ... )
           Instance method.  Sets the new values given in the pairs for the user.

       update_stats ( count, [ sent, bytes, sent_by_bytes ] )
           Updates the stats, argument is number of bytes, returns list fo the updated values.
           Returns zeroes if failed.

   Functions
       get_lists ( [ $that, [ options, ... ] ] )
           Function.  List of lists hosted by a family, a robot or whole site.

           $that
               Robot, Sympa::Family object or site (default).

           options, ...
               Hash including options passed to Sympa::List->new() (see load()) and any of
               following pairs:

               "'filter' => [ KEYS => VALS, ... ]"
                   Filter with list profiles.  When any of items specified by KEYS (separated by
                   "|") have any of values specified by VALS, condition by that pair is
                   satisfied.  KEYS prefixed by "!" mean negated condition.  Only lists
                   satisfying all conditions of query are returned.  Currently available keys and
                   values are:

                   'creation' => TIME
                   'creation<' => TIME
                   'creation>' => TIME
                       Creation date is equal to, earlier than or later than the date (UNIX
                       time).

                   'member' => EMAIL
                   'owner' => EMAIL
                   'editor' => EMAIL
                       Specified user is a subscriber, owner or editor of the list.

                   'name' => STRING
                   'name%' => STRING
                   '%name%' => STRING
                       Exact, prefixed or substring match against list name, case-insensitive.

                   'status' => "STATUS|..."
                       Status of list.  One of 'open', 'closed', 'pending', 'error_config' and
                       'family_closed'.

                   'subject' => STRING
                   'subject%' => STRING
                   '%subject%' => STRING
                       Exact, prefixed or substring match against list subject, case-insensitive
                       (case folding is Unicode-aware).

                   'topics' => "TOPIC|..."
                       Exact match against any of list topics.  'others' or 'topicsless' means no
                       topics.

                   'update' => TIME
                   'update<' => TIME
                   'update>' => TIME
                       Date of last update is equal to, earlier than or later than the date (UNIX
                       time).

               "'limit' => NUMBER "
                   Limit the number of results.  0 means no limit (default).  Note that this
                   option may be applied prior to 'order' option.

               "'order' => [ KEY, ... ]"
                   Subordinate sort key(s).  The results are sorted primarily by robot names then
                   by other key(s).  Keys prefixed by "-" mean descendent ordering.  Available
                   keys are:

                   'creation'
                       Creation date.

                   'name'
                       List name, case-insensitive.  It is the default.

                   'total'
                       Estimated number of subscribers.

                   'update'
                       Date of last update.

           Returns a ref to an array of List objects.

       get_robots ( )
           Function.  List of robots hosted by Sympa.

       get_which ( EMAIL, ROBOT, ROLE )
           Function.  Get a list of lists where EMAIL assumes this ROLE (owner, editor or member)
           of function to any list in ROBOT.

   Obsoleted methods
       add_admin_user ( USER, ROLE, HASHPTR )
           DEPRECATED.  Use add_list_admin().

       am_i ( ROLE, USER )
           DEPRECATED. Use is_admin().

       archive_exist ( FILE )
           DEPRECATED.  Returns true if the indicated file exists.

       archive_ls ()
           DEPRECATED.  Returns the list of available files, if any.

       archive_msg ( MSG )
           DEPRECATED.  Archives the Mail::Internet message given as argument.

       archive_send ( WHO, FILE )
           DEPRECATED.  Send the indicated archive file to the user, if it exists.

       get_db_field_type ( ... )
           Instance method.  Obsoleted.

       get_first_list_admin ( ROLE )
           OBSOLETED.  Use get_admins().

       get_global_user ( USER )
           DEPRECATED.  Returns a hash with the information regarding the indicated user.

       get_latest_distribution_date ( )
           Instance method.  Gets last date of distribution message .

       get_list_address ( [ TYPE ] )
           OBSOLETED.  Use "get_address" in Sympa.

           Return the list email address of type TYPE: posting address (default), "owner",
           "editor" or (non-VERP) "return_path".

       get_list_admin ( ROLE, USER)
           Return an admin user of the list with predefined role

           OBSOLETED.  Use get_admins().

       get_list_id ( )
           OBSOLETED.  Use get_id().

       get_next_list_admin ()
           OBSOLETED.  Use get_admins().

       get_state ( FLAG )
           Deprecated.  Returns the value for a flag : sig or sub.

       is_member_excluded ( $email )
           Instance method.  Deprecated.

       may_do ( ACTION, USER )
           Note: This method was obsoleted.

           Chcks is USER may do the ACTION for the list. ACTION can be one of following : send,
           review, index, getm add, del, reconfirm, purge.

       move_message ( $file, $queue )
           DEPRECATED.  No longer used.

       print_info ( FDNAME )
           DEPRECATED.  Print the list information to the given file descriptor, or the currently
           selected descriptor.

       savestats ()
           Deprecated on 6.2.23b.

           Saves updates the statistics file on disk.

       send_confirm_to_editor ( $message, $method )
           This method was DEPRECATED.

           Send a Sympa::Message object to the editor (for approval).

           Sends a message to the list editor to ask them for moderation (in moderation context :
           editor or editorkey). The message to moderate is set in moderation spool with name
           containing a key (reference send to editor for moderation).  In context of msg_topic
           defined the editor must tag it for the moderation (on Web interface).

           Parameters:

           $message
               Sympa::Message instance - the message to moderate.

           $method
               'md5' - for "editorkey", 'smtp' - for "editor".

           Returns:

           The moderation key for naming message waiting for moderation in moderation spool, or
           "undef".

       send_confirm_to_sender ( $message )
           This method was DEPRECATED.

           Sends an authentication request for a sent message to distribute.  The message for
           distribution is copied in the auth spool in order to wait for confirmation by its
           sender.  This message is named with a key.  In context of msg_topic defined, the
           sender must tag it for the confirmation

           Parameter:

           $message
               Sympa::Message instance.

           Returns:

           The key for naming message waiting for confirmation (or tagging) in auth spool, or
           "undef".

   Attributes
       FIXME @todo doc

SEE ALSO

       Sympa.

HISTORY

       List module was renamed to Sympa::List module on Sympa 6.2.