3 |
2 |
3 |
9 | 
10 |
56 | 
57 |
`**: runs `code` (useful to disambiguate from debugger commands)
102 | - **`depth `**: set depth limit and number of items when pretty printing values
103 | - **`exit`**: quit
104 | - **`where []`**: prints `` or `conf.whereRows` rows around the current line. Is ran for you each time you step in the code or change frame context
105 |
106 |
107 | 
108 |
109 |
110 | - **`trace`**: prints current stack trace and highlights current frame.
111 |
112 |
113 | 
114 |
115 |
116 | ## Caveats
117 |
118 | - Pretty printing values can be expensive in CPU and memory: avoid dumping either large of deeply nested tables. You can play with the `dump.depthLimit` and `dump.itemsLimit` value in your `~/.croissantrc` or the `depth` command to avoid exploring to far down in complex tables.
119 | - The debugger will slow your program down. Croissant will try and clear hooks whenever possible but if you know you won't hit anymore breakpoints, do a `clear` before doing `continue`.
120 | - A breakpoint on a function name will not work if the function is not called by its name in your code. Example:
121 |
122 | ```lua
123 | local function stopMe()
124 | -- ...
125 | end
126 |
127 | local function call(fn)
128 | fn()
129 | end
130 |
131 | call(stopMe)
132 | ```
133 |
134 | ## Configuration
135 |
136 | You can customize some aspect of croissant by writing a `~/.croissantrc` lua file. Here are the default values than you can overwrite:
137 |
138 | ```lua
139 | return {
140 | -- Default prompt
141 | prompt = "→ ",
142 | -- Prompt used when editing multiple lines of code
143 | continuationPrompt = ".... ",
144 |
145 | -- Maximum amount of remembered lines
146 | -- Croissant manages two history file: one for the repl (~/.croissant_history),
147 | -- one for the debugger (~/.croissant_debugger_history)
148 | historyLimit = 1000,
149 |
150 | -- How many rows `where` should print around the current line
151 | whereRows = 4,
152 |
153 | -- Syntax highlighting colors
154 | -- Available colors are: black, red, green, yellow, blue, magenta, cyan, white.
155 | -- They can also be combined with modifiers: bright, dim, underscore, blink, reverse, hidden
156 | syntaxColors = {
157 | constant = { "bright", "yellow" },
158 | string = { "green" },
159 | comment = { "dim", "cyan" },
160 | number = { "yellow" },
161 | operator = { "yellow" },
162 | keywords = { "bright", "magenta" },
163 | identifier = { "blue" },
164 | },
165 |
166 | dump = {
167 | -- Nesting limit at which croissant will stop when pretty printing a table
168 | depthLimit = 5,
169 | -- If a table has more items than itemsLimit, will stop there and print ellipsis
170 | itemsLimit = 30
171 | }
172 | }
173 | ```
174 |
175 | ## Löve 2D
176 |
177 | Read and understand the [**Caveats**](#caveats) section.
178 |
179 | ```bash
180 | luarocks install croissant --tree mygame/lua_modules
181 | ```
182 |
183 | Tell Löve to search in `lua_modules`:
184 |
185 | ```lua
186 | love.filesystem.setRequirePath(
187 | love.filesystem.getRequirePath()
188 | .. ";lua_modules/share/lua/5.1/?/init.lua"
189 | .. ";lua_modules/share/lua/5.1/?.lua"
190 | )
191 |
192 | love.filesystem.setCRequirePath(
193 | love.filesystem.getCRequirePath()
194 | .. ";lua_modules/lib/lua/5.1/?.so"
195 | )
196 | ```
197 |
198 | Require `croissant.debugger` where you want to break:
199 |
200 | ```lua
201 | require "croissant.debugger"()
202 | ```
203 |
--------------------------------------------------------------------------------
/assets/debugger-trace.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/giann/croissant/dc633a0ac3b5bcab9b72b660e926af80944125b3/assets/debugger-trace.png
--------------------------------------------------------------------------------
/assets/debugger-where.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/giann/croissant/dc633a0ac3b5bcab9b72b660e926af80944125b3/assets/debugger-where.png
--------------------------------------------------------------------------------
/assets/debugger.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/giann/croissant/dc633a0ac3b5bcab9b72b660e926af80944125b3/assets/debugger.gif
--------------------------------------------------------------------------------
/assets/logo.gvdesign:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/giann/croissant/dc633a0ac3b5bcab9b72b660e926af80944125b3/assets/logo.gvdesign
--------------------------------------------------------------------------------
/assets/logo.png:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/giann/croissant/dc633a0ac3b5bcab9b72b660e926af80944125b3/assets/logo.png
--------------------------------------------------------------------------------
/assets/repl.gif:
--------------------------------------------------------------------------------
https://raw.githubusercontent.com/giann/croissant/dc633a0ac3b5bcab9b72b660e926af80944125b3/assets/repl.gif
--------------------------------------------------------------------------------
/bin/croissant:
--------------------------------------------------------------------------------
1 | #!/usr/bin/env lua
2 |
3 | require "compat53"
4 |
5 | local colors = require "term.colors"
6 | local argparse = require "argparse"
7 | local cdo = require "croissant.do"
8 |
9 | local parseArgument = function()
10 | local parser = argparse()
11 | :name "croissant"
12 | :description "A Lua REPL and debugger"
13 |
14 | parser:argument "input"
15 | :description "A lua file to run or debug"
16 | :args "?"
17 |
18 | parser:argument "arguments"
19 | :description "Arguments to pass to "
20 | :args "*"
21 |
22 | parser:option "-d --debugger -b --break"
23 | :description "Run croissant in debugger mode"
24 | :args "*"
25 |
26 | return parser:parse()
27 | end
28 |
29 | local route = function(arguments)
30 | -- If breakpoint defined, enter debugger mode
31 | local breakpointsStr = arguments["debugger"]
32 | local breakpoints = {}
33 |
34 | if breakpointsStr and arguments.input then
35 | for _, breakpoint in ipairs(breakpointsStr) do
36 | local source, line = breakpoint:match "^([^:]*):(%d+)$"
37 |
38 | if source then
39 | breakpoints[source] = breakpoints[source] or {}
40 | breakpoints[source][tonumber(line)] = true
41 | end
42 | end
43 |
44 | require "croissant.debugger"(arguments.input, arguments.arguments, breakpoints, true)
45 | elseif breakpointsStr and not arguments.input then
46 | print(colors.red("Illegal use of --debugger: missing input file"))
47 | return
48 | elseif not breakpointsStr and arguments.input then
49 | cdo.runFile(arguments.input, arguments.arguments)
50 | else
51 | -- Regular REPL
52 | require "croissant.repl"()
53 | end
54 | end
55 |
56 | route(parseArgument())
57 |
--------------------------------------------------------------------------------
/croissant-0.0.1-6.rockspec:
--------------------------------------------------------------------------------
1 |
2 | package = "croissant"
3 | version = "0.0.1-6"
4 | rockspec_format = "3.0"
5 |
6 | source = {
7 | url = "git://github.com/giann/croissant",
8 | }
9 |
10 | description = {
11 | summary = "A Lua REPL implemented in Lua",
12 | homepage = "https://github.com/giann/croissant",
13 | license = "MIT/X11",
14 | }
15 |
16 | build = {
17 | modules = {
18 | ["croissant.repl"] = "croissant/repl.lua",
19 | ["croissant.conf"] = "croissant/conf.lua",
20 | ["croissant.debugger"] = "croissant/debugger.lua",
21 | ["croissant.do"] = "croissant/do.lua",
22 | ["croissant.help"] = "croissant/help.lua",
23 | ["croissant.lexer"] = "croissant/lexer.lua",
24 | ["croissant.luaprompt"] = "croissant/luaprompt.lua",
25 | ["croissant.builtins"] = "croissant/builtins.lua",
26 | },
27 | type = "builtin",
28 | install = {
29 | bin = {
30 | "bin/croissant"
31 | }
32 | }
33 | }
34 |
35 | dependencies = {
36 | "lua >= 5.1",
37 | "sirocco >= 0.0.1-5",
38 | "hump >= 0.4-2",
39 | "lpeg >= 1.0.1-1",
40 | "argparse >= 0.6.0-1",
41 | "compat53 >= 0.7-1",
42 | }
43 |
--------------------------------------------------------------------------------
/croissant/builtins.lua:
--------------------------------------------------------------------------------
1 |
2 | return {
3 | "coroutine.create",
4 | "coroutine.isyieldable",
5 | "coroutine.resume",
6 | "coroutine.running",
7 | "coroutine.status",
8 | "coroutine.wrap",
9 | "coroutine.yield",
10 | "debug.debug",
11 | "debug.gethook",
12 | "debug.getinfo",
13 | "debug.getlocal",
14 | "debug.getmetatable",
15 | "debug.getregistry",
16 | "debug.getupvalue",
17 | "debug.getuservalue",
18 | "debug.sethook",
19 | "debug.setlocal",
20 | "debug.setmetatable",
21 | "debug.setupvalue",
22 | "debug.setuservalue",
23 | "debug.traceback",
24 | "debug.upvalueid",
25 | "debug.upvaluejoin",
26 | "io.close",
27 | "io.flush",
28 | "io.input",
29 | "io.lines",
30 | "io.open",
31 | "io.output",
32 | "io.popen",
33 | "io.read",
34 | "io.stderr",
35 | "io.stdin",
36 | "io.stdout",
37 | "io.tmpfile",
38 | "io.type",
39 | "io.write",
40 | "file:close",
41 | "file:flush",
42 | "file:lines",
43 | "file:read",
44 | "file:seek",
45 | "file:setvbuf",
46 | "file:write",
47 | "math.abs",
48 | "math.acos",
49 | "math.asin",
50 | "math.atan",
51 | "math.ceil",
52 | "math.cos",
53 | "math.deg",
54 | "math.exp",
55 | "math.floor",
56 | "math.fmod",
57 | "math.huge",
58 | "math.log",
59 | "math.max",
60 | "math.maxinteger",
61 | "math.min",
62 | "math.mininteger",
63 | "math.modf",
64 | "math.pi",
65 | "math.rad",
66 | "math.random",
67 | "math.randomseed",
68 | "math.sin",
69 | "math.sqrt",
70 | "math.tan",
71 | "math.tointeger",
72 | "math.type",
73 | "math.ult",
74 | "os.clock",
75 | "os.date",
76 | "os.difftime",
77 | "os.execute",
78 | "os.exit",
79 | "os.getenv",
80 | "os.remove",
81 | "os.rename",
82 | "os.setlocale",
83 | "os.time",
84 | "os.tmpname",
85 | "package.config",
86 | "package.cpath",
87 | "package.loaded",
88 | "package.loadlib",
89 | "package.path",
90 | "package.preload",
91 | "package.searchers",
92 | "package.searchpath",
93 | "string.byte",
94 | "string.char",
95 | "string.dump",
96 | "string.find",
97 | "string.format",
98 | "string.gmatch",
99 | "string.gsub",
100 | "string.len",
101 | "string.lower",
102 | "string.match",
103 | "string.pack",
104 | "string.packsize",
105 | "string.rep",
106 | "string.reverse",
107 | "string.sub",
108 | "string.unpack",
109 | "string.upper",
110 | "table.concat",
111 | "table.insert",
112 | "table.move",
113 | "table.pack",
114 | "table.remove",
115 | "table.sort",
116 | "table.unpack",
117 | "utf8.char",
118 | "utf8.charpattern",
119 | "utf8.codepoint",
120 | "utf8.codes",
121 | "utf8.len",
122 | "utf8.offset",
123 | }
124 |
--------------------------------------------------------------------------------
/croissant/conf.lua:
--------------------------------------------------------------------------------
1 | local colors = require "term.colors"
2 | local char = require "sirocco.char"
3 |
4 | local merge
5 | function merge(t1, t2, seen)
6 | seen = seen or {}
7 | local merged = {}
8 |
9 | seen[t1] = true
10 | seen[t2] = true
11 |
12 | for k, v in pairs(t1) do
13 | merged[k] = v
14 | end
15 |
16 | for k, v in pairs(t2) do
17 | if type(v) == "table" and not seen[v] then
18 | seen[v] = true
19 |
20 | if type(merged[k]) ~= "table" then
21 | merged[k] = {}
22 | end
23 |
24 | merged[k] = merge(merged[k], v, seen)
25 | else
26 | merged[k] = v
27 | end
28 | end
29 |
30 | return merged
31 | end
32 |
33 | local default = {
34 | -- TODO: unused
35 | keybinding = {
36 | command_get_next_history = {
37 | "key_down",
38 | "C-n",
39 | },
40 |
41 | command_get_previous_history = {
42 | "key_up",
43 | "C-p",
44 | },
45 |
46 | command_exit = {
47 | "C-c"
48 | },
49 |
50 | command_abort = {
51 | "C-g"
52 | },
53 |
54 | command_help = {
55 | "C- ",
56 | "M- ",
57 | },
58 | },
59 |
60 | prompt = "→ ",
61 | continuationPrompt = ".... ",
62 |
63 | historyLimit = 1000,
64 |
65 | whereRows = 4,
66 |
67 | syntaxColors = {
68 | constant = { "bright", "yellow" },
69 | string = { "green" },
70 | comment = { "dim", "cyan" },
71 | number = { "yellow" },
72 | operator = { "yellow" },
73 | keywords = { "bright", "magenta" },
74 | identifier = { "blue" },
75 | builtin = { "bright", "underscore", "green" }
76 | },
77 |
78 | help = "croissant.help",
79 |
80 | dump = {
81 | depthLimit = 5,
82 | itemsLimit = 30
83 | }
84 | }
85 |
86 | -- Read from ~/.croissantrc
87 | local user = {}
88 | local file, _ = io.open(os.getenv "HOME" .. "/.croissantrc", "r")
89 |
90 | if file then
91 | local rc = file:read("*all")
92 |
93 | file:close()
94 |
95 | rc = load(rc) or load("return " .. rc)
96 |
97 | if rc then
98 | user = rc()
99 | end
100 | end
101 |
102 | -- Merge default and user
103 | local conf = merge(default, user)
104 |
105 | -- Convert colors to escape codes
106 | for k, v in pairs(conf.syntaxColors) do
107 | local color = ""
108 |
109 | for _, c in ipairs(v) do
110 | color = color .. colors[c]
111 | end
112 |
113 | conf.syntaxColors[k] = color
114 | end
115 |
116 | -- Convert keybding to escape codes
117 | for command, bindings in pairs(conf.keybinding) do
118 | local bds = {}
119 |
120 | for _, key in ipairs(bindings) do
121 | local prefix, suffix = key:match "^([CM])-(.*)"
122 |
123 | if prefix then
124 | table.insert(bds, char[prefix](suffix))
125 | else
126 | table.insert(bds, key)
127 | end
128 | end
129 |
130 | conf.keybinding[command] = bds
131 | end
132 |
133 | return conf
134 |
--------------------------------------------------------------------------------
/croissant/debugger.lua:
--------------------------------------------------------------------------------
1 | require "compat53"
2 |
3 | local colors = require "term.colors"
4 | local argparse = require "argparse"
5 | local conf = require "croissant.conf"
6 | local LuaPrompt = require "croissant.luaprompt"
7 | local Lexer = require "croissant.lexer"
8 | local cdo = require "croissant.do"
9 | local runChunk = cdo.runChunk
10 | local frameEnv = cdo.frameEnv
11 | local bindInFrame = cdo.bindInFrame
12 | local banner = cdo.banner
13 | local runFile = cdo.runFile
14 |
15 | local repeatableCommands = {
16 | "continue",
17 | "down",
18 | "next",
19 | "finish",
20 | "step",
21 | "up",
22 | }
23 |
24 | -- Commands allowed when detached
25 | local detachedCommands = {
26 | "args",
27 | "breakpoint",
28 | "clear",
29 | "condition",
30 | "depth",
31 | "delete",
32 | "disable",
33 | "display",
34 | "enable",
35 | "exit",
36 | "help",
37 | "info",
38 | "run",
39 | "undisplay",
40 | "watch",
41 | }
42 |
43 | -- Commands allowed when attached
44 | local attachedCommands = {
45 | "breakpoint",
46 | "clear",
47 | "condition",
48 | "continue",
49 | "depth",
50 | "delete",
51 | "disable",
52 | "display",
53 | "down",
54 | "enable",
55 | "eval",
56 | "exit",
57 | "help",
58 | "info",
59 | "next",
60 | "finish",
61 | "step",
62 | "trace",
63 | "undisplay",
64 | "up",
65 | "watch",
66 | "where",
67 | }
68 |
69 | local commandErrorMessage
70 | local commandsHelp = {}
71 |
72 | local parser = argparse()
73 | parser._name = ""
74 |
75 | local runCommand = parser:command "run r"
76 | :description "Starts your script"
77 |
78 | runCommand._options = {}
79 | commandsHelp.run = runCommand:get_help()
80 |
81 | local argsCommand = parser:command "args a"
82 | :description "Set arguments to pass to your script"
83 | argsCommand:argument "arguments"
84 | :args "+"
85 |
86 | argsCommand._options = {}
87 | commandsHelp.args = argsCommand:get_help()
88 |
89 | local breakpointCommand = parser:command "breakpoint br b"
90 | :description("Add a new breakpoint")
91 | breakpointCommand:argument "where"
92 | :description "Where to break. Function, line number in current file or `file:line`"
93 | :args(1)
94 | breakpointCommand:argument "when"
95 | :description "Break only if this Lua expressions can be evaluated to be true"
96 | :args "*"
97 |
98 | breakpointCommand._options = {}
99 | commandsHelp.breakpoint = breakpointCommand:get_help()
100 |
101 | local watchCommand = parser:command "watch wa"
102 | :description("Add a new watchpoint")
103 | watchCommand:argument "expression"
104 | :description "Break only if this evaluated Lua expression changes value"
105 | :args "+"
106 |
107 | local displayCommand = parser:command "display dp"
108 | :description("Prints expression each time the program stops")
109 | displayCommand:argument "expression"
110 | :description "Lua expression to print"
111 | :args "+"
112 |
113 | displayCommand._options = {}
114 | commandsHelp.display = displayCommand:get_help()
115 |
116 | local undisplayCommand = parser:command "undisplay undp udp"
117 | :description("Removes display")
118 | undisplayCommand:argument "id"
119 | :description "ID of display to remove"
120 | :args(1)
121 |
122 | undisplayCommand._options = {}
123 | commandsHelp.undisplay = undisplayCommand:get_help()
124 |
125 | local conditionCommand = parser:command "condition cond"
126 | :description "Modify breaking condition of a breakpoint"
127 | conditionCommand:argument "id"
128 | :description "Breakpoint ID"
129 | :args(1)
130 | conditionCommand:argument "condition"
131 | :description "New breakpoint condition"
132 | :args "+"
133 |
134 | conditionCommand._options = {}
135 | commandsHelp.condition = conditionCommand:get_help()
136 |
137 | local enableCommand = parser:command "enable en"
138 | :description "Enable a breakpoint"
139 | enableCommand:argument "id"
140 | :description "Breakpoint ID"
141 | :args(1)
142 |
143 | enableCommand._options = {}
144 | commandsHelp.enable = enableCommand:get_help()
145 |
146 | local disableCommand = parser:command "disable dis di"
147 | :description "Disable a breakpoint"
148 | disableCommand:argument "id"
149 | :description "Breakpoint ID"
150 | :args(1)
151 |
152 | disableCommand._options = {}
153 | commandsHelp.disable = disableCommand:get_help()
154 |
155 | local deleteCommand = parser:command "delete del de d"
156 | :description "Delete a breakpoint"
157 | deleteCommand:argument "id"
158 | :description "Breakpoint ID"
159 | :args(1)
160 |
161 | deleteCommand._options = {}
162 | commandsHelp.delete = deleteCommand:get_help()
163 |
164 | local clearCommand = parser:command "clear cl"
165 | :description "Delete all breakpoints, watchpoints and displays"
166 |
167 | clearCommand._options = {}
168 | commandsHelp.clear = clearCommand:get_help()
169 |
170 | local infoCommand = parser:command "info inf i"
171 | :description "Get informations about the debugger state"
172 | infoCommand:argument "about"
173 | :description("`breakpoints` will list breakpoints, "
174 | .. "`locals` will list locals of the current context, "
175 | .. "`displays` will list displays")
176 | :args(1)
177 |
178 | infoCommand._options = {}
179 | commandsHelp.info = infoCommand:get_help()
180 |
181 | local stepCommand = parser:command "step st s"
182 | :description "Step in the code (repeatable)"
183 |
184 | stepCommand._options = {}
185 | commandsHelp.step = stepCommand:get_help()
186 |
187 | local nextCommand = parser:command "next n"
188 | :description "Step in the code without going over any function call (repeatable)"
189 |
190 | nextCommand._options = {}
191 | commandsHelp.next = nextCommand:get_help()
192 |
193 | local finishCommand = parser:command "finish f"
194 | :description "Will break after leaving the current function (repeatable)"
195 |
196 | finishCommand._options = {}
197 | commandsHelp.finish = finishCommand:get_help()
198 |
199 | local upCommand = parser:command "up u"
200 | :description "Go up one frame (repeatable)"
201 |
202 | upCommand._options = {}
203 | commandsHelp.up = upCommand:get_help()
204 |
205 | local downCommand = parser:command "down d"
206 | :description "Go down one frame (repeatable)"
207 |
208 | downCommand._options = {}
209 | commandsHelp.down = downCommand:get_help()
210 |
211 | local continueCommand = parser:command "continue cont c"
212 | :description("Continue until hitting a breakpoint. If no breakpoint are specified,"
213 | .. " clears debug hooks (repeatable)")
214 |
215 | continueCommand._options = {}
216 | commandsHelp.continue = continueCommand:get_help()
217 |
218 | local evalCommand = parser:command "eval ev e"
219 | :description "Evaluates lua code (useful to disambiguate from debugger commands)"
220 | evalCommand:argument "expression"
221 | :description "Lua expression to evaluate"
222 | :args "+"
223 |
224 | evalCommand._options = {}
225 | commandsHelp.eval = evalCommand:get_help()
226 |
227 | local depthCommand = parser:command "depth dep"
228 | :description "Limit depth at which croissant goes to pretty print returned values"
229 | depthCommand:argument "limit"
230 | :description "Depth"
231 | :args(1)
232 | depthCommand:argument "items"
233 | :description "Items"
234 | :args "?"
235 |
236 | depthCommand._options = {}
237 | commandsHelp.depth = depthCommand:get_help()
238 |
239 | local whereCommand = parser:command "where wh w"
240 | :description("Prints code around the current line. Is ran for you each time you step in"
241 | .. " the code or change frame context")
242 | whereCommand:argument "rows"
243 | :description "How many rows to show around the current line"
244 | :args "?"
245 |
246 | whereCommand._options = {}
247 | commandsHelp.where = whereCommand:get_help()
248 |
249 | local traceCommand = parser:command "trace tr t"
250 | :description "Prints current stack trace and highlights current frame"
251 |
252 | traceCommand._options = {}
253 | commandsHelp.trace = traceCommand:get_help()
254 |
255 | local exitCommand = parser:command "exit ex"
256 | :description "Quit"
257 |
258 | exitCommand._options = {}
259 | commandsHelp.exit = exitCommand:get_help()
260 |
261 | local helpCommand = parser:command "help h"
262 | :description "Prints help message"
263 | helpCommand:argument "about"
264 | :description "Command for which you want help"
265 | :args "?"
266 |
267 | helpCommand._options = {}
268 | commandsHelp.help = helpCommand:get_help()
269 |
270 | -- We don't need any
271 | parser._options = {}
272 |
273 | commandsHelp[1] = not commandsHelp[1]
274 | and parser:get_help()
275 | or commandsHelp[1]
276 |
277 | -- If we can't parse it, raise an error instead of os.exit(0)
278 | parser.error = function(self, msg)
279 | commandErrorMessage = msg
280 | error(msg)
281 | end
282 |
283 | local function parseCommands(detached, args)
284 | local ok, parsed = xpcall(parser.parse, function(_)
285 | return commandErrorMessage
286 | end, parser, args)
287 |
288 | if ok then
289 | local keys = {}
290 | for key, _ in pairs(parsed) do
291 | table.insert(keys, key)
292 | end
293 |
294 | -- Zero or one key `about` -> this is help command
295 | if #keys == 0 or (#keys == 1 and keys[1] == "about") then
296 | parsed.help = true
297 | end
298 | end
299 |
300 | return ok, parsed
301 | end
302 |
303 | local function highlight(code)
304 | local lexer = Lexer()
305 | local highlighted = ""
306 |
307 | for kind, text, _ in lexer:tokenize(code) do
308 | highlighted = highlighted
309 | .. (conf.syntaxColors[kind] or "")
310 | .. text
311 | .. colors.reset
312 | end
313 |
314 | return highlighted
315 | end
316 |
317 | return function(script, arguments, breakpoints, fromCli)
318 | arguments = arguments or {}
319 | breakpoints = breakpoints or {}
320 | local displays = {}
321 | local history = cdo.loadDebugHistory()
322 |
323 | local frame = 0
324 | -- When fromCli we don't want to break right away
325 | local frameLimit = not fromCli and -2 or false
326 | local currentFrame = 0
327 |
328 | local lastCommand, commands
329 |
330 | local function breakpointCount()
331 | local count = 0
332 | for _, lines in pairs(breakpoints) do
333 | for _, _ in pairs(lines) do
334 | count = count + 1
335 | end
336 | end
337 |
338 | return count
339 | end
340 |
341 | local function doREPL(detached)
342 | local rframe, fenv, env, rawenv, multiline
343 | while true do
344 | if rframe ~= currentFrame and not detached then
345 | rframe = currentFrame
346 |
347 | commands.where(nil, -1)
348 |
349 | fenv, rawenv = frameEnv(true, currentFrame)
350 | env = setmetatable({}, {
351 | __index = fenv,
352 | __newindex = function(env, name, value)
353 | bindInFrame(8 + currentFrame, name, value, env)
354 | end
355 | })
356 |
357 | -- Print displays
358 | if #displays > 0 then
359 | io.write("\n")
360 | for id, display in ipairs(displays) do
361 | local f = load("return " .. display, "__debugger__", "t", env)
362 | or load(display, "__debugger__", "t", env)
363 |
364 | if not f then
365 | print(colors.red("Display #" .. id .. " expression could not be parsed"))
366 | return
367 | end
368 |
369 | local ok, value = pcall(f)
370 |
371 | io.write(" "
372 | .. id .. ". `"
373 | .. highlight(display) .. "`: ")
374 |
375 | if ok then
376 | cdo.dump(value)
377 | else
378 | io.write("failed with error: " .. colors.red(value))
379 | end
380 | end
381 | io.write("\n\n")
382 | end
383 | elseif detached then
384 | env = _G
385 | rawenv = _G
386 | end
387 |
388 | local prompt = colors.reset
389 | .. "["
390 | .. colors.green(script)
391 | .. "] "
392 | .. (not multiline and conf.prompt or conf.continuationPrompt)
393 |
394 | if not detached then
395 | local info = debug.getinfo(3 + (currentFrame or 0))
396 |
397 | prompt = colors.reset
398 | .. "[" .. currentFrame .. "]"
399 | .. "["
400 | .. colors.green(info.short_src)
401 | .. (info.name and ":" .. colors.blue(info.name) or "")
402 | .. (info.currentline > 0 and ":" .. colors.yellow(info.currentline) or "")
403 | .. "] "
404 | .. (not multiline and conf.prompt or conf.continuationPrompt)
405 | end
406 |
407 | local code = LuaPrompt {
408 | parsing = not detached,
409 | env = rawenv,
410 | prompt = prompt,
411 | multiline = multiline,
412 | history = history,
413 | tokenColors = conf.syntaxColors,
414 | help = require(conf.help),
415 | quit = function() end,
416 | builtins = detached and detachedCommands or attachedCommands
417 | }:ask()
418 |
419 | if code ~= "" and (not history[1] or history[1] ~= code) then
420 | table.insert(history, 1, code)
421 |
422 | cdo.appendToDebugHistory(code)
423 | end
424 |
425 | -- If empty replay previous command
426 | if code == "" then
427 | code = lastCommand
428 | end
429 |
430 | local badCommand
431 | if code and code ~= "" then
432 | -- Is it a command ?
433 | local words = {}
434 | for word in code:gmatch "(%g+)" do
435 | table.insert(words, word)
436 | end
437 |
438 | local ok, parsed = parseCommands(detached, words)
439 | local cmd
440 | if ok then
441 | local allowed = detached and detachedCommands or attachedCommands
442 | for _, command in ipairs(allowed) do
443 | if parsed[command] then
444 | if command == "eval" then
445 | code = table.concat(parsed.expression, " ")
446 | break
447 | end
448 |
449 | local repeatable = false
450 | for _, c in ipairs(repeatableCommands) do
451 | if c == command then
452 | repeatable = true
453 | break
454 | end
455 | end
456 |
457 | lastCommand = repeatable and code or lastCommand
458 |
459 | cmd = command
460 | local cmdOk, continue = pcall(commands[command], parsed)
461 | if cmdOk and continue then
462 | return
463 | elseif not cmdOk then
464 | -- Something broke, bail
465 | print(colors.red "Error in debugger command, quitting", continue)
466 | debug.sethook()
467 | return
468 | end
469 |
470 | break
471 | end
472 | end
473 | elseif not parsed:match "^unknown command" then
474 | print(colors.yellow(parsed))
475 | badCommand = true
476 | end
477 |
478 | -- Don't run any chunk if detached
479 | if not badCommand and not cmd and not detached then
480 | if runChunk((multiline or "") .. code, env, "__debugger__") then
481 | multiline = (multiline or "") .. code .. "\n"
482 | else
483 | multiline = nil
484 | end
485 | end
486 | end
487 | end
488 | end
489 |
490 | local function countTrace(trace)
491 | local count = 1
492 | for _ in trace:gmatch "\n" do
493 | count = count + 1
494 | end
495 | return count
496 | end
497 |
498 | local lastEnteredFunction
499 | local first = true
500 | local stackDepth, previousStackDepth
501 | local function hook(event, line)
502 | local info = debug.getinfo(2)
503 | previousStackDepth = stackDepth
504 | stackDepth = countTrace(debug.traceback())
505 |
506 | if previousStackDepth and (previousStackDepth < stackDepth) then -- call
507 | frame = frame + 1
508 | currentFrame = 0
509 |
510 | lastEnteredFunction = info.name
511 | elseif previousStackDepth and (previousStackDepth > stackDepth) then -- return
512 | frame = frame - 1
513 | currentFrame = 0
514 | end
515 |
516 | -- Don't debug code from watchpoints/breakpoints/displays
517 | if info.source == "[string \"__debugger__\"]" then
518 | return
519 | end
520 |
521 | if (frameLimit and frame <= frameLimit) or (first and not fromCli) then
522 | frameLimit = first and frame or frameLimit
523 | first = false
524 | doREPL(false)
525 | else
526 | local breaks = breakpoints[info.source:sub(2)]
527 | local breakpoint = breaks and breaks[tonumber(line)]
528 |
529 | if not breakpoint
530 | and (breakpoints[-1] and breakpoints[-1][info.name] and lastEnteredFunction == info.name) then
531 | breaks = breakpoints[-1]
532 | breakpoint = breakpoints[-1][info.name]
533 | end
534 |
535 | if not breakpoint
536 | and (breakpoints[-1] and breakpoints[-1][-1]) then
537 | breaks = breakpoints[-1]
538 | breakpoint = breakpoints[-1][-1]
539 | end
540 |
541 | local breakType = type(breakpoint)
542 | -- -1 means `break at any line of code`
543 | if breaks and breakpoint then
544 | lastEnteredFunction = nil
545 |
546 | local fenv, env, watchpointChanged
547 | if breakType == "string" or breakType == "table" then
548 | fenv = frameEnv(true, currentFrame - 1)
549 | env = setmetatable({}, {
550 | __index = fenv,
551 | __newindex = function(env, name, value)
552 | bindInFrame(8 + 2, name, value, env)
553 | end
554 | })
555 | end
556 |
557 | if breakType == "string" then -- Breakpoint condition
558 | local f = load("return " .. breakpoint, "__debugger__", "t", env)
559 | or load(breakpoint, "__debugger__", "t", env)
560 |
561 | if not f then
562 | return
563 | end
564 |
565 | local ok, value = pcall(f)
566 |
567 | if not ok then
568 | print(colors.red("Breakpoint condition failed with error: ".. value))
569 | end
570 |
571 | if not ok or not value then
572 | return
573 | end
574 | elseif breakType == "table" then -- Watchpoints
575 | for _, watchpoint in ipairs(breakpoint) do
576 | local f = load("return " .. watchpoint.expression, "__debugger__", "t", env)
577 | or load(watchpoint.expression, "__debugger__", "t", env)
578 |
579 | if f then
580 | local ok, newValue = pcall(f)
581 |
582 | if ok then
583 | if newValue ~= watchpoint.lastValue then
584 | watchpointChanged = watchpointChanged or {}
585 | table.insert(watchpointChanged, watchpoint)
586 | end
587 | watchpoint.previousValue = watchpoint.lastValue
588 | watchpoint.lastValue = newValue
589 | else
590 | print(colors.red("Watchpoint expression failed with error: " .. newValue))
591 | end
592 | end
593 | end
594 |
595 | if not watchpointChanged then
596 | return
597 | end
598 | end
599 |
600 | if not frameLimit then
601 | frameLimit = frame
602 | end
603 |
604 | if watchpointChanged and #watchpointChanged > 0 then
605 | io.write("\n")
606 | for _, changed in ipairs(watchpointChanged) do
607 | io.write(
608 | "`" .. highlight(changed.expression) .. "`"
609 | .. " changed from "
610 | )
611 |
612 |
613 | cdo.dump(changed.previousValue)
614 |
615 | io.write(" to ")
616 |
617 | cdo.dump(changed.lastValue)
618 | end
619 | io.write("\n")
620 | end
621 |
622 | doREPL(false)
623 | end
624 | end
625 | end
626 |
627 | commands = {
628 | help = function(parsed)
629 | print(
630 | colors.blue(
631 | "\n" ..
632 | (parsed.about
633 | and commandsHelp[parsed.about]
634 | :gsub(" and exit", "")
635 | or commandsHelp[1]
636 | :gsub("^[^\n]*\n+Commands:\n", "") -- Remove usage line
637 | :gsub(" and exit", "")) ..
638 | "\n"
639 | )
640 | )
641 | end,
642 |
643 | exit = function()
644 | os.exit()
645 | end,
646 |
647 | args = function(parsed)
648 | arguments = parsed.arguments
649 | end,
650 |
651 | depth = function(parsed)
652 | conf.dump.depthLimit = tonumber(parsed.limit)
653 | conf.dump.itemsLimit = tonumber(parsed.items) or conf.dump.itemsLimit
654 | end,
655 |
656 | breakpoint = function(parsed)
657 | -- Get breakpoints count
658 | local count = breakpointCount()
659 |
660 | -- Condition
661 | local condition = table.concat(parsed.when, " ")
662 | local cond = true
663 | if condition and condition ~= "" and (load("return " .. condition) or load(condition)) then
664 | cond = condition
665 | elseif condition and condition ~= "" then
666 | print(colors.yellow "Condition `" .. condition .. "` could not be parsed")
667 | return
668 | end
669 |
670 | -- Line in inspected current file
671 | if tonumber(parsed.where) then
672 | if script then
673 | breakpoints[script] = breakpoints[script] or {}
674 | breakpoints[script][tonumber(parsed.where)] = cond
675 | else
676 | -- TODO: get current script ~= debugger
677 | print(colors.red "Could not defer current file")
678 | end
679 | elseif parsed.where:match "^([^:]*):(%d+)$" then -- Line in a file
680 | local file, line = parsed.where:match "^([^:]*):(%d+)$"
681 |
682 | breakpoints[file] = breakpoints[file] or {}
683 | breakpoints[file][tonumber(line)] = cond
684 | else -- Function name
685 | breakpoints[-1] = breakpoints[-1] or {}
686 | breakpoints[-1][parsed.where] = cond
687 | end
688 |
689 | print(colors.green("Breakpoint #" .. count + 1 .. " added"))
690 | end,
691 |
692 | watch = function(parsed)
693 | -- Get breakpoints count
694 | local count = breakpointCount()
695 |
696 | local expression = table.concat(parsed.expression, " ")
697 | if not load("return " .. expression) and not load(expression) then
698 | print(colors.red "Expression could not be parsed")
699 | return
700 | end
701 |
702 | breakpoints[-1] = breakpoints[-1] or {}
703 | breakpoints[-1][-1] = breakpoints[-1][-1] or {}
704 |
705 | table.insert(breakpoints[-1][-1], {
706 | expression = expression,
707 | lastValue = nil
708 | })
709 |
710 | print(colors.green("Watchpoint #" .. count + 1 .. " added"))
711 | end,
712 |
713 | condition = function(parsed)
714 | -- Condition
715 | local cond = true
716 | local condition = table.concat(parsed.condition, " ")
717 | if condition and load("return " .. condition) or load(condition) then
718 | cond = condition
719 | end
720 |
721 | local breakpoint = tonumber(parsed.id)
722 | local count = 1
723 | for _, lines in pairs(breakpoints) do
724 | for l, _ in pairs(lines) do
725 | if count == breakpoint then
726 | lines[l] = cond
727 |
728 | print(colors.yellow("Breakpoint #" .. breakpoint .. " modified"))
729 | return
730 | end
731 |
732 | count = count + 1
733 | end
734 | end
735 |
736 | print(colors.yellow("Could not find breakpoint #" .. breakpoint))
737 | end,
738 |
739 | clear = function()
740 | breakpoints = {}
741 | displays = {}
742 |
743 | print(colors.yellow "All breakpoints, watchpoints and displays removed")
744 | end,
745 |
746 | delete = function(parsed)
747 | local breakpoint = tonumber(parsed.id)
748 | local count = 1
749 | for _, lines in pairs(breakpoints) do
750 | for l, _ in pairs(lines) do
751 | if count == breakpoint then
752 | lines[l] = nil
753 |
754 | print(colors.yellow("Breakpoint #" .. breakpoint .. " deleted"))
755 | return
756 | end
757 |
758 | count = count + 1
759 | end
760 | end
761 |
762 | print(colors.yellow("Could not find breakpoint #" .. breakpoint))
763 | end,
764 |
765 | enable = function(parsed)
766 | local breakpoint = tonumber(parsed.id)
767 | local count = 1
768 | for _, lines in pairs(breakpoints) do
769 | for l, _ in pairs(lines) do
770 | if count == breakpoint then
771 | lines[l] = true
772 |
773 | print(colors.yellow("Breakpoint #" .. breakpoint .. " enabled"))
774 | return
775 | end
776 |
777 | count = count + 1
778 | end
779 | end
780 |
781 | print(colors.yellow("Could not find breakpoint #" .. breakpoint))
782 | end,
783 |
784 | disable = function(parsed)
785 | local breakpoint = tonumber(parsed.id)
786 | local count = 1
787 | for _, lines in pairs(breakpoints) do
788 | for l, _ in pairs(lines) do
789 | if count == breakpoint then
790 | lines[l] = false
791 |
792 | print(colors.yellow("Breakpoint #" .. breakpoint .. " disabled"))
793 | return
794 | end
795 |
796 | count = count + 1
797 | end
798 | end
799 |
800 | print(colors.yellow("Could not find breakpoint #" .. breakpoint))
801 | end,
802 |
803 | info = function(parsed)
804 | local what = parsed.about
805 | if what == "breakpoints" then
806 | local count = 1
807 | for s, lines in pairs(breakpoints) do
808 | for l, on in pairs(lines) do
809 | if l == -1 then
810 | for _, watchpoint in ipairs(on) do
811 | io.write(
812 | "\n "
813 | .. count .. ". When `"
814 | .. highlight(watchpoint.expression)
815 | .. "` is different from "
816 | )
817 |
818 | cdo.dump(watchpoint.lastValue)
819 |
820 | count = count + 1
821 | end
822 | else
823 | io.write(
824 | "\n "
825 | .. count .. ". "
826 | .. (s ~= -1 and colors.green(s) .. ":" .. colors.yellow(l) or colors.blue(l))
827 | )
828 |
829 | if type(on) == "string" then
830 | io.write(" when `"
831 | .. highlight(on)
832 | .. "`"
833 | )
834 | else
835 | io.write(
836 | (on and colors.green " on" or colors.bright(colors.black(" off")))
837 | )
838 | end
839 | count = count + 1
840 | end
841 | end
842 | end
843 |
844 | if count > 1 then
845 | io.write("\n\n")
846 | else
847 | print(colors.yellow "No breakpoint defined")
848 | end
849 | elseif what == "locals" then
850 | local locals = frameEnv(false, currentFrame + 2)
851 |
852 | local keys = {}
853 | for k, _ in pairs(locals) do
854 | table.insert(keys, k)
855 | end
856 | table.sort(keys)
857 |
858 | io.write "\n"
859 | for _, k in ipairs(keys) do
860 | if k ~= "_ENV" and k ~= "(*temporary)" and k ~= "_G" then
861 | io.write(colors.blue(k)
862 | .. " = ")
863 |
864 | cdo.dump(locals[k], 1)
865 |
866 | io.write "\n"
867 | end
868 | end
869 | io.write "\n"
870 | elseif what == "displays" then
871 | local displayStr = ""
872 | for id, display in ipairs(displays) do
873 | displayStr = displayStr ..
874 | "\n "
875 | .. id .. ". `"
876 | .. highlight(display)
877 | .. "`"
878 | end
879 | if displayStr ~= "" then
880 | print(displayStr .. "\n")
881 | else
882 | print(colors.yellow "No display defined")
883 | end
884 | end
885 | end,
886 |
887 | display = function(parsed)
888 | local expression = table.concat(parsed.expression, " ")
889 |
890 | if not load("return " .. expression) and not load(expression) then
891 | print(colors.red "Expression could not be parsed")
892 | return
893 | end
894 |
895 | table.insert(displays, expression)
896 |
897 | print(colors.green("Display #" .. #displays .. " added"))
898 | end,
899 |
900 | undisplay = function(parsed)
901 | if displays[tonumber(parsed.id)] then
902 | table.remove(displays, tonumber(parsed.id))
903 | print(colors.yellow("Removed display #" .. parsed.id))
904 | else
905 | print(colors.red("Could not find display #" .. parsed.id))
906 | end
907 | end,
908 |
909 | step = function()
910 | frameLimit = frame + 1
911 | return true
912 | end,
913 |
914 | next = function()
915 | frameLimit = frame
916 | return true
917 | end,
918 |
919 | finish = function()
920 | frameLimit = frame - 1
921 | return true
922 | end,
923 |
924 | up = function()
925 | if currentFrame + 1 > frame then
926 | print(colors.yellow "No further context")
927 | return false
928 | end
929 |
930 | currentFrame = math.min(currentFrame + 1, frame)
931 |
932 | return false
933 | end,
934 |
935 | down = function()
936 | if currentFrame - 1 < 0 then
937 | print(colors.yellow "No further context")
938 | return false
939 | end
940 |
941 | currentFrame = math.max(0, currentFrame - 1)
942 |
943 | return false
944 | end,
945 |
946 | trace = function()
947 | local trace = ""
948 | local info
949 | local i = 5
950 | repeat
951 | info = debug.getinfo(i)
952 |
953 | if info then
954 | trace = trace ..
955 | (i - 5 == currentFrame
956 | and colors.bright(colors.green(" ❱ " .. (i - 5) .. " │ "))
957 | or colors.bright(colors.black(" " .. (i - 5) .. " │ ")))
958 | .. colors.green(info.short_src) .. ":"
959 | .. (info.currentline > 0 and colors.yellow(info.currentline) .. ":" or "")
960 | .. " in " .. colors.magenta(info.namewhat)
961 | .. colors.blue((info.name and " " .. info.name) or (info.what == "main" and "main chunk") or " ?")
962 | .. "\n"
963 | end
964 |
965 | i = i + 1
966 | until not info or i - 5 > frame
967 |
968 | print("\n" .. trace)
969 |
970 | return false
971 | end,
972 |
973 | where = function(parsed, offset)
974 | offset = offset or 0
975 | local info = debug.getinfo(5 + offset + (currentFrame or 0))
976 |
977 | local source = ""
978 | local srcType = info.source:sub(1, 1)
979 | if srcType == "@" then
980 | local file, _ = io.open(info.source:sub(2), "r")
981 |
982 | if file then
983 | source = file:read("*all")
984 |
985 | file:close()
986 | end
987 | elseif srcType == "=" then
988 | source = info.source:sub(2)
989 | else
990 | source = info.source
991 | end
992 |
993 | source = highlight(source)
994 |
995 | local lines = {}
996 | for line in source:gmatch("([^\n]*)\n") do
997 | table.insert(lines, line)
998 | end
999 |
1000 | local toShow = (parsed and parsed.rows) or conf.whereRows
1001 |
1002 | local minLine = math.max(1, info.currentline - toShow)
1003 | local maxLine = math.min(#lines, info.currentline + toShow)
1004 |
1005 | local w = ""
1006 | for count, line in ipairs(lines) do
1007 | if count >= minLine
1008 | and count <= maxLine then
1009 | w = w ..
1010 | (count == info.currentline
1011 | and colors.bright(colors.green(" ❱ " .. count .. " │ ")) .. line
1012 | or colors.bright(colors.black(" " .. count .. " │ ")) .. line)
1013 | .. "\n"
1014 | end
1015 | end
1016 |
1017 | print("\n [" .. currentFrame .. "] " .. colors.green(info.short_src) .. ":"
1018 | .. (info.currentline > 0 and colors.yellow(info.currentline) .. ":" or "")
1019 | .. " in " .. colors.magenta(info.namewhat)
1020 | .. colors.blue((info.name and " " .. info.name) or (info.what == "main" and "main chunk") or " ?"))
1021 | print(colors.reset .. w)
1022 |
1023 | return false, w
1024 | end,
1025 |
1026 | continue = function()
1027 | for _, v in pairs(breakpoints) do
1028 | -- luacheck: push ignore 512
1029 | for _, _ in pairs(v) do
1030 | -- There's at least one breakpoint: don't clear hooks
1031 | frameLimit = false
1032 | return true
1033 | end
1034 | -- luacheck: pop
1035 | end
1036 |
1037 | -- No breakpoints: clear hooks
1038 | debug.sethook()
1039 | return true
1040 | end,
1041 |
1042 | run = function()
1043 | -- If not breakpoints, don't hook
1044 | if breakpointCount() > 0 then
1045 | debug.sethook(hook, "l")
1046 | end
1047 |
1048 | if script then
1049 | runFile(script, arguments)
1050 | end
1051 |
1052 | debug.sethook()
1053 | end,
1054 | }
1055 |
1056 | banner()
1057 |
1058 | if fromCli then
1059 | doREPL(true)
1060 | else
1061 | -- We're required inside a script, debug.sethook must be the last instruction otherwise
1062 | -- we'll break at the last debugger instruction
1063 | return debug.sethook(hook, "l")
1064 | end
1065 | end
1066 |
--------------------------------------------------------------------------------
/croissant/do.lua:
--------------------------------------------------------------------------------
1 | local colors = require "term.colors"
2 | local conf = require "croissant.conf"
3 |
4 | local dump
5 | dump = function(t, inc, seen)
6 | if type(t) == "table" and (inc or 0) < conf.dump.depthLimit then
7 | inc = inc or 1
8 | seen = seen or {}
9 |
10 | seen[t] = true
11 |
12 | io.write(
13 | "{ "
14 | .. colors.dim .. colors.cyan .. "-- " .. tostring(t) .. colors.reset
15 | .. "\n"
16 | )
17 |
18 | local metatable = getmetatable(t)
19 | if metatable then
20 | io.write(
21 | (" "):rep(inc)
22 | .. colors.dim(colors.cyan "metatable = ")
23 | )
24 | if not seen[metatable] then
25 | dump(metatable, inc + 1, seen)
26 | io.write ",\n"
27 | else
28 | io.write(colors.yellow .. tostring(metatable) .. colors.reset .. ",\n")
29 | end
30 | end
31 |
32 | local count = 0
33 | for k, v in pairs(t) do
34 | count = count + 1
35 |
36 | if count > conf.dump.itemsLimit then
37 | io.write((" "):rep(inc) .. colors.dim(colors.cyan("...")) .. "\n")
38 | break
39 | end
40 |
41 | io.write((" "):rep(inc))
42 |
43 | local typeK = type(k)
44 | local typeV = type(v)
45 |
46 | if typeK == "table" and not seen[v] then
47 | io.write "["
48 |
49 | dump(k, inc + 1, seen)
50 |
51 | io.write "] = "
52 | elseif typeK == "string" then
53 | io.write(colors.blue .. k:format("%q") .. colors.reset
54 | .. " = ")
55 | else
56 | io.write("["
57 | .. colors.yellow .. tostring(k) .. colors.reset
58 | .. "] = ")
59 | end
60 |
61 | if typeV == "table" and not seen[v] then
62 | dump(v, inc + 1, seen)
63 | io.write ",\n"
64 | elseif typeV == "string" then
65 | io.write(colors.green .. "\"" .. v .. "\"" .. colors.reset .. ",\n")
66 | else
67 | io.write(colors.yellow .. tostring(v) .. colors.reset .. ",\n")
68 | end
69 | end
70 |
71 | io.write((" "):rep(inc - 1).. "}")
72 |
73 | return
74 | elseif type(t) == "string" then
75 | io.write(colors.green .. "\"" .. t .. "\"" .. colors.reset)
76 |
77 | return
78 | end
79 |
80 | io.write(colors.yellow .. tostring(t) .. colors.reset)
81 | end
82 |
83 | local function frameEnv(withGlobals, frameOffset)
84 | local level = 5 + (frameOffset or 0)
85 | local func = debug.getinfo(level - 1).func
86 | local env = {}
87 | -- Shallow copy of _G
88 | local rawenv = {}
89 | for k, v in pairs(_G) do
90 | rawenv[k] = v
91 | end
92 | local i
93 |
94 | -- Retrieve the upvalues
95 | i = 1
96 | while true do
97 | local ok, name, value = pcall(debug.getupvalue, func, i)
98 |
99 | if not ok or not name then
100 | break
101 | end
102 |
103 | env[name] = value
104 | rawenv[name] = value
105 | i = i + 1
106 | end
107 |
108 | -- Retrieve the locals (overwriting any upvalues)
109 | i = 1
110 | while true do
111 | local ok, name, value = pcall(debug.getlocal, level, i)
112 |
113 | if not ok or not name then
114 | break
115 | end
116 |
117 | env[name] = value
118 | rawenv[name] = value
119 | i = i + 1
120 | end
121 |
122 | -- Retrieve the varargs
123 | local varargs = {}
124 | i = 1
125 | while true do
126 | local ok, name, value = pcall(debug.getlocal, level, -i)
127 |
128 | if not ok or not name then
129 | break
130 | end
131 |
132 | varargs[i] = value
133 | i = i + 1
134 | end
135 | if i > 1 then
136 | env["..."] = varargs
137 | rawenv["..."] = varargs
138 | end
139 |
140 | if withGlobals then
141 | env._ENV = env._ENV or {}
142 | return setmetatable(env._ENV, {__index = env or _G}), rawenv
143 | else
144 | return env
145 | end
146 | end
147 |
148 | local function bindInFrame(frame, name, value, env)
149 | -- Mutating a local?
150 | do
151 | local i = 1
152 | repeat
153 | local var = debug.getlocal(frame, i)
154 |
155 | if name == var then
156 | debug.setlocal(frame, i, value)
157 |
158 | return
159 | end
160 | i = i + 1
161 | until var == nil
162 | end
163 |
164 | -- Mutating an upvalue?
165 | local func = debug.getinfo(frame).func
166 | do
167 | local i = 1
168 | repeat
169 | local var = debug.getupvalue(func, i)
170 | if name == var then
171 | debug.setupvalue(func, i, value)
172 |
173 | return
174 | end
175 | i = i + 1
176 | until var == nil
177 | end
178 |
179 | -- New global
180 | rawset(_G, name, value)
181 | end
182 |
183 | -- Returns true when more line are needed
184 | local function runChunk(code, env, name)
185 | env = env or _G
186 |
187 | local fn, err = load("return " .. code, name or "croissant", "t", env)
188 | if not fn then
189 | fn, err = load(code, name or "croissant", "t", env)
190 | end
191 |
192 | if fn then
193 | local result = table.pack(xpcall(fn, debug.traceback))
194 |
195 | if result[1] then
196 | for i = 2, result.n do
197 | local r = result[i]
198 | dump(r)
199 | io.write "\t"
200 | end
201 |
202 | if result.n < 2 then
203 | -- Look for assignments
204 | local names = { code:match "^([^{=]+)%s?=[^=]" }
205 | if names then
206 | for _, n in ipairs(names) do
207 | local assignement = load("return " .. n)
208 | local assigned = assignement and assignement()
209 | if assigned then
210 | dump(assigned)
211 | io.write "\t"
212 | end
213 | end
214 | end
215 |
216 | io.write "\n"
217 | else
218 | io.write "\n"
219 | end
220 | else
221 | print(colors.red(result[2]))
222 | end
223 | else
224 | -- Syntax error near
225 | if err:match("") then
226 | return true
227 | else
228 | print(colors.red(err))
229 | end
230 | end
231 |
232 | return false
233 | end
234 |
235 | local function runFile(script, arguments)
236 | arguments = arguments or {}
237 |
238 | -- Run file
239 | local fn, err = loadfile(script)
240 |
241 | if not fn then
242 | print(colors.red(err))
243 | return
244 | end
245 |
246 | local result = table.pack(xpcall(fn, debug.traceback, table.unpack(arguments)))
247 |
248 | if not result[1] then
249 | print(colors.red(result[2]))
250 | return
251 | end
252 |
253 | if result.n > 1 then
254 | io.write(colors.bright(colors.blue("\nReturned values:\n")))
255 |
256 | for i = 2, result.n do
257 | local r = result[i]
258 | dump(r)
259 | io.write "\t"
260 | end
261 |
262 | io.write "\n"
263 | end
264 | end
265 |
266 | local function loadHistory()
267 | local history = {}
268 |
269 | local historyFile = io.open(os.getenv "HOME" .. "/.croissant_history", "r")
270 |
271 | if historyFile then
272 | for line in historyFile:lines() do
273 | if line ~= "" then
274 | table.insert(history, 1, ({line:gsub("\\n", "\n")})[1])
275 | end
276 | end
277 |
278 | historyFile:close()
279 | end
280 |
281 | return history
282 | end
283 |
284 | local function loadDebugHistory()
285 | local history = {}
286 |
287 | local historyFile = io.open(os.getenv "HOME" .. "/.croissant_debugger_history", "r")
288 |
289 | if historyFile then
290 | for line in historyFile:lines() do
291 | if line ~= "" then
292 | table.insert(history, 1, ({line:gsub("\\n", "\n")})[1])
293 | end
294 | end
295 |
296 | historyFile:close()
297 | end
298 |
299 | return history
300 | end
301 |
302 | local function appendToHistory(code)
303 | local historyFile = io.open(os.getenv "HOME" .. "/.croissant_history", "a+")
304 |
305 | if historyFile then
306 | historyFile:write(code:gsub("\n", "\\n") .. "\n")
307 |
308 | historyFile:close()
309 | end
310 | end
311 |
312 | local function appendToDebugHistory(code)
313 | local historyFile = io.open(os.getenv "HOME" .. "/.croissant_debugger_history", "a+")
314 |
315 | if historyFile then
316 | historyFile:write(code:gsub("\n", "\\n") .. "\n")
317 |
318 | historyFile:close()
319 | end
320 | end
321 |
322 | local function luaVersion()
323 | local f = function()
324 | return function()
325 | end
326 | end
327 |
328 | local t = {
329 | nil,
330 | [false] = "Lua 5.1",
331 | [true] = "Lua 5.2",
332 | [1/"-0"] = ({ ['0.0'] = "Lua 5.3", ['0'] = "Lua 5.4" })[0 + '0' .. ''],
333 | [1] = "LuaJIT"
334 | }
335 |
336 | return t[1] or t[1/0] or t[f() == f()]
337 | end
338 |
339 | local function banner()
340 | local version = luaVersion()
341 |
342 | if tonumber(_VERSION:match("Lua (%d+)")) < 5
343 | or tonumber(_VERSION:match("Lua %d+%.(%d+)")) < 1 then
344 | print(colors.red "Croissant requires at least Lua 5.1")
345 | os.exit(1)
346 | end
347 |
348 | print(
349 | "🥐 Croissant 0.0.1 (C) 2019 Benoit Giannangeli\n"
350 | .. version .. (version:match "^LuaJIT"
351 | and " Copyright (C) 2005-2017 Mike Pall. http://luajit.org/"
352 | or " Copyright (C) 1994-2018 Lua.org, PUC-Rio")
353 | )
354 | end
355 |
356 | return {
357 | banner = banner,
358 | appendToDebugHistory = appendToDebugHistory,
359 | appendToHistory = appendToHistory,
360 | bindInFrame = bindInFrame,
361 | dump = dump,
362 | frameEnv = frameEnv,
363 | loadHistory = loadHistory,
364 | runChunk = runChunk,
365 | loadDebugHistory = loadDebugHistory,
366 | runFile = runFile,
367 | }
368 |
--------------------------------------------------------------------------------
/croissant/help.lua:
--------------------------------------------------------------------------------
1 | local colors = require "term.colors"
2 |
3 | local code = colors.yellow local id = colors.blue local keyword = colors.magenta
4 |
5 | -- luacheck: ignore 631
6 |
7 | return {
8 | ["quit"] = {
9 | title = "quit ()", body = "Leave Croissant." },
10 | ["assert"] = {
11 | title = "assert (v [, message])",
12 | body = [[ Calls ]] .. id "error" .. [[ if the value of its argument ]] .. id "v" .. [[ is false (i.e., ]] .. code "nil" .. [[ or ]] .. code "false" .. [[); otherwise, returns all its arguments. In case of error, ]] .. id "message" .. [[ is the error object; when absent, it defaults to ]] .. code "assertion failed!" .. [[ ]] },
13 | ["collectgarbage"] = {
14 | title = "collectgarbage ([opt [, arg]])",
15 | body = [[This function is a generic interface to the garbage collector. It performs different functions according to its first argument, ]] .. id "opt" .. [[:
16 |
17 | ]] .. code "collect" .. [[| performs a full garbage-collection cycle. This is the default option.
18 |
19 | ]] .. code "stop" .. [[| stops automatic execution of the garbage collector. The collector will run only when explicitly invoked, until a call to restart it.
20 |
21 | ]] .. code "restart" .. [[| restarts automatic execution of the garbage collector.
22 |
23 | ]] .. code "count" .. [[| returns the total memory in use by Lua in Kbytes. The value has a fractional part, so that it multiplied by 1024 gives the exact number of bytes in use by Lua (except for overflows).
24 |
25 | ]] .. code "step" .. [[| performs a garbage-collection step. The step size is controlled by ]] .. id "arg" .. [[. With a zero value, the collector will perform one basic (indivisible) step. For non-zero values, the collector will perform as if that amount of memory (in KBytes) had been allocated by Lua. Returns ]] .. code "true" .. [[ if the step finished a collection cycle.
26 |
27 | ]] .. code "setpause" .. [[| sets ]] .. id "arg" .. [[ as the new value for the pause of the collector ]] .. id "GC" .. [[. Returns the previous value for pause.
28 |
29 | ]] .. code "incremental" .. [[| Change the collector mode to incremental. This option can be followed by three numbers: the garbage-collector pause, the step multiplier, and the step size.
30 |
31 | ]] .. code "generational" .. [[| Change the collector mode to generational. This option can be followed by two numbers: the garbage-collector minor multiplier and the major multiplier.
32 |
33 | ]] .. code "isrunning" .. [[| returns a boolean that tells whether the collector is running (i.e., not stopped). }
34 |
35 | } ]] },
36 | ["dofile"] = {
37 | title = "dofile ([filename])",
38 | body = [[ Opens the named file and executes its contents as a Lua chunk. When called without arguments, ]] .. id "dofile" .. [[ executes the contents of the standard input (]] .. id "stdin" .. [[). Returns all values returned by the chunk. In case of errors, ]] .. id "dofile" .. [[ propagates the error to its caller (that is, ]] .. id "dofile" .. [[ does not run in protected mode). ]] },
39 | ["error"] = {
40 | title = "error (message [, level])",
41 | body = [[ Terminates the last protected function called and returns ]] .. id "message" .. [[ as the error object. Function ]] .. id "error" .. [[ never returns.
42 |
43 | Usually, ]] .. id "error" .. [[ adds some information about the error position at the beginning of the message, if the message is a string. The ]] .. id "level" .. [[ argument specifies how to get the error position. With level 1 (the default), the error position is where the ]] .. id "error" .. [[ function was called. Level 2 points the error to where the function that called ]] .. id "error" .. [[ was called; and so on. Passing a level 0 avoids the addition of error position information to the message. ]] },
44 | ["_G"] = {
45 | title = "_G",
46 | body = [[A global variable (not a function) that holds the global environment ]] .. id "globalenv" .. [[. Lua itself does not use this variable; changing its value does not affect any environment, nor vice versa.]]
47 |
48 | },
49 |
50 |
51 | ["getmetatable"] = {
52 | title = "getmetatable (object)",
53 | body = [[If ]] .. id "object" .. [[ does not have a metatable, returns ]] .. code "nil" .. [[. Otherwise, if the object's metatable has a ]] .. id "__metatable" .. [[ field, returns the associated value. Otherwise, returns the metatable of the given object. ]] },
54 | ["ipairs"] = {
55 | title = "ipairs (t)",
56 | body = [[Returns three values (an iterator function, the table ]] .. id "t" .. [[, and 0) so that the construction ]] .. code " for i,v in ipairs(t) do @rep{body" .. [[ end }
57 | will iterate over the key@En{}value pairs (]] .. code "1,t[1]" .. [[), (]] .. code "2,t[2]" .. [[), .., up to the first absent index. ]] },
58 | ["load"] = {
59 | title = "load (chunk [, chunkname [, mode [, env]]])",
60 | body = [[Loads a chunk.
61 |
62 | If ]] .. id "chunk" .. [[ is a string, the chunk is this string. If ]] .. id "chunk" .. [[ is a function, ]] .. id "load" .. [[ calls it repeatedly to get the chunk pieces. Each call to ]] .. id "chunk" .. [[ must return a string that concatenates with previous results. A return of an empty string, ]] .. code "nil" .. [[, or no value signals the end of the chunk.
63 |
64 | If there are no syntactic errors, returns the compiled chunk as a function; otherwise, returns ]] .. code "nil" .. [[ plus the error message.
65 |
66 | When you load a main chunk, the resulting function will always have exactly one upvalue, the ]] .. id "_ENV" .. [[ variable ]] .. id "globalenv" .. [[. However, when you load a binary chunk created from a function ]] .. id "string.dump" .. [[, the resulting function can have an arbitrary number of upvalues, and there is no guarantee that its first upvalue will be the ]] .. id "_ENV" .. [[ variable. (A non-main function may not even have an ]] .. id "_ENV" .. [[ upvalue.)
67 |
68 | Regardless, if the resulting function has any upvalues, its first upvalue is set to the value of ]] .. id "env" .. [[, if that parameter is given, or to the value of the global environment. Other upvalues are initialized with ]] .. code "nil" .. [[. All upvalues are fresh, that is, they are not shared with any other function.
69 |
70 | ]] .. id "chunkname" .. [[ is used as the name of the chunk for error messages and debug information ]] .. id "debugI" .. [[. When absent, it defaults to ]] .. id "chunk" .. [[, if ]] .. id "chunk" .. [[ is a string, or to ]] .. code "=(load)" .. [[ otherwise.
71 |
72 | The string ]] .. id "mode" .. [[ controls whether the chunk can be text or binary (that is, a precompiled chunk). It may be the string ]] .. code "b" .. [[ (only binary chunks), ]] .. code "t" .. [[ (only text chunks), or ]] .. code "bt" .. [[ (both binary and text). The default is ]] .. code "bt" .. [[.
73 |
74 | Lua does not check the consistency of binary chunks. Maliciously crafted binary chunks can crash the interpreter. ]] },
75 | ["loadfile"] = {
76 | title = "loadfile ([filename [, mode [, env]]])",
77 | body = [[Similar to ]] .. id "load" .. [[, but gets the chunk from file ]] .. id "filename" .. [[ or from the standard input, if no file name is given. ]] },
78 | ["next"] = {
79 | title = "next (table [, index])",
80 | body = [[Allows a program to traverse all fields of a table. Its first argument is a table and its second argument is an index in this table. ]] .. id "next" .. [[ returns the next index of the table and its associated value. When called with ]] .. code "nil" .. [[ as its second argument, ]] .. id "next" .. [[ returns an initial index and its associated value. When called with the last index, or with ]] .. code "nil" .. [[ in an empty table, ]] .. id "next" .. [[ returns ]] .. code "nil" .. [[. If the second argument is absent, then it is interpreted as ]] .. code "nil" .. [[. In particular, you can use ]] .. code "next(t)" .. [[ to check whether a table is empty.
81 |
82 | The order in which the indices are enumerated is not specified, even for numeric indices. (To traverse a table in numerical order, use a numerical ]] .. keyword "for" .. [[.)
83 |
84 | The behavior of ]] .. id "next" .. [[ is undefined if, during the traversal, you assign any value to a non-existent field in the table. You may however modify existing fields. In particular, you may set existing fields to nil. ]] },
85 | ["pairs"] = {
86 | title = "pairs (t)",
87 | body = [[If ]] .. id "t" .. [[ has a metamethod ]] .. id "__pairs" .. [[, calls it with ]] .. id "t" .. [[ as argument and returns the first three results from the call.
88 |
89 | Otherwise, returns three values: the ]] .. id "next" .. [[ function, the table ]] .. id "t" .. [[, and ]] .. code "nil" .. [[, so that the construction ]] .. code " for k,v in pairs(t) do @rep{body" .. [[ end }
90 | will iterate over all key@En{}value pairs of table ]] .. id "t" .. [[.
91 |
92 | See function ]] .. id "next" .. [[ for the caveats of modifying the table during its traversal. ]] },
93 | ["pcall"] = {
94 | title = "pcall (f [, arg1, ...])",
95 | body = [[Calls function ]] .. id "f" .. [[ with the given arguments in protected mode. This means that any error inside ]] .. code "f" .. [[ is not propagated; instead, ]] .. id "pcall" .. [[ catches the error and returns a status code. Its first result is the status code (a boolean), which is true if the call succeeds without errors. In such case, ]] .. id "pcall" .. [[ also returns all results from the call, after this first result. In case of any error, ]] .. id "pcall" .. [[ returns ]] .. code "false" .. [[ plus the error message. ]] },
96 | ["print"] = {
97 | title = "print (...)",
98 | body = [[ Receives any number of arguments and prints their values to ]] .. id "stdout" .. [[, using the ]] .. id "tostring" .. [[ function to convert each argument to a string. ]] .. id "print" .. [[ is not intended for formatted output, but only as a quick way to show a value, for instance for debugging. For complete control over the output, use ]] .. id "string.format" .. [[ and ]] .. id "io.write" .. [[. ]] },
99 | ["rawequal"] = {
100 | title = "rawequal (v1, v2)",
101 | body = [[ Checks whether ]] .. id "v1" .. [[ is equal to ]] .. id "v2" .. [[, without invoking the ]] .. id "__eq" .. [[ metamethod. Returns a boolean. ]] },
102 | ["rawget"] = {
103 | title = "rawget (table, index)",
104 | body = [[ Gets the real value of ]] .. code "table[index]" .. [[, without invoking the ]] .. id "__index" .. [[ metamethod. ]] .. id "table" .. [[ must be a table; ]] .. id "index" .. [[ may be any value. ]] },
105 | ["rawlen"] = {
106 | title = "rawlen (v)",
107 | body = [[ Returns the length of the object ]] .. id "v" .. [[, which must be a table or a string, without invoking the ]] .. id "__len" .. [[ metamethod. Returns an integer. ]] },
108 | ["rawset"] = {
109 | title = "rawset (table, index, value)",
110 | body = [[ Sets the real value of ]] .. code "table[index]" .. [[ to ]] .. id "value" .. [[, without invoking the ]] .. id "__newindex" .. [[ metamethod. ]] .. id "table" .. [[ must be a table, ]] .. id "index" .. [[ any value different from ]] .. code "nil" .. [[ and NaN, and ]] .. id "value" .. [[ any Lua value.
111 |
112 | This function returns ]] .. id "table" .. [[. ]] },
113 | ["select"] = {
114 | title = "select (index, ...)",
115 | body = [[If ]] .. id "index" .. [[ is a number, returns all arguments after argument number ]] .. id "index" .. [[; a negative number indexes from the end (]] .. code "-1" .. [[ is the last argument). Otherwise, ]] .. id "index" .. [[ must be the string ]] .. code "\"#\"" .. [[, and ]] .. id "select" .. [[ returns the total number of extra arguments it received. ]] },
116 | ["setmetatable"] = {
117 | title = "setmetatable (table, metatable)",
118 | body = [[Sets the metatable for the given table. (To change the metatable of other types from Lua code, you must use the @link{debuglib|debug library}.) If ]] .. id "metatable" .. [[ is ]] .. code "nil" .. [[, removes the metatable of the given table. If the original metatable has a ]] .. id "__metatable" .. [[ field, raises an error.
119 |
120 | This function returns ]] .. id "table" .. [[. ]] },
121 | ["tonumber"] = {
122 | title = "tonumber (e [, base])",
123 | body = [[When called with no ]] .. id "base" .. [[, ]] .. id "tonumber" .. [[ tries to convert its argument to a number. If the argument is already a number or a string convertible to a number, then ]] .. id "tonumber" .. [[ returns this number; otherwise, it returns ]] .. code "nil" .. [[.
124 |
125 | The conversion of strings can result in integers or floats, according to the lexical conventions of Lua ]] .. id "lexical" .. [[. (The string may have leading and trailing spaces and a sign.)
126 |
127 | When called with ]] .. id "base" .. [[, then ]] .. id "e" .. [[ must be a string to be interpreted as an integer numeral in that base. The base may be any integer between 2 and 36, inclusive. In bases above 10, the letter ]] .. code "A" .. [[ (in either upper or lower case) represents 10, ]] .. code "B" .. [[ represents 11, and so forth, with ]] .. code "Z" .. [[ representing 35. If the string ]] .. id "e" .. [[ is not a valid numeral in the given base, the function returns ]] .. code "nil" .. [[. ]] },
128 | ["tostring"] = {
129 | title = "tostring (v)",
130 | body = [[ Receives a value of any type and converts it to a string in a human-readable format. (For complete control of how numbers are converted, use ]] .. id "string.format" .. [[.)
131 |
132 | If the metatable of ]] .. id "v" .. [[ has a ]] .. id "__tostring" .. [[ field, then ]] .. id "tostring" .. [[ calls the corresponding value with ]] .. id "v" .. [[ as argument, and uses the result of the call as its result. ]] },
133 | ["type"] = {
134 | title = "type (v)",
135 | body = [[ Returns the type of its only argument, coded as a string. The possible results of this function are ]] .. code "nil" .. [[ (a string, not the value ]] .. code "nil" .. [[), ]] .. code "number" .. [[, ]] .. code "string" .. [[, ]] .. code "boolean" .. [[, ]] .. code "table" .. [[, ]] .. code "function" .. [[, ]] .. code "thread" .. [[, and ]] .. code "userdata" .. [[. ]] },
136 | ["_VERSION"] = {
137 | title = "_VERSION",
138 | body = [[ A global variable (not a function) that holds a string containing the running Lua version. The current value of this variable is ]] .. code "Lua 5.4" .. [[. ]] },
139 |
140 |
141 | ["warn"] = {
142 | title = "warn (message)",
143 | body = [[ Emits a warning with the given message. Note that messages not ending with an end-of-line are assumed to be continued by the message in the next call. ]] },
144 | ["xpcall"] = {
145 | title = "xpcall (f, msgh [, arg1, ...])",
146 | body = [[This function is similar to ]] .. id "pcall" .. [[, except that it sets a new message handler ]] .. id "msgh" .. [[.
147 |
148 | } ]] },
149 | ["coroutine.create"] = {
150 | title = "coroutine.create (f)",
151 | body = [[Creates a new coroutine, with body ]] .. id "f" .. [[. ]] .. id "f" .. [[ must be a function. Returns this new coroutine, an object with type ]] .. code "\"thread\"" .. [[. ]] },
152 | ["coroutine.isyieldable"] = {
153 | title = "coroutine.isyieldable ()",
154 | body = [[Returns true when the running coroutine can yield.
155 |
156 | A running coroutine is yieldable if it is not the main thread and it is not inside a non-yieldable C function. ]] },
157 | ["coroutine.kill"] = {
158 | title = "coroutine.kill (co)",
159 | body = [[Kills coroutine ]] .. id "co" .. [[, closing all its pending to-be-closed variables and putting the coroutine in a dead state. In case of error closing some variable, returns ]] .. code "false" .. [[ plus the error object; otherwise returns ]] .. code "true" .. [[. ]] },
160 | ["coroutine.resume"] = {
161 | title = "coroutine.resume (co [, val1, ...])",
162 | body = [[Starts or continues the execution of coroutine ]] .. id "co" .. [[. The first time you resume a coroutine, it starts running its body. The values ]] .. id "val1" .. [[, .. are passed as the arguments to the body function. If the coroutine has yielded, ]] .. id "resume" .. [[ restarts it; the values ]] .. id "val1" .. [[, .. are passed as the results from the yield.
163 |
164 | If the coroutine runs without any errors, ]] .. id "resume" .. [[ returns ]] .. code "true" .. [[ plus any values passed to ]] .. id "yield" .. [[ (when the coroutine yields) or any values returned by the body function (when the coroutine terminates). If there is any error, ]] .. id "resume" .. [[ returns ]] .. code "false" .. [[ plus the error message. ]] },
165 | ["coroutine.running"] = {
166 | title = "coroutine.running ()",
167 | body = [[Returns the running coroutine plus a boolean, true when the running coroutine is the main one. ]] },
168 | ["coroutine.status"] = {
169 | title = "coroutine.status (co)",
170 | body = [[Returns the status of coroutine ]] .. id "co" .. [[, as a string: ]] .. code "\"running\"" .. [[, if the coroutine is running (that is, it called ]] .. id "status" .. [[); ]] .. code "\"suspended\"" .. [[, if the coroutine is suspended in a call to ]] .. id "yield" .. [[, or if it has not started running yet; ]] .. code "\"normal\"" .. [[ if the coroutine is active but not running (that is, it has resumed another coroutine); and ]] .. code "\"dead\"" .. [[ if the coroutine has finished its body function, or if it has stopped with an error. ]] },
171 | ["coroutine.wrap"] = {
172 | title = "coroutine.wrap (f)",
173 | body = [[Creates a new coroutine, with body ]] .. id "f" .. [[. ]] .. id "f" .. [[ must be a function. Returns a function that resumes the coroutine each time it is called. Any arguments passed to the function behave as the extra arguments to ]] .. id "resume" .. [[. Returns the same values returned by ]] .. id "resume" .. [[, except the first boolean. In case of error, propagates the error. ]] },
174 | ["coroutine.yield"] = {
175 | title = "coroutine.yield (...)",
176 | body = [[Suspends the execution of the calling coroutine. Any arguments to ]] .. id "yield" .. [[ are passed as extra results to ]] .. id "resume" .. [[.
177 |
178 | } ]] },
179 | ["require"] = {
180 | title = "require (modname)",
181 | body = [[Loads the given module. The function starts by looking into the ]] .. id "package.loaded" .. [[ table to determine whether ]] .. id "modname" .. [[ is already loaded. If it is, then ]] .. id "require" .. [[ returns the value stored at ]] .. code "package.loaded[modname]" .. [[. Otherwise, it tries to find a loader for the module.
182 |
183 | To find a loader, ]] .. id "require" .. [[ is guided by the ]] .. id "package.searchers" .. [[ sequence. By changing this sequence, we can change how ]] .. id "require" .. [[ looks for a module. The following explanation is based on the default configuration for ]] .. id "package.searchers" .. [[.
184 |
185 | First ]] .. id "require" .. [[ queries ]] .. code "package.preload[modname]" .. [[. If it has a value, this value (which must be a function) is the loader. Otherwise ]] .. id "require" .. [[ searches for a Lua loader using the path stored in ]] .. id "package.path" .. [[. If that also fails, it searches for a C loader using the path stored in ]] .. id "package.cpath" .. [[. If that also fails, it tries an all-in-one loader ]] .. id "package.searchers" .. [[.
186 |
187 | Once a loader is found, ]] .. id "require" .. [[ calls the loader with two arguments: ]] .. id "modname" .. [[ and an extra value dependent on how it got the loader. (If the loader came from a file, this extra value is the file name.) If the loader returns any non-nil value, ]] .. id "require" .. [[ assigns the returned value to ]] .. code "package.loaded[modname]" .. [[. If the loader does not return a non-nil value and has not assigned any value to ]] .. code "package.loaded[modname]" .. [[, then ]] .. id "require" .. [[ assigns ]] .. keyword "true" .. [[ to this entry. In any case, ]] .. id "require" .. [[ returns the final value of ]] .. code "package.loaded[modname]" .. [[.
188 |
189 | If there is any error loading or running the module, or if it cannot find any loader for the module, then ]] .. id "require" .. [[ raises an error. ]] },
190 | ["package.config"] = {
191 | title = "package.config",
192 | body = [[A string describing some compile-time configurations for packages. This string is a sequence of lines:
193 |
194 | ・ The first line is the directory separator string. Default is ]] .. code "\\" .. [[ for Windows and ]] .. code "/" .. [[ for all other systems.}
195 |
196 | ・ The second line is the character that separates templates in a path. Default is ]] .. code ";" .. [[.}
197 |
198 | ・ The third line is the string that marks the substitution points in a template. Default is ]] .. code "?" .. [[.}
199 |
200 | ・ The fourth line is a string that, in a path in Windows, is replaced by the executable's directory. Default is ]] .. code "!" .. [[.}
201 |
202 | ・ The fifth line is a mark to ignore all text after it when building the ]] .. id "luaopen_" .. [[ function name. Default is ]] .. code "-" .. [[.}]]
203 |
204 | },
205 |
206 |
207 | ["package.cpath"] = {
208 | title = "package.cpath",
209 | body = [[The path used by ]] .. id "require" .. [[ to search for a C loader.
210 |
211 | Lua initializes the C path ]] .. id "package.cpath" .. [[ in the same way it initializes the Lua path ]] .. id "package.path" .. [[, using the environment variable ]] .. id "LUA_CPATH_5_4" .. [[, or the environment variable ]] .. id "LUA_CPATH" .. [[, or a default path defined in ]] .. id "luaconf.h" .. [[.]]
212 |
213 | },
214 |
215 |
216 | ["package.loaded"] = {
217 | title = "package.loaded",
218 | body = [[A table used by ]] .. id "require" .. [[ to control which modules are already loaded. When you require a module ]] .. id "modname" .. [[ and ]] .. code "package.loaded[modname]" .. [[ is not false, ]] .. id "require" .. [[ simply returns the value stored there.
219 |
220 | This variable is only a reference to the real table; assignments to this variable do not change the table used by ]] .. id "require" .. [[.]]
221 |
222 | },
223 |
224 |
225 | ["package.loadlib"] = {
226 | title = "package.loadlib (libname, funcname)",
227 | body = [[ Dynamically links the host program with the C library ]] .. id "libname" .. [[.
228 |
229 | If ]] .. id "funcname" .. [[ is ]] .. code "*" .. [[, then it only links with the library, making the symbols exported by the library available to other dynamically linked libraries. Otherwise, it looks for a function ]] .. id "funcname" .. [[ inside the library and returns this function as a C function. So, ]] .. id "funcname" .. [[ must follow the ]] .. id "lua_CFunction" .. [[ prototype lua_CFunction.
230 |
231 | This is a low-level function. It completely bypasses the package and module system. Unlike ]] .. id "require" .. [[, it does not perform any path searching and does not automatically adds extensions. ]] .. id "libname" .. [[ must be the complete file name of the C library, including if necessary a path and an extension. ]] .. id "funcname" .. [[ must be the exact name exported by the C library (which may depend on the C compiler and linker used).
232 |
233 | This function is not supported by Standard C. As such, it is only available on some platforms (Windows, Linux, Mac OS X, Solaris, BSD, plus other Unix systems that support the ]] .. id "dlfcn" .. [[ standard). ]] },
234 |
235 |
236 | ["package.path"] = {
237 | title = "package.path",
238 | body = [[The path used by ]] .. id "require" .. [[ to search for a Lua loader.
239 |
240 | At start-up, Lua initializes this variable with the value of the environment variable ]] .. id "LUA_PATH_5_4" .. [[ or the environment variable ]] .. id "LUA_PATH" .. [[ or with a default path defined in ]] .. id "luaconf.h" .. [[, if those environment variables are not defined. Any ]] .. code ";;" .. [[ in the value of the environment variable is replaced by the default path.]] },
241 |
242 |
243 | ["package.preload"] = {
244 | title = "package.preload",
245 | body = [[A table to store loaders for specific modules ]] .. id "require" .. [[.
246 |
247 | This variable is only a reference to the real table; assignments to this variable do not change the table used by ]] .. id "require" .. [[.]]
248 |
249 | },
250 |
251 |
252 | ["package.searchers"] = {
253 | title = "package.searchers",
254 | body = [[A table used by ]] .. id "require" .. [[ to control how to load modules.
255 |
256 | Each entry in this table is a searcher function. When looking for a module, ]] .. id "require" .. [[ calls each of these searchers in ascending order, with the module name (the argument given to ]] .. id "require" .. [[) as its sole argument. The function can return another function (the module loader) plus an extra value that will be passed to that loader, or a string explaining why it did not find that module (or ]] .. code "nil" .. [[ if it has nothing to say).
257 |
258 | Lua initializes this table with four searcher functions.
259 |
260 | The first searcher simply looks for a loader in the ]] .. id "package.preload" .. [[ table.
261 |
262 | The second searcher looks for a loader as a Lua library, using the path stored at ]] .. id "package.path" .. [[. The search is done as described in function ]] .. id "package.searchpath" .. [[.
263 |
264 | The third searcher looks for a loader as a C library, using the path given by the variable ]] .. id "package.cpath" .. [[. Again, the search is done as described in function ]] .. id "package.searchpath" .. [[. For instance, if the C path is the string ]] .. code " \"./?.so;./?.dll;/usr/local/?/init.so\" " .. [[
265 | the searcher for module ]] .. id "foo" .. [[ will try to open the files ]] .. code "./foo.so" .. [[, ]] .. code "./foo.dll" .. [[, and ]] .. code "/usr/local/foo/init.so" .. [[, in that order. Once it finds a C library, this searcher first uses a dynamic link facility to link the application with the library. Then it tries to find a C function inside the library to be used as the loader. The name of this C function is the string ]] .. code "luaopen_" .. [[ concatenated with a copy of the module name where each dot is replaced by an underscore. Moreover, if the module name has a hyphen, its suffix after (and including) the first hyphen is removed. For instance, if the module name is ]] .. id "a.b.c-v2.1" .. [[, the function name will be ]] .. id "luaopen_a_b_c" .. [[.
266 |
267 | The fourth searcher tries an all-in-one loader. It searches the C path for a library for the root name of the given module. For instance, when requiring ]] .. id "a.b.c" .. [[, it will search for a C library for ]] .. id "a" .. [[. If found, it looks into it for an open function for the submodule; in our example, that would be ]] .. id "luaopen_a_b_c" .. [[. With this facility, a package can pack several C submodules into one single library, with each submodule keeping its original open function.
268 |
269 | All searchers except the first one (preload) return as the extra value the file name where the module was found, as returned by ]] .. id "package.searchpath" .. [[. The first searcher returns no extra value.]]
270 |
271 | },
272 |
273 |
274 | ["package.searchpath"] = {
275 | title = "package.searchpath (name, path [, sep [, rep]])",
276 | body = [[ Searches for the given ]] .. id "name" .. [[ in the given ]] .. id "path" .. [[.
277 |
278 | A path is a string containing a sequence of templates separated by semicolons. For each template, the function replaces each interrogation mark (if any) in the template with a copy of ]] .. id "name" .. [[ wherein all occurrences of ]] .. id "sep" .. [[ (a dot, by default) were replaced by ]] .. id "rep" .. [[ (the system's directory separator, by default), and then tries to open the resulting file name.
279 |
280 | For instance, if the path is the string ]] .. code " \"./?.lua;./?.lc;/usr/local/?/init.lua\" " .. [[
281 | the search for the name ]] .. id "foo.a" .. [[ will try to open the files ]] .. code "./foo/a.lua" .. [[, ]] .. code "./foo/a.lc" .. [[, and ]] .. code "/usr/local/foo/a/init.lua" .. [[, in that order.
282 |
283 | Returns the resulting name of the first file that it can open in read mode (after closing the file), or ]] .. code "nil" .. [[ plus an error message if none succeeds. (This error message lists all file names it tried to open.) ]] },
284 |
285 |
286 | ["string.byte"] = {
287 | title = "string.byte (s [, i [, j]])",
288 | body = [[ Returns the internal numeric codes of the characters ]] .. code "s[i]" .. [[, ]] .. code "s[i+1]" .. [[, .., ]] .. code "s[j]" .. [[. The default value for ]] .. id "i" .. [[ is 1; the default value for ]] .. id "j" .. [[ is ]] .. id "i" .. [[. These indices are corrected following the same rules of function ]] .. id "string.sub" .. [[.
289 |
290 | Numeric codes are not necessarily portable across platforms. ]] },
291 | ["string.char"] = {
292 | title = "string.char (...)",
293 | body = [[ Receives zero or more integers. Returns a string with length equal to the number of arguments, in which each character has the internal numeric code equal to its corresponding argument.
294 |
295 | Numeric codes are not necessarily portable across platforms. ]] },
296 | ["string.dump"] = {
297 | title = "string.dump (function [, strip])",
298 | body = [[Returns a string containing a binary representation (a binary chunk) of the given function, so that a later ]] .. id "load" .. [[ on this string returns a copy of the function (but with new upvalues). If ]] .. id "strip" .. [[ is a true value, the binary representation may not include all debug information about the function, to save space.
299 |
300 | Functions with upvalues have only their number of upvalues saved. When (re)loaded, those upvalues receive fresh instances containing ]] .. code "nil" .. [[. (You can use the debug library to serialize and reload the upvalues of a function in a way adequate to your needs.) ]] },
301 | ["string.find"] = {
302 | title = "string.find (s, pattern [, init [, plain]])",
303 | body = [[Looks for the first match of ]] .. id "pattern" .. [[ ]] .. id "pm" .. [[ in the string ]] .. id "s" .. [[. If it finds a match, then ]] .. id "find" .. [[ returns the indices of ]] .. code "s" .. [[ where this occurrence starts and ends; otherwise, it returns ]] .. code "nil" .. [[. A third, optional numeric argument ]] .. id "init" .. [[ specifies where to start the search; its default value is 1 and can be negative. A value of ]] .. code "true" .. [[ as a fourth, optional argument ]] .. id "plain" .. [[ turns off the pattern matching facilities, so the function does a plain find substring operation, with no characters in ]] .. id "pattern" .. [[ being considered magic. Note that if ]] .. id "plain" .. [[ is given, then ]] .. id "init" .. [[ must be given as well.
304 |
305 | If the pattern has captures, then in a successful match the captured values are also returned, after the two indices. ]] },
306 | ["string.format"] = {
307 | title = "string.format (formatstring, ...)",
308 | body = [[Returns a formatted version of its variable number of arguments following the description given in its first argument (which must be a string). The format string follows the same rules as the ]] .. id "sprintf" .. [[. The only differences are that the options/modifiers ]] .. code "*" .. [[, ]] .. id "h" .. [[, ]] .. id "L" .. [[, ]] .. id "l" .. [[, ]] .. id "n" .. [[, and ]] .. id "p" .. [[ are not supported and that there is an extra option, ]] .. id "q" .. [[.
309 |
310 | The ]] .. id "q" .. [[ option formats booleans, nil, numbers, and strings in a way that the result is a valid constant in Lua source code. Booleans and nil are written in the obvious way (]] .. id "true" .. [[, ]] .. id "false" .. [[, ]] .. id "nil" .. [[). Floats are written in hexadecimal, to preserve full precision. A string is written between double quotes, using escape sequences when necessary to ensure that it can safely be read back by the Lua interpreter. For instance, the call ]] .. code " string.format('%q', 'a string with \"quotes\" and \n new line') " .. [[
311 | may produce the string: ]] .. code " \"a string with \"quotes\" and \\ new line\" " .. [[
312 |
313 | Options ]] .. id "A" .. [[, ]] .. id "a" .. [[, ]] .. id "E" .. [[, ]] .. id "e" .. [[, ]] .. id "f" .. [[, ]] .. id "G" .. [[, and ]] .. id "g" .. [[ all expect a number as argument. Options ]] .. id "c" .. [[, ]] .. id "d" .. [[, ]] .. id "i" .. [[, ]] .. id "o" .. [[, ]] .. id "u" .. [[, ]] .. id "X" .. [[, and ]] .. id "x" .. [[ expect an integer. When Lua is compiled with a C89 compiler, options ]] .. id "A" .. [[ and ]] .. id "a" .. [[ (hexadecimal floats) do not support any modifier (flags, width, length).
314 |
315 | Option ]] .. id "s" .. [[ expects a string; if its argument is not a string, it is converted to one following the same rules of ]] .. id "tostring" .. [[. If the option has any modifier (flags, width, length), the string argument should not contain embedded zeros. ]] },
316 | ["string.gmatch"] = {
317 | title = "string.gmatch (s, pattern [, init])",
318 | body = [[ Returns an iterator function that, each time it is called, returns the next captures from ]] .. id "pattern" .. [[ ]] .. id "pm" .. [[ over the string ]] .. id "s" .. [[. If ]] .. id "pattern" .. [[ specifies no captures, then the whole match is produced in each call. A third, optional numeric argument ]] .. id "init" .. [[ specifies where to start the search; its default value is 1 and can be negative.
319 |
320 | As an example, the following loop will iterate over all the words from string ]] .. id "s" .. [[, printing one per line: ]] .. code " s = \"hello world from Lua\" for w in string.gmatch(s, \"%a+\") do print(w) end " .. [[
321 | The next example collects all pairs ]] .. code "key=value" .. [[ from the given string into a table: ]] .. code " t = {" .. [[ s = "from=world, to=Lua" for k, v in string.gmatch(s, "(%w+)=(%w+)") do t[k] = v end }
322 |
323 | For this function, a caret ]] .. code "^" .. [[ at the start of a pattern does not work as an anchor, as this would prevent the iteration. ]] },
324 | ["string.gsub"] = {
325 | title = "string.gsub (s, pattern, repl [, n])",
326 | body = [[ Returns a copy of ]] .. id "s" .. [[ in which all (or the first ]] .. id "n" .. [[, if given) occurrences of the ]] .. id "pattern" .. [[ ]] .. id "pm" .. [[ have been replaced by a replacement string specified by ]] .. id "repl" .. [[, which can be a string, a table, or a function. ]] .. id "gsub" .. [[ also returns, as its second value, the total number of matches that occurred. The name ]] .. id "gsub" .. [[ comes from Global SUBstitution.
327 |
328 | If ]] .. id "repl" .. [[ is a string, then its value is used for replacement. The character ]] .. code "%" .. [[ works as an escape character: any sequence in ]] .. id "repl" .. [[ of the form ]] .. code "%@rep{d" .. [[}, with @rep{d} between 1 and 9, stands for the value of the @rep{d}-th captured substring. The sequence ]] .. code "%0" .. [[ stands for the whole match. The sequence ]] .. code "%%" .. [[ stands for a single ]] .. code "%" .. [[.
329 |
330 | If ]] .. id "repl" .. [[ is a table, then the table is queried for every match, using the first capture as the key.
331 |
332 | If ]] .. id "repl" .. [[ is a function, then this function is called every time a match occurs, with all captured substrings passed as arguments, in order.
333 |
334 | In any case, if the pattern specifies no captures, then it behaves as if the whole pattern was inside a capture.
335 |
336 | If the value returned by the table query or by the function call is a string or a number, then it is used as the replacement string; otherwise, if it is ]] .. keyword "false" .. [[ or ]] .. code "nil" .. [[, then there is no replacement (that is, the original match is kept in the string).
337 |
338 | Here are some examples: ]] .. code [[ x = string.gsub("hello world", "(%w+)", "%1 %1") --> x="hello hello world world"
339 |
340 | x = string.gsub("hello world", "%w+", "%0 %0", 1) --> x="hello hello world"
341 |
342 | x = string.gsub("hello world from Lua", "(%w+)%s*(%w+)", "%2 %1") --> x="world hello Lua from"
343 |
344 | x = string.gsub("home = $HOME, user = $USER", "%$(%w+)", os.getenv) --> x="home = /home/roberto, user = roberto"
345 |
346 | x = string.gsub("4+5 = $return 4+5$", "%$(.-)%$", function (s) return load(s)() end) --> x="4+5 = 9"
347 |
348 | local t = {name="lua", version="5.4" x = string.gsub("$name-$version.tar.gz", "%$(%w+)", t) --> x="lua-5.4.tar.gz" }]] },
349 | ["string.len"] = {
350 | title = "string.len (s)",
351 | body = [[ Receives a string and returns its length. The empty string ]] .. code "\"\"" .. [[ has length 0. Embedded zeros are counted, so ]] .. code "\"a\000bc\000\"" .. [[ has length 5. ]] },
352 | ["string.lower"] = {
353 | title = "string.lower (s)",
354 | body = [[ Receives a string and returns a copy of this string with all uppercase letters changed to lowercase. All other characters are left unchanged. The definition of what an uppercase letter is depends on the current locale. ]] },
355 | ["string.match"] = {
356 | title = "string.match (s, pattern [, init])",
357 | body = [[ Looks for the first match of ]] .. id "pattern" .. [[ ]] .. id "pm" .. [[ in the string ]] .. id "s" .. [[. If it finds one, then ]] .. id "match" .. [[ returns the captures from the pattern; otherwise it returns ]] .. code "nil" .. [[. If ]] .. id "pattern" .. [[ specifies no captures, then the whole match is returned. A third, optional numeric argument ]] .. id "init" .. [[ specifies where to start the search; its default value is 1 and can be negative. ]] },
358 | ["string.pack"] = {
359 | title = "string.pack (fmt, v1, v2, ...)",
360 | body = [[Returns a binary string containing the values ]] .. id "v1" .. [[, ]] .. id "v2" .. [[, etc. packed (that is, serialized in binary form) according to the format string ]] .. id "fmt" .. [[ ]] .. id "pack" .. [[. ]] },
361 | ["string.packsize"] = {
362 | title = "string.packsize (fmt)",
363 | body = [[Returns the size of a string resulting from ]] .. id "string.pack" .. [[ with the given format. The format string cannot have the variable-length options ]] .. code "s" .. [[ or ]] .. code "z" .. [[ ]] .. id "pack" .. [[. ]] },
364 | ["string.rep"] = {
365 | title = "string.rep (s, n [, sep])",
366 | body = [[ Returns a string that is the concatenation of ]] .. id "n" .. [[ copies of the string ]] .. id "s" .. [[ separated by the string ]] .. id "sep" .. [[. The default value for ]] .. id "sep" .. [[ is the empty string (that is, no separator). Returns the empty string if ]] .. id "n" .. [[ is not positive.
367 |
368 | (Note that it is very easy to exhaust the memory of your machine with a single call to this function.) ]] },
369 | ["string.reverse"] = {
370 | title = "string.reverse (s)",
371 | body = [[ Returns a string that is the string ]] .. id "s" .. [[ reversed. ]] },
372 | ["string.sub"] = {
373 | title = "string.sub (s, i [, j])",
374 | body = [[ Returns the substring of ]] .. id "s" .. [[ that starts at ]] .. id "i" .. [[ and continues until ]] .. id "j" .. [[; ]] .. id "i" .. [[ and ]] .. id "j" .. [[ can be negative. If ]] .. id "j" .. [[ is absent, then it is assumed to be equal to ]] .. code "-1" .. [[ (which is the same as the string length). In particular, the call ]] .. code "string.sub(s,1,j)" .. [[ returns a prefix of ]] .. id "s" .. [[ with length ]] .. id "j" .. [[, and ]] .. code "string.sub(s, -i)" .. [[ (for a positive ]] .. id "i" .. [[) returns a suffix of ]] .. id "s" .. [[ with length ]] .. id "i" .. [[.
375 |
376 | If, after the translation of negative indices, ]] .. id "i" .. [[ is less than 1, it is corrected to 1. If ]] .. id "j" .. [[ is greater than the string length, it is corrected to that length. If, after these corrections, ]] .. id "i" .. [[ is greater than ]] .. id "j" .. [[, the function returns the empty string. ]] },
377 | ["string.unpack"] = {
378 | title = "string.unpack (fmt, s [, pos])",
379 | body = [[Returns the values packed in string ]] .. id "s" .. [[ ]] .. id "string.pack" .. [[ according to the format string ]] .. id "fmt" .. [[ ]] .. id "pack" .. [[. An optional ]] .. id "pos" .. [[ marks where to start reading in ]] .. id "s" .. [[ (default is 1). After the read values, this function also returns the index of the first unread byte in ]] .. id "s" .. [[. ]] },
380 | ["string.upper"] = {
381 | title = "string.upper (s)",
382 | body = [[ Receives a string and returns a copy of this string with all lowercase letters changed to uppercase. All other characters are left unchanged. The definition of what a lowercase letter is depends on the current locale. ]] },
383 | ["utf8.char"] = {
384 | title = "utf8.char (...)",
385 | body = [[ Receives zero or more integers, converts each one to its corresponding UTF-8 byte sequence and returns a string with the concatenation of all these sequences. ]] },
386 | ["utf8.charpattern"] = {
387 | title = "utf8.charpattern",
388 | body = [[The pattern (a string, not a function) ]] .. code "[\0-\x7F\xC2-\xF4][\x80-\xBF]*" .. [[ ]] .. id "pm" .. [[, which matches exactly one UTF-8 byte sequence, assuming that the subject is a valid UTF-8 string.]] },
389 |
390 |
391 | ["utf8.codes"] = {
392 | title = "utf8.codes (s)",
393 | body = [[ Returns values so that the construction ]] .. code " for p, c in utf8.codes(s) do @rep{body" .. [[ end }
394 | will iterate over all characters in string ]] .. id "s" .. [[, with ]] .. id "p" .. [[ being the position (in bytes) and ]] .. id "c" .. [[ the code point of each character. It raises an error if it meets any invalid byte sequence. ]] },
395 | ["utf8.codepoint"] = {
396 | title = "utf8.codepoint (s [, i [, j]])",
397 | body = [[ Returns the codepoints (as integers) from all characters in ]] .. id "s" .. [[ that start between byte position ]] .. id "i" .. [[ and ]] .. id "j" .. [[ (both included). The default for ]] .. id "i" .. [[ is 1 and for ]] .. id "j" .. [[ is ]] .. id "i" .. [[. It raises an error if it meets any invalid byte sequence. ]] },
398 | ["utf8.len"] = {
399 | title = "utf8.len (s [, i [, j]])",
400 | body = [[ Returns the number of UTF-8 characters in string ]] .. id "s" .. [[ that start between positions ]] .. id "i" .. [[ and ]] .. id "j" .. [[ (both inclusive). The default for ]] .. id "i" .. [[ is ]] .. code "1" .. [[ and for ]] .. id "j" .. [[ is ]] .. code "-1" .. [[. If it finds any invalid byte sequence, returns a false value plus the position of the first invalid byte. ]] },
401 | ["utf8.offset"] = {
402 | title = "utf8.offset (s, n [, i])",
403 | body = [[ Returns the position (in bytes) where the encoding of the ]] .. id "n" .. [[-th character of ]] .. id "s" .. [[ (counting from position ]] .. id "i" .. [[) starts. A negative ]] .. id "n" .. [[ gets characters before position ]] .. id "i" .. [[. The default for ]] .. id "i" .. [[ is 1 when ]] .. id "n" .. [[ is non-negative and ]] .. code "#s + 1" .. [[ otherwise, so that ]] .. code "utf8.offset(s, -n)" .. [[ gets the offset of the ]] .. id "n" .. [[-th character from the end of the string. If the specified character is neither in the subject nor right after its end, the function returns ]] .. code "nil" .. [[.
404 |
405 | As a special case, when ]] .. id "n" .. [[ is 0 the function returns the start of the encoding of the character that contains the ]] .. id "i" .. [[-th byte of ]] .. id "s" .. [[.
406 |
407 | This function assumes that ]] .. id "s" .. [[ is a valid UTF-8 string.
408 |
409 | } ]] },
410 | ["table.concat"] = {
411 | title = "table.concat (list [, sep [, i [, j]]])",
412 | body = [[Given a list where all elements are strings or numbers, returns the string ]] .. code "list[i]..sep..list[i+1] ... sep..list[j]" .. [[. The default value for ]] .. id "sep" .. [[ is the empty string, the default for ]] .. id "i" .. [[ is 1, and the default for ]] .. id "j" .. [[ is ]] .. code "#list" .. [[. If ]] .. id "i" .. [[ is greater than ]] .. id "j" .. [[, returns the empty string. ]] },
413 | ["table.insert"] = {
414 | title = "table.insert (list, [pos,] value)",
415 | body = [[Inserts element ]] .. id "value" .. [[ at position ]] .. id "pos" .. [[ in ]] .. id "list" .. [[, shifting up the elements ]] .. code "list[pos], list[pos+1], ..., list[#list]" .. [[. The default value for ]] .. id "pos" .. [[ is ]] .. code "#list+1" .. [[, so that a call ]] .. code "table.insert(t,x)" .. [[ inserts ]] .. id "x" .. [[ at the end of list ]] .. id "t" .. [[. ]] },
416 | ["table.move"] = {
417 | title = "table.move (a1, f, e, t [,a2])",
418 | body = [[Moves elements from table ]] .. id "a1" .. [[ to table ]] .. id "a2" .. [[, performing the equivalent to the following multiple assignment: ]] .. code "a2[t],... = a1[f],...,a1[e]" .. [[. The default for ]] .. id "a2" .. [[ is ]] .. id "a1" .. [[. The destination range can overlap with the source range. The number of elements to be moved must fit in a Lua integer.
419 |
420 | Returns the destination table ]] .. id "a2" .. [[. ]] },
421 | ["table.pack"] = {
422 | title = "table.pack (...)",
423 | body = [[Returns a new table with all arguments stored into keys 1, 2, etc. and with a field ]] .. code "n" .. [[ with the total number of arguments. Note that the resulting table may not be a sequence, if some arguments are ]] .. code "nil" .. [[. ]] },
424 | ["table.remove"] = {
425 | title = "table.remove (list [, pos])",
426 | body = [[Removes from ]] .. id "list" .. [[ the element at position ]] .. id "pos" .. [[, returning the value of the removed element. When ]] .. id "pos" .. [[ is an integer between 1 and ]] .. code "#list" .. [[, it shifts down the elements ]] .. code "list[pos+1], list[pos+2], ..., list[#list]" .. [[ and erases element ]] .. code "list[#list]" .. [[; The index ]] .. id "pos" .. [[ can also be 0 when ]] .. code "#list" .. [[ is 0, or ]] .. code "#list + 1" .. [[.
427 |
428 | The default value for ]] .. id "pos" .. [[ is ]] .. code "#list" .. [[, so that a call ]] .. code "table.remove(l)" .. [[ removes the last element of list ]] .. id "l" .. [[. ]] },
429 | ["table.sort"] = {
430 | title = "table.sort (list [, comp])",
431 | body = [[Sorts list elements in a given order, in-place, from ]] .. code "list[1]" .. [[ to ]] .. code "list[#list]" .. [[. If ]] .. id "comp" .. [[ is given, then it must be a function that receives two list elements and returns true when the first element must come before the second in the final order (so that, after the sort, ]] .. code "i < j" .. [[ implies ]] .. code "not comp(list[j],list[i])" .. [[). If ]] .. id "comp" .. [[ is not given, then the standard Lua operator ]] .. code "<" .. [[ is used instead.
432 |
433 | Note that the ]] .. id "comp" .. [[ function must define a strict partial order over the elements in the list; that is, it must be asymmetric and transitive. Otherwise, no valid sort may be possible.
434 |
435 | The sort algorithm is not stable: elements considered equal by the given order may have their relative positions changed by the sort. ]] },
436 | ["table.unpack"] = {
437 | title = "table.unpack (list [, i [, j]])",
438 | body = [[Returns the elements from the given list. This function is equivalent to ]] .. code " return list[i], list[i+1], ..., list[j] " .. [[
439 | By default, ]] .. id "i" .. [[ is 1 and ]] .. id "j" .. [[ is ]] .. code "#list" .. [[.
440 |
441 | } ]] },
442 | ["math.abs"] = {
443 | title = "math.abs (x)",
444 | body = [[Returns the absolute value of ]] .. id "x" .. [[. (integer/float) ]] },
445 | ["math.acos"] = {
446 | title = "math.acos (x)",
447 | body = [[Returns the arc cosine of ]] .. id "x" .. [[ (in radians). ]] },
448 | ["math.asin"] = {
449 | title = "math.asin (x)",
450 | body = [[Returns the arc sine of ]] .. id "x" .. [[ (in radians). ]] },
451 | ["math.atan"] = {
452 | title = "math.atan (y [, x])",
453 | body = [[@index{atan2} Returns the arc tangent of ]] .. code "y/x" .. [[ (in radians), but uses the signs of both arguments to find the quadrant of the result. (It also handles correctly the case of ]] .. id "x" .. [[ being zero.)
454 |
455 | The default value for ]] .. id "x" .. [[ is 1, so that the call ]] .. code "math.atan(y)" .. [[ returns the arc tangent of ]] .. id "y" .. [[. ]] },
456 | ["math.ceil"] = {
457 | title = "math.ceil (x)",
458 | body = [[Returns the smallest integral value larger than or equal to ]] .. id "x" .. [[. ]] },
459 | ["math.cos"] = {
460 | title = "math.cos (x)",
461 | body = [[Returns the cosine of ]] .. id "x" .. [[ (assumed to be in radians). ]] },
462 | ["math.deg"] = {
463 | title = "math.deg (x)",
464 | body = [[Converts the angle ]] .. id "x" .. [[ from radians to degrees. ]] },
465 | ["math.exp"] = {
466 | title = "math.exp (x)",
467 | body = [[Returns the value esp{x} (where ]] .. id "e" .. [[ is the base of natural logarithms). ]] },
468 | ["math.floor"] = {
469 | title = "math.floor (x)",
470 | body = [[Returns the largest integral value smaller than or equal to ]] .. id "x" .. [[. ]] },
471 | ["math.fmod"] = {
472 | title = "math.fmod (x, y)",
473 | body = [[Returns the remainder of the division of ]] .. id "x" .. [[ by ]] .. id "y" .. [[ that rounds the quotient towards zero. (integer/float) ]] },
474 | ["math.huge"] = {
475 | title = "math.huge",
476 | body = [[The float value ]] .. id "HUGE_VAL" .. [[, a value larger than any other numeric value.]] },
477 |
478 |
479 | ["math.log"] = {
480 | title = "math.log (x [, base])",
481 | body = [[ Returns the logarithm of ]] .. id "x" .. [[ in the given base. The default for ]] .. id "base" .. [[ is e (so that the function returns the natural logarithm of ]] .. id "x" .. [[). ]] },
482 | ["math.max"] = {
483 | title = "math.max (x, ...)",
484 | body = [[Returns the argument with the maximum value, according to the Lua operator ]] .. code "<" .. [[. (integer/float) ]] },
485 | ["math.maxinteger"] = {
486 | title = "math.maxinteger", body = "An integer with the maximum value for an integer." },
487 |
488 |
489 | ["math.min"] = {
490 | title = "math.min (x, ...)",
491 | body = [[ Returns the argument with the minimum value, according to the Lua operator ]] .. code "<" .. [[. (integer/float) ]] },
492 |
493 |
494 | ["math.mininteger"] = {
495 | title = "math.mininteger",
496 | body = [[An integer with the minimum value for an integer.]] },
497 |
498 |
499 | ["math.modf"] = {
500 | title = "math.modf (x)",
501 | body = [[ Returns the integral part of ]] .. id "x" .. [[ and the fractional part of ]] .. id "x" .. [[. Its second result is always a float. ]] },
502 |
503 |
504 | ["math.pi"] = {
505 | title = "math.pi",
506 | body = [[The value of @pi.]]},
507 |
508 |
509 | ["math.rad"] = {
510 | title = "math.rad (x)",
511 | body = [[ Converts the angle ]] .. id "x" .. [[ from degrees to radians. ]] },
512 | ["math.random"] = {
513 | title = "math.random ([m [, n]])",
514 | body = [[When called without arguments, returns a pseudo-random float with uniform distribution in the range ]] .. code "(" .. [[ [0,1). ]] .. code "]" .. [[ When called with two integers ]] .. id "m" .. [[ and ]] .. id "n" .. [[, ]] .. id "math.random" .. [[ returns a pseudo-random integer with uniform distribution in the range [m, n]. The call ]] .. code "math.random(n)" .. [[, for a positive ]] .. id "n" .. [[, is equivalent to ]] .. code "math.random(1,n)" .. [[. The call ]] .. code "math.random(0)" .. [[ produces an integer with all bits (pseudo)random.
515 |
516 | Lua initializes its pseudo-random generator with a weak attempt for ``randomness'', so that ]] .. id "math.random" .. [[ should generate different sequences of results each time the program runs. To ensure a required level of randomness to the initial state (or contrarily, to have a deterministic sequence, for instance when debugging a program), you should call ]] .. id "math.randomseed" .. [[ explicitly.
517 |
518 | The results from this function have good statistical qualities, but they are not cryptographically secure. (For instance, there are no guarantees that it is hard to predict future results based on the observation of some number of previous results.) ]] },
519 | ["math.randomseed"] = {
520 | title = "math.randomseed (x [, y])",
521 | body = [[The integer parameters ]] .. id "x" .. [[ and ]] .. id "y" .. [[ are concatenated into a 128-bit seed that is used to reinitialize the pseudo-random generator; equal seeds produce equal sequences of numbers. The default for ]] .. id "y" .. [[ is zero. ]] },
522 | ["math.sin"] = {
523 | title = "math.sin (x)",
524 | body = [[Returns the sine of ]] .. id "x" .. [[ (assumed to be in radians). ]] },
525 | ["math.sqrt"] = {
526 | title = "math.sqrt (x)",
527 | body = [[Returns the square root of ]] .. id "x" .. [[. (You can also use the expression ]] .. code "x^0.5" .. [[ to compute this value.) ]] },
528 | ["math.tan"] = {
529 | title = "math.tan (x)",
530 | body = [[Returns the tangent of ]] .. id "x" .. [[ (assumed to be in radians). ]] },
531 | ["math.tointeger"] = {
532 | title = "math.tointeger (x)",
533 | body = [[If the value ]] .. id "x" .. [[ is convertible to an integer, returns that integer. Otherwise, returns ]] .. code "nil" .. [[. ]] },
534 | ["math.type"] = {
535 | title = "math.type (x)",
536 | body = [[Returns ]] .. code "integer" .. [[ if ]] .. id "x" .. [[ is an integer, ]] .. code "float" .. [[ if it is a float, or ]] .. code "nil" .. [[ if ]] .. id "x" .. [[ is not a number. ]] },
537 | ["math.ult"] = {
538 | title = "math.ult (m, n)",
539 | body = [[Returns a boolean, true if and only if integer ]] .. id "m" .. [[ is below integer ]] .. id "n" .. [[ when they are compared as unsigned integers.
540 |
541 | } ]] },
542 | ["io.close"] = {
543 | title = "io.close ([file])",
544 | body = [[Equivalent to ]] .. code "file:close()" .. [[. Without a ]] .. id "file" .. [[, closes the default output file. ]] },
545 | ["io.flush"] = {
546 | title = "io.flush ()",
547 | body = [[Equivalent to ]] .. code "io.output():flush()" .. [[. ]] },
548 | ["io.input"] = {
549 | title = "io.input ([file])",
550 | body = [[When called with a file name, it opens the named file (in text mode), and sets its handle as the default input file. When called with a file handle, it simply sets this file handle as the default input file. When called without arguments, it returns the current default input file.
551 |
552 | In case of errors this function raises the error, instead of returning an error code. ]] },
553 | ["io.lines"] = {
554 | title = "io.lines ([filename, ...])",
555 | body = [[Opens the given file name in read mode and returns an iterator function that works like ]] .. code "file:lines(...)" .. [[ over the opened file. When the iterator function detects the end of file, it returns no values (to finish the loop) and automatically closes the file. Besides the iterator function, ]] .. id "io.lines" .. [[ returns three other values: two ]] .. code "nil" .. [[ values as placeholders, plus the created file handle. Therefore, when used in a generic ]] .. keyword "for" .. [[ loop, the file is closed also if the loop is interrupted by an error or a ]] .. keyword "break" .. [[.
556 |
557 | The call ]] .. code "io.lines()" .. [[ (with no file name) is equivalent to ]] .. code "io.input():lines(\"l\")" .. [[; that is, it iterates over the lines of the default input file. In this case, the iterator does not close the file when the loop ends.
558 |
559 | In case of errors this function raises the error, instead of returning an error code. ]] },
560 | ["io.open"] = {
561 | title = "io.open (filename [, mode])",
562 | body = [[This function opens a file, in the mode specified in the string ]] .. id "mode" .. [[. In case of success, it returns a new file handle.
563 |
564 | The ]] .. id "mode" .. [[ string can be any of the following:
565 |
566 | ・ ]] .. code "r" .. [[| read mode (the default);} ・ ]] .. code "w" .. [[| write mode;} ・ ]] .. code "a" .. [[| append mode;} ・ ]] .. code "r+" .. [[| update mode, all previous data is preserved;} ・ ]] .. code "w+" .. [[| update mode, all previous data is erased;} ・ ]] .. code "a+" .. [[| append update mode, previous data is preserved, writing is only allowed at the end of file.} }
567 | The ]] .. id "mode" .. [[ string can also have a ]] .. code "b" .. [[ at the end, which is needed in some systems to open the file in binary mode. ]] },
568 | ["io.output"] = {
569 | title = "io.output ([file])",
570 | body = [[Similar to ]] .. id "io.input" .. [[, but operates over the default output file. ]] },
571 | ["io.popen"] = {
572 | title = "io.popen (prog [, mode])",
573 | body = [[This function is system dependent and is not available on all platforms.
574 |
575 | Starts program ]] .. id "prog" .. [[ in a separated process and returns a file handle that you can use to read data from this program (if ]] .. id "mode" .. [[ is ]] .. code "\"r\"" .. [[, the default) or to write data to this program (if ]] .. id "mode" .. [[ is ]] .. code "\"w\"" .. [[). ]] },
576 | ["io.read"] = {
577 | title = "io.read (...)",
578 | body = [[Equivalent to ]] .. code "io.input():read(...)" .. [[. ]] },
579 | ["io.tmpfile"] = {
580 | title = "io.tmpfile ()",
581 | body = [[In case of success, returns a handle for a temporary file. This file is opened in update mode and it is automatically removed when the program ends. ]] },
582 | ["io.type"] = {
583 | title = "io.type (obj)",
584 | body = [[Checks whether ]] .. id "obj" .. [[ is a valid file handle. Returns the string ]] .. code "\"file\"" .. [[ if ]] .. id "obj" .. [[ is an open file handle, ]] .. code "\"closed file\"" .. [[ if ]] .. id "obj" .. [[ is a closed file handle, or ]] .. code "nil" .. [[ if ]] .. id "obj" .. [[ is not a file handle. ]] },
585 | ["io.write"] = {
586 | title = "io.write (...)",
587 | body = [[Equivalent to ]] .. code "io.output():write(...)" .. [[.
588 |
589 | ]] },
590 | ["file:close"] = {
591 | title = "file:close ()",
592 | body = [[Closes ]] .. id "file" .. [[. Note that files are automatically closed when their handles are garbage collected, but that takes an unpredictable amount of time to happen.
593 |
594 | When closing a file handle created with ]] .. id "io.popen" .. [[, ]] .. id "file:close" .. [[ returns the same values returned by ]] .. id "os.execute" .. [[. ]] },
595 | ["file:flush"] = {
596 | title = "file:flush ()",
597 | body = [[Saves any written data to ]] .. id "file" .. [[. ]] },
598 | ["file:lines"] = {
599 | title = "file:lines (...)",
600 | body = [[Returns an iterator function that, each time it is called, reads the file according to the given formats. When no format is given, uses ]] .. code "l" .. [[ as a default. As an example, the construction ]] .. code " for c in file:lines(1) do @rep{body" .. [[ end }
601 | will iterate over all characters of the file, starting at the current position. Unlike ]] .. id "io.lines" .. [[, this function does not close the file when the loop ends.
602 |
603 | In case of errors this function raises the error, instead of returning an error code. ]] },
604 | ["file:read"] = {
605 | title = "file:read (...)",
606 | body = [[Reads the file ]] .. id "file" .. [[, according to the given formats, which specify what to read. For each format, the function returns a string or a number with the characters read, or ]] .. code "nil" .. [[ if it cannot read data with the specified format. (In this latter case, the function does not read subsequent formats.) When called without arguments, it uses a default format that reads the next line (see below).
607 |
608 | The available formats are
609 |
610 |
611 | ・ ]] .. code "n" .. [[| reads a numeral and returns it as a float or an integer, following the lexical conventions of Lua. (The numeral may have leading spaces and a sign.) This format always reads the longest input sequence that is a valid prefix for a numeral; if that prefix does not form a valid numeral (e.g., an empty string, ]] .. code "0x" .. [[, or ]] .. code "3.4e-" .. [[), it is discarded and the format returns ]] .. code "nil" .. [[.
612 |
613 | ]] .. code "a" .. [[| reads the whole file, starting at the current position. On end of file, it returns the empty string.
614 |
615 | ]] .. code "l" .. [[| reads the next line skipping the end of line, returning ]] .. code "nil" .. [[ on end of file. This is the default format.
616 |
617 | ]] .. code "L" .. [[| reads the next line keeping the end-of-line character (if present), returning ]] .. code "nil" .. [[ on end of file. }
618 |
619 | ・ number| reads a string with up to this number of bytes, returning ]] .. code "nil" .. [[ on end of file. If ]] .. id "number" .. [[ is zero, it reads nothing and returns an empty string, or ]] .. code "nil" .. [[ on end of file. }
620 |
621 | } The formats ]] .. code "l" .. [[ and ]] .. code "L" .. [[ should be used only for text files. ]] },
622 | ["file:seek"] = {
623 | title = "file:seek ([whence [, offset]])",
624 | body = [[Sets and gets the file position, measured from the beginning of the file, to the position given by ]] .. id "offset" .. [[ plus a base specified by the string ]] .. id "whence" .. [[, as follows:
625 |
626 | ・ ]] .. code "set" .. [[| base is position 0 (beginning of the file);} ・ ]] .. code "cur" .. [[| base is current position;} ・ ]] .. code "end" .. [[| base is end of file;} }
627 | In case of success, ]] .. id "seek" .. [[ returns the final file position, measured in bytes from the beginning of the file. If ]] .. id "seek" .. [[ fails, it returns ]] .. code "nil" .. [[, plus a string describing the error.
628 |
629 | The default value for ]] .. id "whence" .. [[ is ]] .. code "\"cur\"" .. [[, and for ]] .. id "offset" .. [[ is 0. Therefore, the call ]] .. code "file:seek()" .. [[ returns the current file position, without changing it; the call ]] .. code "file:seek(\"set\")" .. [[ sets the position to the beginning of the file (and returns 0); and the call ]] .. code "file:seek(\"end\")" .. [[ sets the position to the end of the file, and returns its size. ]] },
630 | ["file:setvbuf"] = {
631 | title = "file:setvbuf (mode [, size])",
632 | body = [[Sets the buffering mode for an output file. There are three available modes:
633 |
634 |
635 | ・ ]] .. code "no" .. [[| no buffering; the result of any output operation appears immediately.
636 |
637 | ]] .. code "full" .. [[| full buffering; output operation is performed only when the buffer is full or when you explicitly ]] .. code "flush" .. [[ the file ]] .. id "io.flush" .. [[.
638 |
639 | ]] .. code "line" .. [[| line buffering; output is buffered until a newline is output or there is any input from some special files (such as a terminal device). }
640 |
641 | } For the last two cases, ]] .. id "size" .. [[ specifies the size of the buffer, in bytes. The default is an appropriate size. ]] },
642 | ["file:write"] = {
643 | title = "file:write (...)",
644 | body = [[Writes the value of each of its arguments to ]] .. id "file" .. [[. The arguments must be strings or numbers.
645 |
646 | In case of success, this function returns ]] .. id "file" .. [[. Otherwise it returns ]] .. code "nil" .. [[ plus a string describing the error.
647 |
648 | } ]] },
649 | ["os.clock"] = {
650 | title = "os.clock ()",
651 | body = [[Returns an approximation of the amount in seconds of CPU time used by the program. ]] },
652 | ["os.date"] = {
653 | title = "os.date ([format [, time]])",
654 | body = [[Returns a string or a table containing date and time, formatted according to the given string ]] .. id "format" .. [[.
655 |
656 | If the ]] .. id "time" .. [[ argument is present, this is the time to be formatted (see the ]] .. id "os.time" .. [[ function for a description of this value). Otherwise, ]] .. id "date" .. [[ formats the current time.
657 |
658 | If ]] .. id "format" .. [[ starts with ]] .. code "!" .. [[, then the date is formatted in Coordinated Universal Time. After this optional character, if ]] .. id "format" .. [[ is the string ]] .. code "*t" .. [[, then ]] .. id "date" .. [[ returns a table with the following fields: ]] .. id "year" .. [[, ]] .. id "month" .. [[ (1@En{}12), ]] .. id "day" .. [[ (1@En{}31), ]] .. id "hour" .. [[ (0@En{}23), ]] .. id "min" .. [[ (0@En{}59), ]] .. id "sec" .. [[ (0@En{}61, due to leap seconds), ]] .. id "wday" .. [[ (weekday, 1@En{}7, Sunday is 1), ]] .. id "yday" .. [[ (day of the year, 1@En{}366), and ]] .. id "isdst" .. [[ (daylight saving flag, a boolean). This last field may be absent if the information is not available.
659 |
660 | If ]] .. id "format" .. [[ is not ]] .. code "*t" .. [[, then ]] .. id "date" .. [[ returns the date as a string, formatted according to the same rules as the ]] .. id "strftime" .. [[.
661 |
662 | When called without arguments, ]] .. id "date" .. [[ returns a reasonable date and time representation that depends on the host system and on the current locale. (More specifically, ]] .. code "os.date()" .. [[ is equivalent to ]] .. code "os.date(\"%c\")" .. [[.)
663 |
664 | On non-POSIX systems, this function may be not thread safe because of its reliance on @CId{gmtime} and @CId{localtime}. ]] },
665 | ["os.difftime"] = {
666 | title = "os.difftime (t2, t1)",
667 | body = [[Returns the difference, in seconds, from time ]] .. id "t1" .. [[ to time ]] .. id "t2" .. [[ (where the times are values returned by ]] .. id "os.time" .. [[). In POSIX, Windows, and some other systems, this value is exactly ]] .. id "t2" .. [[-]] .. id "t1" .. [[. ]] },
668 | ["os.execute"] = {
669 | title = "os.execute ([command])",
670 | body = [[This function is equivalent to the ]] .. id "system" .. [[. It passes ]] .. id "command" .. [[ to be executed by an operating system shell. Its first result is ]] .. code "true" .. [[ if the command terminated successfully, or ]] .. code "nil" .. [[ otherwise. After this first result the function returns a string plus a number, as follows:
671 |
672 |
673 | ・ ]] .. code "exit" .. [[| the command terminated normally; the following number is the exit status of the command.
674 |
675 | ]] .. code "signal" .. [[| the command was terminated by a signal; the following number is the signal that terminated the command. }
676 |
677 | }
678 |
679 | When called without a ]] .. id "command" .. [[, ]] .. id "os.execute" .. [[ returns a boolean that is true if a shell is available. ]] },
680 | ["os.exit"] = {
681 | title = "os.exit ([code [, close]])",
682 | body = [[Calls the ]] .. id "exit" .. [[ to terminate the host program. If ]] .. id "code" .. [[ is ]] .. keyword "true" .. [[, the returned status is ]] .. id "EXIT_SUCCESS" .. [[; if ]] .. id "code" .. [[ is ]] .. keyword "false" .. [[, the returned status is ]] .. id "EXIT_FAILURE" .. [[; if ]] .. id "code" .. [[ is a number, the returned status is this number. The default value for ]] .. id "code" .. [[ is ]] .. keyword "true" .. [[.
683 |
684 | If the optional second argument ]] .. id "close" .. [[ is true, closes the Lua state before exiting. ]] },
685 | ["os.getenv"] = {
686 | title = "os.getenv (varname)",
687 | body = [[Returns the value of the process environment variable ]] .. id "varname" .. [[, or ]] .. code "nil" .. [[ if the variable is not defined. ]] },
688 | ["os.remove"] = {
689 | title = "os.remove (filename)",
690 | body = [[Deletes the file (or empty directory, on POSIX systems) with the given name. If this function fails, it returns ]] .. code "nil" .. [[, plus a string describing the error and the error code. Otherwise, it returns true. ]] },
691 | ["os.rename"] = {
692 | title = "os.rename (oldname, newname)",
693 | body = [[Renames the file or directory named ]] .. id "oldname" .. [[ to ]] .. id "newname" .. [[. If this function fails, it returns ]] .. code "nil" .. [[, plus a string describing the error and the error code. Otherwise, it returns true. ]] },
694 | ["os.setlocale"] = {
695 | title = "os.setlocale (locale [, category])",
696 | body = [[Sets the current locale of the program. ]] .. id "locale" .. [[ is a system-dependent string specifying a locale; ]] .. id "category" .. [[ is an optional string describing which category to change: ]] .. code "\"all\"" .. [[, ]] .. code "\"collate\"" .. [[, ]] .. code "\"ctype\"" .. [[, ]] .. code "\"monetary\"" .. [[, ]] .. code "\"numeric\"" .. [[, or ]] .. code "\"time\"" .. [[; the default category is ]] .. code "\"all\"" .. [[. The function returns the name of the new locale, or ]] .. code "nil" .. [[ if the request cannot be honored.
697 |
698 | If ]] .. id "locale" .. [[ is the empty string, the current locale is set to an implementation-defined native locale. If ]] .. id "locale" .. [[ is the string ]] .. code "C" .. [[, the current locale is set to the standard C locale.
699 |
700 | When called with ]] .. code "nil" .. [[ as the first argument, this function only returns the name of the current locale for the given category.
701 |
702 | This function may be not thread safe because of its reliance on @CId{setlocale}. ]] },
703 | ["os.time"] = {
704 | title = "os.time ([table])",
705 | body = [[Returns the current time when called without arguments, or a time representing the local date and time specified by the given table. This table must have fields ]] .. id "year" .. [[, ]] .. id "month" .. [[, and ]] .. id "day" .. [[, and may have fields ]] .. id "hour" .. [[ (default is 12), ]] .. id "min" .. [[ (default is 0), ]] .. id "sec" .. [[ (default is 0), and ]] .. id "isdst" .. [[ (default is ]] .. code "nil" .. [[). Other fields are ignored. For a description of these fields, see the ]] .. id "os.date" .. [[ function.
706 |
707 | When the function is called, the values in these fields do not need to be inside their valid ranges. For instance, if ]] .. id "sec" .. [[ is -10, it means 10 seconds before the time specified by the other fields; if ]] .. id "hour" .. [[ is 1000, it means 1000 hours after the time specified by the other fields.
708 |
709 | The returned value is a number, whose meaning depends on your system. In POSIX, Windows, and some other systems, this number counts the number of seconds since some given start time (the epoch). In other systems, the meaning is not specified, and the number returned by ]] .. id "time" .. [[ can be used only as an argument to ]] .. id "os.date" .. [[ and ]] .. id "os.difftime" .. [[.
710 |
711 | When called with a table, ]] .. id "os.time" .. [[ also normalizes all the fields documented in the ]] .. id "os.date" .. [[ function, so that they represent the same time as before the call but with values inside their valid ranges. ]] },
712 | ["os.tmpname"] = {
713 | title = "os.tmpname ()",
714 | body = [[Returns a string with a file name that can be used for a temporary file. The file must be explicitly opened before its use and explicitly removed when no longer needed.
715 |
716 | In POSIX systems, this function also creates a file with that name, to avoid security risks. (Someone else might create the file with wrong permissions in the time between getting the name and creating the file.) You still have to open the file to use it and to remove it (even if you do not use it).
717 |
718 | When possible, you may prefer to use ]] .. id "io.tmpfile" .. [[, which automatically removes the file when the program ends.
719 |
720 | } ]] },
721 | ["debug.debug"] = {
722 | title = "debug.debug ()",
723 | body = [[Enters an interactive mode with the user, running each string that the user enters. Using simple commands and other debug facilities, the user can inspect global and local variables, change their values, evaluate expressions, and so on. A line containing only the word ]] .. id "cont" .. [[ finishes this function, so that the caller continues its execution.
724 |
725 | Note that commands for ]] .. id "debug.debug" .. [[ are not lexically nested within any function and so have no direct access to local variables. ]] },
726 | ["debug.gethook"] = {
727 | title = "debug.gethook ([thread])",
728 | body = [[Returns the current hook settings of the thread, as three values: the current hook function, the current hook mask, and the current hook count (as set by the ]] .. id "debug.sethook" .. [[ function). ]] },
729 | ["debug.getinfo"] = {
730 | title = "debug.getinfo ([thread,] f [, what])",
731 | body = [[Returns a table with information about a function. You can give the function directly or you can give a number as the value of ]] .. id "f" .. [[, which means the function running at level ]] .. id "f" .. [[ of the call stack of the given thread: level 0 is the current function (]] .. id "getinfo" .. [[ itself); level 1 is the function that called ]] .. id "getinfo" .. [[ (except for tail calls, which do not count on the stack); and so on. If ]] .. id "f" .. [[ is a number larger than the number of active functions, then ]] .. id "getinfo" .. [[ returns ]] .. code "nil" .. [[.
732 |
733 | The returned table can contain all the fields returned by ]] .. id "lua_getinfo" .. [[, with the string ]] .. id "what" .. [[ describing which fields to fill in. The default for ]] .. id "what" .. [[ is to get all information available, except the table of valid lines. If present, the option ]] .. code "f" .. [[ adds a field named ]] .. id "func" .. [[ with the function itself. If present, the option ]] .. code "L" .. [[ adds a field named ]] .. id "activelines" .. [[ with the table of valid lines.
734 |
735 | For instance, the expression ]] .. code "debug.getinfo(1,\"n\").name" .. [[ returns a name for the current function, if a reasonable name can be found, and the expression ]] .. code "debug.getinfo(print)" .. [[ returns a table with all available information about the ]] .. id "print" .. [[ function. ]] },
736 | ["debug.getlocal"] = {
737 | title = "debug.getlocal ([thread,] f, local)",
738 | body = [[This function returns the name and the value of the local variable with index ]] .. id "local" .. [[ of the function at level ]] .. id "f" .. [[ of the stack. This function accesses not only explicit local variables, but also parameters, temporaries, etc.
739 |
740 | The first parameter or local variable has index 1, and so on, following the order that they are declared in the code, counting only the variables that are active in the current scope of the function. Negative indices refer to vararg arguments; ]] .. code "-1" .. [[ is the first vararg argument. The function returns ]] .. code "nil" .. [[ if there is no variable with the given index, and raises an error when called with a level out of range. (You can call ]] .. id "debug.getinfo" .. [[ to check whether the level is valid.)
741 |
742 | Variable names starting with ]] .. code "(" .. [[ (open parenthesis) ]] .. code ")" .. [[ represent variables with no known names (internal variables such as loop control variables, and variables from chunks saved without debug information).
743 |
744 | The parameter ]] .. id "f" .. [[ may also be a function. In that case, ]] .. id "getlocal" .. [[ returns only the name of function parameters. ]] },
745 | ["debug.getmetatable"] = {
746 | title = "debug.getmetatable (value)",
747 | body = [[Returns the metatable of the given ]] .. id "value" .. [[ or ]] .. code "nil" .. [[ if it does not have a metatable. ]] },
748 | ["debug.getregistry"] = {
749 | title = "debug.getregistry ()",
750 | body = [[Returns the registry table ]] .. id "registry" .. [[. ]] },
751 | ["debug.getupvalue"] = {
752 | title = "debug.getupvalue (f, up)",
753 | body = [[This function returns the name and the value of the upvalue with index ]] .. id "up" .. [[ of the function ]] .. id "f" .. [[. The function returns ]] .. code "nil" .. [[ if there is no upvalue with the given index.
754 |
755 | Variable names starting with ]] .. code "(" .. [[ (open parenthesis) ]] .. code ")" .. [[ represent variables with no known names (variables from chunks saved without debug information). ]] },
756 | ["debug.getuservalue"] = {
757 | title = "debug.getuservalue (u, n)",
758 | body = [[Returns the ]] .. id "n" .. [[-th user value associated to the userdata ]] .. id "u" .. [[ plus a boolean, ]] .. code "false" .. [[ if the userdata does not have that value. ]] },
759 | ["debug.sethook"] = {
760 | title = "debug.sethook ([thread,] hook, mask [, count])",
761 | body = [[Sets the given function as a hook. The string ]] .. id "mask" .. [[ and the number ]] .. id "count" .. [[ describe when the hook will be called. The string mask may have any combination of the following characters, with the given meaning:
762 |
763 | ・ ]] .. code "c" .. [[| the hook is called every time Lua calls a function;} ・ ]] .. code "r" .. [[| the hook is called every time Lua returns from a function;} ・ ]] .. code "l" .. [[| the hook is called every time Lua enters a new line of code.} }
764 | Moreover, with a ]] .. id "count" .. [[ different from zero, the hook is called also after every ]] .. id "count" .. [[ instructions.
765 |
766 | When called without arguments, ]] .. id "debug.sethook" .. [[ turns off the hook.
767 |
768 | When the hook is called, its first parameter is a string describing the event that has triggered its call: ]] .. code "\"call\"" .. [[ (or ]] .. code "\"tail call\"" .. [[), ]] .. code "\"return\"" .. [[, ]] .. code "\"line\"" .. [[, and ]] .. code "\"count\"" .. [[. For line events, the hook also gets the new line number as its second parameter. Inside a hook, you can call ]] .. id "getinfo" .. [[ with level 2 to get more information about the running function (level 0 is the ]] .. id "getinfo" .. [[ function, and level 1 is the hook function). ]] },
769 | ["debug.setlocal"] = {
770 | title = "debug.setlocal ([thread,] level, local, value)",
771 | body = [[This function assigns the value ]] .. id "value" .. [[ to the local variable with index ]] .. id "local" .. [[ of the function at level ]] .. id "level" .. [[ of the stack. The function returns ]] .. code "nil" .. [[ if there is no local variable with the given index, and raises an error when called with a ]] .. id "level" .. [[ out of range. (You can call ]] .. id "getinfo" .. [[ to check whether the level is valid.) Otherwise, it returns the name of the local variable.
772 |
773 | See ]] .. id "debug.getlocal" .. [[ for more information about variable indices and names. ]] },
774 | ["debug.setmetatable"] = {
775 | title = "debug.setmetatable (value, table)",
776 | body = [[Sets the metatable for the given ]] .. id "value" .. [[ to the given ]] .. id "table" .. [[ (which can be ]] .. code "nil" .. [[). Returns ]] .. id "value" .. [[. ]] },
777 |
778 | ["debug.setupvalue"] = {
779 |
780 | title = "debug.setupvalue (f, up, value)",
781 | body = [[This function assigns the value ]] .. id "value" .. [[ to the upvalue with index ]] .. id "up" .. [[ of the function ]] .. id "f" .. [[. The function returns ]] .. code "nil" .. [[ if there is no upvalue with the given index. Otherwise, it returns the name of the upvalue. ]] },
782 | ["debug.setuservalue"] = {
783 | title = "debug.setuservalue (udata, value, n)",
784 | body = [[Sets the given ]] .. id "value" .. [[ as the ]] .. id "n" .. [[-th user value associated to the given ]] .. id "udata" .. [[. ]] .. id "udata" .. [[ must be a full userdata.
785 |
786 | Returns ]] .. id "udata" .. [[, or ]] .. code "nil" .. [[ if the userdata does not have that value. ]] },
787 | ["debug.traceback"] = {
788 | title = "debug.traceback ([thread,] [message [, level]])",
789 | body = [[If ]] .. id "message" .. [[ is present but is neither a string nor ]] .. code "nil" .. [[, this function returns ]] .. id "message" .. [[ without further processing. Otherwise, it returns a string with a traceback of the call stack. The optional ]] .. id "message" .. [[ string is appended at the beginning of the traceback. An optional ]] .. id "level" .. [[ number tells at which level to start the traceback (default is 1, the function calling ]] .. id "traceback" .. [[). ]] },
790 | ["debug.upvalueid"] = {
791 | title = "debug.upvalueid (f, n)",
792 | body = [[Returns a unique identifier (as a light userdata) for the upvalue numbered ]] .. id "n" .. [[ from the given function.
793 |
794 | These unique identifiers allow a program to check whether different closures share upvalues. Lua closures that share an upvalue (that is, that access a same external local variable) will return identical ids for those upvalue indices. ]] },
795 | ["debug.upvaluejoin"] = {
796 | title = "debug.upvaluejoin (f1, n1, f2, n2)",
797 | body = [[ Make the ]] .. id "n1" .. [[-th upvalue of the Lua closure ]] .. id "f1" .. [[ refer to the ]] .. id "n2" .. [[-th upvalue of the Lua closure ]] .. id "f2" .. [[.]] }
798 |
799 | }
800 |
--------------------------------------------------------------------------------
/croissant/lexer.lua:
--------------------------------------------------------------------------------
1 | local lpeg = require "lpeg"
2 | local P = lpeg.P
3 | local R = lpeg.R
4 | local S = lpeg.S
5 | local D = R"09"
6 | local I = R("AZ", "az", "\127\255") + "_"
7 | local B = -(I + D) -- word boundary
8 |
9 | local Class = require "hump.class"
10 |
11 | local function merge(t1, t2)
12 | local t = {}
13 |
14 | for k, v in pairs(t1) do
15 | t[k] = v
16 | end
17 |
18 | for k, v in pairs(t2) do
19 | t[k] = v
20 | end
21 |
22 | return t
23 | end
24 |
25 | local Lexer = Class {
26 |
27 | init = function (self, builtins)
28 | builtins = merge(
29 | require "croissant.builtins",
30 | builtins or {}
31 | )
32 |
33 | -- Adapted version of http://peterodding.com/code/lua/lxsh/ for Lua 5.3 syntax
34 | self.patterns = {}
35 |
36 | self.patterns.whitespace = S"\r\n\f\t\v "^1
37 | self.patterns.constant = (P"true" + "false" + "nil") * B
38 |
39 | -- Strings
40 | local longstring = #(P"[[" + (P"[" * P"="^0 * "[")) * P(function(input, index)
41 | local level = input:match("^%[(=*)%[", index)
42 | if level then
43 | local _, last = input:find("]" .. level .. "]", index, true)
44 | if last then
45 | return last + 1
46 | end
47 | end
48 | end)
49 | local singlequoted = P"'" * ((1 - S"'\r\n\f\\") + (P'\\' * 1))^0 * "'"
50 | local doublequoted = P'"' * ((1 - S'"\r\n\f\\') + (P'\\' * 1))^0 * '"'
51 | self.patterns.string = longstring + singlequoted + doublequoted
52 |
53 | -- Comments
54 | local eol = P"\r\n" + "\n"
55 | local line = (1 - S"\r\n\f")^0 * eol^-1
56 | local soi = P(function(_, i)
57 | return i == 1 and i
58 | end)
59 | local shebang = soi * "#!" * line
60 | local singleline = P"--" * line
61 | local multiline = P"--" * longstring
62 | self.patterns.comment = multiline + singleline + shebang
63 |
64 | -- Numbers
65 | local sign = S"+-"^-1
66 | local decimal = D^1
67 | local hexadecimal = P"0" * S"xX" * R("09", "AF", "af") ^ 1
68 | local float = D^1 * P"." * D^0 + P"." * D^1
69 | local maybeexp = (float + decimal) * (S"eE" * sign * D^1)^-1
70 | self.patterns.number = hexadecimal + maybeexp
71 |
72 | -- Operators
73 | self.patterns.operator =
74 | (P"not" + "..." + "and" + ".." + "~="
75 | + "==" + ">=" + "<=" + "or"
76 | + ">>" + "<<" + (P"/" * P"/"^-1)
77 | + S"]{=>^[<;)*(%}+-:,.#&~|")
78 |
79 | -- Keywords
80 | self.patterns.keywords =
81 | (P"and" + "break" + "do" + "else" + "elseif" + "end"
82 | + "false" + "for" + "function" + "goto" + "if" + "in"
83 | + "local" + "nil" + "not" + "or" + "repeat" + "return"
84 | + "then" + "true" + "until" + "while") * B
85 |
86 | -- Identifiers
87 | local ident = I * (I + D)^0
88 | local expr = ('.' * ident)^0
89 | self.patterns.identifier = lpeg.Cmt(
90 | ident,
91 | function(input, index)
92 | return expr:match(input, index)
93 | end
94 | )
95 |
96 | -- Builtins
97 | if #builtins > 0 then
98 | self.patterns.builtin = P(builtins[1])
99 | for i = 2, #builtins do
100 | self.patterns.builtin = self.patterns.builtin + builtins[i]
101 | end
102 | self.patterns.builtin = self.patterns.builtin * B
103 |
104 | table.insert(self.patterns, "builtin")
105 | end
106 |
107 | table.insert(self.patterns, "whitespace")
108 | table.insert(self.patterns, "constant")
109 | table.insert(self.patterns, "string")
110 | table.insert(self.patterns, "comment")
111 | table.insert(self.patterns, "number")
112 | table.insert(self.patterns, "operator")
113 | table.insert(self.patterns, "keywords")
114 | table.insert(self.patterns, "identifier")
115 |
116 | self:compile()
117 | end
118 |
119 | }
120 |
121 | function Lexer:compile()
122 | local function id(n)
123 | return lpeg.Cc(n) * self.patterns[n] * lpeg.Cp()
124 | end
125 |
126 | local any = id(self.patterns[1])
127 | for i = 2, #self.patterns do
128 | any = any + id(self.patterns[i])
129 | end
130 |
131 | self.any = any
132 | end
133 |
134 | function Lexer.sync(token, lnum, cnum)
135 | local lastidx
136 |
137 | lnum, cnum = lnum or 1, cnum or 1
138 | if token:find "\n" then
139 | for i in token:gmatch "()\n" do
140 | lnum = lnum + 1
141 | lastidx = i
142 | end
143 | cnum = #token - lastidx + 1
144 | else
145 | cnum = cnum + #token
146 | end
147 |
148 | return lnum, cnum
149 | end
150 |
151 | function Lexer:tokenize(subject)
152 | local index, lnum, cnum = 1, 1, 1
153 | return function()
154 | local kind, after = self.any:match(subject, index)
155 | if kind and after then
156 | local text = subject:sub(index, after - 1)
157 | local oldlnum, oldcnum = lnum, cnum
158 | index = after
159 | lnum, cnum = Lexer.sync(text, lnum, cnum)
160 | return kind, text, index, oldlnum, oldcnum
161 | end
162 | end
163 | end
164 |
165 | return Lexer
166 |
--------------------------------------------------------------------------------
/croissant/luaprompt.lua:
--------------------------------------------------------------------------------
1 | local Class = require "hump.class"
2 | local colors = require "term.colors"
3 | local Prompt = require "sirocco.prompt"
4 | local char = require "sirocco.char"
5 | local C, Esc = char.C, char.Esc
6 |
7 | local Lexer = require "croissant.lexer"
8 |
9 | local LuaPrompt
10 | LuaPrompt = Class {
11 |
12 | __includes = Prompt,
13 |
14 | init = function(self, options)
15 | options = options or {}
16 |
17 | -- If false not parsing while typing
18 | self.parsing = true
19 | if options.parsing ~= nil then
20 | self.parsing = options.parsing
21 | end
22 |
23 | Prompt.init(self, {
24 | prompt = options.prompt or "→ ",
25 | validator = self.parsing
26 | and function(code)
27 | return LuaPrompt.validateLua(self.multiline .. code)
28 | end
29 | or function() return true end,
30 | required = false
31 | })
32 |
33 | self.multiline = options.multiline or ""
34 |
35 | self.env = options.env or _G
36 |
37 | -- Leave function
38 | self.quit = options.quit
39 |
40 | -- History
41 | self.history = options.history or {}
42 | self.historyIndex = 0
43 |
44 | -- Lexing
45 | self.builtins = options.builtins or {}
46 | -- merge(
47 | -- require "croissant.builtins",
48 | -- options.builtins or {}
49 | -- )
50 | self.tokens = {}
51 | self.lexer = Lexer(self.builtins)
52 |
53 | self.tokenColors = options.tokenColors
54 |
55 | self.help = options.help
56 | end
57 |
58 | }
59 |
60 | function LuaPrompt:registerKeybinding()
61 | Prompt.registerKeybinding(self)
62 |
63 | self.keybinding.command_get_next_history = {
64 | Prompt.escapeCodes.key_down,
65 | C "n",
66 | Esc "[B", -- backup
67 | }
68 |
69 | self.keybinding.command_get_previous_history = {
70 | Prompt.escapeCodes.key_up,
71 | C "p",
72 | Esc "[A", -- backup
73 | }
74 |
75 | self.keybinding.command_exit = {
76 | -- Not allowed
77 | }
78 |
79 | self.keybinding.command_abort = {
80 | C "c",
81 | C "g"
82 | }
83 |
84 | self.keybinding.command_help = {
85 | C " ",
86 | Esc " ",
87 | }
88 | end
89 |
90 | function LuaPrompt:selectHistory(dt)
91 | if #self.history > 0 then
92 | self.historyIndex = math.min(math.max(0, self.historyIndex + dt), #self.history + 1)
93 | self.buffer = self.history[self.historyIndex] or ""
94 | self:setOffset(Prompt.len(self.buffer) + 1)
95 | end
96 | end
97 |
98 | function LuaPrompt:renderDisplayBuffer()
99 | self.tokens = {}
100 |
101 | self.displayBuffer = ""
102 |
103 | -- Lua code
104 | local lastIndex
105 | for kind, text, index in self.lexer:tokenize(self.buffer) do
106 | self.displayBuffer = self.displayBuffer
107 | .. (self.tokenColors[kind] or "")
108 | .. text
109 | .. colors.reset
110 |
111 | lastIndex = index
112 |
113 | table.insert(self.tokens, {
114 | kind = kind,
115 | index = index - Prompt.len(text),
116 | text = text
117 | })
118 | end
119 |
120 | if lastIndex then
121 | self.displayBuffer = self.displayBuffer
122 | .. self.buffer:utf8sub(lastIndex)
123 | end
124 | end
125 |
126 | function LuaPrompt:getCurrentToken()
127 | local currentToken, currentTokenIndex
128 | for i, token in ipairs(self.tokens) do
129 | currentToken = token
130 | currentTokenIndex = i
131 |
132 | if token.index + Prompt.len(token.text) >= self.bufferOffset + 1 then
133 | break
134 | end
135 | end
136 |
137 | return currentToken, currentTokenIndex
138 | end
139 |
140 | local keywords = {
141 | "and", "break", "do", "else", "elseif", "end",
142 | "false", "for", "function", "goto", "if", "in",
143 | "local", "nil", "not", "or", "repeat", "return",
144 | "then", "true", "until", "while"
145 | }
146 |
147 | function LuaPrompt:command_complete()
148 | local currentToken, currentTokenIndex = self:getCurrentToken()
149 |
150 | if currentToken then
151 | local possibleValues = {}
152 | local highlightedPossibleValues = {}
153 | if currentToken.kind == "identifier" then
154 | -- Search in _G
155 | for k, _ in pairs(self.env) do
156 | if k:utf8sub(1, #currentToken.text) == currentToken.text then
157 | table.insert(possibleValues, k)
158 | table.insert(highlightedPossibleValues,
159 | self.tokenColors.identifier .. k .. colors.reset)
160 | end
161 | end
162 |
163 | -- Search in keywords
164 | for _, k in ipairs(keywords) do
165 | if k:utf8sub(1, #currentToken.text) == currentToken.text then
166 | table.insert(possibleValues, k)
167 | table.insert(highlightedPossibleValues,
168 | self.tokenColors.keywords .. k .. colors.reset)
169 | end
170 | end
171 |
172 | -- Search in builtins
173 | for _, k in ipairs(self.builtins) do
174 | if k:utf8sub(1, #currentToken.text) == currentToken.text then
175 | table.insert(possibleValues, k)
176 | table.insert(highlightedPossibleValues,
177 | self.tokenColors.builtin .. k .. colors.reset)
178 | end
179 | end
180 | elseif currentToken.kind == "operator"
181 | and (currentToken.text == "."
182 | or currentToken.text == ":") then
183 | -- TODO: this requires an AST
184 | -- We need to be able to evaluate previous expression to search
185 | -- possible values in it
186 |
187 | if currentTokenIndex > 1
188 | and self.tokens[currentTokenIndex - 1].kind == "identifier" then
189 | local fn = load("return " .. self.tokens[currentTokenIndex - 1].text, "lookup", "t", self.env)
190 | local parentTable = fn and fn()
191 |
192 | if type(parentTable) == "table" then
193 | for k, _ in pairs(parentTable) do
194 | table.insert(possibleValues, k)
195 | table.insert(highlightedPossibleValues,
196 | self.tokenColors.identifier .. k .. colors.reset)
197 | end
198 | end
199 | end
200 | end
201 |
202 | local count = #possibleValues
203 |
204 | if count > 1 then
205 | self.message = table.concat(highlightedPossibleValues, " ")
206 | elseif count == 1 then
207 | local dt = Prompt.len(possibleValues[1]) - Prompt.len(currentToken.text)
208 | self:insertAtCurrentPosition(possibleValues[1]:utf8sub(#currentToken.text + 1))
209 |
210 | self:setOffset(self.bufferOffset + dt)
211 |
212 | if self.validator then
213 | local _, message = self.validator(self.buffer)
214 | self.message = message
215 | end
216 | end
217 | end
218 | end
219 |
220 | function LuaPrompt.validateLua(code)
221 | local fn, err = load("return " .. code, "croissant")
222 | if not fn then
223 | fn, err = load(code, "croissant")
224 | end
225 |
226 | return fn, (err and colors.red .. err .. colors.reset)
227 | end
228 |
229 | function LuaPrompt:processedResult()
230 | return self.buffer
231 | end
232 |
233 | function LuaPrompt:command_get_next_history()
234 | self:selectHistory(-1)
235 | end
236 |
237 | function LuaPrompt:command_get_previous_history()
238 | self:selectHistory(1)
239 | end
240 |
241 | function LuaPrompt:command_delete_back()
242 | Prompt.command_delete_back(self)
243 |
244 | self.message = nil
245 | end
246 |
247 | function LuaPrompt:command_kill_line()
248 | Prompt.command_kill_line(self)
249 |
250 | self.message = nil
251 | end
252 |
253 | function LuaPrompt:command_abort()
254 | Prompt.command_abort(self)
255 |
256 | self.quit()
257 | end
258 |
259 | local function trim(str)
260 | return str:gsub("%s*$", ""):gsub("^%s*","")
261 | end
262 |
263 | function LuaPrompt:command_help()
264 | local currentToken = self:getCurrentToken()
265 |
266 | if currentToken and (currentToken.kind == "identifier" or currentToken.kind == "builtin") then
267 | local doc = self.help[currentToken.text]
268 |
269 | if doc then
270 | self.message =
271 | colors.magenta " ? "
272 | .. colors.blue .. trim(doc.title) .. colors.reset
273 | .. "\n" .. colors.white .. trim(doc.body)
274 | .. colors.reset
275 | .. "\n"
276 | end
277 | end
278 | end
279 |
280 | function LuaPrompt:after()
281 | Prompt.after(self)
282 |
283 | self:command_end_of_line()
284 |
285 | self.output:write(Prompt.escapeCodes.clr_eos)
286 | end
287 |
288 | return LuaPrompt
289 |
--------------------------------------------------------------------------------
/croissant/repl.lua:
--------------------------------------------------------------------------------
1 | require "compat53"
2 |
3 | local conf = require "croissant.conf"
4 | local cdo = require "croissant.do"
5 | local runChunk = cdo.runChunk
6 | local banner = cdo.banner
7 |
8 | local LuaPrompt = require "croissant.luaprompt"
9 |
10 | return function()
11 | local history = cdo.loadHistory()
12 | local multiline = false
13 | local finished = false
14 |
15 | _G.quit = function()
16 | finished = true
17 | end
18 |
19 | banner()
20 |
21 | while not finished do
22 | local code = LuaPrompt {
23 | prompt = multiline and conf.continuationPrompt or conf.prompt,
24 | multiline = multiline,
25 | history = history,
26 | tokenColors = conf.syntaxColors,
27 | help = require(conf.help),
28 | quit = _G.quit
29 | }:ask()
30 |
31 | if code ~= "" and (not history[1] or history[1] ~= code) then
32 | table.insert(history, 1, code)
33 |
34 | cdo.appendToHistory(code)
35 | end
36 |
37 | if runChunk((multiline or "") .. code) then
38 | multiline = (multiline or "") .. code .. "\n"
39 | else
40 | multiline = nil
41 | end
42 | end
43 | end
44 |
--------------------------------------------------------------------------------
/debugtest.lua:
--------------------------------------------------------------------------------
1 | local watchMe = 1
2 |
3 | local t = {
4 | 1,2,3,
5 | yo = "sldkfj",
6 | watchMe = 1
7 | }
8 |
9 | for k, v in pairs({...}) do
10 | print(k, v)
11 | end
12 |
13 | local function yo(name)
14 | local yoLocal = "i'm local to yo"
15 |
16 | print(name)
17 |
18 | watchMe = watchMe + 1
19 | t.watchMe = t.watchMe + 1
20 |
21 | print "third level"
22 | end
23 |
24 | local anUpvalue = "i'm a wild upvalue"
25 |
26 | local function sayHello(name)
27 | print("Hello " .. name)
28 |
29 | local sayHelloLocal = "i'm local to sayHello"
30 |
31 | -- require "croissant.debugger"()
32 |
33 | yo(name)
34 |
35 | watchMe = watchMe + 1
36 | t.watchMe = t.watchMe + 1
37 |
38 | print(yo, anUpvalue, sayHelloLocal, newGlobal)
39 | end
40 |
41 | local function sayIt()
42 | print "sayIt"
43 |
44 | local sayItLocal = "i'm local to sayIt"
45 |
46 | sayHello("joe")
47 |
48 | watchMe = watchMe + 1
49 | t.watchMe = t.watchMe + 1
50 |
51 | return true
52 | end
53 |
54 | for idx = 1, 10 do
55 | print(idx)
56 | end
57 |
58 | local it = sayIt()
59 |
60 | yo "lo"
61 |
62 | print(debug.getinfo(1).source)
63 |
64 | return it, "yeah !", { 1, 2, 3 }
65 |
66 |
--------------------------------------------------------------------------------