aboutsummaryrefslogtreecommitdiff
path: root/docs/modules/system.html
diff options
context:
space:
mode:
Diffstat (limited to 'docs/modules/system.html')
-rw-r--r--docs/modules/system.html944
1 files changed, 492 insertions, 452 deletions
diff --git a/docs/modules/system.html b/docs/modules/system.html
index 0934b35..6840b85 100644
--- a/docs/modules/system.html
+++ b/docs/modules/system.html
@@ -37,7 +37,12 @@
37<li><a href="#Environment">Environment </a></li> 37<li><a href="#Environment">Environment </a></li>
38<li><a href="#Random">Random </a></li> 38<li><a href="#Random">Random </a></li>
39<li><a href="#Terminal">Terminal </a></li> 39<li><a href="#Terminal">Terminal </a></li>
40<li><a href="#Terminal_Windows">Terminal_Windows</a></li>
41<li><a href="#Terminal_Posix">Terminal_Posix</a></li>
42<li><a href="#Terminal_Input">Terminal_Input</a></li>
43<li><a href="#Terminal_UTF_8">Terminal_UTF-8</a></li>
40<li><a href="#Time">Time </a></li> 44<li><a href="#Time">Time </a></li>
45<li><a href="#Terminal_Backup">Terminal_Backup</a></li>
41</ul> 46</ul>
42 47
43 48
@@ -112,97 +117,93 @@
112<h2><a href="#Terminal">Terminal </a></h2> 117<h2><a href="#Terminal">Terminal </a></h2>
113<table class="function_list"> 118<table class="function_list">
114 <tr> 119 <tr>
115 <td class="name" nowrap><a href="#CODEPAGE_UTF8">CODEPAGE_UTF8</a></td> 120 <td class="name" nowrap><a href="#isatty">isatty (file)</a></td>
116 <td class="summary">UTF8 codepage.</td> 121 <td class="summary">Checks if a file-handle is a TTY.</td>
117 </tr>
118 <tr>
119 <td class="name" nowrap><a href="#_readkey">_readkey ()</a></td>
120 <td class="summary">Reads a key from the console non-blocking.</td>
121 </tr>
122 <tr>
123 <td class="name" nowrap><a href="#autotermrestore">autotermrestore ()</a></td>
124 <td class="summary">Backs up terminal settings and restores them on application exit.</td>
125 </tr>
126 <tr>
127 <td class="name" nowrap><a href="#detachfds">detachfds ()</a></td>
128 <td class="summary">Creates new file descriptions for <code>stdout</code> and <code>stderr</code>.</td>
129 </tr> 122 </tr>
130 <tr> 123 <tr>
131 <td class="name" nowrap><a href="#getconsolecp">getconsolecp ()</a></td> 124 <td class="name" nowrap><a href="#termsize">termsize ()</a></td>
132 <td class="summary">Gets the current console code page (Windows).</td> 125 <td class="summary">Get the size of the terminal in rows and columns.</td>
133 </tr> 126 </tr>
127</table>
128<h2><a href="#Terminal_Windows">Terminal_Windows</a></h2>
129<table class="function_list">
134 <tr> 130 <tr>
135 <td class="name" nowrap><a href="#getconsoleflags">getconsoleflags (file)</a></td> 131 <td class="name" nowrap><a href="#getconsoleflags">getconsoleflags (file)</a></td>
136 <td class="summary">Gets console flags (Windows).</td> 132 <td class="summary">Gets console flags (Windows).</td>
137 </tr> 133 </tr>
138 <tr> 134 <tr>
139 <td class="name" nowrap><a href="#getconsoleoutputcp">getconsoleoutputcp ()</a></td> 135 <td class="name" nowrap><a href="#listconsoleflags">listconsoleflags (fh)</a></td>
140 <td class="summary">Gets the current console output code page (Windows).</td> 136 <td class="summary">Debug function for console flags (Windows).</td>
141 </tr> 137 </tr>
142 <tr> 138 <tr>
143 <td class="name" nowrap><a href="#getnonblock">getnonblock (fd)</a></td> 139 <td class="name" nowrap><a href="#setconsoleflags">setconsoleflags (file, bitflags)</a></td>
144 <td class="summary">Gets non-blocking mode status for a file (Posix).</td> 140 <td class="summary">Sets the console flags (Windows).</td>
145 </tr> 141 </tr>
142</table>
143<h2><a href="#Terminal_Posix">Terminal_Posix</a></h2>
144<table class="function_list">
146 <tr> 145 <tr>
147 <td class="name" nowrap><a href="#isatty">isatty (file)</a></td> 146 <td class="name" nowrap><a href="#detachfds">detachfds ()</a></td>
148 <td class="summary">Checks if a file-handle is a TTY.</td> 147 <td class="summary">Creates new file descriptions for <code>stdout</code> and <code>stderr</code>.</td>
149 </tr> 148 </tr>
150 <tr> 149 <tr>
151 <td class="name" nowrap><a href="#listconsoleflags">listconsoleflags (fh)</a></td> 150 <td class="name" nowrap><a href="#getnonblock">getnonblock (fd)</a></td>
152 <td class="summary">Debug function for console flags (Windows).</td> 151 <td class="summary">Gets non-blocking mode status for a file (Posix).</td>
153 </tr> 152 </tr>
154 <tr> 153 <tr>
155 <td class="name" nowrap><a href="#listtermflags">listtermflags (fh)</a></td> 154 <td class="name" nowrap><a href="#listtermflags">listtermflags (fh)</a></td>
156 <td class="summary">Debug function for terminal flags (Posix).</td> 155 <td class="summary">Debug function for terminal flags (Posix).</td>
157 </tr> 156 </tr>
158 <tr> 157 <tr>
159 <td class="name" nowrap><a href="#readansi">readansi (timeout[, fsleep=system.sleep])</a></td> 158 <td class="name" nowrap><a href="#setnonblock">setnonblock (fd, make_non_block)</a></td>
160 <td class="summary">Reads a single key, if it is the start of ansi escape sequence then it reads 159 <td class="summary">Enables or disables non-blocking mode for a file (Posix).</td>
161 the full sequence.</td>
162 </tr>
163 <tr>
164 <td class="name" nowrap><a href="#readkey">readkey (timeout[, fsleep=system.sleep])</a></td>
165 <td class="summary">Reads a single byte from the console, with a timeout.</td>
166 </tr> 160 </tr>
167 <tr> 161 <tr>
168 <td class="name" nowrap><a href="#setconsolecp">setconsolecp (cp)</a></td> 162 <td class="name" nowrap><a href="#tcgetattr">tcgetattr (fd)</a></td>
169 <td class="summary">Sets the current console code page (Windows).</td> 163 <td class="summary">Get termios state (Posix).</td>
170 </tr> 164 </tr>
171 <tr> 165 <tr>
172 <td class="name" nowrap><a href="#setconsoleflags">setconsoleflags (file, bitflags)</a></td> 166 <td class="name" nowrap><a href="#tcsetattr">tcsetattr (fd, actions, termios)</a></td>
173 <td class="summary">Sets the console flags (Windows).</td> 167 <td class="summary">Set termios state (Posix).</td>
174 </tr> 168 </tr>
169</table>
170<h2><a href="#Terminal_Input">Terminal_Input</a></h2>
171<table class="function_list">
175 <tr> 172 <tr>
176 <td class="name" nowrap><a href="#setconsoleoutputcp">setconsoleoutputcp (cp)</a></td> 173 <td class="name" nowrap><a href="#_readkey">_readkey ()</a></td>
177 <td class="summary">Sets the current console output code page (Windows).</td> 174 <td class="summary">Reads a key from the console non-blocking.</td>
178 </tr> 175 </tr>
179 <tr> 176 <tr>
180 <td class="name" nowrap><a href="#setnonblock">setnonblock (fd, make_non_block)</a></td> 177 <td class="name" nowrap><a href="#readansi">readansi (timeout[, fsleep=system.sleep])</a></td>
181 <td class="summary">Enables or disables non-blocking mode for a file (Posix).</td> 178 <td class="summary">Reads a single key, if it is the start of ansi escape sequence then it reads
179 the full sequence.</td>
182 </tr> 180 </tr>
183 <tr> 181 <tr>
184 <td class="name" nowrap><a href="#tcgetattr">tcgetattr (fd)</a></td> 182 <td class="name" nowrap><a href="#readkey">readkey (timeout[, fsleep=system.sleep])</a></td>
185 <td class="summary">Get termios state (Posix).</td> 183 <td class="summary">Reads a single byte from the console, with a timeout.</td>
186 </tr> 184 </tr>
185</table>
186<h2><a href="#Terminal_UTF_8">Terminal_UTF-8</a></h2>
187<table class="function_list">
187 <tr> 188 <tr>
188 <td class="name" nowrap><a href="#tcsetattr">tcsetattr (fd, actions, termios)</a></td> 189 <td class="name" nowrap><a href="#CODEPAGE_UTF8">CODEPAGE_UTF8</a></td>
189 <td class="summary">Set termios state (Posix).</td> 190 <td class="summary">UTF8 codepage.</td>
190 </tr> 191 </tr>
191 <tr> 192 <tr>
192 <td class="name" nowrap><a href="#termbackup">termbackup ()</a></td> 193 <td class="name" nowrap><a href="#getconsolecp">getconsolecp ()</a></td>
193 <td class="summary">Returns a backup of terminal settings for stdin/out/err.</td> 194 <td class="summary">Gets the current console code page (Windows).</td>
194 </tr> 195 </tr>
195 <tr> 196 <tr>
196 <td class="name" nowrap><a href="#termrestore">termrestore (backup)</a></td> 197 <td class="name" nowrap><a href="#getconsoleoutputcp">getconsoleoutputcp ()</a></td>
197 <td class="summary">Restores terminal settings from a backup</td> 198 <td class="summary">Gets the current console output code page (Windows).</td>
198 </tr> 199 </tr>
199 <tr> 200 <tr>
200 <td class="name" nowrap><a href="#termsize">termsize ()</a></td> 201 <td class="name" nowrap><a href="#setconsolecp">setconsolecp (cp)</a></td>
201 <td class="summary">Get the size of the terminal in rows and columns.</td> 202 <td class="summary">Sets the current console code page (Windows).</td>
202 </tr> 203 </tr>
203 <tr> 204 <tr>
204 <td class="name" nowrap><a href="#termwrap">termwrap (f)</a></td> 205 <td class="name" nowrap><a href="#setconsoleoutputcp">setconsoleoutputcp (cp)</a></td>
205 <td class="summary">Wraps a function to automatically restore terminal settings upon returning.</td> 206 <td class="summary">Sets the current console output code page (Windows).</td>
206 </tr> 207 </tr>
207 <tr> 208 <tr>
208 <td class="name" nowrap><a href="#utf8cwidth">utf8cwidth (utf8_char)</a></td> 209 <td class="name" nowrap><a href="#utf8cwidth">utf8cwidth (utf8_char)</a></td>
@@ -228,6 +229,25 @@
228 <td class="summary">Sleep without a busy loop.</td> 229 <td class="summary">Sleep without a busy loop.</td>
229 </tr> 230 </tr>
230</table> 231</table>
232<h2><a href="#Terminal_Backup">Terminal_Backup</a></h2>
233<table class="function_list">
234 <tr>
235 <td class="name" nowrap><a href="#autotermrestore">autotermrestore ()</a></td>
236 <td class="summary">Backs up terminal settings and restores them on application exit.</td>
237 </tr>
238 <tr>
239 <td class="name" nowrap><a href="#termbackup">termbackup ()</a></td>
240 <td class="summary">Returns a backup of terminal settings for stdin/out/err.</td>
241 </tr>
242 <tr>
243 <td class="name" nowrap><a href="#termrestore">termrestore (backup)</a></td>
244 <td class="summary">Restores terminal settings from a backup</td>
245 </tr>
246 <tr>
247 <td class="name" nowrap><a href="#termwrap">termwrap (f)</a></td>
248 <td class="summary">Wraps a function to automatically restore terminal settings upon returning.</td>
249 </tr>
250</table>
231 251
232<br/> 252<br/>
233<br/> 253<br/>
@@ -403,95 +423,66 @@ requested number of bytes, or an error, never a partial result.
403 </div> 423 </div>
404 <dl class="function"> 424 <dl class="function">
405 <dt> 425 <dt>
406 <a name = "CODEPAGE_UTF8"></a> 426 <a name = "isatty"></a>
407 <strong>CODEPAGE_UTF8</strong> 427 <strong>isatty (file)</strong>
408 </dt> 428 </dt>
409 <dd> 429 <dd>
410 UTF8 codepage. 430 Checks if a file-handle is a TTY.
411 To be used with <a href="../modules/system.html#setconsoleoutputcp">system.setconsoleoutputcp</a> and <a href="../modules/system.html#setconsolecp">system.setconsolecp</a>.
412 431
413 432
433 <h3>Parameters:</h3>
414 <ul> 434 <ul>
415 <li><span class="parameter">CODEPAGE_UTF8</span> 435 <li><span class="parameter">file</span>
416 The Windows CodePage for UTF8. 436 <span class="types"><span class="type">file</span></span>
437 the file-handle to check, one of <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>.
417 </li> 438 </li>
418 </ul> 439 </ul>
419 440
420
421
422
423
424</dd>
425 <dt>
426 <a name = "_readkey"></a>
427 <strong>_readkey ()</strong>
428 </dt>
429 <dd>
430 Reads a key from the console non-blocking. This function should not be called
431directly, but through the <a href="../modules/system.html#readkey">system.readkey</a> or <a href="../modules/system.html#readansi">system.readansi</a> functions. It
432will return the next byte from the input stream, or <code>nil</code> if no key was pressed.</p>
433
434<p>On Posix, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a> must be set to non-blocking mode using <a href="../modules/system.html#setnonblock">setnonblock</a>
435and canonical mode must be turned off using <a href="../modules/system.html#tcsetattr">tcsetattr</a>,
436before calling this function. Otherwise it will block. No conversions are
437done on Posix, so the byte read is returned as-is.</p>
438
439<p>On Windows this reads a wide character and converts it to UTF-8. Multi-byte
440sequences will be buffered internally and returned one byte at a time.
441
442
443
444 <h3>Returns:</h3> 441 <h3>Returns:</h3>
445 <ol> 442 <ol>
446 443
447 <span class="types"><span class="type">integer</span></span> 444 <span class="types"><span class="type">boolean</span></span>
448 the byte read from the input stream 445 true if the file is a tty
449 </ol>
450 <h3>Or</h3>
451 <ol>
452
453 <span class="types"><span class="type">nil</span></span>
454 if no key was pressed
455 </ol>
456 <h3>Or</h3>
457 <ol>
458 <li>
459 <span class="types"><span class="type">nil</span></span>
460 on error</li>
461 <li>
462 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
463 error message</li>
464 <li>
465 <span class="types"><span class="type">int</span></span>
466 errnum (on posix)</li>
467 </ol> 446 </ol>
468 447
469 448
470 449
450 <h3>Usage:</h3>
451 <ul>
452 <pre class="example"><span class="keyword">local</span> system = <span class="global">require</span>(<span class="string">'system'</span>)
453<span class="keyword">if</span> system.<span class="function-name">isatty</span>(<span class="global">io</span>.stdin) <span class="keyword">then</span>
454 <span class="comment">-- enable ANSI coloring etc on Windows, does nothing in Posix.
455</span> <span class="keyword">local</span> flags = system.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout)
456 system.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdout, flags + sys.COF_VIRTUAL_TERMINAL_PROCESSING)
457<span class="keyword">end</span></pre>
458 </ul>
471 459
472</dd> 460</dd>
473 <dt> 461 <dt>
474 <a name = "autotermrestore"></a> 462 <a name = "termsize"></a>
475 <strong>autotermrestore ()</strong> 463 <strong>termsize ()</strong>
476 </dt> 464 </dt>
477 <dd> 465 <dd>
478 Backs up terminal settings and restores them on application exit. 466 Get the size of the terminal in rows and columns.
479 Calls <a href="../modules/system.html#termbackup">termbackup</a> to back up terminal settings and sets up a GC method to
480 automatically restore them on application exit (also works on Lua 5.1).
481 467
482 468
483 469
484 <h3>Returns:</h3> 470 <h3>Returns:</h3>
485 <ol> 471 <ol>
486 472 <li>
487 <span class="types"><span class="type">boolean</span></span> 473 <span class="types"><span class="type">int</span></span>
488 true 474 the number of rows</li>
475 <li>
476 <span class="types"><span class="type">int</span></span>
477 the number of columns</li>
489 </ol> 478 </ol>
490 <h3>Or</h3> 479 <h3>Or</h3>
491 <ol> 480 <ol>
492 <li> 481 <li>
493 <span class="types"><span class="type">nil</span></span> 482 <span class="types"><span class="type">nil</span></span>
494 if the backup was already created</li> 483
484
485</li>
495 <li> 486 <li>
496 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> 487 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
497 error message</li> 488 error message</li>
@@ -501,60 +492,10 @@ sequences will be buffered internally and returned one byte at a time.
501 492
502 493
503</dd> 494</dd>
504 <dt> 495</dl>
505 <a name = "detachfds"></a> 496 <h2 class="section-header "><a name="Terminal_Windows"></a>Terminal_Windows</h2>
506 <strong>detachfds ()</strong>
507 </dt>
508 <dd>
509 Creates new file descriptions for <code>stdout</code> and <code>stderr</code>.
510Even if the file descriptors are unique, they still might point to the same
511file description, and hence share settings like <code>O_NONBLOCK</code>. This means that
512if one of them is set to non-blocking, the other will be as well. This can
513lead to unexpected behavior.</p>
514
515<p>This function is used to detach <code>stdout</code> and <code>stderr</code> from the original
516file descriptions, and create new file descriptions for them. This allows
517independent control of flags (e.g., <code>O_NONBLOCK</code>) on <code>stdout</code> and <code>stderr</code>,
518avoiding shared side effects.</p>
519
520<p>Does not modify <code>stdin</code> (fd 0), and does nothing on Windows.
521
522
523
524 <h3>Returns:</h3>
525 <ol>
526
527 boolean <code>true</code> on success, or throws an error on failure.
528 </ol>
529
530
531 <h3>See also:</h3>
532 <ul>
533 <a href="../modules/system.html#setnonblock">setnonblock</a>
534 </ul>
535
536
537</dd>
538 <dt>
539 <a name = "getconsolecp"></a>
540 <strong>getconsolecp ()</strong>
541 </dt>
542 <dd>
543 Gets the current console code page (Windows).
544
545
546
547 <h3>Returns:</h3>
548 <ol>
549
550 <span class="types"><span class="type">int</span></span>
551 the current code page (always 65001 on Posix systems)
552 </ol>
553
554
555
556 497
557</dd> 498 <dl class="function">
558 <dt> 499 <dt>
559 <a name = "getconsoleflags"></a> 500 <a name = "getconsoleflags"></a>
560 <strong>getconsoleflags (file)</strong> 501 <strong>getconsoleflags (file)</strong>
@@ -613,107 +554,6 @@ for more information on the flags.
613 554
614</dd> 555</dd>
615 <dt> 556 <dt>
616 <a name = "getconsoleoutputcp"></a>
617 <strong>getconsoleoutputcp ()</strong>
618 </dt>
619 <dd>
620 Gets the current console output code page (Windows).
621
622
623
624 <h3>Returns:</h3>
625 <ol>
626
627 <span class="types"><span class="type">int</span></span>
628 the current code page (always 65001 on Posix systems)
629 </ol>
630
631
632
633
634</dd>
635 <dt>
636 <a name = "getnonblock"></a>
637 <strong>getnonblock (fd)</strong>
638 </dt>
639 <dd>
640 Gets non-blocking mode status for a file (Posix).
641
642
643 <h3>Parameters:</h3>
644 <ul>
645 <li><span class="parameter">fd</span>
646 <span class="types"><span class="type">file</span></span>
647 file handle to operate on, one of <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>
648 </li>
649 </ul>
650
651 <h3>Returns:</h3>
652 <ol>
653
654 <span class="types"><span class="type">bool</span></span>
655 <code>true</code> if set to non-blocking, <code>false</code> if not. Always returns <code>false</code> on Windows.
656 </ol>
657 <h3>Or</h3>
658 <ol>
659 <li>
660 <span class="types"><span class="type">nil</span></span>
661
662
663</li>
664 <li>
665 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
666 error message</li>
667 <li>
668 <span class="types"><span class="type">int</span></span>
669 errnum</li>
670 </ol>
671
672
673 <h3>See also:</h3>
674 <ul>
675 <a href="../modules/system.html#setnonblock">setnonblock</a>
676 </ul>
677
678
679</dd>
680 <dt>
681 <a name = "isatty"></a>
682 <strong>isatty (file)</strong>
683 </dt>
684 <dd>
685 Checks if a file-handle is a TTY.
686
687
688 <h3>Parameters:</h3>
689 <ul>
690 <li><span class="parameter">file</span>
691 <span class="types"><span class="type">file</span></span>
692 the file-handle to check, one of <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>.
693 </li>
694 </ul>
695
696 <h3>Returns:</h3>
697 <ol>
698
699 <span class="types"><span class="type">boolean</span></span>
700 true if the file is a tty
701 </ol>
702
703
704
705 <h3>Usage:</h3>
706 <ul>
707 <pre class="example"><span class="keyword">local</span> system = <span class="global">require</span>(<span class="string">'system'</span>)
708<span class="keyword">if</span> system.<span class="function-name">isatty</span>(<span class="global">io</span>.stdin) <span class="keyword">then</span>
709 <span class="comment">-- enable ANSI coloring etc on Windows, does nothing in Posix.
710</span> <span class="keyword">local</span> flags = system.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout)
711 system.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdout, flags + sys.COF_VIRTUAL_TERMINAL_PROCESSING)
712<span class="keyword">end</span></pre>
713 </ul>
714
715</dd>
716 <dt>
717 <a name = "listconsoleflags"></a> 557 <a name = "listconsoleflags"></a>
718 <strong>listconsoleflags (fh)</strong> 558 <strong>listconsoleflags (fh)</strong>
719 </dt> 559 </dt>
@@ -742,194 +582,125 @@ system.<span class="function-name">listconsoleflags</span>(<span class="global">
742 582
743</dd> 583</dd>
744 <dt> 584 <dt>
745 <a name = "listtermflags"></a> 585 <a name = "setconsoleflags"></a>
746 <strong>listtermflags (fh)</strong> 586 <strong>setconsoleflags (file, bitflags)</strong>
747 </dt> 587 </dt>
748 <dd> 588 <dd>
749 Debug function for terminal flags (Posix). 589 Sets the console flags (Windows).
750 Pretty prints the current flags set for the handle. 590The <code>CIF_</code> and <code>COF_</code> constants are available on the module table. Where <code>CIF</code> are the
751 591input flags (for use with <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>) and <code>COF</code> are the output flags (for use with
752 592<a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>/<a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>).</p>
753 <h3>Parameters:</h3>
754 <ul>
755 <li><span class="parameter">fh</span>
756 file handle (<a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>)
757 </li>
758 </ul>
759
760
761
762 593
763 <h3>Usage:</h3> 594<p>To see flag status and constant names check <a href="../modules/system.html#listconsoleflags">listconsoleflags</a>.</p>
764 <ul>
765 <pre class="example"><span class="comment">-- Print the flags for stdin/out/err
766</span>system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdin)
767system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdout)
768system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stderr)</pre>
769 </ul>
770 595
771</dd> 596<p>Note: not all combinations of flags are allowed, as some are mutually exclusive or mutually required.
772 <dt> 597See <a href="https://learn.microsoft.com/en-us/windows/console/setconsolemode">setconsolemode documentation</a>
773 <a name = "readansi"></a>
774 <strong>readansi (timeout[, fsleep=system.sleep])</strong>
775 </dt>
776 <dd>
777 Reads a single key, if it is the start of ansi escape sequence then it reads
778 the full sequence. The key can be a multi-byte string in case of multibyte UTF-8 character.
779 This function uses <a href="../modules/system.html#readkey">system.readkey</a>, and hence <code>fsleep</code> to wait until either a key is
780 available or the timeout is reached.
781 It returns immediately if a key is available or if <code>timeout</code> is less than or equal to <code>0</code>.
782 In case of an ANSI sequence, it will return the full sequence as a string.
783 598
784 599
785 <h3>Parameters:</h3> 600 <h3>Parameters:</h3>
786 <ul> 601 <ul>
787 <li><span class="parameter">timeout</span> 602 <li><span class="parameter">file</span>
788 <span class="types"><span class="type">number</span></span> 603 <span class="types"><span class="type">file</span></span>
789 the timeout in seconds. 604 file handle to operate on, one of <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>
790 </li> 605 </li>
791 <li><span class="parameter">fsleep</span> 606 <li><span class="parameter">bitflags</span>
792 <span class="types"><span class="type">function</span></span> 607 <span class="types"><a class="type" href="../classes/bitflags.html#">bitflags</a></span>
793 the function to call for sleeping. 608 the flags to set/unset
794 (<em>default</em> system.sleep)
795 </li> 609 </li>
796 </ul> 610 </ul>
797 611
798 <h3>Returns:</h3> 612 <h3>Returns:</h3>
799 <ol> 613 <ol>
800 <li> 614
801 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> 615 <span class="types"><span class="type">boolean</span></span>
802 the character that was received (can be multi-byte), or a complete ANSI sequence</li> 616 <code>true</code> on success
803 <li>
804 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
805 the type of input: <code>&quot;char&quot;</code> for a single key, <code>&quot;ansi&quot;</code> for an ANSI sequence</li>
806 </ol> 617 </ol>
807 <h3>Or</h3> 618 <h3>Or</h3>
808 <ol> 619 <ol>
809 <li> 620 <li>
810 <span class="types"><span class="type">nil</span></span> 621 <span class="types"><span class="type">nil</span></span>
811 in case of an error</li> 622
812 <li> 623
813 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> 624</li>
814 error message; <code>&quot;timeout&quot;</code> if the timeout was reached.</li>
815 <li> 625 <li>
816 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> 626 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
817 partial result in case of an error while reading a sequence, the sequence so far. 627 error message</li>
818 The function retains its own internal buffer, so on the next call the incomplete buffer is used to
819 complete the sequence.</li>
820 </ol> 628 </ol>
821 629
822 630
823 631
632 <h3>Usage:</h3>
633 <ul>
634 <pre class="example"><span class="keyword">local</span> system = <span class="global">require</span>(<span class="string">'system'</span>)
635system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdout) <span class="comment">-- List all the available flags and their current status
636</span>
637<span class="keyword">local</span> flags = system.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout)
638<span class="global">assert</span>(system.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdout,
639 flags + system.COF_VIRTUAL_TERMINAL_PROCESSING)
640
641system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdout) <span class="comment">-- List again to check the differences</span></pre>
642 </ul>
824 643
825</dd> 644</dd>
645</dl>
646 <h2 class="section-header "><a name="Terminal_Posix"></a>Terminal_Posix</h2>
647
648 <dl class="function">
826 <dt> 649 <dt>
827 <a name = "readkey"></a> 650 <a name = "detachfds"></a>
828 <strong>readkey (timeout[, fsleep=system.sleep])</strong> 651 <strong>detachfds ()</strong>
829 </dt> 652 </dt>
830 <dd> 653 <dd>
831 Reads a single byte from the console, with a timeout. 654 Creates new file descriptions for <code>stdout</code> and <code>stderr</code>.
832 This function uses <code>fsleep</code> to wait until either a byte is available or the timeout is reached. 655Even if the file descriptors are unique, they still might point to the same
833 The sleep period is exponentially backing off, starting at 0.0125 seconds, with a maximum of 0.2 seconds. 656file description, and hence share settings like <code>O_NONBLOCK</code>. This means that
834 It returns immediately if a byte is available or if <code>timeout</code> is less than or equal to <code>0</code>.</p> 657if one of them is set to non-blocking, the other will be as well. This can
658lead to unexpected behavior.</p>
835 659
836<p> Using <a href="../modules/system.html#readansi">system.readansi</a> is preferred over this function. Since this function can leave stray/invalid 660<p>This function is used to detach <code>stdout</code> and <code>stderr</code> from the original
837 byte-sequences in the input buffer, while <a href="../modules/system.html#readansi">system.readansi</a> reads full ANSI and UTF8 sequences. 661file descriptions, and create new file descriptions for them. This allows
662independent control of flags (e.g., <code>O_NONBLOCK</code>) on <code>stdout</code> and <code>stderr</code>,
663avoiding shared side effects.</p>
664
665<p>Does not modify <code>stdin</code> (fd 0), and does nothing on Windows.
838 666
839 667
840 <h3>Parameters:</h3>
841 <ul>
842 <li><span class="parameter">timeout</span>
843 <span class="types"><span class="type">number</span></span>
844 the timeout in seconds.
845 </li>
846 <li><span class="parameter">fsleep</span>
847 <span class="types"><span class="type">function</span></span>
848 the function to call for sleeping; <code>ok, err = fsleep(secs)</code>
849 (<em>default</em> system.sleep)
850 </li>
851 </ul>
852 668
853 <h3>Returns:</h3> 669 <h3>Returns:</h3>
854 <ol> 670 <ol>
855 671
856 <span class="types"><span class="type">byte</span></span> 672 boolean <code>true</code> on success, or throws an error on failure.
857 the byte value that was read.
858 </ol>
859 <h3>Or</h3>
860 <ol>
861 <li>
862 <span class="types"><span class="type">nil</span></span>
863 if no key was read</li>
864 <li>
865 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
866 error message when the timeout was reached (<code>&quot;timeout&quot;</code>), or if <a href="../modules/system.html#sleep">sleep</a> failed.</li>
867 </ol> 673 </ol>
868 674
869 675
870 676 <h3>See also:</h3>
871
872</dd>
873 <dt>
874 <a name = "setconsolecp"></a>
875 <strong>setconsolecp (cp)</strong>
876 </dt>
877 <dd>
878 Sets the current console code page (Windows).
879
880
881 <h3>Parameters:</h3>
882 <ul> 677 <ul>
883 <li><span class="parameter">cp</span> 678 <a href="../modules/system.html#setnonblock">setnonblock</a>
884 <span class="types"><span class="type">int</span></span>
885 the code page to set, use <a href="../modules/system.html#CODEPAGE_UTF8">system.CODEPAGE_UTF8</a> (65001) for UTF-8
886 </li>
887 </ul> 679 </ul>
888 680
889 <h3>Returns:</h3>
890 <ol>
891
892 <span class="types"><span class="type">bool</span></span>
893 <code>true</code> on success (always <code>true</code> on Posix systems)
894 </ol>
895
896
897
898 681
899</dd> 682</dd>
900 <dt> 683 <dt>
901 <a name = "setconsoleflags"></a> 684 <a name = "getnonblock"></a>
902 <strong>setconsoleflags (file, bitflags)</strong> 685 <strong>getnonblock (fd)</strong>
903 </dt> 686 </dt>
904 <dd> 687 <dd>
905 Sets the console flags (Windows). 688 Gets non-blocking mode status for a file (Posix).
906The <code>CIF_</code> and <code>COF_</code> constants are available on the module table. Where <code>CIF</code> are the
907input flags (for use with <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>) and <code>COF</code> are the output flags (for use with
908<a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>/<a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>).</p>
909
910<p>To see flag status and constant names check <a href="../modules/system.html#listconsoleflags">listconsoleflags</a>.</p>
911
912<p>Note: not all combinations of flags are allowed, as some are mutually exclusive or mutually required.
913See <a href="https://learn.microsoft.com/en-us/windows/console/setconsolemode">setconsolemode documentation</a>
914 689
915 690
916 <h3>Parameters:</h3> 691 <h3>Parameters:</h3>
917 <ul> 692 <ul>
918 <li><span class="parameter">file</span> 693 <li><span class="parameter">fd</span>
919 <span class="types"><span class="type">file</span></span> 694 <span class="types"><span class="type">file</span></span>
920 file handle to operate on, one of <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a> 695 file handle to operate on, one of <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>
921 </li> 696 </li>
922 <li><span class="parameter">bitflags</span>
923 <span class="types"><a class="type" href="../classes/bitflags.html#">bitflags</a></span>
924 the flags to set/unset
925 </li>
926 </ul> 697 </ul>
927 698
928 <h3>Returns:</h3> 699 <h3>Returns:</h3>
929 <ol> 700 <ol>
930 701
931 <span class="types"><span class="type">boolean</span></span> 702 <span class="types"><span class="type">bool</span></span>
932 <code>true</code> on success 703 <code>true</code> if set to non-blocking, <code>false</code> if not. Always returns <code>false</code> on Windows.
933 </ol> 704 </ol>
934 <h3>Or</h3> 705 <h3>Or</h3>
935 <ol> 706 <ol>
@@ -941,48 +712,45 @@ See <a href="https://learn.microsoft.com/en-us/windows/console/setconsolemode">s
941 <li> 712 <li>
942 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> 713 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
943 error message</li> 714 error message</li>
715 <li>
716 <span class="types"><span class="type">int</span></span>
717 errnum</li>
944 </ol> 718 </ol>
945 719
946 720
947 721 <h3>See also:</h3>
948 <h3>Usage:</h3>
949 <ul> 722 <ul>
950 <pre class="example"><span class="keyword">local</span> system = <span class="global">require</span>(<span class="string">'system'</span>) 723 <a href="../modules/system.html#setnonblock">setnonblock</a>
951system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdout) <span class="comment">-- List all the available flags and their current status
952</span>
953<span class="keyword">local</span> flags = system.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout)
954<span class="global">assert</span>(system.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdout,
955 flags + system.COF_VIRTUAL_TERMINAL_PROCESSING)
956
957system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdout) <span class="comment">-- List again to check the differences</span></pre>
958 </ul> 724 </ul>
959 725
726
960</dd> 727</dd>
961 <dt> 728 <dt>
962 <a name = "setconsoleoutputcp"></a> 729 <a name = "listtermflags"></a>
963 <strong>setconsoleoutputcp (cp)</strong> 730 <strong>listtermflags (fh)</strong>
964 </dt> 731 </dt>
965 <dd> 732 <dd>
966 Sets the current console output code page (Windows). 733 Debug function for terminal flags (Posix).
734 Pretty prints the current flags set for the handle.
967 735
968 736
969 <h3>Parameters:</h3> 737 <h3>Parameters:</h3>
970 <ul> 738 <ul>
971 <li><span class="parameter">cp</span> 739 <li><span class="parameter">fh</span>
972 <span class="types"><span class="type">int</span></span> 740 file handle (<a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdout">io.stdout</a>, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stderr">io.stderr</a>)
973 the code page to set, use <a href="../modules/system.html#CODEPAGE_UTF8">system.CODEPAGE_UTF8</a> (65001) for UTF-8
974 </li> 741 </li>
975 </ul> 742 </ul>
976 743
977 <h3>Returns:</h3>
978 <ol>
979
980 <span class="types"><span class="type">bool</span></span>
981 <code>true</code> on success (always <code>true</code> on Posix systems)
982 </ol>
983 744
984 745
985 746
747 <h3>Usage:</h3>
748 <ul>
749 <pre class="example"><span class="comment">-- Print the flags for stdin/out/err
750</span>system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdin)
751system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdout)
752system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stderr)</pre>
753 </ul>
986 754
987</dd> 755</dd>
988 <dt> 756 <dt>
@@ -1198,21 +966,52 @@ flags for the <code>iflags</code>, <code>oflags</code>, and <code>lflags</code>
1198 </ul> 966 </ul>
1199 967
1200</dd> 968</dd>
969</dl>
970 <h2 class="section-header "><a name="Terminal_Input"></a>Terminal_Input</h2>
971
972 <dl class="function">
1201 <dt> 973 <dt>
1202 <a name = "termbackup"></a> 974 <a name = "_readkey"></a>
1203 <strong>termbackup ()</strong> 975 <strong>_readkey ()</strong>
1204 </dt> 976 </dt>
1205 <dd> 977 <dd>
1206 Returns a backup of terminal settings for stdin/out/err. 978 Reads a key from the console non-blocking. This function should not be called
1207 Handles terminal/console flags, Windows codepage, and non-block flags on the streams. 979directly, but through the <a href="../modules/system.html#readkey">system.readkey</a> or <a href="../modules/system.html#readansi">system.readansi</a> functions. It
1208 Backs up terminal/console flags only if a stream is a tty. 980will return the next byte from the input stream, or <code>nil</code> if no key was pressed.</p>
981
982<p>On Posix, <a href="https://www.lua.org/manual/5.4/manual.html#pdf-io.stdin">io.stdin</a> must be set to non-blocking mode using <a href="../modules/system.html#setnonblock">setnonblock</a>
983and canonical mode must be turned off using <a href="../modules/system.html#tcsetattr">tcsetattr</a>,
984before calling this function. Otherwise it will block. No conversions are
985done on Posix, so the byte read is returned as-is.</p>
986
987<p>On Windows this reads a wide character and converts it to UTF-8. Multi-byte
988sequences will be buffered internally and returned one byte at a time.
1209 989
1210 990
1211 991
1212 <h3>Returns:</h3> 992 <h3>Returns:</h3>
1213 <ol> 993 <ol>
1214 994
1215 table with backup of terminal settings 995 <span class="types"><span class="type">integer</span></span>
996 the byte read from the input stream
997 </ol>
998 <h3>Or</h3>
999 <ol>
1000
1001 <span class="types"><span class="type">nil</span></span>
1002 if no key was pressed
1003 </ol>
1004 <h3>Or</h3>
1005 <ol>
1006 <li>
1007 <span class="types"><span class="type">nil</span></span>
1008 on error</li>
1009 <li>
1010 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
1011 error message</li>
1012 <li>
1013 <span class="types"><span class="type">int</span></span>
1014 errnum (on posix)</li>
1216 </ol> 1015 </ol>
1217 1016
1218 1017
@@ -1220,26 +1019,53 @@ flags for the <code>iflags</code>, <code>oflags</code>, and <code>lflags</code>
1220 1019
1221</dd> 1020</dd>
1222 <dt> 1021 <dt>
1223 <a name = "termrestore"></a> 1022 <a name = "readansi"></a>
1224 <strong>termrestore (backup)</strong> 1023 <strong>readansi (timeout[, fsleep=system.sleep])</strong>
1225 </dt> 1024 </dt>
1226 <dd> 1025 <dd>
1227 Restores terminal settings from a backup 1026 Reads a single key, if it is the start of ansi escape sequence then it reads
1027 the full sequence. The key can be a multi-byte string in case of multibyte UTF-8 character.
1028 This function uses <a href="../modules/system.html#readkey">system.readkey</a>, and hence <code>fsleep</code> to wait until either a key is
1029 available or the timeout is reached.
1030 It returns immediately if a key is available or if <code>timeout</code> is less than or equal to <code>0</code>.
1031 In case of an ANSI sequence, it will return the full sequence as a string.
1228 1032
1229 1033
1230 <h3>Parameters:</h3> 1034 <h3>Parameters:</h3>
1231 <ul> 1035 <ul>
1232 <li><span class="parameter">backup</span> 1036 <li><span class="parameter">timeout</span>
1233 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span> 1037 <span class="types"><span class="type">number</span></span>
1234 the backup of terminal settings, see <a href="../modules/system.html#termbackup">termbackup</a>. 1038 the timeout in seconds.
1039 </li>
1040 <li><span class="parameter">fsleep</span>
1041 <span class="types"><span class="type">function</span></span>
1042 the function to call for sleeping.
1043 (<em>default</em> system.sleep)
1235 </li> 1044 </li>
1236 </ul> 1045 </ul>
1237 1046
1238 <h3>Returns:</h3> 1047 <h3>Returns:</h3>
1239 <ol> 1048 <ol>
1240 1049 <li>
1241 <span class="types"><span class="type">boolean</span></span> 1050 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
1242 true 1051 the character that was received (can be multi-byte), or a complete ANSI sequence</li>
1052 <li>
1053 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
1054 the type of input: <code>&quot;char&quot;</code> for a single key, <code>&quot;ansi&quot;</code> for an ANSI sequence</li>
1055 </ol>
1056 <h3>Or</h3>
1057 <ol>
1058 <li>
1059 <span class="types"><span class="type">nil</span></span>
1060 in case of an error</li>
1061 <li>
1062 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
1063 error message; <code>&quot;timeout&quot;</code> if the timeout was reached.</li>
1064 <li>
1065 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
1066 partial result in case of an error while reading a sequence, the sequence so far.
1067 The function retains its own internal buffer, so on the next call the incomplete buffer is used to
1068 complete the sequence.</li>
1243 </ol> 1069 </ol>
1244 1070
1245 1071
@@ -1247,61 +1073,164 @@ flags for the <code>iflags</code>, <code>oflags</code>, and <code>lflags</code>
1247 1073
1248</dd> 1074</dd>
1249 <dt> 1075 <dt>
1250 <a name = "termsize"></a> 1076 <a name = "readkey"></a>
1251 <strong>termsize ()</strong> 1077 <strong>readkey (timeout[, fsleep=system.sleep])</strong>
1252 </dt> 1078 </dt>
1253 <dd> 1079 <dd>
1254 Get the size of the terminal in rows and columns. 1080 Reads a single byte from the console, with a timeout.
1081 This function uses <code>fsleep</code> to wait until either a byte is available or the timeout is reached.
1082 The sleep period is exponentially backing off, starting at 0.0125 seconds, with a maximum of 0.2 seconds.
1083 It returns immediately if a byte is available or if <code>timeout</code> is less than or equal to <code>0</code>.</p>
1255 1084
1085<p> Using <a href="../modules/system.html#readansi">system.readansi</a> is preferred over this function. Since this function can leave stray/invalid
1086 byte-sequences in the input buffer, while <a href="../modules/system.html#readansi">system.readansi</a> reads full ANSI and UTF8 sequences.
1256 1087
1257 1088
1089 <h3>Parameters:</h3>
1090 <ul>
1091 <li><span class="parameter">timeout</span>
1092 <span class="types"><span class="type">number</span></span>
1093 the timeout in seconds.
1094 </li>
1095 <li><span class="parameter">fsleep</span>
1096 <span class="types"><span class="type">function</span></span>
1097 the function to call for sleeping; <code>ok, err = fsleep(secs)</code>
1098 (<em>default</em> system.sleep)
1099 </li>
1100 </ul>
1101
1258 <h3>Returns:</h3> 1102 <h3>Returns:</h3>
1259 <ol> 1103 <ol>
1260 <li> 1104
1261 <span class="types"><span class="type">int</span></span> 1105 <span class="types"><span class="type">byte</span></span>
1262 the number of rows</li> 1106 the byte value that was read.
1263 <li>
1264 <span class="types"><span class="type">int</span></span>
1265 the number of columns</li>
1266 </ol> 1107 </ol>
1267 <h3>Or</h3> 1108 <h3>Or</h3>
1268 <ol> 1109 <ol>
1269 <li> 1110 <li>
1270 <span class="types"><span class="type">nil</span></span> 1111 <span class="types"><span class="type">nil</span></span>
1271 1112 if no key was read</li>
1272
1273</li>
1274 <li> 1113 <li>
1275 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> 1114 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
1276 error message</li> 1115 error message when the timeout was reached (<code>&quot;timeout&quot;</code>), or if <a href="../modules/system.html#sleep">sleep</a> failed.</li>
1277 </ol> 1116 </ol>
1278 1117
1279 1118
1280 1119
1281 1120
1282</dd> 1121</dd>
1122</dl>
1123 <h2 class="section-header "><a name="Terminal_UTF_8"></a>Terminal_UTF-8</h2>
1124
1125 <dl class="function">
1283 <dt> 1126 <dt>
1284 <a name = "termwrap"></a> 1127 <a name = "CODEPAGE_UTF8"></a>
1285 <strong>termwrap (f)</strong> 1128 <strong>CODEPAGE_UTF8</strong>
1286 </dt> 1129 </dt>
1287 <dd> 1130 <dd>
1288 Wraps a function to automatically restore terminal settings upon returning. 1131 UTF8 codepage.
1289 Calls <a href="../modules/system.html#termbackup">termbackup</a> before calling the function and <a href="../modules/system.html#termrestore">termrestore</a> after. 1132 To be used with <a href="../modules/system.html#setconsoleoutputcp">system.setconsoleoutputcp</a> and <a href="../modules/system.html#setconsolecp">system.setconsolecp</a>.
1133
1134
1135 <ul>
1136 <li><span class="parameter">CODEPAGE_UTF8</span>
1137 The Windows CodePage for UTF8.
1138 </li>
1139 </ul>
1140
1141
1142
1143
1144
1145</dd>
1146 <dt>
1147 <a name = "getconsolecp"></a>
1148 <strong>getconsolecp ()</strong>
1149 </dt>
1150 <dd>
1151 Gets the current console code page (Windows).
1152
1153
1154
1155 <h3>Returns:</h3>
1156 <ol>
1157
1158 <span class="types"><span class="type">int</span></span>
1159 the current code page (always 65001 on Posix systems)
1160 </ol>
1161
1162
1163
1164
1165</dd>
1166 <dt>
1167 <a name = "getconsoleoutputcp"></a>
1168 <strong>getconsoleoutputcp ()</strong>
1169 </dt>
1170 <dd>
1171 Gets the current console output code page (Windows).
1172
1173
1174
1175 <h3>Returns:</h3>
1176 <ol>
1177
1178 <span class="types"><span class="type">int</span></span>
1179 the current code page (always 65001 on Posix systems)
1180 </ol>
1181
1182
1183
1184
1185</dd>
1186 <dt>
1187 <a name = "setconsolecp"></a>
1188 <strong>setconsolecp (cp)</strong>
1189 </dt>
1190 <dd>
1191 Sets the current console code page (Windows).
1290 1192
1291 1193
1292 <h3>Parameters:</h3> 1194 <h3>Parameters:</h3>
1293 <ul> 1195 <ul>
1294 <li><span class="parameter">f</span> 1196 <li><span class="parameter">cp</span>
1295 <span class="types"><span class="type">function</span></span> 1197 <span class="types"><span class="type">int</span></span>
1296 function to wrap 1198 the code page to set, use <a href="../modules/system.html#CODEPAGE_UTF8">system.CODEPAGE_UTF8</a> (65001) for UTF-8
1297 </li> 1199 </li>
1298 </ul> 1200 </ul>
1299 1201
1300 <h3>Returns:</h3> 1202 <h3>Returns:</h3>
1301 <ol> 1203 <ol>
1302 1204
1303 <span class="types"><span class="type">function</span></span> 1205 <span class="types"><span class="type">bool</span></span>
1304 wrapped function 1206 <code>true</code> on success (always <code>true</code> on Posix systems)
1207 </ol>
1208
1209
1210
1211
1212</dd>
1213 <dt>
1214 <a name = "setconsoleoutputcp"></a>
1215 <strong>setconsoleoutputcp (cp)</strong>
1216 </dt>
1217 <dd>
1218 Sets the current console output code page (Windows).
1219
1220
1221 <h3>Parameters:</h3>
1222 <ul>
1223 <li><span class="parameter">cp</span>
1224 <span class="types"><span class="type">int</span></span>
1225 the code page to set, use <a href="../modules/system.html#CODEPAGE_UTF8">system.CODEPAGE_UTF8</a> (65001) for UTF-8
1226 </li>
1227 </ul>
1228
1229 <h3>Returns:</h3>
1230 <ol>
1231
1232 <span class="types"><span class="type">bool</span></span>
1233 <code>true</code> on success (always <code>true</code> on Posix systems)
1305 </ol> 1234 </ol>
1306 1235
1307 1236
@@ -1463,13 +1392,124 @@ This function will sleep, without doing a busy-loop and wasting CPU cycles.
1463 1392
1464</dd> 1393</dd>
1465</dl> 1394</dl>
1395 <h2 class="section-header "><a name="Terminal_Backup"></a>Terminal_Backup</h2>
1396
1397 <dl class="function">
1398 <dt>
1399 <a name = "autotermrestore"></a>
1400 <strong>autotermrestore ()</strong>
1401 </dt>
1402 <dd>
1403 Backs up terminal settings and restores them on application exit.
1404 Calls <a href="../modules/system.html#termbackup">termbackup</a> to back up terminal settings and sets up a GC method to
1405 automatically restore them on application exit (also works on Lua 5.1).
1406
1407
1408
1409 <h3>Returns:</h3>
1410 <ol>
1411
1412 <span class="types"><span class="type">boolean</span></span>
1413 true
1414 </ol>
1415 <h3>Or</h3>
1416 <ol>
1417 <li>
1418 <span class="types"><span class="type">nil</span></span>
1419 if the backup was already created</li>
1420 <li>
1421 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span>
1422 error message</li>
1423 </ol>
1424
1425
1426
1427
1428</dd>
1429 <dt>
1430 <a name = "termbackup"></a>
1431 <strong>termbackup ()</strong>
1432 </dt>
1433 <dd>
1434 Returns a backup of terminal settings for stdin/out/err.
1435 Handles terminal/console flags, Windows codepage, and non-block flags on the streams.
1436 Backs up terminal/console flags only if a stream is a tty.
1437
1438
1439
1440 <h3>Returns:</h3>
1441 <ol>
1442
1443 table with backup of terminal settings
1444 </ol>
1445
1446
1447
1448
1449</dd>
1450 <dt>
1451 <a name = "termrestore"></a>
1452 <strong>termrestore (backup)</strong>
1453 </dt>
1454 <dd>
1455 Restores terminal settings from a backup
1456
1457
1458 <h3>Parameters:</h3>
1459 <ul>
1460 <li><span class="parameter">backup</span>
1461 <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span>
1462 the backup of terminal settings, see <a href="../modules/system.html#termbackup">termbackup</a>.
1463 </li>
1464 </ul>
1465
1466 <h3>Returns:</h3>
1467 <ol>
1468
1469 <span class="types"><span class="type">boolean</span></span>
1470 true
1471 </ol>
1472
1473
1474
1475
1476</dd>
1477 <dt>
1478 <a name = "termwrap"></a>
1479 <strong>termwrap (f)</strong>
1480 </dt>
1481 <dd>
1482 Wraps a function to automatically restore terminal settings upon returning.
1483 Calls <a href="../modules/system.html#termbackup">termbackup</a> before calling the function and <a href="../modules/system.html#termrestore">termrestore</a> after.
1484
1485
1486 <h3>Parameters:</h3>
1487 <ul>
1488 <li><span class="parameter">f</span>
1489 <span class="types"><span class="type">function</span></span>
1490 function to wrap
1491 </li>
1492 </ul>
1493
1494 <h3>Returns:</h3>
1495 <ol>
1496
1497 <span class="types"><span class="type">function</span></span>
1498 wrapped function
1499 </ol>
1500
1501
1502
1503
1504</dd>
1505</dl>
1466 1506
1467 1507
1468</div> <!-- id="content" --> 1508</div> <!-- id="content" -->
1469</div> <!-- id="main" --> 1509</div> <!-- id="main" -->
1470<div id="about"> 1510<div id="about">
1471<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i> 1511<i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i>
1472<i style="float:right;">Last updated 2025-04-15 13:14:45 </i> 1512<i style="float:right;">Last updated 2025-04-17 09:50:39 </i>
1473</div> <!-- id="about" --> 1513</div> <!-- id="about" -->
1474</div> <!-- id="container" --> 1514</div> <!-- id="container" -->
1475</body> 1515</body>
generated by cgit v1.2.3-55-g6feb (git 2.39.1) at 2025-11-23 10:36:11 +0000