Needlessly Postulating Minds
    Have ideas to improve npm?Join in the discussion! »

    receiptline

    1.5.3 • Public • Published

    receiptline

    Printable digital receipts 🧾

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

    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
    • SII RP series
    • Star MC series
    • Citizen CT series
    • Fujitsu FP series

    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: '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
      • cp1252: Western European
      • cp932: Japanese
      • shiftjis: Japanese
      • cp936: Simplified Chinese
      • gb18030: Simplified Chinese
      • cp949: Korean
      • ksc5601: Korean
      • cp950: Traditional Chinese
      • big5: Traditional Chinese
    • gradient (for printer)
      • false: image processing for text, barcodes, and 2D codes
      • true: image processing for photos (default)
    • gamma (for printer)
      • image gamma correction (range: 0.1 - 10.0, default: 1.8)
    • threshold (for printer)
      • image thresholding (range: 0 - 255, default: 128)
    • upsideDown (for printer)
      • false: normal (default)
      • true: upside down
    • spacing
      • false: no line spacing (default)
      • true: line spacing
    • cutting (for printer)
      • false: no paper cutting
      • true: paper cutting (default)
    • command
      • svg: SVG (default)
      • escpos: ESC/POS (Epson)
      • sii: ESC/POS (SII)
      • 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.

    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

    Designer

    Setup

    1. Start the server

      $ cd node_modules/receiptline
      $ npm start
    2. Open http://localhost:8080

      Use a modern browser.

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

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

      $ npm install serialport
      $ cd node_modules/receiptline
    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

      Please back up this json file as it will be initialized by updating the package.

    3. Restart the server

      $ npm start

    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

    • 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

    Install

    npm i receiptline

    DownloadsWeekly Downloads

    94

    Version

    1.5.3

    License

    Apache-2.0

    Unpacked Size

    664 kB

    Total Files

    94

    Last publish

    Collaborators

    • avatar