/ 
Developer-Dashboard-6.06
/ Developer::Dashboard::PageDocument

NAME

Developer::Dashboard::PageDocument - common page model for Developer Dashboard

SYNOPSIS

my $page = Developer::Dashboard::PageDocument->from_instruction($text);
my $id = $page->id;
print $page->canonical_instruction;

DESCRIPTION

This module represents the common internal page model used by saved pages, transient encoded pages, and provider-generated pages.

METHODS

new, from_hash, from_json, from_instruction, merge_state, with_mode, id, mode, as_hash, canonical_json, canonical_instruction, instruction_text, render_html

Construct, mutate, serialize, and render page documents.

id returns the stored identifier without allocating the complete hash returned by as_hash. Use it when a caller only needs the page identifier. mode likewise returns only the stored display mode for renderer decisions.

PURPOSE

This module parses and normalizes dashboard bookmark instruction documents. It understands the separator-based bookmark format, extracts fields such as TITLE, BOOKMARK, STASH, HEAD, HTML, and CODE* blocks, and preserves the raw instruction when callers need source-stable editing behavior. HEAD is trusted raw HTML inserted inside the rendered document head; never put untrusted text there.

Legacy parsing uses a direct single-section path when the input contains no legacy separator or Markdown --- separator. Multi-section documents retain the separator-aware parser. This avoids constructing a parts array for the common one-section form without changing section-name validation, whitespace handling, undefined-input behavior, or body-line preservation.

id and mode are lightweight accessors for code paths that need only a document's identifier or display mode; as_hash remains the public way to obtain the complete page data structure. mode avoids building that full hash when the renderer only needs to choose the edit or render chrome.

WHY IT EXISTS

It exists because bookmark parsing is a core format contract. The editor, renderer, source view, seeded pages, and saved page store all need the same understanding of how a bookmark document is shaped.

The renderer's text escaping also needs to preserve the bookmark format's existing HTML output while using the shared XS body escaper for long, densely escaped titles, descriptions, or runtime errors. Ordinary plain scalars return after metacharacter checks; sparse or short escaped values keep the established Perl substitutions, including double-quote escaping.

WHEN TO USE

Use this file when changing bookmark syntax, source preservation, directive parsing, or any workflow that reads or writes the text instruction format behind saved pages.

HOW TO USE

Create or load a page document through the parsing helpers, then pass the normalized structure into the page runtime, page store, or web routes. Keep bookmark syntax rules in this module instead of scattering regex parsing around the codebase.

WHAT USES IT

It is used by page storage and rendering, by skill bookmark routing, by init/seed flows, and by tests that guard the bookmark document grammar.

EXAMPLES

Example 1:

perl -Ilib -MDeveloper::Dashboard::PageDocument -e 1

Do a direct compile-and-load check against the module from a source checkout.

Example 2:

prove -lv t/07-core-units.t t/21-refactor-coverage.t

Run the focused regression tests that most directly exercise this module's behavior.

Example 3:

HARNESS_PERL_SWITCHES=-MDevel::Cover prove -lr t

Recheck the module under the repository coverage gate rather than relying on a load-only probe.

Example 4:

prove -lr t

Put any module-level change back through the entire repository suite before release.