DBI::Format(3)

💅 DBI::Format — the manual, but make it make sense

ok so real talk, this is DBI::Format(3) from the User Contributed Perl Documentation, and I'm gonna walk you through it like we're on facetime. sit down, hydrate, let's go 🍓

---

✨ NAME ✨

DBI::Format — a whole package for displaying result tables, bestie. that's the whole vibe.

---

🎀 SYNOPSIS 🎀

like, here's the actual shape of it:

# create a new result object
$r = DBI::Format->new('var1' => 'val1', ...);

# 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();

no cap, that's the entire lifecycle: make it, header it, loop it, trailer it. iconic.

---

🦋 DESCRIPTION 🦋

okay so FIRST THING, and I need you to hear me: THIS PACKAGE IS STILL VERY EXPERIMENTAL. THINGS WILL CHANGE. literally not joking, it's giving "work in progress, handle with care" energy. 💀

This package exists so the output of DBI::Shell can be configurable. the whole idea is that you derive a subclass for whatever kind of output table you might want to create. examples are:

• a very simple output format as offered by DBI::neat_list(). peep "AVAILABLE SUBCLASSES" below for that one 👀
• a box format, as offered by the Data::ShowTable module
• HTML format, as used in CGI binaries
• postscript, to be piped into lpr or something similar

and in the future the package should also support interactive methods — for example tab completion. yes please, we love a glow-up in progress ✨

These are the available methods:

• new(@attr)
• new(\%attr)

(Class method) this is the constructor. honestly you'd rather call a subclass constructor, but anyway — the construcor is accepting either a list of key/value pairs or a hash ref. both work, pick your fighter 🫶

• header($sth, $fh)

(Instance method) this gets called when a new result table should be created to display the results of the statement handle $sth. the (optional) argument $fh is an IO handle (or any object supporting a print method) — usually you use an IO::Wrap object for STDIN.

The method will query the $sth for its NAME, NUM_OF_FIELDS, TYPE, SCALE and PRECISION attributes and typically print a header. In general you should not assume that $sth is indeed a DBI statement handle, and better treat it as a hash ref with the above attributes. lowkey that's the important bit, don't skip it 👑

• row($ref)

(Instance method) prints the contents of the array ref $ref. usually you obtain this array ref by calling $sth->fetchrow_arrayref(). that's it, that's the row. slay.

• trailer (Instance method) once you have passed all result rows to the result package, you should call the trailer method. this method can, for example, print the number of result rows. it's the little goodbye at the end 🥺

---

🌈 AVAILABLE SUBCLASSES 🌈

First of all — plot twist — you can just use the DBI::Format package itself. It's not an abstract base class, it's a very simple default using DBI::neat_list(). no subclass required, we love convenience.

📦 Ascii boxes

This subclass is using the Box mode of the Data::ShowTable module internally. also, Data::ShowTable(3). boxes! cute! 🎁

🧾 Raw

Row is written without formating. Columns returned in comma or user defined separated list. minimal effort, maximum honesty.

🎀 String

Row is written using a string format. future releases will include th ability set the string format. (yes that's how it's written, I don't make the rules 🙈 — it's coming, okay?)

---

👑 AUTHOR AND COPYRIGHT 👑

This module is Copyright (c) 1997, 1998

Jochen Wiedmann
Am Eisteich 9
72555 Metzingen
Germany

Email: joe@ispsoft.de
Phone: +49 7123 14887

The DBD::Proxy module is free software; you can redistribute it and/or modify it under the same terms as Perl itself. fr fr, same terms as Perl, go wild 🫶

tiny heads-up: the original really does say DBD::Proxy here even though we're talking about DBI::Format. not me fixing it. I'm just the messenger 💅

---

💖 SEE ALSO 💖

DBI::Shell(3), DBI(3), dbish(1) — go read those next, bestie, iykyk 🌸

---

⭐ and that's the page!! this was perl v5.42.0, dated 2025-12-14, and you just read DBI::Format(3). mwah, go format some tables 💜🧚‍♀️