tmpl

package
v0.1.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 5, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package tmpl holds the template model of doc/template.md: the node tree a KDL document parses into, and the validation that runs once at load, before any data is read.

Index

Constants

This section is empty.

Variables

View Source 
var BarcodeTypes = map[string]bool{
	"Code128": true, "Code39": true, "Code93": true, "2of5i": true,
	"DataMatrix": true, "Aztec": true,
	"QR-L": true, "QR-M": true, "QR-Q": true, "QR-H": true,
}

BarcodeTypes lists the symbologies the format accepts.

Functions

func ForEachSection 

func ForEachSection(report *Report, fn func(*Section))

ForEachSection visits every band in the report, including those in embedded layouts.

Types

type Arg 

type Arg struct {
	Name  string
	Value *expr.Program
	Node  *kdl.Node
}

Arg supplies a value for a subreport parameter.

type Barcode 

type Barcode struct {
	Common
	Content
	Type     string
	Module   float64
	Vertical bool
	Grow     bool
	Ink      *Color
	Paper    *Color
}

Barcode draws a symbol.

Ink and Paper are the barcode's own, and are deliberately not taken from the style: a style's colour falls through from every enclosing scope, so a layout that colours its text would otherwise recolour every symbol under it and change what scans.

func (*Barcode) Kind 

func (barcode *Barcode) Kind() string

Kind names the element.

type Body 

type Body struct {
	Title   *Section
	Summary *Section
	Header  *Section
	Footer  *Section
	Columns *Columns
	Group   *Group
	Detail  *Section
}

Body is the part of a layout that band containers share: the optional bands, an optional columns block, and exactly one of group or detail.

type CalcMode 

type CalcMode int

CalcMode is a variable's accumulation mode. 

const (
	CalcFirst CalcMode = iota
	CalcLast
	CalcCount
	CalcList
	CalcSet
	CalcChain
	CalcSum
	CalcAvg
	CalcMin
	CalcMax
	CalcStd
	CalcVar
)

Accumulation modes.

func (CalcMode) Retains 

func (calc CalcMode) Retains() bool

Retains reports whether the mode has to keep individual values.

Everything else is an incremental accumulator with constant memory.

func (CalcMode) String 

func (calc CalcMode) String() string

String names the mode.

type Color 

type Color struct {
	Red, Green, Blue uint8
}

Color is an RGB colour. The canonical form, and what a printout carries, is always "#RRGGBB".

func ParseColor 

func ParseColor(spec string) (Color, error)

ParseColor accepts "#RRGGBB", a name, three comma-separated components as integers 0-255 or floats 0-1, or a single packed integer.

func (Color) Hex 

func (color Color) Hex() string

Hex renders the canonical form.

type Columns 

type Columns struct {
	Count int
	Gap   float64
	// Balance spreads the frame's last fragment over the columns it reached,
	// so that they end at similar heights instead of the last one running short.
	Balance bool
	Styles  []*Style
	Header  *Section
	Footer  *Section
	Node    *kdl.Node
}

Columns splits the enclosing frame.

type Common 

type Common struct {
	Horiz     geom.Extent
	Vert      geom.Extent
	HAlign    geom.HAlign
	VAlign    geom.VAlign
	Float     bool
	PrintWhen *expr.Program
	Styles    []*Style
	Node      *kdl.Node
}

Common holds what every body element and xref carries.

func (*Common) Base 

func (common *Common) Base() *Common

Base gives access to the shared properties.

type Content 

type Content struct {
	Expr     *expr.Program
	Text     string
	HasText  bool
	Data     string
	EvalTime string
	Format   string
}

Content is where a field's or barcode's text comes from.

func (*Content) Deferred 

func (content *Content) Deferred() bool

Deferred reports whether the element's expression is evaluated at the end of a scope rather than where the element sits.

func (*Content) HasPlaceholder 

func (content *Content) HasPlaceholder() bool

HasPlaceholder reports whether a deferred element carries content to be measured from before its value is known.

type Dash 

type Dash int

Dash is a stroke dash pattern. 

const (
	DashSolid Dash = iota
	DashDot
	DashDash
	DashDotDash
)

Dash patterns.

func (Dash) String 

func (dash Dash) String() string

String names the pattern, as the printout spells it.

type DataBlob 

type DataBlob struct {
	Name     string
	Encoding string
	Compress string
	Expr     *expr.Program
	Content  string
	HasBody  bool
	Node     *kdl.Node
}

DataBlob is a named literal blob.

type Diagnostic 

type Diagnostic struct {
	File    string
	Line    int
	Path    string
	Prop    string
	Message string
}

Diagnostic is one validation message.

Every one names the file, the node path, and, where the fault is in a property rather than in the node, the property.

func (Diagnostic) Error 

func (diag Diagnostic) Error() string

Error renders the diagnostic.

type DiagnosticList 

type DiagnosticList []Diagnostic

DiagnosticList is a set of validation messages.

func (DiagnosticList) Error 

func (diags DiagnosticList) Error() string

Error renders every diagnostic, one per line.

type Eject 

type Eject struct {
	Type    EjectType
	When    *expr.Program
	Require geom.Opt
	Node    *kdl.Node
}

Eject forces a break.

type EjectType 

type EjectType int

EjectType is a page or column break. 

const (
	EjectPage EjectType = iota
	EjectColumn
)

Eject kinds.

func (EjectType) String 

func (kind EjectType) String() string

String names the kind.

type Element 

type Element interface {
	Base() *Common
	// Kind names the element for diagnostics and for the printout.
	Kind() string
}

Element is a body element or an xref.

type Embedded 

type Embedded struct {
	Name      string
	Params    []*Parameter
	Records   *Records
	Variables []*Variable
	Styles    []*Style
	Body      Body
	Embedded  []*Embedded

	ParamByName map[string]*Parameter
	VarByName   map[string]*Variable
	GroupNames  []string

	Node *kdl.Node
}

Embedded is a subreport layout defined inline.

type Field 

type Field struct {
	Common
	Content
	Align TextAlign
	// HasAlign records whether the template wrote align,
	// which is what lets halign supply the alignment when it did not.
	HasAlign bool
	Stretch  bool
}

Field is text.

func (*Field) Kind 

func (field *Field) Kind() string

Kind names the element.

type Font 

type Font struct {
	Name      string
	Typeface  string
	File      string
	Data      string
	Size      int
	Bold      bool
	Italic    bool
	Underline bool
	Node      *kdl.Node
}

Font is a named font definition.

type Group 

type Group struct {
	Name         string
	Expr         *expr.Program
	KeepTogether bool
	MinRows      int
	MinTailRows  int
	Styles       []*Style
	Title        *Section
	Summary      *Section
	Columns      *Columns
	Group        *Group
	Detail       *Section
	Node         *kdl.Node
}

Group is a data-driven grouping level.

type Image 

type Image struct {
	Common
	File         string
	Data         string
	Content      string
	HasContent   bool
	Type         string
	Scale        ScaleMode
	Proportional bool
	Embed        bool
}

Image draws a bitmap.

func (*Image) Kind 

func (image *Image) Kind() string

Kind names the element.

type Layout 

type Layout struct {
	Page      geom.PageSize
	Landscape bool

	LeftMargin   float64
	RightMargin  float64
	TopMargin    float64
	BottomMargin float64

	Styles   []*Style
	Embedded []*Embedded
	Body     Body
	Node     *kdl.Node
}

Layout is page geometry and the root of the band tree.

type Line 

type Line struct {
	Common
	PenWidth  float64
	Dash      Dash
	Backslant bool
}

Line draws a rule corner to corner of its box.

func (*Line) Kind 

func (line *Line) Kind() string

Kind names the element.

type Outline 

type Outline struct {
	Title  *expr.Program
	Level  int
	Name   *expr.Program
	When   *expr.Program
	Closed bool
	Node   *kdl.Node
}

Outline is a document outline entry.

type Parameter 

type Parameter struct {
	Name        string
	Type        ValueType
	Default     string
	HasDefault  bool
	DefaultExpr *expr.Program
	Format      string
	Prompt      bool
	Node        *kdl.Node
}

Parameter is a value supplied by the caller.

func (*Parameter) Required 

func (param *Parameter) Required() bool

Required reports whether the caller must supply a value.

type RecordMember 

type RecordMember struct {
	Name     string
	Type     ValueType
	Nullable bool
	Format   string
	Node     *kdl.Node
}

RecordMember declares one member of the input records, from a `member` node.

Neither Column nor Field: a Column is an area on the page and a Field is a band element that prints a value, and this package holds all three.

type Records 

type Records struct {
	Members []*RecordMember
	ByName  map[string]*RecordMember
	Node    *kdl.Node
}

Records declares the members of the input records.

func (*Records) Names 

func (records *Records) Names() []string

Names lists the declared member names in declaration order.

type Rectangle 

type Rectangle struct {
	Common
	PenWidth float64
	Dash     Dash
	Radius   float64
	Opaque   bool
	Stroke   bool
}

Rectangle draws a box.

func (*Rectangle) Kind 

func (rect *Rectangle) Kind() string

Kind names the element.

type Report 

type Report struct {
	File        string
	BaseDir     string
	Name        string
	Description string
	Version     string
	Author      string

	Params    []*Parameter
	Records   *Records
	Variables []*Variable
	Fonts     []*Font
	Data      []*DataBlob
	Layout    *Layout

	ParamByName map[string]*Parameter
	VarByName   map[string]*Variable
	FontByName  map[string]*Font
	DataByName  map[string]*DataBlob
	GroupNames  []string

	// Warnings are load-time diagnostics that do not stop a build.
	Warnings DiagnosticList

	Node *kdl.Node
}

Report is the root of a template.

func Load 

func Load(file string) (*Report, error)

Load reads and validates a template file.

A `subreport template=` names another template, which is read here too: one call loads the whole tree, so a build never touches the filesystem for a document it has not already validated.

func LoadString 

func LoadString(src, name string) (*Report, error)

LoadString reads and validates a template from a string. The name is used in diagnostics and as the base for relative paths.

type ScaleMode 

type ScaleMode int

ScaleMode is how an image meets its box. 

const (
	ScaleCut ScaleMode = iota
	ScaleFill
	ScaleGrow
)

Image scale modes.

func (ScaleMode) String 

func (scale ScaleMode) String() string

String names the mode.

type Scope 

type Scope int

Scope is a variable's iteration or reset scope. 

const (
	ScopeReport Scope = iota
	ScopePage
	ScopeColumn
	ScopeGroup
	ScopeDetail
	ScopeItem
)

Scopes.

func (Scope) String 

func (scope Scope) String() string

String names the scope.

type Section 

type Section struct {
	Kind       SectionKind
	Height     geom.Opt // unset means height="auto"
	PrintWhen  *expr.Program
	Split      bool
	Orphans    int
	Widows     int
	SwapHeader bool
	SwapFooter bool

	Styles     []*Style
	Ejects     []*Eject
	Outlines   []*Outline
	Elements   []Element
	Subreports []*Subreport

	Node *kdl.Node
}

Section is one band.

type SectionKind 

type SectionKind int

SectionKind names one of the five bands. 

const (
	BandTitle SectionKind = iota
	BandSummary
	BandHeader
	BandFooter
	BandDetail
)

Band kinds.

func (SectionKind) String 

func (kind SectionKind) String() string

String names the band.

type Style 

type Style struct {
	When    *expr.Program
	Font    string
	HasFont bool
	Color   *Color
	BgColor *Color
	Node    *kdl.Node
}

Style is conditional formatting.

type Subreport 

type Subreport struct {
	Template string
	// Report is the template named by Template, loaded with this one.
	// Nil for a subreport that names an embedded layout instead.
	Report   *Report
	Embedded string
	// EmbeddedLayout is the layout Embedded names, resolved at load against
	// the scope this node is written in. Nil for a subreport naming a file.
	//
	// Resolving once, at load, is what keeps validation and the engine
	// from answering one name differently.
	EmbeddedLayout *Embedded

	Seq       int
	Data      *expr.Program
	When      *expr.Program
	Inline    bool
	OwnPageNo bool
	Args      []*Arg
	DocOrder  int
	Node      *kdl.Node
}

Subreport runs another template over a nested sequence.

type TextAlign 

type TextAlign int

TextAlign is a field's per-line text alignment. 

const (
	AlignLeft TextAlign = iota
	AlignCenter
	AlignRight
	AlignJustified
)

Text alignments.

func (TextAlign) String 

func (align TextAlign) String() string

String names the alignment, as the printout spells it.

type ValueType 

type ValueType int

ValueType is a declared parameter or record member type. 

const (
	TypeString ValueType = iota
	TypeInt
	TypeDecimal
	TypeFloat
	TypeBool
	TypeDatetime
	TypeDate
	TypeObject
	TypeList
)

Declared value types.

func (ValueType) IsTemporal 

func (kind ValueType) IsTemporal() bool

IsTemporal reports whether the type is date or datetime, which are the two that accept a `format` parsing layout.

func (ValueType) String 

func (kind ValueType) String() string

String names the type.

type Variable 

type Variable struct {
	Name     string
	Expr     *expr.Program
	Init     *expr.Program
	Calc     CalcMode
	Iter     Scope
	IterGrp  string
	Reset    Scope
	ResetGrp string
	Node     *kdl.Node
}

Variable is an accumulator updated as data is consumed.

type Xref 

type Xref struct {
	Common
	Type     string
	Target   *expr.Program
	Caption  *expr.Program
	Elements []Element
}

Xref is a link region containing its own body elements.

func (*Xref) Kind 

func (xref *Xref) Kind() string

Kind names the element.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.