package Filter::QuasiLiterate;
use strict;
use Carp;
use Filter::Util::Call;

sub import
{
    my $me =
    {
	sections => { },
	defining => undef,
    };
    filter_add(bless $me);
}

sub filter
{
    my $me = shift;
    my $status = filter_read;
    ($status > 0) or return $status;
    
    (/^\s*\#([<>])/ ?
     (($1 eq '<') ?
      (/^\s*\#[<>]([a-zA-Z0-9\-.\/: ]+)(\>?)(?:\#.*)?$/ ?
       (($2 eq '>') ?
	(exists $me->{sections}->{$1} ?
	 ($_ = $me->{sections}->{$1}) :
	 (croak "QuasiLiterate filter: chunk does not exist: \"$1\"")
	 ) :
	 (push @ {$me->{defining}},
	  (((scalar @ {$me->{defining}}) ? $me->{defining}->[-1] . '.' : '')
	   . $1))
	) :
       (croak "QuasiLiterate filter: invalid command: \"$_\"")
       ) :
      (pop @ {$me->{defining}})
      ) :
     ((scalar @ {$me->{defining}})? do
      {	
	  foreach my $def (@ {$me->{defining}}) { $me->{sections}->{$def}
					  .= $_ }
	  $_ = '';
      } :
      ()));

    return $status;
}

=head1 NAME

Filter::QuasiLiterate

=head1 SYNOPSIS

    use Filter::QuasiLiterate;
    #<foo_code
    # Put code that does foo here.
    #>
    #<foo_doc
    It then does foo, by first calling bar...
    #>
    # etc.
    
    if ($Run)
    {
        #<foo_code>
    }
    else
    {
        print <<'//'; # Or some other string you're sure won't be a
                      # line in foo_doc
        #<foo_doc>
//
    }
    #<nested-section
    #<bork
    # now in nested-section.bork
    bork;
    #>
    gork;
    #>

    #<nested-section> # Gives bork then gork
    #<nested-section.bork> # Gives bork by itself

    #<blorple
    xyzzy;
    #>
    #<baz
    rumple;
    #>
    #<blorple
    fizzy;
    #>
    #<blorple> # Gives xyzzy then fizzy
    

=head1 DESCRIPTION

Filter::QuasiLiterate allows you to do quasi-literate programming, using
chunks of code / documentation / comments / whatever which can get reused,
shuffled arbitrarily, and/or disused.  Chunks can also be defined in pieces,
and nested.  QuasiLiterate commands are indicated by lines with any amount
of whitespace, followed by # and then either < or >.  They are terminated by
newline or #.  Chunk names may contain any of the characters a-z, A-Z, 0-9,
or [-./: ].  #<chunk-name will start defining a chunk, or adding to it if 
a chunk with that name already exists.  If a chunk is already
being defined, the new chunk will have the name outer.inner, where outer and
inner are placeholders for the outer and inner chunks.  Anything inside the
inner chunk is added to both the outer and inner chunks.  Chunks can be
nested to an infinite (theoretically) number of levels.  #> stops defining
the innermost chunk.  Note that if a nested chunk is added to explicitly,
i.e. with a specified name of outer.inner, the outer chunk will I<not> be
added to.  #<chunk-name> (note the >) includes the contents
of a previously defined chunk at the current position.

=head1 BUGS

There should be more options.  Chunks can't be used before their definitions.
Documentation could be I<much> better.

There are undoubtedly more bugs lurking here somewhere.

=head1 SEE ALSO

This is the mandatory SEE ALSO section.  There is no useful information here.  :-)
		    
=cut

1;

__END__