.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ========================================================================
.\"
.IX Title "Sympa::Spindle 3Sympa"
.TH Sympa::Spindle 3Sympa "2022-11-25" "6.2.70" "sympa 6.2.70"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Sympa::Spindle \- Base class of subclasses to define Sympa workflows
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&  package Sympa::Spindle::FOO;
\&  use base qw(Sympa::Spindle);
\&
\&  use constant _distaff => \*(AqSympa::Spool::BAR\*(Aq;
\&  
\&  sub _twist {
\&      my $self = shift;
\&      my $object = shift;
\&  
\&      # Process object...
\& 
\&      return 1;                        # If succeeded.
\&      return 0;                        # If skipped.
\&      return undef;                    # If failed.
\&      return [\*(AqSympa::Spindle::BAZ\*(Aq];  # Splicing to the other class(es).
\&  }
\&
\&  1;
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Sympa::Spindle is the base class of subclasses to define particular
workflows of Sympa.
.PP
A spindle class is a set of features to process objects.
If \fBspin()\fR method is called, it retrieves each object from source spool,
processes it, at last passes altered object to appropriate destination
(another spool or mailer), and removes it as necessity.
Processing repeats until source spool is empty.
.SS "Public methods"
.IX Subsection "Public methods"
.IP "new ( [ key => value, ... ] )" 4
.IX Item "new ( [ key => value, ... ] )"
\&\fIConstructor\fR.
Creates new instance of Sympa::Spindle.
.IP "spin ( )" 4
.IX Item "spin ( )"
\&\fIInstance method\fR.
Fetches an object and handle locking it from source spool, processes them
calling \fB_twist()\fR and repeats.
If source spool no longer gives content, returns the number of processed
objects.
.IP "add_stash ( =\fIparameters\fR... )" 4
.IX Item "add_stash ( =parameters... )"
\&\fIInstance method\fR.
Adds arrayref of parameters to a storage for general-purpose.
.SS "Properties"
.IX Subsection "Properties"
Instance of Sympa::Spindle may have following properties.
.IP "{distaff}" 4
.IX Item "{distaff}"
Instance of source spool class \fB_distaff()\fR method returns.
.IP "{finish}" 4
.IX Item "{finish}"
\&\fIRead/write\fR.
At first this property is false.
Once it is set, \fBspin()\fR finishes processing safely.
.IP "Spools" 4
.IX Item "Spools"
Instances of spool classes \fB_spools()\fR method returns.
.IP "{start_time}" 4
.IX Item "{start_time}"
Unix time in floating point number when processing of the latest message by
\&\fBspin()\fR began.
Introduced by Sympa 6.2.13.
.IP "{stash}" 4
.IX Item "{stash}"
A reference to array of added data by \fBadd_stash()\fR.
.SS "Methods subclass should implement"
.IX Subsection "Methods subclass should implement"
.IP "_distaff ( )" 4
.IX Item "_distaff ( )"
\&\fIClass method\fR, \fImandatory\fR if you want to implement \fBspin()\fR.
Returns the name of source spool class.
source spool class must implement \fBnew()\fR and \fBnext()\fR.
.ie n .IP "_init ( $state )" 4
.el .IP "_init ( \f(CW$state\fR )" 4
.IX Item "_init ( $state )"
\&\fIInstance method\fR.
Additional processing
when the spindle class is instantiated ($state is 0), before \fBspin()\fR processes
next object in source spool ($state is 1) or after it processed object
($state is 2).
.Sp
If it returns false value, \fBnew()\fR will return \f(CW\*(C`undef\*(C'\fR (when \f(CW$state\fR is 0)
or \fBspin()\fR will terminate processing (when \f(CW$state\fR is 1).
By default it always returns \f(CW1\fR.
.ie n .IP "_on_garbage ( $handle )" 4
.el .IP "_on_garbage ( \f(CW$handle\fR )" 4
.IX Item "_on_garbage ( $handle )"
\&\fIInstance method\fR, \fIoverridable\fR.
Executes process when object could not be deserialized (\fBnew()\fR method of object
failed).
By default, quarantines object calling \fBquarantine()\fR method of source spool.
.ie n .IP "_on_failure ( $message, $handle )" 4
.el .IP "_on_failure ( \f(CW$message\fR, \f(CW$handle\fR )" 4
.IX Item "_on_failure ( $message, $handle )"
\&\fIInstance method\fR, \fIoverridable\fR.
Executes process when processing of \f(CW$message\fR failed (\fB_twist()\fR returned
\&\f(CW\*(C`undef\*(C'\fR).
By default, quarantines object calling \fBquarantine()\fR method of source spool.
.ie n .IP "_on_skip ( $message, $handle )" 4
.el .IP "_on_skip ( \f(CW$message\fR, \f(CW$handle\fR )" 4
.IX Item "_on_skip ( $message, $handle )"
\&\fIInstance method\fR, \fIoverridable\fR.
Executes process when \f(CW$message\fR was skipped (\fB_twist()\fR returned \f(CW0\fR).
By default, simply unlocks object calling \fBclose()\fR method of \f(CW$handle\fR.
.ie n .IP "_on_success ( $message, $handle )" 4
.el .IP "_on_success ( \f(CW$message\fR, \f(CW$handle\fR )" 4
.IX Item "_on_success ( $message, $handle )"
\&\fIInstance method\fR, \fIoverridable\fR.
Executes process when processing of \f(CW$message\fR succeeded (\fB_twist()\fR returned true
value).
By default, removes object calling \fBremove()\fR method of source spool.
.IP "_spools ( )" 4
.IX Item "_spools ( )"
\&\fIClass method\fR.
If implemented, returns hashref with names of spool classes related to the
spindle as values.
.ie n .IP "_twist ( $message )" 4
.el .IP "_twist ( \f(CW$message\fR )" 4
.IX Item "_twist ( $message )"
\&\fIInstance method\fR, \fImandatory\fR.
Processes an object: Typically, modifies object or creates another object and
stores it into appropriate spool.
.Sp
Parameter:
.RS 4
.ie n .IP "$message" 4
.el .IP "\f(CW$message\fR" 4
.IX Item "$message"
An object.
.RE
.RS 4
.Sp
Returns:
.Sp
Status of processing:
True value on success; \f(CW0\fR if processing skipped; \f(CW\*(C`undef\*(C'\fR on failure.
.Sp
As of Sympa 6.2.13, \fB_twist()\fR may also return the reference to array including
name(s) of other classes:
In this case \fBspin()\fR and \fBtwist()\fR will call \fB_twist()\fR method of given classes in
order (not coercing spindle object into them) and uses returned false value
at first or true value at last.
.RE
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Sympa::Internals::Workflow,
Sympa::Spool.
.SH "HISTORY"
.IX Header "HISTORY"
Sympa::Spindle appeared on Sympa 6.2.10.