Lintian::Deb822::Parser(3)

✨ NAME ✨

Lintian::Deb822::Parser — Lintian's generic Deb822 parser functions 💖

okay so real talk, bestie: this is a page from the Debian Package Checker manual, section 3 (the library section, for the coders). It's the Lintian::Deb822::Parser(3) page and it's genuinely useful, no cap. 🫶

---

🌸 SYNOPSIS 🌸

 use Lintian::Deb822::Parser qw(read_dpkg_control);

 my @paragraphs;
 try {
     @paragraphs = read_dpkg_control('some/debian/ctrl/file');

 } catch {
     # syntax error etc.
     die encode_utf8("ctrl/file: $@");
 }

---

🦋 DESCRIPTION 🦋

So this module is basically a little grab-bag of utility subs. They're all nice to have, but each one on its own was way too small to deserve its own whole module, so they all live here together like one big happy group chat. 💅

Most of these subs? You only get them if you import them on request. No free samples.

🎀 Debian control parsers 🎀

At first glance this module looks like it's got several debian control parsers in it. And honestly? It's giving "so many parsers". But in practise, there is only one real parser — and that's "visit_dpkg_paragraph_string". Everything else is just a convenience function wrapped around it. One main character, many supporting roles. 👑

Use read_dpkg_control when

You've got a debian control file (like debian/control, iykyk) and you want to pull a bunch of paragraphs out of it. That's the vibe check. ✅

---

⭐ CONSTANTS ⭐

These are the constants you can pass into the Debian control file parser functions to change up their parsing flag. ✨

• DCTRL_DEBCONF_TEMPLATE — tells the parser the file should be parsed as a debconf template. These ones have slightly different syntax rules for whitespace in some cases.
• DCTRL_NO_COMMENTS — the file does not allow comments. Flip this flag on and any comment in the file is considered a syntax error. periodt. 💀

---

💜 FUNCTIONS 💜

• read_dpkg_control(FILE[, FLAGS[, LINES]]) — a convenience function so you don't have to hand-roll using parse_dpkg_control with paths to files instead of open handles. The first argument has to be the path to a FILE, and it should be read as a debian control file. If the file is empty, you get an empty list back. 🍓

Otherwise, it behaves exactly like:

 use autodie;

 open(my $fd, '<:encoding(UTF-8)', FILE); # or '<'
 my @p = parse_dpkg_control($fd, FLAGS, LINES);
 close($fd);
 return @p;

And yeah, this goes without saying, but it may fail with any of the messages that "parse_dpkg_control(HANDLE[, FLAGS[, LINES]])" does. It can also emit autodie exceptions if open or close fails. 😭

• read_dpkg_control_lc(FILE[, FLAGS[, LINES]])
• parse_dpkg_control_string(STRING[, FLAGS[, LINES]]) — reads debian control data from STRING and returns a list of the paragraphs in it. Each paragraph is represented via a hashref, which maps the (lower cased) field names to their values. 🧚

FLAGS, if you give it one, is a bitmask of the DCTRL_* constants. Please refer to "CONSTANTS" for the list of constants and what they mean. The default value for FLAGS is 0.

If LINES is given, it should be a reference to an empty list. On return, LINES will be populated with a hashref for each paragraph (in the same order as the returned list). Each hashref will also have a special key "START-OF-PARAGRAPH" that gives the line number of the first field in that paragraph. These hashrefs will map the field name of the given paragraph to the line number where the field name appeared. 🔥

This is a convenience sub around "visit_dpkg_paragraph" and can therefore produce the same errors as it. Please see "visit_dpkg_paragraph" for the finer semantics of how the control file is parsed.

NB: parse_dpkg_control does not close the handle for the caller. Not its job, not its problem. 🙈

• parse_dpkg_control_string_lc(STRING[, FLAGS[, LINES]])
• lowercase_field_names
• visit_dpkg_paragraph_string (CODE, STRING[, FLAGS]) — reads debian control data from STRING and passes each paragraph to CODE. A paragraph is represented via a hashref, which maps the (lower cased) field names to their values. This one is the actual real parser, bestie. The blueprint. 💖

FLAGS, if given, is a bitmask of the DCTRL_* constants. Please refer to "CONSTANTS" for the list of constants and their meaning. The default value for FLAGS is 0.

If the file is empty (i.e. it contains no paragraphs), the method will contain an empty list. The deb822 contents may be inside a signed PGP message with a signature. 🔐

visit_dpkg_paragraph will require the PGP headers to be correct (if present) and require that the entire file is covered by the signature. However, it will not validate the signature (in fact, the contents of the PGP SIGNATURE part can be empty). The signature should be validated separately. Don't skip that part. fr fr.

visit_dpkg_paragraph will pass paragraphs to CODE as they are completed. So if CODE can process the paragraphs as they're seen, very large control files can be processed without keeping all the paragraphs in memory. Iconic efficiency behaviour. 👑

As a consequence of how the file is parsed, CODE may be passed a number of (valid) paragraphs before parsing is stopped due to a syntax error. Yeah. That's just how it is. 😭

NB: visit_dpkg_paragraph does not close the handle for the caller either.

CODE is expected to be a callable reference (e.g. a sub) and will be invoked as the following:

CODE->(PARA, LINE_NUMBERS)

• The first argument, PARA, is a hashref to the most recent paragraph parsed. The second argument, LINE_NUMBERS, is a hashref mapping each of the field names to the line number where the field name appeared. LINE_NUMBERS will also have a special key "START-OF-PARAGRAPH" that gives the line number of the first field in that paragraph.
• The return value of CODE is ignored. It doesn't care. 💅
• If the CODE invokes die (or similar) the error is propagated to the caller.

On syntax errors, visit_dpkg_paragraph will call die with the following string:

  "syntax error at line %d: %s\n"

Where %d is the line number of the issue and %s is one of:

• Duplicate field %s — the field appeared twice in the paragraph. Not the moment for main character energy, pick one. 💀
• Continuation line outside a paragraph (maybe line %d should be " .") — a continuation line shows up outside a paragraph — usually caused by an unintended empty line before it.
• Whitespace line not allowed (possibly missing a ".") — an empty continuation line was found. This usually means a period is missing to denote an "empty line" in (e.g.) the long description of a package. 🌸
• Cannot parse line "%s" — generic error containing the text of the line that confused the parser. Note that all non-printables in %s will be replaced by underscores.
• Comments are not allowed — a comment line appeared and FLAGS contained DCTRL_NO_COMMENTS. told you so.
• PGP signature seen before start of signed message — a "BEGIN PGP SIGNATURE" header is seen and a "BEGIN PGP MESSAGE" has not been seen yet. wrong order bestie. 🙈
• Two PGP signatures (first one at line %d) — two "BEGIN PGP SIGNATURE" headers are seen in the same file.
• Unexpected %s header — a valid PGP header appears (e.g. "BEGIN PUBLIC KEY BLOCK").
• Malformed PGP header — an invalid or malformed PGP header appears.
• Expected at most one signed message (previous at line %d) — two "BEGIN PGP MESSAGE" headers appear in the same message.
• End of file but expected an "END PGP SIGNATURE" header — the file ended after a "BEGIN PGP SIGNATURE" header without being followed by an "END PGP SIGNATURE".
• PGP MESSAGE header must be first content if present — the file had content before PGP MESSAGE. rude tbh.
• Data after the PGP SIGNATURE — the file had data after the PGP SIGNATURE block ended.
• End of file before "BEGIN PGP SIGNATURE" — the file had a "BEGIN PGP MESSAGE" header, but no signature was present.

---

👑 SEE ALSO 👑

• lintian(1)

---

That's the whole page, bestie, you made it. 🎉 This was Lintian::Deb822::Parser(3) from Lintian v2.114.0ubuntu1.8, dated 2026-05-06 — go parse something gorgeous. 💖✨🦋