receiptline

Markdown for receipts. Printable digital receipts. 🧾
Generate receipt printer commands and SVG images.

"ReceiptLine" is a coined word from "Receipt" and "Streamline".
Make it more efficient by making it simpler!

ReceiptIO - Simple and easy API and CLI using receiptline, supporting printer status.

English
Japanese
German

Features

The reference implementation of the OFSC ReceiptLine Specification.
http://www.ofsc.or.jp/receiptline/en/

ReceiptLine is the receipt description language that expresses the output image of small roll paper.
It supports printing paper receipts using a receipt printer and displaying electronic receipts on a POS system or smartphone.
It can be described simply with markdown-like text data that does not depend on the paper width.

This reference implementation also provides the development tool "ReceiptLine Designer" for editing, previewing, hex dumps with a virtual printer, and test printing on receipt printers.

Receipt Printers

Epson TM series (South Asia model) and Star MC series (StarPRNT model) can print with device font of Thai characters.

Printers

Installation

$ npm install receiptline

Usage

receiptline.transform() method transforms ReceiptLine document to printer commands or SVG images. 

const receiptline = require('receiptline');

const doc = '{code:2012345678903;option:ean,hri}';

// printer example
const printer = {
    cpl: 42,
    encoding: 'multilingual',
    upsideDown: false,
    gamma: 1.8,
    command: 'escpos'
};
const command = receiptline.transform(doc, printer);

// display example
const display = {
    cpl: 42,
    encoding: 'multilingual'
};
const svg = receiptline.transform(doc, display);

Method

receiptline.transform(doc[, printer])

Parameters

Return value

Printer configuration

Transform stream API

receiptline.createTransform() method is the stream version of the receiptline.transform(). 

const fs = require('fs');
const receiptline = require('receiptline');

const source = fs.createReadStream('example.txt');
const transform = receiptline.createTransform({ command: 'svg' });
const destination = fs.createWriteStream('example.svg');

source.pipe(transform).pipe(destination);

Method

receiptline.createTransform([printer])

Parameters

Return value

Examples

example/receipt/*

Display digital receipts in the web browser and print paper receipts on the printer as needed.

example/cloud/*

Print order slips from cloud server using Epson Server Direct Print or Star CloudPRNT.

example/nodejs/*

Enter markdown-like text from the web form, transform it to printer commands on the server, and print it out.

example/js/*

Enter markdown-like text from the web form, transform it to SVG images on the web browser, and display it.

example/data/*

The documents (markdown-like text) are the same as the examples in the OFSC ReceiptLine Specification.

example/command/*

Customize the command object to output your own commands.

Libraries

lib/receiptline.js

JavaScript ES2015(ES6) version. It works on both web browser and Node.js.
To output printer commands on a web browser, use Browserify. 

$ browserify -o receiptline-full.js receiptline.js

lib/qrcode-generator/qrcode.js

Generate the QR Code for display. Optional.

ReceiptLine Designer

Online version is available.
https://receiptline.github.io/designer/

The ReceiptLine Designer provides more features.

Designer

Setup

  1. Copy the following files to your working directory

    • designer/*
    • designer.js
    • printers.json
    • servers.json

  2. Start the server

    $ node designer.js

  3. Open http://localhost:8080

    Use a modern browser.

  4. Configure printers.json

    "printer_id": {
    "host": "127.0.0.1",
    "port": 19100,
    "asImage": false,
    "cpl": 48,
    "encoding": "shiftjis",
    "gradient": true,
    "gamma": 1.8,
    "threshold": 128,
    "upsideDown": false,
    "spacing": true,
    "cutting": true,
    "command": "escpos"
}
    • printer_id
      • printer identifier (alphanumeric or underscore characters)
    • host
      • printer address
    • port
      • printer port (will be 9100)
    • asImage
      • false: print with device font (default)
      • true: print as image (Requires puppeteer or sharp)
    • cpl, encoding, gradient, gamma, threshold, upsideDown, spacing, cutting, command
      • see the printer configuration above

Serial-LAN Converter

The serial-LAN converter enables test printing to USB / Bluetooth printers that support virtual serial ports.

Setup

  1. Install the virtual serial port driver for the printer and Node Serialport

    $ npm install serialport

  2. Configure servers.json

    "serial": {
    "host": "127.0.0.1",
    "port": 9100,
    "device": "COM9"
}
    • serial
      • to enable it, change from _serial
    • host
      • local address
    • port
      • local port
    • device
      • the system path of the serial port

  3. Restart the server

    $ node designer.js

Syntax

Railroad diagram

document
document

line
line

columns
columns

column
column

text
text

char
char

escape
escape

ws (whitespace)
ws

property
property

member
member

key
key

value
value

Grammar

Structure

The receipt is made of a table, which separates each column with a pipe |.

Line Content Description
column
| column |
| column
column |		 Text
Property		 Single column
column | column
| column | column |
| column | column
column | column |		 Text Double column
column | ... | column
| column | ... | column |
| column | ... | column
column | ... | column |		 Text Multiple columns

Alignment

The column is attracted to the pipe | like a magnet.
␣ means one or more whitespaces.

Column Description
column
|column|
|␣column␣|		 Center
|column
|column␣|
column␣|		 Left
column|
|␣column|
|␣column		 Right

Text

The text is valid for any column. 

Asparagus | 0.99
Broccoli | 1.99
Carrot | 2.99
---
^TOTAL | ^5.97

Characters are printed in a monospace font (12 x 24 px).
Wide characters are twice as wide as Latin characters (24 x 24 px).
Control characters are ignored.

Special characters in text

Special characters are assigned to characters that are rarely used in the receipt.

Special character Description
\ Character escape
| Column delimiter
{ Property delimiter (Start)
} Property delimiter (End)
- (1 or more, exclusive) Horizontal rule
= (1 or more, exclusive) Paper cut
~ Space
_ Underline
" Emphasis
` Invert
^ Double width
^^ Double height
^^^ 2x size
^^^^ 3x size
^^^^^ 4x size
^^^^^^ 5x size
^^^^^^^ (7 or more) 6x size

Escape sequences in text

Escape special characters.

Escape sequence Description
\\ \
\| |
\{ {
\} }
\- - (Cancel horizontal rule)
\= = (Cancel paper cut)
\~ ~
\_ _
\" _
\` `
\^ ^
\n Wrap text manually
\xnn Hexadecimal character code
\char (Others) Ignore

Properties

The property is valid for lines with a single column. 

{ width: * 10; comment: the column width is specified in characters }
Key Abbreviation Value Case-sensitive Default Saved Description
image i base64 png format ✓ - - Image
(Recommended: monochrome, critical chunks only)
code c textdata ✓ - - Barcode / 2D code
option o see below - code128 2 72 nohri 3 l ✓ Barcode / 2D code options
(Options are separated by commas or one or more whitespaces)
align a left
center
right		 - center ✓ Line alignment
(Valid when line width < CPL)
width w auto
*
0 -		 - auto
(* for all columns)		 ✓ Column widths (chars)
(Widths are separated by commas or one or more whitespaces)
border b line
space
none
0 - 2		 - space ✓ Column border (chars)
(Border width: line=1, space=1, none=0)
text t wrap
nowrap		 - wrap ✓ Text wrapping
command x textdata ✓ - - Device-specific commands
comment _ textdata ✓ - - Comment

Barcode options

Barcode options are separated by commas or one or more whitespaces.

Barcode option Description
upc UPC-A, UPC-E
(Check digit can be omitted)
ean
jan		 EAN-13, EAN-8
(Check digit can be omitted)
code39 CODE39
itf Interleaved 2 of 5
codabar
nw7		 Codabar (NW-7)
code93 CODE93
code128 CODE128
2 - 4 Barcode module width (px)
24 - 240 Barcode module height (px)
hri With human readable interpretation
nohri Without human readable interpretation

2D code options

2D code options are separated by commas or one or more whitespaces.

2D code option Description
qrcode QR Code
3 - 8 Cell size (px)
l
m
q
h		 Error correction level

Special characters in property values

Special characters in property values are different from special characters in text.

Special character Description
\ Character escape
| Column delimiter
{ Property delimiter (Start)
} Property delimiter (End)
: Key-value separator
; Key-value delimiter

Escape sequences in property values

Escape special characters.

Escape sequence Description
\\ \
\| |
\{ {
\} }
\; ;
\n New line
\xnn Hexadecimal character code
\char (Others) Ignore

Restrictions

Author

Open Foodservice System Consortium
http://www.ofsc.or.jp/

License