From a19bf0aa4474f05e41c4e8ed6c337a80f42d0494 Mon Sep 17 00:00:00 2001
From: yabu76 <yabu76@gmail.com>
Date: Sun, 22 Feb 2026 16:40:57 +0900
Subject: [PATCH] Add Lua API tio.twrite's documentation and example

---
 README.md               | 10 ++++++++--
 examples/lua/twrite.lua | 22 ++++++++++++++++++++++
 man/tio.1.in            |  9 +++++++--
 man/tio.1.txt           |  9 +++++++--
 4 files changed, 44 insertions(+), 6 deletions(-)
 create mode 100644 examples/lua/twrite.lua

diff --git a/README.md b/README.md
index 78d4ce7..bed9bd9 100644
--- a/README.md
+++ b/README.md
@@ -424,9 +424,15 @@ line may be returned as a second return value.
 
 #### `tio.write(string)`
 
-Write string to serial device.
+Write string to serial device without any of input-editing, output-mapping or output-delay.
 
-Returns the `tio` table.
+Returns the tio table on success or nil on error.
+
+#### `tio.twrite(string)`
+
+Write string to serial device with input-editing, output-mapping and output-delay.
+
+Returns the tio table on success or nil on error.
 
 #### `tio.send(file, protocol)`
 
diff --git a/examples/lua/twrite.lua b/examples/lua/twrite.lua
new file mode 100644
index 0000000..adfe8e0
--- /dev/null
+++ b/examples/lua/twrite.lua
@@ -0,0 +1,22 @@
+--
+-- tio.twrite() uses output-mapping, output-delay and input-mode.
+--
+-- Input-mode HEX is very slow, so it has limited use.
+--
+-- This script sends
+--   Hello.
+--   This is Hex mode.
+--   Bye.
+--
+
+tio.set_input_mode(tio.C.IM_NORMAL)
+tio.twrite("Hello.\r\n")
+
+tio.set_input_mode(tio.C.IM_HEX)
+tio.twrite("5468697320697320486578206d6f64652e0d0a") -- "This is Hex mode."
+
+tio.set_input_mode(tio.C.IM_LINE)
+tio.twrite("Bye.\r\n")
+
+tio.set_input_mode(tio.C.IM_NORMAL)
+
diff --git a/man/tio.1.in b/man/tio.1.in
index dd8243e..2aa53ae 100644
--- a/man/tio.1.in
+++ b/man/tio.1.in
@@ -469,9 +469,14 @@ Returns a string on success and nil on timeout.  On timeout a partially read
 line may be returned as a second return value.
 
 .IP "\fBtio.write(string)"
-Write string to serial device.
+Write string to serial device without Input-editing, Output-mapping nor Output-delay.
 
-Returns the tio table.
+Returns the tio table on success or nil on error.
+
+.IP "\fBtio.twrite(string)"
+Write string to serial device with Input-editing, Output-mapping and Output-delay.
+
+Returns tio table on success or nil on error.
 
 .IP "\fBtio.send(file, protocol)"
 Send file using x/y-modem protocol.
diff --git a/man/tio.1.txt b/man/tio.1.txt
index f3344a0..f863e23 100644
--- a/man/tio.1.txt
+++ b/man/tio.1.txt
@@ -381,9 +381,14 @@ SCRIPT API
              On success, returns the string that was read as second return value.  Also emits a single timestamp to stdout and log file per options.timestamp and options.log.
 
        write(string)
-             Write string to serial device.
+             Write string to serial device without Input-editing, Output-mapping nor Output-delay.
 
-             Returns number of bytes written on success or -1 on error.
+             Returns the tio table on success or nil on error.
+
+       twrite(string)
+             Write string to serial device with Input-editing, Output-mapping and Output-delay.
+
+             Returns the tio table on success or nil on error.
 
        send(file, protocol)
              Send file using x/y-modem protocol.