Initial versions of metaclear and metamail.
authorGavin Carr <gonzai@users.sourceforge.net>
Fri, 28 Sep 2007 11:48:33 +0000 (11:48 +0000)
committerGavin Carr <gonzai@users.sourceforge.net>
Fri, 28 Sep 2007 11:48:33 +0000 (11:48 +0000)
gavinc/metaclear [new file with mode: 0644]
gavinc/metamail [new file with mode: 0644]

diff --git a/gavinc/metaclear b/gavinc/metaclear
new file mode 100644 (file)
index 0000000..1e2ba2e
--- /dev/null
@@ -0,0 +1,83 @@
+# Blosxom Plugin: metamail
+# Author(s): Gavin Carr <gavin@openfusion.com.au>
+# Version: 0.001001
+# Documentation: 'perldoc metaclear'
+
+package metaclear;
+
+use strict;
+
+# --- Configurable variables -----
+
+# None
+
+# --------------------------------
+
+sub start { 1 };
+
+sub story {
+  %blosxom::meta = ();
+  return 1;
+}
+
+1;
+
+__END__
+
+=head1 NAME
+
+metaclear - clear/reset the %blosxom::meta hash at the start of a story
+
+=head1 DESCRIPTION
+
+metaclear is a plugin to clear/reset the %blosxom::meta hash at the start
+of a story. It should be used with any of the new-style meta plugins like 
+L<metamail>, L<metadir>, L<metafile>, etc., and must be called B<BEFORE> 
+any of those.
+
+=head1 USAGE
+
+Should be loaded early, before all other meta plugins e.g. as 01metaclear. 
+
+=head1 SEE ALSO
+
+L<metamail>, L<metadir>, L<metafile>
+
+Blosxom: http://blosxom.sourceforge.net/
+
+=head1 BUGS
+
+Messing with variables in other packages is evil. This should really use 
+some kind of Blosxom::Meta API instead.
+
+=head1 AUTHOR
+
+Gavin Carr <gavin@openfusion.com.au>, http://www.openfusion.net/
+
+=head1 LICENSE
+
+Copyright 2007, Gavin Carr.
+
+This plugin is licensed under the same terms as blosxom itself i.e.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+=cut
+
+# vim:ft=perl
diff --git a/gavinc/metamail b/gavinc/metamail
new file mode 100644 (file)
index 0000000..29da361
--- /dev/null
@@ -0,0 +1,179 @@
+# Blosxom Plugin: metamail
+# Author(s): Gavin Carr <gavin@openfusion.com.au>
+# Version: 0.001000
+# Documentation: 'perldoc metamail'
+# Requires: metaclear
+# Follows: metaclear
+
+package metamail;
+
+use strict;
+
+#use Blosxom::Debug debug_level => 1;
+
+# --- Configurable variables -----
+
+# Headers to consider titles
+my @title_headers = qw(Title Subject);
+
+# Headers to keep in the body (required by later plugins, for instance)
+my @keep_in_body_headers = qw(Tags);
+
+# Whether to unfold (join) multi-line headers
+my $unfold_headers = 1;
+
+# --------------------------------
+
+sub start { 1 };
+
+sub story {
+  my($pkg, $path, $filename, $story_ref, $title_ref, $body_ref) = @_;
+
+  my %header = ();
+  my ($headers, $body) = split /\n\s*\n/, $$title_ref . "\n" . $$body_ref, 2;
+
+  my $meta = \%blosxom::meta;
+
+  # Walk the headers
+  for my $header ( split /\n(?=\S)/, $headers ) {
+    # Split header into key/value
+    my ($key, $key2, $value);
+    if ($header =~ m/:/) {
+      ($key, $value) = split /:\s*/, $header, 2;  
+    }
+    # For backwards compatibility, assume a header without a : is a title
+    else {
+      $key = @title_headers[0] || 'Title';
+      $value = $header;
+    }
+    chomp $value;
+    
+    # Unfold
+    $value =~ s/\n //g if $unfold_headers;
+
+    # Cache header
+    $header{$key} = $value;
+
+    # Insert into meta namespace
+    $meta->{$key} = $value;
+    # debug(1, "metamail: $key: " . $meta->{$key} . "\n");
+    # Insert lowercase/underscored version as well
+    ($key2 = lc $key) =~ s/-/_/g;
+    if ($key ne $key2) {
+      $meta->{$key2} = $value;
+      # debug(1, "metamail: $key2: " . $meta->{$key2} . "\n");
+    }
+  }
+
+  # Update $$title_ref to the first title_header we can find
+  $$title_ref = '';
+  for (@title_headers) {
+    $$title_ref = $header{$_} and last if $header{$_};
+  }
+
+  # Update body_ref
+  if (my @keep_headers = grep { defined $header{$_} } @keep_in_body_headers) {
+    $$body_ref = join("\n", map { "$_: $header{$_}" } @keep_headers) . "\n" . $body;
+  }
+  else {
+    $$body_ref = $body;
+  }
+
+  return 1;
+}
+
+1;
+
+__END__
+
+=head1 NAME
+
+metamail - an alternative to Rael's original L<meta> plugin, supporting
+mail/RFC822-style headers in posts
+
+=head1 DESCRIPTION
+
+metamail is a plugin for loading metadata from the 'headers' in a 
+blosxom post. Metadata is loaded into a %blosxom::meta hash (instead of
+into package variables like L<meta>). metamail expects posts to look like 
+RFC822-style mails i.e. a bunch of headers, where a header is a key (no 
+whitespace) followed by a colon followed by a value; then an empty line 
+as a separator; and then the post body.
+
+metamail loads all headers it finds as variables into the %blosxom::meta
+hash. It typically creates two entries for each header: the first is named 
+exactly as the key is given in the header, and the second is the key 
+converted to lowercase, and with dashes converted to underscores.
+
+So given the following headers:
+
+    Title: Test Post 1
+    Tags: test, ignore
+    URL: http://www.openfusion.net/
+
+metamail will create the following %blosxom::meta entries:
+   
+    $blosxom::meta{Title} = 'Test Post 1';
+    $blosxom::meta{title} = 'Test Post 1';
+    $blosxom::meta{Tags} = 'test, ignore';
+    $blosxom::meta{tags} = 'test, ignore';
+    $blosxom::meta{URL} = 'http://www.openfusion.net/';
+    $blosxom::meta{url} = 'http://www.openfusion.net/';
+
+For backwards compatibility purposes, L<metamail> will treat any header
+not containing a colon (which is typically the first line title) as the 
+'Title' of the post, and store it with the first key in @title_headers
+(default is 'Title'). L<metamail> supports the title being anywhere in 
+the headers, and will report it properly to blosxom, but any plugins 
+that look directly at the post file may still expect the title 
+(without a key) to be there in the first line, so that is currently
+still the recommended convention.
+
+=head1 USAGE
+
+This plugin requires the L<metaclear> plugin to reset the %blosxom::meta
+hash for each story, and should be loaded early, after L<metaclear>, but
+typically before all other story plugins e.g. as 05metamail. 
+
+This is an *alternative* to the L<meta> plugin, so should usually be used 
+_instead_ of L<meta>, not as well.
+
+=head1 SEE ALSO
+
+L<metaclear>, L<metadir>, L<metafile>.
+
+L<meta>, Rael Dornfest's original metadata plugin
+
+Blosxom: http://blosxom.sourceforge.net/
+
+=head1 AUTHOR
+
+Gavin Carr <gavin@openfusion.com.au>, http://www.openfusion.net/
+
+=head1 LICENSE
+
+Copyright 2007, Gavin Carr.
+
+This plugin is licensed under the same terms as blosxom itself i.e.
+
+Permission is hereby granted, free of charge, to any person obtaining a
+copy of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+=cut
+
+# vim:ft=perl