WWW::Wikipedia::TemplateFiller::Source - Base class for data sources

  my $source = new WWW::Wikipedia::TemplateFiller::Source( filler => $filler, %attrs );

  my $search = $source->_search_obj;

  my $result = $source->_search($id);

  $source->_search->native_query($id);
  return $source->_search->next_result;

  sub template_name { 'cite journal' }

  my $template = $source->fill;

  my $markup = $source->output( %args );

  my $id = $source->get_ref_name;

  my $type = $source->type;

    perldoc WWW::Wikipedia::TemplateFiller::Source

package WWW::Wikipedia::TemplateFiller::Source;
use warnings;
use strict;

# Plus:  +Field means show field only if extended-fields is enabled
# Minus: -Field means always show, regardless of extended-fields status
# Other:  Field means show only if filled

use Date::Calc;
use XML::Writer;
use HTML::Entities;
use Tie::IxHash;
use Carp;

sub new {
  my( $pkg, %attrs ) = @_;
  croak "no TemplateFiller object provided as 'filler' attr" unless $attrs{filler};

  if( my $class = $pkg->search_class ) {
    $attrs{__search} = new WWW::Search($class);
  }

  my $self = bless \%attrs, $pkg;
  return $self;
}

sub __result_from_cache { }
sub __result_to_cache { }

sub __cache_key {
  my( $self, $id ) = @_;
  return $self->type.'-'.$id;
}

sub _search_obj { shift->{__search} }

sub _search {
  my( $self, $id ) = @_;

  my $result = $self->__result_from_cache( $id );
  if( not $result ) {
    $self->_search_obj->native_query($id);
    $result = $self->_search_obj->next_result;
    $self->__result_to_cache( $id => $result );
  }

  return $result;
}

sub template_name { croak "no 'template_name' class method specified in this source" }

sub filler { shift->{filler} }

sub source_url { shift->{__source_url} }

sub __source_obj {
  my( $self, $attrs ) = @_;

  while( my($k,$v) = each %$attrs ) {
    ( my $plain_k = $k ) =~ s/^\W//;
    $self->{$k} = $v;
    $self->{$plain_k} = $v;
  }

  return $self;
}

sub fill {
  my( $self, %args ) = @_;
  $self->{_basic_fields} = $self->template_basic_fields( %args );
  return $self;
}

sub output {
  my( $self, %args ) = @_;
  $self->fill(%args) unless $self->{_basic_fields};

  my $ref_name = $self->get_ref_name;
  my $add_ref_tag = $args{add_ref_tag};
  my $vertical = $args{vertical};
  my $format = $args{format} ? $args{format} : 'text';
  my $add_param_space = $args{add_param_space};
  my $show_extended = $args{extended};

  tie( my %all_fields, 'Tie::IxHash' );
  %all_fields = ( %{ $self->{_basic_fields} }, %{ $self->template_output_fields(%args) } );

  my @pairs = ( );
  while( my( $param, $info ) = each %all_fields ) {
 			die $param unless ref $info;
    $info->{show} ||= 'always';
    next if $info->{show} eq 'if-filled' and !defined($info->{value});
    next if $info->{show} eq 'if-extended' and !$show_extended;

    my $param_value = $info->{value} || '';
       $param_value =~ s/\|/|/g;

    my $pair = sprintf ( ($add_param_space ? "%s = %s" : "%s=%s"), $param, $param_value );
    push @pairs, $pair;
  }

  my $citation;
  $citation = "{{".$self->template_name;
  $citation .= $vertical ? "\n" : ' ';
  foreach my $pair ( @pairs ) {
    $citation .= ' ' unless $vertical;
    $citation .= !$vertical && $citation =~ s/\s*$// ? ' ' : '';
    $citation .= $add_param_space ? "| $pair" : "|$pair";
    $citation .= "\n" if $vertical;
  }
  $citation .= "}}";

  if( $add_ref_tag ) {
    $citation = $ref_name
      ? sprintf( '<ref name="%s">%s</ref>', $ref_name, $citation )
      : sprintf( '<ref>%s</ref>', $citation );
  }

  if( $format eq 'xml' ) {
    my $output = '';
    my $writer = new XML::Writer( OUTPUT => \$output );
    $writer->startTag( 'wikitemplate', application => 'cite' );
      $writer->startTag( 'content' );
      $writer->characters( $citation );
      $writer->endTag();

      $writer->startTag('paramlist');
      while( my( $param, $info ) = each %all_fields ) {
        $writer->startTag( 'param', name => $param );
        $writer->characters($info->{value});
        $writer->endTag();
      }
      $writer->endTag();

    $writer->endTag;
    $writer->end;
    $writer->close;

    return $output;
  }

  $citation = encode_entities( $citation ) if $args{encode_entities};

  return $citation;
}

sub template_basic_fields { croak "no 'template_basic_fields' provided by this source" }

sub template_output_fields { {} }

sub get_ref_name {
  my $self = shift;
  my $ref_name = $self->template_ref_name;

  # Arcadian asks that quotation marks are removed from ref_name
  # so that MediaWiki renders the ref properly
  $ref_name =~ s/[\"\']//g;

  return $ref_name;
}

sub template_ref_name { my $pkg = shift; croak ref($pkg).' does not define a template_ref_name() method' }

sub type {
  my $self = shift;
  ( my $type = ref $self || $self ) =~ s/.*::(.*)//;
  return lc $type;
}

sub __today_and_now {
  my @ymd = map { $_ < 10 ? "0$_" : $_ } Date::Calc::Today();
  return sprintf '%s-%s-%s', @ymd;
}

1;