.\" 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 3Sympa"
.TH Sympa 3Sympa "2020-12-30" "6.2.58" "sympa 6.2.58"
.\" 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 \- Future base class of Sympa functional objects
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This module aims to be the base class for functional objects of Sympa:
Site, Robot, Family and List.
.SS "Functions"
.IX Subsection "Functions"
\fIFinding config files and templates\fR
.IX Subsection "Finding config files and templates"
.ie n .IP "search_fullpath ( $that, $name, [ opt => val, ...] )" 4
.el .IP "search_fullpath ( \f(CW$that\fR, \f(CW$name\fR, [ opt => val, ...] )" 4
.IX Item "search_fullpath ( $that, $name, [ opt => val, ...] )"
.Vb 8
\&    # To get file name for global site
\&    $file = Sympa::search_fullpath(\*(Aq*\*(Aq, $name);
\&    # To get file name for a robot
\&    $file = Sympa::search_fullpath($robot_id, $name);
\&    # To get file name for a family
\&    $file = Sympa::search_fullpath($family, $name);
\&    # To get file name for a list
\&    $file = Sympa::search_fullpath($list, $name);
.Ve
.Sp
Look for a file in the list > robot > site > default locations.
.Sp
Possible values for options:
    order     => 'all'
    subdir    => directory ending each path
    lang      => language
    lang_only => if paths without lang subdirectory would be omitted
.Sp
Returns full path of target file \f(CW\*(C`\f(CIroot\f(CW/\f(CIsubdir\f(CW/\f(CIlang\f(CW/\f(CIname\f(CW\*(C'\fR
or \f(CW\*(C`\f(CIroot\f(CW/\f(CIsubdir\f(CW/\f(CIname\f(CW\*(C'\fR.
\&\fIroot\fR is the location determined by target object \f(CW$that\fR.
\&\fIsubdir\fR and \fIlang\fR are optional.
If \f(CW\*(C`lang_only\*(C'\fR option is set, paths without \fIlang\fR subdirectory is omitted.
.ie n .IP "get_search_path ( $that, [ opt => val, ... ] )" 4
.el .IP "get_search_path ( \f(CW$that\fR, [ opt => val, ... ] )" 4
.IX Item "get_search_path ( $that, [ opt => val, ... ] )"
.Vb 8
\&    # To make include path for global site
\&    @path = @{Sympa::get_search_path(\*(Aq*\*(Aq)};
\&    # To make include path for a robot
\&    @path = @{Sympa::get_search_path($robot_id)};
\&    # To make include path for a family
\&    @path = @{Sympa::get_search_path($family)};
\&    # To make include path for a list
\&    @path = @{Sympa::get_search_path($list)};
.Ve
.Sp
make an array of include path for tt2 parsing
.Sp
\&\s-1IN :\s0
      \-$that(+) : ref(Sympa::List) | ref(Sympa::Family) | Robot | \*(L"*\*(R"
      \-%options : options
.Sp
Possible values for options:
    subdir    => directory ending each path
    lang      => language
    lang_only => if paths without lang subdirectory would be omitted
.Sp
\&\s-1OUT :\s0 ref(\s-1ARRAY\s0) of tt2 include path
.PP
\fISending Notifications\fR
.IX Subsection "Sending Notifications"
.ie n .IP "send_dsn ( $that, $message, [ { key => val, ... }, [ $status, [ $diag ] ] ] )" 4
.el .IP "send_dsn ( \f(CW$that\fR, \f(CW$message\fR, [ { key => val, ... }, [ \f(CW$status\fR, [ \f(CW$diag\fR ] ] ] )" 4
.IX Item "send_dsn ( $that, $message, [ { key => val, ... }, [ $status, [ $diag ] ] ] )"
.Vb 8
\&    # To send site\-wide DSN
\&    Sympa::send_dsn(\*(Aq*\*(Aq, $message, {\*(Aqrecipient\*(Aq => $rcpt},
\&        \*(Aq5.1.2\*(Aq, \*(AqUnknown robot\*(Aq);
\&    # To send DSN related to a robot
\&    Sympa::send_dsn($robot, $message, {\*(Aqlistname\*(Aq => $name},
\&        \*(Aq5.1.1\*(Aq, \*(AqUnknown list\*(Aq);
\&    # To send DSN specific to a list
\&    Sympa::send_dsn($list, $message, {}, \*(Aq2.1.5\*(Aq, \*(AqSuccess\*(Aq);
.Ve
.Sp
Sends a delivery status notification (\s-1DSN\s0) to \s-1SENDER\s0
by parsing delivery_status_notification.tt2 template.
.ie n .IP "send_file ( $that, $tpl, $who, [ $context, [ options... ] ] )" 4
.el .IP "send_file ( \f(CW$that\fR, \f(CW$tpl\fR, \f(CW$who\fR, [ \f(CW$context\fR, [ options... ] ] )" 4
.IX Item "send_file ( $that, $tpl, $who, [ $context, [ options... ] ] )"
.Vb 8
\&    # To send site\-global (not relative to a list or a robot)
\&    # message
\&    Sympa::send_file(\*(Aq*\*(Aq, $template, $who, ...);
\&    # To send global (not relative to a list, but relative to a
\&    # robot) message
\&    Sympa::send_file($robot, $template, $who, ...);
\&    # To send message relative to a list
\&    Sympa::send_file($list, $template, $who, ...);
.Ve
.Sp
Send a message to user(s).
Find the tt2 file according to \f(CW$tpl\fR, set up
\&\f(CW$data\fR for the next parsing (with \f(CW$context\fR and
configuration)
Message is signed if the list has a key and a
certificate
.Sp
Note: \fBList::send_global_file()\fR was deprecated.
.ie n .IP "send_notify_to_listmaster ( $that, $operation, $data )" 4
.el .IP "send_notify_to_listmaster ( \f(CW$that\fR, \f(CW$operation\fR, \f(CW$data\fR )" 4
.IX Item "send_notify_to_listmaster ( $that, $operation, $data )"
.Vb 6
\&    # To send notify to super listmaster(s)
\&    Sympa::send_notify_to_listmaster(\*(Aq*\*(Aq, \*(Aqcss_updated\*(Aq, ...);
\&    # To send notify to normal (per\-robot) listmaster(s)
\&    Sympa::send_notify_to_listmaster($robot, \*(Aqweb_tt2_error\*(Aq, ...);
\&    # To send notify to normal listmaster(s) of robot the list belongs to.
\&    Sympa::send_notify_to_listmaster($list, \*(Aqrequest_list_creation\*(Aq, ...);
.Ve
.Sp
Sends a notice to (super or normal) listmaster by parsing
listmaster_notification.tt2 template.
.Sp
Parameters:
.RS 4
.ie n .IP "$self" 4
.el .IP "\f(CW$self\fR" 4
.IX Item "$self"
Sympa::List, Robot or Site.
.ie n .IP "$operation" 4
.el .IP "\f(CW$operation\fR" 4
.IX Item "$operation"
Notification type.
.ie n .IP "$param" 4
.el .IP "\f(CW$param\fR" 4
.IX Item "$param"
Hashref or arrayref.
Values for template parsing.
.RE
.RS 4
.Sp
Returns:
.Sp
\&\f(CW1\fR or \f(CW\*(C`undef\*(C'\fR.
.RE
.ie n .IP "send_notify_to_user ( $that, $operation, $user, $param )" 4
.el .IP "send_notify_to_user ( \f(CW$that\fR, \f(CW$operation\fR, \f(CW$user\fR, \f(CW$param\fR )" 4
.IX Item "send_notify_to_user ( $that, $operation, $user, $param )"
Send a notice to a user (sender, subscriber or another user)
by parsing user_notification.tt2 template.
.Sp
Parameters:
.RS 4
.ie n .IP "$that" 4
.el .IP "\f(CW$that\fR" 4
.IX Item "$that"
Sympa::List, Robot or Site.
.ie n .IP "$operation" 4
.el .IP "\f(CW$operation\fR" 4
.IX Item "$operation"
Notification type.
.ie n .IP "$user" 4
.el .IP "\f(CW$user\fR" 4
.IX Item "$user"
E\-mail of notified user.
.ie n .IP "$param" 4
.el .IP "\f(CW$param\fR" 4
.IX Item "$param"
Hashref or arrayref.  Values for template parsing.
.RE
.RS 4
.Sp
Returns:
.Sp
\&\f(CW1\fR or \f(CW\*(C`undef\*(C'\fR.
.RE
.PP
\fIInternationalization\fR
.IX Subsection "Internationalization"
.IP "best_language ( \s-1LANG, ...\s0 )" 4
.IX Item "best_language ( LANG, ... )"
.Vb 6
\&    # To get site\-wide best language.
\&    $lang = Sympa::best_language(\*(Aq*\*(Aq, \*(Aqde\*(Aq, \*(Aqen\-US;q=0.9\*(Aq);
\&    # To get robot\-wide best language.
\&    $lang = Sympa::best_language($robot, \*(Aqde\*(Aq, \*(Aqen\-US;q=0.9\*(Aq);
\&    # To get list\-specific best language.
\&    $lang = Sympa::best_language($list, \*(Aqde\*(Aq, \*(Aqen\-US;q=0.9\*(Aq);
.Ve
.Sp
Chooses best language under the context of List, Robot or Site.
Arguments are language codes (see Language) or ones with quality value.
If no arguments are given, the value of \f(CW\*(C`HTTP_ACCEPT_LANGUAGE\*(C'\fR environment
variable will be used.
.Sp
Returns language tag or, if negotiation failed, lang of object.
.ie n .IP "get_supported_languages ( $that )" 4
.el .IP "get_supported_languages ( \f(CW$that\fR )" 4
.IX Item "get_supported_languages ( $that )"
\&\fIFunction\fR.
Gets supported languages, canonicalized.
In array context, returns array of supported languages.
In scalar context, returns arrayref to them.
.PP
\fIAddresses and users\fR
.IX Subsection "Addresses and users"
.PP
These are accessors derived from configuration parameters.
.ie n .IP "get_address ( $that, [ $type ] )" 4
.el .IP "get_address ( \f(CW$that\fR, [ \f(CW$type\fR ] )" 4
.IX Item "get_address ( $that, [ $type ] )"
.Vb 10
\&    # Get address bound for super listmaster(s).
\&    Sympa::get_address(\*(Aq*\*(Aq, \*(Aqlistmaster\*(Aq);     # <listmaster@DEFAULT_HOST>
\&    # Get address for command robot and robot listmaster(s).
\&    Sympa::get_address($robot, \*(Aqsympa\*(Aq);       # <sympa@HOST>
\&    Sympa::get_address($robot, \*(Aqlistmaster\*(Aq);  # <listmaster@HOST>
\&    # Get address for command robot and robot listmaster(s).
\&    Sympa::get_address($family, \*(Aqsympa\*(Aq);      # <sympa@HOST>
\&    Sympa::get_address($family, \*(Aqlistmaster\*(Aq); # listmaster@HOST>
\&    # Get address bound for the list and its owner(s) etc.
\&    Sympa::get_address($list);                 # <NAME@HOST>
\&    Sympa::get_address($list, \*(Aqowner\*(Aq);        # <NAME\-request@HOST>
\&    Sympa::get_address($list, \*(Aqeditor\*(Aq);       # <NAME\-editor@HOST>
\&    Sympa::get_address($list, \*(Aqreturn_path\*(Aq);  # <NAME\-owner@HOST>
.Ve
.Sp
Site or robot:
Returns the site or robot email address of type \f(CW$type:\fR email command address
(default, <sympa> address), \*(L"sympaowner\*(R" (<sympa\-request> address) or
\&\*(L"listmaster\*(R".
.Sp
List:
Returns the list email address of type \f(CW$type:\fR posting address (default),
\&\*(L"owner\*(R" (<LIST\-request> address), \*(L"editor\*(R", non-VERP \*(L"return_path\*(R"
(<LIST\-owner> address), \*(L"subscribe\*(R" or \*(L"unsubscribe\*(R".
.Sp
Note:
.RS 4
.IP "\(bu" 4
\&\f(CW%Conf::Conf\fR or \fBConf::get_robot_conf()\fR may return <sympa> and
<sympa\-request> addresses by \*(L"sympa\*(R" and \*(L"request\*(R" arguments, respectively.
They are obsoleted.  Use this function instead.
.IP "\(bu" 4
\&\f(CW"sympaowner"\fR with robot context was introduced on 6.2.57b.2.
\&\f(CW"owner"\fR and \f(CW"request"\fR may also be used for convenience.
.RE
.RS 4
.RE
.ie n .IP "get_listmasters_email ( $that )" 4
.el .IP "get_listmasters_email ( \f(CW$that\fR )" 4
.IX Item "get_listmasters_email ( $that )"
.Vb 8
\&    # To get addresses of super\-listmasters.
\&    @addrs = Sympa::get_listmasters_email(\*(Aq*\*(Aq);
\&    # To get addresses of normal listmasters of a robot.
\&    @addrs = Sympa::get_listmasters_email($robot);
\&    # To get addresses of normal listmasters of the robot of a family.
\&    @addrs = Sympa::get_listmasters_email($family);
\&    # To get addresses of normal listmasters of the robot of a list.
\&    @addrs = Sympa::get_listmasters_email($list);
.Ve
.Sp
Gets valid email addresses of listmasters. In array context, returns array of
addresses. In scalar context, returns arrayref to them.
.ie n .IP "get_url ( $that, $action, [ nomenu => 1 ], [ paths => \e@paths ], [ authority => $mode ], [ options... ] )" 4
.el .IP "get_url ( \f(CW$that\fR, \f(CW$action\fR, [ nomenu => 1 ], [ paths => \e@paths ], [ authority => \f(CW$mode\fR ], [ options... ] )" 4
.IX Item "get_url ( $that, $action, [ nomenu => 1 ], [ paths => @paths ], [ authority => $mode ], [ options... ] )"
Returns \s-1URL\s0 for web interface.
.Sp
Parameters:
.RS 4
.ie n .IP "$action" 4
.el .IP "\f(CW$action\fR" 4
.IX Item "$action"
Name of action.
This is inserted into \s-1URL\s0 intact.
.ie n .IP "authority => $mode" 4
.el .IP "authority => \f(CW$mode\fR" 4
.IX Item "authority => $mode"
\&\f(CW\*(Aqdefault\*(Aq\fR respects \f(CW\*(C`wwsympa_url\*(C'\fR parameter.
\&\f(CW\*(Aqlocal\*(Aq\fR is similar but may replace host name and script path.
\&\f(CW\*(Aqomit\*(Aq\fR omits scheme and authority, i.e. returns relative \s-1URI.\s0
.Sp
Note that \f(CW\*(Aqlocal\*(Aq\fR mode works correctly only under \s-1CGI\s0 environment.
See also a note below.
.IP "nomenu => 1" 4
.IX Item "nomenu => 1"
Adds \f(CW\*(C`nomenu\*(C'\fR modifier.
.IP "paths => \e@paths" 4
.IX Item "paths => @paths"
Additional path components.
Note that they are percent-encoded as necessity.
.IP "options..." 4
.IX Item "options..."
See \*(L"weburl\*(R" in Sympa::Tools::Text.
.RE
.RS 4
.Sp
Returns:
.Sp
A string.
.Sp
Note:
If \f(CW$mode\fR is \f(CW\*(Aqlocal\*(Aq\fR, result is that Sympa server recognizes locally.
In other cases, result is the \s-1URI\s0 that is used by end users to access to web
interface.
When, for example, the server is placed behind a reverse-proxy,
\&\f(CW\*(C`Location:\*(C'\fR field in \s-1HTTP\s0 response to cause redirection would be better
to contain \f(CW\*(Aqlocal\*(Aq\fR \s-1URI.\s0
.RE
.ie n .IP "is_listmaster ( $that, $who )" 4
.el .IP "is_listmaster ( \f(CW$that\fR, \f(CW$who\fR )" 4
.IX Item "is_listmaster ( $that, $who )"
Is the user listmaster?
.ie n .IP "unique_message_id ( $that )" 4
.el .IP "unique_message_id ( \f(CW$that\fR )" 4
.IX Item "unique_message_id ( $that )"
\&\s-1TBD\s0
.SH "SEE ALSO"
.IX Header "SEE ALSO"
Sympa::Site (not yet available),
Sympa::Robot (not yet available),
Sympa::Family,
Sympa::List.