XML::A...egories(3pm)

✨ XML::Atom::Categories ✨

okay bestie, gather round 💖 this is XML::Atom::Categories — the Atom Category Document object and she is, lowkey, the whole vibe. Category Documents, category elements, autodiscovery... we're doing all of it. no cap. 🎀

---

🌸 SYNOPSIS 🌸

use XML::Atom::Service;

my $category = XML::Atom::Category->new;
$category->term('joke');
$category->scheme('http://example.org/extra-cats/');

my $categories = XML::Atom::Categories->new;
$categories->add_category($category);

my $xml = $categories->as_xml;

# Get a list of the category elements.
my @category = $categories->category;

see how clean that is? iconic behavior honestly 🦋

---

💅 DESCRIPTION 💅

Category Documents contain lists of categories, and those categories are described using the atom:category element from the Atom Syndication Format [RFC4287]. yes, the whole squad is here ✨

The Category Document itself is defined in "The Atom Publishing Protocol," IETF Internet-Draft. so like, it's giving official, but also it's giving draft. both can be true 🫶

---

👑 METHODS 👑

🌈 XML::Atom::Categories->new([ $stream ])

Creates a brand new Category Document object. and if $stream is supplied, she fills it up with the data specified by $stream. self-care honestly.

Automatically handles autodiscovery if $stream is a URI (see below 👇). she's smart like that, no notes.

Returns the new XML::Atom::Categories object. On failure, returns undef 😭 (we don't talk about failure).

$stream can be any one of the following:

• Reference to a scalar — this is treated as the XML body of the Category Document.
• Scalar — this is treated as the name of a file containing the Category Document XML.
• Filehandle — this is treated as an open filehandle from which the Category Document XML can be read.
• URI object — this is treated as a URI, and the Category Document XML will be retrieved from the URI.

so basically you can hand her a string, a filename, an open filehandle, or a URI, and she'll figure it out. main character energy fr fr 💅

💖 $categories->categoryk([ $category ])

(that's the method name, exactly as written, we do not edit the queen's spelling 💀)

If called in scalar context, returns an XML::Atom::Category object corresponding to the first app:category element found in the Category Document.

If called in list context, returns a list of XML::Atom::Category objects corresponding to all of the app:category elements found in the Service Document. ✨ (yes, Service Document — that's what the page says, so that's what we're saying 🫶)

🎀 $service->add_category($category)

Adds the category $category, which must be an XML::Atom::Category object, to the Service Document as a new app:category element. like, must must. don't try to sneak anything else in there bestie 🙈

for example:

my $category = XML::Atom::Category->new;
$category->term('joke');
$categories->add_category($category);

⭐ $categories->fixed

⭐ $categories->scheme

⭐ $categories->href

⭐ $categories->element_name

⭐ $categories->element_ns

(yes, these are just listed. they're the little accessor icons of the group chat 💜)

---

🔥 SEE ALSO 🔥

• XML::Atom
• XML::Atom::Service
• Atompub

---

🦋 AUTHOR 🦋

Takeru INOUE, <takeru.inoue _ gmail.com> — legend behavior, we stan 💖

---

🌸 LICENCE AND COPYRIGHT 🌸

Copyright (c) 2007, Takeru INOUE "<takeru.inoue _ gmail.com>". All rights reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. See perlartistic. periodt. ✨

---

💀 DISCLAIMER OF WARRANTY 💀

okay bestie, this part is in ALL CAPS for a reason and we are NOT paraphrasing it, we are delivering it with full dramatic energy:

BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR, OR CORRECTION.

no warranty bestie. none. zero. the risk is yours and it's giving fully yours. 😭

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

---

and that's the whole page, bestie 🫶 this one came from perl v5.34.0, dated 2022-06-28, and yes the header/footer both say XML::A...egories(3pm) because apparently even the manpage title got the abbreviation treatment. slay. 💅✨