thermal 0.1.1 → 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: b18797f5189d89f1f7326ab9eb8a131c1c0a98f37fc76b10469e4a67bddf5c47
+  data.tar.gz: 509efa5bfc9b51dd736b30c9f215d36e8f15fc2a578c7039b9bcd60915929554
+SHA512:
+  metadata.gz: ecef3e5aba6e5d6b296762f53f6b809a2d4950c32232790138cff89ad8beb49439147cd5da89635f1002664c12fb9b9e4595a453a344ce8db148a0c330e2b0d7
+  data.tar.gz: cfb8b73b14a9bc09ad839066f888e35574c8ec00986787f6e0c666cfddd7d2c9eaa295483867b10297ff389c4c7bfc3b67fa06d6ec8db8c4e5b42e78aa55c254

data/LICENSE

@@ -1,20 +1,21 @@
-Copyright (c) 2012 Tyler Kellen
-
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to deal in the Software without restriction, including
-without limitation the rights to use, copy, modify, merge, publish,
-distribute, sublicense, and/or sell copies of the Software, and to
-permit persons to whom the Software is furnished to do so, subject to
-the following conditions:
-
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+MIT License
+
+Copyright (c) 2025 Johnny Shields & TableCheck
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -1,27 +1,200 @@
-# thermal
-> Convert basic HTML into thermal printer codes.
-
-This is a work in progress.
-
-Supported devices:
-- BTP-R880NP
-
-## Setup
-
-```console
-gem install thermal
-```
-
-## Usage
-
-```ruby
-require 'thermal'
-
-parser = Thermal::Parser.new(BTPR880)
-
-BTPR880.print('192.168.1.200', 9100) do |print|
-  print.puts parser.process('<strong>bold <u>underline</u></strong>')
-end
-```
-
-> Copyright (c) 2013 Tyler Kellen. See LICENSE for further details.
+# Thermal 🖨️
+
+Thermal printer support for Ruby. Used to print receipts, chits, tickets, labels, etc.
+
+[![Gem Version](https://badge.fury.io/rb/thermal.svg)](https://badge.fury.io/rb/thermal)
+[![CI](https://github.com/tablecheck/thermal/actions/workflows/ci.yml/badge.svg)](https://github.com/tablecheck/thermal/actions/workflows/ci.yml)
+[![Ruby Style Guide](https://img.shields.io/badge/code_style-rubocop-brightgreen.svg)](https://github.com/rubocop/rubocop)
+[![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](https://opensource.org/licenses/MIT)
+
+## ⚠️ WARNING: Gem under active development
+
+**All APIs and features should be considered unstable before 1.0.0 release.**
+
+### ✨ Features
+
+- 🎯 Simple and opinionated API. **It just works™**
+- 🎨 Generates **rich text, image, and QR codes** for thermal printers.
+- 🏭 Supports a broad range of **makers and models** (Epson, Star Micronics, Brother, PBM, Zijiang, etc.)
+- 🌐 Automatic **multi-lingual** codepage support, including support for **CJK extended character sets**.
+- 📝 **Simple DSL** for rich text output formatting.
+- 🦋 **Graceful degradation** of features based on printer capabilities.
+
+### 🔌 Optional Features
+
+- **QR code generation** 📱
+  - Requires [rqrcode](https://github.com/whomwah/rqrcode) gem.
+- Support for **Stargraphic (raster-only format)** using system-side font rendering. 🖼️
+  - See requirements below.
+
+### 📤 Supported Output Formats
+
+- Epson ESC/POS
+  - Industry standard used by most thermal printers
+- Star Micronics-specific formats
+  - Star Micronics Extended ESC/POS (UTF-8)
+  - Starprnt
+  - Stargraphic
+
+### ❌ Non-Features & Limitations
+
+- **HTML-to-text support** (planned, not yet released) 🔄
+  - Requires [nokogiri](https://nokogiri.org/) gem.
+- **No support for wire protocols** such as USB, Bluetooth, etc. This gem is intended
+  to run on a server; it only generates the instructions/bytes to be sent to the client
+- (browser, iOS, etc.) which should then send it to the end device.
+  - **PR welcome** if someone wants to add USB/Bluetooth support.
+- **Pixel-only printer support (Stargraphic) is rudimentary and slow** 🐢, because
+  it uses system-side font rendering ([Pango](https://www.pango.org/)) to generate
+  the image data.
+  - **PR welcome** to use a different approach and/or make it faster.
+- Table formatting support not yet added. **PR welcome**.
+- Indian ISCII encoding for Escpos is not yet supported. **PR welcome**.
+
+## 🚀 How to Use
+
+### 📦 Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'thermal'
+```
+
+### 🖨️ Formatting your Output
+
+#### ⌨️ Procedural code
+
+Intended API: (needs to be further extracted)
+
+```ruby
+printer = Thermal::Printer.new(device: :espon_tm_t88v)
+printer.text('Contra felicem vix deus vires habet')
+printer.align_center
+printer.text('Quam vellem nescire litteras!')
+printer.flush # todo: #print!?
+```
+
+#### 🧩 DSL
+
+You can also use it as a DSL:
+
+```ruby
+# TODO: Example text should look like an actual receipt
+class MyChitPrinter
+  include Thermal::Dsl
+
+  def initialize
+    @printer = Thermal::Printer.new(device: :espon_tm_t88v)
+  end
+
+  def print
+    thermal_print do # TODO: does this flush automatically?
+      bold do
+        text('Contra felicem vix deus vires habet')
+        align(:center) do
+          text('Quam vellem nescire litteras!')
+        end
+        # html do
+        #
+        # end
+        # html('<b>foo</b>')
+      end
+    end
+  end
+end
+```
+
+#### 📃 HTML Conversion
+
+```ruby
+# TODO: float/tables?
+# h1
+# h2
+# h3
+# 
+```
+
+### 🚢 Integrating Thermal into your App
+
+- Add details of how to implement a thermal printer config.
+
+
+### 🛠️ Advanced Considerations
+
+#### 🧵 Thread-Safety
+
+- Thermal's internals are thread-safe in principle.
+- However, don't use the same `Thermal::Printer` object from multiple threads.
+  You're gonna have a bad time. 😵
+
+### 📝 TODOs
+
+#### ✅ Required before 1.0.0 release
+
+- [ ] Add render method instead of flush
+- [ ] Add task to import config from escpos-printer-db
+- [ ] Rename CjkEncoding to RubyEncoding, rename CharmapEncoding, CharsetEncoding, also add IconvEncoding
+- [ ] Encoding classes themselves should validate missing char (move from Escpos::Buffer class)
+- [ ] Iconv config generator rake task.
+- [ ] Set output format for thermal_print (default, base64, bytes, etc.)
+- [ ] Params for escpos: :codepages, escpos: charsets
+- [ ] Copy in Escpos and EscposImage gems (get rid of dependency)
+- [ ] Param pass-thru to EscposImage
+- [ ] Configurability of tmp path -- specific to stargraphic (?) -- Should use Tempfile
+- [ ] Write Readme
+- [ ] DslMixin should include protocol (?), ipp_uri (?) -- why??
+- [ ] Specs for all classes, including base.
+- [ ] StarGraphic needs multiple message buffering. ???
+- [ ] Add QR to DSL
+
+#### ✨ Nice to haves
+
+- [ ] font support. col_width should be dynamic in the printer (currently depends on font 0)
+- [ ] Copy "Available methods" from https://github.com/escpos/escpos-php
+- [ ] Add HTML command in addition to text. Should be done as an AST (HtmlAst) like [[:text, 'ddd'], [:underline, 2, [[:text, 'foo']]]]
+- [ ] Optional HTML image support
+- [ ] Copy TestReport
+- [ ] Stargraphic needs much better buffer support, including line break splitting + multiple buffers.
+- [ ] Allow pass-in of codepage object.
+- [ ] Allow pass-in of charset object.
+- [ ] Indian ISCII encoding for Escpos (separate gem?).
+
+# 🙏 Contributing
+
+To add support for additional Thermal printers.
+- escpos-printer-db
+- Add new code in `lib/thermal/printer/escpos.rb`
+- Add new code in `lib/thermal/printer/starprnt.rb`
+
+# 💖 Acknowledgements
+
+### 👨‍💻 Maintainers
+
+Thermal is maintained and battle-tested by the team at [TableCheck](https://www.tablecheck.com/en/join/)
+based in Tokyo, Japan. 🗼 We use Thermal to help our restaurant users print chits, receipts, and
+QR codes to serve their guests' reservations. If you are seeking your next career adventure,
+[we're hiring](https://careers.tablecheck.com/)!
+
+### 📚 Data Sources
+
+This gem relies on the community-maintained
+[escpos-printer-db](https://github.com/receipt-print-hq/escpos-printer-db)
+to provide a comprehensive list of thermal printers.
+
+### 🌟 Special Thanks
+
+This gem draws inspiration from the following libraries.
+Thank you to the authors for their hard work.
+- [escpos-php](https://github.com/escpos/escpos-php)
+- [escpos-printer-db](https://github.com/receipt-print-hq/escpos-printer-db)
+- [EscPosEncoder JS](https://github.com/NielsLeenheer/EscPosEncoder/blob/master/src/esc-pos-encoder.js)
+
+### ©️ Copyright Attribution
+
+The vendor manuals in the `doc/vendor` directory are the property of their respective owners.
+They are included here for references purposes only under the fair use doctrine.
+
+### 📜 License
+
+This gem is released under the MIT License. Please see the [LICENSE](LICENSE) file for details.