Provided by: libanyevent-xmpp-perl_0.55-5_all bug

NAME

       AnyEvent::XMPP::Util - Utility functions for AnyEvent::XMPP

SYNOPSIS

          use AnyEvent::XMPP::Util qw/split_jid/;
          ...

FUNCTIONS

       These functions can be exported if you want:

       resourceprep ($string)
           This function applies the stringprep profile for resources to $string and returns the
           result.

       nodeprep ($string)
           This function applies the stringprep profile for nodes to $string and returns the
           result.

       prep_join_jid ($node, $domain, $resource)
           This function joins the parts $node, $domain and $resource to a full jid and applies
           stringprep profiles. If the profiles couldn't be applied undef will be returned.

       join_jid ($user, $domain, $resource)
           This is a plain concatenation of $user, $domain and $resource without stringprep.

           See also prep_join_jid

       split_uri ($uri)
           This function splits up the $uri into service and node part and will return them as
           list.

              my ($service, $node) = split_uri ($uri);

       split_jid ($jid)
           This function splits up the $jid into user/node, domain and resource part and will
           return them as list.

              my ($user, $host, $res) = split_jid ($jid);

       node_jid ($jid)
           See "prep_res_jid" below.

       domain_jid ($jid)
           See "prep_res_jid" below.

       res_jid ($jid)
           See "prep_res_jid" below.

       prep_node_jid ($jid)
           See "prep_res_jid" below.

       prep_domain_jid ($jid)
           See "prep_res_jid" below.

       prep_res_jid ($jid)
           These functions return the corresponding parts of a JID.  The "prep_" prefixed JIDs
           return the stringprep'ed versions.

       stringprep_jid ($jid)
           This applies stringprep to all parts of the jid according to the RFC 3920.  Use this
           if you want to compare two jids like this:

              stringprep_jid ($jid_a) eq stringprep_jid ($jid_b)

           This function returns undef if the $jid couldn't successfully be parsed and the
           preparations done.

       cmp_jid ($jid1, $jid2)
           This function compares two jids $jid1 and $jid2 whether they are equal.

       cmp_bare_jid ($jid1, $jid2)
           This function compares two jids $jid1 and $jid2 whether their bare part is equal.

       prep_bare_jid ($jid)
           This function makes the jid $jid a bare jid, meaning: it will strip off the resource
           part. With stringprep.

       bare_jid ($jid)
           This function makes the jid $jid a bare jid, meaning: it will strip off the resource
           part. But without stringprep.

       is_bare_jid ($jid)
           This method returns a boolean which indicates whether $jid is a bare JID.

       filter_xml_chars ($string)
           This function removes all characters from $string which are not allowed in XML and
           returns the new string.

       filter_xml_attr_hash_chars ($hashref)
           This runs all values of the $hashref through "filter_xml_chars" (see above) and
           changes them in-place!

       simxml ($w, %xmlstruct)
           This function takes a XML::Writer as first argument ($w) and the rest key value pairs:

              simxml ($w,
                 defns    => '<xmlnamespace>',
                 node     => <node>,
                 prefixes => { prefix => namespace, ... },
              );

           Where node is:

              <node> := {
                           ns => '<xmlnamespace>',
                           name => 'tagname',
                           attrs => [ 'name', 'value', 'name2', 'value2', ... ],
                           childs => [ <node>, ... ]
                        }
                      | {
                           dns => '<xmlnamespace>',  # this will set that namespace to
                                                     # the default namespace before using it.
                           name => 'tagname',
                           attrs => [ 'name', 'value', 'name2', 'value2', ... ],
                           childs => [ <node>, ... ]
                        }
                      | sub { my ($w) = @_; ... } # with $w being a XML::Writer object
                      | "textnode"

           Please note: "childs" stands for "child sequence" :-)

           Also note that if you omit the "ns" 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:

              {
                 defns => 'muc_owner',
                 node => { name => 'query' }
              }

           (Without having to include "ns" in the node.)

           Please note that all attribute values and character data will be filtered by
           "filter_xml_chars".

           This is a bigger example:

              ...

              $msg->append_creation( sub {
                 my($w) = @_;
                 simxml($w,
                    defns => 'muc_user',   # sets the default namepsace for all following elements
                    node  => {
                       name => 'x',        # element 'x' in namespace 'muc_user'
                       childs => [
                          {
                             'name' => 'invite', # element 'invite' in namespace 'muc_user'
                             'attrs' => [ 'to', $to_jid ], # to="$to_jid" attribute for 'invite'
                             'childs' => [
                                { # the <reason>$reason</reason> element in the invite element
                                  'name' => 'reason',
                                  childs => [ $reason ]
                                }
                             ],
                          }
                       ]
                    }
                 );
              });

       to_xmpp_time ($sec, $min, $hour, $tz, $secfrac)
           This function transforms a time to the XMPP date time format.  The meanings and value
           ranges of $sec, ..., $hour are explained in the perldoc of Perl's builtin "localtime".

           $tz has to be either "UTC" or of the form "[+-]hh:mm", it can be undefined and wont
           occur in the time string then.

           $secfrac are optional and can be the fractions of the second.

           See also XEP-0082.

       to_xmpp_datetime ($sec,$min,$hour,$mday,$mon,$year,$tz, $secfrac)
           This function transforms a time to the XMPP date time format.  The meanings of $sec,
           ..., $year are explained in the perldoc of Perl's "localtime" builtin and have the
           same value ranges.

           $tz has to be either "Z" (for UTC) or of the form "[+-]hh:mm" (offset from UTC), if it
           is undefined "Z" will be used.

           $secfrac are optional and can be the fractions of the second.

           See also XEP-0082.

       from_xmpp_datetime ($string)
           This function transforms the $string which is either a time or datetime in XMPP
           format. If the string was not in the right format an empty list is returned.
           Otherwise this is returned:

              my ($sec, $min, $hour, $mday, $mon, $year, $tz, $secfrac)
                 = from_xmpp_datetime ($string);

           For the value ranges and semantics of $sec, ..., $srcfrac please look at the
           documentation for "to_xmpp_datetime".

           $tz and $secfrac might be undefined.

           If $tz is undefined the timezone is to be assumed to be UTC.

           If $string contained just a time $mday, $mon and $year will be undefined.

           See also XEP-0082.

       xmpp_datetime_as_timestamp ($string)
           This function takes the same arguments as "from_xmpp_datetime", but returns a unix
           timestamp, like "time ()" would.

           This function requires the POSIX module.

AUTHOR

       Robin Redeker, "<elmex at ta-sa.org>", JID: "<elmex at jabber.org>"

COPYRIGHT & LICENSE

       Copyright 2007, 2008 Robin Redeker, all rights reserved.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.