Lua API docs

common/languages.ts

@@ -123,6 +123,7 @@ export const builtinLanguages: Record<string, Language> = {
     parser: highlightingQueryParser,
   }),
   "space-lua": luaLanguage,
+  "lua": luaLanguage,
   "template": extendedMarkdownLanguage,
   "expression": LRLanguage.define({
     name: "expression",

website/API/global.md

@@ -4,25 +4,202 @@ These are Lua functions defined in the global namespace:
 ## print(...)
 Prints to your log (browser or server log).
 
-## assert(expr)
-Asserts `expr` to be true otherwise raises an [[#error]]
+Example:
+
+```lua
+print("Hello, world!")
+```
+
+## assert(expr, message?)
+Asserts `expr` to be true otherwise raises an [[#error(message)]]
+
+Example:
+
+```lua
+assert(1 == 2, "1 is not equal to 2")
+```
 
 ## ipairs
+Returns an iterator for array-like tables that iterates over numeric indices in order.
+
+Example:
+```lua
+local fruits = {"apple", "banana", "orange"}
+for i, fruit in ipairs(fruits) do
+    print(i, fruit)
+end
+-- Output:
+-- 1 apple
+-- 2 banana
+-- 3 orange
+```
+
 ## pairs
+Returns an iterator for tables that traverses all keys and values.
+
+Example:
+```lua
+local person = {name = "John", age = 30, city = "New York"}
+for key, value in pairs(person) do
+    print(key, value)
+end
+-- Output (order not guaranteed):
+-- name John
+-- age 30
+-- city New York
+```
+
+## each
+Returns an iterator for array-like tables that iterates over values only (without indices).
+
+Example:
+```lua
+local fruits = {"apple", "banana", "orange"}
+for fruit in each(fruits) do
+    print(fruit)
+end
+-- Output:
+-- apple
+-- banana
+-- orange
+```
+
 ## unpack
+Unpacks a table into individual values.
+
+Example:
+```lua
+local numbers = {10, 20, 30}
+print(unpack(numbers))  -- prints: 10 20 30
+
+local function sum(a, b, c)
+    return a + b + c
+end
+print(sum(unpack(numbers)))  -- prints: 60
+```
+
 ## type
+Returns the type of a value as a string.
+
+Example:
+```lua
+print(type("hello"))    -- string
+print(type(42))         -- number
+print(type({}))         -- table
+print(type(print))      -- function
+print(type(nil))        -- nil
+print(type(true))       -- boolean
+```
+
 ## tostring
+Converts a value to a string representation.
+
+Example:
+```lua
+print(tostring(42))           -- "42"
+print(tostring(true))         -- "true"
+print(tostring({1, 2, 3}))    -- "{1, 2, 3}"
+```
+
 ## tonumber
+Converts a string to a number, returns nil if conversion fails.
+
+Example:
+```lua
+print(tonumber("42"))      -- 42
+print(tonumber("3.14"))    -- 3.14
+print(tonumber("abc"))     -- nil
+```
+
 ## error(message)
 Throw an error.
 
-Example: `error("FAIL")`
+Example: 
+```lua
+error("FAIL")
+```
 
 ## pcall
+Protected call - executes a function in protected mode, catching errors.
+
+Example:
+```lua
+local status, result = pcall(function()
+    return 10/0  -- will cause an error
+end)
+print(status)  -- false
+print(result)  -- "attempt to divide by zero"
+
+status, result = pcall(function()
+    return 10/2  -- will succeed
+end)
+print(status)  -- true
+print(result)  -- 5
+```
+
 ## xpcall
+Like pcall, but allows you to specify an error handler function.
+
+Example:
+```lua
+local function errorHandler(err)
+    return "Error occurred: " .. tostring(err)
+end
+
+local status, result = xpcall(function()
+    error("something went wrong")
+end, errorHandler)
+print(status)  -- false
+print(result)  -- "Error occurred: something went wrong"
+```
+
 ## setmetatable
+Sets the metatable for a table.
+
+Example:
+```lua
+local t1 = {value = 10}
+local t2 = {value = 20}
+local mt = {
+    __add = function(a, b)
+        return a.value + b.value
+    end
+}
+setmetatable(t1, mt)
+setmetatable(t2, mt)
+
+-- Now we can add the tables together using the + operator
+print(t1 + t2)  -- prints: 30
+```
+
 ## getmetatable
+Gets the metatable of a table.
+
+Example:
+```lua
+local t = {}
+local mt = {}
+setmetatable(t, mt)
+print(getmetatable(t) == mt)  -- true
+```
+
 ## rawset
+Sets a table index without invoking metamethods.
+
+Example:
+```lua
+local t = {}
+local mt = {
+    __newindex = function(t, k, v)
+        print("Blocked setting:", k, v)
+    end
+}
+setmetatable(t, mt)
+
+t.foo = "bar"  -- prints: "Blocked setting: foo bar"
+rawset(t, "foo", "bar")  -- bypasses the metamethod
+print(t.foo)  -- prints: "bar"
+```
 
 # Space Lua specific
 ## tag(name)

website/API/js.md

@@ -0,0 +1,75 @@
+API docs for Space Lua's `js` module, which provides JavaScript interoperability.
+
+## js.import(url)
+Imports a JavaScript module from a URL. Returns the imported module.
+
+Example:
+```lua
+-- Import lodash library
+local lodash = js.import("https://esm.sh/lodash@4.17.21")
+local result = lodash.chunk({1, 2, 3, 4, 5, 6, 7, 8, 9, 10}, 3)
+
+-- Import moment.js for date handling
+local moment = js.import("https://esm.sh/moment@2.30.1")
+local day = moment("1995-12-25")
+print(day.format("DD-MM-YYYY"))  -- prints: 25-12-1995
+```
+
+## js.new(constructor, ...)
+Creates a new instance of a JavaScript class. Takes a constructor function and its arguments.
+
+Example:
+```lua
+local Date = js.import("https://esm.sh/date-fns")
+local date = js.new(Date, "2024-03-14")
+```
+
+## js.stringify(value)
+Converts a Lua value to a JSON string representation.
+
+Example:
+```lua
+local data = {1, 2, 3}
+print(js.stringify(data))  -- prints: [1,2,3]
+
+local nested = lodash.chunk({1, 2, 3, 4, 5, 6}, 2)
+print(js.stringify(nested))  -- prints: [[1,2],[3,4],[5,6]]
+```
+
+## js.tolua(value)
+Converts a JavaScript value to its Lua equivalent.
+
+Example:
+```lua
+local jsArray = someJsFunction()
+local luaTable = js.tolua(jsArray)
+```
+
+## js.tojs(value)
+Converts a Lua value to its JavaScript equivalent.
+
+Example:
+```lua
+local luaTable = {1, 2, 3}
+local jsArray = js.tojs(luaTable)
+```
+
+## js.log(...)
+Logs messages to the JavaScript console.
+
+Example:
+```lua
+js.log("Debug message")
+js.log("User data:", {name = "John", age = 30})
+```
+
+## js.each_iterable(iterable)
+Creates an iterator for JavaScript async iterables.
+
+Example:
+```lua
+local async_iterator = js.each_iterable(some_js_async_iterable)
+for value in async_iterator do
+    print(value)
+end
+```

website/API/os.md

@@ -0,0 +1,58 @@
+API docs for Lua's `os` module.
+
+## os.time(table?)
+Returns the current time when called without arguments, or a timestamp for a specific date when given a table. The table can contain the following fields: year (required), month (required), day (required), hour (defaults to 12), min (defaults to 0), and sec (defaults to 0).
+
+Example:
+```lua
+-- Get current timestamp
+print(os.time())  -- prints: current Unix timestamp
+
+-- Get timestamp for specific date
+local timestamp = os.time({
+    year = 2020,
+    month = 1,
+    day = 1
+})
+```
+
+## os.date(format?, timestamp?)
+Returns a string or table containing date and time, formatted according to the given format string. If timestamp is not provided, formats the current time.
+
+Format specifiers:
+- `%Y`: Full year (e.g., "2024")
+- `%y`: Year without century (e.g., "24")
+- `%m`: Month (01-12)
+- `%b`: Abbreviated month name (e.g., "Jan")
+- `%B`: Full month name (e.g., "January")
+- `%d`: Day of month (01-31)
+- `%e`: Day of month (1-31)
+- `%H`: Hour (00-23)
+- `%I`: Hour (01-12)
+- `%M`: Minute (00-59)
+- `%S`: Second (00-59)
+- `%p`: AM/PM
+- `%A`: Full weekday name (e.g., "Sunday")
+- `%a`: Abbreviated weekday name (e.g., "Sun")
+- `%w`: Weekday (0-6, Sunday is 0)
+- `%j`: Day of year (001-366)
+- `%Z`: Time zone name
+- `%z`: Time zone offset from UTC
+- `%%`: Literal "%"
+
+Example:
+```lua
+-- Format specific date
+local date = os.date("%Y-%m-%d", os.time({
+    year = 2020,
+    month = 1,
+    day = 1
+}))
+print(date)  -- prints: 2020-01-01
+
+-- Current date in different formats
+print(os.date("%Y-%m-%d"))         -- prints: current date (e.g., "2024-03-14")
+print(os.date("%B %d, %Y"))        -- prints: month day, year (e.g., "March 14, 2024")
+print(os.date("%I:%M %p"))         -- prints: time in 12-hour format (e.g., "02:30 PM")
+print(os.date("%A, %B %d, %Y"))    -- prints: full date (e.g., "Thursday, March 14, 2024")
+```