receiptline

Printable digital receipts 🧾

Transform markdown-like text to receipt printer commands or SVG images.

Features

The reference implementation of the OFSC ReceiptLine Specification.

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 with LAN support.

Receipt Printers

• Epson TM series
• SII 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: 'cp437',
    upsideDown: false,
    gamma: 1.8,
    command: 'escpos'
};
const command = receiptline.transform(doc, printer);

// display example
const display = {
    cpl: 42,
    encoding: 'cp437'
};
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)
• encoding
  • cp437: United States (default)
  • cp852: Central European
  • cp858: Western European
  • cp860: Portuguese
  • cp863: French Canadian
  • cp865: Nordic
  • cp866: Cyrillic
  • cp932: Japanese
  • cp1252: Western European
• gamma (for printer)
  • image gamma correction (default: 1.8)
• upsideDown (for printer)
  • false: normal (default)
  • true: upside down
• command
  • svg: SVG (default)
  • escpos: Epson, Citizen
  • sii: SII
  • starmbcs: Star MBCS
  • starsbcs: Star SBCS
  • fit: Fujitsu

Examples

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.

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

The ReceiptLine Designer provides more features.

• Edit and preview
• Data transmission via TCP socket
• Hex dump view by listening TCP 19100 port

Setup

1. Start the server

   $ cd node_modules/receiptline
   $ npm start

2. Open http://localhost:10080

   Use a modern browser.

3. Configure printers.json

   "printer_id": {
       "host": "127.0.0.1",
       "port": 19100,
       "cpl": 48,
       "encoding": "cp437",
       "gamma": 1.8,
       "upsideDown": false,
       "command": "svg"
   }

   • printer_id
     • printer identifier (alphanumeric or underscore characters)
   • host
     • printer address
   • port
     • printer port (will be 9100)
   • cpl, encoding, gamma, upsideDown, command
     • see the printer configuration above

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

Alignment

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

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.

Escape sequences in text

Escape special characters.

Properties

The property is valid for lines with a single column.

{ width: * 10; comment: the column width is specified in characters }

Barcode options

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

2D code options

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

Special characters in property values

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

Escape sequences in property values

Escape special characters.

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.

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