Repo refactor: rename "website" to "docs"

2026-06-23 09:12:24 +02:00
parent 1b3e86d960
commit e7ccdc2883
226 changed files with 1 additions and 1 deletions
@@ -0,0 +1,258 @@
+#api/lua
+
+API docs for Space Lua's `string` module.
+
+> **note** Note
+> Since string values set `string` as their meta table, these APIs can also be called as method calls on strings directly. For instance: `someString:startsWith("h")` is equivalent to `string.startsWith(someString, "h")`.
+
+# Lua standard library
+
+## Lua Pattern Matching
+Lua patterns are not regular expressions. Space Lua makes a good effort at translating Lua patterns to regex to run in a Javascript environment, but there are two main differences:
+
+1. Magic characters `^$()%.[]*+-?` must be escaped to represent their character. Standard Lua patterns do not require escaping magic characters when they are not contextually magic (e.g. `%d--` is a valid Lua pattern where the second hyphen is not magic). Space Lua may have unexpected results when expecting an un-escaped magic character to behave like a character.
+2. In Space Lua, the repetition magic characters (`?`, `*`, `+`, and `-`) will apply to captures in patterns. They do not in standard Lua.
+
+Additionally, the patterns for the *n*th captured string (`%*n*`), balanced match (`%b*xy*`), and frontier pattern (`%f[set]`) in [Lua](https://www.lua.org/manual/5.4/manual.html#6.4.1) will likely not be supported.
+
+As noted below, the operations `string.matchRegex` and `string.matchRegexAll`
+leverage regex in Javascript--not Space Lua patterns.
+
+Here are some valid Lua patterns with different matches (or outright errors) in Space Lua:
+
+```lua
+print(string.match("1234", "(%d)+"))
+-- prints "4" in Space Lua (last match of the captures)
+-- prints "nil" in Lua (repetition magic does not work on captures)
+
+print(string.match("*", "*"))
+-- invalid regex in Space Lua ("*" is not escaped)
+-- prints "*" in Lua
+
+print(string.match("2024-03-14", "%d+-(%d+)-%d+"))
+-- invalid regex in Space Lua (the "-"s are not escaped")
+-- prints "03" in Lua
+```
+
+## String Operations
+### string.byte(s, i?, j?)
+Returns the numeric codes of characters in string `s` from position `i` to `j`. If `j` is not provided, defaults to `i`.
+
+Example:
+```lua
+print(string.byte("Hello", 1))  -- prints: 72 (ASCII code for 'H')
+```
+
+### string.char(...)
+Returns a string from given ASCII codes.
+
+Example:
+```lua
+print(string.char(72))  -- prints: H
+```
+
+### string.find(s, pattern, init?, plain?)
+Looks for the first match of `pattern` in string `s`. Returns start and end indices of match.
+
+Example:
+```lua
+local start, end_ = string.find("Hello", "l")
+print(start)  -- prints: 3 (first 'l' position)
+```
+
+### string.format(format, ...)
+Returns a formatted string using C-style format specifiers.
+
+Example:
+```lua
+print(string.format("Name: %s, Age: %d", "John", 30))  -- prints: Name: John, Age: 30
+print(string.format("Pi: %.2f", 3.14159))             -- prints: Pi: 3.14
+```
+
+### string.gsub(s, pattern, repl, n?)
+Returns a copy of `s` in which all (or the first `n`) occurrences of `pattern` have been replaced by `repl`.
+
+Example:
+```lua
+-- Simple string replacement
+local result, count = string.gsub("hello world", "hello", "hi")
+print(result, count)  -- prints: hi world 1
+
+-- Multiple replacements with limit
+result = string.gsub("hello hello hello", "hello", "hi", 2)
+print(result)  -- prints: hi hi hello
+
+-- Function replacement
+result = string.gsub("hello world", "(h)ello", function(h)
+    return string.upper(h) .. "i"
+end)
+print(result)  -- prints: Hi world
+
+-- Pattern with magic characters
+result = string.gsub("hello.world", "%.", "-")
+print(result)  -- prints: hello-world
+```
+
+### string.match(s, pattern, init?)
+Returns the captures from the first match of `pattern` in string `s`.
+
+Example:
+```lua
+-- Basic pattern matching
+print(string.match("hello", "h"))  -- prints: h
+
+-- Multiple captures
+local year, month, day = string.match("2024-03-14", "(%d+)%-(%d+)%-(%d+)")
+print(year, month, day)  -- prints: 2024 03 14
+
+-- With init position
+print(string.match("hello world", "(world)", 7))  -- prints: world
+
+-- Pattern characters
+print(string.match("123", "%d+"))      -- prints: 123
+print(string.match("abc123", "%a+"))   -- prints: abc
+print(string.match("   abc", "%s+"))   -- prints: "   "
+```
+
+### string.gmatch(s, pattern)
+Returns an iterator function that returns successive captures from pattern matches in string `s`.
+
+Example:
+```lua
+local words = {}
+for word in string.gmatch("hello world lua", "%w+") do
+    table.insert(words, word)
+end
+print(words[1], words[2], words[3])  -- prints: hello world lua
+```
+
+### string.len(s)
+Returns the length of string `s`.
+
+Example:
+```lua
+print(string.len("Hello"))  -- prints: 5
+```
+
+### string.lower(s)
+Returns a copy of `s` with all characters converted to lowercase.
+
+Example:
+```lua
+print(string.lower("Hello"))  -- prints: hello
+```
+
+### string.upper(s)
+Returns a copy of `s` with all characters converted to uppercase.
+
+Example:
+```lua
+print(string.upper("Hello"))  -- prints: HELLO
+```
+
+### string.rep(s, n, sep?)
+Returns a string that is the concatenation of `n` copies of string `s`.
+
+Example:
+```lua
+print(string.rep("Hello", 3))  -- prints: HelloHelloHello
+```
+
+### string.reverse(s)
+Returns a string with the characters of `s` in reverse order.
+
+Example:
+```lua
+print(string.reverse("hello"))  -- prints: olleh
+print(string.reverse(""))       -- prints: "" (empty string)
+```
+
+### string.sub(s, i, j?)
+Returns the substring of `s` from position `i` to `j`.
+
+Example:
+```lua
+print(string.sub("Hello", 2, 4))  -- prints: ell
+```
+
+### string.split(s, sep)
+Splits string `s` using separator `sep` and returns a table of substrings.
+
+Example:
+```lua
+local parts = string.split("a,b,c", ",")
+for i, part in ipairs(parts) do
+    print(part)
+end
+-- Output:
+-- a
+-- b
+-- c
+```
+
+# Non-standard Extensions
+## JavaScript inspired
+### string.startsWith(s, prefix)
+Returns true if string `s` starts with `prefix`.
+
+Example:
+```lua
+print(string.startsWith("hello world", "hello"))  -- prints: true
+print(string.startsWith("hello world", "world"))  -- prints: false
+```
+
+### string.endsWith(s, suffix)
+Returns true if string `s` ends with `suffix`.
+
+Example:
+```lua
+print(string.endsWith("hello world", "world"))  -- prints: true
+print(string.endsWith("hello world", "hello"))  -- prints: false
+```
+
+### string.trim(s)
+Returns a copy of string `s` with whitespace removed from both ends.
+
+Example:
+```lua
+print(string.trim("  hello  "))  -- prints: hello
+```
+
+### string.trimStart(s)
+Returns a copy of string `s` with whitespace removed from the beginning.
+
+Example:
+```lua
+print(string.trimStart("  hello  "))  -- prints: hello  
+```
+
+### string.trimEnd(s)
+Returns a copy of string `s` with whitespace removed from the end.
+
+Example:
+```lua
+print(string.trimEnd("  hello  "))  -- prints:   hello
+```
+
+### string.matchRegex(s, pattern)
+Matches string `s` against a JavaScript regular expression pattern and returns the result. This uses JavaScript's native regex capabilities rather than Lua patterns.
+
+Example:
+```lua
+local match = string.matchRegex("hello123", "([a-z]+)([0-9]+)")
+print(match[1], match[2], match[3])  -- prints: hello123 hello 123
+```
+
+### string.matchRegexAll(s, pattern)
+Returns an iterator that finds all matches of a JavaScript regular expression pattern in string `s`.
+
+Example:
+```lua
+for match in string.matchRegexAll("a1b2c3", "([a-z])([0-9])") do
+    print(match[1], match[2], match[3])  -- prints each full match and its capture groups
+end
+-- Output:
+-- a1 a 1
+-- b2 b 2
+-- c3 c 3
+```