Changeset 497 for wiki-toolkit/trunk/lib/Wiki/Toolkit/Feed/Atom.pm

Timestamp:

02/01/09 00:06:59 (3 years ago)

Author:

dom

Message:

fix up pod and add pod testing (fixes #45)

Files:

• wiki-toolkit/trunk/lib/Wiki/Toolkit/Feed/Atom.pm (modified) (4 diffs)

wiki-toolkit/trunk/lib/Wiki/Toolkit/Feed/Atom.pm

@@ -13 +13 @@
 use Wiki::Toolkit::Feed::Listing;
 @ISA = qw( Wiki::Toolkit::Feed::Listing );
-
-sub new {
-    my $class = shift;
-    my $self  = {};
-    bless $self, $class;
-
-    my %args = @_;
-    my $wiki = $args{wiki};
-
-    unless ($wiki && UNIVERSAL::isa($wiki, 'Wiki::Toolkit')) {
-        croak 'No Wiki::Toolkit object supplied';
-    }
-  
-    $self->{wiki} = $wiki;
-  
-    # Mandatory arguments.
-    foreach my $arg (qw/site_name site_url make_node_url atom_link/) {
-        croak "No $arg supplied" unless $args{$arg};
-        $self->{$arg} = $args{$arg};
-    }
-
-    # Must-supply-one-of arguments
-    my %mustoneof = ( 'html_equiv_link' => ['html_equiv_link','recent_changes_link'] );
-    $self->handle_supply_one_of(\%mustoneof,\%args);
-  
-    # Optional arguments.
-    foreach my $arg (qw/site_description software_name software_version software_homepage encoding/) {
-        $self->{$arg} = $args{$arg} || '';
-    }
-
-    # Supply some defaults, if a blank string isn't what we want
-    unless($self->{encoding}) {
-        $self->{encoding} = $self->{wiki}->store->{_charset};
-    }
-
-    $self->{timestamp_fmt} = $Wiki::Toolkit::Store::Database::timestamp_fmt;
-    $self->{utc_offset} = strftime "%z", localtime;
-    $self->{utc_offset} =~ s/(..)(..)$/$1:$2/;
-  
-    # Escape any &'s in the urls
-    foreach my $key qw(site_url atom_link) {
-        my @ands = ($self->{$key} =~ /(\&.{1,6})/g);
-        foreach my $and (@ands) {
-            if($and ne "&") {
-                my $new_and = $and;
-                $new_and =~ s/\&/\&/;
-                $self->{$key} =~ s/$and/$new_and/;
-            }
-        }
-    }
-
-    $self;
-}
-
-=item <build_feed_start>
-
-Internal method, to build all the stuff that will go at the start of a feed.
-Outputs the feed header, and initial feed info.
-
-=cut
-
-sub build_feed_start {
-    my ($self,$atom_timestamp) = @_;
-
-    my $generator = '';
-  
-    if ($self->{software_name}) {
-        $generator  = '  <generator';
-        $generator .= ' uri="' . $self->{software_homepage} . '"'   if $self->{software_homepage};
-        $generator .= ' version=' . $self->{software_version} . '"' if $self->{software_version};
-        $generator .= ">\n";
-        $generator .= $self->{software_name} . "</generator>\n";
-    }                          
-
-    my $subtitle = $self->{site_description}
-                 ? '<subtitle>' . $self->{site_description} . "</subtitle>\n"
-                 : '';
-
-    $atom_timestamp ||= '';
-
-    my $atom = qq{<?xml version="1.0" encoding="} . $self->{encoding} . qq{"?>
-
-<feed 
- xmlns         = "http://www.w3.org/2005/Atom"
- xmlns:geo     = "http://www.w3.org/2003/01/geo/wgs84_pos#"
- xmlns:space   = "http://frot.org/space/0.1/"
->
-
-  <link href="}            . $self->{site_url}     . qq{" />
-  <title>}                 . $self->{site_name}    . qq{</title>
-  <link rel="self" href="} . $self->{atom_link}    . qq{" />
-  <updated>}               . $atom_timestamp       . qq{</updated>
-  <id>}                    . $self->{site_url}     . qq{</id>
-  $subtitle};
-  
-    return $atom;
-}
-
-=item <build_feed_end>
-
-Internal method, to build all the stuff that will go at the end of a feed.
-
-=cut
-
-sub build_feed_end {
-    my ($self,$feed_timestamp) = @_;
-
-    return "</feed>\n";
-}
-
-=item <generate_node_list_feed>
-  
-Generate and return an Atom feed for a list of nodes
-  
-=cut
-
-sub generate_node_list_feed {
-    my ($self,$atom_timestamp,@nodes) = @_;
-
-    my $atom = $self->build_feed_start($atom_timestamp);
-
-    my (@urls, @items);
-
-    foreach my $node (@nodes) {
-        my $node_name = $node->{name};
-
-        my $item_timestamp = $node->{last_modified};
-    
-        # Make a Time::Piece object.
-        my $time = Time::Piece->strptime($item_timestamp, $self->{timestamp_fmt});
-
-        my $utc_offset = $self->{utc_offset};
-    
-        $item_timestamp = $time->strftime( "%Y-%m-%dT%H:%M:%S$utc_offset" );
-
-        my $author      = $node->{metadata}{username}[0] || $node->{metadata}{host}[0] || 'Anonymous';
-        my $description = $node->{metadata}{comment}[0]  || 'No description given for node';
-
-        $description .= " [$author]" if $author;
-
-        my $version = $node->{version};
-        my $status  = (1 == $version) ? 'new' : 'updated';
-
-        my $major_change = $node->{metadata}{major_change}[0];
-        $major_change = 1 unless defined $major_change;
-        my $importance = $major_change ? 'major' : 'minor';
-
-        my $url = $self->{make_node_url}->($node_name, $version);
-
-        # make XML-clean
-        my $title =  $node_name;
-        $title =~ s/&/&amp;/g;
-        $title =~ s/</&lt;/g;
-        $title =~ s/>/&gt;/g;
-
-        # Pop the categories into atom:category elements (4.2.2)
-        # We can do this because the spec says:
-        #   "This specification assigns no meaning to the content (if any) 
-        #    of this element."
-        # TODO: Decide if we should include the "all categories listing" url
-        #        as the scheme (URI) attribute?
-        my $category_atom = "";
-        if ($node->{metadata}->{category}) {
-            foreach my $cat (@{ $node->{metadata}->{category} }) {
-                $category_atom .= "    <category term=\"$cat\" />\n";
-            }
-        }
-
-        # Include geospacial data, if we have it
-        my $geo_atom = $self->format_geo($node->{metadata});
-
-        # TODO: Find an Atom equivalent of ModWiki, so we can include more info
-
-    
-        push @items, qq{
-  <entry>
-    <title>$title</title>
-    <link href="$url" />
-    <id>$url</id>
-    <summary>$description</summary>
-    <updated>$item_timestamp</updated>
-    <author><name>$author</name></author>
-$category_atom
-$geo_atom
-  </entry>
-};
-
-    }
-  
-    $atom .= join('', @items) . "\n";
-    $atom .= $self->build_feed_end($atom_timestamp);
-
-    return $atom;   
-}
-
-=item <generate_node_name_distance_feed>
-  
-Generate a very cut down atom feed, based just on the nodes, their locations
-(if given), and their distance from a reference location (if given).
-
-Typically used on search feeds.
-  
-=cut
-
-sub generate_node_name_distance_feed {
-    my ($self,$atom_timestamp,@nodes) = @_;
-
-    my $atom = $self->build_feed_start($atom_timestamp);
-
-    my (@urls, @items);
-
-    foreach my $node (@nodes) {
-        my $node_name = $node->{name};
-
-        my $url = $self->{make_node_url}->($node_name);
-
-        # make XML-clean
-        my $title =  $node_name;
-        $title =~ s/&/&amp;/g;
-        $title =~ s/</&lt;/g;
-        $title =~ s/>/&gt;/g;
-
-        # What location stuff do we have?
-        my $geo_atom = $self->format_geo($node);
-
-        push @items, qq{
-  <entry>
-    <title>$title</title>
-    <link href="$url" />
-    <id>$url</id>
-$geo_atom
-  </entry>
-};
-
-    }
-  
-    $atom .= join('', @items) . "\n";
-    $atom .= $self->build_feed_end($atom_timestamp);
-
-    return $atom;   
-}
-
-=item B<feed_timestamp>
-
-Generate the timestamp for the Atom, based on the newest node (if available).
-Will return a timestamp for now if no node dates are available
-
-=cut
-
-sub feed_timestamp {
-    my ($self, $newest_node) = @_;
-  
-    my $time;
-    if ($newest_node->{last_modified}) {
-        $time = Time::Piece->strptime( $newest_node->{last_modified}, $self->{timestamp_fmt} );
-    } else {
-        $time = localtime;
-    }
-
-    my $utc_offset = $self->{utc_offset};
-    
-    return $time->strftime( "%Y-%m-%dT%H:%M:%S$utc_offset" );
-}
-
-
-=item B<parse_feed_timestamp>
-
-Take a feed_timestamp and return a Time::Piece object. 
-
-=cut
-
-sub parse_feed_timestamp {
-    my ($self, $feed_timestamp) = @_;
-   
-    $feed_timestamp = substr($feed_timestamp, 0, -length( $self->{utc_offset}));
-    return Time::Piece->strptime( $feed_timestamp, '%Y-%m-%dT%H:%M:%S' );
-}
-1;
-
-__END__
 
 =head1 NAME
@@ -451 +171 @@
 =back
 
+=cut
+
+sub new {
+    my $class = shift;
+    my $self  = {};
+    bless $self, $class;
+
+    my %args = @_;
+    my $wiki = $args{wiki};
+
+    unless ($wiki && UNIVERSAL::isa($wiki, 'Wiki::Toolkit')) {
+        croak 'No Wiki::Toolkit object supplied';
+    }
+  
+    $self->{wiki} = $wiki;
+  
+    # Mandatory arguments.
+    foreach my $arg (qw/site_name site_url make_node_url atom_link/) {
+        croak "No $arg supplied" unless $args{$arg};
+        $self->{$arg} = $args{$arg};
+    }
+
+    # Must-supply-one-of arguments
+    my %mustoneof = ( 'html_equiv_link' => ['html_equiv_link','recent_changes_link'] );
+    $self->handle_supply_one_of(\%mustoneof,\%args);
+  
+    # Optional arguments.
+    foreach my $arg (qw/site_description software_name software_version software_homepage encoding/) {
+        $self->{$arg} = $args{$arg} || '';
+    }
+
+    # Supply some defaults, if a blank string isn't what we want
+    unless($self->{encoding}) {
+        $self->{encoding} = $self->{wiki}->store->{_charset};
+    }
+
+    $self->{timestamp_fmt} = $Wiki::Toolkit::Store::Database::timestamp_fmt;
+    $self->{utc_offset} = strftime "%z", localtime;
+    $self->{utc_offset} =~ s/(..)(..)$/$1:$2/;
+  
+    # Escape any &'s in the urls
+    foreach my $key qw(site_url atom_link) {
+        my @ands = ($self->{$key} =~ /(\&.{1,6})/g);
+        foreach my $and (@ands) {
+            if($and ne "&amp;") {
+                my $new_and = $and;
+                $new_and =~ s/\&/\&amp;/;
+                $self->{$key} =~ s/$and/$new_and/;
+            }
+        }
+    }
+
+    $self;
+}
+
+# Internal method, to build all the stuff that will go at the start of a feed.
+# Outputs the feed header, and initial feed info.
+
+sub build_feed_start {
+    my ($self,$atom_timestamp) = @_;
+
+    my $generator = '';
+  
+    if ($self->{software_name}) {
+        $generator  = '  <generator';
+        $generator .= ' uri="' . $self->{software_homepage} . '"'   if $self->{software_homepage};
+        $generator .= ' version=' . $self->{software_version} . '"' if $self->{software_version};
+        $generator .= ">\n";
+        $generator .= $self->{software_name} . "</generator>\n";
+    }                          
+
+    my $subtitle = $self->{site_description}
+                 ? '<subtitle>' . $self->{site_description} . "</subtitle>\n"
+                 : '';
+
+    $atom_timestamp ||= '';
+
+    my $atom = qq{<?xml version="1.0" encoding="} . $self->{encoding} . qq{"?>
+
+<feed 
+ xmlns         = "http://www.w3.org/2005/Atom"
+ xmlns:geo     = "http://www.w3.org/2003/01/geo/wgs84_pos#"
+ xmlns:space   = "http://frot.org/space/0.1/"
+>
+
+  <link href="}            . $self->{site_url}     . qq{" />
+  <title>}                 . $self->{site_name}    . qq{</title>
+  <link rel="self" href="} . $self->{atom_link}    . qq{" />
+  <updated>}               . $atom_timestamp       . qq{</updated>
+  <id>}                    . $self->{site_url}     . qq{</id>
+  $subtitle};
+  
+    return $atom;
+}
+
+# Internal method, to build all the stuff that will go at the end of a feed.
+
+sub build_feed_end {
+    my ($self,$feed_timestamp) = @_;
+
+    return "</feed>\n";
+}
+
+=head2 C<generate_node_list_feed>
+  
+Generate and return an Atom feed for a list of nodes
+  
+=cut
+
+sub generate_node_list_feed {
+    my ($self,$atom_timestamp,@nodes) = @_;
+
+    my $atom = $self->build_feed_start($atom_timestamp);
+
+    my (@urls, @items);
+
+    foreach my $node (@nodes) {
+        my $node_name = $node->{name};
+
+        my $item_timestamp = $node->{last_modified};
+    
+        # Make a Time::Piece object.
+        my $time = Time::Piece->strptime($item_timestamp, $self->{timestamp_fmt});
+
+        my $utc_offset = $self->{utc_offset};
+    
+        $item_timestamp = $time->strftime( "%Y-%m-%dT%H:%M:%S$utc_offset" );
+
+        my $author      = $node->{metadata}{username}[0] || $node->{metadata}{host}[0] || 'Anonymous';
+        my $description = $node->{metadata}{comment}[0]  || 'No description given for node';
+
+        $description .= " [$author]" if $author;
+
+        my $version = $node->{version};
+        my $status  = (1 == $version) ? 'new' : 'updated';
+
+        my $major_change = $node->{metadata}{major_change}[0];
+        $major_change = 1 unless defined $major_change;
+        my $importance = $major_change ? 'major' : 'minor';
+
+        my $url = $self->{make_node_url}->($node_name, $version);
+
+        # make XML-clean
+        my $title =  $node_name;
+        $title =~ s/&/&amp;/g;
+        $title =~ s/</&lt;/g;
+        $title =~ s/>/&gt;/g;
+
+        # Pop the categories into atom:category elements (4.2.2)
+        # We can do this because the spec says:
+        #   "This specification assigns no meaning to the content (if any) 
+        #    of this element."
+        # TODO: Decide if we should include the "all categories listing" url
+        #        as the scheme (URI) attribute?
+        my $category_atom = "";
+        if ($node->{metadata}->{category}) {
+            foreach my $cat (@{ $node->{metadata}->{category} }) {
+                $category_atom .= "    <category term=\"$cat\" />\n";
+            }
+        }
+
+        # Include geospacial data, if we have it
+        my $geo_atom = $self->format_geo($node->{metadata});
+
+        # TODO: Find an Atom equivalent of ModWiki, so we can include more info
+
+    
+        push @items, qq{
+  <entry>
+    <title>$title</title>
+    <link href="$url" />
+    <id>$url</id>
+    <summary>$description</summary>
+    <updated>$item_timestamp</updated>
+    <author><name>$author</name></author>
+$category_atom
+$geo_atom
+  </entry>
+};
+
+    }
+  
+    $atom .= join('', @items) . "\n";
+    $atom .= $self->build_feed_end($atom_timestamp);
+
+    return $atom;   
+}
+
+=head2 C<generate_node_name_distance_feed>
+  
+Generate a very cut down atom feed, based just on the nodes, their locations
+(if given), and their distance from a reference location (if given).
+
+Typically used on search feeds.
+  
+=cut
+
+sub generate_node_name_distance_feed {
+    my ($self,$atom_timestamp,@nodes) = @_;
+
+    my $atom = $self->build_feed_start($atom_timestamp);
+
+    my (@urls, @items);
+
+    foreach my $node (@nodes) {
+        my $node_name = $node->{name};
+
+        my $url = $self->{make_node_url}->($node_name);
+
+        # make XML-clean
+        my $title =  $node_name;
+        $title =~ s/&/&amp;/g;
+        $title =~ s/</&lt;/g;
+        $title =~ s/>/&gt;/g;
+
+        # What location stuff do we have?
+        my $geo_atom = $self->format_geo($node);
+
+        push @items, qq{
+  <entry>
+    <title>$title</title>
+    <link href="$url" />
+    <id>$url</id>
+$geo_atom
+  </entry>
+};
+
+    }
+  
+    $atom .= join('', @items) . "\n";
+    $atom .= $self->build_feed_end($atom_timestamp);
+
+    return $atom;   
+}
+
 =head2 C<feed_timestamp()>
 
@@ -460 +415 @@
 need this to print a Last-Modified HTTP header so user-agents can determine
 whether they need to reload the feed or not.
-  
+
+=cut
+
+sub feed_timestamp {
+    my ($self, $newest_node) = @_;
+  
+    my $time;
+    if ($newest_node->{last_modified}) {
+        $time = Time::Piece->strptime( $newest_node->{last_modified}, $self->{timestamp_fmt} );
+    } else {
+        $time = localtime;
+    }
+
+    my $utc_offset = $self->{utc_offset};
+    
+    return $time->strftime( "%Y-%m-%dT%H:%M:%S$utc_offset" );
+}
+
+
+=head2 C<parse_feed_timestamp>
+
+Take a feed_timestamp and return a Time::Piece object. 
+
+=cut
+
+sub parse_feed_timestamp {
+    my ($self, $feed_timestamp) = @_;
+   
+    $feed_timestamp = substr($feed_timestamp, 0, -length( $self->{utc_offset}));
+    return Time::Piece->strptime( $feed_timestamp, '%Y-%m-%dT%H:%M:%S' );
+}
+1;
+
+__END__
+
+
 =head1 SEE ALSO
 
@@ -477 +467 @@
 =head1 COPYRIGHT AND LICENSE
 
-Copyright 2006-2008 Earle Martin and the Wiki::Toolkit team.
+Copyright 2006-2009 Earle Martin and the Wiki::Toolkit team.
 
 This module is free software; you can redistribute it and/or modify it