Lire::ReportParser::AsciiDocBookFormatter.3pm

Langue: en

Autres versions - même langue

Version: 2006-07-23 (debian - 07/07/09)

Section: 3 (Bibliothèques de fonctions)

Sommaire

NAME

Lire::ReportParser::AsciiDocBookFormatter - Lire::ReportParser subclass which formats description.

SYNOPSIS

To format DocBook: 
     use Lire::ReportParser::AsciiDocBookFormatter qw/dbk2txt/;
 
     my $txt = dbk2txt( "<para>Test</para>" );

In XML Report processors :

     package MyParser;
 
     use base qw/ Lire::ReportParser::AsciiDocBookFormatter Lire::ReportParser /;
 
     sub new {
         my $self = shift->SUPER::new( @_ );
 
         $self->init_docbook_formatter( @_ );
 
         return $self;
     }
 
     sub handle_description {
         my ( $self, $desc ) = @_;
 
         print $desc;
 
         return;
     }

DESCRIPTION

This package implements methods that can handle the content of "description" elements and it can be used by a subclass of Lire::ReportParser. Client only have to inherit from this module so that a handle_description() method is available to process the text formatted DocBook description.

This module also provide a convenient dbk2txt() function which can be used to format a string containing DocBook elements into an ASCII equivalent.

USING Lire::ReportParser::AsciiDocBookFormatter

Lire::ReportParser processors that would like to work with text version of the description should inherit from Lire::ReportParser::AsciiDocBookFormatter in addition to Lire::ReportParser. If they override the description_start(), description_end()methods, they must link to their parents' version using "SUPER::".

Additionnally, they should merge the value elements_spec() in their elements_spec() implementation.

The Lire::ReportParser::AsciiDocBookFormatter should be listed before Lire::ReportParser in the @ISA. The AsciiDocBookFormatter doesn't inherit directly from Lire::ReportParser so that it can be used in multiple inheritance scenario.

The subclass should call the init_docbook_formatter() method from their constructor method to initialize the DocBookFormatter module.

init_docbook_formatter( %params )

The initializer recognizes some parameters that can be used to control the behavior of the DocBook handling:
columns
The number of columns in which the DocBook text should be formatted. Defaults to 72.

dbk_start_processing()

Initializes the parser's structure for formatting DocBook XML as ASCII. This is used from the description_start implementation.

dbk_end_processing()

Cleans the parser structure. This is used from the description_end() implementation.

handle_description( $description )

This method is invoked after the closing tag of the "description" element is encountered. The $description contains the description formatted in plain text.

FORMATTING DocBook STRINGS

If you have DocBook content in a string, like you can obtain from some of the Report Specifications object, you can format it in plain text using the dbx2txt() function.

dbk2txt( $docbook_str, [$columns] )

Returns a plain text version of the DocBook XML fragment $docbook_str. The "columns" parameter sets the number of columns in which the DocBook text should be formatted.

This method will die() in case of error.

SEE ALSO

Lire::ReportParser(3pm)

VERSION

$Id: AsciiDocBookFormatter.pm,v 1.13 2006/07/23 13:16:31 vanbaal Exp $ Copyright (C) 2001-2004 Stichting LogReport Foundation LogReport@LogReport.org

This file is part of Lire.

Lire is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program (see COPYING); if not, check with http://www.gnu.org/copyleft/gpl.html.

AUTHOR

Francis J. Lacoste <flacoste@logreport.org>