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
- func Has(s string) bool
- func Items(v any) []any
- func Normalize(v any) any
- func ParseDate(s string) (time.Time, bool)
- func PictureData(files fs.FS, name string) ([]byte, error)
- func Truthy(v any) bool
- func ValueText(v any, format string, f Formatter) string
- func Vars(k, n int, page bool) map[string]any
- type Error
- type Field
- type Formatter
- type Kind
- type Scope
- type Token
Constants ¶
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).
const ( AlignLeft = "left" AlignRight = "right" AlignCenter = "center" )
Alignments of values in their columns (Token.Align), in templates of text.
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.
const ( FitContain = "contain" FitCover = "cover" FitStretch = "stretch" )
Fits of pictures (Token.Fit).
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.
const ( FieldValue = "value" FieldSection = "section" FieldImage = "image" )
Kinds of fields (Field.Kind).
const MaxPicture = 32 << 20
MaxPicture bounds the bytes of a picture of the data.
const MaxTagLen = 1024
MaxTagLen bounds the bytes of a tag between its braces.
const MaxWidth = 4096
MaxWidth bounds the columns of a value (Token.Width).
Variables ¶
This section is empty.
Functions ¶
func Items ¶
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 ¶
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 ¶
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 ¶
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 ¶
Truthy reports whether a value shows a section: not nil, false, zero, an empty string or an empty list.
func ValueText ¶
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.
Types ¶
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 ¶
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 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 (*Scope) Blank ¶
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 ¶
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 ¶
Item returns the scope of an item in s, with variables about its place (their names start with "_": "_index", "_first" …).
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.