This module is the base class for spool subclasses of Sympa.
Publicmethods
new ( [ options... ] )
Constructor. Creates new instance of the class.
marshal ( $message, [ keep_keys => 1 ] )
Instancemethod. Gets marshalled key (file name) of the message.
Parameters:
$message
Message to be marshalled.
keep_keys => 1
See marshal_metadata().
next ( [ no_filter => 1 ], [ no_lock => 1 ] )
Instancemethod. Gets next message to process, order is controlled by name of spool file and so on.
Message will be locked to prevent multiple processing of a single message.
Parameters:
no_filter => 1
Won't skip messages when filter defined by _filter() returns false.
no_lock => 1
Won't lock messages.
Returns:
Two-elements list of message instance and filehandle locking a message. If parsing message fails,
list of "undef" and filehandle. If no more message found, empty array.
If "no_lock" is set, true scalar value will be returned in place of filehandle.
quarantine ( $handle )
Instancemethod. Quarantines a message. On filesystem spool, message will be moved into
"{bad_directory}" of the spool using rename().
Parameter:
$handle
Filehandle, Sympa::LockedFile instance, locking message.
Returns:
True value if message could be quarantined. Otherwise false value.
If $handle was not a filehandle, this method will die.
remove ( $handle )
Instancemethod. Removes a message.
Parameter:
$handle
Filehandle, Sympa::LockedFile instance, locking message.
Returns:
True value if message could be removed. Otherwise false value.
If $handle was not a filehandle, this method will die.
size ( )
Instancemethod. Gets the number of messages the spool contains.
Parameters:
None.
Returns:
Number of messages.
Note: This method returns the number of messages _load() returns, not applying _filter().
store ( $message, [ original => $original ] )
Instancemethod. Stores the message into spool.
Parameters:
$message
Message to be stored.
original => $original
If true value is specified and $message was decrypted, Stores original encrypted form.
Returns:
If storing succeeded, marshalled metadata (file name) of the message. Otherwise "undef".
unmarshal ( $marshalled )
Instancemethod. Gets metadata from marshalled key (file name).
Parameters:
$marshalled
Marshalled key.
Returns:
Hashref containing metadata.
Properties
Instance of Sympa::Spool may have following properties.
Directories
Directories _directories() method returns: "{directory}", "{bad_directory}" and so on.
Lowlevelfunctions
build_glob_pattern ( $marshal_format, $marshal_keys, [ key => value, ... ] )
Function. Builds a glob pattern from parameters and returns it. If built pattern is empty or
contains only punctuations, i.e. "[^0-9A-Za-z\x80-\xFF]", will return "undef".
split_listname ( $robot, $localpart )
Function. Split local part of e-mail to list name and type. Returns an array "(name, type)". Note
that the list with returned name may or may not exist.
If local part looks like listmaster or sympa address, name is "undef" and type is either 'listmaster'
or 'sympa'. Otherwise, type is either 'editor', 'owner', 'return_path', 'subscribe', 'unsubscribe',
'UNKNOWN' or "undef".
Note: For "-request" and "-owner" suffix, this function returns "owner" and "return_path" types,
respectively.
store_spool ( $spool_dir, $message, $marshal_format, $marshal_keys, [ key => value, ... ] )
Function. Store $message into directory $spool_dir as a file with name as marshalled metadata using
$marshal_format and $marshal_keys.
unmarshal_metadata ( $spool_dir, $marshalled, $marshal_regexp, $marshal_keys )
Function. Unmarshals metadata. Returns hashref with keys in arrayref $marshal_keys and values with
substrings captured by regexp $marshal_regexp. If $marshalled did not match against $marshal_regexp,
returns "undef".
The keys "localpart" and "domainpart" are special. Following keys are derived from them: "context",
"listname", "listtype", "priority".
marshal_metadata ( $message, $marshal_format, $marshal_keys, [ keep_keys => 1 ] )
Function. Marshals metadata. Returns formatted string by sprintf() using $marshal_format and
metadatas indexed by keys in arrayref $marshal_keys.
If key is uppercase, it means auto-generated value: 'AUTHKEY', 'KEYAUTH', 'PID', 'RAND', 'TIME'.
Otherwise it means metadata or property of $message. If "keep_keys" option (added on 6.2.23b) is
set, forces using latter.
sprintf() is executed under "C" locale: Full stop (".") is always used for decimal point in floating
point number.
Methodssubclassshouldimplement
_create ( )
Instancemethod, overridable. Creates spool. By default, creates directories returned by
_directories().
_directories ( [ options, ... ] )
Classorinstancemethod, mandatoryforfilesystemspool. Returns hashref with directory paths
related to the spool as values. It must have keys at least "directory" and (if you wish to implement
quarantine() method) "bad_directory".
_filter ( $metadata )
Instancemethod, overridable. If it returned false value, processing of $metadata by next() will be
skipped. By default, always returns true value.
This method may modify unmarshalled metadata _and_ deserialized messages include it.
_filter_pre ( $metadata )
Instancemethod, overridable. If it returned false value, processing of $metadata by store() will be
skipped. By default, always returns true value.
This method may modify marshalled metadata _but_ stored messages are not affected.
_generator ( )
Classorinstancemethod, mandatory. Returns name of the class to serialize and deserialize messages
in the spool. If spool subclass is the collection (see _is_collection), generator class must
implement new(). Otherwise, generator class must implement dup(), new() and to_string().
_glob_pattern ( )
Deprecated. See _no_glob_pattern ( )
_init ( $state )
Instancemethod. Additional processing when _load() returns no contents ($state is 1) or when the
spool class is instantiated ($state is 0).
_is_collection ( )
Instancemethod, overridable. If the class is collection of spool class, returns true value. By
default returns false value.
Collection class does not have store() method. Its content is the set of spool instances.
_load ( )
Instancemethod, overridable. Loads sorted content of spool. Returns arrayref of marshalled
metadatas. By default, returns content of "{directory}" directory sorted by file name.
_marshal_format ( )
_marshal_keys ( )
_marshal_regexp ( )
Instancemethods, mandatoryforfilesystemspool. _marshal_format() and _marshal_keys() are used to
marshal metadata. _marshal_keys() and _marshal_regexp() are used to unmarshal metadata. See also
marshal_metadata() and unmarshal_metadata().
_no_glob_pattern ( )
Classorinstancemethod, overridableforfilesystemspool. If it returns false value, glob() is
used as much as possible to scan the spool faster. Otherwise readdir() is used for filesystem spool
to get all entries. By default returns false value.
_store_key ( )
Instancemethod. If implemented and returns non-empty string, store() returns an item in metadata
specified by this method. By default store() returns marshalled metadata (file name on filesystem
spool).
Marshalingandunmarshalingmetadata
Spool class gives generator class the metadata to instantiate it. On spool based on filesystem, it is
typically encoded into file names. For example a file name in incoming spool (Sympa::Spool::Incoming)
listname-owner@domain.name.143599229.12345
encodes the metadata
localpart => 'listname-owner',
listname => 'listname',
listtype => 'return_path',
domainpart => 'domain.name',
date => 143599229,
Metadata always includes information of context: List, Robot, Site (or Family). For example:
- Message in incoming spool bound for <listname@domain.name>:
context => Sympa::List <listname@domain.name>,
- Command message in incoming spool bound for <sympa@domain.name>:
context => 'domain.name',
- Message sent from Sympa to super-listmaster(s):
context => '*'
Context is determined when the generator class is instantiated, and generally never changed through
lifetime of instance. Thus, constructor of generator class should take context object as an argument.
"localpart" is encoded in a bit complex manner.
• If the context is Site or Robot, it is a value of "email" parameter, typically ""sympa"".
• If the context is Family, it is encoded as "@familyname". This encoding was added on Sympa 6.2.53b.
• If the context is List, it is encoded as local part of list address according to listtype (See also
"get_address" in Sympa).
Install Now
Emojis
PNG Icons
