# Blosxom3 Plugin: blox.pm
# Author(s): Stu MacKenzie <http://groups.yahoo.com/group/blosxom/messages>
# Version: 2004-05-30 (v3.0a)
# blox docs/: http://www.enilnomi.net/download.html
# More notes at the bottom of this file or type: perldoc blox

package Blosxom::Plugin::blox;

# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #
#
#  Configuration Section
#
# # # # # # # # # # # # # # # # #
#
#  Open and Close tags --
#   The text you enter between the single quote marks for open_p_tag 
#   and close_p_tag becomes the exact html inserted before and after 
#   each untagged block of text in your entry file. You could use 
#   '<blockquote>' and '</blockquote>', or '<li>' and '</li>', or 
#   even '<hr><p class="glitzy">' and '<img src="fini.gif"></p>', 
#   or whatever you like. Default here is '<p>' and '</p>'
 my $open_p_tag = '<p>';
 my $close_p_tag = '</p>';
#
#  Adding initial and final tags --
#   Perhaps your flavour templates specify a tag for the beginning or end 
#   of your entry; if so, you can stop blox from adding either tag by 
#   putting 0 [zero] into add_initial_open_tag and/or add_final_close_tag
#
#   Should blox do anything to the start of the very first block?
#   0 = no; 1 = yes
 my $add_initial_open_tag = 1;
#
#   Should blox do anything to the end of the very last block?
#   0 = no; 1 = yes
 my $add_final_close_tag = 1;
#
# # # # # # # # # # # # # # # # #
#  Using a noblox file to ignore certain files --
#   For some pre-formatted entry files, blox may just get in the way; 
#   for those cases, you can make blox skip over particular files. You 
#   can always set the first line of a story to "<!--noblox-->", and 
#   blox will skip that file. You can also enter paths in a file named 
#   "noblox" in Blosxom 3's "state" directory, and tell blox to skip 
#   over the directories and files listed there.
#   Format is: (note -- no leading "/")
#   directory/
#   directory/file.ext
#
#   Should blox take the time to read a list of files to skip over?
#   0 = no; 1 = yes
  my $use_noblox_file = 1;
#
#   What's the complete path to the noblox file?
#   (default is "$self->{settings}->{state_dir}/noblox";
#    you p'bly don't want to change that)
  ##my $noblox_file_path = "$self->{settings}->{state_dir}/noblox";
##  $noblox_path = "$self->{settings}->{state_dir}/noblox";
##  warn $noblox_path;
#
# # # # # # # # # # # # # # # # # # # # # # # # # # # # # # # #

sub noblox_filter {
 my $self = shift;
  !$use_noblox_file and return 0;        # is this trip necessary?

# read the list of dirs/files to skip into an array, or bail:
  my $noblox_file_path = "$self->{settings}->{state_dir}/noblox";
  my @skips = ();                        # read the whole file into a string;
  open(NOBLOX, "< $noblox_file_path") or 1; my $str = join '', <NOBLOX>; close(NOBLOX);
  $str =~ s/(\r\n)|(\r)/\n/gm;           # make it proper lines;
  %blox_skip_files = ();                 # create a hash of targeted files from the array
  foreach (split /\n/, $str) {
    my $skip = "$self->{settings}->{find_entries_dir}/$_" if $_;
    foreach (keys %{$self->{entries}}) {
      $_ !~ m/^$skip/ or $blox_skip_files{$_}=1;
    }
  }

  1;
}


sub run {
  my $self = shift;
# get refs to the data (instead of typing these bloody long var names ;-)
  my $title_ref = \$self->{state}->{current_entry}->{title};
  my $body_ref = \$self->{state}->{current_entry}->{body};

# Blosxom expects \n line endings (ascii 10), but macs might 
# use \r (ascii 13), and windows might use \r\n (ascii 13,10); 
# Macs will have the entire story in $title; Wins will leave 
# a trailing \r in $title.
  if ($$title_ref =~ m/\r/) {
    $$title_ref =~ s/\r/\n/;              # convert first return to newline
    my $temp;                             # re-populate the two vars
    ($$title_ref,$temp) = split /\n/, $$title_ref, 2;
    $$body_ref = $temp . $$body_ref;
  }

  if ($$body_ref =~ m/\r/) {
# convert leading line-ends to double newline
    $$body_ref =~ s/^\r\n/\n\n/ or $$body_ref =~ s/^\r/\n\n/;
# convert any winlines in $body to newlines
    $$body_ref =~ s/\r\n/\n/gm;
# convert any maclines in $body to newlines
    $$body_ref =~ s/\r/\n/gm;
  }

# 2 chances to skip this file:
  $$body_ref !~ s/^<!--\s*noblox\s*-->\n// or return 0;
  if ($use_noblox_file) {
    !$blox_skip_files{"$self->{state}->{current_entry}->{id}"} or return 0;
  }

# remove leading and trailing blank lines; 
# remember that it happened
  my $have_starting_blanklines = $$body_ref =~ s/^\n+//s;
  my $have_ending_blanklines = $$body_ref =~ s/\n+$//s;

# change all \n{2,} to \n\n, since \n{2,} doesn't work well 
# in the lines below (phantom tags show up)
  $$body_ref =~ s/\n{2,}/\n\n/gm;

# change untagged start-of-blocks (except start of first block)
  $$body_ref =~ s/\n\n(?:(?!\<))/\n\n$open_p_tag\n/gm;

# change all untagged end-of-blocks (except end of last block)
  $$body_ref =~ s/(?:(?<!\>))\n\n/\n$close_p_tag\n\n/gm;

# change the first start-of-block if permission and untagged
  ($add_initial_open_tag) && ($$body_ref =~ s/^(?:(?!<))/$open_p_tag\n/s);

# change the last end-of-block if permission and untagged
  ($add_final_close_tag) && ($$body_ref =~ s/(?:(?<!>))$/\n$close_p_tag/s);

# restore leading/trailing blank line...
  ($have_starting_blanklines) && ($$body_ref =~ s/^/\n/);
  ($have_ending_blanklines) && ($$body_ref =~ s/$/\n/);

# strip lone leading and trailing next-to spaces
# (strip consecutive spaces with: s/($open_p_tag\n) +?(<)/$1$2/gm;)
  $$body_ref =~ s/($open_p_tag\n) (<)/$1$2/gm;
  $$body_ref =~ s/(>) (\n$close_p_tag)/$1$2/gm;
  
 1;
}

1;

__END__

=head1 NAME

Blosxom3 Plug-in: blox -- adds html block tags around "paragraphs" from plain entry file text


=head1 SYNOPSIS

Use blox to add pre-selected "paragraph" tags to plain text entry files. If blox sees one or more blank lines and no starting or ending tags, it adds appropriate markup to the text flow. Existing tags are left alone. Sloppy pre-existing markup or blank lines in <PRE> tags may add "phantom" paragraph tags to Blosxom's output; such files can be ignored in two ways. Text files can use Unix, Mac, or Windows line-ends.


=head1 DESCRIPTION

The blox plugin makes it easier to produce entry files, by removing the need to wrap "paragraphs" of entry text in html tags like "<p>" and "</p>" while typing. (Or "blockquote>" and "</blockquote>", or "<li>" and "</li>", or whatever.) Simply type regular text into your entry files, separating "paragraphs" by at least one blank line (completely blank: no spaces, tabs, etc.) -- blox will add open- and close-tags to each block of text. Existing tags will be left alone. 

If you need to put your own tag at the start or end of a block (such as <b> or <img>), pad it with a single space and blox will still add an open- or close-block tag. 

Some existing files, or new pages that use <PRE> tags, may not benefit from blox. In those cases, there are two ways to have blox skip over a file:
1) set the first line of the story to "<!--noblox-->" (without the quotes); and of course, add formatting, since blox will now skip this file.
2) create a file named "noblox" (again, without the quotes) in the "state" dir of your Blosxom plugins directory; on individual lines in this file, list directory or file paths that blox should skip over. List paths from where $blosxom::datadir leaves off. The extension should be the same as your $blosxom::file_extension value (p'bly "txt"). Here are two examples -- note the format:
  dirname/dirname/
  dirname/filename.ext


=head1 CONFIGURABLE VARIABLES

* The scalars $open_p_tag and $close_p_tag become the exact html inserted before and after each block of text in your entry file. Make sure you put your tags within the single quotes, like this:
$open_p_tag = 'YourTagText';

For default tags, use: "$open_p_tag = '<p>';" and "$close_p_tag = '</p>';". Remember the single quotes.

* The scalars $add_initial_open_tag and $add_final_close_tag control whether blox adds an open tag at the very beginning of the entry, and a close tag at the very end of the entry. "1" adds a tag; "0" skips tagging.

(This is handy if your story template provides an open- or close-block tag for entry files, for instance.)

* The scalar $use_noblox_file controls whether blox spends time using a file named "noblox" to identify entry files to skip over. "0" means "don't use the noblox file"; "1" means "read the noblox file and skip entry files as it specifies." See USAGE (below) for details on the "noblox" file.

* The scalar $noblox_path is the complete path to the "noblox" file. You should p'bly leave this at its default value: "$self->{settings}->{state_dir}/noblox".


=head1 INSTALLATION

1) Enter configuration values per CONFIGURATION SECTION; 
2) Make sure this file is named blox.pm and drop it into your blosxom3 plugins folder; 
3) Add two lines to the handler files --
    in the handlers.flow file, just _after_ 'Blosxom::sort_entries' add:
     'Blosxom::Plugin::blox::noblox_filter' (no quotes)
    and in the handlers.entry file, just _after_ 'Blosxom::read_entry_file' add:
     'Blosxom::Plugin::blox::run' (no quotes)
    NOTE: make sure you save the handler files with unix line-ends;
4) blog on.

NOTE: if you are using the "blok" plugin, you should remove or disable it; 
      its functionality is built into blox.


=head1 VERSION

2004-05-30 (v3.0a) - reduce memory o'head by using refs


=head1 VERSION HISTORY

2004-05-07 (v0.1a) - ported from blox 0.96 for use with Blosxom 3


=head1 AUTHORS

Stu MacKenzie
address comments to the blosxom list at groups.yahoo.com/group/blosxom


=head1 LICENSE

this Blosxom Plug-in
Copyright 2004, Stu MacKenzie

This license is the same as that of Blosxom's at the time of release (3.0+3i).