use strict;
use integer;

# Tag parser object for use in plugins.
#
# The plugin author uses this object by generating one or more
# TagParser objects, either in their initPlugin function if they
# have a long lifetime, or in the handler methods otherwise. Each
# TagParser is passed a callback object that is required to implement
# the method "call". =call= takes one formal parameter, an attributes
# object. It also passes on any extra parameters passed by the caller
# to processText, varArgs style.
# For example:
# sub initPlugin {
#    my $cb = new MyPlugin::CallbackHandler();
#    $tagParser = new TWiki::Plugins::TagParser( "MYTAG", $cb );
# }
# sub commonTagsHandler {
#    $tagParser->processText( $_[0] );
# }
#
{ package TWiki::Plugins::TagParser;

  # Create a new TagParser object.
  sub new {
    my ( $class, $tag, $callback ) = @_;
    my $this = {};

    $this->{tag} = $tag;
    $this->{callback} = $callback;

    return bless( $this, $class );
  }

  # PUBLIC process the block of text through the tag handler, calling
  # the callback on each occurence of the tag.
  sub processText {
    my $this = shift;
    my $textref = shift;

    my $tag = $this->{tag};

    $$textref =~ s/%$tag({(.*)})?%/&_handleTag( $this, $2, @_ )/ge;
  }

  # PRIVATE handle the processing of a tag instance
  sub _handleTag {
    my $this = shift;
    my $attrs = shift;

    $attrs = new TWiki::Plugins::Attrs( shift ) if( defined( $attrs ));
    ($this->{callback}->call)( $attrs, $this->{extras}, @_ );
  }

  # PUBLIC generate a printable representation of the tag and the
  # attributes object passed
  sub generateTag {
    my ( $this, $attrs ) = @_;

    return "%" . $this->{tag} . "{" . $attrs->toString() . "}%";
  }
}

1;