NAME

Quiq::Pod::Generator - POD-Generator

BASE CLASS

Quiq::Hash

DESCRIPTION

Dokumentation der POD-Syntax: http://perldoc.perl.org/perlpod.html

Ein Objekt der Klasse repräsentiert einen POD-Generator. Mit den Methoden der Klasse können aus einem Perl-Programm heraus POD-Dokumente erzeugt werden, wobei man sich um die Syntaxregeln und die Details der Formatierung nicht zu kümmern braucht.

ATTRIBUTES

indentation => $n (Default: 4)

Einrücktiefe bei Code-Abschnitten und Listen.

METHODS

Konstruktor

new() - Instantiiere POD-Generator

Synopsis

  $pg = $class->new(@keyVal);

Description

Instantiiere einen POD-Generator und liefere eine Referenz auf dieses Objekt zurück.

Example

Generiere POD mit Einrückung 2:

  $pg = Quiq::Pod::Generator->new(
      indentation => 2,
  );

Abschnitts-Kommandos

Alle Abschnitts-Methoden ergänzen den generierten POD-Code um eine Leerzeile am Ende, so dass das nächste Konstrukt direkt angefügt werden kann. Diese Leezeile ist in den Beispielen nicht wiedergegeben.

encoding() - Deklaration des Encodings

Synopsis

  $pod = $pg->encoding($encoding);

Description

Erzeuge eine Deklaration des Encodings $encoding und liefere den resultierenden POD-Code zurück.

Example

  $pg->encoding('utf-8');

erzeugt

  =encoding utf-8

section() - Abschnitt

Synopsis

  $pod = $pg->section($level,$title);
  $pod = $pg->section($level,$title,$body);

Description

Erzeuge einen Abschnitt der Tiefe $level mit dem Titel $title und dem Abschnitts-Körper $body und liefere den resultierenden POD-Code zurück. Ist $body nicht angegeben oder ein Leerstring, wird nur der Titel erzeugt. Andernfalls wird $body per trim() von einer Einrückung befreit.

Examples

  • ohne Body

      $pg->section(1,'Test');

    erzeugt

      =head1 Test
  • mit Body

      $pg->section(1,'Test',"Dies ist\nein Test.");

    erzeugt

      =head1 Test
      
      Dies ist
      ein Test.
  • eine Einrückung wird automatisch entfernt

      $pg->section(1,'DESCRIPTION',q~
          Dies ist
          ein Test.
      ~);

    erzeugt

      =head1 Test
      
      Dies ist
      ein Test.

code() - Code-Abschnitt

Synopsis

  $pod = $pg->code($text);

Description

Erzeuge einen Code-Abschnitt mit Text $text und liefere den resultierenden POD-Code zurück.

Example

  $pg->code("sub f {\n    return 1;\n}");

erzeugt

  $n Leerzeichen
  ----
      sub f {
          return 1;
      }

Der Code ist um $n Leerzeichen (den Wert des Objekt-Attributs "indentation") eingerückt.

bulletList() - Punkte-Liste

Synopsis

  $pod = $pg->bulletList(\@items);

Description

Erzeuge eine Punkte-Liste mit den Elementen @items und liefere den resultierenden POD-Code zurück.

Example

  $pg->bulletList(['Eins','Zwei']);

erzeugt

  =over 4
  
  =item *
  
  Eins
  
  =item *
  
  Zwei
  
  =back

orderedList() - Aufzählungs-Liste

Synopsis

  $pod = $pg->orderedList(\@items);

Description

Erzeuge eine Aufzählungs-Liste mit den Elementen @items und liefere den resultierenden POD-Code zurück.

Example

  $pg->orderedList(['Eins','Zwei']);

erzeugt

  =over 4
  
  =item 1.
  
  Eins
  
  =item 2.
  
  Zwei
  
  =back

definitionList() - Definitions-Liste

Synopsis

  $pod = $pg->definitionList(\@items);

Description

Erzeuge eine Definitions-Liste mit den Elementen @items und liefere den resultierenden POD-Code zurück.

Example

Die Aufrufe

  $pg->definitionList([A=>'Eins',B=>'Zwei']);

oder

  $pg->definitionList([['A','Eins'],['B','Zwei']]);

erzeugen

  =over 4
  
  =item A
  
  Eins
  
  =item B
  
  Zwei
  
  =back

for() - Formatierer-Code

Synopsis

  $pod = $pg->for($format,$code);

Description

Definiere Code $code für Formatierer des Formats $format und liefere das Resultat zurück. Ist $code einzeilig, wird eine for-Instruktion erzeugt, ansonsten eine begin/end-Instruktion.

Examples

  • einzeiliger Code

      $pg->for('html','<img src="figure1.png" />');

    erzeugt

      =for html <img src="figure1.png" />
  • mehrzeiliger Code

      $pg->for('html',qq|Ein Bild:\n<img src="figure1.png" />|);

    erzeugt

      =begin html
      
      Ein Bild:
      <img src="figure1.png" />
      
      =end html

pod() - Beginne POD-Block

Synopsis

  $pod = $pg->pod;

Description

Beginne einen POD-Block. Diese Instruktion ist nur nötig, wenn der Block mit einem einfachen Text beginnt, denn jede andere POD-Instruktion beginnt ebenfalls einen POD-Block.

Example

  $pg->pod;

erzeugt

  =pod

cut() - Beende POD-Block

Synopsis

  $pod = $pg->cut;

Description

Beende einen POD-Block. Diese Instruktion ist nicht nötig, wenn danach kein Perl-Code folgt.

Example

  $pg->cut;

erzeugt

  =cut

Format-Codes

fmt() - Format-Code

Synopsis

  $str = $this->fmt($type,$text);

Description

Erzeuge Inline-Segment vom Typ $type (B, I, C usw.) und liefere den resultierenden POD-Code dieses zurück.

Die Methode sorgt dafür, dass das Segment korrekt generiert wird, wenn in $text die Zeichen '<' oder '>' vorkommen.

Examples

Nomal:

  $pg->fmt('C','$x');
  =>
  C<$x>

1x > eingebettet:

  $pg->fmt('C','$class->new()');
  =>
  C<< $class->new() >>

2x > eingebettet:

  $pg->fmt('C','$x >> $y');
  =>
  C<<< $x >> $y >>>

VERSION

1.163

AUTHOR

Frank Seitz, http://fseitz.de/

COPYRIGHT

Copyright (C) 2019 Frank Seitz

LICENSE

This code is free software; you can redistribute it and/or modify it under the same terms as Perl itself.