.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man v6.0.2 (Pod::Simple 3.45)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\"
.\" Required to disable full justification in groff 1.23.0.
.if n .ds AD l
.\" ========================================================================
.\"
.IX Title "DBI::Format 3"
.TH DBI::Format 3 2025-12-14 "perl v5.42.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
DBI::Format \- A package for displaying result tables
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 2
\&  # create a new result object
\&  $r = DBI::Format\->new(\*(Aqvar1\*(Aq => \*(Aqval1\*(Aq, ...);
\&
\&  # Prepare it for output by creating a header
\&  $r\->header($sth, $fh);
\&
\&  # In a loop, display rows
\&  while ($ref = $sth\->fetchrow_arrayref()) {
\&    $r\->row($ref);
\&  }
\&
\&  # Finally create a trailer
\&  $r\->trailer();
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
THIS PACKAGE IS STILL VERY EXPERIMENTAL. THINGS WILL CHANGE.
.PP
This package is used for making the output of DBI::Shell configurable.
The idea is to derive a subclass for any kind of output table you might
create. Examples are
.IP \(bu 8
a very simple output format as offered by \fBDBI::neat_list()\fR.
"AVAILABLE SUBCLASSES".
.IP \(bu 8
a box format, as offered by the Data::ShowTable module.
.IP \(bu 8
HTML format, as used in CGI binaries
.IP \(bu 8
postscript, to be piped into lpr or something similar
.PP
In the future the package should also support interactive methods, for
example tab completion.
.PP
These are the available methods:
.IP new(@attr) 8
.IX Item "new(@attr)"
.PD 0
.IP new(\e%attr) 8
.IX Item "new(%attr)"
.PD
(Class method) This is the constructor. You\*(Aqd rather call a subclass
constructor. The construcor is accepting either a list of key/value
pairs or a hash ref.
.ie n .IP "header($sth, $fh)" 8
.el .IP "header($sth, \f(CW$fh\fR)" 8
.IX Item "header($sth, $fh)"
(Instance method) This is called when a new result table should be
created to display the results of the statement handle \fR\f(CB$sth\fR\fB\fR. The
(optional) argument \fB\fR\f(CB$fh\fR\fB\fR is an IO handle (or any object supporting
a \fIprint\fR method), usually you use an IO::Wrap object for STDIN.
.Sp
The method will query the \fR\f(CB$sth\fR\fB\fR for its \fINAME\fR, \fINUM_OF_FIELDS\fR,
\&\fITYPE\fR, \fISCALE\fR and \fIPRECISION\fR attributes and typically print a
header. In general you should not assume that \fB\fR\f(CB$sth\fR\fB\fR is indeed a DBI
statement handle and better treat it as a hash ref with the above
attributes.
.IP row($ref) 8
.IX Item "row($ref)"
(Instance method) Prints the contents of the array ref \fR\f(CB$ref\fR\fB\fR. Usually
you obtain this array ref by calling \fB\fR\f(CB$sth\fR\fB\->fetchrow_arrayref()\fR.
.IP trailer 8
.IX Item "trailer"
(Instance method) Once you have passed all result rows to the result
package, you should call the \fItrailer\fR method. This method can, for
example print the number of result rows.
.SH "AVAILABLE SUBCLASSES"
.IX Header "AVAILABLE SUBCLASSES"
First of all, you can use the DBI::Format package itself: It\*(Aqs
not an abstract base class, but a very simple default using
\&\fBDBI::neat_list()\fR.
.SS "Ascii boxes"
.IX Subsection "Ascii boxes"
This subclass is using the \fIBox\fR mode of the \fIData::ShowTable\fR module
internally. \fBData::ShowTable\fR\|(3).
.SS Raw
.IX Subsection "Raw"
Row is written without formating.  Columns returned in comma or user defined
separated list.
.SS String
.IX Subsection "String"
Row is written using a string format.  Future releases will include th ability
set the string format.
.SH "AUTHOR AND COPYRIGHT"
.IX Header "AUTHOR AND COPYRIGHT"
This module is Copyright (c) 1997, 1998
.PP
.Vb 4
\&    Jochen Wiedmann
\&    Am Eisteich 9
\&    72555 Metzingen
\&    Germany
\&
\&    Email: joe@ispsoft.de
\&    Phone: +49 7123 14887
.Ve
.PP
The DBD::Proxy module is free software; you can redistribute it and/or
modify it under the same terms as Perl itself.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBDBI::Shell\fR\|(3), \fBDBI\fR\|(3), \fBdbish\fR\|(1)