.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (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
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    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 "XML::Atom::Client 3pm"
.TH XML::Atom::Client 3pm 2024-07-13 "perl v5.38.2" "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
XML::Atom::Client \- A client for the Atom API
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 5
\&    use XML::Atom::Client;
\&    use XML::Atom::Entry;
\&    my $api = XML::Atom::Client\->new;
\&    $api\->username(\*(AqMelody\*(Aq);
\&    $api\->password(\*(AqNelson\*(Aq);
\&
\&    my $entry = XML::Atom::Entry\->new;
\&    $entry\->title(\*(AqNew Post\*(Aq);
\&    $entry\->content(\*(AqContent of my post.\*(Aq);
\&    my $EditURI = $api\->createEntry($PostURI, $entry);
\&
\&    my $feed = $api\->getFeed($FeedURI);
\&    my @entries = $feed\->entries;
\&
\&    my $entry = $api\->getEntry($EditURI);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fIXML::Atom::Client\fR implements a client for the Atom API described at
\&\fIhttp://bitworking.org/projects/atom/draft\-gregorio\-09.html\fR, with the
authentication scheme described at
\&\fIhttp://www.intertwingly.net/wiki/pie/DifferentlyAbledClients\fR.
.PP
\&\fBNOTE:\fR the API, and particularly the authentication scheme, are still
in flux.
.SH USAGE
.IX Header "USAGE"
.SS XML::Atom::Client\->new(%param)
.IX Subsection "XML::Atom::Client->new(%param)"
.ie n .SS "$api\->use_soap([ 0 | 1 ])"
.el .SS "\f(CW$api\fP\->use_soap([ 0 | 1 ])"
.IX Subsection "$api->use_soap([ 0 | 1 ])"
\&\fIXML::Atom::Client\fR supports both the REST and SOAP-wrapper versions of the
Atom API. By default, the REST version of the API will be used, but you can
turn on the SOAP wrapper\-\-for example, if you need to connect to a server
that supports only the SOAP wrapper\-\-by calling \fIuse_soap\fR with a value of
\&\f(CW1\fR:
.PP
.Vb 1
\&    $api\->use_soap(1);
.Ve
.PP
If called without arguments, returns the current value of the flag.
.ie n .SS "$api\->username([ $username ])"
.el .SS "\f(CW$api\fP\->username([ \f(CW$username\fP ])"
.IX Subsection "$api->username([ $username ])"
If called with an argument, sets the username for login to \fR\f(CI$username\fR\fI\fR.
.PP
Returns the current username that will be used when logging in to the
Atom server.
.ie n .SS "$api\->password([ $password ])"
.el .SS "\f(CW$api\fP\->password([ \f(CW$password\fP ])"
.IX Subsection "$api->password([ $password ])"
If called with an argument, sets the password for login to \fR\f(CI$password\fR\fI\fR.
.PP
Returns the current password that will be used when logging in to the
Atom server.
.ie n .SS "$api\->createEntry($PostURI, $entry)"
.el .SS "\f(CW$api\fP\->createEntry($PostURI, \f(CW$entry\fP)"
.IX Subsection "$api->createEntry($PostURI, $entry)"
Creates a new entry.
.PP
\&\fR\f(CI$entry\fR\fI\fR must be an \fIXML::Atom::Entry\fR object.
.ie n .SS $api\->getEntry($EditURI)
.el .SS \f(CW$api\fP\->getEntry($EditURI)
.IX Subsection "$api->getEntry($EditURI)"
Retrieves the entry with the given URL \fR\f(CI$EditURI\fR\fI\fR.
.PP
Returns an \fIXML::Atom::Entry\fR object.
.ie n .SS "$api\->updateEntry($EditURI, $entry)"
.el .SS "\f(CW$api\fP\->updateEntry($EditURI, \f(CW$entry\fP)"
.IX Subsection "$api->updateEntry($EditURI, $entry)"
Updates the entry at URL \fR\f(CI$EditURI\fR\fI\fR with the entry \fI\fR\f(CI$entry\fR\fI\fR, which must be
an \fIXML::Atom::Entry\fR object.
.PP
Returns true on success, false otherwise.
.ie n .SS $api\->deleteEntry($EditURI)
.el .SS \f(CW$api\fP\->deleteEntry($EditURI)
.IX Subsection "$api->deleteEntry($EditURI)"
Deletes the entry at URL \fR\f(CI$EditURI\fR\fI\fR.
.ie n .SS $api\->getFeed($FeedURI)
.el .SS \f(CW$api\fP\->getFeed($FeedURI)
.IX Subsection "$api->getFeed($FeedURI)"
Retrieves the feed at \fR\f(CI$FeedURI\fR\fI\fR.
.PP
Returns an \fIXML::Atom::Feed\fR object representing the feed returned
from the server.
.SS "ERROR HANDLING"
.IX Subsection "ERROR HANDLING"
Methods return \f(CW\*(C`undef\*(C'\fR on error, and the error message can be retrieved
using the \fIerrstr\fR method.
.SH "AUTHOR & COPYRIGHT"
.IX Header "AUTHOR & COPYRIGHT"
Please see the \fIXML::Atom\fR manpage for author, copyright, and license
information.