tag

package
v0.2.0 Latest Latest
Warning

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

Go to latest
Published: Oct 26, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package tag reads the tags of form templates: the marks in the text of a Word, Excel or PowerPoint file that data replaces when the template is filled (package form).

A tag is written between double braces, in the manner of Mustache:

{{name}}                 a value; {{a.b}} a value of a value, {{.}} the item itself
{{total | fmt:"#,##0"}}  a value in a number format (the format codes of Excel)
{{#items}} … {{/items}}  a section: once for each item of a list, or when the value is true
{{^items}} … {{/items}}  an inverted section: when the list is empty or the value is false
{{%photo}}               a picture ({{%photo | fit:cover}})
{{%sign | signature}}    a picture that a person draws: a signature ({{%seal | seal}} the picture of a seal)
{{%url | qr}}            a QR code of a value ({{%url | qr:H}}, with the level of error correction)
{{%jan | barcode:ean13}} a barcode of a value (the symbologies of image/barcode)

In a template of plain text (ParseText) a value may take a number of columns: {{name | width:20}} (on the left of them), {{no | right:8}}, {{title | center:30}}, with | cut or | wrap for a value that is wider.

A section may say how it repeats what a template has between its tags ({{#items | pages}}; see Token.Mode). The braces, the marks after them and the quotes may be the full-width or typographic ones that input methods and word processors put in their place. \{{ is {{ as text.

Tags never run code: there are no expressions, only names looked up in the data. A template is as untrusted as any other input.

Index

Constants

View Source
const (
	// ModeRows copies the unit once for each item, moving down what is
	// below. It is the default of a section whose tags are in the same
	// row. ("block" is another name for it.)
	ModeRows = "rows"
	// ModeSlots fills the rows that are there, an item each, and leaves the
	// others empty: nothing moves. It is the default of a section whose
	// tags are in different rows.
	ModeSlots = "slots"
	// ModePages copies the unit once for each item as ModeRows does, each
	// copy on a printed page of its own.
	ModePages = "pages"
)

How a section repeats the rows (or other units) of the template between its tags (Token.Mode).

View Source
const (
	AlignLeft   = "left"
	AlignRight  = "right"
	AlignCenter = "center"
)

Alignments of values in their columns (Token.Align), in templates of text.

View Source
const (
	// OverflowKeep writes it whole, with a warning: the line is longer.
	OverflowKeep = ""
	// OverflowCut writes the columns it has room for.
	OverflowCut = "cut"
	// OverflowWrap writes the rest of it on the lines that follow, in the
	// same columns.
	OverflowWrap = "wrap"
)

What is done with a value wider than its columns (Token.Overflow), in templates of text.

View Source
const (
	FitContain = "contain"
	FitCover   = "cover"
	FitStretch = "stretch"
)

Fits of pictures (Token.Fit).

View Source
const (
	// InputSignature is a signature that the person draws by hand.
	InputSignature = "signature"
	// InputSeal is the picture of a seal (a hanko): a picture that the
	// person picks, of which the white is taken out.
	InputSeal = "seal"
)

Inputs of pictures (Token.Input, Field.Input): what a person gives for the picture, which a page that asks for the data asks with. Either is a picture as any other is.

View Source
const (
	FieldValue   = "value"
	FieldSection = "section"
	FieldImage   = "image"
)

Kinds of fields (Field.Kind).

View Source
const MaxPicture = 32 << 20

MaxPicture bounds the bytes of a picture of the data.

View Source
const MaxTagLen = 1024

MaxTagLen bounds the bytes of a tag between its braces.

View Source
const MaxWidth = 4096

MaxWidth bounds the columns of a value (Token.Width).

Variables

This section is empty.

Functions

func Has

func Has(s string) bool

Has reports whether text may hold a tag.

func Items

func Items(v any) []any

Items returns what a section of a value is repeated for: the items of a list, the value itself when it is another true value, and nothing when it is false.

func Normalize

func Normalize(v any) any

Normalize returns data in the values that templates are filled with: the numbers as float64, the lists as []any, the objects as map[string]any with keys that are strings, whatever the decoder that read them made of them. Values of other kinds become their text.

func ParseDate

func ParseDate(s string) (time.Time, bool)

ParseDate reads the text of a date as data writes it: a date ("2026-10-13", "2026/10/13"), or a date and a time ("2026-10-13T09:30:00", with or without a zone, or with a space for the T). The time is that of the clock on the wall: the zone is dropped, as a spreadsheet has none.

func PictureData

func PictureData(files fs.FS, name string) ([]byte, error)

PictureData reads a picture that the data names for a picture tag: the path of a file among files, or a data: URL in base64.

func Truthy

func Truthy(v any) bool

Truthy reports whether a value shows a section: not nil, false, zero, an empty string or an empty list.

func ValueText

func ValueText(v any, format string, f Formatter) string

ValueText writes a value as the text that replaces a tag in the text of a document: in the format of the tag, with the formatter; without a format, a number as the General format writes it, a date as yyyy-mm-dd (with hh:mm, and :ss, when it has a time), true and false as TRUE and FALSE, nothing for no value. Lists and objects have no text. Without a formatter, a format is not applied.

func Vars

func Vars(k, n int, page bool) map[string]any

Vars returns the variables of item k of n (see Scope.Item): "_index" and "_count", "_first" and "_last", and, for an item that is a page, "_page" and "_pages".

Types

type Error

type Error struct {
	Pos int
	Msg string
}

Error is a mistake in the tags of a text, at a byte of it.

func (*Error) Error

func (e *Error) Error() string

type Field

type Field struct {
	// Name is the name as the tags write it ("customer.name").
	Name string `json:"name"`
	// Kind is FieldValue, FieldSection or FieldImage.
	Kind string `json:"kind"`
	// In names the sections the tags are in, outermost first: the name is
	// looked up in their items first.
	In []string `json:"in,omitempty"`
	// Format is the number format of a value, when its tags give one.
	Format string `json:"format,omitempty"`
	// Mode is how a section repeats (ModeRows, ModeSlots or ModePages; ""
	// for a section inside a text), and Slots the items a section of
	// ModeSlots has room for.
	Mode  string `json:"mode,omitempty"`
	Slots int    `json:"slots,omitempty"`
	// Inverted is set for a name that only inverted sections look up.
	Inverted bool `json:"inverted,omitempty"`
	// Code is the symbology of an image that is a QR code or a barcode of
	// the value ("qr", "ean13" …): the value is then what the symbol
	// says, not the name of a picture.
	Code string `json:"code,omitempty"`
	// Input is what a person gives for a picture (InputSignature,
	// InputSeal; "" for any picture).
	Input string `json:"input,omitempty"`
	// At is where the tags are ("Sheet1!B5").
	At []string `json:"at"`

	// Type is the type of the value: "string", "number", "boolean",
	// "date" or "date-time" ("": the tags do not tell).
	Type string `json:"type,omitempty"`
	// Options are the values that a value is one of, and Labels what a
	// person is shown for each (the same number of them, or none).
	Options []string `json:"options,omitempty"`
	Labels  []string `json:"labels,omitempty"`
	// Label names the field for a person, and Default is the value that
	// the template has for it.
	Label   string `json:"label,omitempty"`
	Default any    `json:"default,omitempty"`
	// MaxLen is the most characters that a text has room for (0: any
	// number), and Multiline says that it may be of several lines.
	MaxLen    int  `json:"maxLength,omitempty"`
	Multiline bool `json:"multiline,omitempty"`
}

Field is a name that the tags of a template look up in the data: what a template asks of the data that fills it.

type Formatter

type Formatter func(v any, format string) string

Formatter writes a value in a number format: the format codes of Excel ("#,##0", "yyyy/mm/dd"). An empty format is the General format, as a cell without a format shows a number. (converter/xlsx has one: Formatter.)

type Kind

type Kind uint8

Kind is the kind of a token.

const (
	// Text is text outside tags.
	Text Kind = iota
	// Value is {{name}}.
	Value
	// Open is {{#name}}.
	Open
	// Inverted is {{^name}}.
	Inverted
	// Close is {{/name}}.
	Close
	// Image is {{%name}}.
	Image
)

type Scope

type Scope struct {
	// contains filtered or unexported fields
}

Scope is the data that the tags at a place of a template see: the item of the section they are in, inside the items of the sections around it, in the data of the template. A name is looked up from the innermost item outwards.

func NewScope

func NewScope(root any) *Scope

NewScope returns the scope of the data of a template.

func (*Scope) Blank

func (s *Scope) Blank(vars map[string]any) *Scope

Blank returns the scope of a place in s that no item fills: only the variables, its own and those around it, are found from it.

func (*Scope) IsBlank

func (s *Scope) IsBlank() bool

IsBlank reports whether the scope is of a place that no item fills, or is in one: names that are not found from it are not missing from the data.

func (*Scope) Item

func (s *Scope) Item(value any, vars map[string]any) *Scope

Item returns the scope of an item in s, with variables about its place (their names start with "_": "_index", "_first" …).

func (*Scope) Lookup

func (s *Scope) Lookup(path []string) (any, bool)

Lookup finds the value of the name of a tag. The first part of the name is looked up in the item of the scope, then in those around it; the others in the value found.

func (*Scope) Value

func (s *Scope) Value() any

Value returns the item of the scope.

type Token

type Token struct {
	Kind Kind
	// Text is the text of a Text token.
	Text string
	// Name is the name of a tag as written ("customer.name", "."), and
	// Path its parts. A Close may have none: it closes the open section.
	Name string
	Path []string
	// Format is the number format of a Value (fmt:"…"); HasFormat tells
	// an empty one from none.
	Format    string
	HasFormat bool
	// Width is the columns a Value takes in a template of text (width:n,
	// right:n, center:n; 0 for the columns of its value), Align how it is
	// placed in them (AlignLeft …), and Overflow what is done with a
	// value wider than them (OverflowKeep …). Only ParseText reads them.
	Width    int
	Align    string
	Overflow string
	// Mode is how an Open repeats ("" for the default of where it is).
	Mode string
	// Fit is how an Image fills its place ("" is FitContain).
	Fit string
	// Input is what a person gives for the picture of an Image
	// (InputSignature, InputSeal; "" for any picture).
	Input string
	// Code is the symbology of an Image that is a QR code or a barcode of
	// its value, not a picture that the value names (barcode.QR,
	// barcode.EAN13 …; "" for a picture). Level is the level of error
	// correction of a QR code ("" for the default), and Quiet the modules
	// of its quiet zone when HasQuiet is set (else that of the symbology).
	Code     string
	Level    string
	Quiet    int
	HasQuiet bool
	// Pos and End are the bytes of the token in the text.
	Pos, End int
}

Token is a piece of template text: text, or a tag.

func Parse

func Parse(s string) ([]Token, error)

Parse splits text into text and tags.

func ParseText added in v0.2.0

func ParseText(s string) ([]Token, error)

ParseText splits the text of a template of plain text into text and tags: those of Parse, whose values may also take a number of columns (width:n, right:n, center:n, with cut or wrap).

func (Token) Symbol

func (t Token) Symbol(v any) (*barcode.Symbol, error)

Symbol makes the QR code or the barcode that an Image tag asks for (Code) of a value of the data: a text, or a number (written without an exponent; a code that starts with zeros is a text in the data).

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL