Parse:...t::HTML(3pm)

✨ NAME ✨

Parse::Dia::SQL::Output::HTML — bestie, this module literally exists to create HTML documentation. That's it, that's the whole job. 👑

It lives in the Perl manual pages, section 3pm, and honestly? She's a whole vibe. 💅

---

🦋 SYNOPSIS 🦋

use Parse::Dia::SQL;
my $dia = Parse::Dia::SQL->new(
  file => 'foo.dia',
  db   => 'html' [ , htmlformat => {formatfile} ]
);
print $dia->get_sql();

---

🌸 DESCRIPTION 🌸

okay so. This sub-class creates HTML formatted database documentation. That's her main character moment. 💖

The HTML formatting is controlled by templates, and you pick those with the optional htmlformat parameter — that one hands over a format file. Peep "HTML formats" below for the whole tea. 🫖

Real talk though: the generated HTML is meant to be useful rather than beautiful. It's giving "functional, not a glow-up." No cap.

This sub-class follows the exact same structure as the rdbms output sub-classes, and the whole point of that is keeping things consistent — even though ngl, this gives less than optimum efficiency. Consistency ate, efficiency didn't. 😭

---

🧚 new 🧚

The constructor. The setup. The "let me introduce myself" moment. ✨

Object names in HTML have no inherent limit. The number 64 was just arbitrarily chosen. Like, no deep lore, someone just picked it. 🙈

---

💜 get_sql 💜

Returns all sql documentation. Periodt.

First, she builds the data structures:

  schema create
  view create
  permissions create
  inserts
  associations create  (indices first, then foreign keys)

Then she generates the output:

  html start
  html comments
  body start
  generate main html
  body end
  html end

---

🎀 _get_preamble 🎀

HTML Header. That's the whole thing, bestie.

---

🎀 _get_comment 🎀

Comment for HTML Header.

---

🎀 get_smallpackage_pre_sql 🎀

HTML Body start.

---

🎀 get_smallpackage_post_sql 🎀

HTML Body close.

---

🎀 _get_postscript 🎀

HTML close.

---

🦋 _get_create_table_sql 🦋

Extracts the documentation details for a single table. One table, all the deets.

---

💀 get_schema_drop 💀

Do nothing. She's not doing anything here. Nothing. Zero. Resting. 😌

---

💀 get_view_drop 💀

Do nothing. Same energy.

---

💀 _get_fk_drop 💀

Do nothing. Still nothing.

---

💀 _get_drop_index_sql 💀

Do nothing. Iconic behaviour, honestly.

---

👑 get_permissions_create 👑

Permissions get formatted as "{type} {name} to {list of roles}", and here's what each lil piece means:

• "type" is the operation — "GRANT", "REVOKE" etc.
• "name" is the permission name — "SELECT", "INSERT" etc.
• "list of roles" is the set of datbase roles affected. (yes, "datbase" — she said what she said 💀)

⚠️ Warning: Permissions are at best lightly tested (ie potentially buggy). Bestie, tread carefully. 🚨

---

💀 get_permissions_drop 💀

Do nothing. Again. We love a low-effort queen.

---

🌈 _get_create_association_sql 🌈

Extracts the documentation for table relationships. It's giving connection. 🫶

---

🌈 _get_create_index_sql 🌈

Extracts the documentation for table indices.

---

⭐ generate_html ⭐

Do the output. She does the output. That's the job. ✨

---

🧚 set_html_template 🧚

Sets up the formatting template.

Template elements use "{placeholders}" to identify how the document should be built. Like little fill-in-the-blanks but make it documentation. 💅

---

🌸 HTML Formats 🌸

The default format may be all you need, fr fr. But if you want different HTML formats for different uses, then bestie, make a format file — you define template elements between "{def:element}" and "{/def:element}" markers. 🎀

And here's the slay part: you only need to define the elements you want to be different from the defaults. Nothing more. 🙌

Any text outside the "{def:element}" and "{/def:element}" is ignored, so you can drop comments in there without it affecting the output at all. Free real estate for your thoughts. 💭

Any "\n" literals in the format file get replaced with newlines. And yeah, newlines in generated HTML typically have no effect on the layout — but they can make the output easier for humans to read, and honestly, we do it for the humans. 🫶

---

✨ Template elements ✨

💖 htmlpreamble 💖

The start of the html document.

Placeholders: filename

Default:

<html><head>\n<title>Database documentation: {filename}</title>

💖 htmlcomment 💖

A generated comment at the start of the html document. This is the standard comment at the start of the SQL script.

Placeholders: htmlcomment

Default:

\n<!-- {htmlcomment} -->\n

💖 htmlstartbody 💖

The start body html tag.

Default: </head><body>

💖 htmlendbody 💖

The end body html tag.

Placeholders: gentime

Default: <p style="font-size:75%">Generated at {gentime}.</p>

💖 htmlend 💖

The end html tag.

Default: </html>

🦋 tablelist 🦋

The bit at the top of the page which lists all the tables. Each one is formatted with "tablelistitem", separated by "tablelistsep".

Placeholders: tablelist (the assembled list of table), filename

Default:

<h1>Data Dictionary for {filename}</h1>
<h2\>List of Tables</h2>
{tablelist}
<hr width='80%'/>

🦋 tablelistitem 🦋

An individual element (table) in the table list.

Placeholders: tablename, tablecomment

Default: <a href='#{tablename}'>{tablename}</a>

🦋 tablelistsep 🦋

Separator between individual elements in the table list.

Default: ", "

🎀 tablestart 🎀

Introduction to the table details.

Default: <h2>Table details</h2>

🎀 table 🎀

Details of one table.

Placeholders: tablename, comment, refto, refby, tablerowdata, autoupdate, indices, permissions.

Default:

<h3>Table: {tablename}<a name='{tablename}'/></h3>
{comment}
{refto}
{refby}
<table border='1' cellspacing='0' cellpadding='1'>
<tr><td>Field</td><td>Type</td><td>Default</td><td>Description</td></tr>
{tablerowdata}
</table>
{autoupdate}
{indices}
{permissions}
<hr width='80%'/>

🎀 tablekeyrow, tablerow 🎀

Details of an individual field (column) from the (table) in the table detail.

tablekeyrow is used for primary key fields, tablerow for other fields.

Placeholders: name, type, default, comment.

Default tablekeyrow:

<tr><td><b>{name}</b></td><td>{type}</td><td>{default}</td><td>{comment}</td></tr>

Default tablerow:

<tr><td>{name}</td><td>{type}</td><td>{default}</td><td>{comment}</td></tr>

🎀 tablecomment 🎀

Table comments/description.

Placeholders: comment

Default: <p>{comment}</p>

🎀 tablecommentlist 🎀

Table comments/description in a list context.

Placeholders: comment

Default: {comment}

⭐ autoupdate ⭐

Auto update code, if used.

Placeholders: autoupdate

Default: <p>Automatically set:{autoupdate}</p>

⭐ refby, refto ⭐

refby — References by — a list of tables that refer to this one via foreign keys.

refto — References to — a list of tables to which this table refers via foreign keys.

🚨 The whole section is omitted if there are no references — and yes, that includes any static text. Gone. Poof. 💨

Placeholders: refbylist, reftolist respectively.

Default refby: <p>Referenced by: {refbylist}</p>

Default refto: <p>References: {reftolist}</p>

⭐ refbyitem, reftoitem ⭐

A single item in the reference by list.

Placeholders: tablename, key, fk, action, refname

Here tablename is the other table, key is the field in this table, fk is the field in the other table, action is the action on update/delete (such as cascade or update) and refname is the name of the constraint.

Default: <a href='#{tablename}'>{tablename}</a>

⭐ refbysep, reftosep ⭐

Separator between references.

Default: ", "

🌈 indices 🌈

List of indices on this tables.

🚨 The whole section is omitted if there are no indices — again, including any static text. Nothing survives. 💀

Placeholders: indexlist

Default: <h4>Indices</h4><p>{indexlist}</p>

🌈 indexitem 🌈

A single item in the index list.

Placeholders: tablename, columns, comment, type, indexname

Here tablename is the indexed (ie current) table, columns is the set of columns in the index, comment is the index comment if any, type is 'unique' (or blank) and indexname is the name of the index.

Default: {indexname}: {type} on {columns} {comment}

🌈 indexsep 🌈

Separator between indices.

Default: "<br\>"

👑 permission 👑

A list of permissions granted on this table.

Placeholders: permissionlist

Default: <h4>Permissions</h4><p>{permissionlist}</p>

👑 permissionitem 👑

A single permission in the list.

Placeholders: permission

Default: {permission}

👑 permissionsep 👑

Separator between permissions.

Default: <br/>

🫶 fieldblank 🫶

Replacement character(s) for blank values. Default value is empty.

---

🎀 Sample format file 🎀

This format file generates vertical lists of tables and references rather than single paragraph, comma separated lists (which is the default).

{def:tablelist}
<h1>List of Tables</h1>
<table border='1' cellspacing='0' cellpadding='2'>
<tr><td><b>Name</b></td><td><b>Description</b></td></tr>
{tablelist}
</table>

<hr width='80%'/>
{/def:tablelist}

{def:tablelistitem}<tr><td><a href='#{tablename}'>{tablename}</a></td><td>{tablecomment}</td></tr> {/def:tablelistitem}
{def:tablelistsep}\n{/def:tablelistsep}

{def:refby}<p><b>Referenced by:</b> <br/>{refbylist}</p>{/def:refby}
{def:refbyitem}{fk}=<a href='#{tablename}'>{tablename}</a>.{key} {action}{/def:refbyitem}
{def:refbysep} <br/>{/def:refbysep}

{def:refto}<p><b>References:</b> <br/>{reftolist}</p>{/def:refto}
{def:reftoitem} {fk}=<a href='#{tablename}'>{tablename}</a>.{key} {action}{/def:reftoitem}
{def:reftosep}<br/>{/def:reftosep}

# Comments don't matter
{def:permission}<h4>Permissions</h4><p>{permissionlist}</p>{/def:permission}
{def:permissionitem}{permission}{/def:permissionitem}
{def:permissionsep}<br/>{/def:permissionsep}

Note that comments or other text outside the {def:} The other template elements are the same as the default.

(yes bestie, that sentence is just like that in the source. We keep the lore accurate. 💀)

---

🦋 TODO 🦋

Things that might get added in future versions:

• Views are not currently documented.
• Bugs etc

---

and that's the whole page, bestie!! 💖✨

This one came from the Perl manual pages, perl v5.36.0, dated 2022-11-19 — that's the source and the date, mwah, no notes. 🫶🎀💅