pdftable

type BBox struct {
	X0, Y0, X1, Y1 float64
}

type Char struct {
	// Text is the Unicode payload of this glyph (one or more runes).
	// Empty string means the font's encoding and ToUnicode CMap both
	// failed to map the glyph; the bbox still describes where the
	// glyph was drawn so downstream layout heuristics can use the
	// positioning even when we can't read the text.
	Text string

	// Bounding box in PDF user space, with x0 <= x1 and y0 <= y1.
	// Y0 is the descender baseline of the glyph; Y1 is the top of the
	// ascender. The bbox is the typographic cell, not the ink — it
	// matches what pdfplumber reports.
	X0, Y0, X1, Y1 float64

	// FontName is the /BaseFont (or /Name) value from the font dict,
	// e.g. "Helvetica" or "ABCDEF+TimesNewRoman-Bold". It's surfaced
	// verbatim — callers that want to detect bold weight should match
	// on substrings ("bold", "-bd").
	FontName string

	// FontSize is the size the glyph was rendered at, in PDF user space
	// units (i.e. after applying the text matrix and CTM). For a glyph
	// drawn with `12 Tf` and identity CTM this is 12.0; if the CTM
	// scales by 2x it's 24.0.
	FontSize float64

	// Upright is true when the glyph is drawn in normal reading
	// orientation (a*d > 0 and b*c <= 0 in the combined text matrix).
	// Rotated and mirrored glyphs report false. pdfplumber uses the
	// same predicate to skip vertical-stamp text during table finding.
	Upright bool

	// Advance is the horizontal advance width the text matrix moved by
	// after drawing this glyph (in user-space units). It already
	// includes character spacing, word spacing for the space glyph,
	// and the font's per-glyph width — i.e. the actual ink-to-ink
	// distance to the next glyph.
	Advance float64
}

type Curve struct {
	// Points are the vertices of the path in order. For curve segments,
	// only the on-path endpoints are emitted (control points are
	// dropped) — this matches pdfplumber's "pts" field, which is also
	// just the endpoints. Callers that need precise curve geometry
	// should request that extension; we don't expect tables to use
	// curves so dropping control points is fine for the initial scope.
	Points [][2]float64

	Stroke bool
	Fill   bool
	Width  float64
}

type Document interface {
	// NumPages returns the page count. Always >= 1 for a valid PDF.
	NumPages() int

	// Page returns the n'th page (1-indexed). Returns
	// ErrPageOutOfRange if n is < 1 or > NumPages().
	Page(n int) (Page, error)

	// Pages returns a range iterator over (n, Page) pairs for use
	// with Go 1.23+ range-over-func syntax:
	//
	//   for n, p := range doc.Pages() {
	//       // ...
	//   }
	//
	// The iterator yields pages in 1-based order. It does NOT clone
	// the underlying Document — Close() on the doc still tears down
	// the iterator's pages.
	Pages() iter.Seq2[int, Page]

	// Close releases any resources held by the underlying parser.
	// For pdfcpu-backed documents this is currently a no-op (pdfcpu
	// holds everything in memory), but callers should still defer
	// Close() so that future backends (mmap, file handles) work.
	Close() error
}

type Line struct {
	X0, Y0, X1, Y1 float64

	// Stroke is true if the path was stroked (S, s, B, b, B*, b*).
	// Lines emitted from non-stroked paths are dropped before the
	// caller sees them — but the field is preserved for symmetry
	// with Rect/Curve so layout code can branch on it uniformly.
	Stroke bool

	// Width is the stroke line width in user-space units at the time
	// the line was emitted. For ruling lines this is typically 0.5–1.0.
	Width float64
}

type Objects struct {
	Chars  []Char
	Lines  []Line
	Rects  []Rect
	Curves []Curve
}

type Page interface {
	// Number returns the page number (1-based).
	Number() int

	// Width and Height return the page's mediabox dimensions in PDF
	// points (1/72 inch), already adjusted for the page's /Rotate
	// entry — so a portrait letter-sized page rotated 90 degrees
	// reports Width=792 Height=612 (landscape), matching what a
	// PDF viewer would display.
	Width() float64
	Height() float64

	// Chars walks the page and returns every positioned glyph. The
	// order is content-stream order — i.e. the order the producer
	// drew them, NOT visual reading order. Downstream layout code
	// (extract_text, find_tables) sorts the chars by position.
	Chars() ([]Char, error)

	// Lines returns every straight-line segment drawn on the page.
	// Each `l` segment in the content stream becomes one Line.
	// Rectangles drawn via `re` are NOT decomposed into four Lines;
	// they're reported through Rects() instead.
	Lines() ([]Line, error)

	// Rects returns every rectangle drawn via the `re` operator.
	// Both stroked and filled rectangles are returned; the Stroke
	// and Fill flags say which.
	Rects() ([]Rect, error)

	// Curves returns every Bezier or composite path that isn't a
	// pure line-segment chain or a single rect.
	Curves() ([]Curve, error)

	// Objects returns Chars + Lines + Rects + Curves in a single
	// walk. Use this when you need all four — it's strictly
	// cheaper than calling each accessor separately because the
	// content stream is parsed exactly once.
	Objects() (Objects, error)

	// Words extracts positioned text runs from the page. A "word"
	// is a contiguous group of chars whose horizontal gaps are
	// within WordOpts.XTolerance and whose vertical positions
	// agree within WordOpts.YTolerance. Pass DefaultWordOpts() to
	// use pdfplumber-matching defaults. See WordOpts for the full
	// configuration surface.
	//
	// Returns an empty slice (not nil) when the page contains no
	// extractable text.
	Words(opts WordOpts) ([]Word, error)

	// ExtractText returns the page's text as a single string. By
	// default words on the same line are joined with a single
	// space and lines are joined with "\n". When TextOpts.Layout is
	// true, the output preserves spatial layout (column-aligned
	// text, blank lines for vertical gaps) at the cost of more
	// whitespace. Pass DefaultTextOpts() for pdfplumber-matching
	// defaults.
	ExtractText(opts TextOpts) (string, error)

	// ExtractTextSimple is a no-frills extraction that clusters
	// chars by visual line and joins them by gap detection. Use
	// when ExtractText's word-grouping heuristics produce undesired
	// results on adversarial input.
	ExtractTextSimple(xTolerance, yTolerance float64) (string, error)
}

type Rect struct {
	X0, Y0, X1, Y1 float64

	// Stroke and Fill mirror the painting operator that closed the
	// path: S/s set Stroke; f/F/f* set Fill; B/b/B*/b* set both.
	// Either or both can be true — but not neither (paths with `n`
	// produce nothing).
	Stroke bool
	Fill   bool

	// Width is the stroke line width at the time the rectangle was
	// painted, in user-space units. Zero when Stroke is false.
	Width float64
}

type TextOpts struct {
	XTolerance float64
	YTolerance float64

	// Layout: when true, the output preserves the page's spatial
	// layout — words at the same x-position appear in the same column
	// across lines, and lines that are far apart are separated by
	// extra newlines. When false (the default), output is dense:
	// words on the same line are joined with single spaces, lines
	// with "\n".
	Layout bool

	// LayoutWidthChars: when Layout=true, the total width of each
	// emitted line in characters. If 0, defaults to round(page.Width /
	// XDensity).
	LayoutWidthChars int

	// LayoutHeightChars: when Layout=true, the total number of
	// emitted lines (extra blank lines at the bottom pad to this
	// height). If 0, defaults to round(page.Height / YDensity).
	LayoutHeightChars int

	// XDensity / YDensity: PDF points per character / per line when
	// computing layout grid dimensions. Default values match
	// pdfplumber (XDensity=7.25, YDensity=13) — roughly the metrics
	// of 10pt Helvetica.
	XDensity float64
	YDensity float64

	// UseTextFlow / HorizontalLTR / VerticalTTB / ExtraAttrs are
	// passed through to the underlying WordExtractor.
	UseTextFlow   bool
	HorizontalLTR bool
	VerticalTTB   bool
	ExtraAttrs    []string

	// Expand passes through to WordOpts.Expand.
	Expand bool
}

type Word struct {
	// Text is the concatenated Unicode payload of the run. Ligature
	// glyphs are expanded into their constituent characters when
	// WordOpts.Expand is true (the default), so "file" appears as
	// "file" in the output.
	Text string

	// Bounding box of the run in PDF user space (origin at bottom-
	// left, Y growing up). The bbox is the union of every char's bbox
	// in this run.
	X0, Y0, X1, Y1 float64

	// Upright is true if every char in the run was drawn in normal
	// reading orientation. We don't merge upright and rotated chars
	// into the same Word — they end up in different runs.
	Upright bool

	// Direction is one of "ltr", "rtl", "ttb", "btt". Most words on
	// most pages are "ltr"; rotated stamps may be "ttb"; Arabic/Hebrew
	// content is "rtl". The value is the direction the chars were
	// READ, not the direction they were drawn.
	Direction string

	// FontName / FontSize are copied from the first char in the run.
	// pdfplumber does the same — if a word straddles a font change,
	// only the leading font is reported, but in practice such words
	// are rare because changing font emits a new BT/ET pair which
	// breaks the run boundary at the content-stream level.
	FontName string
	FontSize float64

	// Chars is the slice of Char objects this word was assembled from.
	// Populated only when WordOpts.KeepChars is true (it costs O(n)
	// memory per word so we default to off). Useful for callers that
	// want to map word substrings back to glyph positions (highlight,
	// search) or to filter further by per-char attributes.
	Chars []Char
}

type WordOpts struct {
	// XTolerance is the maximum horizontal gap (in PDF points) between
	// adjacent chars that still get merged into the same word.
	// Default: 3.
	XTolerance float64

	// YTolerance is the maximum vertical jitter between chars that
	// still get clustered onto the same line. Default: 3.
	YTolerance float64

	// KeepBlankChars: when false (the default), space chars in the
	// content stream are dropped before word grouping — the word
	// boundary is inferred from the gap, not from the explicit space.
	// Set to true to preserve them (e.g. for diff-style line
	// reconstruction).
	KeepBlankChars bool

	// UseTextFlow: when true, chars are processed in content-stream
	// order rather than re-sorted by position. This is faster and
	// often matches reading order in well-formed PDFs, but breaks for
	// PDFs that draw glyphs in random order (e.g. some scanner OCR
	// output).
	UseTextFlow bool

	// HorizontalLTR: when true (the default), upright text is read
	// left-to-right; when false, right-to-left. Setting this to false
	// is shorthand for Direction="rtl" but only for upright text.
	HorizontalLTR bool

	// VerticalTTB: when true (the default), rotated text is read top-
	// to-bottom; when false, bottom-to-top.
	VerticalTTB bool

	// ExtraAttrs is a list of Char field names that must match
	// EXACTLY for two chars to be merged into the same word. The
	// supported names are: "fontname", "size". Useful when a single
	// physical line has two runs that should be kept separate (e.g. a
	// bold caption followed by regular body text).
	ExtraAttrs []string

	// SplitAtPunctuation: when true, every ASCII punctuation char
	// (string.punctuation in Python) terminates the current word and
	// becomes its own one-char word. Default: false.
	SplitAtPunctuation bool

	// Expand: when true (the default), ligature glyphs (fi, fl, …) are
	// expanded into their constituent ASCII chars during text
	// assembly. The Char's text payload is preserved unchanged; only
	// the Word.Text string is expanded.
	Expand bool

	// KeepChars: when true, Word.Chars is populated with the source
	// chars. Off by default to save memory.
	KeepChars bool
}