Display current voting identifier in menu.

[usenet/usevote.git] / UVtemplate.pm

#----------------------------------------------------------------------
package UVtemplate;
#----------------------------------------------------------------------

=head1 NAME

UVtemplate - Templateverarbeitung und String-Formatierungen

=head1 SYNOPSIS

  use UVtemplate;

  $plate  = UVtemplate->new([%keys]);

            $plate->setKey(%keys);
  $item   = $plate->addListItem($name, %keys);

  $string = $plate->processTemplate($file);

=head1 DESCRIPTION

Mit Hilfe von UVtemplate, wird die komplette Aufbereitung und 
Formatierung der Programmausgaben nicht nur ausgelagert sondern
auch so flexibiliert, dass sie jederzeit angepasst werden kann,
ohne das im eigentlichen Programmcode veraendert werden muss.

Auf Programmseite wird eine Datenstruktur mit Schluessel-Wert
Paaren erzeugt. In den Template-Dateien werden dann spaeter die
jeweiligen Schluessel, durch ihre im Programm festgelegten 
Werte ersetzt. Zusaetzlich ist es moeglich Schluessel zu Listen
zusammenzufassen.

Da es sich bei den Templates um Ascii-Texte handelt, gibt es 
zusaetzlich die Moeglichkeit die Werte der Schluessel zuformatieren
um eine einheitliche Ausgabe zu ermoeglichen. D.h. es kann z.B. durch 
das Anhaengen von Leerzeichen dafuer gesorgt werden, das ein Schluessel
einer Liste immer 60 Zeichen lang ist um ansehnliche Tabellen auszugeben.

=head1 FUNCTIONS

=over 3

=cut

#----------------------------------------------------------------------

use strict;
use vars qw( $VERSION $functions @dirs);
use UVconfig;

$VERSION = 0.1;

#----------------------------------------------------------------------

=item new

Eine neues Objekt vom Typ UVtemplate anlegen. 

  my $plate = UVtemplate->new();

Als Parameter koennen gleich beliebig viele Schluessel-Wert-Paare
uebergeben werden.

=cut

sub new{
  my $class = shift;
  my $self  = {};

  if (ref($class)){
    $self->{FATHER} = $class;
    bless($self, ref($class));

  }else{
    bless($self, $class);
  }

  $self->setKey(@_);

  return $self;
}

=item setKey

Schluessel und zugehoerige Werte im Objekt speichern.

  $plate->setKey( vote-addr => 'to-vote@dom.ain' );
  $plate->setKey( datenschutz => 1);

Ist der zu speichernde Schluessel bereits vorhanden, wird er
durch den neuen Wert ueberschrieben.

=cut

sub setKey{
  my $self = shift;
  my %param = @_;

  foreach my $key (keys(%param)){
    $self->{KEYS}->{$key} = $param{$key};
  }
}

=item addListItem

Erzeugt ein neues Objekt vom Typ UVtemplate und fuegt es der 
angebenen Liste hinzu.

  $plate->addListItem(name => 'Musterman', email => 'em@il');

Da sich Listen wie normale Schluessel-Wert Paare verhalten, 
wird die Liste als Array ueber UVtemplate-Objekte unter dem
definiertem Schluessel abgelegt. Ist dieser Schluessel bereits
gesetzt und enthaehlt keinen Array, so bricht die Funktion ab.

=cut

sub addListItem{
  my $self = shift;
  my $list = shift;

  # pruefen ob key angegeben ist und falls key vorhanden
  # eine liste vorliegt
  return unless ($list && (not($self->{KEYS}->{$list}) ||
    UNIVERSAL::isa($self->{KEYS}->{$list}, 'ARRAY')));

  # neues Element erzeugen
  my $new = $self->new( @_ );

  # an listen anhaengen
  push(@{$self->{KEYS}->{$list}}, $new);

  # referenz zurueckgeben
  return $new;
}

=item getKey($key)

Den Wert eines Schluessel ermitteln.

  my $value = $plate->getKey('email');

Ist der Wert im Objekt nicht gesetzt, wird - falls es sich um ein
Element einer Liste handelt - rekursiv beim Vater weiter gesucht.

So stehen allen Kindern auch die Schluessel-Wert Paare ihrer Eltern
zur Verfuegung.

Zum Schluss wird noch geprueft, ob der Schluessel in usevote.cfg
gesetzt wurde. Dadurch sind alle Konfigurationsoptionen direkt
in Templates nutzbar.

=cut

sub getKey{
  my $self = shift;
  my $key  = $_[0];

  my $value;

  do{
    $value = $self->{KEYS}->{$key};
    $self  = $self->{FATHER};

  }while(!defined($value) && $self);

  if (!defined($value) && defined($config{$key})) {
    $value = $config{$key};
  }

  return $value;
}

#----------------------------------------------------------------------

sub getRules{
  my $self = shift;

  do{
    return $self->{RULES} if ($self->{RULES});
    $self = $self->{FATHER};
  }while($self);

  return;
}

=item getConvKey{

Einen Format ermitteln.

  my $value = $plate->getConvKey('email-adresse');

Diese Funktion ueberprueft ob eine Formatierung mit den entsprechenden
Schluessel definiert ist und ruft dementsprechend die dort definierten
Funktionen ueber der Datenstruktur auf.

Ist kein solches Format definiert, wird der Wert des Schluessel mit
einem solchen Namen zurueckgegeben. (Es wird intern getKey aufgerufen).

=cut

sub getConvKey{
  my $self = shift;
  my $key  = $_[0] || return;

  my $rules = $self->getRules();
  my $value = $self->getKey($key);
  
  $value = '' unless (defined($value));

  if ($rules && ($rules->{$key})){
    my @funcs = @{$rules->{$key}};

    foreach my $func (@funcs){
      my ($name, @params) = @$func;
  
      if ($functions->{$name}){
        $value = $functions->{$name}->($self, $value, @params);
    
      }else{
        print STDERR "format function '$name' not found!\n";
      }
    }
  }

  return $value;
}

#----------------------------------------------------------------------

=item processTemplate

Daten des Objekts in ein Template einfuegen.

  my $string = $plate->processTemplate('template/info.txt');

Die angebene Datei wird eingelesen, zerlegt und danach
die enstprechenden Platzhalter durch die (formatierten) 
Werte aus der Datenstruktur ersetzt.

=cut

sub processTemplate{
  my $self = shift;
  my $file = $_[0] || return;

  my ($rules, $body) = _split_file($file);

  # konvertierungsregeln parsen
  $self->{RULES} = _parse_rules($rules);

  # template zerlegen (zuerst fuehrende leerzeilen entfernen!)
  $body =~ s/^\n+//s;	
  my $token = UVtemplate::scan->new(string => $body);

  # daten einsetzen
  return $token->processData($self);
}

sub _split_file{
  my $file = $_[0] || return;

  my $fname = _complete_filename($file);

  unless ($fname){
    print STDERR "couldnt find '$file'\n";
    return;
  }

  my (@rules, @body);

  open(PLATE, $fname);
  my @lines = <PLATE>;
  close(PLATE);

  my $body = 0;

  foreach my $line (@lines){
    if ($line =~ m/^== TEMPLATE/){
      $body = 1;

    }else{
      if ($body){
        push(@body, $line);

      }else{
        push(@rules, $line);
      }
    }
  }

  # falls kein Separator definiert war, wird der komplette Text
  # als Body interpretiert. Es gibt keine Regeln!
  
  unless ($body){
    @body  = @rules;
    @rules = ();
  }

  # und nun wieder zu Strings zusammenpappen
  return (join('', @rules), join('', @body));
}

sub _complete_filename{
  my $file = $_[0] || return;

  my $dirs = $UVconfig::config{templatedir};
     @dirs = split(/\s*,\s*/, $dirs) if $dirs;

  my $fname;

  foreach my $dir (@dirs, '.'){
    $fname = "$dir/$file";
    return $fname if (-r $fname);
  }
}

#----------------------------------------------------------------------
# Konvertierungs-Regeln
#----------------------------------------------------------------------

sub _parse_rules{
  my $string = $_[0] || return;

  my @stack;
  my $rules = {};

  my $this = [];
    
  while (length($string) > 0){
    _strip_chars(\$string);

    my $token = _parse_token(\$string);

    if ($token){
      push(@stack, $token);
      
      _strip_chars(\$string);

      if ($string =~ s/^:=//){
        # neuen Schluessel vom Stack holen
        my $key = pop(@stack);
	
	# restlichen Stack auf alten Schluessel packen
	push(@$this, [ @stack ]);
	@stack = ();

	# neuen Schluessel anlegen
	$rules->{$key} = $this = [];

      }elsif($string =~ s/^\|//){
        # stack auf schluessel packen
	push(@$this, [ @stack ]);
	@stack = ();
      }

    }else{
      # fehlermeldung ausgeben (nacharbeiten!)
      print STDERR "Syntaxerror in Definition\n";
      return;
    }
  }

  # den Rest vom Stack abarbeiten
  push(@$this, [ @stack ]) if @stack;

  return $rules;
}

sub _strip_chars{
  my $line = $_[0] || return;