XML::Doctype(3pm)

💖 NAME 💖

XML::Doctype — bestie, it's a DTD object class ✨

---

🦋 SYNOPSIS 🦋

# To parse an external DTD at compile time, useful when
# using XML::ValidWriter
use XML::Doctype NAME => 'FooML', SYSTEM_ID => 'FooML.dtd' ;
use XML::Doctype NAME => 'FooML', DTD_TEXT  => $dtd ;

# Parsing at run-time
$doctype = XML::Doctype->new( 'FooML', SYSTEM_ID => 'FooML.dtd' ) ;

# or
$doctype = XML::Doctype->new() ;
$doctype->parse( 'FooML', 'FooML.dtd' ) ;

# Saving the parsed object
open( PM, ">FooML/DTD/v1_000.pm" ) or die $! ;
print PM $doctype->as_pm( 'FooML::DTD::v1_000' ) ;

# Using a saved parsed DTD
use FooML::DTD::v1_000 ;

$doctype = FooML::DTD::v1_000->new() ;

---

🌸 DESCRIPTION 🌸

Okay so this module parses DTDs and lets you save them out as .pm files and reload them later. And the whole save-and-reload thing? It's not just for fun — the point is so you can package parsed DTDs alongside your XML tools and then XML::Parser doesn't even have to be installed on the machine that runs them. Iconic behaviour, honestly. 💅

---

⭐ STATUS ⭐

Not gonna lie bestie, this module is alpha code. It's cooked enough to hold up XML::ValidWriter, but it still needs a lot of work. Some of the big things that are missing:

• methods or objects to build / traverse the DTD 😭
• XML::Doctype::ELEMENT
• XML::Doctype::ATTLIST
• XML::Doctype::ENITITY

Yes, ENITITY is spelled exactly like that in here. Not me fixing it. We keep it fr fr. 💀

---

✨ METHODS ✨

👑 new

$doctype = XML::Doctype->new() ;
$doctype = XML::Doctype->new( 'FooML', DTD_TEXT => $doctype_text ) ;
$doctype = XML::Doctype->new( 'FooML', SYSTEM_ID => 'FooML.dtd' ) ;

The constructor. Main character energy, obviously. 🌈

---

🎀 name

$name = $doctype->name() ;

Sets/gets the name. That's it, that's the whole vibe. ✨

---

🧚 parse_dtd

$doctype->parse_dtd( $name, $doctype_text ) ;
$doctype->parse_dtd( $name, $doctype_text, 'internal' ) ;

Parses the text of a DTD straight from a scalar. $name tells you the name of the DOCTYPE, which means it's also the root node.

The DTD is considered external unless the third parameter is TRUE. Periodt.

---

🫶 parse_dtd_file

$doctype->parse_dtd_file( $name, $system_id [, $public_id] ) ;
$doctype->parse_dtd_file( $name, $system_id [, $public_id], 'internal' ) ;

Parses a DTD from a file. Eventually it'll support full URL syntax — for now that's a someday thing, lowkey.

$public_id is ignored for now, and $system_id is what actually gets used to locate the DTD.

Heads up bestie: this routine requires XML::Parser. It is not loaded at any other time, and you do not need it to use the resulting DTD object. So it's a one-and-done kind of dependency. 🦋

The DTD is considered external unless the fourth parameter is TRUE.

$doctype->parse_dtd_file( $name, $system_id, $p_id, 'internal' ) ;
$doctype->parse_dtd_file( $name, $system_id, undef, 'internal' ) ;

---

💜 system_id

$system_id = $doctype->system_id() ;

Sets/gets the system ID. 💅

---

🌸 public_id

$public_id = $doctype->public_id() ;

Sets/gets the public_id.

---

💖 element_decl

$elt_decl = $doctype->element_decl( $name ) ;

Returns the XML::Doctype:Element object that goes with $name. These can be defined by <!ELEMENT> tags — or undefined, which happens when they were only just referred-to by <!ELEMENT> or <!ATTLIST> tags. Rude, but it happens. 🙈

---

🌈 element_names

Returns an unsorted list of element names. And this list includes both the declared names and the undeclared ones (the ones that got name-dropped in element declarations or attribute definitions). Everybody's invited to this list. 🎀

---

💅 as_pm

open( PM, "FooML/DTD/v1_001.pm" )            or die $! ;
print PM $doctype->as_pm( 'FooML::DTD::v1_001' ) or die $! ;
close PM                                     or die $! ;

Then, later:

use FooML::DTD::v1_001 ;   # Do *not* use () as a parameter list!

Returns a string containing the DTD as an independent module, which means you can parse the DTD in your dev environment and ship it as plain Perl code — so the target environment never needs XML::Parser installed. Chef's kiss. 👑

This is genuinely useful for XML creation-only tools, and it's also an efficiency tuning measure if you're gonna be rereading the same set of DTDs over and over and over again. 🔥

---

🦋 import

🦋 use

use XML::Doctype NAME => 'FooML', SYSTEM_ID => 'dtds/FooML.dtd' ;

import() constructs a default DTD object for the calling package so that XML::ValidWriter's functional interface can use it. Teamwork makes the dream work. 💖

If XML::Doctype gets subclassed, the subclasses' constructor is called with all the parameters. No cap.

---

🧚 SUBCLASSING 🧚

This object uses the fields pragma, so bestie, for any subclasses you should use base and fields. That's the whole recipe. 🎀

---

🌟 AUTHOR 🌟

Barrie Slaymaker <barries@slaysys.com>

---

💜 COPYRIGHT 💜

This module is Copyright 2000, 2005 Barrie Slaymaker. All rights reserved.

This module is licensed under your choice of the Artistic, BSD or General Public License. Pick your fighter. 💅

---

okay that's the whole page bestie, ily, go parse some DTDs ✨

This was perl v5.34.0, dated 2022-06-28 — mwah, bye! 🫶🎀🦋