.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43)
.\"
.\" 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
.\" ========================================================================
.\"
.IX Title "AnyEvent::XMPP::Util 3pm"
.TH AnyEvent::XMPP::Util 3pm "2022-12-06" "perl v5.36.0" "User Contributed Perl Documentation"
.\" 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"
AnyEvent::XMPP::Util \- Utility functions for AnyEvent::XMPP
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&   use AnyEvent::XMPP::Util qw/split_jid/;
\&   ...
.Ve
.SH "FUNCTIONS"
.IX Header "FUNCTIONS"
These functions can be exported if you want:
.IP "\fBresourceprep ($string)\fR" 4
.IX Item "resourceprep ($string)"
This function applies the stringprep profile for resources to \f(CW$string\fR
and returns the result.
.IP "\fBnodeprep ($string)\fR" 4
.IX Item "nodeprep ($string)"
This function applies the stringprep profile for nodes to \f(CW$string\fR
and returns the result.
.IP "\fBprep_join_jid ($node, \f(CB$domain\fB, \f(CB$resource\fB)\fR" 4
.IX Item "prep_join_jid ($node, $domain, $resource)"
This function joins the parts \f(CW$node\fR, \f(CW$domain\fR and \f(CW$resource\fR
to a full jid and applies stringprep profiles. If the profiles couldn't
be applied undef will be returned.
.IP "\fBjoin_jid ($user, \f(CB$domain\fB, \f(CB$resource\fB)\fR" 4
.IX Item "join_jid ($user, $domain, $resource)"
This is a plain concatenation of \f(CW$user\fR, \f(CW$domain\fR and \f(CW$resource\fR
without stringprep.
.Sp
See also prep_join_jid
.IP "\fBsplit_uri ($uri)\fR" 4
.IX Item "split_uri ($uri)"
This function splits up the \f(CW$uri\fR into service and node
part and will return them as list.
.Sp
.Vb 1
\&   my ($service, $node) = split_uri ($uri);
.Ve
.IP "\fBsplit_jid ($jid)\fR" 4
.IX Item "split_jid ($jid)"
This function splits up the \f(CW$jid\fR into user/node, domain and resource
part and will return them as list.
.Sp
.Vb 1
\&   my ($user, $host, $res) = split_jid ($jid);
.Ve
.IP "\fBnode_jid ($jid)\fR" 4
.IX Item "node_jid ($jid)"
See \f(CW\*(C`prep_res_jid\*(C'\fR below.
.IP "\fBdomain_jid ($jid)\fR" 4
.IX Item "domain_jid ($jid)"
See \f(CW\*(C`prep_res_jid\*(C'\fR below.
.IP "\fBres_jid ($jid)\fR" 4
.IX Item "res_jid ($jid)"
See \f(CW\*(C`prep_res_jid\*(C'\fR below.
.IP "\fBprep_node_jid ($jid)\fR" 4
.IX Item "prep_node_jid ($jid)"
See \f(CW\*(C`prep_res_jid\*(C'\fR below.
.IP "\fBprep_domain_jid ($jid)\fR" 4
.IX Item "prep_domain_jid ($jid)"
See \f(CW\*(C`prep_res_jid\*(C'\fR below.
.IP "\fBprep_res_jid ($jid)\fR" 4
.IX Item "prep_res_jid ($jid)"
These functions return the corresponding parts of a \s-1JID.\s0
The \f(CW\*(C`prep_\*(C'\fR prefixed JIDs return the stringprep'ed versions.
.IP "\fBstringprep_jid ($jid)\fR" 4
.IX Item "stringprep_jid ($jid)"
This applies stringprep to all parts of the jid according to the \s-1RFC 3920.\s0
Use this if you want to compare two jids like this:
.Sp
.Vb 1
\&   stringprep_jid ($jid_a) eq stringprep_jid ($jid_b)
.Ve
.Sp
This function returns undef if the \f(CW$jid\fR couldn't successfully be parsed
and the preparations done.
.IP "\fBcmp_jid ($jid1, \f(CB$jid2\fB)\fR" 4
.IX Item "cmp_jid ($jid1, $jid2)"
This function compares two jids \f(CW$jid1\fR and \f(CW$jid2\fR
whether they are equal.
.IP "\fBcmp_bare_jid ($jid1, \f(CB$jid2\fB)\fR" 4
.IX Item "cmp_bare_jid ($jid1, $jid2)"
This function compares two jids \f(CW$jid1\fR and \f(CW$jid2\fR whether their
bare part is equal.
.IP "\fBprep_bare_jid ($jid)\fR" 4
.IX Item "prep_bare_jid ($jid)"
This function makes the jid \f(CW$jid\fR a bare jid, meaning:
it will strip off the resource part. With stringprep.
.IP "\fBbare_jid ($jid)\fR" 4
.IX Item "bare_jid ($jid)"
This function makes the jid \f(CW$jid\fR a bare jid, meaning:
it will strip off the resource part. But without stringprep.
.IP "\fBis_bare_jid ($jid)\fR" 4
.IX Item "is_bare_jid ($jid)"
This method returns a boolean which indicates whether \f(CW$jid\fR is a 
bare \s-1JID.\s0
.IP "\fBfilter_xml_chars ($string)\fR" 4
.IX Item "filter_xml_chars ($string)"
This function removes all characters from \f(CW$string\fR which
are not allowed in \s-1XML\s0 and returns the new string.
.IP "\fBfilter_xml_attr_hash_chars ($hashref)\fR" 4
.IX Item "filter_xml_attr_hash_chars ($hashref)"
This runs all values of the \f(CW$hashref\fR through \f(CW\*(C`filter_xml_chars\*(C'\fR (see above)
and changes them in-place!
.IP "\fBsimxml ($w, \f(CB%xmlstruct\fB)\fR" 4
.IX Item "simxml ($w, %xmlstruct)"
This function takes a XML::Writer as first argument (\f(CW$w\fR) and the
rest key value pairs:
.Sp
.Vb 5
\&   simxml ($w,
\&      defns    => \*(Aq<xmlnamespace>\*(Aq,
\&      node     => <node>,
\&      prefixes => { prefix => namespace, ... },
\&   );
.Ve
.Sp
Where node is:
.Sp
.Vb 10
\&   <node> := {
\&                ns => \*(Aq<xmlnamespace>\*(Aq,
\&                name => \*(Aqtagname\*(Aq,
\&                attrs => [ \*(Aqname\*(Aq, \*(Aqvalue\*(Aq, \*(Aqname2\*(Aq, \*(Aqvalue2\*(Aq, ... ],
\&                childs => [ <node>, ... ]
\&             }
\&           | {
\&                dns => \*(Aq<xmlnamespace>\*(Aq,  # this will set that namespace to
\&                                          # the default namespace before using it.
\&                name => \*(Aqtagname\*(Aq,
\&                attrs => [ \*(Aqname\*(Aq, \*(Aqvalue\*(Aq, \*(Aqname2\*(Aq, \*(Aqvalue2\*(Aq, ... ],
\&                childs => [ <node>, ... ]
\&             }
\&           | sub { my ($w) = @_; ... } # with $w being a XML::Writer object
\&           | "textnode"
.Ve
.Sp
Please note: \f(CW\*(C`childs\*(C'\fR stands for \f(CW\*(C`child sequence\*(C'\fR :\-)
.Sp
Also note that if you omit the \f(CW\*(C`ns\*(C'\fR key for nodes there is a fall back
to the namespace of the parent element or the last default namespace.
This makes it easier to write things like this:
.Sp
.Vb 4
\&   {
\&      defns => \*(Aqmuc_owner\*(Aq,
\&      node => { name => \*(Aqquery\*(Aq }
\&   }
.Ve
.Sp
(Without having to include \f(CW\*(C`ns\*(C'\fR in the node.)
.Sp
Please note that all attribute values and character data will be filtered
by \f(CW\*(C`filter_xml_chars\*(C'\fR.
.Sp
This is a bigger example:
.Sp
.Vb 1
\&   ...
\&
\&   $msg\->append_creation( sub {
\&      my($w) = @_;
\&      simxml($w,
\&         defns => \*(Aqmuc_user\*(Aq,   # sets the default namepsace for all following elements
\&         node  => {
\&            name => \*(Aqx\*(Aq,        # element \*(Aqx\*(Aq in namespace \*(Aqmuc_user\*(Aq
\&            childs => [
\&               {
\&                  \*(Aqname\*(Aq => \*(Aqinvite\*(Aq, # element \*(Aqinvite\*(Aq in namespace \*(Aqmuc_user\*(Aq
\&                  \*(Aqattrs\*(Aq => [ \*(Aqto\*(Aq, $to_jid ], # to="$to_jid" attribute for \*(Aqinvite\*(Aq
\&                  \*(Aqchilds\*(Aq => [         
\&                     { # the <reason>$reason</reason> element in the invite element
\&                       \*(Aqname\*(Aq => \*(Aqreason\*(Aq, 
\&                       childs => [ $reason ]
\&                     }
\&                  ],
\&               }
\&            ]
\&         }
\&      );
\&   });
.Ve
.IP "\fBto_xmpp_time ($sec, \f(CB$min\fB, \f(CB$hour\fB, \f(CB$tz\fB, \f(CB$secfrac\fB)\fR" 4
.IX Item "to_xmpp_time ($sec, $min, $hour, $tz, $secfrac)"
This function transforms a time to the \s-1XMPP\s0 date time format.
The meanings and value ranges of \f(CW$sec\fR, ..., \f(CW$hour\fR are explained
in the perldoc of Perl's builtin \f(CW\*(C`localtime\*(C'\fR.
.Sp
\&\f(CW$tz\fR has to be either \f(CW"UTC"\fR or of the form \f(CW\*(C`[+\-]hh:mm\*(C'\fR, it can be undefined
and wont occur in the time string then.
.Sp
\&\f(CW$secfrac\fR are optional and can be the fractions of the second.
.Sp
See also \s-1XEP\-0082.\s0
.IP "\fBto_xmpp_datetime ($sec,$min,$hour,$mday,$mon,$year,$tz, \f(CB$secfrac\fB)\fR" 4
.IX Item "to_xmpp_datetime ($sec,$min,$hour,$mday,$mon,$year,$tz, $secfrac)"
This function transforms a time to the \s-1XMPP\s0 date time format.
The meanings of \f(CW$sec\fR, ..., \f(CW$year\fR are explained in the perldoc
of Perl's \f(CW\*(C`localtime\*(C'\fR builtin and have the same value ranges.
.Sp
\&\f(CW$tz\fR has to be either \f(CW"Z"\fR (for \s-1UTC\s0) or of the form \f(CW\*(C`[+\-]hh:mm\*(C'\fR (offset
from \s-1UTC\s0), if it is undefined \*(L"Z\*(R" will be used.
.Sp
\&\f(CW$secfrac\fR are optional and can be the fractions of the second.
.Sp
See also \s-1XEP\-0082.\s0
.IP "\fBfrom_xmpp_datetime ($string)\fR" 4
.IX Item "from_xmpp_datetime ($string)"
This function transforms the \f(CW$string\fR which is either a time or datetime in \s-1XMPP\s0
format. If the string was not in the right format an empty list is returned.
Otherwise this is returned:
.Sp
.Vb 2
\&   my ($sec, $min, $hour, $mday, $mon, $year, $tz, $secfrac)
\&      = from_xmpp_datetime ($string);
.Ve
.Sp
For the value ranges and semantics of \f(CW$sec\fR, ..., \f(CW$srcfrac\fR please look at the
documentation for \f(CW\*(C`to_xmpp_datetime\*(C'\fR.
.Sp
\&\f(CW$tz\fR and \f(CW$secfrac\fR might be undefined.
.Sp
If \f(CW$tz\fR is undefined the timezone is to be assumed to be \s-1UTC.\s0
.Sp
If \f(CW$string\fR contained just a time \f(CW$mday\fR, \f(CW$mon\fR and \f(CW$year\fR will be undefined.
.Sp
See also \s-1XEP\-0082.\s0
.IP "\fBxmpp_datetime_as_timestamp ($string)\fR" 4
.IX Item "xmpp_datetime_as_timestamp ($string)"
This function takes the same arguments as \f(CW\*(C`from_xmpp_datetime\*(C'\fR, but returns a
unix timestamp, like \f(CW\*(C`time ()\*(C'\fR would.
.Sp
This function requires the \s-1POSIX\s0 module.
.SH "AUTHOR"
.IX Header "AUTHOR"
Robin Redeker, \f(CW\*(C`<elmex at ta\-sa.org>\*(C'\fR, \s-1JID:\s0 \f(CW\*(C`<elmex at jabber.org>\*(C'\fR
.SH "COPYRIGHT & LICENSE"
.IX Header "COPYRIGHT & LICENSE"
Copyright 2007, 2008 Robin Redeker, all rights reserved.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.