Documentation
¶
Overview ¶
Command bdfwasm is the converters built for the browser: a page hands it the bytes of a file and gets a BDF document back, so that the file never leaves the browser. Build it with
GOOS=js GOARCH=wasm go build -tags bdf_noconv -o bdf.wasm ./cmd/bdfwasm
and run it with Go's wasm_exec.js (in a Worker: a conversion keeps the thread busy). -tags pdfonly, officeonly, webonly or imageonly builds a smaller module of the PDF converters (PDF, and Illustrator, whose files are PDFs), the Office converters (Word, PowerPoint, Excel, CSV, Parquet, Visio, draw.io, DXF, Jw_cad, SXF, CGM, Gerber, KiCad, metafiles, Photoshop, the music formats MML, MIDI and MusicXML, font files, and images), the HTML, Markdown and EPUB converters, or the images browsers display by themselves (PNG, JPEG, SVG …, stored as they are) only; previewonly builds one without converters that makes the thumbnail, the search text and the PDF file of a bdf document, and formonly one that fills the templates of forms (see the end of this comment). bdf_noconv leaves out the image and WOFF2 encoders: a document drawn where it is converted gains nothing from them. It leaves out Brotli altogether, whose tables alone would add 1.7 MB to the Office module: the Parquet converter reads no Brotli in any js build (converter/parquet/brotli_js.go), and the font converter no WOFF2 file. bdf_woff2dec brings the decoder of WOFF2 back by itself, for the preview module, which reads the fonts of documents made by the bdf command. The demo site (examples/viewer/site.mjs) builds it with a copy of goldmark (the Markdown converter's parser) whose linkify patterns it rewrites: compiled when the program starts, they overflow the stack of a worker in Safari.
The program sets globalThis.bdfConverter and waits for calls:
bdfConverter.formats: [{name, description, extensions}]
bdfConverter.convert(data: Uint8Array, options?: {
format?: string, // a format name; detected from the content when absent
password?: string, // the open password of an encrypted input
fonts?: string, // URL of a font directory (see below)
name?: string, // the file name, whose extension tells what the content does not (Markdown, a CSV file of one line)
pages?: string, // the pages (slides, sheets) to convert, as bdf generate -pages takes them ("1" for a thumbnail); all when absent
params?: {[name: string]: string}, // the format's own options, as bdf generate -param takes them ({play: "false"})
}): Promise<{bdf: Uint8Array, format: string, summary: string, warnings: string[], protected: boolean}>
bdfConverter.open(data, options?): Promise<{bdf, format, pages: number, warnings, stream?}>
convert converts the input whole into a single-file bdf. open starts a conversion done a page at a time (converter.OpenStream), for a viewer that draws the pages as they are converted: with pages > 0, bdf is the outline (every page sized, the pages of the first view without layers) and stream converts the rest:
stream.page(i: number): Promise<{bdf: Uint8Array, warnings: string[]}>
stream.finish(): Promise<{bdf, format, summary, warnings, protected}>
stream.close(): void
page converts page i of the first view and returns a single-file bdf whose only page is that page, with the parts no earlier call returned; warnings are the new ones. finish returns the whole document, as convert makes it, with every warning. close lets the stream go (call it after finish too). A format that is not converted a page at a time comes back whole from open, with pages 0, a summary and no stream.
An audio file's document carries the file itself, which the viewer plays (converter/audio). Here the input, the document and the bytes returned are all in the module's memory at once, so the audio of a file larger than 64 MiB is left out (the card comes without it, with a warning); params.maxaudio, in MiB, sets another limit, and params.play "false" leaves the audio out of a document that is not for playing (one made for its text).
A failed conversion rejects with an Error whose code is "password-required", "wrong-password" or "unknown-format" when it is one of those. The document is not encrypted even when the input was.
The Office converters lay text out with the fonts of the font directory: index.json there lists its files as [{"name", "size", "scan", "url"}], where scan holds the [offset, length] ranges of the tables the font scan and fallback coverage checks read (the table directories, name, OS/2, post and cmap), fetched ahead in parallel. Fallback search checks cmap first; a font's whole file is fetched only when it can draw a needed character. url is optional: when absent the file is fetched beside index.json; when present it is resolved relative to that directory and may be an absolute HTTP(S) URL, such as a Google Fonts CDN font with CORS enabled. name remains the file name seen by the converters; size and scan describe the bytes at url. Remote files use the same range fetching and cache.
The preview module (-tags previewonly) makes of a single-file bdf what a server makes with packages thumbnail and bdf (Document.SearchText):
bdfConverter.thumbnail(bdf: Uint8Array, options?: {
size?: number, // pixels: the side of a cropped thumbnail, the longer side of a fitted one (default 256, at most 2048)
mode?: string, // "auto" (from the kind of document, as thumbnail.Auto), "crop" or "fit"
format?: string, // "png" (default), "jpeg", or "webp" (not with bdf_noconv)
view?: string, // the id of the view to draw (default: the first)
password?: string, // the password of an encrypted document
fonts?: string, // URL of a font directory, for text in fonts referred to by name
}): Promise<{image: Uint8Array, format: string, width: number, height: number, mode: "crop" | "fit", warnings: string[]}>
bdfConverter.text(bdf: Uint8Array, options?: {password?: string}): Promise<{json: string}>
text returns what bdf text writes: the metadata and the text of each page, as JSON. Neither the thumbnail nor the text is encrypted when the document is; an encrypted document without its password rejects with "password-required".
The preview module and the form module write a single-file bdf as a PDF file, as bdf pdf does (vector/pdfbdf):
bdfConverter.pdf(bdf: Uint8Array, options?: {
password?: string, // the password of an encrypted document (the file is not encrypted)
fonts?: string, // URL of a font directory, for text in fonts referred to by name
views?: string[], // the ids of the views to write (default: those with pages)
skip?: string[], // roles of layers to leave out ("background", "master")
tagged?: boolean, // a tagged PDF: with the structure of the document, for screen readers
pdfa?: string, // a PDF/A file: "2b", "2u", "2a" (tagged), "3b", "3u" or "3a"
}): Promise<{pdf: Uint8Array, pages: number, fonts: number, warnings: string[]}>
The form module (-tags formonly) has the converters of the templates of forms (Word, Excel, PowerPoint, PDF forms and the templates of pdfme) and package form: it reads what a template asks of data (its tags, or its fields), and fills it with data, as bdf template schema and bdf fill do:
bdfConverter.fields(template: Uint8Array, options?: {
sample?: string, // sample data, as JSON: it settles where the names are and the types of their values
}): Promise<{fields: string, schema: string, format: string, sample?: string}>
bdfConverter.fill(template: Uint8Array, options: {
data: string, // the data, as the JSON of an object
files?: {[path: string]: Uint8Array}, // the pictures that the data names
strict?: boolean, // fail when the data lacks a name of a tag
fonts?, name?, pages?, params? // as convert takes them
}): Promise<{bdf: Uint8Array, format: string, pages: number, warnings: string[]}>
fields and schema are JSON texts: the names that the tags look up, and the JSON Schema of the data (form.Schema), which a page makes a form of. format is the format of the template ("xlsx", "docx", "pptx", "pdf", "pdfme"; of a compiled template, .bdft, that of the template it holds), and sample the sample of the data that the template has for itself: a compiled template, and a template of pdfme (what its designer left in its fields).