diff options
author | Thijs Schreijer <thijs@thijsschreijer.nl> | 2024-06-20 23:16:29 +0200 |
---|---|---|
committer | GitHub <noreply@github.com> | 2024-06-20 23:16:29 +0200 |
commit | bb4fd73c317cc88beb5e58c1abf52138abed107f (patch) | |
tree | 35b774efc97d820a908424a5bc2452e0d6bf12a8 | |
parent | c1a64c1b75f97cef97965b3bd9a941564a6270bd (diff) | |
download | luasystem-bb4fd73c317cc88beb5e58c1abf52138abed107f.tar.gz luasystem-bb4fd73c317cc88beb5e58c1abf52138abed107f.tar.bz2 luasystem-bb4fd73c317cc88beb5e58c1abf52138abed107f.zip |
Release v0.4.0 (#24)v0.4.0
-rw-r--r-- | CHANGELOG.md | 14 | ||||
-rw-r--r-- | LICENSE.md | 2 | ||||
-rw-r--r-- | docs/classes/bitflags.html | 305 | ||||
-rw-r--r-- | docs/examples/compat.lua.html | 119 | ||||
-rw-r--r-- | docs/examples/flag_debugging.lua.html | 87 | ||||
-rw-r--r-- | docs/examples/password_input.lua.html | 139 | ||||
-rw-r--r-- | docs/examples/read.lua.html | 150 | ||||
-rw-r--r-- | docs/examples/readline.lua.html | 552 | ||||
-rw-r--r-- | docs/examples/spinner.lua.html | 144 | ||||
-rw-r--r-- | docs/examples/spiral_snake.lua.html | 152 | ||||
-rw-r--r-- | docs/examples/terminalsize.lua.html | 117 | ||||
-rw-r--r-- | docs/index.html | 369 | ||||
-rw-r--r-- | docs/modules/system.html | 1418 | ||||
-rw-r--r-- | docs/topics/01-introduction.md.html | 27 | ||||
-rw-r--r-- | docs/topics/02-development.md.html | 91 | ||||
-rw-r--r-- | docs/topics/03-terminal.md.html | 225 | ||||
-rw-r--r-- | docs/topics/CHANGELOG.md.html | 55 | ||||
-rw-r--r-- | docs/topics/LICENSE.md.html | 29 | ||||
-rw-r--r-- | rockspecs/luasystem-0.4.0-1.rockspec | 85 | ||||
-rw-r--r-- | src/core.c | 5 |
20 files changed, 3774 insertions, 311 deletions
diff --git a/CHANGELOG.md b/CHANGELOG.md index eb85c94..a3544ea 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md | |||
@@ -28,6 +28,20 @@ The scope of what is covered by the version number excludes: | |||
28 | 28 | ||
29 | ## Version history | 29 | ## Version history |
30 | 30 | ||
31 | ### Version 0.4.0, released 20-Jun-2024 | ||
32 | |||
33 | - Feat: `getconsoleflags` and `setconsoleflags` for getting/setting the current console configuration flags on Windows | ||
34 | - Feat: `getconsolecp` and `setconsolecp` for getting/setting the console codepage on Windows | ||
35 | - Feat: `getconsoleoutputcp` and `setconsoleoutputcp` for getting/setting the console output codepage on Windows | ||
36 | - Feat: `tcgetattr` and `tcsetattr` for getting/setting the current console configuration flags on Posix | ||
37 | - Feat: `getnonblock` and `setnonblock` for getting/setting the non-blocking flag on Posix | ||
38 | - Feat: `bitflags`: a support feature for the above flag type controls to facilitate bit manipulation without resorting to binary operations (to also support PuC Lua 5.1) | ||
39 | - Feat: `readkey` reads a keyboard input from `stdin` in a non-blocking way (utf8, also on Windows) | ||
40 | - Feat: `readansi` reads a keyboard input from `stdin` in a non-blocking way, parses ansi and utf8 sequences | ||
41 | - Feat: `termsize` gets the current terminal size in rows and columns | ||
42 | - Feat: `utf8cwidth` and `utf8swidth` for getting the display width (in columns) of respectively a single utf8 character, or a utf8 string | ||
43 | - Feat: helpers; `termbackup`, `termrestore`, `autotermrestore`, and `termwrap` for managing the many terminal settings on all platforms. | ||
44 | |||
31 | ### Version 0.3.0, released 15-Dec-2023 | 45 | ### Version 0.3.0, released 15-Dec-2023 |
32 | 46 | ||
33 | - Feat: on Windows `sleep` now has a precision parameter | 47 | - Feat: on Windows `sleep` now has a precision parameter |
@@ -1,6 +1,6 @@ | |||
1 | # MIT License | 1 | # MIT License |
2 | 2 | ||
3 | ### Copyright (c) 2016-2023 Oscar Lim | 3 | ### Copyright (c) 2016-2024 Oscar Lim |
4 | 4 | ||
5 | Permission is hereby granted, free of charge, to any person obtaining a copy of | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy of |
6 | this software and associated documentation files (the "Software"), to deal in | 6 | this software and associated documentation files (the "Software"), to deal in |
diff --git a/docs/classes/bitflags.html b/docs/classes/bitflags.html new file mode 100644 index 0000000..f063149 --- /dev/null +++ b/docs/classes/bitflags.html | |||
@@ -0,0 +1,305 @@ | |||
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" | ||
2 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> | ||
3 | <html> | ||
4 | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> | ||
5 | <head> | ||
6 | <title>Lua-System docs</title> | ||
7 | <link rel="stylesheet" href="../ldoc.css" type="text/css" /> | ||
8 | </head> | ||
9 | <body> | ||
10 | |||
11 | <div id="container"> | ||
12 | |||
13 | <div id="product"> | ||
14 | <div id="product_logo"></div> | ||
15 | <div id="product_name"><big><b></b></big></div> | ||
16 | <div id="product_description"></div> | ||
17 | </div> <!-- id="product" --> | ||
18 | |||
19 | |||
20 | <div id="main"> | ||
21 | |||
22 | |||
23 | <!-- Menu --> | ||
24 | |||
25 | <div id="navigation"> | ||
26 | <br/> | ||
27 | <h1>Lua-System</h1> | ||
28 | |||
29 | |||
30 | <ul> | ||
31 | <li><a href="../index.html">Index</a></li> | ||
32 | </ul> | ||
33 | |||
34 | <h2>Contents</h2> | ||
35 | <ul> | ||
36 | <li><a href="#Bit_flags">Bit flags </a></li> | ||
37 | </ul> | ||
38 | |||
39 | |||
40 | <h2>Classes</h2> | ||
41 | <ul class="nowrap"> | ||
42 | <li><strong>bitflags</strong></li> | ||
43 | </ul> | ||
44 | <h2>Modules</h2> | ||
45 | <ul class="nowrap"> | ||
46 | <li><a href="../modules/system.html">system</a></li> | ||
47 | </ul> | ||
48 | <h2>Topics</h2> | ||
49 | <ul class=""> | ||
50 | <li><a href="../topics/01-introduction.md.html">1. Introduction</a></li> | ||
51 | <li><a href="../topics/02-development.md.html">2. Development</a></li> | ||
52 | <li><a href="../topics/03-terminal.md.html">3. Terminal functionality</a></li> | ||
53 | <li><a href="../topics/CHANGELOG.md.html">CHANGELOG</a></li> | ||
54 | <li><a href="../topics/LICENSE.md.html">MIT License</a></li> | ||
55 | </ul> | ||
56 | <h2>Examples</h2> | ||
57 | <ul class="nowrap"> | ||
58 | <li><a href="../examples/compat.lua.html">compat.lua</a></li> | ||
59 | <li><a href="../examples/flag_debugging.lua.html">flag_debugging.lua</a></li> | ||
60 | <li><a href="../examples/password_input.lua.html">password_input.lua</a></li> | ||
61 | <li><a href="../examples/read.lua.html">read.lua</a></li> | ||
62 | <li><a href="../examples/readline.lua.html">readline.lua</a></li> | ||
63 | <li><a href="../examples/spinner.lua.html">spinner.lua</a></li> | ||
64 | <li><a href="../examples/spiral_snake.lua.html">spiral_snake.lua</a></li> | ||
65 | <li><a href="../examples/terminalsize.lua.html">terminalsize.lua</a></li> | ||
66 | </ul> | ||
67 | |||
68 | </div> | ||
69 | |||
70 | <div id="content"> | ||
71 | |||
72 | <h1>Class <code>bitflags</code></h1> | ||
73 | <p>Bitflags module.</p> | ||
74 | <p> The bitflag object makes it easy to manipulate flags in a bitmask.</p> | ||
75 | |||
76 | <p> It has metamethods that do the hard work, adding flags sets them, substracting | ||
77 | unsets them. Comparing flags checks if all flags in the second set are also set | ||
78 | in the first set. The <code>has</code> method checks if all flags in the second set are | ||
79 | also set in the first set, but behaves slightly different.</p> | ||
80 | |||
81 | <p> Indexing allows checking values or setting them by bit index (eg. 0-7 for flags | ||
82 | in the first byte).</p> | ||
83 | |||
84 | <p> <em>NOTE</em>: unavailable flags (eg. Windows flags on a Posix system) should not be | ||
85 | omitted, but be assigned a value of 0. This is because the <code>has</code> method will | ||
86 | return <code>false</code> if the flags are checked and the value is 0.</p> | ||
87 | |||
88 | <p> See <a href="../classes/bitflags.html#system.bitflag">system.bitflag</a> (the constructor) for extensive examples on usage.</p> | ||
89 | |||
90 | |||
91 | <h2><a href="#Bit_flags">Bit flags </a></h2> | ||
92 | <table class="function_list"> | ||
93 | <tr> | ||
94 | <td class="name" nowrap><a href="#bitflag:has_all_of">bitflag:has_all_of (subset)</a></td> | ||
95 | <td class="summary">Checks if all the flags in the given subset are set.</td> | ||
96 | </tr> | ||
97 | <tr> | ||
98 | <td class="name" nowrap><a href="#bitflag:has_any_of">bitflag:has_any_of (subset)</a></td> | ||
99 | <td class="summary">Checks if any of the flags in the given subset are set.</td> | ||
100 | </tr> | ||
101 | <tr> | ||
102 | <td class="name" nowrap><a href="#bitflag:value">bitflag:value ()</a></td> | ||
103 | <td class="summary">Retrieves the numeric value of the bitflag object.</td> | ||
104 | </tr> | ||
105 | <tr> | ||
106 | <td class="name" nowrap><a href="#system.bitflag">system.bitflag ([value=0])</a></td> | ||
107 | <td class="summary">Creates a new bitflag object from the given value.</td> | ||
108 | </tr> | ||
109 | </table> | ||
110 | |||
111 | <br/> | ||
112 | <br/> | ||
113 | |||
114 | |||
115 | <h2 class="section-header has-description"><a name="Bit_flags"></a>Bit flags </h2> | ||
116 | |||
117 | <div class="section-description"> | ||
118 | Bitflag objects can be used to easily manipulate and compare bit flags. | ||
119 | These are primarily for use with the terminal functions, but can be used | ||
120 | in other places as well. | ||
121 | </div> | ||
122 | <dl class="function"> | ||
123 | <dt> | ||
124 | <a name = "bitflag:has_all_of"></a> | ||
125 | <strong>bitflag:has_all_of (subset)</strong> | ||
126 | </dt> | ||
127 | <dd> | ||
128 | Checks if all the flags in the given subset are set. | ||
129 | If the flags to check has a value <code>0</code>, it will always return <code>false</code>. So if there are flags that are | ||
130 | unsupported on a platform, they can be set to 0 and the <a href="../classes/bitflags.html#bitflag:has_all_of">has_all_of</a> function will | ||
131 | return <code>false</code> if the flags are checked. | ||
132 | |||
133 | |||
134 | <h3>Parameters:</h3> | ||
135 | <ul> | ||
136 | <li><span class="parameter">subset</span> | ||
137 | <span class="types"><a class="type" href="../classes/bitflags.html#system.bitflag">bitflag</a></span> | ||
138 | the flags to check for. | ||
139 | </li> | ||
140 | </ul> | ||
141 | |||
142 | <h3>Returns:</h3> | ||
143 | <ol> | ||
144 | |||
145 | <span class="types"><span class="type">boolean</span></span> | ||
146 | true if all the flags are set, false otherwise. | ||
147 | </ol> | ||
148 | |||
149 | |||
150 | |||
151 | <h3>Usage:</h3> | ||
152 | <ul> | ||
153 | <pre class="example"><span class="keyword">local</span> sys = <span class="global">require</span> <span class="string">'system'</span> | ||
154 | <span class="keyword">local</span> flags = sys.<span class="function-name">bitflag</span>(<span class="number">12</span>) <span class="comment">-- b1100 | ||
155 | </span><span class="keyword">local</span> myflags = sys.<span class="function-name">bitflag</span>(<span class="number">15</span>) <span class="comment">-- b1111 | ||
156 | </span><span class="global">print</span>(flags:<span class="function-name">has_all_of</span>(myflags)) <span class="comment">-- false, not all bits in myflags are set in flags | ||
157 | </span><span class="global">print</span>(myflags:<span class="function-name">has_all_of</span>(flags)) <span class="comment">-- true, all bits in flags are set in myflags</span></pre> | ||
158 | </ul> | ||
159 | |||
160 | </dd> | ||
161 | <dt> | ||
162 | <a name = "bitflag:has_any_of"></a> | ||
163 | <strong>bitflag:has_any_of (subset)</strong> | ||
164 | </dt> | ||
165 | <dd> | ||
166 | Checks if any of the flags in the given subset are set. | ||
167 | If the flags to check has a value <code>0</code>, it will always return <code>false</code>. So if there are flags that are | ||
168 | unsupported on a platform, they can be set to 0 and the <a href="../classes/bitflags.html#bitflag:has_any_of">has_any_of</a> function will | ||
169 | return <code>false</code> if the flags are checked. | ||
170 | |||
171 | |||
172 | <h3>Parameters:</h3> | ||
173 | <ul> | ||
174 | <li><span class="parameter">subset</span> | ||
175 | <span class="types"><a class="type" href="../classes/bitflags.html#system.bitflag">bitflag</a></span> | ||
176 | the flags to check for. | ||
177 | </li> | ||
178 | </ul> | ||
179 | |||
180 | <h3>Returns:</h3> | ||
181 | <ol> | ||
182 | |||
183 | <span class="types"><span class="type">boolean</span></span> | ||
184 | true if any of the flags are set, false otherwise. | ||
185 | </ol> | ||
186 | |||
187 | |||
188 | |||
189 | <h3>Usage:</h3> | ||
190 | <ul> | ||
191 | <pre class="example"><span class="keyword">local</span> sys = <span class="global">require</span> <span class="string">'system'</span> | ||
192 | <span class="keyword">local</span> flags = sys.<span class="function-name">bitflag</span>(<span class="number">12</span>) <span class="comment">-- b1100 | ||
193 | </span><span class="keyword">local</span> myflags = sys.<span class="function-name">bitflag</span>(<span class="number">7</span>) <span class="comment">-- b0111 | ||
194 | </span><span class="global">print</span>(flags:<span class="function-name">has_any_of</span>(myflags)) <span class="comment">-- true, some bits in myflags are set in flags | ||
195 | </span><span class="global">print</span>(myflags:<span class="function-name">has_any_of</span>(flags)) <span class="comment">-- true, some bits in flags are set in myflags</span></pre> | ||
196 | </ul> | ||
197 | |||
198 | </dd> | ||
199 | <dt> | ||
200 | <a name = "bitflag:value"></a> | ||
201 | <strong>bitflag:value ()</strong> | ||
202 | </dt> | ||
203 | <dd> | ||
204 | Retrieves the numeric value of the bitflag object. | ||
205 | |||
206 | |||
207 | |||
208 | <h3>Returns:</h3> | ||
209 | <ol> | ||
210 | |||
211 | <span class="types"><span class="type">number</span></span> | ||
212 | the numeric value of the bitflags. | ||
213 | </ol> | ||
214 | |||
215 | |||
216 | |||
217 | <h3>Usage:</h3> | ||
218 | <ul> | ||
219 | <pre class="example"><span class="keyword">local</span> sys = <span class="global">require</span> <span class="string">'system'</span> | ||
220 | <span class="keyword">local</span> flags = sys.<span class="function-name">bitflag</span>() <span class="comment">-- b0000 | ||
221 | </span>flags[<span class="number">0</span>] = <span class="keyword">true</span> <span class="comment">-- b0001 | ||
222 | </span>flags[<span class="number">2</span>] = <span class="keyword">true</span> <span class="comment">-- b0101 | ||
223 | </span><span class="global">print</span>(flags:<span class="function-name">value</span>()) <span class="comment">-- 5</span></pre> | ||
224 | </ul> | ||
225 | |||
226 | </dd> | ||
227 | <dt> | ||
228 | <a name = "system.bitflag"></a> | ||
229 | <strong>system.bitflag ([value=0])</strong> | ||
230 | </dt> | ||
231 | <dd> | ||
232 | Creates a new bitflag object from the given value. | ||
233 | |||
234 | |||
235 | <h3>Parameters:</h3> | ||
236 | <ul> | ||
237 | <li><span class="parameter">value</span> | ||
238 | <span class="types"><span class="type">number</span></span> | ||
239 | the value to create the bitflag object from. | ||
240 | (<em>default</em> 0) | ||
241 | </li> | ||
242 | </ul> | ||
243 | |||
244 | <h3>Returns:</h3> | ||
245 | <ol> | ||
246 | |||
247 | <span class="types"><a class="type" href="../classes/bitflags.html#system.bitflag">bitflag</a></span> | ||
248 | bitflag object with the given values set. | ||
249 | </ol> | ||
250 | |||
251 | |||
252 | |||
253 | <h3>Usage:</h3> | ||
254 | <ul> | ||
255 | <pre class="example"><span class="keyword">local</span> sys = <span class="global">require</span> <span class="string">'system'</span> | ||
256 | <span class="keyword">local</span> flags = sys.<span class="function-name">bitflag</span>(<span class="number">2</span>) <span class="comment">-- b0010 | ||
257 | </span> | ||
258 | <span class="comment">-- get state of individual bits | ||
259 | </span><span class="global">print</span>(flags[<span class="number">0</span>]) <span class="comment">-- false | ||
260 | </span><span class="global">print</span>(flags[<span class="number">1</span>]) <span class="comment">-- true | ||
261 | </span> | ||
262 | <span class="comment">-- set individual bits | ||
263 | </span>flags[<span class="number">0</span>] = <span class="keyword">true</span> <span class="comment">-- b0011 | ||
264 | </span><span class="global">print</span>(flags:<span class="function-name">value</span>()) <span class="comment">-- 3 | ||
265 | </span><span class="global">print</span>(flags) <span class="comment">-- "bitflags: 3" | ||
266 | </span> | ||
267 | <span class="comment">-- adding flags (bitwise OR) | ||
268 | </span><span class="keyword">local</span> flags1 = sys.<span class="function-name">bitflag</span>(<span class="number">1</span>) <span class="comment">-- b0001 | ||
269 | </span><span class="keyword">local</span> flags2 = sys.<span class="function-name">bitflag</span>(<span class="number">2</span>) <span class="comment">-- b0010 | ||
270 | </span><span class="keyword">local</span> flags3 = flags1 + flags2 <span class="comment">-- b0011 | ||
271 | </span> | ||
272 | <span class="comment">-- substracting flags (bitwise AND NOT) | ||
273 | </span><span class="global">print</span>(flags3:<span class="function-name">value</span>()) <span class="comment">-- 3 | ||
274 | </span>flag3 = flag3 - flag3 <span class="comment">-- b0000 | ||
275 | </span><span class="global">print</span>(flags3:<span class="function-name">value</span>()) <span class="comment">-- 0 | ||
276 | </span> | ||
277 | <span class="comment">-- comparing flags | ||
278 | </span><span class="keyword">local</span> flags4 = sys.<span class="function-name">bitflag</span>(<span class="number">7</span>) <span class="comment">-- b0111 | ||
279 | </span><span class="keyword">local</span> flags5 = sys.<span class="function-name">bitflag</span>(<span class="number">255</span>) <span class="comment">-- b11111111 | ||
280 | </span><span class="global">print</span>(flags5 ~= flags4) <span class="comment">-- true, not the same flags | ||
281 | </span><span class="keyword">local</span> flags6 = sys.<span class="function-name">bitflag</span>(<span class="number">7</span>) <span class="comment">-- b0111 | ||
282 | </span><span class="global">print</span>(flags6 == flags4) <span class="comment">-- true, same flags | ||
283 | </span> | ||
284 | <span class="comment">-- comparison of subsets | ||
285 | </span><span class="keyword">local</span> flags7 = sys.<span class="function-name">bitflag</span>(<span class="number">0</span>) <span class="comment">-- b0000 | ||
286 | </span><span class="keyword">local</span> flags8 = sys.<span class="function-name">bitflag</span>(<span class="number">3</span>) <span class="comment">-- b0011 | ||
287 | </span><span class="keyword">local</span> flags9 = sys.<span class="function-name">bitflag</span>(<span class="number">7</span>) <span class="comment">-- b0111 | ||
288 | </span><span class="global">print</span>(flags9:<span class="function-name">has_all_of</span>(flags8)) <span class="comment">-- true, flags8 bits are all set in flags9 | ||
289 | </span><span class="global">print</span>(flags8:<span class="function-name">has_any_of</span>(flags9)) <span class="comment">-- true, some of flags9 bits are set in flags8 | ||
290 | </span><span class="global">print</span>(flags8:<span class="function-name">has_all_of</span>(flags7)) <span class="comment">-- false, flags7 (== 0) is not set in flags8</span></pre> | ||
291 | </ul> | ||
292 | |||
293 | </dd> | ||
294 | </dl> | ||
295 | |||
296 | |||
297 | </div> <!-- id="content" --> | ||
298 | </div> <!-- id="main" --> | ||
299 | <div id="about"> | ||
300 | <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i> | ||
301 | <i style="float:right;">Last updated 2024-06-20 23:11:37 </i> | ||
302 | </div> <!-- id="about" --> | ||
303 | </div> <!-- id="container" --> | ||
304 | </body> | ||
305 | </html> | ||
diff --git a/docs/examples/compat.lua.html b/docs/examples/compat.lua.html new file mode 100644 index 0000000..a0abafe --- /dev/null +++ b/docs/examples/compat.lua.html | |||
@@ -0,0 +1,119 @@ | |||
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" | ||
2 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> | ||
3 | <html> | ||
4 | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> | ||
5 | <head> | ||
6 | <title>Lua-System docs</title> | ||
7 | <link rel="stylesheet" href="../ldoc.css" type="text/css" /> | ||
8 | </head> | ||
9 | <body> | ||
10 | |||
11 | <div id="container"> | ||
12 | |||
13 | <div id="product"> | ||
14 | <div id="product_logo"></div> | ||
15 | <div id="product_name"><big><b></b></big></div> | ||
16 | <div id="product_description"></div> | ||
17 | </div> <!-- id="product" --> | ||
18 | |||
19 | |||
20 | <div id="main"> | ||
21 | |||
22 | |||
23 | <!-- Menu --> | ||
24 | |||
25 | <div id="navigation"> | ||
26 | <br/> | ||
27 | <h1>Lua-System</h1> | ||
28 | |||
29 | |||
30 | <ul> | ||
31 | <li><a href="../index.html">Index</a></li> | ||
32 | </ul> | ||
33 | |||
34 | |||
35 | |||
36 | <h2>Examples</h2> | ||
37 | <ul class="nowrap"> | ||
38 | <li><strong>compat.lua</strong></li> | ||
39 | <li><a href="../examples/flag_debugging.lua.html">flag_debugging.lua</a></li> | ||
40 | <li><a href="../examples/password_input.lua.html">password_input.lua</a></li> | ||
41 | <li><a href="../examples/read.lua.html">read.lua</a></li> | ||
42 | <li><a href="../examples/readline.lua.html">readline.lua</a></li> | ||
43 | <li><a href="../examples/spinner.lua.html">spinner.lua</a></li> | ||
44 | <li><a href="../examples/spiral_snake.lua.html">spiral_snake.lua</a></li> | ||
45 | <li><a href="../examples/terminalsize.lua.html">terminalsize.lua</a></li> | ||
46 | </ul> | ||
47 | <h2>Modules</h2> | ||
48 | <ul class="nowrap"> | ||
49 | <li><a href="../modules/system.html">system</a></li> | ||
50 | </ul> | ||
51 | <h2>Classes</h2> | ||
52 | <ul class="nowrap"> | ||
53 | <li><a href="../classes/bitflags.html">bitflags</a></li> | ||
54 | </ul> | ||
55 | <h2>Topics</h2> | ||
56 | <ul class=""> | ||
57 | <li><a href="../topics/01-introduction.md.html">1. Introduction</a></li> | ||
58 | <li><a href="../topics/02-development.md.html">2. Development</a></li> | ||
59 | <li><a href="../topics/03-terminal.md.html">3. Terminal functionality</a></li> | ||
60 | <li><a href="../topics/CHANGELOG.md.html">CHANGELOG</a></li> | ||
61 | <li><a href="../topics/LICENSE.md.html">MIT License</a></li> | ||
62 | </ul> | ||
63 | |||
64 | </div> | ||
65 | |||
66 | <div id="content"> | ||
67 | |||
68 | <h2>compat.lua</h2> | ||
69 | <pre> | ||
70 | <span class="comment">-- This example shows how to remove platform differences to create a | ||
71 | </span><span class="comment">-- cross-platform level playing field. | ||
72 | </span> | ||
73 | <span class="keyword">local</span> sys = <span class="global">require</span> <span class="string">"system"</span> | ||
74 | |||
75 | |||
76 | |||
77 | <span class="keyword">if</span> sys.windows <span class="keyword">then</span> | ||
78 | <span class="comment">-- Windows holds multiple copies of environment variables, to ensure <code>getenv</code> | ||
79 | </span> <span class="comment">-- returns what <code>setenv</code> sets we need to use the <a href="../modules/system.html#getenv">system.getenv</a> instead of | ||
80 | </span> <span class="comment">-- <a href="https://www.lua.org/manual/5.4/manual.html#pdf-os.getenv">os.getenv</a>. | ||
81 | </span> <span class="global">os</span>.getenv = sys.getenv <span class="comment">-- luacheck: ignore | ||
82 | </span> | ||
83 | <span class="comment">-- Set console output to UTF-8 encoding. | ||
84 | </span> sys.<span class="function-name">setconsoleoutputcp</span>(sys.CODEPAGE_UTF8) | ||
85 | |||
86 | <span class="comment">-- Set up the terminal to handle ANSI escape sequences on Windows. | ||
87 | </span> <span class="keyword">if</span> sys.<span class="function-name">isatty</span>(<span class="global">io</span>.stdout) <span class="keyword">then</span> | ||
88 | sys.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdout, sys.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout) + sys.COF_VIRTUAL_TERMINAL_PROCESSING) | ||
89 | <span class="keyword">end</span> | ||
90 | <span class="keyword">if</span> sys.<span class="function-name">isatty</span>(<span class="global">io</span>.stderr) <span class="keyword">then</span> | ||
91 | sys.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stderr, sys.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stderr) + sys.COF_VIRTUAL_TERMINAL_PROCESSING) | ||
92 | <span class="keyword">end</span> | ||
93 | <span class="keyword">if</span> sys.<span class="function-name">isatty</span>(<span class="global">io</span>.stdin) <span class="keyword">then</span> | ||
94 | sys.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdin, sys.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout) + sys.ENABLE_VIRTUAL_TERMINAL_INPUT) | ||
95 | <span class="keyword">end</span> | ||
96 | |||
97 | |||
98 | <span class="keyword">else</span> | ||
99 | <span class="comment">-- On Posix, one can set a variable to an empty string, but on Windows, this | ||
100 | </span> <span class="comment">-- will remove the variable from the environment. To make this consistent | ||
101 | </span> <span class="comment">-- across platforms, we will remove the variable from the environment if the | ||
102 | </span> <span class="comment">-- value is an empty string. | ||
103 | </span> <span class="keyword">local</span> old_setenv = sys.setenv | ||
104 | <span class="keyword">function</span> sys.<span class="function-name">setenv</span>(name, value) | ||
105 | <span class="keyword">if</span> value == <span class="string">""</span> <span class="keyword">then</span> value = <span class="keyword">nil</span> <span class="keyword">end</span> | ||
106 | <span class="keyword">return</span> <span class="function-name">old_setenv</span>(name, value) | ||
107 | <span class="keyword">end</span> | ||
108 | <span class="keyword">end</span></pre> | ||
109 | |||
110 | |||
111 | </div> <!-- id="content" --> | ||
112 | </div> <!-- id="main" --> | ||
113 | <div id="about"> | ||
114 | <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i> | ||
115 | <i style="float:right;">Last updated 2024-06-20 23:11:37 </i> | ||
116 | </div> <!-- id="about" --> | ||
117 | </div> <!-- id="container" --> | ||
118 | </body> | ||
119 | </html> | ||
diff --git a/docs/examples/flag_debugging.lua.html b/docs/examples/flag_debugging.lua.html new file mode 100644 index 0000000..38f506a --- /dev/null +++ b/docs/examples/flag_debugging.lua.html | |||
@@ -0,0 +1,87 @@ | |||
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" | ||
2 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> | ||
3 | <html> | ||
4 | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> | ||
5 | <head> | ||
6 | <title>Lua-System docs</title> | ||
7 | <link rel="stylesheet" href="../ldoc.css" type="text/css" /> | ||
8 | </head> | ||
9 | <body> | ||
10 | |||
11 | <div id="container"> | ||
12 | |||
13 | <div id="product"> | ||
14 | <div id="product_logo"></div> | ||
15 | <div id="product_name"><big><b></b></big></div> | ||
16 | <div id="product_description"></div> | ||
17 | </div> <!-- id="product" --> | ||
18 | |||
19 | |||
20 | <div id="main"> | ||
21 | |||
22 | |||
23 | <!-- Menu --> | ||
24 | |||
25 | <div id="navigation"> | ||
26 | <br/> | ||
27 | <h1>Lua-System</h1> | ||
28 | |||
29 | |||
30 | <ul> | ||
31 | <li><a href="../index.html">Index</a></li> | ||
32 | </ul> | ||
33 | |||
34 | |||
35 | |||
36 | <h2>Examples</h2> | ||
37 | <ul class="nowrap"> | ||
38 | <li><a href="../examples/compat.lua.html">compat.lua</a></li> | ||
39 | <li><strong>flag_debugging.lua</strong></li> | ||
40 | <li><a href="../examples/password_input.lua.html">password_input.lua</a></li> | ||
41 | <li><a href="../examples/read.lua.html">read.lua</a></li> | ||
42 | <li><a href="../examples/readline.lua.html">readline.lua</a></li> | ||
43 | <li><a href="../examples/spinner.lua.html">spinner.lua</a></li> | ||
44 | <li><a href="../examples/spiral_snake.lua.html">spiral_snake.lua</a></li> | ||
45 | <li><a href="../examples/terminalsize.lua.html">terminalsize.lua</a></li> | ||
46 | </ul> | ||
47 | <h2>Modules</h2> | ||
48 | <ul class="nowrap"> | ||
49 | <li><a href="../modules/system.html">system</a></li> | ||
50 | </ul> | ||
51 | <h2>Classes</h2> | ||
52 | <ul class="nowrap"> | ||
53 | <li><a href="../classes/bitflags.html">bitflags</a></li> | ||
54 | </ul> | ||
55 | <h2>Topics</h2> | ||
56 | <ul class=""> | ||
57 | <li><a href="../topics/01-introduction.md.html">1. Introduction</a></li> | ||
58 | <li><a href="../topics/02-development.md.html">2. Development</a></li> | ||
59 | <li><a href="../topics/03-terminal.md.html">3. Terminal functionality</a></li> | ||
60 | <li><a href="../topics/CHANGELOG.md.html">CHANGELOG</a></li> | ||
61 | <li><a href="../topics/LICENSE.md.html">MIT License</a></li> | ||
62 | </ul> | ||
63 | |||
64 | </div> | ||
65 | |||
66 | <div id="content"> | ||
67 | |||
68 | <h2>flag_debugging.lua</h2> | ||
69 | <pre> | ||
70 | <span class="keyword">local</span> sys = <span class="global">require</span> <span class="string">"system"</span> | ||
71 | |||
72 | <span class="comment">-- Print the Windows Console flags for stdin | ||
73 | </span>sys.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdin) | ||
74 | |||
75 | <span class="comment">-- Print the Posix termios flags for stdin | ||
76 | </span>sys.<span class="function-name">listtermflags</span>(<span class="global">io</span>.stdin)</pre> | ||
77 | |||
78 | |||
79 | </div> <!-- id="content" --> | ||
80 | </div> <!-- id="main" --> | ||
81 | <div id="about"> | ||
82 | <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i> | ||
83 | <i style="float:right;">Last updated 2024-06-20 23:11:37 </i> | ||
84 | </div> <!-- id="about" --> | ||
85 | </div> <!-- id="container" --> | ||
86 | </body> | ||
87 | </html> | ||
diff --git a/docs/examples/password_input.lua.html b/docs/examples/password_input.lua.html new file mode 100644 index 0000000..4234fbb --- /dev/null +++ b/docs/examples/password_input.lua.html | |||
@@ -0,0 +1,139 @@ | |||
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" | ||
2 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> | ||
3 | <html> | ||
4 | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> | ||
5 | <head> | ||
6 | <title>Lua-System docs</title> | ||
7 | <link rel="stylesheet" href="../ldoc.css" type="text/css" /> | ||
8 | </head> | ||
9 | <body> | ||
10 | |||
11 | <div id="container"> | ||
12 | |||
13 | <div id="product"> | ||
14 | <div id="product_logo"></div> | ||
15 | <div id="product_name"><big><b></b></big></div> | ||
16 | <div id="product_description"></div> | ||
17 | </div> <!-- id="product" --> | ||
18 | |||
19 | |||
20 | <div id="main"> | ||
21 | |||
22 | |||
23 | <!-- Menu --> | ||
24 | |||
25 | <div id="navigation"> | ||
26 | <br/> | ||
27 | <h1>Lua-System</h1> | ||
28 | |||
29 | |||
30 | <ul> | ||
31 | <li><a href="../index.html">Index</a></li> | ||
32 | </ul> | ||
33 | |||
34 | |||
35 | |||
36 | <h2>Examples</h2> | ||
37 | <ul class="nowrap"> | ||
38 | <li><a href="../examples/compat.lua.html">compat.lua</a></li> | ||
39 | <li><a href="../examples/flag_debugging.lua.html">flag_debugging.lua</a></li> | ||
40 | <li><strong>password_input.lua</strong></li> | ||
41 | <li><a href="../examples/read.lua.html">read.lua</a></li> | ||
42 | <li><a href="../examples/readline.lua.html">readline.lua</a></li> | ||
43 | <li><a href="../examples/spinner.lua.html">spinner.lua</a></li> | ||
44 | <li><a href="../examples/spiral_snake.lua.html">spiral_snake.lua</a></li> | ||
45 | <li><a href="../examples/terminalsize.lua.html">terminalsize.lua</a></li> | ||
46 | </ul> | ||
47 | <h2>Modules</h2> | ||
48 | <ul class="nowrap"> | ||
49 | <li><a href="../modules/system.html">system</a></li> | ||
50 | </ul> | ||
51 | <h2>Classes</h2> | ||
52 | <ul class="nowrap"> | ||
53 | <li><a href="../classes/bitflags.html">bitflags</a></li> | ||
54 | </ul> | ||
55 | <h2>Topics</h2> | ||
56 | <ul class=""> | ||
57 | <li><a href="../topics/01-introduction.md.html">1. Introduction</a></li> | ||
58 | <li><a href="../topics/02-development.md.html">2. Development</a></li> | ||
59 | <li><a href="../topics/03-terminal.md.html">3. Terminal functionality</a></li> | ||
60 | <li><a href="../topics/CHANGELOG.md.html">CHANGELOG</a></li> | ||
61 | <li><a href="../topics/LICENSE.md.html">MIT License</a></li> | ||
62 | </ul> | ||
63 | |||
64 | </div> | ||
65 | |||
66 | <div id="content"> | ||
67 | |||
68 | <h2>password_input.lua</h2> | ||
69 | <pre> | ||
70 | <span class="keyword">local</span> sys = <span class="global">require</span> <span class="string">"system"</span> | ||
71 | |||
72 | <span class="global">print</span> <span class="string">[[ | ||
73 | |||
74 | This example shows how to disable the "echo" of characters read to the console, | ||
75 | useful for reading secrets from the user. | ||
76 | |||
77 | ]]</span> | ||
78 | |||
79 | <span class="comment">--- Function to read from stdin without echoing the input (for secrets etc). | ||
80 | </span><span class="comment">-- It will (in a platform agnostic way) disable echo on the terminal, read the | ||
81 | </span><span class="comment">-- input, and then re-enable echo. | ||
82 | </span><span class="comment">-- @param ... Arguments to pass to <code>io.stdin:read()</code> | ||
83 | </span><span class="comment">-- @return the results of <code>io.stdin:read(...)</code> | ||
84 | </span><span class="keyword">local</span> <span class="keyword">function</span> <span class="function-name">read_secret</span>(...) | ||
85 | <span class="keyword">local</span> w_oldflags, p_oldflags | ||
86 | |||
87 | <span class="keyword">if</span> sys.<span class="function-name">isatty</span>(<span class="global">io</span>.stdin) <span class="keyword">then</span> | ||
88 | <span class="comment">-- backup settings, configure echo flags | ||
89 | </span> w_oldflags = sys.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdin) | ||
90 | p_oldflags = sys.<span class="function-name">tcgetattr</span>(<span class="global">io</span>.stdin) | ||
91 | <span class="comment">-- set echo off to not show password on screen | ||
92 | </span> <span class="global">assert</span>(sys.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdin, w_oldflags - sys.CIF_ECHO_INPUT)) | ||
93 | <span class="global">assert</span>(sys.<span class="function-name">tcsetattr</span>(<span class="global">io</span>.stdin, sys.TCSANOW, { lflag = p_oldflags.lflag - sys.L_ECHO })) | ||
94 | <span class="keyword">end</span> | ||
95 | |||
96 | <span class="keyword">local</span> secret, err = <span class="global">io</span>.stdin:<span class="function-name">read</span>(...) | ||
97 | |||
98 | <span class="comment">-- restore settings | ||
99 | </span> <span class="keyword">if</span> sys.<span class="function-name">isatty</span>(<span class="global">io</span>.stdin) <span class="keyword">then</span> | ||
100 | <span class="global">io</span>.stdout:<span class="function-name">write</span>(<span class="string">"\n"</span>) <span class="comment">-- Add newline after reading the password | ||
101 | </span> sys.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdin, w_oldflags) | ||
102 | sys.<span class="function-name">tcsetattr</span>(<span class="global">io</span>.stdin, sys.TCSANOW, p_oldflags) | ||
103 | <span class="keyword">end</span> | ||
104 | |||
105 | <span class="keyword">return</span> secret, err | ||
106 | <span class="keyword">end</span> | ||
107 | |||
108 | |||
109 | |||
110 | <span class="comment">-- Get username | ||
111 | </span><span class="global">io</span>.<span class="function-name">write</span>(<span class="string">"Username: "</span>) | ||
112 | <span class="keyword">local</span> username = <span class="global">io</span>.stdin:<span class="function-name">read</span>(<span class="string">"*l"</span>) | ||
113 | |||
114 | <span class="comment">-- Get the secret | ||
115 | </span><span class="global">io</span>.<span class="function-name">write</span>(<span class="string">"Password: "</span>) | ||
116 | <span class="keyword">local</span> password = <span class="function-name">read_secret</span>(<span class="string">"*l"</span>) | ||
117 | |||
118 | <span class="comment">-- Get domainname | ||
119 | </span><span class="global">io</span>.<span class="function-name">write</span>(<span class="string">"Domain : "</span>) | ||
120 | <span class="keyword">local</span> domain = <span class="global">io</span>.stdin:<span class="function-name">read</span>(<span class="string">"*l"</span>) | ||
121 | |||
122 | |||
123 | <span class="comment">-- Print the results | ||
124 | </span><span class="global">print</span>(<span class="string">""</span>) | ||
125 | <span class="global">print</span>(<span class="string">"Here's what we got:"</span>) | ||
126 | <span class="global">print</span>(<span class="string">" username: "</span> .. username) | ||
127 | <span class="global">print</span>(<span class="string">" password: "</span> .. password) | ||
128 | <span class="global">print</span>(<span class="string">" domain : "</span> .. domain)</pre> | ||
129 | |||
130 | |||
131 | </div> <!-- id="content" --> | ||
132 | </div> <!-- id="main" --> | ||
133 | <div id="about"> | ||
134 | <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i> | ||
135 | <i style="float:right;">Last updated 2024-06-20 23:11:37 </i> | ||
136 | </div> <!-- id="about" --> | ||
137 | </div> <!-- id="container" --> | ||
138 | </body> | ||
139 | </html> | ||
diff --git a/docs/examples/read.lua.html b/docs/examples/read.lua.html new file mode 100644 index 0000000..c7697d3 --- /dev/null +++ b/docs/examples/read.lua.html | |||
@@ -0,0 +1,150 @@ | |||
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" | ||
2 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> | ||
3 | <html> | ||
4 | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> | ||
5 | <head> | ||
6 | <title>Lua-System docs</title> | ||
7 | <link rel="stylesheet" href="../ldoc.css" type="text/css" /> | ||
8 | </head> | ||
9 | <body> | ||
10 | |||
11 | <div id="container"> | ||
12 | |||
13 | <div id="product"> | ||
14 | <div id="product_logo"></div> | ||
15 | <div id="product_name"><big><b></b></big></div> | ||
16 | <div id="product_description"></div> | ||
17 | </div> <!-- id="product" --> | ||
18 | |||
19 | |||
20 | <div id="main"> | ||
21 | |||
22 | |||
23 | <!-- Menu --> | ||
24 | |||
25 | <div id="navigation"> | ||
26 | <br/> | ||
27 | <h1>Lua-System</h1> | ||
28 | |||
29 | |||
30 | <ul> | ||
31 | <li><a href="../index.html">Index</a></li> | ||
32 | </ul> | ||
33 | |||
34 | |||
35 | |||
36 | <h2>Examples</h2> | ||
37 | <ul class="nowrap"> | ||
38 | <li><a href="../examples/compat.lua.html">compat.lua</a></li> | ||
39 | <li><a href="../examples/flag_debugging.lua.html">flag_debugging.lua</a></li> | ||
40 | <li><a href="../examples/password_input.lua.html">password_input.lua</a></li> | ||
41 | <li><strong>read.lua</strong></li> | ||
42 | <li><a href="../examples/readline.lua.html">readline.lua</a></li> | ||
43 | <li><a href="../examples/spinner.lua.html">spinner.lua</a></li> | ||
44 | <li><a href="../examples/spiral_snake.lua.html">spiral_snake.lua</a></li> | ||
45 | <li><a href="../examples/terminalsize.lua.html">terminalsize.lua</a></li> | ||
46 | </ul> | ||
47 | <h2>Modules</h2> | ||
48 | <ul class="nowrap"> | ||
49 | <li><a href="../modules/system.html">system</a></li> | ||
50 | </ul> | ||
51 | <h2>Classes</h2> | ||
52 | <ul class="nowrap"> | ||
53 | <li><a href="../classes/bitflags.html">bitflags</a></li> | ||
54 | </ul> | ||
55 | <h2>Topics</h2> | ||
56 | <ul class=""> | ||
57 | <li><a href="../topics/01-introduction.md.html">1. Introduction</a></li> | ||
58 | <li><a href="../topics/02-development.md.html">2. Development</a></li> | ||
59 | <li><a href="../topics/03-terminal.md.html">3. Terminal functionality</a></li> | ||
60 | <li><a href="../topics/CHANGELOG.md.html">CHANGELOG</a></li> | ||
61 | <li><a href="../topics/LICENSE.md.html">MIT License</a></li> | ||
62 | </ul> | ||
63 | |||
64 | </div> | ||
65 | |||
66 | <div id="content"> | ||
67 | |||
68 | <h2>read.lua</h2> | ||
69 | <pre> | ||
70 | <span class="keyword">local</span> sys = <span class="global">require</span> <span class="string">"system"</span> | ||
71 | |||
72 | <span class="global">print</span> <span class="string">[[ | ||
73 | |||
74 | This example shows how to do a non-blocking read from the cli. | ||
75 | |||
76 | ]]</span> | ||
77 | |||
78 | <span class="comment">-- setup Windows console to handle ANSI processing | ||
79 | </span><span class="keyword">local</span> of_in = sys.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdin) | ||
80 | <span class="keyword">local</span> of_out = sys.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout) | ||
81 | sys.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdout, sys.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout) + sys.COF_VIRTUAL_TERMINAL_PROCESSING) | ||
82 | sys.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdin, sys.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdin) + sys.CIF_VIRTUAL_TERMINAL_INPUT) | ||
83 | |||
84 | <span class="comment">-- setup Posix terminal to use non-blocking mode, and disable line-mode | ||
85 | </span><span class="keyword">local</span> of_attr = sys.<span class="function-name">tcgetattr</span>(<span class="global">io</span>.stdin) | ||
86 | <span class="keyword">local</span> of_block = sys.<span class="function-name">getnonblock</span>(<span class="global">io</span>.stdin) | ||
87 | sys.<span class="function-name">setnonblock</span>(<span class="global">io</span>.stdin, <span class="keyword">true</span>) | ||
88 | sys.<span class="function-name">tcsetattr</span>(<span class="global">io</span>.stdin, sys.TCSANOW, { | ||
89 | lflag = of_attr.lflag - sys.L_ICANON - sys.L_ECHO, <span class="comment">-- disable canonical mode and echo | ||
90 | </span>}) | ||
91 | |||
92 | <span class="comment">-- cursor sequences | ||
93 | </span><span class="keyword">local</span> get_cursor_pos = <span class="string">"\27[6n"</span> | ||
94 | |||
95 | |||
96 | |||
97 | <span class="global">print</span>(<span class="string">"Press a key, or 'A' to get cursor position, 'ESC' to exit"</span>) | ||
98 | <span class="keyword">while</span> <span class="keyword">true</span> <span class="keyword">do</span> | ||
99 | <span class="keyword">local</span> key, keytype | ||
100 | |||
101 | <span class="comment">-- wait for a key | ||
102 | </span> <span class="keyword">while</span> <span class="keyword">not</span> key <span class="keyword">do</span> | ||
103 | key, keytype = sys.<span class="function-name">readansi</span>(<span class="global">math</span>.huge) | ||
104 | <span class="keyword">end</span> | ||
105 | |||
106 | <span class="keyword">if</span> key == <span class="string">"A"</span> <span class="keyword">then</span> <span class="global">io</span>.<span class="function-name">write</span>(get_cursor_pos); <span class="global">io</span>.<span class="function-name">flush</span>() <span class="keyword">end</span> | ||
107 | |||
108 | <span class="comment">-- check if we got a key or ANSI sequence | ||
109 | </span> <span class="keyword">if</span> keytype == <span class="string">"char"</span> <span class="keyword">then</span> | ||
110 | <span class="comment">-- just a key | ||
111 | </span> <span class="keyword">local</span> b = key:<span class="function-name">byte</span>() | ||
112 | <span class="keyword">if</span> b < <span class="number">32</span> <span class="keyword">then</span> | ||
113 | key = <span class="string">"."</span> <span class="comment">-- replace control characters with a simple "." to not mess up the screen | ||
114 | </span> <span class="keyword">end</span> | ||
115 | |||
116 | <span class="global">print</span>(<span class="string">"you pressed: "</span> .. key .. <span class="string">" ("</span> .. b .. <span class="string">")"</span>) | ||
117 | <span class="keyword">if</span> b == <span class="number">27</span> <span class="keyword">then</span> | ||
118 | <span class="global">print</span>(<span class="string">"Escape pressed, exiting"</span>) | ||
119 | <span class="keyword">break</span> | ||
120 | <span class="keyword">end</span> | ||
121 | |||
122 | <span class="keyword">elseif</span> keytype == <span class="string">"ansi"</span> <span class="keyword">then</span> | ||
123 | <span class="comment">-- we got an ANSI sequence | ||
124 | </span> <span class="keyword">local</span> seq = { key:<span class="function-name">byte</span>(<span class="number">1</span>, #key) } | ||
125 | <span class="global">print</span>(<span class="string">"ANSI sequence received: "</span> .. key:<span class="function-name">sub</span>(<span class="number">2</span>,-<span class="number">1</span>), <span class="string">"(bytes: "</span> .. <span class="global">table</span>.<span class="function-name">concat</span>(seq, <span class="string">", "</span>)..<span class="string">")"</span>) | ||
126 | |||
127 | <span class="keyword">else</span> | ||
128 | <span class="global">print</span>(<span class="string">"unknown key type received: "</span> .. <span class="global">tostring</span>(keytype)) | ||
129 | <span class="keyword">end</span> | ||
130 | <span class="keyword">end</span> | ||
131 | |||
132 | |||
133 | |||
134 | <span class="comment">-- Clean up afterwards | ||
135 | </span>sys.<span class="function-name">setnonblock</span>(<span class="global">io</span>.stdin, <span class="keyword">false</span>) | ||
136 | sys.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdout, of_out) | ||
137 | sys.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdin, of_in) | ||
138 | sys.<span class="function-name">tcsetattr</span>(<span class="global">io</span>.stdin, sys.TCSANOW, of_attr) | ||
139 | sys.<span class="function-name">setnonblock</span>(<span class="global">io</span>.stdin, of_block)</pre> | ||
140 | |||
141 | |||
142 | </div> <!-- id="content" --> | ||
143 | </div> <!-- id="main" --> | ||
144 | <div id="about"> | ||
145 | <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i> | ||
146 | <i style="float:right;">Last updated 2024-06-20 23:11:37 </i> | ||
147 | </div> <!-- id="about" --> | ||
148 | </div> <!-- id="container" --> | ||
149 | </body> | ||
150 | </html> | ||
diff --git a/docs/examples/readline.lua.html b/docs/examples/readline.lua.html new file mode 100644 index 0000000..7895a81 --- /dev/null +++ b/docs/examples/readline.lua.html | |||
@@ -0,0 +1,552 @@ | |||
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" | ||
2 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> | ||
3 | <html> | ||
4 | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> | ||
5 | <head> | ||
6 | <title>Lua-System docs</title> | ||
7 | <link rel="stylesheet" href="../ldoc.css" type="text/css" /> | ||
8 | </head> | ||
9 | <body> | ||
10 | |||
11 | <div id="container"> | ||
12 | |||
13 | <div id="product"> | ||
14 | <div id="product_logo"></div> | ||
15 | <div id="product_name"><big><b></b></big></div> | ||
16 | <div id="product_description"></div> | ||
17 | </div> <!-- id="product" --> | ||
18 | |||
19 | |||
20 | <div id="main"> | ||
21 | |||
22 | |||
23 | <!-- Menu --> | ||
24 | |||
25 | <div id="navigation"> | ||
26 | <br/> | ||
27 | <h1>Lua-System</h1> | ||
28 | |||
29 | |||
30 | <ul> | ||
31 | <li><a href="../index.html">Index</a></li> | ||
32 | </ul> | ||
33 | |||
34 | |||
35 | |||
36 | <h2>Examples</h2> | ||
37 | <ul class="nowrap"> | ||
38 | <li><a href="../examples/compat.lua.html">compat.lua</a></li> | ||
39 | <li><a href="../examples/flag_debugging.lua.html">flag_debugging.lua</a></li> | ||
40 | <li><a href="../examples/password_input.lua.html">password_input.lua</a></li> | ||
41 | <li><a href="../examples/read.lua.html">read.lua</a></li> | ||
42 | <li><strong>readline.lua</strong></li> | ||
43 | <li><a href="../examples/spinner.lua.html">spinner.lua</a></li> | ||
44 | <li><a href="../examples/spiral_snake.lua.html">spiral_snake.lua</a></li> | ||
45 | <li><a href="../examples/terminalsize.lua.html">terminalsize.lua</a></li> | ||
46 | </ul> | ||
47 | <h2>Modules</h2> | ||
48 | <ul class="nowrap"> | ||
49 | <li><a href="../modules/system.html">system</a></li> | ||
50 | </ul> | ||
51 | <h2>Classes</h2> | ||
52 | <ul class="nowrap"> | ||
53 | <li><a href="../classes/bitflags.html">bitflags</a></li> | ||
54 | </ul> | ||
55 | <h2>Topics</h2> | ||
56 | <ul class=""> | ||
57 | <li><a href="../topics/01-introduction.md.html">1. Introduction</a></li> | ||
58 | <li><a href="../topics/02-development.md.html">2. Development</a></li> | ||
59 | <li><a href="../topics/03-terminal.md.html">3. Terminal functionality</a></li> | ||
60 | <li><a href="../topics/CHANGELOG.md.html">CHANGELOG</a></li> | ||
61 | <li><a href="../topics/LICENSE.md.html">MIT License</a></li> | ||
62 | </ul> | ||
63 | |||
64 | </div> | ||
65 | |||
66 | <div id="content"> | ||
67 | |||
68 | <h2>readline.lua</h2> | ||
69 | <pre> | ||
70 | <span class="comment">--- An example class for reading a line of input from the user in a non-blocking way. | ||
71 | </span><span class="comment">-- It uses ANSI escape sequences to move the cursor and handle input. | ||
72 | </span><span class="comment">-- It can be used to read a line of input from the user, with a prompt. | ||
73 | </span><span class="comment">-- It can handle double-width UTF-8 characters. | ||
74 | </span><span class="comment">-- It can be used asynchroneously if <a href="../modules/system.html#sleep">system.sleep</a> is patched to yield to a coroutine scheduler. | ||
75 | </span> | ||
76 | <span class="keyword">local</span> sys = <span class="global">require</span>(<span class="string">"system"</span>) | ||
77 | |||
78 | |||
79 | <span class="comment">-- Mapping of key-sequences to key-names | ||
80 | </span><span class="keyword">local</span> key_names = { | ||
81 | [<span class="string">"\27[C"</span>] = <span class="string">"right"</span>, | ||
82 | [<span class="string">"\27[D"</span>] = <span class="string">"left"</span>, | ||
83 | [<span class="string">"\127"</span>] = <span class="string">"backspace"</span>, | ||
84 | [<span class="string">"\27[3~"</span>] = <span class="string">"delete"</span>, | ||
85 | [<span class="string">"\27[H"</span>] = <span class="string">"home"</span>, | ||
86 | [<span class="string">"\27[F"</span>] = <span class="string">"end"</span>, | ||
87 | [<span class="string">"\27"</span>] = <span class="string">"escape"</span>, | ||
88 | [<span class="string">"\9"</span>] = <span class="string">"tab"</span>, | ||
89 | [<span class="string">"\27[Z"</span>] = <span class="string">"shift-tab"</span>, | ||
90 | } | ||
91 | |||
92 | <span class="keyword">if</span> sys.windows <span class="keyword">then</span> | ||
93 | key_names[<span class="string">"\13"</span>] = <span class="string">"enter"</span> | ||
94 | <span class="keyword">else</span> | ||
95 | key_names[<span class="string">"\10"</span>] = <span class="string">"enter"</span> | ||
96 | <span class="keyword">end</span> | ||
97 | |||
98 | |||
99 | <span class="comment">-- Mapping of key-names to key-sequences | ||
100 | </span><span class="keyword">local</span> key_sequences = {} | ||
101 | <span class="keyword">for</span> k, v <span class="keyword">in</span> <span class="global">pairs</span>(key_names) <span class="keyword">do</span> | ||
102 | key_sequences[v] = k | ||
103 | <span class="keyword">end</span> | ||
104 | |||
105 | |||
106 | <span class="comment">-- bell character | ||
107 | </span><span class="keyword">local</span> <span class="keyword">function</span> <span class="function-name">bell</span>() | ||
108 | <span class="global">io</span>.<span class="function-name">write</span>(<span class="string">"\7"</span>) | ||
109 | <span class="global">io</span>.<span class="function-name">flush</span>() | ||
110 | <span class="keyword">end</span> | ||
111 | |||
112 | |||
113 | <span class="comment">-- generate string to move cursor horizontally | ||
114 | </span><span class="comment">-- positive goes right, negative goes left | ||
115 | </span><span class="keyword">local</span> <span class="keyword">function</span> <span class="function-name">cursor_move_horiz</span>(n) | ||
116 | <span class="keyword">if</span> n == <span class="number">0</span> <span class="keyword">then</span> | ||
117 | <span class="keyword">return</span> <span class="string">""</span> | ||
118 | <span class="keyword">end</span> | ||
119 | <span class="keyword">return</span> <span class="string">"\27["</span> .. (n > <span class="number">0</span> <span class="keyword">and</span> n <span class="keyword">or</span> -n) .. (n > <span class="number">0</span> <span class="keyword">and</span> <span class="string">"C"</span> <span class="keyword">or</span> <span class="string">"D"</span>) | ||
120 | <span class="keyword">end</span> | ||
121 | |||
122 | |||
123 | <span class="comment">-- -- generate string to move cursor vertically | ||
124 | </span><span class="comment">-- -- positive goes down, negative goes up | ||
125 | </span><span class="comment">-- local function cursor_move_vert(n) | ||
126 | </span><span class="comment">-- if n == 0 then | ||
127 | </span><span class="comment">-- return "" | ||
128 | </span><span class="comment">-- end | ||
129 | </span><span class="comment">-- return "\27[" .. (n > 0 and n or -n) .. (n > 0 and "B" or "A") | ||
130 | </span><span class="comment">-- end | ||
131 | </span> | ||
132 | |||
133 | <span class="comment">-- -- log to the line above the current line | ||
134 | </span><span class="comment">-- local function log(...) | ||
135 | </span><span class="comment">-- local arg = { n = select("#", ...), ...} | ||
136 | </span><span class="comment">-- for i = 1, arg.n do | ||
137 | </span><span class="comment">-- arg[i] = tostring(arg[i]) | ||
138 | </span><span class="comment">-- end | ||
139 | </span><span class="comment">-- arg = " " .. table.concat(arg, " ") .. " " | ||
140 | </span> | ||
141 | <span class="comment">-- io.write(cursor_move_vert(-1), arg, cursor_move_vert(1), cursor_move_horiz(-#arg)) | ||
142 | </span><span class="comment">-- end | ||
143 | </span> | ||
144 | |||
145 | <span class="comment">-- UTF8 character size in bytes | ||
146 | </span><span class="comment">-- @tparam number b the byte value of the first byte of a UTF8 character | ||
147 | </span><span class="keyword">local</span> <span class="keyword">function</span> <span class="function-name">utf8size</span>(b) | ||
148 | <span class="keyword">return</span> b < <span class="number">128</span> <span class="keyword">and</span> <span class="number">1</span> <span class="keyword">or</span> b < <span class="number">224</span> <span class="keyword">and</span> <span class="number">2</span> <span class="keyword">or</span> b < <span class="number">240</span> <span class="keyword">and</span> <span class="number">3</span> <span class="keyword">or</span> b < <span class="number">248</span> <span class="keyword">and</span> <span class="number">4</span> | ||
149 | <span class="keyword">end</span> | ||
150 | |||
151 | |||
152 | |||
153 | <span class="keyword">local</span> utf8parse <span class="keyword">do</span> | ||
154 | <span class="keyword">local</span> utf8_value_mt = { | ||
155 | __tostring = <span class="keyword">function</span>(self) | ||
156 | <span class="keyword">return</span> <span class="global">table</span>.<span class="function-name">concat</span>(self, <span class="string">""</span>) | ||
157 | <span class="keyword">end</span>, | ||
158 | } | ||
159 | |||
160 | <span class="comment">-- Parses a UTF8 string into list of individual characters. | ||
161 | </span> <span class="comment">-- key 'chars' gets the length in UTF8 characters, whilst # returns the length | ||
162 | </span> <span class="comment">-- for display (to handle double-width UTF8 chars). | ||
163 | </span> <span class="comment">-- in the list the double-width characters are followed by an empty string. | ||
164 | </span> <span class="comment">-- @tparam string s the UTF8 string to parse | ||
165 | </span> <span class="comment">-- @treturn table the list of characters | ||
166 | </span> <span class="keyword">function</span> <span class="function-name">utf8parse</span>(s) | ||
167 | <span class="keyword">local</span> t = <span class="global">setmetatable</span>({ chars = <span class="number">0</span> }, utf8_value_mt) | ||
168 | <span class="keyword">local</span> i = <span class="number">1</span> | ||
169 | <span class="keyword">while</span> i <= #s <span class="keyword">do</span> | ||
170 | <span class="keyword">local</span> b = s:<span class="function-name">byte</span>(i) | ||
171 | <span class="keyword">local</span> w = <span class="function-name">utf8size</span>(b) | ||
172 | <span class="keyword">local</span> char = s:<span class="function-name">sub</span>(i, i + w - <span class="number">1</span>) | ||
173 | t[#t + <span class="number">1</span>] = char | ||
174 | t.chars = t.chars + <span class="number">1</span> | ||
175 | <span class="keyword">if</span> sys.<span class="function-name">utf8cwidth</span>(char) == <span class="number">2</span> <span class="keyword">then</span> | ||
176 | <span class="comment">-- double width character, add empty string to keep the length of the | ||
177 | </span> <span class="comment">-- list the same as the character width on screen | ||
178 | </span> t[#t + <span class="number">1</span>] = <span class="string">""</span> | ||
179 | <span class="keyword">end</span> | ||
180 | i = i + w | ||
181 | <span class="keyword">end</span> | ||
182 | <span class="keyword">return</span> t | ||
183 | <span class="keyword">end</span> | ||
184 | <span class="keyword">end</span> | ||
185 | |||
186 | |||
187 | |||
188 | <span class="comment">-- inline tests for utf8parse | ||
189 | </span><span class="comment">-- do | ||
190 | </span><span class="comment">-- local t = utf8parse("aä½ b好c") | ||
191 | </span><span class="comment">-- assert(t[1] == "a") | ||
192 | </span><span class="comment">-- assert(t[2] == "ä½ ") -- double width | ||
193 | </span><span class="comment">-- assert(t[3] == "") | ||
194 | </span><span class="comment">-- assert(t[4] == "b") | ||
195 | </span><span class="comment">-- assert(t[5] == "好") -- double width | ||
196 | </span><span class="comment">-- assert(t[6] == "") | ||
197 | </span><span class="comment">-- assert(t[7] == "c") | ||
198 | </span><span class="comment">-- assert(#t == 7) -- size as displayed | ||
199 | </span><span class="comment">-- end | ||
200 | </span> | ||
201 | |||
202 | |||
203 | <span class="comment">-- readline class | ||
204 | </span> | ||
205 | <span class="keyword">local</span> readline = {} | ||
206 | readline.__index = readline | ||
207 | |||
208 | |||
209 | <span class="comment">--- Create a new readline object. | ||
210 | </span><span class="comment">-- @tparam table opts the options for the readline object | ||
211 | </span><span class="comment">-- @tparam[opt=""] string opts.prompt the prompt to display | ||
212 | </span><span class="comment">-- @tparam[opt=80] number opts.max_length the maximum length of the input (in characters, not bytes) | ||
213 | </span><span class="comment">-- @tparam[opt=""] string opts.value the default value | ||
214 | </span><span class="comment">-- @tparam[opt=<code>#value</code>] number opts.position of the cursor in the input | ||
215 | </span><span class="comment">-- @tparam[opt={"\10"/"\13"}] table opts.exit_keys an array of keys that will cause the readline to exit | ||
216 | </span><span class="comment">-- @treturn readline the new readline object | ||
217 | </span><span class="keyword">function</span> readline.<span class="function-name">new</span>(opts) | ||
218 | <span class="keyword">local</span> value = <span class="function-name">utf8parse</span>(opts.value <span class="keyword">or</span> <span class="string">""</span>) | ||
219 | <span class="keyword">local</span> prompt = <span class="function-name">utf8parse</span>(opts.prompt <span class="keyword">or</span> <span class="string">""</span>) | ||
220 | <span class="keyword">local</span> pos = <span class="global">math</span>.<span class="function-name">floor</span>(opts.position <span class="keyword">or</span> (#value + <span class="number">1</span>)) | ||
221 | pos = <span class="global">math</span>.<span class="function-name">max</span>(<span class="global">math</span>.<span class="function-name">min</span>(pos, (#value + <span class="number">1</span>)), <span class="number">1</span>) | ||
222 | <span class="keyword">local</span> len = <span class="global">math</span>.<span class="function-name">floor</span>(opts.max_length <span class="keyword">or</span> <span class="number">80</span>) | ||
223 | <span class="keyword">if</span> len < <span class="number">1</span> <span class="keyword">then</span> | ||
224 | <span class="global">error</span>(<span class="string">"max_length must be at least 1"</span>, <span class="number">2</span>) | ||
225 | <span class="keyword">end</span> | ||
226 | |||
227 | <span class="keyword">if</span> value.chars > len <span class="keyword">then</span> | ||
228 | <span class="global">error</span>(<span class="string">"value is longer than max_length"</span>, <span class="number">2</span>) | ||
229 | <span class="keyword">end</span> | ||
230 | |||
231 | <span class="keyword">local</span> exit_keys = {} | ||
232 | <span class="keyword">for</span> _, key <span class="keyword">in</span> <span class="global">ipairs</span>(opts.exit_keys <span class="keyword">or</span> {}) <span class="keyword">do</span> | ||
233 | exit_keys[key] = <span class="keyword">true</span> | ||
234 | <span class="keyword">end</span> | ||
235 | <span class="keyword">if</span> exit_keys[<span class="number">1</span>] == <span class="keyword">nil</span> <span class="keyword">then</span> | ||
236 | <span class="comment">-- nothing provided, default to Enter-key | ||
237 | </span> exit_keys[<span class="number">1</span>] = key_sequences.enter | ||
238 | <span class="keyword">end</span> | ||
239 | |||
240 | <span class="keyword">local</span> self = { | ||
241 | value = value, <span class="comment">-- the default value | ||
242 | </span> max_length = len, <span class="comment">-- the maximum length of the input | ||
243 | </span> prompt = prompt, <span class="comment">-- the prompt to display | ||
244 | </span> position = pos, <span class="comment">-- the current position in the input | ||
245 | </span> drawn_before = <span class="keyword">false</span>, <span class="comment">-- if the prompt has been drawn | ||
246 | </span> exit_keys = exit_keys, <span class="comment">-- the keys that will cause the readline to exit | ||
247 | </span> } | ||
248 | |||
249 | <span class="global">setmetatable</span>(self, readline) | ||
250 | <span class="keyword">return</span> self | ||
251 | <span class="keyword">end</span> | ||
252 | |||
253 | |||
254 | |||
255 | <span class="comment">-- draw the prompt and the input value, and position the cursor. | ||
256 | </span><span class="keyword">local</span> <span class="keyword">function</span> <span class="function-name">draw</span>(self, redraw) | ||
257 | <span class="keyword">if</span> redraw <span class="keyword">or</span> <span class="keyword">not</span> self.drawn_before <span class="keyword">then</span> | ||
258 | <span class="comment">-- we are at start of prompt | ||
259 | </span> self.drawn_before = <span class="keyword">true</span> | ||
260 | <span class="keyword">else</span> | ||
261 | <span class="comment">-- we are at current cursor position, move to start of prompt | ||
262 | </span> <span class="global">io</span>.<span class="function-name">write</span>(<span class="function-name">cursor_move_horiz</span>(-(#self.prompt + self.position))) | ||
263 | <span class="keyword">end</span> | ||
264 | <span class="comment">-- write prompt & value | ||
265 | </span> <span class="global">io</span>.<span class="function-name">write</span>(<span class="global">tostring</span>(self.prompt) .. <span class="global">tostring</span>(self.value)) | ||
266 | <span class="comment">-- clear remainder of input size | ||
267 | </span> <span class="global">io</span>.<span class="function-name">write</span>(<span class="global">string</span>.<span class="function-name">rep</span>(<span class="string">" "</span>, self.max_length - self.value.chars)) | ||
268 | <span class="global">io</span>.<span class="function-name">write</span>(<span class="function-name">cursor_move_horiz</span>(-(self.max_length - self.value.chars))) | ||
269 | <span class="comment">-- move to cursor position | ||
270 | </span> <span class="global">io</span>.<span class="function-name">write</span>(<span class="function-name">cursor_move_horiz</span>(-(#self.value + <span class="number">1</span> - self.position))) | ||
271 | <span class="global">io</span>.<span class="function-name">flush</span>() | ||
272 | <span class="keyword">end</span> | ||
273 | |||
274 | |||
275 | <span class="keyword">local</span> handle_key <span class="keyword">do</span> <span class="comment">-- keyboard input handler | ||
276 | </span> | ||
277 | <span class="keyword">local</span> key_handlers | ||
278 | key_handlers = { | ||
279 | left = <span class="keyword">function</span>(self) | ||
280 | <span class="keyword">if</span> self.position == <span class="number">1</span> <span class="keyword">then</span> | ||
281 | <span class="function-name">bell</span>() | ||
282 | <span class="keyword">return</span> | ||
283 | <span class="keyword">end</span> | ||
284 | |||
285 | <span class="keyword">local</span> new_pos = self.position - <span class="number">1</span> | ||
286 | <span class="keyword">while</span> self.value[new_pos] == <span class="string">""</span> <span class="keyword">do</span> <span class="comment">-- skip empty strings; double width chars | ||
287 | </span> new_pos = new_pos - <span class="number">1</span> | ||
288 | <span class="keyword">end</span> | ||
289 | |||
290 | <span class="global">io</span>.<span class="function-name">write</span>(<span class="function-name">cursor_move_horiz</span>(-(self.position - new_pos))) | ||
291 | <span class="global">io</span>.<span class="function-name">flush</span>() | ||
292 | self.position = new_pos | ||
293 | <span class="keyword">end</span>, | ||
294 | |||
295 | right = <span class="keyword">function</span>(self) | ||
296 | <span class="keyword">if</span> self.position == #self.value + <span class="number">1</span> <span class="keyword">then</span> | ||
297 | <span class="function-name">bell</span>() | ||
298 | <span class="keyword">return</span> | ||
299 | <span class="keyword">end</span> | ||
300 | |||
301 | <span class="keyword">local</span> new_pos = self.position + <span class="number">1</span> | ||
302 | <span class="keyword">while</span> self.value[new_pos] == <span class="string">""</span> <span class="keyword">do</span> <span class="comment">-- skip empty strings; double width chars | ||
303 | </span> new_pos = new_pos + <span class="number">1</span> | ||
304 | <span class="keyword">end</span> | ||
305 | |||
306 | <span class="global">io</span>.<span class="function-name">write</span>(<span class="function-name">cursor_move_horiz</span>(new_pos - self.position)) | ||
307 | <span class="global">io</span>.<span class="function-name">flush</span>() | ||
308 | self.position = new_pos | ||
309 | <span class="keyword">end</span>, | ||
310 | |||
311 | backspace = <span class="keyword">function</span>(self) | ||
312 | <span class="keyword">if</span> self.position == <span class="number">1</span> <span class="keyword">then</span> | ||
313 | <span class="function-name">bell</span>() | ||
314 | <span class="keyword">return</span> | ||
315 | <span class="keyword">end</span> | ||
316 | |||
317 | <span class="keyword">while</span> self.value[self.position - <span class="number">1</span>] == <span class="string">""</span> <span class="keyword">do</span> <span class="comment">-- remove empty strings; double width chars | ||
318 | </span> <span class="global">io</span>.<span class="function-name">write</span>(<span class="function-name">cursor_move_horiz</span>(-<span class="number">1</span>)) | ||
319 | self.position = self.position - <span class="number">1</span> | ||
320 | <span class="global">table</span>.<span class="function-name">remove</span>(self.value, self.position) | ||
321 | <span class="keyword">end</span> | ||
322 | <span class="comment">-- remove char itself | ||
323 | </span> <span class="global">io</span>.<span class="function-name">write</span>(<span class="function-name">cursor_move_horiz</span>(-<span class="number">1</span>)) | ||
324 | self.position = self.position - <span class="number">1</span> | ||
325 | <span class="global">table</span>.<span class="function-name">remove</span>(self.value, self.position) | ||
326 | self.value.chars = self.value.chars - <span class="number">1</span> | ||
327 | <span class="function-name">draw</span>(self) | ||
328 | <span class="keyword">end</span>, | ||
329 | |||
330 | home = <span class="keyword">function</span>(self) | ||
331 | <span class="keyword">local</span> new_pos = <span class="number">1</span> | ||
332 | <span class="global">io</span>.<span class="function-name">write</span>(<span class="function-name">cursor_move_horiz</span>(new_pos - self.position)) | ||
333 | self.position = new_pos | ||
334 | <span class="keyword">end</span>, | ||
335 | |||
336 | [<span class="string">"end"</span>] = <span class="keyword">function</span>(self) | ||
337 | <span class="keyword">local</span> new_pos = #self.value + <span class="number">1</span> | ||
338 | <span class="global">io</span>.<span class="function-name">write</span>(<span class="function-name">cursor_move_horiz</span>(new_pos - self.position)) | ||
339 | self.position = new_pos | ||
340 | <span class="keyword">end</span>, | ||
341 | |||
342 | delete = <span class="keyword">function</span>(self) | ||
343 | <span class="keyword">if</span> self.position > #self.value <span class="keyword">then</span> | ||
344 | <span class="function-name">bell</span>() | ||
345 | <span class="keyword">return</span> | ||
346 | <span class="keyword">end</span> | ||
347 | |||
348 | key_handlers.<span class="function-name">right</span>(self) | ||
349 | key_handlers.<span class="function-name">backspace</span>(self) | ||
350 | <span class="keyword">end</span>, | ||
351 | } | ||
352 | |||
353 | |||
354 | <span class="comment">-- handles a single input key/ansi-sequence. | ||
355 | </span> <span class="comment">-- @tparam string key the key or ansi-sequence (from <a href="../modules/system.html#readansi">system.readansi</a>) | ||
356 | </span> <span class="comment">-- @tparam string keytype the type of the key, either "char" or "ansi" (from <a href="../modules/system.html#readansi">system.readansi</a>) | ||
357 | </span> <span class="comment">-- @treturn string status the status of the key handling, either "ok", "exit_key" or an error message | ||
358 | </span> <span class="keyword">function</span> <span class="function-name">handle_key</span>(self, key, keytype) | ||
359 | <span class="keyword">if</span> self.exit_keys[key] <span class="keyword">then</span> | ||
360 | <span class="comment">-- registered exit key | ||
361 | </span> <span class="keyword">return</span> <span class="string">"exit_key"</span> | ||
362 | <span class="keyword">end</span> | ||
363 | |||
364 | <span class="keyword">local</span> handler = key_handlers[key_names[key] <span class="keyword">or</span> <span class="keyword">true</span> ] | ||
365 | <span class="keyword">if</span> handler <span class="keyword">then</span> | ||
366 | <span class="function-name">handler</span>(self) | ||
367 | <span class="keyword">return</span> <span class="string">"ok"</span> | ||
368 | <span class="keyword">end</span> | ||
369 | |||
370 | <span class="keyword">if</span> keytype == <span class="string">"ansi"</span> <span class="keyword">then</span> | ||
371 | <span class="comment">-- we got an ansi sequence, but dunno how to handle it, ignore | ||
372 | </span> <span class="comment">-- print("unhandled ansi: ", key:sub(2,-1), string.byte(key, 1, -1)) | ||
373 | </span> <span class="function-name">bell</span>() | ||
374 | <span class="keyword">return</span> <span class="string">"ok"</span> | ||
375 | <span class="keyword">end</span> | ||
376 | |||
377 | <span class="comment">-- just a single key | ||
378 | </span> <span class="keyword">if</span> key < <span class="string">" "</span> <span class="keyword">then</span> | ||
379 | <span class="comment">-- control character | ||
380 | </span> <span class="function-name">bell</span>() | ||
381 | <span class="keyword">return</span> <span class="string">"ok"</span> | ||
382 | <span class="keyword">end</span> | ||
383 | |||
384 | <span class="keyword">if</span> self.value.chars >= self.max_length <span class="keyword">then</span> | ||
385 | <span class="function-name">bell</span>() | ||
386 | <span class="keyword">return</span> <span class="string">"ok"</span> | ||
387 | <span class="keyword">end</span> | ||
388 | |||
389 | <span class="comment">-- insert the key into the value | ||
390 | </span> <span class="keyword">if</span> sys.<span class="function-name">utf8cwidth</span>(key) == <span class="number">2</span> <span class="keyword">then</span> | ||
391 | <span class="comment">-- double width character, insert empty string after it | ||
392 | </span> <span class="global">table</span>.<span class="function-name">insert</span>(self.value, self.position, <span class="string">""</span>) | ||
393 | <span class="global">table</span>.<span class="function-name">insert</span>(self.value, self.position, key) | ||
394 | self.position = self.position + <span class="number">2</span> | ||
395 | <span class="global">io</span>.<span class="function-name">write</span>(<span class="function-name">cursor_move_horiz</span>(<span class="number">2</span>)) | ||
396 | <span class="keyword">else</span> | ||
397 | <span class="global">table</span>.<span class="function-name">insert</span>(self.value, self.position, key) | ||
398 | self.position = self.position + <span class="number">1</span> | ||
399 | <span class="global">io</span>.<span class="function-name">write</span>(<span class="function-name">cursor_move_horiz</span>(<span class="number">1</span>)) | ||
400 | <span class="keyword">end</span> | ||
401 | self.value.chars = self.value.chars + <span class="number">1</span> | ||
402 | <span class="function-name">draw</span>(self) | ||
403 | <span class="keyword">return</span> <span class="string">"ok"</span> | ||
404 | <span class="keyword">end</span> | ||
405 | <span class="keyword">end</span> | ||
406 | |||
407 | |||
408 | |||
409 | <span class="comment">--- Get_size returns the maximum size of the input box (prompt + input). | ||
410 | </span><span class="comment">-- The size is in rows and columns. Columns is determined by | ||
411 | </span><span class="comment">-- the prompt and the <code>max_length * 2</code> (characters can be double-width). | ||
412 | </span><span class="comment">-- @treturn number the number of rows (always 1) | ||
413 | </span><span class="comment">-- @treturn number the number of columns | ||
414 | </span><span class="keyword">function</span> readline:<span class="function-name">get_size</span>() | ||
415 | <span class="keyword">return</span> <span class="number">1</span>, #self.prompt + self.max_length * <span class="number">2</span> | ||
416 | <span class="keyword">end</span> | ||
417 | |||
418 | |||
419 | |||
420 | <span class="comment">--- Get coordinates of the cursor in the input box (prompt + input). | ||
421 | </span><span class="comment">-- The coordinates are 1-based. They are returned as row and column, within the | ||
422 | </span><span class="comment">-- size as reported by <code>get_size</code>. | ||
423 | </span><span class="comment">-- @treturn number the row of the cursor (always 1) | ||
424 | </span><span class="comment">-- @treturn number the column of the cursor | ||
425 | </span><span class="keyword">function</span> readline:<span class="function-name">get_cursor</span>() | ||
426 | <span class="keyword">return</span> <span class="number">1</span>, #self.prompt + self.position | ||
427 | <span class="keyword">end</span> | ||
428 | |||
429 | |||
430 | |||
431 | <span class="comment">--- Set the coordinates of the cursor in the input box (prompt + input). | ||
432 | </span><span class="comment">-- The coordinates are 1-based. They are expected to be within the | ||
433 | </span><span class="comment">-- size as reported by <code>get_size</code>, and beyond the prompt. | ||
434 | </span><span class="comment">-- If the position is invalid, it will be corrected. | ||
435 | </span><span class="comment">-- Use the results to check if the position was adjusted. | ||
436 | </span><span class="comment">-- @tparam number row the row of the cursor (always 1) | ||
437 | </span><span class="comment">-- @tparam number col the column of the cursor | ||
438 | </span><span class="comment">-- @return results of get_cursor | ||
439 | </span><span class="keyword">function</span> readline:<span class="function-name">set_cursor</span>(row, col) | ||
440 | <span class="keyword">local</span> l_prompt = #self.prompt | ||
441 | <span class="keyword">local</span> l_value = #self.value | ||
442 | |||
443 | <span class="keyword">if</span> col < l_prompt + <span class="number">1</span> <span class="keyword">then</span> | ||
444 | col = l_prompt + <span class="number">1</span> | ||
445 | <span class="keyword">elseif</span> col > l_prompt + l_value + <span class="number">1</span> <span class="keyword">then</span> | ||
446 | col = l_prompt + l_value + <span class="number">1</span> | ||
447 | <span class="keyword">end</span> | ||
448 | |||
449 | <span class="keyword">while</span> self.value[col - l_prompt] == <span class="string">""</span> <span class="keyword">do</span> | ||
450 | col = col - <span class="number">1</span> <span class="comment">-- on an empty string, so move back to start of double-width char | ||
451 | </span> <span class="keyword">end</span> | ||
452 | |||
453 | <span class="keyword">local</span> new_pos = col - l_prompt | ||
454 | |||
455 | <span class="function-name">cursor_move_horiz</span>(self.position - new_pos) | ||
456 | <span class="global">io</span>.<span class="function-name">flush</span>() | ||
457 | |||
458 | self.position = new_pos | ||
459 | <span class="keyword">return</span> self:<span class="function-name">get_cursor</span>() | ||
460 | <span class="keyword">end</span> | ||
461 | |||
462 | |||
463 | |||
464 | <span class="comment">--- Read a line of input from the user. | ||
465 | </span><span class="comment">-- It will first print the <code>prompt</code> and then wait for input. Ensure the cursor | ||
466 | </span><span class="comment">-- is at the correct position before calling this function. This function will | ||
467 | </span><span class="comment">-- do all cursor movements in a relative way. | ||
468 | </span><span class="comment">-- Can be called again after an exit-key or timeout has occurred. Just make sure | ||
469 | </span><span class="comment">-- the cursor is at the same position where is was when it returned the last time. | ||
470 | </span><span class="comment">-- Alternatively the cursor can be set to the position of the prompt (the position | ||
471 | </span><span class="comment">-- the cursor was in before the first call), and the parameter <code>redraw</code> can be set | ||
472 | </span><span class="comment">-- to <code>true</code>. | ||
473 | </span><span class="comment">-- @tparam[opt=math.huge] number timeout the maximum time to wait for input in seconds | ||
474 | </span><span class="comment">-- @tparam[opt=false] boolean redraw if <code>true</code> the prompt will be redrawn (cursor must be at prompt position!) | ||
475 | </span><span class="comment">-- @treturn[1] string the input string as entered the user | ||
476 | </span><span class="comment">-- @treturn[1] string the exit-key used to exit the readline (see <code>new</code>) | ||
477 | </span><span class="comment">-- @treturn[2] nil when input is incomplete | ||
478 | </span><span class="comment">-- @treturn[2] string error message, the reason why the input is incomplete, <code>"timeout"</code>, or an error reading a key | ||
479 | </span><span class="keyword">function</span> readline:<span class="function-name">__call</span>(timeout, redraw) | ||
480 | <span class="function-name">draw</span>(self, redraw) | ||
481 | timeout = timeout <span class="keyword">or</span> <span class="global">math</span>.huge | ||
482 | <span class="keyword">local</span> timeout_end = sys.<span class="function-name">gettime</span>() + timeout | ||
483 | |||
484 | <span class="keyword">while</span> <span class="keyword">true</span> <span class="keyword">do</span> | ||
485 | <span class="keyword">local</span> key, keytype = sys.<span class="function-name">readansi</span>(timeout_end - sys.<span class="function-name">gettime</span>()) | ||
486 | <span class="keyword">if</span> <span class="keyword">not</span> key <span class="keyword">then</span> | ||
487 | <span class="comment">-- error or timeout | ||
488 | </span> <span class="keyword">return</span> <span class="keyword">nil</span>, keytype | ||
489 | <span class="keyword">end</span> | ||
490 | |||
491 | <span class="keyword">local</span> status = <span class="function-name">handle_key</span>(self, key, keytype) | ||
492 | <span class="keyword">if</span> status == <span class="string">"exit_key"</span> <span class="keyword">then</span> | ||
493 | <span class="keyword">return</span> <span class="global">tostring</span>(self.value), key | ||
494 | |||
495 | <span class="keyword">elseif</span> status ~= <span class="string">"ok"</span> <span class="keyword">then</span> | ||
496 | <span class="global">error</span>(<span class="string">"unknown status received: "</span> .. <span class="global">tostring</span>(status)) | ||
497 | <span class="keyword">end</span> | ||
498 | <span class="keyword">end</span> | ||
499 | <span class="keyword">end</span> | ||
500 | |||
501 | |||
502 | |||
503 | <span class="comment">-- return readline -- normally we'd return here, but for the example we continue | ||
504 | </span> | ||
505 | |||
506 | |||
507 | |||
508 | <span class="keyword">local</span> backup = sys.<span class="function-name">termbackup</span>() | ||
509 | |||
510 | <span class="comment">-- setup Windows console to handle ANSI processing | ||
511 | </span>sys.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdout, sys.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout) + sys.COF_VIRTUAL_TERMINAL_PROCESSING) | ||
512 | sys.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdin, sys.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdin) + sys.CIF_VIRTUAL_TERMINAL_INPUT) | ||
513 | <span class="comment">-- set output to UTF-8 | ||
514 | </span>sys.<span class="function-name">setconsoleoutputcp</span>(sys.CODEPAGE_UTF8) | ||
515 | |||
516 | <span class="comment">-- setup Posix terminal to disable canonical mode and echo | ||
517 | </span>sys.<span class="function-name">tcsetattr</span>(<span class="global">io</span>.stdin, sys.TCSANOW, { | ||
518 | lflag = sys.<span class="function-name">tcgetattr</span>(<span class="global">io</span>.stdin).lflag - sys.L_ICANON - sys.L_ECHO, | ||
519 | }) | ||
520 | <span class="comment">-- setup stdin to non-blocking mode | ||
521 | </span>sys.<span class="function-name">setnonblock</span>(<span class="global">io</span>.stdin, <span class="keyword">true</span>) | ||
522 | |||
523 | |||
524 | <span class="keyword">local</span> rl = readline.<span class="function-name">new</span>{ | ||
525 | prompt = <span class="string">"Enter something: "</span>, | ||
526 | max_length = <span class="number">60</span>, | ||
527 | value = <span class="string">"Hello, ä½ -好 World 🚀!"</span>, | ||
528 | <span class="comment">-- position = 2, | ||
529 | </span> exit_keys = {key_sequences.enter, <span class="string">"\27"</span>, <span class="string">"\t"</span>, <span class="string">"\27[Z"</span>}, <span class="comment">-- enter, escape, tab, shift-tab | ||
530 | </span>} | ||
531 | |||
532 | |||
533 | <span class="keyword">local</span> result, key = <span class="function-name">rl</span>() | ||
534 | <span class="global">print</span>(<span class="string">""</span>) <span class="comment">-- newline after input, to move cursor down from the input line | ||
535 | </span><span class="global">print</span>(<span class="string">"Result (string): '"</span> .. result .. <span class="string">"'"</span>) | ||
536 | <span class="global">print</span>(<span class="string">"Result (bytes):"</span>, result:<span class="function-name">byte</span>(<span class="number">1</span>,-<span class="number">1</span>)) | ||
537 | <span class="global">print</span>(<span class="string">"Exit-Key (bytes):"</span>, key:<span class="function-name">byte</span>(<span class="number">1</span>,-<span class="number">1</span>)) | ||
538 | |||
539 | |||
540 | <span class="comment">-- Clean up afterwards | ||
541 | </span>sys.<span class="function-name">termrestore</span>(backup)</pre> | ||
542 | |||
543 | |||
544 | </div> <!-- id="content" --> | ||
545 | </div> <!-- id="main" --> | ||
546 | <div id="about"> | ||
547 | <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i> | ||
548 | <i style="float:right;">Last updated 2024-06-20 23:11:37 </i> | ||
549 | </div> <!-- id="about" --> | ||
550 | </div> <!-- id="container" --> | ||
551 | </body> | ||
552 | </html> | ||
diff --git a/docs/examples/spinner.lua.html b/docs/examples/spinner.lua.html new file mode 100644 index 0000000..181cbe5 --- /dev/null +++ b/docs/examples/spinner.lua.html | |||
@@ -0,0 +1,144 @@ | |||
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" | ||
2 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> | ||
3 | <html> | ||
4 | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> | ||
5 | <head> | ||
6 | <title>Lua-System docs</title> | ||
7 | <link rel="stylesheet" href="../ldoc.css" type="text/css" /> | ||
8 | </head> | ||
9 | <body> | ||
10 | |||
11 | <div id="container"> | ||
12 | |||
13 | <div id="product"> | ||
14 | <div id="product_logo"></div> | ||
15 | <div id="product_name"><big><b></b></big></div> | ||
16 | <div id="product_description"></div> | ||
17 | </div> <!-- id="product" --> | ||
18 | |||
19 | |||
20 | <div id="main"> | ||
21 | |||
22 | |||
23 | <!-- Menu --> | ||
24 | |||
25 | <div id="navigation"> | ||
26 | <br/> | ||
27 | <h1>Lua-System</h1> | ||
28 | |||
29 | |||
30 | <ul> | ||
31 | <li><a href="../index.html">Index</a></li> | ||
32 | </ul> | ||
33 | |||
34 | |||
35 | |||
36 | <h2>Examples</h2> | ||
37 | <ul class="nowrap"> | ||
38 | <li><a href="../examples/compat.lua.html">compat.lua</a></li> | ||
39 | <li><a href="../examples/flag_debugging.lua.html">flag_debugging.lua</a></li> | ||
40 | <li><a href="../examples/password_input.lua.html">password_input.lua</a></li> | ||
41 | <li><a href="../examples/read.lua.html">read.lua</a></li> | ||
42 | <li><a href="../examples/readline.lua.html">readline.lua</a></li> | ||
43 | <li><strong>spinner.lua</strong></li> | ||
44 | <li><a href="../examples/spiral_snake.lua.html">spiral_snake.lua</a></li> | ||
45 | <li><a href="../examples/terminalsize.lua.html">terminalsize.lua</a></li> | ||
46 | </ul> | ||
47 | <h2>Modules</h2> | ||
48 | <ul class="nowrap"> | ||
49 | <li><a href="../modules/system.html">system</a></li> | ||
50 | </ul> | ||
51 | <h2>Classes</h2> | ||
52 | <ul class="nowrap"> | ||
53 | <li><a href="../classes/bitflags.html">bitflags</a></li> | ||
54 | </ul> | ||
55 | <h2>Topics</h2> | ||
56 | <ul class=""> | ||
57 | <li><a href="../topics/01-introduction.md.html">1. Introduction</a></li> | ||
58 | <li><a href="../topics/02-development.md.html">2. Development</a></li> | ||
59 | <li><a href="../topics/03-terminal.md.html">3. Terminal functionality</a></li> | ||
60 | <li><a href="../topics/CHANGELOG.md.html">CHANGELOG</a></li> | ||
61 | <li><a href="../topics/LICENSE.md.html">MIT License</a></li> | ||
62 | </ul> | ||
63 | |||
64 | </div> | ||
65 | |||
66 | <div id="content"> | ||
67 | |||
68 | <h2>spinner.lua</h2> | ||
69 | <pre> | ||
70 | <span class="keyword">local</span> sys = <span class="global">require</span>(<span class="string">"system"</span>) | ||
71 | |||
72 | <span class="global">print</span> <span class="string">[[ | ||
73 | |||
74 | An example to display a spinner, whilst a long running task executes. | ||
75 | |||
76 | ]]</span> | ||
77 | |||
78 | |||
79 | <span class="comment">-- start make backup, to auto-restore on exit | ||
80 | </span>sys.<span class="function-name">autotermrestore</span>() | ||
81 | <span class="comment">-- configure console | ||
82 | </span>sys.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdin, sys.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdin) - sys.CIF_ECHO_INPUT - sys.CIF_LINE_INPUT) | ||
83 | <span class="keyword">local</span> of = sys.<span class="function-name">tcgetattr</span>(<span class="global">io</span>.stdin) | ||
84 | sys.<span class="function-name">tcsetattr</span>(<span class="global">io</span>.stdin, sys.TCSANOW, { lflag = of.lflag - sys.L_ICANON - sys.L_ECHO }) | ||
85 | sys.<span class="function-name">setnonblock</span>(<span class="global">io</span>.stdin, <span class="keyword">true</span>) | ||
86 | |||
87 | |||
88 | |||
89 | <span class="keyword">local</span> <span class="keyword">function</span> <span class="function-name">hideCursor</span>() | ||
90 | <span class="global">io</span>.<span class="function-name">write</span>(<span class="string">"\27[?25l"</span>) | ||
91 | <span class="global">io</span>.<span class="function-name">flush</span>() | ||
92 | <span class="keyword">end</span> | ||
93 | |||
94 | <span class="keyword">local</span> <span class="keyword">function</span> <span class="function-name">showCursor</span>() | ||
95 | <span class="global">io</span>.<span class="function-name">write</span>(<span class="string">"\27[?25h"</span>) | ||
96 | <span class="global">io</span>.<span class="function-name">flush</span>() | ||
97 | <span class="keyword">end</span> | ||
98 | |||
99 | <span class="keyword">local</span> <span class="keyword">function</span> <span class="function-name">left</span>(n) | ||
100 | <span class="global">io</span>.<span class="function-name">write</span>(<span class="string">"\27["</span>,n <span class="keyword">or</span> <span class="number">1</span>,<span class="string">"D"</span>) | ||
101 | <span class="global">io</span>.<span class="function-name">flush</span>() | ||
102 | <span class="keyword">end</span> | ||
103 | |||
104 | |||
105 | |||
106 | <span class="keyword">local</span> spinner <span class="keyword">do</span> | ||
107 | <span class="keyword">local</span> spin = <span class="string">[[|/-\]]</span> | ||
108 | <span class="keyword">local</span> i = <span class="number">1</span> | ||
109 | spinner = <span class="keyword">function</span>() | ||
110 | <span class="function-name">hideCursor</span>() | ||
111 | <span class="global">io</span>.<span class="function-name">write</span>(spin:<span class="function-name">sub</span>(i, i)) | ||
112 | <span class="function-name">left</span>() | ||
113 | i = i + <span class="number">1</span> | ||
114 | <span class="keyword">if</span> i > #spin <span class="keyword">then</span> i = <span class="number">1</span> <span class="keyword">end</span> | ||
115 | |||
116 | <span class="keyword">if</span> sys.<span class="function-name">readkey</span>(<span class="number">0</span>) ~= <span class="keyword">nil</span> <span class="keyword">then</span> | ||
117 | <span class="keyword">while</span> sys.<span class="function-name">readkey</span>(<span class="number">0</span>) ~= <span class="keyword">nil</span> <span class="keyword">do</span> <span class="keyword">end</span> <span class="comment">-- consume keys pressed | ||
118 | </span> <span class="global">io</span>.<span class="function-name">write</span>(<span class="string">" "</span>); | ||
119 | <span class="function-name">left</span>() | ||
120 | <span class="function-name">showCursor</span>() | ||
121 | <span class="keyword">return</span> <span class="keyword">true</span> | ||
122 | <span class="keyword">else</span> | ||
123 | <span class="keyword">return</span> <span class="keyword">false</span> | ||
124 | <span class="keyword">end</span> | ||
125 | <span class="keyword">end</span> | ||
126 | <span class="keyword">end</span> | ||
127 | |||
128 | <span class="global">io</span>.stdout:<span class="function-name">write</span>(<span class="string">"press any key to stop the spinner... "</span>) | ||
129 | <span class="keyword">while</span> <span class="keyword">not</span> <span class="function-name">spinner</span>() <span class="keyword">do</span> | ||
130 | sys.<span class="function-name">sleep</span>(<span class="number">0.1</span>) | ||
131 | <span class="keyword">end</span> | ||
132 | |||
133 | <span class="global">print</span>(<span class="string">"Done!"</span>)</pre> | ||
134 | |||
135 | |||
136 | </div> <!-- id="content" --> | ||
137 | </div> <!-- id="main" --> | ||
138 | <div id="about"> | ||
139 | <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i> | ||
140 | <i style="float:right;">Last updated 2024-06-20 23:11:37 </i> | ||
141 | </div> <!-- id="about" --> | ||
142 | </div> <!-- id="container" --> | ||
143 | </body> | ||
144 | </html> | ||
diff --git a/docs/examples/spiral_snake.lua.html b/docs/examples/spiral_snake.lua.html new file mode 100644 index 0000000..7ebb838 --- /dev/null +++ b/docs/examples/spiral_snake.lua.html | |||
@@ -0,0 +1,152 @@ | |||
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" | ||
2 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> | ||
3 | <html> | ||
4 | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> | ||
5 | <head> | ||
6 | <title>Lua-System docs</title> | ||
7 | <link rel="stylesheet" href="../ldoc.css" type="text/css" /> | ||
8 | </head> | ||
9 | <body> | ||
10 | |||
11 | <div id="container"> | ||
12 | |||
13 | <div id="product"> | ||
14 | <div id="product_logo"></div> | ||
15 | <div id="product_name"><big><b></b></big></div> | ||
16 | <div id="product_description"></div> | ||
17 | </div> <!-- id="product" --> | ||
18 | |||
19 | |||
20 | <div id="main"> | ||
21 | |||
22 | |||
23 | <!-- Menu --> | ||
24 | |||
25 | <div id="navigation"> | ||
26 | <br/> | ||
27 | <h1>Lua-System</h1> | ||
28 | |||
29 | |||
30 | <ul> | ||
31 | <li><a href="../index.html">Index</a></li> | ||
32 | </ul> | ||
33 | |||
34 | |||
35 | |||
36 | <h2>Examples</h2> | ||
37 | <ul class="nowrap"> | ||
38 | <li><a href="../examples/compat.lua.html">compat.lua</a></li> | ||
39 | <li><a href="../examples/flag_debugging.lua.html">flag_debugging.lua</a></li> | ||
40 | <li><a href="../examples/password_input.lua.html">password_input.lua</a></li> | ||
41 | <li><a href="../examples/read.lua.html">read.lua</a></li> | ||
42 | <li><a href="../examples/readline.lua.html">readline.lua</a></li> | ||
43 | <li><a href="../examples/spinner.lua.html">spinner.lua</a></li> | ||
44 | <li><strong>spiral_snake.lua</strong></li> | ||
45 | <li><a href="../examples/terminalsize.lua.html">terminalsize.lua</a></li> | ||
46 | </ul> | ||
47 | <h2>Modules</h2> | ||
48 | <ul class="nowrap"> | ||
49 | <li><a href="../modules/system.html">system</a></li> | ||
50 | </ul> | ||
51 | <h2>Classes</h2> | ||
52 | <ul class="nowrap"> | ||
53 | <li><a href="../classes/bitflags.html">bitflags</a></li> | ||
54 | </ul> | ||
55 | <h2>Topics</h2> | ||
56 | <ul class=""> | ||
57 | <li><a href="../topics/01-introduction.md.html">1. Introduction</a></li> | ||
58 | <li><a href="../topics/02-development.md.html">2. Development</a></li> | ||
59 | <li><a href="../topics/03-terminal.md.html">3. Terminal functionality</a></li> | ||
60 | <li><a href="../topics/CHANGELOG.md.html">CHANGELOG</a></li> | ||
61 | <li><a href="../topics/LICENSE.md.html">MIT License</a></li> | ||
62 | </ul> | ||
63 | |||
64 | </div> | ||
65 | |||
66 | <div id="content"> | ||
67 | |||
68 | <h2>spiral_snake.lua</h2> | ||
69 | <pre> | ||
70 | <span class="keyword">local</span> sys = <span class="global">require</span> <span class="string">"system"</span> | ||
71 | |||
72 | <span class="global">print</span> <span class="string">[[ | ||
73 | |||
74 | This example will draw a snake like spiral on the screen. Showing ANSI escape | ||
75 | codes for moving the cursor around. | ||
76 | |||
77 | ]]</span> | ||
78 | |||
79 | <span class="comment">-- backup term settings with auto-restore on exit | ||
80 | </span>sys.<span class="function-name">autotermrestore</span>() | ||
81 | |||
82 | <span class="comment">-- setup Windows console to handle ANSI processing | ||
83 | </span>sys.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdout, sys.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout) + sys.COF_VIRTUAL_TERMINAL_PROCESSING) | ||
84 | |||
85 | <span class="comment">-- start drawing the spiral. | ||
86 | </span><span class="comment">-- start from current pos, then right, then up, then left, then down, and again. | ||
87 | </span><span class="keyword">local</span> x, y = <span class="number">1</span>, <span class="number">1</span> <span class="comment">-- current position | ||
88 | </span><span class="keyword">local</span> dx, dy = <span class="number">1</span>, <span class="number">0</span> <span class="comment">-- direction after each step | ||
89 | </span><span class="keyword">local</span> wx, wy = <span class="number">30</span>, <span class="number">30</span> <span class="comment">-- width and height of the room | ||
90 | </span><span class="keyword">local</span> mx, my = <span class="number">1</span>, <span class="number">1</span> <span class="comment">-- margin | ||
91 | </span> | ||
92 | <span class="comment">-- commands to move the cursor | ||
93 | </span><span class="keyword">local</span> move_left = <span class="string">"\27[1D"</span> | ||
94 | <span class="keyword">local</span> move_right = <span class="string">"\27[1C"</span> | ||
95 | <span class="keyword">local</span> move_up = <span class="string">"\27[1A"</span> | ||
96 | <span class="keyword">local</span> move_down = <span class="string">"\27[1B"</span> | ||
97 | |||
98 | <span class="comment">-- create room: 30 empty lines | ||
99 | </span><span class="global">print</span>((<span class="string">"\n"</span>):<span class="function-name">rep</span>(wy)) | ||
100 | <span class="keyword">local</span> move = move_right | ||
101 | |||
102 | <span class="keyword">while</span> wx > <span class="number">0</span> <span class="keyword">and</span> wy > <span class="number">0</span> <span class="keyword">do</span> | ||
103 | sys.<span class="function-name">sleep</span>(<span class="number">0.01</span>) <span class="comment">-- slow down the drawing a little | ||
104 | </span> <span class="global">io</span>.<span class="function-name">write</span>(<span class="string">"*"</span> .. move_left .. move ) | ||
105 | <span class="global">io</span>.<span class="function-name">flush</span>() | ||
106 | x = x + dx | ||
107 | y = y + dy | ||
108 | |||
109 | <span class="keyword">if</span> x > wx <span class="keyword">and</span> move == move_right <span class="keyword">then</span> | ||
110 | <span class="comment">-- end of move right | ||
111 | </span> dx = <span class="number">0</span> | ||
112 | dy = <span class="number">1</span> | ||
113 | move = move_up | ||
114 | wy = wy - <span class="number">1</span> | ||
115 | my = my + <span class="number">1</span> | ||
116 | <span class="keyword">elseif</span> y > wy <span class="keyword">and</span> move == move_up <span class="keyword">then</span> | ||
117 | <span class="comment">-- end of move up | ||
118 | </span> dx = -<span class="number">1</span> | ||
119 | dy = <span class="number">0</span> | ||
120 | move = move_left | ||
121 | wx = wx - <span class="number">1</span> | ||
122 | mx = mx + <span class="number">1</span> | ||
123 | <span class="keyword">elseif</span> x < mx <span class="keyword">and</span> move == move_left <span class="keyword">then</span> | ||
124 | <span class="comment">-- end of move left | ||
125 | </span> dx = <span class="number">0</span> | ||
126 | dy = -<span class="number">1</span> | ||
127 | move = move_down | ||
128 | wy = wy - <span class="number">1</span> | ||
129 | my = my + <span class="number">1</span> | ||
130 | <span class="keyword">elseif</span> y < my <span class="keyword">and</span> move == move_down <span class="keyword">then</span> | ||
131 | <span class="comment">-- end of move down | ||
132 | </span> dx = <span class="number">1</span> | ||
133 | dy = <span class="number">0</span> | ||
134 | move = move_right | ||
135 | wx = wx - <span class="number">1</span> | ||
136 | mx = mx + <span class="number">1</span> | ||
137 | <span class="keyword">end</span> | ||
138 | <span class="keyword">end</span> | ||
139 | |||
140 | <span class="global">io</span>.<span class="function-name">write</span>(move_down:<span class="function-name">rep</span>(<span class="number">15</span>)) | ||
141 | <span class="global">print</span>(<span class="string">"\nDone!"</span>)</pre> | ||
142 | |||
143 | |||
144 | </div> <!-- id="content" --> | ||
145 | </div> <!-- id="main" --> | ||
146 | <div id="about"> | ||
147 | <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i> | ||
148 | <i style="float:right;">Last updated 2024-06-20 23:11:37 </i> | ||
149 | </div> <!-- id="about" --> | ||
150 | </div> <!-- id="container" --> | ||
151 | </body> | ||
152 | </html> | ||
diff --git a/docs/examples/terminalsize.lua.html b/docs/examples/terminalsize.lua.html new file mode 100644 index 0000000..d7f902d --- /dev/null +++ b/docs/examples/terminalsize.lua.html | |||
@@ -0,0 +1,117 @@ | |||
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" | ||
2 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> | ||
3 | <html> | ||
4 | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> | ||
5 | <head> | ||
6 | <title>Lua-System docs</title> | ||
7 | <link rel="stylesheet" href="../ldoc.css" type="text/css" /> | ||
8 | </head> | ||
9 | <body> | ||
10 | |||
11 | <div id="container"> | ||
12 | |||
13 | <div id="product"> | ||
14 | <div id="product_logo"></div> | ||
15 | <div id="product_name"><big><b></b></big></div> | ||
16 | <div id="product_description"></div> | ||
17 | </div> <!-- id="product" --> | ||
18 | |||
19 | |||
20 | <div id="main"> | ||
21 | |||
22 | |||
23 | <!-- Menu --> | ||
24 | |||
25 | <div id="navigation"> | ||
26 | <br/> | ||
27 | <h1>Lua-System</h1> | ||
28 | |||
29 | |||
30 | <ul> | ||
31 | <li><a href="../index.html">Index</a></li> | ||
32 | </ul> | ||
33 | |||
34 | |||
35 | |||
36 | <h2>Examples</h2> | ||
37 | <ul class="nowrap"> | ||
38 | <li><a href="../examples/compat.lua.html">compat.lua</a></li> | ||
39 | <li><a href="../examples/flag_debugging.lua.html">flag_debugging.lua</a></li> | ||
40 | <li><a href="../examples/password_input.lua.html">password_input.lua</a></li> | ||
41 | <li><a href="../examples/read.lua.html">read.lua</a></li> | ||
42 | <li><a href="../examples/readline.lua.html">readline.lua</a></li> | ||
43 | <li><a href="../examples/spinner.lua.html">spinner.lua</a></li> | ||
44 | <li><a href="../examples/spiral_snake.lua.html">spiral_snake.lua</a></li> | ||
45 | <li><strong>terminalsize.lua</strong></li> | ||
46 | </ul> | ||
47 | <h2>Modules</h2> | ||
48 | <ul class="nowrap"> | ||
49 | <li><a href="../modules/system.html">system</a></li> | ||
50 | </ul> | ||
51 | <h2>Classes</h2> | ||
52 | <ul class="nowrap"> | ||
53 | <li><a href="../classes/bitflags.html">bitflags</a></li> | ||
54 | </ul> | ||
55 | <h2>Topics</h2> | ||
56 | <ul class=""> | ||
57 | <li><a href="../topics/01-introduction.md.html">1. Introduction</a></li> | ||
58 | <li><a href="../topics/02-development.md.html">2. Development</a></li> | ||
59 | <li><a href="../topics/03-terminal.md.html">3. Terminal functionality</a></li> | ||
60 | <li><a href="../topics/CHANGELOG.md.html">CHANGELOG</a></li> | ||
61 | <li><a href="../topics/LICENSE.md.html">MIT License</a></li> | ||
62 | </ul> | ||
63 | |||
64 | </div> | ||
65 | |||
66 | <div id="content"> | ||
67 | |||
68 | <h2>terminalsize.lua</h2> | ||
69 | <pre> | ||
70 | <span class="keyword">local</span> sys = <span class="global">require</span>(<span class="string">"system"</span>) | ||
71 | |||
72 | sys.<span class="function-name">autotermrestore</span>() <span class="comment">-- set up auto restore of terminal settings on exit | ||
73 | </span> | ||
74 | <span class="comment">-- setup Windows console to handle ANSI processing | ||
75 | </span>sys.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdout, sys.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout) + sys.COF_VIRTUAL_TERMINAL_PROCESSING) | ||
76 | sys.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdin, sys.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdin) + sys.CIF_VIRTUAL_TERMINAL_INPUT) | ||
77 | |||
78 | <span class="comment">-- setup Posix to disable canonical mode and echo | ||
79 | </span><span class="keyword">local</span> of_attr = sys.<span class="function-name">tcgetattr</span>(<span class="global">io</span>.stdin) | ||
80 | sys.<span class="function-name">setnonblock</span>(<span class="global">io</span>.stdin, <span class="keyword">true</span>) | ||
81 | sys.<span class="function-name">tcsetattr</span>(<span class="global">io</span>.stdin, sys.TCSANOW, { | ||
82 | lflag = of_attr.lflag - sys.L_ICANON - sys.L_ECHO, <span class="comment">-- disable canonical mode and echo | ||
83 | </span>}) | ||
84 | |||
85 | |||
86 | <span class="comment">-- generate string to move cursor horizontally | ||
87 | </span><span class="comment">-- positive goes right, negative goes left | ||
88 | </span><span class="keyword">local</span> <span class="keyword">function</span> <span class="function-name">cursor_move_horiz</span>(n) | ||
89 | <span class="keyword">if</span> n == <span class="number">0</span> <span class="keyword">then</span> | ||
90 | <span class="keyword">return</span> <span class="string">""</span> | ||
91 | <span class="keyword">end</span> | ||
92 | <span class="keyword">return</span> <span class="string">"\27["</span> .. (n > <span class="number">0</span> <span class="keyword">and</span> n <span class="keyword">or</span> -n) .. (n > <span class="number">0</span> <span class="keyword">and</span> <span class="string">"C"</span> <span class="keyword">or</span> <span class="string">"D"</span>) | ||
93 | <span class="keyword">end</span> | ||
94 | |||
95 | |||
96 | <span class="keyword">local</span> rows, cols | ||
97 | <span class="global">print</span>(<span class="string">"Change the terminal window size, press any key to exit"</span>) | ||
98 | <span class="keyword">while</span> <span class="keyword">not</span> sys.<span class="function-name">readansi</span>(<span class="number">0.2</span>) <span class="keyword">do</span> <span class="comment">-- use readansi to not leave stray bytes in the input buffer | ||
99 | </span> <span class="keyword">local</span> nrows, ncols = sys.<span class="function-name">termsize</span>() | ||
100 | <span class="keyword">if</span> rows ~= nrows <span class="keyword">or</span> cols ~= ncols <span class="keyword">then</span> | ||
101 | rows, cols = nrows, ncols | ||
102 | <span class="keyword">local</span> text = <span class="string">"Terminal size: "</span> .. rows .. <span class="string">"x"</span> .. cols .. <span class="string">" "</span> | ||
103 | <span class="global">io</span>.<span class="function-name">write</span>(text .. <span class="function-name">cursor_move_horiz</span>(-#text)) | ||
104 | <span class="global">io</span>.<span class="function-name">flush</span>() | ||
105 | <span class="keyword">end</span> | ||
106 | <span class="keyword">end</span></pre> | ||
107 | |||
108 | |||
109 | </div> <!-- id="content" --> | ||
110 | </div> <!-- id="main" --> | ||
111 | <div id="about"> | ||
112 | <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i> | ||
113 | <i style="float:right;">Last updated 2024-06-20 23:11:37 </i> | ||
114 | </div> <!-- id="about" --> | ||
115 | </div> <!-- id="container" --> | ||
116 | </body> | ||
117 | </html> | ||
diff --git a/docs/index.html b/docs/index.html index cd95fc2..52c93fe 100644 --- a/docs/index.html +++ b/docs/index.html | |||
@@ -27,339 +27,122 @@ | |||
27 | <h1>Lua-System</h1> | 27 | <h1>Lua-System</h1> |
28 | 28 | ||
29 | 29 | ||
30 | <h2>Contents</h2> | 30 | |
31 | <ul> | ||
32 | <li><a href="#environment_Functions">environment Functions</a></li> | ||
33 | <li><a href="#random_Functions">random Functions</a></li> | ||
34 | <li><a href="#term_Functions">term Functions</a></li> | ||
35 | <li><a href="#time_Functions">time Functions</a></li> | ||
36 | </ul> | ||
37 | 31 | ||
38 | 32 | ||
39 | <h2>Modules</h2> | 33 | <h2>Modules</h2> |
40 | <ul class="nowrap"> | 34 | <ul class="nowrap"> |
41 | <li><strong>system</strong></li> | 35 | <li><a href="modules/system.html">system</a></li> |
36 | </ul> | ||
37 | <h2>Classes</h2> | ||
38 | <ul class="nowrap"> | ||
39 | <li><a href="classes/bitflags.html">bitflags</a></li> | ||
42 | </ul> | 40 | </ul> |
43 | <h2>Topics</h2> | 41 | <h2>Topics</h2> |
44 | <ul class=""> | 42 | <ul class=""> |
45 | <li><a href="topics/01-introduction.md.html">1. Introduction</a></li> | 43 | <li><a href="topics/01-introduction.md.html">1. Introduction</a></li> |
44 | <li><a href="topics/02-development.md.html">2. Development</a></li> | ||
45 | <li><a href="topics/03-terminal.md.html">3. Terminal functionality</a></li> | ||
46 | <li><a href="topics/CHANGELOG.md.html">CHANGELOG</a></li> | 46 | <li><a href="topics/CHANGELOG.md.html">CHANGELOG</a></li> |
47 | <li><a href="topics/LICENSE.md.html">MIT License</a></li> | 47 | <li><a href="topics/LICENSE.md.html">MIT License</a></li> |
48 | </ul> | 48 | </ul> |
49 | <h2>Examples</h2> | ||
50 | <ul class="nowrap"> | ||
51 | <li><a href="examples/compat.lua.html">compat.lua</a></li> | ||
52 | <li><a href="examples/flag_debugging.lua.html">flag_debugging.lua</a></li> | ||
53 | <li><a href="examples/password_input.lua.html">password_input.lua</a></li> | ||
54 | <li><a href="examples/read.lua.html">read.lua</a></li> | ||
55 | <li><a href="examples/readline.lua.html">readline.lua</a></li> | ||
56 | <li><a href="examples/spinner.lua.html">spinner.lua</a></li> | ||
57 | <li><a href="examples/spiral_snake.lua.html">spiral_snake.lua</a></li> | ||
58 | <li><a href="examples/terminalsize.lua.html">terminalsize.lua</a></li> | ||
59 | </ul> | ||
49 | 60 | ||
50 | </div> | 61 | </div> |
51 | 62 | ||
52 | <div id="content"> | 63 | <div id="content"> |
53 | 64 | ||
54 | <h1>Module <code>system</code></h1> | ||
55 | <p>Platform independent system calls for Lua.</p> | ||
56 | <p> | ||
57 | |||
58 | </p> | ||
59 | 65 | ||
66 | <h2>Platform independent system calls for Lua</h2> | ||
60 | 67 | ||
61 | <h2><a href="#environment_Functions">environment Functions</a></h2> | 68 | <h2>Modules</h2> |
62 | <table class="function_list"> | 69 | <table class="module_list"> |
63 | <tr> | 70 | <tr> |
64 | <td class="name" nowrap><a href="#getenv">getenv (name)</a></td> | 71 | <td class="name" nowrap><a href="modules/system.html">system</a></td> |
65 | <td class="summary">Gets the value of an environment variable.</td> | 72 | <td class="summary">Platform independent system calls for Lua.</td> |
66 | </tr> | 73 | </tr> |
74 | </table> | ||
75 | <h2>Classes</h2> | ||
76 | <table class="module_list"> | ||
67 | <tr> | 77 | <tr> |
68 | <td class="name" nowrap><a href="#getenvs">getenvs ()</a></td> | 78 | <td class="name" nowrap><a href="classes/bitflags.html">bitflags</a></td> |
69 | <td class="summary">Returns a table with all environment variables.</td> | 79 | <td class="summary">Bitflags module.</td> |
70 | </tr> | 80 | </tr> |
81 | </table> | ||
82 | <h2>Topics</h2> | ||
83 | <table class="module_list"> | ||
71 | <tr> | 84 | <tr> |
72 | <td class="name" nowrap><a href="#setenv">setenv (name[, value])</a></td> | 85 | <td class="name" nowrap><a href="topics/01-introduction.md.html">01-introduction.md</a></td> |
73 | <td class="summary">Sets an environment variable.</td> | 86 | <td class="summary"></td> |
74 | </tr> | 87 | </tr> |
75 | </table> | ||
76 | <h2><a href="#random_Functions">random Functions</a></h2> | ||
77 | <table class="function_list"> | ||
78 | <tr> | 88 | <tr> |
79 | <td class="name" nowrap><a href="#random">random ([length=1])</a></td> | 89 | <td class="name" nowrap><a href="topics/02-development.md.html">02-development.md</a></td> |
80 | <td class="summary">Generate random bytes.</td> | 90 | <td class="summary"></td> |
81 | </tr> | 91 | </tr> |
82 | </table> | ||
83 | <h2><a href="#term_Functions">term Functions</a></h2> | ||
84 | <table class="function_list"> | ||
85 | <tr> | 92 | <tr> |
86 | <td class="name" nowrap><a href="#isatty">isatty (file)</a></td> | 93 | <td class="name" nowrap><a href="topics/03-terminal.md.html">03-terminal.md</a></td> |
87 | <td class="summary">Checks if a file-handle is a TTY.</td> | 94 | <td class="summary"></td> |
95 | </tr> | ||
96 | <tr> | ||
97 | <td class="name" nowrap><a href="topics/CHANGELOG.md.html">CHANGELOG.md</a></td> | ||
98 | <td class="summary"></td> | ||
99 | </tr> | ||
100 | <tr> | ||
101 | <td class="name" nowrap><a href="topics/LICENSE.md.html">LICENSE.md</a></td> | ||
102 | <td class="summary"></td> | ||
88 | </tr> | 103 | </tr> |
89 | </table> | 104 | </table> |
90 | <h2><a href="#time_Functions">time Functions</a></h2> | 105 | <h2>Examples</h2> |
91 | <table class="function_list"> | 106 | <table class="module_list"> |
107 | <tr> | ||
108 | <td class="name" nowrap><a href="examples/compat.lua.html">compat.lua</a></td> | ||
109 | <td class="summary"></td> | ||
110 | </tr> | ||
111 | <tr> | ||
112 | <td class="name" nowrap><a href="examples/flag_debugging.lua.html">flag_debugging.lua</a></td> | ||
113 | <td class="summary"></td> | ||
114 | </tr> | ||
115 | <tr> | ||
116 | <td class="name" nowrap><a href="examples/password_input.lua.html">password_input.lua</a></td> | ||
117 | <td class="summary"></td> | ||
118 | </tr> | ||
119 | <tr> | ||
120 | <td class="name" nowrap><a href="examples/read.lua.html">read.lua</a></td> | ||
121 | <td class="summary"></td> | ||
122 | </tr> | ||
123 | <tr> | ||
124 | <td class="name" nowrap><a href="examples/readline.lua.html">readline.lua</a></td> | ||
125 | <td class="summary"></td> | ||
126 | </tr> | ||
92 | <tr> | 127 | <tr> |
93 | <td class="name" nowrap><a href="#gettime">gettime ()</a></td> | 128 | <td class="name" nowrap><a href="examples/spinner.lua.html">spinner.lua</a></td> |
94 | <td class="summary">Get system time.</td> | 129 | <td class="summary"></td> |
95 | </tr> | 130 | </tr> |
96 | <tr> | 131 | <tr> |
97 | <td class="name" nowrap><a href="#monotime">monotime ()</a></td> | 132 | <td class="name" nowrap><a href="examples/spiral_snake.lua.html">spiral_snake.lua</a></td> |
98 | <td class="summary">Get monotonic time.</td> | 133 | <td class="summary"></td> |
99 | </tr> | 134 | </tr> |
100 | <tr> | 135 | <tr> |
101 | <td class="name" nowrap><a href="#sleep">sleep (seconds[, precision=16])</a></td> | 136 | <td class="name" nowrap><a href="examples/terminalsize.lua.html">terminalsize.lua</a></td> |
102 | <td class="summary">Sleep without a busy loop.</td> | 137 | <td class="summary"></td> |
103 | </tr> | 138 | </tr> |
104 | </table> | 139 | </table> |
105 | 140 | ||
106 | <br/> | ||
107 | <br/> | ||
108 | |||
109 | |||
110 | <h2 class="section-header "><a name="environment_Functions"></a>environment Functions</h2> | ||
111 | |||
112 | <dl class="function"> | ||
113 | <dt> | ||
114 | <a name = "getenv"></a> | ||
115 | <strong>getenv (name)</strong> | ||
116 | </dt> | ||
117 | <dd> | ||
118 | Gets the value of an environment variable. </p> | ||
119 | |||
120 | <p><strong>NOTE</strong>: Windows has multiple copies of environment variables. For this reason, | ||
121 | the <a href="index.html#setenv">setenv</a> function will not work with Lua's <a href="https://www.lua.org/manual/5.1/manual.html#pdf-os.getenv">os.getenv</a> on Windows. If you want | ||
122 | to use <a href="index.html#setenv">setenv</a> then consider patching <a href="https://www.lua.org/manual/5.1/manual.html#pdf-os.getenv">os.getenv</a> with this implementation of <a href="index.html#getenv">getenv</a>. | ||
123 | |||
124 | |||
125 | <h3>Parameters:</h3> | ||
126 | <ul> | ||
127 | <li><span class="parameter">name</span> | ||
128 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span> | ||
129 | name of the environment variable | ||
130 | </li> | ||
131 | </ul> | ||
132 | |||
133 | <h3>Returns:</h3> | ||
134 | <ol> | ||
135 | |||
136 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a> or <span class="type">nil</span></span> | ||
137 | value of the environment variable, or nil if the variable is not set | ||
138 | </ol> | ||
139 | |||
140 | |||
141 | |||
142 | |||
143 | </dd> | ||
144 | <dt> | ||
145 | <a name = "getenvs"></a> | ||
146 | <strong>getenvs ()</strong> | ||
147 | </dt> | ||
148 | <dd> | ||
149 | Returns a table with all environment variables. | ||
150 | |||
151 | |||
152 | |||
153 | <h3>Returns:</h3> | ||
154 | <ol> | ||
155 | |||
156 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.5">table</a></span> | ||
157 | table with all environment variables and their values | ||
158 | </ol> | ||
159 | |||
160 | |||
161 | |||
162 | |||
163 | </dd> | ||
164 | <dt> | ||
165 | <a name = "setenv"></a> | ||
166 | <strong>setenv (name[, value])</strong> | ||
167 | </dt> | ||
168 | <dd> | ||
169 | Sets an environment variable. </p> | ||
170 | |||
171 | <p><strong>NOTE</strong>: Windows has multiple copies of environment variables. For this reason, the | ||
172 | <a href="index.html#setenv">setenv</a> function will not work with Lua's <a href="https://www.lua.org/manual/5.1/manual.html#pdf-os.getenv">os.getenv</a> on Windows. If you want to use | ||
173 | it then consider patching <a href="https://www.lua.org/manual/5.1/manual.html#pdf-os.getenv">os.getenv</a> with the implementation of <a href="index.html#getenv">system.getenv</a>. | ||
174 | |||
175 | |||
176 | <h3>Parameters:</h3> | ||
177 | <ul> | ||
178 | <li><span class="parameter">name</span> | ||
179 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span> | ||
180 | name of the environment variable | ||
181 | </li> | ||
182 | <li><span class="parameter">value</span> | ||
183 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span> | ||
184 | value of the environment variable, if <code>nil</code> the variable will be deleted (on | ||
185 | Windows, setting an empty string, will also delete the variable) | ||
186 | (<em>optional</em>) | ||
187 | </li> | ||
188 | </ul> | ||
189 | |||
190 | <h3>Returns:</h3> | ||
191 | <ol> | ||
192 | |||
193 | <span class="types"><span class="type">boolean</span></span> | ||
194 | success | ||
195 | </ol> | ||
196 | |||
197 | |||
198 | |||
199 | |||
200 | </dd> | ||
201 | </dl> | ||
202 | <h2 class="section-header "><a name="random_Functions"></a>random Functions</h2> | ||
203 | |||
204 | <dl class="function"> | ||
205 | <dt> | ||
206 | <a name = "random"></a> | ||
207 | <strong>random ([length=1])</strong> | ||
208 | </dt> | ||
209 | <dd> | ||
210 | Generate random bytes. | ||
211 | This uses <code>CryptGenRandom()</code> on Windows, and <code>/dev/urandom</code> on other platforms. It will return the | ||
212 | requested number of bytes, or an error, never a partial result. | ||
213 | |||
214 | |||
215 | <h3>Parameters:</h3> | ||
216 | <ul> | ||
217 | <li><span class="parameter">length</span> | ||
218 | <span class="types"><span class="type">int</span></span> | ||
219 | number of bytes to get | ||
220 | (<em>default</em> 1) | ||
221 | </li> | ||
222 | </ul> | ||
223 | |||
224 | <h3>Returns:</h3> | ||
225 | <ol> | ||
226 | |||
227 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span> | ||
228 | string of random bytes | ||
229 | </ol> | ||
230 | <h3>Or</h3> | ||
231 | <ol> | ||
232 | <li> | ||
233 | <span class="types"><span class="type">nil</span></span> | ||
234 | |||
235 | |||
236 | </li> | ||
237 | <li> | ||
238 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.1/manual.html#5.4">string</a></span> | ||
239 | error message</li> | ||
240 | </ol> | ||
241 | |||
242 | |||
243 | |||
244 | |||
245 | </dd> | ||
246 | </dl> | ||
247 | <h2 class="section-header "><a name="term_Functions"></a>term Functions</h2> | ||
248 | |||
249 | <dl class="function"> | ||
250 | <dt> | ||
251 | <a name = "isatty"></a> | ||
252 | <strong>isatty (file)</strong> | ||
253 | </dt> | ||
254 | <dd> | ||
255 | Checks if a file-handle is a TTY. | ||
256 | |||
257 | |||
258 | <h3>Parameters:</h3> | ||
259 | <ul> | ||
260 | <li><span class="parameter">file</span> | ||
261 | <span class="types"><span class="type">file</span></span> | ||
262 | the file-handle to check | ||
263 | </li> | ||
264 | </ul> | ||
265 | |||
266 | <h3>Returns:</h3> | ||
267 | <ol> | ||
268 | |||
269 | <span class="types"><span class="type">boolean</span></span> | ||
270 | true if the file is a tty | ||
271 | </ol> | ||
272 | |||
273 | |||
274 | |||
275 | |||
276 | </dd> | ||
277 | </dl> | ||
278 | <h2 class="section-header "><a name="time_Functions"></a>time Functions</h2> | ||
279 | |||
280 | <dl class="function"> | ||
281 | <dt> | ||
282 | <a name = "gettime"></a> | ||
283 | <strong>gettime ()</strong> | ||
284 | </dt> | ||
285 | <dd> | ||
286 | Get system time. | ||
287 | The time is returned as the seconds since the epoch (1 January 1970 00:00:00). | ||
288 | |||
289 | |||
290 | |||
291 | <h3>Returns:</h3> | ||
292 | <ol> | ||
293 | |||
294 | <span class="types"><span class="type">number</span></span> | ||
295 | seconds (fractional) | ||
296 | </ol> | ||
297 | |||
298 | |||
299 | |||
300 | |||
301 | </dd> | ||
302 | <dt> | ||
303 | <a name = "monotime"></a> | ||
304 | <strong>monotime ()</strong> | ||
305 | </dt> | ||
306 | <dd> | ||
307 | Get monotonic time. | ||
308 | The time is returned as the seconds since system start. | ||
309 | |||
310 | |||
311 | |||
312 | <h3>Returns:</h3> | ||
313 | <ol> | ||
314 | |||
315 | <span class="types"><span class="type">number</span></span> | ||
316 | seconds (fractional) | ||
317 | </ol> | ||
318 | |||
319 | |||
320 | |||
321 | |||
322 | </dd> | ||
323 | <dt> | ||
324 | <a name = "sleep"></a> | ||
325 | <strong>sleep (seconds[, precision=16])</strong> | ||
326 | </dt> | ||
327 | <dd> | ||
328 | Sleep without a busy loop. | ||
329 | This function will sleep, without doing a busy-loop and wasting CPU cycles. | ||
330 | |||
331 | |||
332 | <h3>Parameters:</h3> | ||
333 | <ul> | ||
334 | <li><span class="parameter">seconds</span> | ||
335 | <span class="types"><span class="type">number</span></span> | ||
336 | seconds to sleep (fractional). | ||
337 | </li> | ||
338 | <li><span class="parameter">precision</span> | ||
339 | <span class="types"><span class="type">integer</span></span> | ||
340 | minimum stepsize in milliseconds (Windows only, ignored elsewhere) | ||
341 | (<em>default</em> 16) | ||
342 | </li> | ||
343 | </ul> | ||
344 | |||
345 | <h3>Returns:</h3> | ||
346 | <ol> | ||
347 | |||
348 | <code>true</code> on success, or <code>nil+err</code> on failure | ||
349 | </ol> | ||
350 | |||
351 | |||
352 | |||
353 | |||
354 | </dd> | ||
355 | </dl> | ||
356 | |||
357 | |||
358 | </div> <!-- id="content" --> | 141 | </div> <!-- id="content" --> |
359 | </div> <!-- id="main" --> | 142 | </div> <!-- id="main" --> |
360 | <div id="about"> | 143 | <div id="about"> |
361 | <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i> | 144 | <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i> |
362 | <i style="float:right;">Last updated 2023-12-15 13:15:09 </i> | 145 | <i style="float:right;">Last updated 2024-06-20 23:11:37 </i> |
363 | </div> <!-- id="about" --> | 146 | </div> <!-- id="about" --> |
364 | </div> <!-- id="container" --> | 147 | </div> <!-- id="container" --> |
365 | </body> | 148 | </body> |
diff --git a/docs/modules/system.html b/docs/modules/system.html new file mode 100644 index 0000000..0423e37 --- /dev/null +++ b/docs/modules/system.html | |||
@@ -0,0 +1,1418 @@ | |||
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" | ||
2 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> | ||
3 | <html> | ||
4 | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> | ||
5 | <head> | ||
6 | <title>Lua-System docs</title> | ||
7 | <link rel="stylesheet" href="../ldoc.css" type="text/css" /> | ||
8 | </head> | ||
9 | <body> | ||
10 | |||
11 | <div id="container"> | ||
12 | |||
13 | <div id="product"> | ||
14 | <div id="product_logo"></div> | ||
15 | <div id="product_name"><big><b></b></big></div> | ||
16 | <div id="product_description"></div> | ||
17 | </div> <!-- id="product" --> | ||
18 | |||
19 | |||
20 | <div id="main"> | ||
21 | |||
22 | |||
23 | <!-- Menu --> | ||
24 | |||
25 | <div id="navigation"> | ||
26 | <br/> | ||
27 | <h1>Lua-System</h1> | ||
28 | |||
29 | |||
30 | <ul> | ||
31 | <li><a href="../index.html">Index</a></li> | ||
32 | </ul> | ||
33 | |||
34 | <h2>Contents</h2> | ||
35 | <ul> | ||
36 | <li><a href="#Fields">Fields</a></li> | ||
37 | <li><a href="#Environment">Environment </a></li> | ||
38 | <li><a href="#Random">Random </a></li> | ||
39 | <li><a href="#Terminal">Terminal </a></li> | ||
40 | <li><a href="#Time">Time </a></li> | ||
41 | </ul> | ||
42 | |||
43 | |||
44 | <h2>Modules</h2> | ||
45 | <ul class="nowrap"> | ||
46 | <li><strong>system</strong></li> | ||
47 | </ul> | ||
48 | <h2>Classes</h2> | ||
49 | <ul class="nowrap"> | ||
50 | <li><a href="../classes/bitflags.html">bitflags</a></li> | ||
51 | </ul> | ||
52 | <h2>Topics</h2> | ||
53 | <ul class=""> | ||
54 | <li><a href="../topics/01-introduction.md.html">1. Introduction</a></li> | ||
55 | <li><a href="../topics/02-development.md.html">2. Development</a></li> | ||
56 | <li><a href="../topics/03-terminal.md.html">3. Terminal functionality</a></li> | ||
57 | <li><a href="../topics/CHANGELOG.md.html">CHANGELOG</a></li> | ||
58 | <li><a href="../topics/LICENSE.md.html">MIT License</a></li> | ||
59 | </ul> | ||
60 | <h2>Examples</h2> | ||
61 | <ul class="nowrap"> | ||
62 | <li><a href="../examples/compat.lua.html">compat.lua</a></li> | ||
63 | <li><a href="../examples/flag_debugging.lua.html">flag_debugging.lua</a></li> | ||
64 | <li><a href="../examples/password_input.lua.html">password_input.lua</a></li> | ||
65 | <li><a href="../examples/read.lua.html">read.lua</a></li> | ||
66 | <li><a href="../examples/readline.lua.html">readline.lua</a></li> | ||
67 | <li><a href="../examples/spinner.lua.html">spinner.lua</a></li> | ||
68 | <li><a href="../examples/spiral_snake.lua.html">spiral_snake.lua</a></li> | ||
69 | <li><a href="../examples/terminalsize.lua.html">terminalsize.lua</a></li> | ||
70 | </ul> | ||
71 | |||
72 | </div> | ||
73 | |||
74 | <div id="content"> | ||
75 | |||
76 | <h1>Module <code>system</code></h1> | ||
77 | <p>Platform independent system calls for Lua.</p> | ||
78 | <p> | ||
79 | |||
80 | </p> | ||
81 | |||
82 | |||
83 | <h2><a href="#Fields">Fields</a></h2> | ||
84 | <table class="function_list"> | ||
85 | <tr> | ||
86 | <td class="name" nowrap><a href="#windows">windows</a></td> | ||
87 | <td class="summary">Flag to identify Windows.</td> | ||
88 | </tr> | ||
89 | </table> | ||
90 | <h2><a href="#Environment">Environment </a></h2> | ||
91 | <table class="function_list"> | ||
92 | <tr> | ||
93 | <td class="name" nowrap><a href="#getenv">getenv (name)</a></td> | ||
94 | <td class="summary">Gets the value of an environment variable.</td> | ||
95 | </tr> | ||
96 | <tr> | ||
97 | <td class="name" nowrap><a href="#getenvs">getenvs ()</a></td> | ||
98 | <td class="summary">Returns a table with all environment variables.</td> | ||
99 | </tr> | ||
100 | <tr> | ||
101 | <td class="name" nowrap><a href="#setenv">setenv (name[, value])</a></td> | ||
102 | <td class="summary">Sets an environment variable.</td> | ||
103 | </tr> | ||
104 | </table> | ||
105 | <h2><a href="#Random">Random </a></h2> | ||
106 | <table class="function_list"> | ||
107 | <tr> | ||
108 | <td class="name" nowrap><a href="#random">random ([length=1])</a></td> | ||
109 | <td class="summary">Generate random bytes.</td> | ||
110 | </tr> | ||
111 | </table> | ||
112 | <h2><a href="#Terminal">Terminal </a></h2> | ||
113 | <table class="function_list"> | ||
114 | <tr> | ||
115 | <td class="name" nowrap><a href="#CODEPAGE_UTF8">CODEPAGE_UTF8</a></td> | ||
116 | <td class="summary">UTF8 codepage.</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="#getconsolecp">getconsolecp ()</a></td> | ||
128 | <td class="summary">Gets the current console code page (Windows).</td> | ||
129 | </tr> | ||
130 | <tr> | ||
131 | <td class="name" nowrap><a href="#getconsoleflags">getconsoleflags (file)</a></td> | ||
132 | <td class="summary">Gets console flags (Windows).</td> | ||
133 | </tr> | ||
134 | <tr> | ||
135 | <td class="name" nowrap><a href="#getconsoleoutputcp">getconsoleoutputcp ()</a></td> | ||
136 | <td class="summary">Gets the current console output code page (Windows).</td> | ||
137 | </tr> | ||
138 | <tr> | ||
139 | <td class="name" nowrap><a href="#getnonblock">getnonblock (fd)</a></td> | ||
140 | <td class="summary">Gets non-blocking mode status for a file (Posix).</td> | ||
141 | </tr> | ||
142 | <tr> | ||
143 | <td class="name" nowrap><a href="#isatty">isatty (file)</a></td> | ||
144 | <td class="summary">Checks if a file-handle is a TTY.</td> | ||
145 | </tr> | ||
146 | <tr> | ||
147 | <td class="name" nowrap><a href="#listconsoleflags">listconsoleflags (fh)</a></td> | ||
148 | <td class="summary">Debug function for console flags (Windows).</td> | ||
149 | </tr> | ||
150 | <tr> | ||
151 | <td class="name" nowrap><a href="#listtermflags">listtermflags (fh)</a></td> | ||
152 | <td class="summary">Debug function for terminal flags (Posix).</td> | ||
153 | </tr> | ||
154 | <tr> | ||
155 | <td class="name" nowrap><a href="#readansi">readansi (timeout)</a></td> | ||
156 | <td class="summary">Reads a single key, if it is the start of ansi escape sequence then it reads | ||
157 | the full sequence.</td> | ||
158 | </tr> | ||
159 | <tr> | ||
160 | <td class="name" nowrap><a href="#readkey">readkey (timeout)</a></td> | ||
161 | <td class="summary">Reads a single byte from the console, with a timeout.</td> | ||
162 | </tr> | ||
163 | <tr> | ||
164 | <td class="name" nowrap><a href="#setconsolecp">setconsolecp (cp)</a></td> | ||
165 | <td class="summary">Sets the current console code page (Windows).</td> | ||
166 | </tr> | ||
167 | <tr> | ||
168 | <td class="name" nowrap><a href="#setconsoleflags">setconsoleflags (file, bitflags)</a></td> | ||
169 | <td class="summary">Sets the console flags (Windows).</td> | ||
170 | </tr> | ||
171 | <tr> | ||
172 | <td class="name" nowrap><a href="#setconsoleoutputcp">setconsoleoutputcp (cp)</a></td> | ||
173 | <td class="summary">Sets the current console output code page (Windows).</td> | ||
174 | </tr> | ||
175 | <tr> | ||
176 | <td class="name" nowrap><a href="#setnonblock">setnonblock (fd, make_non_block)</a></td> | ||
177 | <td class="summary">Enables or disables non-blocking mode for a file (Posix).</td> | ||
178 | </tr> | ||
179 | <tr> | ||
180 | <td class="name" nowrap><a href="#tcgetattr">tcgetattr (fd)</a></td> | ||
181 | <td class="summary">Get termios state (Posix).</td> | ||
182 | </tr> | ||
183 | <tr> | ||
184 | <td class="name" nowrap><a href="#tcsetattr">tcsetattr (fd, actions, termios)</a></td> | ||
185 | <td class="summary">Set termios state (Posix).</td> | ||
186 | </tr> | ||
187 | <tr> | ||
188 | <td class="name" nowrap><a href="#termbackup">termbackup ()</a></td> | ||
189 | <td class="summary">Returns a backup of terminal settings for stdin/out/err.</td> | ||
190 | </tr> | ||
191 | <tr> | ||
192 | <td class="name" nowrap><a href="#termrestore">termrestore (backup)</a></td> | ||
193 | <td class="summary">Restores terminal settings from a backup</td> | ||
194 | </tr> | ||
195 | <tr> | ||
196 | <td class="name" nowrap><a href="#termsize">termsize ()</a></td> | ||
197 | <td class="summary">Get the size of the terminal in rows and columns.</td> | ||
198 | </tr> | ||
199 | <tr> | ||
200 | <td class="name" nowrap><a href="#termwrap">termwrap (f)</a></td> | ||
201 | <td class="summary">Wraps a function to automatically restore terminal settings upon returning.</td> | ||
202 | </tr> | ||
203 | <tr> | ||
204 | <td class="name" nowrap><a href="#utf8cwidth">utf8cwidth (utf8_char)</a></td> | ||
205 | <td class="summary">Get the width of a utf8 character for terminal display.</td> | ||
206 | </tr> | ||
207 | <tr> | ||
208 | <td class="name" nowrap><a href="#utf8swidth">utf8swidth (utf8_string)</a></td> | ||
209 | <td class="summary">Get the width of a utf8 string for terminal display.</td> | ||
210 | </tr> | ||
211 | </table> | ||
212 | <h2><a href="#Time">Time </a></h2> | ||
213 | <table class="function_list"> | ||
214 | <tr> | ||
215 | <td class="name" nowrap><a href="#gettime">gettime ()</a></td> | ||
216 | <td class="summary">Get system time.</td> | ||
217 | </tr> | ||
218 | <tr> | ||
219 | <td class="name" nowrap><a href="#monotime">monotime ()</a></td> | ||
220 | <td class="summary">Get monotonic time.</td> | ||
221 | </tr> | ||
222 | <tr> | ||
223 | <td class="name" nowrap><a href="#sleep">sleep (seconds[, precision=16])</a></td> | ||
224 | <td class="summary">Sleep without a busy loop.</td> | ||
225 | </tr> | ||
226 | </table> | ||
227 | |||
228 | <br/> | ||
229 | <br/> | ||
230 | |||
231 | |||
232 | <h2 class="section-header "><a name="Fields"></a>Fields</h2> | ||
233 | |||
234 | <dl class="function"> | ||
235 | <dt> | ||
236 | <a name = "windows"></a> | ||
237 | <strong>windows</strong> | ||
238 | </dt> | ||
239 | <dd> | ||
240 | Flag to identify Windows. | ||
241 | |||
242 | |||
243 | <ul> | ||
244 | <li><span class="parameter">windows</span> | ||
245 | <code>true</code> if on Windows, <code>false</code> otherwise. | ||
246 | </li> | ||
247 | </ul> | ||
248 | |||
249 | |||
250 | |||
251 | |||
252 | |||
253 | </dd> | ||
254 | </dl> | ||
255 | <h2 class="section-header "><a name="Environment"></a>Environment </h2> | ||
256 | |||
257 | <dl class="function"> | ||
258 | <dt> | ||
259 | <a name = "getenv"></a> | ||
260 | <strong>getenv (name)</strong> | ||
261 | </dt> | ||
262 | <dd> | ||
263 | Gets the value of an environment variable. </p> | ||
264 | |||
265 | <p><strong>NOTE</strong>: Windows has multiple copies of environment variables. For this reason, | ||
266 | the <a href="../modules/system.html#setenv">setenv</a> function will not work with Lua's <a href="https://www.lua.org/manual/5.4/manual.html#pdf-os.getenv">os.getenv</a> on Windows. If you want | ||
267 | to use <a href="../modules/system.html#setenv">setenv</a> then consider patching <a href="https://www.lua.org/manual/5.4/manual.html#pdf-os.getenv">os.getenv</a> with this implementation of <a href="../modules/system.html#getenv">getenv</a>. | ||
268 | |||
269 | |||
270 | <h3>Parameters:</h3> | ||
271 | <ul> | ||
272 | <li><span class="parameter">name</span> | ||
273 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
274 | name of the environment variable | ||
275 | </li> | ||
276 | </ul> | ||
277 | |||
278 | <h3>Returns:</h3> | ||
279 | <ol> | ||
280 | |||
281 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a> or <span class="type">nil</span></span> | ||
282 | value of the environment variable, or nil if the variable is not set | ||
283 | </ol> | ||
284 | |||
285 | |||
286 | |||
287 | |||
288 | </dd> | ||
289 | <dt> | ||
290 | <a name = "getenvs"></a> | ||
291 | <strong>getenvs ()</strong> | ||
292 | </dt> | ||
293 | <dd> | ||
294 | Returns a table with all environment variables. | ||
295 | |||
296 | |||
297 | |||
298 | <h3>Returns:</h3> | ||
299 | <ol> | ||
300 | |||
301 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span> | ||
302 | table with all environment variables and their values | ||
303 | </ol> | ||
304 | |||
305 | |||
306 | |||
307 | |||
308 | </dd> | ||
309 | <dt> | ||
310 | <a name = "setenv"></a> | ||
311 | <strong>setenv (name[, value])</strong> | ||
312 | </dt> | ||
313 | <dd> | ||
314 | Sets an environment variable. </p> | ||
315 | |||
316 | <p><strong>NOTE</strong>: Windows has multiple copies of environment variables. For this reason, the | ||
317 | <a href="../modules/system.html#setenv">setenv</a> function will not work with Lua's <a href="https://www.lua.org/manual/5.4/manual.html#pdf-os.getenv">os.getenv</a> on Windows. If you want to use | ||
318 | it then consider patching <a href="https://www.lua.org/manual/5.4/manual.html#pdf-os.getenv">os.getenv</a> with the implementation of <a href="../modules/system.html#getenv">system.getenv</a>. | ||
319 | |||
320 | |||
321 | <h3>Parameters:</h3> | ||
322 | <ul> | ||
323 | <li><span class="parameter">name</span> | ||
324 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
325 | name of the environment variable | ||
326 | </li> | ||
327 | <li><span class="parameter">value</span> | ||
328 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
329 | value of the environment variable, if <code>nil</code> the variable will be deleted (on | ||
330 | Windows, setting an empty string, will also delete the variable) | ||
331 | (<em>optional</em>) | ||
332 | </li> | ||
333 | </ul> | ||
334 | |||
335 | <h3>Returns:</h3> | ||
336 | <ol> | ||
337 | |||
338 | <span class="types"><span class="type">boolean</span></span> | ||
339 | success | ||
340 | </ol> | ||
341 | |||
342 | |||
343 | |||
344 | |||
345 | </dd> | ||
346 | </dl> | ||
347 | <h2 class="section-header "><a name="Random"></a>Random </h2> | ||
348 | |||
349 | <dl class="function"> | ||
350 | <dt> | ||
351 | <a name = "random"></a> | ||
352 | <strong>random ([length=1])</strong> | ||
353 | </dt> | ||
354 | <dd> | ||
355 | Generate random bytes. | ||
356 | This uses <code>CryptGenRandom()</code> on Windows, and <code>/dev/urandom</code> on other platforms. It will return the | ||
357 | requested number of bytes, or an error, never a partial result. | ||
358 | |||
359 | |||
360 | <h3>Parameters:</h3> | ||
361 | <ul> | ||
362 | <li><span class="parameter">length</span> | ||
363 | <span class="types"><span class="type">int</span></span> | ||
364 | number of bytes to get | ||
365 | (<em>default</em> 1) | ||
366 | </li> | ||
367 | </ul> | ||
368 | |||
369 | <h3>Returns:</h3> | ||
370 | <ol> | ||
371 | |||
372 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
373 | string of random bytes | ||
374 | </ol> | ||
375 | <h3>Or</h3> | ||
376 | <ol> | ||
377 | <li> | ||
378 | <span class="types"><span class="type">nil</span></span> | ||
379 | |||
380 | |||
381 | </li> | ||
382 | <li> | ||
383 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
384 | error message</li> | ||
385 | </ol> | ||
386 | |||
387 | |||
388 | |||
389 | |||
390 | </dd> | ||
391 | </dl> | ||
392 | <h2 class="section-header has-description"><a name="Terminal"></a>Terminal </h2> | ||
393 | |||
394 | <div class="section-description"> | ||
395 | Unix: see https://blog.nelhage.com/2009/12/a-brief-introduction-to-termios-termios3-and-stty/</p> | ||
396 | |||
397 | <p> Windows: see https://learn.microsoft.com/en-us/windows/console/console-reference | ||
398 | </div> | ||
399 | <dl class="function"> | ||
400 | <dt> | ||
401 | <a name = "CODEPAGE_UTF8"></a> | ||
402 | <strong>CODEPAGE_UTF8</strong> | ||
403 | </dt> | ||
404 | <dd> | ||
405 | UTF8 codepage. | ||
406 | To be used with <a href="../modules/system.html#setconsoleoutputcp">system.setconsoleoutputcp</a> and <a href="../modules/system.html#setconsolecp">system.setconsolecp</a>. | ||
407 | |||
408 | |||
409 | <ul> | ||
410 | <li><span class="parameter">CODEPAGE_UTF8</span> | ||
411 | The Windows CodePage for UTF8. | ||
412 | </li> | ||
413 | </ul> | ||
414 | |||
415 | |||
416 | |||
417 | |||
418 | |||
419 | </dd> | ||
420 | <dt> | ||
421 | <a name = "_readkey"></a> | ||
422 | <strong>_readkey ()</strong> | ||
423 | </dt> | ||
424 | <dd> | ||
425 | Reads a key from the console non-blocking. This function should not be called | ||
426 | directly, but through the <a href="../modules/system.html#readkey">system.readkey</a> or <a href="../modules/system.html#readansi">system.readansi</a> functions. It | ||
427 | will return the next byte from the input stream, or <code>nil</code> if no key was pressed.</p> | ||
428 | |||
429 | <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> | ||
430 | and canonical mode must be turned off using <a href="../modules/system.html#tcsetattr">tcsetattr</a>, | ||
431 | before calling this function. Otherwise it will block. No conversions are | ||
432 | done on Posix, so the byte read is returned as-is.</p> | ||
433 | |||
434 | <p>On Windows this reads a wide character and converts it to UTF-8. Multi-byte | ||
435 | sequences will be buffered internally and returned one byte at a time. | ||
436 | |||
437 | |||
438 | |||
439 | <h3>Returns:</h3> | ||
440 | <ol> | ||
441 | |||
442 | <span class="types"><span class="type">integer</span></span> | ||
443 | the byte read from the input stream | ||
444 | </ol> | ||
445 | <h3>Or</h3> | ||
446 | <ol> | ||
447 | |||
448 | <span class="types"><span class="type">nil</span></span> | ||
449 | if no key was pressed | ||
450 | </ol> | ||
451 | <h3>Or</h3> | ||
452 | <ol> | ||
453 | <li> | ||
454 | <span class="types"><span class="type">nil</span></span> | ||
455 | on error</li> | ||
456 | <li> | ||
457 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
458 | error message</li> | ||
459 | <li> | ||
460 | <span class="types"><span class="type">int</span></span> | ||
461 | errnum (on posix)</li> | ||
462 | </ol> | ||
463 | |||
464 | |||
465 | |||
466 | |||
467 | </dd> | ||
468 | <dt> | ||
469 | <a name = "autotermrestore"></a> | ||
470 | <strong>autotermrestore ()</strong> | ||
471 | </dt> | ||
472 | <dd> | ||
473 | Backs up terminal settings and restores them on application exit. | ||
474 | Calls <a href="../modules/system.html#termbackup">termbackup</a> to back up terminal settings and sets up a GC method to | ||
475 | automatically restore them on application exit (also works on Lua 5.1). | ||
476 | |||
477 | |||
478 | |||
479 | <h3>Returns:</h3> | ||
480 | <ol> | ||
481 | |||
482 | <span class="types"><span class="type">boolean</span></span> | ||
483 | true | ||
484 | </ol> | ||
485 | <h3>Or</h3> | ||
486 | <ol> | ||
487 | <li> | ||
488 | <span class="types"><span class="type">nil</span></span> | ||
489 | if the backup was already created</li> | ||
490 | <li> | ||
491 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
492 | error message</li> | ||
493 | </ol> | ||
494 | |||
495 | |||
496 | |||
497 | |||
498 | </dd> | ||
499 | <dt> | ||
500 | <a name = "getconsolecp"></a> | ||
501 | <strong>getconsolecp ()</strong> | ||
502 | </dt> | ||
503 | <dd> | ||
504 | Gets the current console code page (Windows). | ||
505 | |||
506 | |||
507 | |||
508 | <h3>Returns:</h3> | ||
509 | <ol> | ||
510 | |||
511 | <span class="types"><span class="type">int</span></span> | ||
512 | the current code page (always 65001 on Posix systems) | ||
513 | </ol> | ||
514 | |||
515 | |||
516 | |||
517 | |||
518 | </dd> | ||
519 | <dt> | ||
520 | <a name = "getconsoleflags"></a> | ||
521 | <strong>getconsoleflags (file)</strong> | ||
522 | </dt> | ||
523 | <dd> | ||
524 | Gets console flags (Windows). | ||
525 | The <code>CIF_</code> and <code>COF_</code> constants are available on the module table. Where <code>CIF</code> are the | ||
526 | input 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 | ||
527 | <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> | ||
528 | |||
529 | <p><em>Note</em>: See <a href="https://learn.microsoft.com/en-us/windows/console/setconsolemode">setconsolemode documentation</a> | ||
530 | for more information on the flags. | ||
531 | |||
532 | |||
533 | <h3>Parameters:</h3> | ||
534 | <ul> | ||
535 | <li><span class="parameter">file</span> | ||
536 | <span class="types"><span class="type">file</span></span> | ||
537 | 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> | ||
538 | </li> | ||
539 | </ul> | ||
540 | |||
541 | <h3>Returns:</h3> | ||
542 | <ol> | ||
543 | |||
544 | <span class="types"><a class="type" href="../classes/bitflags.html#">bitflags</a></span> | ||
545 | the current console flags. | ||
546 | </ol> | ||
547 | <h3>Or</h3> | ||
548 | <ol> | ||
549 | <li> | ||
550 | <span class="types"><span class="type">nil</span></span> | ||
551 | |||
552 | |||
553 | </li> | ||
554 | <li> | ||
555 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
556 | error message</li> | ||
557 | </ol> | ||
558 | |||
559 | |||
560 | |||
561 | <h3>Usage:</h3> | ||
562 | <ul> | ||
563 | <pre class="example"><span class="keyword">local</span> system = <span class="global">require</span>(<span class="string">'system'</span>) | ||
564 | |||
565 | <span class="keyword">local</span> flags = system.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout) | ||
566 | <span class="global">print</span>(<span class="string">"Current stdout flags:"</span>, <span class="global">tostring</span>(flags)) | ||
567 | |||
568 | <span class="keyword">if</span> flags:<span class="function-name">has_all_of</span>(system.COF_VIRTUAL_TERMINAL_PROCESSING + system.COF_PROCESSED_OUTPUT) <span class="keyword">then</span> | ||
569 | <span class="global">print</span>(<span class="string">"Both flags are set"</span>) | ||
570 | <span class="keyword">else</span> | ||
571 | <span class="global">print</span>(<span class="string">"At least one flag is not set"</span>) | ||
572 | <span class="keyword">end</span></pre> | ||
573 | </ul> | ||
574 | |||
575 | </dd> | ||
576 | <dt> | ||
577 | <a name = "getconsoleoutputcp"></a> | ||
578 | <strong>getconsoleoutputcp ()</strong> | ||
579 | </dt> | ||
580 | <dd> | ||
581 | Gets the current console output code page (Windows). | ||
582 | |||
583 | |||
584 | |||
585 | <h3>Returns:</h3> | ||
586 | <ol> | ||
587 | |||
588 | <span class="types"><span class="type">int</span></span> | ||
589 | the current code page (always 65001 on Posix systems) | ||
590 | </ol> | ||
591 | |||
592 | |||
593 | |||
594 | |||
595 | </dd> | ||
596 | <dt> | ||
597 | <a name = "getnonblock"></a> | ||
598 | <strong>getnonblock (fd)</strong> | ||
599 | </dt> | ||
600 | <dd> | ||
601 | Gets non-blocking mode status for a file (Posix). | ||
602 | |||
603 | |||
604 | <h3>Parameters:</h3> | ||
605 | <ul> | ||
606 | <li><span class="parameter">fd</span> | ||
607 | <span class="types"><span class="type">file</span></span> | ||
608 | 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> | ||
609 | </li> | ||
610 | </ul> | ||
611 | |||
612 | <h3>Returns:</h3> | ||
613 | <ol> | ||
614 | |||
615 | <span class="types"><span class="type">bool</span></span> | ||
616 | <code>true</code> if set to non-blocking, <code>false</code> if not. Always returns <code>false</code> on Windows. | ||
617 | </ol> | ||
618 | <h3>Or</h3> | ||
619 | <ol> | ||
620 | <li> | ||
621 | <span class="types"><span class="type">nil</span></span> | ||
622 | |||
623 | |||
624 | </li> | ||
625 | <li> | ||
626 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
627 | error message</li> | ||
628 | <li> | ||
629 | <span class="types"><span class="type">int</span></span> | ||
630 | errnum</li> | ||
631 | </ol> | ||
632 | |||
633 | |||
634 | |||
635 | |||
636 | </dd> | ||
637 | <dt> | ||
638 | <a name = "isatty"></a> | ||
639 | <strong>isatty (file)</strong> | ||
640 | </dt> | ||
641 | <dd> | ||
642 | Checks if a file-handle is a TTY. | ||
643 | |||
644 | |||
645 | <h3>Parameters:</h3> | ||
646 | <ul> | ||
647 | <li><span class="parameter">file</span> | ||
648 | <span class="types"><span class="type">file</span></span> | ||
649 | 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>. | ||
650 | </li> | ||
651 | </ul> | ||
652 | |||
653 | <h3>Returns:</h3> | ||
654 | <ol> | ||
655 | |||
656 | <span class="types"><span class="type">boolean</span></span> | ||
657 | true if the file is a tty | ||
658 | </ol> | ||
659 | |||
660 | |||
661 | |||
662 | <h3>Usage:</h3> | ||
663 | <ul> | ||
664 | <pre class="example"><span class="keyword">local</span> system = <span class="global">require</span>(<span class="string">'system'</span>) | ||
665 | <span class="keyword">if</span> system.<span class="function-name">isatty</span>(<span class="global">io</span>.stdin) <span class="keyword">then</span> | ||
666 | <span class="comment">-- enable ANSI coloring etc on Windows, does nothing in Posix. | ||
667 | </span> <span class="keyword">local</span> flags = system.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout) | ||
668 | system.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdout, flags + sys.COF_VIRTUAL_TERMINAL_PROCESSING) | ||
669 | <span class="keyword">end</span></pre> | ||
670 | </ul> | ||
671 | |||
672 | </dd> | ||
673 | <dt> | ||
674 | <a name = "listconsoleflags"></a> | ||
675 | <strong>listconsoleflags (fh)</strong> | ||
676 | </dt> | ||
677 | <dd> | ||
678 | Debug function for console flags (Windows). | ||
679 | Pretty prints the current flags set for the handle. | ||
680 | |||
681 | |||
682 | <h3>Parameters:</h3> | ||
683 | <ul> | ||
684 | <li><span class="parameter">fh</span> | ||
685 | 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>) | ||
686 | </li> | ||
687 | </ul> | ||
688 | |||
689 | |||
690 | |||
691 | |||
692 | <h3>Usage:</h3> | ||
693 | <ul> | ||
694 | <pre class="example"><span class="comment">-- Print the flags for stdin/out/err | ||
695 | </span>system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdin) | ||
696 | system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdout) | ||
697 | system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stderr)</pre> | ||
698 | </ul> | ||
699 | |||
700 | </dd> | ||
701 | <dt> | ||
702 | <a name = "listtermflags"></a> | ||
703 | <strong>listtermflags (fh)</strong> | ||
704 | </dt> | ||
705 | <dd> | ||
706 | Debug function for terminal flags (Posix). | ||
707 | Pretty prints the current flags set for the handle. | ||
708 | |||
709 | |||
710 | <h3>Parameters:</h3> | ||
711 | <ul> | ||
712 | <li><span class="parameter">fh</span> | ||
713 | 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>) | ||
714 | </li> | ||
715 | </ul> | ||
716 | |||
717 | |||
718 | |||
719 | |||
720 | <h3>Usage:</h3> | ||
721 | <ul> | ||
722 | <pre class="example"><span class="comment">-- Print the flags for stdin/out/err | ||
723 | </span>system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdin) | ||
724 | system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdout) | ||
725 | system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stderr)</pre> | ||
726 | </ul> | ||
727 | |||
728 | </dd> | ||
729 | <dt> | ||
730 | <a name = "readansi"></a> | ||
731 | <strong>readansi (timeout)</strong> | ||
732 | </dt> | ||
733 | <dd> | ||
734 | Reads a single key, if it is the start of ansi escape sequence then it reads | ||
735 | the full sequence. The key can be a multi-byte string in case of multibyte UTF-8 character. | ||
736 | This function uses <a href="../modules/system.html#readkey">system.readkey</a>, and hence <a href="../modules/system.html#sleep">system.sleep</a> to wait until either a key is | ||
737 | available or the timeout is reached. | ||
738 | It returns immediately if a key is available or if <code>timeout</code> is less than or equal to <code>0</code>. | ||
739 | In case of an ANSI sequence, it will return the full sequence as a string. | ||
740 | |||
741 | |||
742 | <h3>Parameters:</h3> | ||
743 | <ul> | ||
744 | <li><span class="parameter">timeout</span> | ||
745 | <span class="types"><span class="type">number</span></span> | ||
746 | the timeout in seconds. | ||
747 | </li> | ||
748 | </ul> | ||
749 | |||
750 | <h3>Returns:</h3> | ||
751 | <ol> | ||
752 | <li> | ||
753 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
754 | the character that was received (can be multi-byte), or a complete ANSI sequence</li> | ||
755 | <li> | ||
756 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
757 | the type of input: <code>"char"</code> for a single key, <code>"ansi"</code> for an ANSI sequence</li> | ||
758 | </ol> | ||
759 | <h3>Or</h3> | ||
760 | <ol> | ||
761 | <li> | ||
762 | <span class="types"><span class="type">nil</span></span> | ||
763 | in case of an error</li> | ||
764 | <li> | ||
765 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
766 | error message; <code>"timeout"</code> if the timeout was reached.</li> | ||
767 | <li> | ||
768 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
769 | partial result in case of an error while reading a sequence, the sequence so far.</li> | ||
770 | </ol> | ||
771 | |||
772 | |||
773 | |||
774 | |||
775 | </dd> | ||
776 | <dt> | ||
777 | <a name = "readkey"></a> | ||
778 | <strong>readkey (timeout)</strong> | ||
779 | </dt> | ||
780 | <dd> | ||
781 | Reads a single byte from the console, with a timeout. | ||
782 | This function uses <a href="../modules/system.html#sleep">system.sleep</a> to wait until either a byte is available or the timeout is reached. | ||
783 | The sleep period is exponentially backing off, starting at 0.0125 seconds, with a maximum of 0.2 seconds. | ||
784 | It returns immediately if a byte is available or if <code>timeout</code> is less than or equal to <code>0</code>.</p> | ||
785 | |||
786 | <p> Using <a href="../modules/system.html#readansi">system.readansi</a> is preferred over this function. Since this function can leave stray/invalid | ||
787 | byte-sequences in the input buffer, while <a href="../modules/system.html#readansi">system.readansi</a> reads full ANSI and UTF8 sequences. | ||
788 | |||
789 | |||
790 | <h3>Parameters:</h3> | ||
791 | <ul> | ||
792 | <li><span class="parameter">timeout</span> | ||
793 | <span class="types"><span class="type">number</span></span> | ||
794 | the timeout in seconds. | ||
795 | </li> | ||
796 | </ul> | ||
797 | |||
798 | <h3>Returns:</h3> | ||
799 | <ol> | ||
800 | |||
801 | <span class="types"><span class="type">byte</span></span> | ||
802 | the byte value that was read. | ||
803 | </ol> | ||
804 | <h3>Or</h3> | ||
805 | <ol> | ||
806 | <li> | ||
807 | <span class="types"><span class="type">nil</span></span> | ||
808 | if no key was read</li> | ||
809 | <li> | ||
810 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
811 | error message; <code>"timeout"</code> if the timeout was reached.</li> | ||
812 | </ol> | ||
813 | |||
814 | |||
815 | |||
816 | |||
817 | </dd> | ||
818 | <dt> | ||
819 | <a name = "setconsolecp"></a> | ||
820 | <strong>setconsolecp (cp)</strong> | ||
821 | </dt> | ||
822 | <dd> | ||
823 | Sets the current console code page (Windows). | ||
824 | |||
825 | |||
826 | <h3>Parameters:</h3> | ||
827 | <ul> | ||
828 | <li><span class="parameter">cp</span> | ||
829 | <span class="types"><span class="type">int</span></span> | ||
830 | the code page to set, use <a href="../modules/system.html#CODEPAGE_UTF8">system.CODEPAGE_UTF8</a> (65001) for UTF-8 | ||
831 | </li> | ||
832 | </ul> | ||
833 | |||
834 | <h3>Returns:</h3> | ||
835 | <ol> | ||
836 | |||
837 | <span class="types"><span class="type">bool</span></span> | ||
838 | <code>true</code> on success (always <code>true</code> on Posix systems) | ||
839 | </ol> | ||
840 | |||
841 | |||
842 | |||
843 | |||
844 | </dd> | ||
845 | <dt> | ||
846 | <a name = "setconsoleflags"></a> | ||
847 | <strong>setconsoleflags (file, bitflags)</strong> | ||
848 | </dt> | ||
849 | <dd> | ||
850 | Sets the console flags (Windows). | ||
851 | The <code>CIF_</code> and <code>COF_</code> constants are available on the module table. Where <code>CIF</code> are the | ||
852 | input 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 | ||
853 | <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> | ||
854 | |||
855 | <p>To see flag status and constant names check <a href="../modules/system.html#listconsoleflags">listconsoleflags</a>.</p> | ||
856 | |||
857 | <p>Note: not all combinations of flags are allowed, as some are mutually exclusive or mutually required. | ||
858 | See <a href="https://learn.microsoft.com/en-us/windows/console/setconsolemode">setconsolemode documentation</a> | ||
859 | |||
860 | |||
861 | <h3>Parameters:</h3> | ||
862 | <ul> | ||
863 | <li><span class="parameter">file</span> | ||
864 | <span class="types"><span class="type">file</span></span> | ||
865 | 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> | ||
866 | </li> | ||
867 | <li><span class="parameter">bitflags</span> | ||
868 | <span class="types"><a class="type" href="../classes/bitflags.html#">bitflags</a></span> | ||
869 | the flags to set/unset | ||
870 | </li> | ||
871 | </ul> | ||
872 | |||
873 | <h3>Returns:</h3> | ||
874 | <ol> | ||
875 | |||
876 | <span class="types"><span class="type">boolean</span></span> | ||
877 | <code>true</code> on success | ||
878 | </ol> | ||
879 | <h3>Or</h3> | ||
880 | <ol> | ||
881 | <li> | ||
882 | <span class="types"><span class="type">nil</span></span> | ||
883 | |||
884 | |||
885 | </li> | ||
886 | <li> | ||
887 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
888 | error message</li> | ||
889 | </ol> | ||
890 | |||
891 | |||
892 | |||
893 | <h3>Usage:</h3> | ||
894 | <ul> | ||
895 | <pre class="example"><span class="keyword">local</span> system = <span class="global">require</span>(<span class="string">'system'</span>) | ||
896 | system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdout) <span class="comment">-- List all the available flags and their current status | ||
897 | </span> | ||
898 | <span class="keyword">local</span> flags = system.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout) | ||
899 | <span class="global">assert</span>(system.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdout, | ||
900 | flags + system.COF_VIRTUAL_TERMINAL_PROCESSING) | ||
901 | |||
902 | system.<span class="function-name">listconsoleflags</span>(<span class="global">io</span>.stdout) <span class="comment">-- List again to check the differences</span></pre> | ||
903 | </ul> | ||
904 | |||
905 | </dd> | ||
906 | <dt> | ||
907 | <a name = "setconsoleoutputcp"></a> | ||
908 | <strong>setconsoleoutputcp (cp)</strong> | ||
909 | </dt> | ||
910 | <dd> | ||
911 | Sets the current console output code page (Windows). | ||
912 | |||
913 | |||
914 | <h3>Parameters:</h3> | ||
915 | <ul> | ||
916 | <li><span class="parameter">cp</span> | ||
917 | <span class="types"><span class="type">int</span></span> | ||
918 | the code page to set, use <a href="../modules/system.html#CODEPAGE_UTF8">system.CODEPAGE_UTF8</a> (65001) for UTF-8 | ||
919 | </li> | ||
920 | </ul> | ||
921 | |||
922 | <h3>Returns:</h3> | ||
923 | <ol> | ||
924 | |||
925 | <span class="types"><span class="type">bool</span></span> | ||
926 | <code>true</code> on success (always <code>true</code> on Posix systems) | ||
927 | </ol> | ||
928 | |||
929 | |||
930 | |||
931 | |||
932 | </dd> | ||
933 | <dt> | ||
934 | <a name = "setnonblock"></a> | ||
935 | <strong>setnonblock (fd, make_non_block)</strong> | ||
936 | </dt> | ||
937 | <dd> | ||
938 | Enables or disables non-blocking mode for a file (Posix). | ||
939 | |||
940 | |||
941 | <h3>Parameters:</h3> | ||
942 | <ul> | ||
943 | <li><span class="parameter">fd</span> | ||
944 | <span class="types"><span class="type">file</span></span> | ||
945 | 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> | ||
946 | </li> | ||
947 | <li><span class="parameter">make_non_block</span> | ||
948 | <span class="types"><span class="type">boolean</span></span> | ||
949 | a truthy value will enable non-blocking mode, a falsy value will disable it. | ||
950 | </li> | ||
951 | </ul> | ||
952 | |||
953 | <h3>Returns:</h3> | ||
954 | <ol> | ||
955 | |||
956 | <span class="types"><span class="type">bool</span></span> | ||
957 | <code>true</code>, if successful | ||
958 | </ol> | ||
959 | <h3>Or</h3> | ||
960 | <ol> | ||
961 | <li> | ||
962 | <span class="types"><span class="type">nil</span></span> | ||
963 | |||
964 | |||
965 | </li> | ||
966 | <li> | ||
967 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
968 | error message</li> | ||
969 | <li> | ||
970 | <span class="types"><span class="type">int</span></span> | ||
971 | errnum</li> | ||
972 | </ol> | ||
973 | |||
974 | |||
975 | <h3>See also:</h3> | ||
976 | <ul> | ||
977 | <a href="../modules/system.html#getnonblock">getnonblock</a> | ||
978 | </ul> | ||
979 | |||
980 | <h3>Usage:</h3> | ||
981 | <ul> | ||
982 | <pre class="example"><span class="keyword">local</span> sys = <span class="global">require</span>(<span class="string">'system'</span>) | ||
983 | |||
984 | <span class="comment">-- set io.stdin to non-blocking mode | ||
985 | </span><span class="keyword">local</span> old_setting = sys.<span class="function-name">getnonblock</span>(<span class="global">io</span>.stdin) | ||
986 | sys.<span class="function-name">setnonblock</span>(<span class="global">io</span>.stdin, <span class="keyword">true</span>) | ||
987 | |||
988 | <span class="comment">-- do stuff | ||
989 | </span> | ||
990 | <span class="comment">-- restore old setting | ||
991 | </span>sys.<span class="function-name">setnonblock</span>(<span class="global">io</span>.stdin, old_setting)</pre> | ||
992 | </ul> | ||
993 | |||
994 | </dd> | ||
995 | <dt> | ||
996 | <a name = "tcgetattr"></a> | ||
997 | <strong>tcgetattr (fd)</strong> | ||
998 | </dt> | ||
999 | <dd> | ||
1000 | |||
1001 | <p>Get termios state (Posix). | ||
1002 | The terminal attributes is a table with the following fields:</p> | ||
1003 | |||
1004 | <ul> | ||
1005 | <li><code>iflag</code> input flags</li> | ||
1006 | <li><code>oflag</code> output flags</li> | ||
1007 | <li><code>lflag</code> local flags</li> | ||
1008 | <li><code>cflag</code> control flags</li> | ||
1009 | <li><code>ispeed</code> input speed</li> | ||
1010 | <li><code>ospeed</code> output speed</li> | ||
1011 | <li><code>cc</code> control characters</li> | ||
1012 | </ul> | ||
1013 | |||
1014 | |||
1015 | |||
1016 | |||
1017 | <h3>Parameters:</h3> | ||
1018 | <ul> | ||
1019 | <li><span class="parameter">fd</span> | ||
1020 | <span class="types"><span class="type">file</span></span> | ||
1021 | 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> | ||
1022 | </li> | ||
1023 | </ul> | ||
1024 | |||
1025 | <h3>Returns:</h3> | ||
1026 | <ol> | ||
1027 | |||
1028 | error message if failed | ||
1029 | </ol> | ||
1030 | <h3>Or</h3> | ||
1031 | <ol> | ||
1032 | |||
1033 | <span class="types"><span class="type">termios</span></span> | ||
1034 | terminal attributes, if successful. On Windows the bitflags are all 0, and the <code>cc</code> table is empty. | ||
1035 | </ol> | ||
1036 | <h3>Or</h3> | ||
1037 | <ol> | ||
1038 | <li> | ||
1039 | <span class="types"><span class="type">nil</span></span> | ||
1040 | |||
1041 | |||
1042 | </li> | ||
1043 | <li> | ||
1044 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
1045 | error message</li> | ||
1046 | <li> | ||
1047 | <span class="types"><span class="type">int</span></span> | ||
1048 | errnum</li> | ||
1049 | </ol> | ||
1050 | |||
1051 | |||
1052 | |||
1053 | <h3>Usage:</h3> | ||
1054 | <ul> | ||
1055 | <pre class="example"><span class="keyword">local</span> system = <span class="global">require</span>(<span class="string">'system'</span>) | ||
1056 | |||
1057 | <span class="keyword">local</span> status = <span class="global">assert</span>(<span class="function-name">tcgetattr</span>(<span class="global">io</span>.stdin)) | ||
1058 | <span class="keyword">if</span> status.iflag:<span class="function-name">has_all_of</span>(system.I_IGNBRK) <span class="keyword">then</span> | ||
1059 | <span class="global">print</span>(<span class="string">"Ignoring break condition"</span>) | ||
1060 | <span class="keyword">end</span></pre> | ||
1061 | </ul> | ||
1062 | |||
1063 | </dd> | ||
1064 | <dt> | ||
1065 | <a name = "tcsetattr"></a> | ||
1066 | <strong>tcsetattr (fd, actions, termios)</strong> | ||
1067 | </dt> | ||
1068 | <dd> | ||
1069 | Set termios state (Posix). | ||
1070 | This function will set the flags as given.</p> | ||
1071 | |||
1072 | <p>The <code>I_</code>, <code>O_</code>, and <code>L_</code> constants are available on the module table. They are the respective | ||
1073 | flags for the <code>iflags</code>, <code>oflags</code>, and <code>lflags</code> bitmasks.</p> | ||
1074 | |||
1075 | <p>To see flag status and constant names check <a href="../modules/system.html#listtermflags">listtermflags</a>. For their meaning check | ||
1076 | <a href="https://www.man7.org/linux/man-pages/man3/termios.3.html">the manpage</a>.</p> | ||
1077 | |||
1078 | <p><em>Note</em>: only <code>iflag</code>, <code>oflag</code>, and <code>lflag</code> are supported at the moment. The other fields are ignored. | ||
1079 | |||
1080 | |||
1081 | <h3>Parameters:</h3> | ||
1082 | <ul> | ||
1083 | <li><span class="parameter">fd</span> | ||
1084 | <span class="types"><span class="type">file</span></span> | ||
1085 | 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> | ||
1086 | </li> | ||
1087 | <li><span class="parameter">actions</span> | ||
1088 | <span class="types"><span class="type">integer</span></span> | ||
1089 | one of <code>TCSANOW</code>, <code>TCSADRAIN</code>, <code>TCSAFLUSH</code> | ||
1090 | </li> | ||
1091 | <li><span class="parameter">termios</span> a table with bitflag fields: | ||
1092 | <ul> | ||
1093 | <li><span class="parameter">iflag</span> | ||
1094 | <span class="types"><a class="type" href="../classes/bitflags.html#">bitflags</a></span> | ||
1095 | if given will set the input flags | ||
1096 | (<em>optional</em>) | ||
1097 | </li> | ||
1098 | <li><span class="parameter">oflag</span> | ||
1099 | <span class="types"><a class="type" href="../classes/bitflags.html#">bitflags</a></span> | ||
1100 | if given will set the output flags | ||
1101 | (<em>optional</em>) | ||
1102 | </li> | ||
1103 | <li><span class="parameter">lflag</span> | ||
1104 | <span class="types"><a class="type" href="../classes/bitflags.html#">bitflags</a></span> | ||
1105 | if given will set the local flags | ||
1106 | (<em>optional</em>) | ||
1107 | </li> | ||
1108 | </li></ul> | ||
1109 | </ul> | ||
1110 | |||
1111 | <h3>Returns:</h3> | ||
1112 | <ol> | ||
1113 | |||
1114 | <span class="types"><span class="type">bool</span></span> | ||
1115 | <code>true</code>, if successful. Always returns <code>true</code> on Windows. | ||
1116 | </ol> | ||
1117 | <h3>Or</h3> | ||
1118 | <ol> | ||
1119 | <li> | ||
1120 | nil</li> | ||
1121 | <li> | ||
1122 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
1123 | error message</li> | ||
1124 | <li> | ||
1125 | <span class="types"><span class="type">int</span></span> | ||
1126 | errnum</li> | ||
1127 | </ol> | ||
1128 | |||
1129 | |||
1130 | |||
1131 | <h3>Usage:</h3> | ||
1132 | <ul> | ||
1133 | <pre class="example"><span class="keyword">local</span> system = <span class="global">require</span>(<span class="string">'system'</span>) | ||
1134 | |||
1135 | <span class="keyword">local</span> status = <span class="global">assert</span>(<span class="function-name">tcgetattr</span>(<span class="global">io</span>.stdin)) | ||
1136 | <span class="keyword">if</span> <span class="keyword">not</span> status.lflag:<span class="function-name">has_all_of</span>(system.L_ECHO) <span class="keyword">then</span> | ||
1137 | <span class="comment">-- if echo is off, turn echoing newlines on | ||
1138 | </span> <span class="function-name">tcsetattr</span>(<span class="global">io</span>.stdin, system.TCSANOW, { lflag = status.lflag + system.L_ECHONL })) | ||
1139 | <span class="keyword">end</span></pre> | ||
1140 | </ul> | ||
1141 | |||
1142 | </dd> | ||
1143 | <dt> | ||
1144 | <a name = "termbackup"></a> | ||
1145 | <strong>termbackup ()</strong> | ||
1146 | </dt> | ||
1147 | <dd> | ||
1148 | Returns a backup of terminal settings for stdin/out/err. | ||
1149 | Handles terminal/console flags, Windows codepage, and non-block flags on the streams. | ||
1150 | Backs up terminal/console flags only if a stream is a tty. | ||
1151 | |||
1152 | |||
1153 | |||
1154 | <h3>Returns:</h3> | ||
1155 | <ol> | ||
1156 | |||
1157 | table with backup of terminal settings | ||
1158 | </ol> | ||
1159 | |||
1160 | |||
1161 | |||
1162 | |||
1163 | </dd> | ||
1164 | <dt> | ||
1165 | <a name = "termrestore"></a> | ||
1166 | <strong>termrestore (backup)</strong> | ||
1167 | </dt> | ||
1168 | <dd> | ||
1169 | Restores terminal settings from a backup | ||
1170 | |||
1171 | |||
1172 | <h3>Parameters:</h3> | ||
1173 | <ul> | ||
1174 | <li><span class="parameter">backup</span> | ||
1175 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.6">table</a></span> | ||
1176 | the backup of terminal settings, see <a href="../modules/system.html#termbackup">termbackup</a>. | ||
1177 | </li> | ||
1178 | </ul> | ||
1179 | |||
1180 | <h3>Returns:</h3> | ||
1181 | <ol> | ||
1182 | |||
1183 | <span class="types"><span class="type">boolean</span></span> | ||
1184 | true | ||
1185 | </ol> | ||
1186 | |||
1187 | |||
1188 | |||
1189 | |||
1190 | </dd> | ||
1191 | <dt> | ||
1192 | <a name = "termsize"></a> | ||
1193 | <strong>termsize ()</strong> | ||
1194 | </dt> | ||
1195 | <dd> | ||
1196 | Get the size of the terminal in rows and columns. | ||
1197 | |||
1198 | |||
1199 | |||
1200 | <h3>Returns:</h3> | ||
1201 | <ol> | ||
1202 | <li> | ||
1203 | <span class="types"><span class="type">int</span></span> | ||
1204 | the number of rows</li> | ||
1205 | <li> | ||
1206 | <span class="types"><span class="type">int</span></span> | ||
1207 | the number of columns</li> | ||
1208 | </ol> | ||
1209 | <h3>Or</h3> | ||
1210 | <ol> | ||
1211 | <li> | ||
1212 | <span class="types"><span class="type">nil</span></span> | ||
1213 | |||
1214 | |||
1215 | </li> | ||
1216 | <li> | ||
1217 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
1218 | error message</li> | ||
1219 | </ol> | ||
1220 | |||
1221 | |||
1222 | |||
1223 | |||
1224 | </dd> | ||
1225 | <dt> | ||
1226 | <a name = "termwrap"></a> | ||
1227 | <strong>termwrap (f)</strong> | ||
1228 | </dt> | ||
1229 | <dd> | ||
1230 | Wraps a function to automatically restore terminal settings upon returning. | ||
1231 | Calls <a href="../modules/system.html#termbackup">termbackup</a> before calling the function and <a href="../modules/system.html#termrestore">termrestore</a> after. | ||
1232 | |||
1233 | |||
1234 | <h3>Parameters:</h3> | ||
1235 | <ul> | ||
1236 | <li><span class="parameter">f</span> | ||
1237 | <span class="types"><span class="type">function</span></span> | ||
1238 | function to wrap | ||
1239 | </li> | ||
1240 | </ul> | ||
1241 | |||
1242 | <h3>Returns:</h3> | ||
1243 | <ol> | ||
1244 | |||
1245 | <span class="types"><span class="type">function</span></span> | ||
1246 | wrapped function | ||
1247 | </ol> | ||
1248 | |||
1249 | |||
1250 | |||
1251 | |||
1252 | </dd> | ||
1253 | <dt> | ||
1254 | <a name = "utf8cwidth"></a> | ||
1255 | <strong>utf8cwidth (utf8_char)</strong> | ||
1256 | </dt> | ||
1257 | <dd> | ||
1258 | Get the width of a utf8 character for terminal display. | ||
1259 | |||
1260 | |||
1261 | <h3>Parameters:</h3> | ||
1262 | <ul> | ||
1263 | <li><span class="parameter">utf8_char</span> | ||
1264 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
1265 | the utf8 character to check, only the width of the first character will be returned | ||
1266 | </li> | ||
1267 | </ul> | ||
1268 | |||
1269 | <h3>Returns:</h3> | ||
1270 | <ol> | ||
1271 | |||
1272 | <span class="types"><span class="type">int</span></span> | ||
1273 | the display width in columns of the first character in the string (0 for an empty string) | ||
1274 | </ol> | ||
1275 | <h3>Or</h3> | ||
1276 | <ol> | ||
1277 | <li> | ||
1278 | <span class="types"><span class="type">nil</span></span> | ||
1279 | |||
1280 | |||
1281 | </li> | ||
1282 | <li> | ||
1283 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
1284 | error message</li> | ||
1285 | </ol> | ||
1286 | |||
1287 | |||
1288 | |||
1289 | |||
1290 | </dd> | ||
1291 | <dt> | ||
1292 | <a name = "utf8swidth"></a> | ||
1293 | <strong>utf8swidth (utf8_string)</strong> | ||
1294 | </dt> | ||
1295 | <dd> | ||
1296 | Get the width of a utf8 string for terminal display. | ||
1297 | |||
1298 | |||
1299 | <h3>Parameters:</h3> | ||
1300 | <ul> | ||
1301 | <li><span class="parameter">utf8_string</span> | ||
1302 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
1303 | the utf8 string to check | ||
1304 | </li> | ||
1305 | </ul> | ||
1306 | |||
1307 | <h3>Returns:</h3> | ||
1308 | <ol> | ||
1309 | |||
1310 | <span class="types"><span class="type">int</span></span> | ||
1311 | the display width of the string in columns (0 for an empty string) | ||
1312 | </ol> | ||
1313 | <h3>Or</h3> | ||
1314 | <ol> | ||
1315 | <li> | ||
1316 | <span class="types"><span class="type">nil</span></span> | ||
1317 | |||
1318 | |||
1319 | </li> | ||
1320 | <li> | ||
1321 | <span class="types"><a class="type" href="https://www.lua.org/manual/5.4/manual.html#6.4">string</a></span> | ||
1322 | error message</li> | ||
1323 | </ol> | ||
1324 | |||
1325 | |||
1326 | |||
1327 | |||
1328 | </dd> | ||
1329 | </dl> | ||
1330 | <h2 class="section-header "><a name="Time"></a>Time </h2> | ||
1331 | |||
1332 | <dl class="function"> | ||
1333 | <dt> | ||
1334 | <a name = "gettime"></a> | ||
1335 | <strong>gettime ()</strong> | ||
1336 | </dt> | ||
1337 | <dd> | ||
1338 | Get system time. | ||
1339 | The time is returned as the seconds since the epoch (1 January 1970 00:00:00). | ||
1340 | |||
1341 | |||
1342 | |||
1343 | <h3>Returns:</h3> | ||
1344 | <ol> | ||
1345 | |||
1346 | <span class="types"><span class="type">number</span></span> | ||
1347 | seconds (fractional) | ||
1348 | </ol> | ||
1349 | |||
1350 | |||
1351 | |||
1352 | |||
1353 | </dd> | ||
1354 | <dt> | ||
1355 | <a name = "monotime"></a> | ||
1356 | <strong>monotime ()</strong> | ||
1357 | </dt> | ||
1358 | <dd> | ||
1359 | Get monotonic time. | ||
1360 | The time is returned as the seconds since system start. | ||
1361 | |||
1362 | |||
1363 | |||
1364 | <h3>Returns:</h3> | ||
1365 | <ol> | ||
1366 | |||
1367 | <span class="types"><span class="type">number</span></span> | ||
1368 | seconds (fractional) | ||
1369 | </ol> | ||
1370 | |||
1371 | |||
1372 | |||
1373 | |||
1374 | </dd> | ||
1375 | <dt> | ||
1376 | <a name = "sleep"></a> | ||
1377 | <strong>sleep (seconds[, precision=16])</strong> | ||
1378 | </dt> | ||
1379 | <dd> | ||
1380 | Sleep without a busy loop. | ||
1381 | This function will sleep, without doing a busy-loop and wasting CPU cycles. | ||
1382 | |||
1383 | |||
1384 | <h3>Parameters:</h3> | ||
1385 | <ul> | ||
1386 | <li><span class="parameter">seconds</span> | ||
1387 | <span class="types"><span class="type">number</span></span> | ||
1388 | seconds to sleep (fractional). | ||
1389 | </li> | ||
1390 | <li><span class="parameter">precision</span> | ||
1391 | <span class="types"><span class="type">integer</span></span> | ||
1392 | minimum stepsize in milliseconds (Windows only, ignored elsewhere) | ||
1393 | (<em>default</em> 16) | ||
1394 | </li> | ||
1395 | </ul> | ||
1396 | |||
1397 | <h3>Returns:</h3> | ||
1398 | <ol> | ||
1399 | |||
1400 | <code>true</code> on success, or <code>nil+err</code> on failure | ||
1401 | </ol> | ||
1402 | |||
1403 | |||
1404 | |||
1405 | |||
1406 | </dd> | ||
1407 | </dl> | ||
1408 | |||
1409 | |||
1410 | </div> <!-- id="content" --> | ||
1411 | </div> <!-- id="main" --> | ||
1412 | <div id="about"> | ||
1413 | <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i> | ||
1414 | <i style="float:right;">Last updated 2024-06-20 23:11:37 </i> | ||
1415 | </div> <!-- id="about" --> | ||
1416 | </div> <!-- id="container" --> | ||
1417 | </body> | ||
1418 | </html> | ||
diff --git a/docs/topics/01-introduction.md.html b/docs/topics/01-introduction.md.html index 319b9d5..019f7e4 100644 --- a/docs/topics/01-introduction.md.html +++ b/docs/topics/01-introduction.md.html | |||
@@ -27,17 +27,38 @@ | |||
27 | <h1>Lua-System</h1> | 27 | <h1>Lua-System</h1> |
28 | 28 | ||
29 | 29 | ||
30 | <ul> | ||
31 | <li><a href="../index.html">Index</a></li> | ||
32 | </ul> | ||
33 | |||
30 | 34 | ||
31 | 35 | ||
32 | <h2>Topics</h2> | 36 | <h2>Topics</h2> |
33 | <ul class=""> | 37 | <ul class=""> |
34 | <li><strong>1. Introduction</strong></li> | 38 | <li><strong>1. Introduction</strong></li> |
39 | <li><a href="../topics/02-development.md.html">2. Development</a></li> | ||
40 | <li><a href="../topics/03-terminal.md.html">3. Terminal functionality</a></li> | ||
35 | <li><a href="../topics/CHANGELOG.md.html">CHANGELOG</a></li> | 41 | <li><a href="../topics/CHANGELOG.md.html">CHANGELOG</a></li> |
36 | <li><a href="../topics/LICENSE.md.html">MIT License</a></li> | 42 | <li><a href="../topics/LICENSE.md.html">MIT License</a></li> |
37 | </ul> | 43 | </ul> |
38 | <h2>Modules</h2> | 44 | <h2>Modules</h2> |
39 | <ul class="nowrap"> | 45 | <ul class="nowrap"> |
40 | <li><a href="../index.html">system</a></li> | 46 | <li><a href="../modules/system.html">system</a></li> |
47 | </ul> | ||
48 | <h2>Classes</h2> | ||
49 | <ul class="nowrap"> | ||
50 | <li><a href="../classes/bitflags.html">bitflags</a></li> | ||
51 | </ul> | ||
52 | <h2>Examples</h2> | ||
53 | <ul class="nowrap"> | ||
54 | <li><a href="../examples/compat.lua.html">compat.lua</a></li> | ||
55 | <li><a href="../examples/flag_debugging.lua.html">flag_debugging.lua</a></li> | ||
56 | <li><a href="../examples/password_input.lua.html">password_input.lua</a></li> | ||
57 | <li><a href="../examples/read.lua.html">read.lua</a></li> | ||
58 | <li><a href="../examples/readline.lua.html">readline.lua</a></li> | ||
59 | <li><a href="../examples/spinner.lua.html">spinner.lua</a></li> | ||
60 | <li><a href="../examples/spiral_snake.lua.html">spiral_snake.lua</a></li> | ||
61 | <li><a href="../examples/terminalsize.lua.html">terminalsize.lua</a></li> | ||
41 | </ul> | 62 | </ul> |
42 | 63 | ||
43 | </div> | 64 | </div> |
@@ -62,8 +83,8 @@ independence.</p> | |||
62 | </div> <!-- id="content" --> | 83 | </div> <!-- id="content" --> |
63 | </div> <!-- id="main" --> | 84 | </div> <!-- id="main" --> |
64 | <div id="about"> | 85 | <div id="about"> |
65 | <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i> | 86 | <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i> |
66 | <i style="float:right;">Last updated 2023-12-15 13:15:09 </i> | 87 | <i style="float:right;">Last updated 2024-06-20 23:11:37 </i> |
67 | </div> <!-- id="about" --> | 88 | </div> <!-- id="about" --> |
68 | </div> <!-- id="container" --> | 89 | </div> <!-- id="container" --> |
69 | </body> | 90 | </body> |
diff --git a/docs/topics/02-development.md.html b/docs/topics/02-development.md.html new file mode 100644 index 0000000..e911eed --- /dev/null +++ b/docs/topics/02-development.md.html | |||
@@ -0,0 +1,91 @@ | |||
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" | ||
2 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> | ||
3 | <html> | ||
4 | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> | ||
5 | <head> | ||
6 | <title>Lua-System docs</title> | ||
7 | <link rel="stylesheet" href="../ldoc.css" type="text/css" /> | ||
8 | </head> | ||
9 | <body> | ||
10 | |||
11 | <div id="container"> | ||
12 | |||
13 | <div id="product"> | ||
14 | <div id="product_logo"></div> | ||
15 | <div id="product_name"><big><b></b></big></div> | ||
16 | <div id="product_description"></div> | ||
17 | </div> <!-- id="product" --> | ||
18 | |||
19 | |||
20 | <div id="main"> | ||
21 | |||
22 | |||
23 | <!-- Menu --> | ||
24 | |||
25 | <div id="navigation"> | ||
26 | <br/> | ||
27 | <h1>Lua-System</h1> | ||
28 | |||
29 | |||
30 | <ul> | ||
31 | <li><a href="../index.html">Index</a></li> | ||
32 | </ul> | ||
33 | |||
34 | |||
35 | |||
36 | <h2>Topics</h2> | ||
37 | <ul class=""> | ||
38 | <li><a href="../topics/01-introduction.md.html">1. Introduction</a></li> | ||
39 | <li><strong>2. Development</strong></li> | ||
40 | <li><a href="../topics/03-terminal.md.html">3. Terminal functionality</a></li> | ||
41 | <li><a href="../topics/CHANGELOG.md.html">CHANGELOG</a></li> | ||
42 | <li><a href="../topics/LICENSE.md.html">MIT License</a></li> | ||
43 | </ul> | ||
44 | <h2>Modules</h2> | ||
45 | <ul class="nowrap"> | ||
46 | <li><a href="../modules/system.html">system</a></li> | ||
47 | </ul> | ||
48 | <h2>Classes</h2> | ||
49 | <ul class="nowrap"> | ||
50 | <li><a href="../classes/bitflags.html">bitflags</a></li> | ||
51 | </ul> | ||
52 | <h2>Examples</h2> | ||
53 | <ul class="nowrap"> | ||
54 | <li><a href="../examples/compat.lua.html">compat.lua</a></li> | ||
55 | <li><a href="../examples/flag_debugging.lua.html">flag_debugging.lua</a></li> | ||
56 | <li><a href="../examples/password_input.lua.html">password_input.lua</a></li> | ||
57 | <li><a href="../examples/read.lua.html">read.lua</a></li> | ||
58 | <li><a href="../examples/readline.lua.html">readline.lua</a></li> | ||
59 | <li><a href="../examples/spinner.lua.html">spinner.lua</a></li> | ||
60 | <li><a href="../examples/spiral_snake.lua.html">spiral_snake.lua</a></li> | ||
61 | <li><a href="../examples/terminalsize.lua.html">terminalsize.lua</a></li> | ||
62 | </ul> | ||
63 | |||
64 | </div> | ||
65 | |||
66 | <div id="content"> | ||
67 | |||
68 | |||
69 | <h1>2. Development</h1> | ||
70 | |||
71 | <p>Some tests cannot be run in CI becasue they test system specifics that | ||
72 | simply do not exist in a CI environment. An example is the <code>isatty</code> function | ||
73 | Which cannot be set to return a truthy value in CI.</p> | ||
74 | |||
75 | <p>The tests concerned are all labelled with <code>#manual</code>. And in CI they will | ||
76 | be skipped because <code>--exclude-tags=manual</code> is being passed to the | ||
77 | <code>busted</code> command line.</p> | ||
78 | |||
79 | <p>Hence if tests like this are being added, then please ensure the tests | ||
80 | pass locally, and do not rely on CI only.</p> | ||
81 | |||
82 | |||
83 | </div> <!-- id="content" --> | ||
84 | </div> <!-- id="main" --> | ||
85 | <div id="about"> | ||
86 | <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i> | ||
87 | <i style="float:right;">Last updated 2024-06-20 23:11:37 </i> | ||
88 | </div> <!-- id="about" --> | ||
89 | </div> <!-- id="container" --> | ||
90 | </body> | ||
91 | </html> | ||
diff --git a/docs/topics/03-terminal.md.html b/docs/topics/03-terminal.md.html new file mode 100644 index 0000000..3e7e548 --- /dev/null +++ b/docs/topics/03-terminal.md.html | |||
@@ -0,0 +1,225 @@ | |||
1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" | ||
2 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> | ||
3 | <html> | ||
4 | <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/> | ||
5 | <head> | ||
6 | <title>Lua-System docs</title> | ||
7 | <link rel="stylesheet" href="../ldoc.css" type="text/css" /> | ||
8 | </head> | ||
9 | <body> | ||
10 | |||
11 | <div id="container"> | ||
12 | |||
13 | <div id="product"> | ||
14 | <div id="product_logo"></div> | ||
15 | <div id="product_name"><big><b></b></big></div> | ||
16 | <div id="product_description"></div> | ||
17 | </div> <!-- id="product" --> | ||
18 | |||
19 | |||
20 | <div id="main"> | ||
21 | |||
22 | |||
23 | <!-- Menu --> | ||
24 | |||
25 | <div id="navigation"> | ||
26 | <br/> | ||
27 | <h1>Lua-System</h1> | ||
28 | |||
29 | |||
30 | <ul> | ||
31 | <li><a href="../index.html">Index</a></li> | ||
32 | </ul> | ||
33 | |||
34 | <h2>Contents</h2> | ||
35 | <ul> | ||
36 | <li><a href="#3_1_Backup_and_Restore_terminal_settings">3.1 Backup and Restore terminal settings </a></li> | ||
37 | <li><a href="#3_1_Terminal_ANSI_sequences">3.1 Terminal ANSI sequences </a></li> | ||
38 | <li><a href="#3_2_UTF_8_in_output_and_display_width">3.2 UTF-8 in/output and display width </a></li> | ||
39 | <li><a href="#3_3_reading_keyboard_input">3.3 reading keyboard input </a></li> | ||
40 | </ul> | ||
41 | |||
42 | |||
43 | <h2>Topics</h2> | ||
44 | <ul class=""> | ||
45 | <li><a href="../topics/01-introduction.md.html">1. Introduction</a></li> | ||
46 | <li><a href="../topics/02-development.md.html">2. Development</a></li> | ||
47 | <li><strong>3. Terminal functionality</strong></li> | ||
48 | <li><a href="../topics/CHANGELOG.md.html">CHANGELOG</a></li> | ||
49 | <li><a href="../topics/LICENSE.md.html">MIT License</a></li> | ||
50 | </ul> | ||
51 | <h2>Modules</h2> | ||
52 | <ul class="nowrap"> | ||
53 | <li><a href="../modules/system.html">system</a></li> | ||
54 | </ul> | ||
55 | <h2>Classes</h2> | ||
56 | <ul class="nowrap"> | ||
57 | <li><a href="../classes/bitflags.html">bitflags</a></li> | ||
58 | </ul> | ||
59 | <h2>Examples</h2> | ||
60 | <ul class="nowrap"> | ||
61 | <li><a href="../examples/compat.lua.html">compat.lua</a></li> | ||
62 | <li><a href="../examples/flag_debugging.lua.html">flag_debugging.lua</a></li> | ||
63 | <li><a href="../examples/password_input.lua.html">password_input.lua</a></li> | ||
64 | <li><a href="../examples/read.lua.html">read.lua</a></li> | ||
65 | <li><a href="../examples/readline.lua.html">readline.lua</a></li> | ||
66 | <li><a href="../examples/spinner.lua.html">spinner.lua</a></li> | ||
67 | <li><a href="../examples/spiral_snake.lua.html">spiral_snake.lua</a></li> | ||
68 | <li><a href="../examples/terminalsize.lua.html">terminalsize.lua</a></li> | ||
69 | </ul> | ||
70 | |||
71 | </div> | ||
72 | |||
73 | <div id="content"> | ||
74 | |||
75 | |||
76 | <h1>3. Terminal functionality</h1> | ||
77 | |||
78 | <p>Terminals are fundamentally different on Windows and Posix. So even though | ||
79 | <code>luasystem</code> provides primitives to manipulate both the Windows and Posix terminals, | ||
80 | the user will still have to write platform specific code.</p> | ||
81 | |||
82 | <p>To mitigate this a little, all functions are available on all platforms. They just | ||
83 | will be a no-op if invoked on another platform. This means that no platform specific | ||
84 | branching is required (but still possible) in user code. The user must simply set | ||
85 | up both platforms to make it work.</p> | ||
86 | |||
87 | <p><a name="3_1_Backup_and_Restore_terminal_settings"></a></p> | ||
88 | <h2>3.1 Backup and Restore terminal settings</h2> | ||
89 | |||
90 | <p>Since there are a myriad of settings available;</p> | ||
91 | |||
92 | <ul> | ||
93 | <li><a href="../modules/system.html#setconsoleflags">system.setconsoleflags</a> (Windows)</li> | ||
94 | <li><a href="../modules/system.html#setconsolecp">system.setconsolecp</a> (Windows)</li> | ||
95 | <li><a href="../modules/system.html#setconsoleoutputcp">system.setconsoleoutputcp</a> (Windows)</li> | ||
96 | <li><a href="../modules/system.html#setnonblock">system.setnonblock</a> (Posix)</li> | ||
97 | <li><a href="../modules/system.html#tcsetattr">system.tcsetattr</a> (Posix)</li> | ||
98 | </ul> | ||
99 | |||
100 | <p>Some helper functions are available to backup and restore them all at once. | ||
101 | See <code>termbackup</code>, <code>termrestore</code>, <code>autotermrestore</code> and <code>termwrap</code>.</p> | ||
102 | |||
103 | |||
104 | <p><a name="3_1_Terminal_ANSI_sequences"></a></p> | ||
105 | <h2>3.1 Terminal ANSI sequences</h2> | ||
106 | |||
107 | <p>Windows is catching up with this. In Windows 10 (since 2019), the Windows Terminal application (not to be | ||
108 | mistaken for the <code>cmd</code> console application) supports ANSI sequences. However this | ||
109 | might not be enabled by default.</p> | ||
110 | |||
111 | <p>ANSI processing can be set up both on the input (key sequences, reading cursor position) | ||
112 | as well as on the output (setting colors and cursor shapes).</p> | ||
113 | |||
114 | <p>To enable it use <a href="../modules/system.html#setconsoleflags">system.setconsoleflags</a> like this:</p> | ||
115 | |||
116 | |||
117 | <pre> | ||
118 | <span class="comment">-- setup Windows console to handle ANSI processing on output | ||
119 | </span>sys.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdout, sys.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdout) + sys.COF_VIRTUAL_TERMINAL_PROCESSING) | ||
120 | sys.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stderr, sys.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stderr) + sys.COF_VIRTUAL_TERMINAL_PROCESSING) | ||
121 | |||
122 | <span class="comment">-- setup Windows console to handle ANSI processing on input | ||
123 | </span>sys.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdin, sys.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdin) + sys.CIF_VIRTUAL_TERMINAL_INPUT) | ||
124 | </pre> | ||
125 | |||
126 | <p><a name="3_2_UTF_8_in_output_and_display_width"></a></p> | ||
127 | <h2>3.2 UTF-8 in/output and display width</h2> | ||
128 | |||
129 | <h3>3.2.1 UTF-8 in/output</h3> | ||
130 | |||
131 | <p>Where (most) Posix systems use UTF-8 by default, Windows internally uses UTF-16. More | ||
132 | recent versions of Lua also have UTF-8 support. So <code>luasystem</code> also focusses on UTF-8.</p> | ||
133 | |||
134 | <p>On Windows UTF-8 output can be enabled by setting the output codepage like this:</p> | ||
135 | |||
136 | |||
137 | <pre> | ||
138 | <span class="comment">-- setup Windows output codepage to UTF-8 | ||
139 | </span>sys.<span class="function-name">setconsoleoutputcp</span>(sys.CODEPAGE_UTF8) | ||
140 | </pre> | ||
141 | |||
142 | <p>Terminal input is handled by the <a href="https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/getchar-getwchar"><code>_getwchar()</code></a> function on Windows which returns | ||
143 | UTF-16 surrogate pairs. <code>luasystem</code> will automatically convert those to UTF-8. | ||
144 | So when using <code>readkey</code> or <code>readansi</code> to read keyboard input no additional changes | ||
145 | are required.</p> | ||
146 | |||
147 | <h3>3.2.2 UTF-8 display width</h3> | ||
148 | |||
149 | <p>Typical western characters and symbols are single width characters and will use only | ||
150 | a single column when displayed on a terminal. However many characters from other | ||
151 | languages/cultures or emojis require 2 columns for display.</p> | ||
152 | |||
153 | <p>Typically the <code>wcwidth</code> function is used on Posix to check the number of columns | ||
154 | required for display. However since Windows doesn't provide this functionality a | ||
155 | custom implementation is included based on <a href="http://www.cl.cam.ac.uk/~mgk25/ucs/wcwidth.c">the work by Markus Kuhn</a>.</p> | ||
156 | |||
157 | <p>2 functions are provided, <a href="../modules/system.html#utf8cwidth">system.utf8cwidth</a> for a single character, and <a href="../modules/system.html#utf8swidth">system.utf8swidth</a> for | ||
158 | a string. When writing terminal applications the display width is relevant to | ||
159 | positioning the cursor properly. For an example see the <a href="../examples/readline.lua.html"><code>examples/readline.lua</code></a> file.</p> | ||
160 | |||
161 | |||
162 | <p><a name="3_3_reading_keyboard_input"></a></p> | ||
163 | <h2>3.3 reading keyboard input</h2> | ||
164 | |||
165 | <h3>3.3.1 Non-blocking</h3> | ||
166 | |||
167 | <p>There are 2 functions for keyboard input (actually 3, if taking <a href="../modules/system.html#_readkey">system._readkey</a> into | ||
168 | account): <code>readkey</code> and <code>readansi</code>.</p> | ||
169 | |||
170 | <p><code>readkey</code> is a low level function and should preferably not be used, it returns | ||
171 | a byte at a time, and hence can leave stray/invalid byte sequences in the buffer if | ||
172 | only the start of a UTF-8 or ANSI sequence is consumed.</p> | ||
173 | |||
174 | <p>The preferred way is to use <code>readansi</code> which will parse and return entire characters in | ||
175 | single or multiple bytes, or a full ANSI sequence.</p> | ||
176 | |||
177 | <p>On Windows the input is read using <a href="https://learn.microsoft.com/en-us/cpp/c-runtime-library/reference/getchar-getwchar"><code>_getwchar()</code></a> which bypasses the terminal and reads | ||
178 | the input directly from the keyboard buffer. This means however that the character is | ||
179 | also not being echoed to the terminal (independent of the echo settings used with | ||
180 | <a href="../modules/system.html#setconsoleflags">system.setconsoleflags</a>).</p> | ||
181 | |||
182 | <p>On Posix the traditional file approach is used, which:</p> | ||
183 | |||
184 | <ul> | ||
185 | <li>is blocking by default</li> | ||
186 | <li>echoes input to the terminal</li> | ||
187 | <li>requires enter to be pressed to pass the input (canonical mode)</li> | ||
188 | </ul> | ||
189 | |||
190 | <p>To use non-blocking input here's how to set it up:</p> | ||
191 | |||
192 | |||
193 | <pre> | ||
194 | <span class="comment">-- setup Windows console to disable echo and line input (not required since _getwchar is used, just for consistency) | ||
195 | </span>sys.<span class="function-name">setconsoleflags</span>(<span class="global">io</span>.stdin, sys.<span class="function-name">getconsoleflags</span>(<span class="global">io</span>.stdin) - sys.CIF_ECHO_INPUT - sys.CIF_LINE_INPUT) | ||
196 | |||
197 | <span class="comment">-- setup Posix by disabling echo, canonical mode, and making non-blocking | ||
198 | </span><span class="keyword">local</span> of_attr = sys.<span class="function-name">tcgetattr</span>(<span class="global">io</span>.stdin) | ||
199 | sys.<span class="function-name">tcsetattr</span>(<span class="global">io</span>.stdin, sys.TCSANOW, { | ||
200 | lflag = of_attr.lflag - sys.L_ICANON - sys.L_ECHO, | ||
201 | }) | ||
202 | sys.<span class="function-name">setnonblock</span>(<span class="global">io</span>.stdin, <span class="keyword">true</span>) | ||
203 | </pre> | ||
204 | |||
205 | <p>Both functions require a timeout to be provided which allows for proper asynchronous | ||
206 | code to be written. Since the underlying sleep method used is <a href="../modules/system.html#sleep">system.sleep</a>, just patching | ||
207 | that function with a coroutine based yielding one should be all that is needed to make | ||
208 | the result work with asynchroneous coroutine schedulers.</p> | ||
209 | |||
210 | <h3>3.3.2 Blocking input</h3> | ||
211 | |||
212 | <p>When using traditional input method like <code>io.stdin:read()</code> (which is blocking) the echo | ||
213 | and newline properties should be set on Windows similar to Posix. | ||
214 | For an example see <a href="../examples/password_input.lua.html"><code>examples/password_input.lua</code></a>.</p> | ||
215 | |||
216 | |||
217 | </div> <!-- id="content" --> | ||
218 | </div> <!-- id="main" --> | ||
219 | <div id="about"> | ||
220 | <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i> | ||
221 | <i style="float:right;">Last updated 2024-06-20 23:11:37 </i> | ||
222 | </div> <!-- id="about" --> | ||
223 | </div> <!-- id="container" --> | ||
224 | </body> | ||
225 | </html> | ||
diff --git a/docs/topics/CHANGELOG.md.html b/docs/topics/CHANGELOG.md.html index 4e656c7..da8ddde 100644 --- a/docs/topics/CHANGELOG.md.html +++ b/docs/topics/CHANGELOG.md.html | |||
@@ -27,6 +27,10 @@ | |||
27 | <h1>Lua-System</h1> | 27 | <h1>Lua-System</h1> |
28 | 28 | ||
29 | 29 | ||
30 | <ul> | ||
31 | <li><a href="../index.html">Index</a></li> | ||
32 | </ul> | ||
33 | |||
30 | <h2>Contents</h2> | 34 | <h2>Contents</h2> |
31 | <ul> | 35 | <ul> |
32 | <li><a href="#Versioning">Versioning </a></li> | 36 | <li><a href="#Versioning">Versioning </a></li> |
@@ -37,12 +41,29 @@ | |||
37 | <h2>Topics</h2> | 41 | <h2>Topics</h2> |
38 | <ul class=""> | 42 | <ul class=""> |
39 | <li><a href="../topics/01-introduction.md.html">1. Introduction</a></li> | 43 | <li><a href="../topics/01-introduction.md.html">1. Introduction</a></li> |
44 | <li><a href="../topics/02-development.md.html">2. Development</a></li> | ||
45 | <li><a href="../topics/03-terminal.md.html">3. Terminal functionality</a></li> | ||
40 | <li><strong>CHANGELOG</strong></li> | 46 | <li><strong>CHANGELOG</strong></li> |
41 | <li><a href="../topics/LICENSE.md.html">MIT License</a></li> | 47 | <li><a href="../topics/LICENSE.md.html">MIT License</a></li> |
42 | </ul> | 48 | </ul> |
43 | <h2>Modules</h2> | 49 | <h2>Modules</h2> |
44 | <ul class="nowrap"> | 50 | <ul class="nowrap"> |
45 | <li><a href="../index.html">system</a></li> | 51 | <li><a href="../modules/system.html">system</a></li> |
52 | </ul> | ||
53 | <h2>Classes</h2> | ||
54 | <ul class="nowrap"> | ||
55 | <li><a href="../classes/bitflags.html">bitflags</a></li> | ||
56 | </ul> | ||
57 | <h2>Examples</h2> | ||
58 | <ul class="nowrap"> | ||
59 | <li><a href="../examples/compat.lua.html">compat.lua</a></li> | ||
60 | <li><a href="../examples/flag_debugging.lua.html">flag_debugging.lua</a></li> | ||
61 | <li><a href="../examples/password_input.lua.html">password_input.lua</a></li> | ||
62 | <li><a href="../examples/read.lua.html">read.lua</a></li> | ||
63 | <li><a href="../examples/readline.lua.html">readline.lua</a></li> | ||
64 | <li><a href="../examples/spinner.lua.html">spinner.lua</a></li> | ||
65 | <li><a href="../examples/spiral_snake.lua.html">spiral_snake.lua</a></li> | ||
66 | <li><a href="../examples/terminalsize.lua.html">terminalsize.lua</a></li> | ||
46 | </ul> | 67 | </ul> |
47 | 68 | ||
48 | </div> | 69 | </div> |
@@ -86,15 +107,31 @@ | |||
86 | <p><a name="Version_history"></a></p> | 107 | <p><a name="Version_history"></a></p> |
87 | <h2>Version history</h2> | 108 | <h2>Version history</h2> |
88 | 109 | ||
110 | <h3>Version 0.4.0, released 20-Jun-2024</h3> | ||
111 | |||
112 | <ul> | ||
113 | <li>Feat: <code>getconsoleflags</code> and <code>setconsoleflags</code> for getting/setting the current console configuration flags on Windows</li> | ||
114 | <li>Feat: <code>getconsolecp</code> and <code>setconsolecp</code> for getting/setting the console codepage on Windows</li> | ||
115 | <li>Feat: <code>getconsoleoutputcp</code> and <code>setconsoleoutputcp</code> for getting/setting the console output codepage on Windows</li> | ||
116 | <li>Feat: <code>tcgetattr</code> and <code>tcsetattr</code> for getting/setting the current console configuration flags on Posix</li> | ||
117 | <li>Feat: <code>getnonblock</code> and <code>setnonblock</code> for getting/setting the non-blocking flag on Posix</li> | ||
118 | <li>Feat: <a href="../classes/bitflags.html#">bitflags</a>: a support feature for the above flag type controls to facilitate bit manipulation without resorting to binary operations (to also support PuC Lua 5.1)</li> | ||
119 | <li>Feat: <code>readkey</code> reads a keyboard input from <code>stdin</code> in a non-blocking way (utf8, also on Windows)</li> | ||
120 | <li>Feat: <code>readansi</code> reads a keyboard input from <code>stdin</code> in a non-blocking way, parses ansi and utf8 sequences</li> | ||
121 | <li>Feat: <code>termsize</code> gets the current terminal size in rows and columns</li> | ||
122 | <li>Feat: <code>utf8cwidth</code> and <code>utf8swidth</code> for getting the display width (in columns) of respectively a single utf8 character, or a utf8 string</li> | ||
123 | <li>Feat: helpers; <code>termbackup</code>, <code>termrestore</code>, <code>autotermrestore</code>, and <code>termwrap</code> for managing the many terminal settings on all platforms.</li> | ||
124 | </ul> | ||
125 | |||
89 | <h3>Version 0.3.0, released 15-Dec-2023</h3> | 126 | <h3>Version 0.3.0, released 15-Dec-2023</h3> |
90 | 127 | ||
91 | <ul> | 128 | <ul> |
92 | <li>Feat: on Windows <a href="../index.html#sleep">sleep</a> now has a precision parameter</li> | 129 | <li>Feat: on Windows <code>sleep</code> now has a precision parameter</li> |
93 | <li>Feat: <a href="../index.html#setenv">setenv</a> added to set environment variables.</li> | 130 | <li>Feat: <code>setenv</code> added to set environment variables.</li> |
94 | <li>Feat: <a href="../index.html#getenvs">getenvs</a> added to list environment variables.</li> | 131 | <li>Feat: <code>getenvs</code> added to list environment variables.</li> |
95 | <li>Feat: <a href="../index.html#getenv">getenv</a> added to get environment variable previously set (Windows).</li> | 132 | <li>Feat: <code>getenv</code> added to get environment variable previously set (Windows).</li> |
96 | <li>Feat: <a href="../index.html#random">random</a> added to return high-quality random bytes</li> | 133 | <li>Feat: <code>random</code> added to return high-quality random bytes</li> |
97 | <li>Feat: <a href="../index.html#isatty">isatty</a> added to check if a file-handle is a tty</li> | 134 | <li>Feat: <code>isatty</code> added to check if a file-handle is a tty</li> |
98 | </ul> | 135 | </ul> |
99 | 136 | ||
100 | <h3>Version 0.2.1, released 02-Oct-2016</h3> | 137 | <h3>Version 0.2.1, released 02-Oct-2016</h3> |
@@ -113,8 +150,8 @@ | |||
113 | </div> <!-- id="content" --> | 150 | </div> <!-- id="content" --> |
114 | </div> <!-- id="main" --> | 151 | </div> <!-- id="main" --> |
115 | <div id="about"> | 152 | <div id="about"> |
116 | <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i> | 153 | <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i> |
117 | <i style="float:right;">Last updated 2023-12-15 13:15:09 </i> | 154 | <i style="float:right;">Last updated 2024-06-20 23:11:37 </i> |
118 | </div> <!-- id="about" --> | 155 | </div> <!-- id="about" --> |
119 | </div> <!-- id="container" --> | 156 | </div> <!-- id="container" --> |
120 | </body> | 157 | </body> |
diff --git a/docs/topics/LICENSE.md.html b/docs/topics/LICENSE.md.html index de3eeff..9866af5 100644 --- a/docs/topics/LICENSE.md.html +++ b/docs/topics/LICENSE.md.html | |||
@@ -27,17 +27,38 @@ | |||
27 | <h1>Lua-System</h1> | 27 | <h1>Lua-System</h1> |
28 | 28 | ||
29 | 29 | ||
30 | <ul> | ||
31 | <li><a href="../index.html">Index</a></li> | ||
32 | </ul> | ||
33 | |||
30 | 34 | ||
31 | 35 | ||
32 | <h2>Topics</h2> | 36 | <h2>Topics</h2> |
33 | <ul class=""> | 37 | <ul class=""> |
34 | <li><a href="../topics/01-introduction.md.html">1. Introduction</a></li> | 38 | <li><a href="../topics/01-introduction.md.html">1. Introduction</a></li> |
39 | <li><a href="../topics/02-development.md.html">2. Development</a></li> | ||
40 | <li><a href="../topics/03-terminal.md.html">3. Terminal functionality</a></li> | ||
35 | <li><a href="../topics/CHANGELOG.md.html">CHANGELOG</a></li> | 41 | <li><a href="../topics/CHANGELOG.md.html">CHANGELOG</a></li> |
36 | <li><strong>MIT License</strong></li> | 42 | <li><strong>MIT License</strong></li> |
37 | </ul> | 43 | </ul> |
38 | <h2>Modules</h2> | 44 | <h2>Modules</h2> |
39 | <ul class="nowrap"> | 45 | <ul class="nowrap"> |
40 | <li><a href="../index.html">system</a></li> | 46 | <li><a href="../modules/system.html">system</a></li> |
47 | </ul> | ||
48 | <h2>Classes</h2> | ||
49 | <ul class="nowrap"> | ||
50 | <li><a href="../classes/bitflags.html">bitflags</a></li> | ||
51 | </ul> | ||
52 | <h2>Examples</h2> | ||
53 | <ul class="nowrap"> | ||
54 | <li><a href="../examples/compat.lua.html">compat.lua</a></li> | ||
55 | <li><a href="../examples/flag_debugging.lua.html">flag_debugging.lua</a></li> | ||
56 | <li><a href="../examples/password_input.lua.html">password_input.lua</a></li> | ||
57 | <li><a href="../examples/read.lua.html">read.lua</a></li> | ||
58 | <li><a href="../examples/readline.lua.html">readline.lua</a></li> | ||
59 | <li><a href="../examples/spinner.lua.html">spinner.lua</a></li> | ||
60 | <li><a href="../examples/spiral_snake.lua.html">spiral_snake.lua</a></li> | ||
61 | <li><a href="../examples/terminalsize.lua.html">terminalsize.lua</a></li> | ||
41 | </ul> | 62 | </ul> |
42 | 63 | ||
43 | </div> | 64 | </div> |
@@ -47,7 +68,7 @@ | |||
47 | 68 | ||
48 | <h1>MIT License</h1> | 69 | <h1>MIT License</h1> |
49 | 70 | ||
50 | <h3>Copyright (c) 2016-2023 Oscar Lim</h3> | 71 | <h3>Copyright (c) 2016-2024 Oscar Lim</h3> |
51 | 72 | ||
52 | <p>Permission is hereby granted, free of charge, to any person obtaining a copy of | 73 | <p>Permission is hereby granted, free of charge, to any person obtaining a copy of |
53 | this software and associated documentation files (the "Software"), to deal in | 74 | this software and associated documentation files (the "Software"), to deal in |
@@ -71,8 +92,8 @@ SOFTWARE.</p> | |||
71 | </div> <!-- id="content" --> | 92 | </div> <!-- id="content" --> |
72 | </div> <!-- id="main" --> | 93 | </div> <!-- id="main" --> |
73 | <div id="about"> | 94 | <div id="about"> |
74 | <i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.6</a></i> | 95 | <i>generated by <a href="http://github.com/lunarmodules/LDoc">LDoc 1.5.0</a></i> |
75 | <i style="float:right;">Last updated 2023-12-15 13:15:09 </i> | 96 | <i style="float:right;">Last updated 2024-06-20 23:11:37 </i> |
76 | </div> <!-- id="about" --> | 97 | </div> <!-- id="about" --> |
77 | </div> <!-- id="container" --> | 98 | </div> <!-- id="container" --> |
78 | </body> | 99 | </body> |
diff --git a/rockspecs/luasystem-0.4.0-1.rockspec b/rockspecs/luasystem-0.4.0-1.rockspec new file mode 100644 index 0000000..d35565d --- /dev/null +++ b/rockspecs/luasystem-0.4.0-1.rockspec | |||
@@ -0,0 +1,85 @@ | |||
1 | local package_name = "luasystem" | ||
2 | local package_version = "0.4.0" | ||
3 | local rockspec_revision = "1" | ||
4 | local github_account_name = "lunarmodules" | ||
5 | local github_repo_name = "luasystem" | ||
6 | |||
7 | |||
8 | package = package_name | ||
9 | version = package_version.."-"..rockspec_revision | ||
10 | |||
11 | source = { | ||
12 | url = "git+https://github.com/"..github_account_name.."/"..github_repo_name..".git", | ||
13 | branch = (package_version == "scm") and "master" or nil, | ||
14 | tag = (package_version ~= "scm") and "v"..package_version or nil, | ||
15 | } | ||
16 | |||
17 | description = { | ||
18 | summary = 'Platform independent system calls for Lua.', | ||
19 | detailed = [[ | ||
20 | Adds a Lua API for making platform independent system calls. | ||
21 | ]], | ||
22 | license = 'MIT <http://opensource.org/licenses/MIT>', | ||
23 | homepage = "https://github.com/"..github_account_name.."/"..github_repo_name, | ||
24 | } | ||
25 | |||
26 | dependencies = { | ||
27 | 'lua >= 5.1', | ||
28 | } | ||
29 | |||
30 | local function make_platform(plat) | ||
31 | local defines = { | ||
32 | linux = { }, | ||
33 | unix = { }, | ||
34 | macosx = { }, | ||
35 | win32 = { "WINVER=0x0600", "_WIN32_WINNT=0x0600" }, | ||
36 | mingw32 = { "WINVER=0x0600", "_WIN32_WINNT=0x0600" }, | ||
37 | } | ||
38 | local libraries = { | ||
39 | linux = { "rt" }, | ||
40 | unix = { }, | ||
41 | macosx = { }, | ||
42 | win32 = { "advapi32", "winmm" }, | ||
43 | mingw32 = { }, | ||
44 | } | ||
45 | local libdirs = { | ||
46 | linux = nil, | ||
47 | unix = nil, | ||
48 | macosx = nil, | ||
49 | win32 = nil, | ||
50 | mingw32 = { }, | ||
51 | } | ||
52 | return { | ||
53 | modules = { | ||
54 | ['system.core'] = { | ||
55 | sources = { | ||
56 | 'src/core.c', | ||
57 | 'src/compat.c', | ||
58 | 'src/time.c', | ||
59 | 'src/environment.c', | ||
60 | 'src/random.c', | ||
61 | 'src/term.c', | ||
62 | 'src/bitflags.c', | ||
63 | 'src/wcwidth.c', | ||
64 | }, | ||
65 | defines = defines[plat], | ||
66 | libraries = libraries[plat], | ||
67 | libdirs = libdirs[plat], | ||
68 | }, | ||
69 | }, | ||
70 | } | ||
71 | end | ||
72 | |||
73 | build = { | ||
74 | type = 'builtin', | ||
75 | platforms = { | ||
76 | linux = make_platform('linux'), | ||
77 | unix = make_platform('unix'), | ||
78 | macosx = make_platform('macosx'), | ||
79 | win32 = make_platform('win32'), | ||
80 | mingw32 = make_platform('mingw32'), | ||
81 | }, | ||
82 | modules = { | ||
83 | ['system.init'] = 'system/init.lua', | ||
84 | }, | ||
85 | } | ||
@@ -4,7 +4,7 @@ | |||
4 | #include <lua.h> | 4 | #include <lua.h> |
5 | #include <lauxlib.h> | 5 | #include <lauxlib.h> |
6 | 6 | ||
7 | #define LUASYSTEM_VERSION "LuaSystem 0.3.0" | 7 | #define LUASYSTEM_VERSION "LuaSystem 0.4.0" |
8 | 8 | ||
9 | #ifdef _WIN32 | 9 | #ifdef _WIN32 |
10 | #define LUAEXPORT __declspec(dllexport) | 10 | #define LUAEXPORT __declspec(dllexport) |
@@ -26,6 +26,9 @@ LUAEXPORT int luaopen_system_core(lua_State *L) { | |||
26 | lua_pushstring(L, "_VERSION"); | 26 | lua_pushstring(L, "_VERSION"); |
27 | lua_pushstring(L, LUASYSTEM_VERSION); | 27 | lua_pushstring(L, LUASYSTEM_VERSION); |
28 | lua_rawset(L, -3); | 28 | lua_rawset(L, -3); |
29 | |||
30 | /// Flag to identify Windows. | ||
31 | // @field windows `true` if on Windows, `false` otherwise. | ||
29 | lua_pushstring(L, "windows"); | 32 | lua_pushstring(L, "windows"); |
30 | #ifdef _WIN32 | 33 | #ifdef _WIN32 |
31 | lua_pushboolean(L, 1); | 34 | lua_pushboolean(L, 1); |