README
receiptline
Markdown for receipts. Printable digital receipts. 🧾
Generate receipt printer commands and SVG images.
ReceiptIO - Simple and easy API and CLI using receiptline, supporting printer status.
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
- Seiko Instruments RP series
- Star MC series
- Citizen CT series
- Fujitsu FP series
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
doc
- a string of ReceiptLine document
printer
- an object of printer configuration
Return value
- printer commands or SVG images
Printer configuration
cpl
- characters per line (default:
48
)
- characters per line (default:
encoding
multilingual
: Multilingual (including cp437, cp852, cp858, cp866, cp1252)cp437
: United States (default)cp852
: Central Europeancp858
: Western Europeancp860
: Portuguesecp863
: French Canadiancp865
: Nordiccp866
: Cyrilliccp1252
: Western Europeancp932
: Japaneseshiftjis
: Japanesecp936
: Simplified Chinesegb18030
: Simplified Chinesecp949
: Koreanksc5601
: Koreancp950
: Traditional Chinesebig5
: Traditional Chinese
gradient
(for printer)false
: image processing for text, barcodes, and 2D codestrue
: image processing for photos (default)
gamma
(for printer)- image gamma correction (range:
0.1
-10.0
, default:1.8
)
- image gamma correction (range:
threshold
(for printer)- image thresholding (range:
0
-255
, default:128
)
- image thresholding (range:
upsideDown
(for printer)false
: normal (default)true
: upside down
spacing
false
: no line spacing (default)true
: line spacing
cutting
(for printer)false
: no paper cuttingtrue
: paper cutting (default)
command
svg
: SVG (default)escpos
: ESC/POS (Epson)sii
: ESC/POS (Seiko Instruments)citizen
: ESC/POS (Citizen)fit
: ESC/POS (Fujitsu)impact
: ESC/POS (TM-U220)impactb
: ESC/POS (TM-U220 Font B)starsbcs
: StarPRNT (SBCS)starmbcs
: StarPRNT (Japanese)starmbcs2
: StarPRNT (Chinese, Korean)starlinesbcs
: Star Line Mode (SBCS)starlinembcs
: Star Line Mode (Japanese)starlinembcs2
: Star Line Mode (Chinsese, Korean)emustarlinesbcs
: Command Emulator Star Line Mode (SBCS)emustarlinembcs
: Command Emulator Star Line Mode (Japanese)emustarlinembcs2
: Command Emulator Star Line Mode (Chinsese, Korean)stargraphic
: Star Graphic Mode (TSP100LAN)
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.
- Edit and preview
- Data transmission via TCP socket
- Hex dump view by listening TCP 19100 port
Setup
Start the server
$ cd node_modules/receiptline $ npm start
Open http://localhost:8080
Use a modern browser.
Configure printers.json
"printer_id": { "host": "127.0.0.1", "port": 19100, "asImage": false, "cpl": 48, "encoding": "cp932", "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
)
- printer port (will be
asImage
false
: print with device font (default)true
: print as image (Requires convert-svg-to-png)
cpl
,encoding
,gradient
,gamma
,threshold
,upsideDown
,spacing
,cutting
,command
- see the printer configuration above
Please back up this json file as it will be initialized by updating the package.
Serial-LAN Converter
The serial-LAN converter enables test printing to USB / Bluetooth printers that support virtual serial ports.
Setup
Install the virtual serial port driver for the printer and Node Serialport
$ npm install serialport $ cd node_modules/receiptline
Configure servers.json
"serial": { "host": "127.0.0.1", "port": 9100, "device": "COM9" }
serial
- to enable it, change from
_serial
- to enable it, change from
host
- local address
port
- local port
device
- the system path of the serial port
Please back up this json file as it will be initialized by updating the package.
Restart the server
$ npm start
Syntax
Railroad diagram
document
line
columns
column
text
char
escape
ws (whitespace)
property
member
key
value
Grammar
Structure
The receipt is made of a table, which separates each column with a pipe |
.
Line | Content | Description |
---|---|---|
column| column | | columncolumn | |
Text Property |
Single column |
column | column | column | column | | column | columncolumn | column | |
Text | Double column |
column | ... | column| column | ... | column | | column | ... | columncolumn | ... | 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 |
\x nn |
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 |
\x nn |
Hexadecimal character code |
\ char (Others) |
Ignore |
Restrictions
- Communication with the printer, status event processing, and error handling are out of scope.
- SVG images depend on the font family installed on the computer and may not display properly.
- The QR code for display is encoded in UTF-8, while the QR code for printing is encoded in ASCII or Shift_JIS.
- Impact printer has some limitations for printing.
- Characters larger than 2x size
- Inverted characters (will be printed in red)
- Double height characters in different colors on the same line
- Multibyte characters
- Image position and size ratio
- Barcodes and 2D codes
- Star Graphic Mode printing only supports images, line feeds, and paper cuts.
Author
Open Foodservice System Consortium
http://www.ofsc.or.jp/
License
- receiptline
- Apache License, Version 2.0
- QR Code Generator for JavaScript with UTF8 Support
- MIT License