Provided by: libxml-opml-perl_0.26-2_all bug

NAME

       XML::OPML - creates and updates OPML (Outline Processor Markup Language) files

SYNOPSIS

       # Create an OPML file

        use XML::OPML;

        my $opml = new XML::OPML(version => "1.1");

        $opml->head(
                    title => 'mySubscription',
                    dateCreated => 'Mon, 16 Feb 2004 11:35:00 GMT',
                    dateModified => 'Sat, 05 Mar 2004 09:02:00 GMT',
                    ownerName => 'michael szul',
                    ownerEmail => 'opml-dev@blogenstein.com',
                    expansionState => '',
                    vertScrollState => '',
                    windowTop => '',
                    windowLeft => '',
                    windowBottom => '',
                    windowRight => '',
                  );

        $opml->add_outline(
                        text => 'Warren Ellis Speaks Clever',
                        description => 'Warren Ellis\' Personal Weblog',
                        title => 'Warren Ellis Speaks Clever',
                        type => 'rss',
                        version => 'RSS',
                        htmlUrl => 'http://www.diepunyhumans.com ',
                        xmlUrl => 'http://www.diepunyhumans.com/index.rdf ',
                      );

        $opml->add_outline(
                        text => 'raelity bytes',
                        descriptions => 'The raelity bytes weblog.',
                        title => 'raelity bytes',
                        type => 'rss',
                        version => 'RSS',
                        htmlUrl => 'http://www.raelity.org ',
                        xmlUrl => 'http://www.raelity.org/index.rss10 ',
                      );

       # Create embedded outlines

        $opml->add_outline(
                            opmlvalue => 'embed',
                            outline_one => {
                                             text => 'The first embedded outline',
                                             description => 'The description for the first embedded outline',
                                           },
                            outline_two => {
                                             text => 'The second embedded outline',
                                             description => 'The description for the second embedded outline',
                                           },
                            outline_three => {
                                               opmlvalue => 'embed',
                                               em_outline_one => {
                                                                   text => 'I'm too lazy to come up with real examples',
                                                                 },
                                               em_outline_two => {
                                                                   text => 'so you get generic text',
                                                                 },
                                             },
                          );

       # Create an embedded outline with attributes in the encasing <outline> tag

        $opml->add_outline(
                            opmlvalue => 'embed',
                            description => 'now we can have attributes in this tag',
                            title => 'attributes',
                            outline_with_atts => {
                                                   text => 'Eat Your Wheaties',
                                                   description => 'Cereal is the breakfast of champion programmers',
                                                 },
                          );

       # Save it as a string.

        $opml->as_string();

       # Save it to a file.

        $opml->save('mySubscriptions.opml');

       # Update your OPML file.

        use XML::OPML;

        my $opml = new XML::OPML;

       # Parse the file.

        $opml->parse('mySubscriptions.opml');

       # Or optionally from a variable.

        my $content = $opml->as_string();
        $opml->parse($content);

       # Update it appending to the end of the outline

        $opml->add_outline(
                           text => 'Neil Gaiman\'s Journal',
                           description =>'Neil Gaiman\'s Journal',
                           title => 'Neil Gaiman\'s Journal',
                           type => 'rss',
                           version => 'RSS',
                           htmlUrl => 'http://www.neilgaiman.com/journal/journal.asp ',
                           xmlUrl => 'http://www.neilgaiman.com/journal/blogger_rss.xml ',
                         );

       # Update it inserting the outline into a specific group (note the group parameter)

        $opml->insert_outline(
                              group => 'occult',
                              text => 'madghoul.com',
                              description => 'the dark night of the soul',
                              title => 'madghoul.com',
                              type => 'rss',
                              version => 'RSS',
                              htmlUrl => 'http://www.madghoul.com ',
                              xmlUrl => 'http://www.madghoul.com/cgi-bin/fearsome/fallout/index.rss10 ',
                             );

DESCRIPTION

       This experimental module is designed to allow for easy creation and manipulation of OPML
       files. OPML files are most commonly used for the sharing of blogrolls or subscriptions -
       an outlined list of what other blogs an Internet blogger reads. RSS Feed Readers such as
       AmphetaDesk ( http://www.disobey.com/amphetadesk ) use *.opml files to store your
       subscription information for easy access.

       This is purely experimental at this point and has a few limitations. This module may now
       support attributes in the <outline> element of an embedded hierarchy, but these are
       limited to the following attributes: date_added, date_downloaded, description, email,
       filename, htmlurl, keywords, text, title, type, version, and xmlurl. Additionally, the
       following alternate spellings are also supported: dateAdded, dateDownloaded, htmlUrl, and
       xmlUrl.

       Rather than reinvent the wheel, this module was modified from the XML::RSS module, so
       functionality works in a similar way.

METHODS

       new XML::OPML(version => '1.1')
           This is the constructor. It returns a reference to an XML::OPML object. This will
           always be version 1.1 for now, so don't worry about it.

       head(title => '$title', dateCreated => '$cdate', dateModified => '$mdate',ownerName =>
       '$name', ownerEmail => '$email', expansionState => '$es', vertScrollState => '$vs',
       windowTop => '$wt', windowLeft => '$wl', windowBottom => '$wb',windowRight => '$wr',)
           This method will create all the OPML tags for the <head> subset. For more information
           on these tags, please see the OPML documentation at http://www.opml.org .

       add_outline(opmlvalue => '$value', %attributes)
           This method adds the <outline> elements to the OPML document(see the example above).
           There are no statement requirements for the attributes in this tag. The ones shown in
           the example are the ones most commonly used by RSS Feed Readers, blogrolls, and
           subscriptions. The opmlvalue element is optional. Only use this with the value 'embed'
           if you wish to embed another outline within the current outline. You can now use
           attributes in <outline> tags that are used for embedded outlines, however, you cannot
           use any attribute you want. The embedded <outline> tag only supports the following:
           date_added, date_downloaded, description, email, filename, htmlurl, keywords, text,
           title, type, version, and xmlurl, as well as the alternate spellings: dateAdded,
           dateDownloaded, htmlUrl, and xmlUrl.

       insert_outline(group => '$group', %attributes)
           This method works in the same exact manner as add_outline() except that this will
           insert the outline element into the specified group. The $group variable must be the
           text presented in the "text" attribute of the outline that you wish to insert this one
           into. For example, if you have an outline element with the text attribute of "occult"
           that contains four outline subelements of occult web sites, your group parameter would
           be "occult."

       as_string()
           Returns a string containing the OPML document.

       save($file)
           Saves the OPML document to $file

       parse($content)
           Uses XML::Parser and XML::SimpleObject to parse the value of the string or file that
           is passed to it. This method prepares your OPML file for a possible update. Embedded
           outlines are supported.

SOURCE AVAILABILITY

       Source code is available at the development site at http://opml.blogenstein.com . Any
       contributions or improvements are greatly appreciated. You may also want to visit
       http://www.madghoul.com to see a whole lot of perl coding at work.

AUTHOR

        michael szul <opml-dev@blogenstein.com>

COPYRIGHT

       copyright (c) 2004 michael szul <opml-dev@blogenstein.com>

       XML::OPML is free software. It may be redistributed and/or modified under the same terms
       as Perl.

CREDITS

        michael szul <opml-dev@blogenstein.com>
        matt cashner <sungo@eekeek.org>
        ricardo signes <rjbs@cpan.org>
        gergely nagy <algernon@bonehunter.rulez.org>

SEE ALSO

       perl(1), XML::Parser(3), XML::SimpleObject(3), XML::RSS(3).