Complete move to thh.votetaker.de

[usenet/usevote.git] / UVformats.pm

#----------------------------------------------------------------------
  package UVformats;
#----------------------------------------------------------------------

=head1 NAME

UVformats - Methoden zur Stringformatierung

=head1 SYNOPSIS

  value  <name-of-key>
  append <name-of-key>

  fill-left   <width> <character>
  fill-right  <width> <character>
  fill-center <width> <character>

  justify	 <name-of-key> <width>
  justify-before <name-of-key> <width>
  justify-behind <name-of-key> <width>
  
  first-words  <width>
  drop-words   <width>
  create-lines <width>

  multi-graph <width> <position> <count>
  multi-line  <width> <count>

  quote <string>
  replace <original-string> <replacement-string>
  sprintf <format-string>

  generate_date_header

=head1 DESCRIPTION

Dieses Modul stellt verschiedenste Methoden bereit, um die Strings in 
den Templates auf die unterschiedlichste Art zu formatieren. 

Dieses Modul beschraenkt sich auf die Beschreibung der Funktionen. Ihre
Einbindung wird in UVtemplates beschrieben.

=head1 FUNCTIONS

=over 3

=cut

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

use strict;
use vars qw(@ISA @EXPORT $VERSION $functions);

use Exporter;
$VERSION = 0.01;

@ISA = qw(Exporter);
@EXPORT = qw( getFunctions );

use Text::Wrap;
#use POSIX qw(strftime);
use Email::Date;

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

sub getFunctions{
  return $functions;
}

#----------------------------------------------------------------------
=item value

Gibt den Wert eines Schluessel zurueck. 

  new-key := value 'old-key' | <other-functions> ...

Diese Funktion sollte dann eingesetzt werden, wenn man einen virtuellen
Schluessel erzeugen will. D.h. der Bezeichner nicht im Template als
Schluessel vorhanden ist. Durch den Einsatz von value wird der Wert eines
anderen Schluessel kopiert und kann dann weiter formatiert werden.

=cut

sub value{
  my ($data, $value, $key) = @_;
  return $data->getKey($key);
}

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

=item append

Den Wert eines anderen Schluessels an den bisherigen String anhaengen.

  ... | append 'other-key' | ...

Per default wird als Trenner der beiden String ein Leerzeichen verwendet.
Soll dieses entfallen oder ein anderes Zeichen benutzt werden, so kann
ein dementsprechender drittere Parameter angegeben werden.

  ... | append 'other-key' ''  | ...
  ... | append 'other-key' '_' | ...

Im ersten Beispiel wird der Wert von C<other-key> nahtlos hinzugefuegt.
Im zweiten statt des Leerzeichens '_' benutzt.

=cut

sub append{
  my ($data, $value, $key, $sep) = @_;

  $sep = ' ' unless defined($sep);

  return $value. $sep. $data->getConvKey($key);
}

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

=item fill-left, fill-right, fill-center

Fuellt den String entsprechend mit Zeichen auf bis die gewuenschte
Laenge erreicht ist. Bei C<fill-left> werden die Zeichen vorranggestellt,
bei C<fill-right> angehaengt. C<fill-center> verteilt die Zeichen 
gleichmaessig vor und nach dem String.

  ... | fill-left 72 '.' | ...

Wird kein zweiter Parameter angegeben, wird automatisch das Leerzeichen
benutzt.

  ... | fill-right 60 | ...

Ist der String bereits laenger als gewuenscht, wird er nicht weiter
veraendert und auch nicht verkuerzt.

=cut

sub fill_left{ 
  my ($data, $value, $width, $char) = @_;

  $width ||= 72;
  $char  = ' ' unless (defined($char) && length($char) == 1);

  my $fill = $width - length($value);

  $value = $char x $fill . $value if ($fill > 0);

  return $value;
}

sub fill_right{ 
  my ($data, $value, $width, $char) = @_;

  $width ||= 72;
  $char  ||= ' ';

  my $fill = $width - length($value);

  $value .= $char x $fill if ($fill > 0);

  return $value;
}

sub fill_both{ 
  my ($data, $value, $width, $char) = @_;

  $width ||= 72;
  $char  ||= ' ';

  my $fill = $width - length($value);
  
  if ($fill > 0){
    my $left  = int($fill / 2);
    my $right = $fill - $left;

    $value = $char x $left . $value . $char x $right; 
  }

  return $value;
}

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

=item justify, justify-before, justify-behind

Fuegt zwischen den existierenden String und dem Wert des angegebenen 
Schluessel genau so viele Leerzeichen ein, damit die gewuenschte 
Stringlaenge erreicht wird.

  ... | justify-behind 'key' 72 | ...

C<justify-behind> haengt den Wert des Schluessel an das Ende des Strings,
C<justify-before> stellt es davor.

  justify-behind: existing-string.........value-of-key
  justify-before: value-of-key.........existing-string

C<justify> ist lediglich ein Alias auf C<justify-behind>.