Class PdfUaDocument

Namespace

PDiffy

Assembly

PDiffy.dll

Everything PDiffy reads from a PDF, in the order a snapshot prints it.

public sealed record PdfUaDocument : IEquatable<PdfUaDocument>

Inheritance

object

PdfUaDocument

Implements

IEquatable<PdfUaDocument>

Inherited Members

object.Equals(object)

object.Equals(object, object)

object.GetHashCode()

object.GetType()

object.ReferenceEquals(object, object)

object.ToString()

Properties

Annotations

Every annotation on every page, in each page's own order. Those a structure element points to are also in its Annotations.

public IReadOnlyList<PdfAnnotation> Annotations { get; init; }

Property Value

IReadOnlyList<PdfAnnotation>

Artifacts

Artifact text, such as page numbers, headers and footers, page by page.

public IReadOnlyList<PdfPageText> Artifacts { get; init; }

Property Value

IReadOnlyList<PdfPageText>

Bookmarks

The top-level bookmarks, with nested ones in their Children.

public IReadOnlyList<PdfBookmark> Bookmarks { get; init; }

Property Value

IReadOnlyList<PdfBookmark>

BookmarksUnreadable

Set when the bookmarks nest more than 256 deep or loop back on themselves, so they can't be read safely; Bookmarks is then empty.

public bool BookmarksUnreadable { get; init; }

Property Value

bool

Document

Whether it's tagged, its language and page count, and whether a viewer shows its title.

public required PdfDocumentInfo Document { get; init; }

Property Value

PdfDocumentInfo

Fonts

Every font the pages use, and every font a text, combo box, list box or signature field's appearance, or a FreeText annotation's, draws with, once each. Those appearances aren't hashed, so this is where their fonts show.

public IReadOnlyList<PdfFont> Fonts { get; init; }

Property Value

IReadOnlyList<PdfFont>

Form

Settings for the whole form; null when the document has no form.

public PdfFormSettings? Form { get; init; }

Property Value

PdfFormSettings

FormFields

Every field in the form; empty when the document has no form.

public IReadOnlyList<PdfFormField> FormFields { get; init; }

Property Value

IReadOnlyList<PdfFormField>

Images

Every image drawn on every page, page by page.

public IReadOnlyList<PdfImage> Images { get; init; }

Property Value

IReadOnlyList<PdfImage>

Metadata

The title, author and other metadata from the Info dictionary and XMP.

public required PdfMetadata Metadata { get; init; }

Property Value

PdfMetadata

PageLabels

The page label ranges, ordered by their first page; empty when the PDF doesn't label its pages.

public IReadOnlyList<PdfPageLabelRange> PageLabels { get; init; }

Property Value

IReadOnlyList<PdfPageLabelRange>

Pages

Every page in order, including any that couldn't be loaded (Unreadable).

public IReadOnlyList<PdfPage> Pages { get; init; }

Property Value

IReadOnlyList<PdfPage>

Paths

Every painted vector path, such as a line, box or filled shape, page by page.

public IReadOnlyList<PdfVectorPath> Paths { get; init; }

Property Value

IReadOnlyList<PdfVectorPath>

RoleMap

The custom structure types and the type each maps to; empty when the PDF has no role map.

public IReadOnlyList<PdfRoleMapping> RoleMap { get; init; }

Property Value

IReadOnlyList<PdfRoleMapping>

Settings

How a viewer opens, shows or restricts the file, such as its layout, encryption or attachments.

public PdfSettings Settings { get; init; }

Property Value

PdfSettings

Shadings

Every shading painted on its own with the sh operator, such as a gradient background, page by page.

public IReadOnlyList<PdfShading> Shadings { get; init; }

Property Value

IReadOnlyList<PdfShading>

Structure

The structure tree's top-level elements, with the rest in their Children; empty for an untagged PDF. AllElements() lists every element.

public IReadOnlyList<PdfStructureElement> Structure { get; init; }

Property Value

IReadOnlyList<PdfStructureElement>

TextRuns

The text, page by page, in runs that share a font, size, color, render mode and role.

public IReadOnlyList<PdfTextRun> TextRuns { get; init; }

Property Value

IReadOnlyList<PdfTextRun>

Untagged

Text assistive technology can't reach, page by page: text outside any tag, one entry per line, and tagged text that no structure element points to, one entry per marked-content ID.

public IReadOnlyList<PdfPageText> Untagged { get; init; }

Property Value

IReadOnlyList<PdfPageText>

Methods

AllElements()

Every structure element, in reading order.

public IEnumerable<PdfStructureElement> AllElements()

Returns

IEnumerable<PdfStructureElement>

Check(PdfCheckSet)

Applies the rules in a set, such as Latest or a release's own set that never changes, and lists what they find as Check(params PdfCheck[]) does.

public IReadOnlyList<PdfCheckFinding> Check(PdfCheckSet set)

Parameters

set PdfCheckSet

Returns

IReadOnlyList<PdfCheckFinding>

Check(params PdfCheck[])

Applies the checks and lists what they find, grouped by check in the order PdfCheck declares them; an empty list means every check passed. With no checks given, applies every check.

public IReadOnlyList<PdfCheckFinding> Check(params PdfCheck[] checks)

Parameters

checks PdfCheck[]

Returns

IReadOnlyList<PdfCheckFinding>

CompareTo(PdfUaDocument, Action<PdfSnapshotOptions>?)

The differences between this document's snapshot and a later one's, element by element, as Compare(PdfUaDocument, PdfUaDocument, Action<PdfSnapshotOptions>?) gives them.

public DocumentDiff CompareTo(PdfUaDocument after, Action<PdfSnapshotOptions>? configure = null)

Parameters

after PdfUaDocument

The later PDF, whose new content counts as added.

configure Action<PdfSnapshotOptions>

What to leave out or scrub from both, as for ToSnapshot(Action<PdfSnapshotOptions>?).

Returns

DocumentDiff

Elements(string)

Structure elements of a type, such as Figure, matched on the type or its role-mapped type, in reading order.

public IEnumerable<PdfStructureElement> Elements(string type)

Parameters

type string

Returns

IEnumerable<PdfStructureElement>

Exceptions

ArgumentException

The type is neither a standard type, nor in the role map, nor used in the document, so a typo such as "figure" throws instead of returning no elements and letting an assertion over them pass.

Headings()

Every heading, H1 to H6 and H, with its level, role-mapped types included, in reading order.

public IReadOnlyList<PdfHeading> Headings()

Returns

IReadOnlyList<PdfHeading>

Load(byte[])

Reads the PDF in a byte array.

public static PdfUaDocument Load(byte[] pdf)

Parameters

pdf byte[]

Returns

PdfUaDocument

Load(Stream)

Reads the PDF in a stream from its start, wherever the stream was left, and puts its position back afterward. The stream is left open.

public static PdfUaDocument Load(Stream pdf)

Parameters

pdf Stream

Returns

PdfUaDocument

Remarks

A page that can't be loaded comes back as Unreadable. An empty stream, a ZIP file, a web page, or a PDF that is too damaged to open or is encrypted with a password throws InvalidDataException with a message that says which.

Load(string)

Reads the PDF file at a path.

public static PdfUaDocument Load(string path)

Parameters

path string

Returns

PdfUaDocument

Remarks

A page that can't be loaded comes back as Unreadable; a file that isn't a PDF, is too damaged to open or is encrypted with a password throws InvalidDataException.

MatchStructure(string)

Whether part of the structure tree matches a template written like the snapshot's structure section, for a test about one table or list rather than the whole document:

Table
  TR
    TH scope=Column "Trail"
    TH scope=Column /Length/

A line matches an element of its type, or role-mapped type, with everything else it gives: words such as p1, keys such as scope=Column, and quoted text. Keys left out match anything, and /regex/ in place of the text or a key's value matches part of it (write \s for a space). A line's children match the element's children in order, with others allowed between them, and a top-level line can match anywhere in the tree.

public StructureMatch MatchStructure(string template)

Parameters

template string

The template, indented two spaces per level.

Returns

StructureMatch

Whether it matched, and if not, the closest part of the tree and the first template line it doesn't match.

Exceptions

ArgumentException

The template has no lines, a line is indented with a tab or an odd number of spaces, a line doesn't start with a type, or a /regex/ isn't a valid regular expression.

ToSnapshot(Action<PdfSnapshotOptions>?)

The canonical snapshot text: one element per line, LF endings.

public string ToSnapshot(Action<PdfSnapshotOptions>? configure = null)

Parameters

configure Action<PdfSnapshotOptions>

What to leave out, e.g. o => o.Ignore(PdfSection.Metadata).Ignore(PdfDetail.Positions).

Returns

string

ToTranscript()

The structure tree as the lines a screen reader announces, in reading order, such as "heading level 1: Trail Guide" and "figure: Park logo". Pass it to VerifyTextAsync(string, Action<TextSnapshotOptions>?, string, string) for a test that fails when what a screen reader user hears changes.

public string ToTranscript()

Returns

string