Documentation
¶
Overview ¶
Package form fills templates with data and makes the forms that business systems print (invoices, slips, certificates) as BDF documents.
A template is an Excel workbook, a Word document or a PowerPoint presentation whose text holds tags (package form/tag): {{name}} for a value, {{#items}} … {{/items}} for what a list repeats. Filling it lays the file out with the tags replaced by the data: a workbook as the pages Excel prints, a document as its pages, a presentation as its slides. See Fill of converter/xlsx, converter/docx and converter/pptx for what the tags do in each.
A template is also a file whose fields have places: a PDF with the fields of a form (its AcroForm; converter/pdfform), and a template of pdfme (the JSON file that its designer saves; converter/pdfme). Their fields are the names that the data has values for.
A template is also a text file of the characters of a form on a grid of columns and lines (converter/textform): the continuous forms and slips of dot matrix printers, and receipts. Its tags are those of the Office templates; the form keeps its print image, from which the text modes of printers and plain text are written (package form/textpart).
data, err := form.LoadData(form.Source{FileName: "order.json", Data: order},
form.Source{Name: "items", FileName: "lines.csv", Data: lines})
res, err := form.Fill(template, size, &form.Options{Data: data})
err = res.Doc.WriteSingle(out)
The data is an object of the values of JSON. Sums, taxes, what is carried over to the next page and the rounding of all of them are the data's: a template looks values up and formats them, and does not calculate with them (the formulas of a workbook aside).
Compile makes a compiled template (.bdft) of a template: a BDF document that holds the template with what it asks of data, and shows it filled with sample data. It is checked once, and is filled like the template.
A fill may leave names of the data open (Options.Open): it makes a partly filled form (.bdff), which holds the values given, and which another fill completes with the values of the names left open, as when one party of a contract fills in theirs and the other party the rest.
Index ¶
- Constants
- func Describe(r io.ReaderAt, size int64) (format string, sample map[string]any, err error)
- func Fields(r io.ReaderAt, size int64) ([]tag.Field, error)
- func LoadData(sources ...Source) (map[string]any, error)
- func Schema(fields []tag.Field, sample map[string]any) ([]byte, error)
- func SchemaOf(r io.ReaderAt, size int64, sample map[string]any) ([]byte, error)
- type Compiled
- type Options
- type Record
- type Result
- type Source
- type Template
- type ValueSignature
- type ValueSigner
- type Values
Constants ¶
const ( FormatXLSX = "xlsx" FormatDOCX = "docx" FormatPPTX = "pptx" FormatPDF = "pdf" FormatPDFME = "pdfme" FormatText = "text" )
Formats of templates: the documents of Office with tags in their text, the files whose fields are what is filled (a PDF with the fields of a form, and a template of pdfme), and text with tags on a grid of columns and lines.
const MaxDataSize = 256 << 20
MaxDataSize bounds the bytes of a file of data.
const MaxTemplateSize = 256 << 20
MaxTemplateSize bounds the bytes of the source stored in a compiled template. Both compiling and reading a compiled template enforce it.
const OpenAll = "*"
OpenAll in Options.Open leaves open every name that the data does not give.
const RecordVersion = 1
RecordVersion is the version of Record.
const SchemaDialect = "https://json-schema.org/draft/2020-12/schema"
SchemaDialect is the dialect of JSON Schema that Schema writes.
const SchemaKeyword = "x-bdf"
SchemaKeyword is the keyword of the schemas of Schema that holds what a template says of a name: the kind of its tags ("value", "section" or "image"), their number format, how a section repeats ("mode", and "slots"), the symbology of a code ("code"), what a person gives for a picture ("input": "signature" or "seal"), where the tags are ("at"), what a person is shown for the values of a choice ("labels"), and that a text may have several lines ("multiline").
const TemplateVersion = 1
TemplateVersion is the version of the description of compiled templates.
const ValuesVersion = 1
ValuesVersion is the version of what a signature of values signs.
Variables ¶
This section is empty.
Functions ¶
func Describe ¶
Describe tells what a template is: its format (FormatXLSX …; that of the template a compiled template holds), and the sample of its data that it has for itself: of a compiled template the sample it was compiled with, of a template of pdfme what its designer left in its fields. sample is nil for a template without one.
func Fields ¶
Fields reads the tags of a template without filling it: the names that data for it has, or the first mistake in its tags.
func LoadData ¶
LoadData reads files of data into the data of a template: the values of JSON, with numbers as float64 and dates (of YAML, and of workbooks) as time.Time.
func Schema ¶
Schema describes the data that a template asks for as a JSON Schema: an object with a property for each name that the tags of the template look up, in the order of the template. A program that makes a form for the data of a template (an editor, a page that asks a person for the values) makes it of the schema.
A template does not say all of it, and the schema is what its tags suggest:
- A section with names in it, with {{.}}, or with a way to repeat (rows, slots, pages) is a list: of objects with those names, or of values. A section of slots holds as many items as it has slots, at most.
- Another section is a condition: true or false.
- A value with a number format is a number, with a date format a date (a text as tag.ParseDate reads it), and otherwise a text or a number.
- A picture is a text: the path of a file, or a data: URL. A QR code or a barcode is the text that the symbol says.
- A name with dots (customer.name) is a property of an object.
A name in a section is looked up in the item of the section first and in what is around it next, so that the tags alone do not tell which of the two has it: it is a property of the item, unless the template looks the same name up around the section too. A sample of the data (that of a compiled template, or nil) settles it: the names are where the sample has them, a section is a list, an object or a condition as its value in the sample is, and a value has the type of its value there.
Nothing is required: a tag whose name the data lacks is left empty. Construction is limited to 65,536 fields and nodes, nested at most 256 levels.
Types ¶
type Compiled ¶
type Compiled struct {
// Doc is the document to write as the .bdft: its pages are the
// template filled with the sample data.
Doc *bdf.Document
Template *Template
Warnings []string
}
Compiled is a compiled template.
func Compile ¶
Compile checks a template and makes its compiled form. The data of the options is the sample that the pages of the compiled template show the template filled with; without data they show the template with its tags (a template of pdfme with what its designer left in its fields, which is then the sample). name is the file name of the template, when it has one. The source may be at most MaxTemplateSize bytes.
type Options ¶
type Options struct {
// Data is the data: an object of the values of JSON (see LoadData).
Data map[string]any
// Strict makes a tag whose name the data does not have an error;
// without it the tag is replaced by nothing, with a warning.
Strict bool
// Files holds the pictures that the data names by their paths.
Files fs.FS
// Convert are the options of the conversion: the fonts, the images,
// the sheets or slides to fill (Pages; for a Word document the pages
// to keep) and the parameters of the format ("views", "paper" …). nil
// converts with the defaults.
Convert *converter.Options
// Open are the names of the data that the fill leaves open: with any,
// Fill makes a partly filled form (a .bdff; Result.Partial) of the
// values that the data gives, which another fill completes. OpenAll
// leaves open every name that the data does not give. Otherwise every
// name of a partly filled form or of a template that is filled partly
// is given or left open (null gives none); see Template.Filled.
Open []string
// Sign signs the values that the fill gives the form (values.go): a
// partly filled form holds the signature, and a form completed of it
// a record of its values with the signatures (VerifyValues).
Sign *ValueSigner
}
Options controls filling a template.
type Record ¶ added in v0.2.0
type Record struct {
Version int `json:"version"`
Format string `json:"format"`
Source string `json:"source"`
From string `json:"from,omitempty"`
// Filled are all of the values of the form.
Filled map[string]any `json:"filled"`
// Signed are the signatures of values (the DER of CMS signatures).
Signed [][]byte `json:"signed"`
}
Record is the record of a form completed of a partly filled form whose values were signed: the part of the type bdf.PartFill.
type Result ¶
type Result struct {
Doc *bdf.Document
Warnings []string
// Fields are the names that the tags of the template look up.
Fields []tag.Field
// Format is the format of the template (FormatXLSX …).
Format string
// Partial describes the partly filled form that Doc is when the fill
// left names open (Options.Open), and is nil when Doc is complete.
Partial *Template
}
Result is a filled template.
type Source ¶
type Source struct {
// Name is where the data of the file goes: "" makes it the data
// itself (a JSON or YAML object, whose values the values of the
// sources before it with the same names give way to), and a name
// ("items", "customer.address") makes it the value of that name.
//
// A CSV or TSV file is a list of objects: the first record names the
// values of the others. Without a name it is the list named after the
// file ("lines" for lines.csv). A workbook (.xlsx) is such a list for
// each of its sheets, by the names of the sheets; with a name, a
// workbook of one sheet is that list.
Name string
// FileName tells the format of the data by its extension: .json,
// .yaml or .yml, .csv or .tsv, .xlsx.
FileName string
Data []byte
}
Source is a file of data for a template.
type Template ¶
type Template struct {
// Version is TemplateVersion.
Version int `json:"version"`
// Format is the format of the template the document holds (FormatXLSX
// …), Name its file name when it had one, and Source the hash of the part
// (of the type bdf.PartSource) that is the template.
Format string `json:"format"`
Name string `json:"name,omitempty"`
Source string `json:"source"`
// Fields are the names that the tags of the template look up.
Fields []tag.Field `json:"fields"`
// Sample is the data the pages of the document show the template
// filled with (none: they show the tags).
Sample map[string]any `json:"sample,omitempty"`
// Schema is the JSON Schema of the data (Schema, made of the fields
// and the sample): what a program makes a form for the data of,
// without reading the template. That of a partly filled form is the
// schema of the names it leaves open.
Schema json.RawMessage `json:"schema,omitempty"`
// Filled are the values of a partly filled form (a .bdff): its pages
// show the template filled with them. Open are the names that it
// leaves open, which the data that completes it gives, and no others.
// From is the SHA-256 (in hex) of the description of the compiled
// template that the form was made of ("" for a template that was not
// compiled).
Filled map[string]any `json:"filled,omitempty"`
Open []string `json:"open,omitempty"`
From string `json:"from,omitempty"`
// Signed are the signatures of the values of a partly filled form
// (the DER of CMS signatures; values.go), of those who filled in
// their parts, in their order.
Signed [][]byte `json:"signed,omitempty"`
// contains filtered or unexported fields
}
Template describes a compiled template: the part of the type bdf.PartTemplate of a .bdft, as JSON.
func ReadTemplate ¶
ReadTemplate reads a compiled template: its description, and the template it holds.
type ValueSignature ¶ added in v0.2.0
type ValueSignature struct {
Index int
Certificate *x509.Certificate
Chain []*x509.Certificate
SigningTime time.Time
TimeStamp time.Time
// Values are what it signed.
Values *Values
// Err is why it does not hold for the form (nil: it does), TrustErr
// why its certificate is not trusted.
Err error
TrustErr error
}
ValueSignature is what VerifyValues finds of a signature of values.
func VerifyValues ¶ added in v0.2.0
func VerifyValues(r io.ReaderAt, size int64, o *sign.VerifyOptions) ([]*ValueSignature, error)
VerifyValues checks the signatures of the values of a partly filled form, or of a form completed of one (its Record). A document with neither has none.
func (*ValueSignature) Valid ¶ added in v0.2.0
func (s *ValueSignature) Valid() bool
Valid reports whether the signature holds and its signer is trusted.
type ValueSigner ¶ added in v0.2.0
type ValueSigner struct {
// Key signs, and Chain is its certificate and the chain to the root.
Key crypto.Signer
Chain []*x509.Certificate
// Claims are what the signer says of the signature (its role …).
Claims map[string]any
// Time is the signing time (the clock when zero).
Time time.Time
// TSA is the URL of a time-stamp authority (RFC 3161), and Client
// the client that asks it.
TSA string
Client *http.Client
}
ValueSigner signs the values of a fill (Options.Sign).
type Values ¶ added in v0.2.0
type Values struct {
Version int `json:"bdf-form-values"`
// Format is the format of the template, Source the SHA-256 (hex) of
// its bytes, and From that of the description of the compiled
// template the form was made of (Template.From).
Format string `json:"format"`
Source string `json:"source"`
From string `json:"from,omitempty"`
// Filled are the values of the form, and Open the names it leaves
// open, when it was signed.
Filled map[string]any `json:"filled"`
Open []string `json:"open"`
Claims map[string]any `json:"claims,omitempty"`
}
Values is what a signature of values signs.
Directories
¶
| Path | Synopsis |
|---|---|
|
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).
|
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). |
|
Package textpart reads and writes the print image of a form filled from a template of plain text: the part of the type bdf.PartText ("text") of a document, as JSON (docs/spec.md §4).
|
Package textpart reads and writes the print image of a form filled from a template of plain text: the part of the type bdf.PartText ("text") of a document, as JSON (docs/spec.md §4). |