textpart

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: 8 Imported by: 0

Documentation

Overview

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).

A template of text (converter/textform) puts its characters on a grid of columns and lines, as a dot matrix printer prints in its text mode. The pages of the document draw that grid with a monospace font; this part keeps the grid itself, so that the writers of the text modes of printers (ESC/P, ESC/POS) and of plain text print the characters and not the pictures of the pages. It is small and imports neither package form nor the converters, for the package print to read.

The JSON of version 1:

{
  "version": 1,
  "cpi": 10, "lpi": 6,            // columns and lines to the inch
  "columns": 136, "lines": 66,    // the paper, in columns and lines (lines 0: a roll)
  "margin": {"left": 2, "top": 1},
  "skip": 3,                      // lines skipped over the perforation
  "pages": [
    {"lines": [
      {"text": "納品書", "size": [{"col": 30, "cols": 12, "size": "big"}]},
      {"text": ""},
      {"text": "┌────┬──┐", "paper": [{"col": 0, "cols": 9}]},
      {"text": "│ ペン │ 2 │", "paper": [{"col": 0, "cols": 1}, {"col": 7, "cols": 1}, {"col": 11, "cols": 1}]}
    ]}
  ]
}

Columns are counted from the left margin: column 0 of a line is the first column after it, and line 0 of a page the first line under the top margin. A character takes the columns that Width gives it, twice as many in a range of the size "wide" or "big"; Cells walks a line with the columns of its characters.

Index

Constants

View Source
const (
	// SizeWide is double width: ESC W 1 of ESC/P, GS ! 0x10 of ESC/POS.
	SizeWide = "wide"
	// SizeTall is double height: ESC w 1, GS ! 0x01.
	SizeTall = "tall"
	// SizeBig is double width and height.
	SizeBig = "big"
)

Sizes of characters (Range.Size).

View Source
const (
	// MaxSize bounds the bytes of the JSON.
	MaxSize = 64 << 20
	// MaxColumns and MaxLines bound the paper.
	MaxColumns = 4096
	MaxLines   = 4096
	// MaxPages bounds the pages, and MaxPageLines the lines of a page (a
	// roll of paper has as many as it has).
	MaxPages     = 100000
	MaxPageLines = 1 << 20
)

Limits of a part (it is read from documents that are not trusted).

View Source
const Version = 1

Version is the version of the JSON this package writes and reads.

Variables

View Source
var ErrNone = errors.New("textpart: the document has no print image of text")

ErrNone tells that a document has no part of the print image.

Functions

func Width

func Width(r rune, ambiguousWide bool) int

Width is the columns of a character: 2 for a wide or full-width one (East Asian width W or F: kanji, kana, full-width forms, most emoji), and for an ambiguous one (A) when ambiguousWide is set; 0 for a character that takes no column of its own (a combining mark, a variation selector, a zero-width space or joiner, a control character); 1 for the others.

Types

type Cell

type Cell struct {
	// Text is the character.
	Text string
	// Col is its first column and Cols its columns as printed: Width of
	// the character, twice that in a range of the size "wide" or "big".
	Col, Cols int
	// Size is the size of the range the character is in ("" for none),
	// and Paper whether it is in a range of the paper.
	Size  string
	Paper bool
}

Cell is a character of a line with its place: a character and the characters of no width that follow it (combining marks).

type Image

type Image struct {
	// Version is Version.
	Version int `json:"version"`
	// CPI is the width of a column: columns to the inch (10, 12, 15, 17.1
	// …). LPI is the height of a line: lines to the inch (6, 8 …).
	CPI float64 `json:"cpi"`
	LPI float64 `json:"lpi"`
	// Columns is the width of the paper in columns, the left margin
	// included (80; 136 for paper of 15 inches).
	Columns int `json:"columns"`
	// Lines is the length of a page in lines, the top margin and the skip
	// included (66 for 11 inches at 6 LPI). 0 is a roll of paper (a
	// receipt): each page is as long as its lines.
	Lines int `json:"lines"`
	// Margin is the room left of the lines (in columns) and above them (in
	// lines) on each page.
	Margin Margin `json:"margin"`
	// Skip is the lines left empty at the bottom of each page, over the
	// perforation of fanfold paper (ESC N of ESC/P). Lines - Margin.Top -
	// Skip lines are printed on a page.
	Skip int `json:"skip,omitempty"`
	// AmbiguousWide says that the characters of East Asian width
	// "ambiguous" (box drawing, ○, ※, Greek, Cyrillic …) take two
	// columns; without it they take one (see Width).
	AmbiguousWide bool `json:"ambiguousWide,omitempty"`
	// Font is the family of the monospace font that the pages are drawn
	// with ("" for none named).
	Font string `json:"font,omitempty"`
	// Pages are the pages of the form, in the order of the pages of the
	// first view of the document.
	Pages []Page `json:"pages"`
}

Image is the print image of a form: the grid and the lines of its pages.

func Decode

func Decode(b []byte) (*Image, error)

Decode reads the JSON of a part, and checks it.

func FromDocument

func FromDocument(doc *bdf.Document) (*Image, error)

FromDocument reads the print image of a document being written. It returns ErrNone when it has none.

func Read

func Read(rd *bdf.Reader) (*Image, error)

Read reads the print image of an open document: its first part of the type bdf.PartText. It returns ErrNone when it has none.

func (*Image) AddTo

func (im *Image) AddTo(doc *bdf.Document) (bdf.Hash, error)

AddTo adds the image to a document as its part of the print image.

func (*Image) Cells

func (im *Image) Cells(l Line) []Cell

Cells returns the characters of a line of the image with their columns. Spaces are characters too.

func (*Image) Encode

func (im *Image) Encode() ([]byte, error)

Encode writes the image as the JSON of the part.

func (*Image) Rows

func (im *Image) Rows(p Page) int

Rows is the lines that a page prints: those of the paper without the top margin and the skip, or, on a roll (Lines 0), those of the page.

func (*Image) Text

func (im *Image) Text(o TextOptions) string

Text writes the image as plain text: its lines, ended by LF, and its pages separated by a form feed (FF). A character of double width is followed by the spaces of its other columns, so that the columns of the line stay those of the grid; the second line of a line of double height is an empty line.

type Line

type Line struct {
	// Text is the characters of the line from its first column (the left
	// margin is not in it), without spaces at its end. A character of a
	// double width range is in it once.
	Text string `json:"text"`
	// Paper are the ranges of the line that are of the preprinted paper
	// (the rules and the names of a printed form): they are drawn on the
	// page, as a layer of the role "background", and are not printed on
	// paper that has them already. They do not overlap and are in order.
	Paper []Range `json:"paper,omitempty"`
	// Size are the ranges of the line whose characters are printed double
	// in size (Range.Size). They do not overlap and are in order. A line
	// with a range of the size "tall" or "big" takes two lines of the
	// page: its own and the one under it, whose Text is empty. All of its
	// characters stand on the base line of the lower one (as ESC/POS
	// prints a line with characters of double height).
	Size []Range `json:"size,omitempty"`
}

Line is a line of a page.

func (Line) Tall

func (l Line) Tall() bool

Tall reports whether a line takes two lines of the page.

type Margin

type Margin struct {
	// Left is in columns, Top in lines.
	Left int `json:"left"`
	Top  int `json:"top"`
}

Margin is the room around the lines of a page.

type Page

type Page struct {
	// Lines are the lines of the page from the top margin down, a line
	// for each line of the grid: Lines[i] is line i. Lines past the last
	// one are empty.
	Lines []Line `json:"lines"`
}

Page is a page of the form.

type Range

type Range struct {
	// Col is the first column of the range, and Cols the number of its
	// columns as printed (a character of double width takes twice its
	// columns).
	Col  int `json:"col"`
	Cols int `json:"cols"`
	// Size is the size of the characters of a range of Line.Size:
	// SizeWide, SizeTall or SizeBig. A range of Line.Paper has none.
	Size string `json:"size,omitempty"`
}

Range is the columns of a part of a line.

type TextOptions

type TextOptions struct {
	// Margins writes the margins: spaces before each line, and empty
	// lines above the first.
	Margins bool
	// NoPaper writes the ranges of the paper as spaces, as they are
	// printed on paper that has them already.
	NoPaper bool
	// CRLF ends the lines with CR LF instead of LF.
	CRLF bool
}

TextOptions controls Image.Text.

Jump to

Keyboard shortcuts

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