NAME

Blog::BlogML::Reader - Read data from a BlogML formatted XML document.

SYNOPSIS

use Blog::BlogML::Reader;
Blog::BlogML::Reader::parse_blog("this_blog.xml");

# OR

use Blog::BlogML::Reader qw(:all);
parse_blog("that_blog.xml");
my $posts = find_latest(10);

DESCRIPTION

BlogML is a standard for XML to define and store an entire blog. This module allows you to easily read most data in a given BlogML file.

DEPENDENCIES

• XML::Parser::Expat

  This module uses XML::Parser::Expat to parse the XML in the BlogML source file. I chose an expat based parser primarily for its speed. Check the docs for XML::Parser::Expat for further dependencies.

• HTTP::Date

  This module uses HTTP::Date to transform date strings into sortable timestamps. Neccessary when, for example, sorting blog posts and retrieving the most recent.

EXPORT

None by default.

INTERFACE

Any or all of the following subroutines can be imported into the using script's namespace (or you may use the full package name to access them if you prefer). Specifying ":all" on the use line will include all of them into your script's namespace. Note that, for efficiency reasons, this module does not use an object-oriented interface, so the items listed below are not methods of any instance, just simple subroutines.

• parse_blog("/path/to/blog.xml");

  Call this first. This will build a data structure in memory, which can then be more conveniently accessed through the remaining subroutines. Calling this more than once is useless as the XML file will only be parsed once. The single argument is required, and must specify the filepath to a readable XML file that complies with the BlogML format.

• meta($meta_key);

  If your BlogML document includes information about the blog it can be accessed via the hashref returned by this subroutine. If you only want a specific field you can specify it as an optional argument.

  my $meta = meta();
  print $meta->{title};
  print $meta->{subtitle};
  print $meta->{author_name};
  print $meta->{author_email};
  print $meta->{root_url};
  print $meta->{cats}{personal}{parent-ref};
  
  # OR
  
  my $title = meta('title');
  my $cats = meta('cats');
  print $cats->{news}{date-created};

• find_latest($limit);

  This returns an array reference of posts from the blog, sorted most recent first. You may optionally pass along a limit (integer) to specify the maximum number of posts you want.

  my $latest_posts = find_latest(10);
  foreach my $post (@$latest_posts) {
  	print $post->{title};
  }

• find_by_cat($cat_id);

  Given a required category ID, this will return an array reference to every post that is associated with that category.

  my $reviews = find_by_cat('review');
  foreach my $post (@$reviews) {
  	print $post->{title};
  }

• post($post_id);

  If you already know the ID of the post you want, use this subroutine, which returns a hash reference to only that post;

  my $post = post(309);
  print $post->{title}, $post->{content};

EXAMPLE

use Blog::BlogML::Reader qw(:all);
use Date::Format;
parse_blog("/blogs/my_blog.xml");

# get the latest posts
my $posts = find_latest(12);

foreach my $post (@$posts) {
	print "<h1>", $post->{title}, "</h1>";
	# You can use Date::Format to make a nicely formatted date string
	print "posted on: ", time2str("%o of %B %Y", $post->{time}), "<br>";
	print "<div>", $post->{content}, "</div>";
	
	# the categories associated with this post
	my $cat_listing = join(", ",  map{$_->{title}} @{$post->{catrefs}});
	$cat_listing and print "Filed under: $cat_listing";
}

SEE ALSO

The website http://BlogML.com has the latest documentation on the BlogML standard. Note that the reference document "example.xml" included with this module illustrates the expected format.

AUTHOR

Michael Mathews, <mmathews@cpan.org>

COPYRIGHT AND LICENSE

Copyright (C) 2006 by Michael Mathews

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.6 or, at your option, any later version of Perl 5 you may have available.