wushenghua/plainleaf
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs for stdlib

Browse Source
This commit is contained in:
Zef Hemel
2026-07-15 17:55:18 +02:00
parent 23f338dc14
commit 599798c831
11 changed files with 1713 additions and 404 deletions
Download Patch File Download Diff File Expand all files Collapse all files
client/space_lua/stdlib/string.ts
+325 -99
View File
@@ -28,20 +28,39 @@ function capturesToLua(caps: CaptureResult[]): any {
}
export const stringApi = new LuaTable({
byte: new LuaBuiltinFunction((_sf, s: string, i?: number, j?: number) => {
i = i ?? 1;
j = j ?? i;
if (j > s.length) j = s.length;
if (i < 1) i = 1;
const result = [];
for (let k = i; k <= j; k++) {
result.push(s.charCodeAt(k - 1));
}
return new LuaMultiRes(result);
}),
char: new LuaBuiltinFunction((_sf, ...args: number[]) => {
return String.fromCharCode(...args);
}),
byte: new LuaBuiltinFunction(
(_sf, s: string, i?: number, j?: number) => {
i = i ?? 1;
j = j ?? i;
if (j > s.length) j = s.length;
if (i < 1) i = 1;
const result = [];
for (let k = i; k <= j; k++) {
result.push(s.charCodeAt(k - 1));
}
return new LuaMultiRes(result);
},
{
kind: "builtin",
description:
"Returns the numeric character codes in the inclusive range from `i` to `j`.",
parameters: [
{ name: "s", type: "string" },
{ name: "i", type: "integer", optional: true },
{ name: "j", type: "integer", optional: true },
],
returns: [{ type: "integer", description: "One result per character." }],
},
),
char: new LuaBuiltinFunction(
(_sf, ...args: number[]) => String.fromCharCode(...args),
{
kind: "builtin",
description: "Creates a string from numeric character codes.",
signatures: ["string.char(...): string"],
returns: [{ type: "string" }],
},
),
find: new LuaBuiltinFunction(
(_sf, s: string, pattern: string, init = 1, plain = false) => {
const r = patternFind(s, pattern, init, plain);
@@ -52,13 +71,46 @@ export const stringApi = new LuaTable({
}
return new LuaMultiRes(result);
},
{
kind: "builtin",
description:
"Finds the first Lua-pattern match and returns its bounds followed by captures.",
parameters: [
{ name: "s", type: "string" },
{ name: "pattern", type: "string" },
{ name: "init", type: "integer", optional: true },
{ name: "plain", type: "boolean", optional: true },
],
returns: [
{ type: "integer|nil", description: "Start index or `nil`." },
{ type: "integer", description: "End index." },
],
},
),
format: new LuaBuiltinFunction(
(_sf, format: string, ...args: any[]) => {
for (let i = 0; i < args.length; i++) {
args[i] = untagNumber(args[i]);
}
return luaFormat(format, ...args);
},
{
kind: "builtin",
description: "Formats values according to a C-style format string.",
signatures: ["string.format(format, ...): string"],
parameters: [
{ name: "format", type: "string" },
{
name: "...",
description: "Values consumed by conversion specifiers.",
},
],
returns: [{ type: "string" }],
examples: [
{ code: 'print(string.format("Name: %s, score: %.1f", "Ada", 9.5))' },
],
},
),
format: new LuaBuiltinFunction((_sf, format: string, ...args: any[]) => {
for (let i = 0; i < args.length; i++) {
args[i] = untagNumber(args[i]);
}
return luaFormat(format, ...args);
}),
gmatch: new LuaBuiltinFunction(
(_sf, s: string, pattern: string, init = 1) => {
const iter = patternGmatch(s, pattern, init);
@@ -68,6 +120,22 @@ export const stringApi = new LuaTable({
return capturesToLua(caps);
};
},
{
kind: "builtin",
description:
"Returns an iterator over successive Lua-pattern matches and captures.",
parameters: [
{ name: "s", type: "string" },
{ name: "pattern", type: "string" },
{ name: "init", type: "integer", optional: true },
],
returns: [{ type: "function", description: "Match iterator." }],
examples: [
{
code: 'for word in string.gmatch("hello world", "%w+") do\n print(word)\nend',
},
],
},
),
gsub: new LuaBuiltinFunction(
async (sf, s: string, pattern: string, repl: any, n?: number) => {
@@ -103,61 +171,156 @@ export const stringApi = new LuaTable({
const [result, count] = await patternGsub(s, pattern, callbacks, n);
return new LuaMultiRes([result, count]);
},
{
kind: "builtin",
description:
"Replaces Lua-pattern matches using a string, table, or function replacement.",
parameters: [
{ name: "s", type: "string" },
{ name: "pattern", type: "string" },
{ name: "replacement", type: "string|table|function" },
{ name: "n", type: "integer", optional: true },
],
returns: [
{ type: "string", description: "Result string." },
{ type: "integer", description: "Number of replacements." },
],
examples: [
{
code: 'local result, count = string.gsub("hello hello", "hello", "hi", 1)\nprint(result, count) -- hi hello 1',
},
],
},
),
len: new LuaBuiltinFunction((_sf, s: string) => {
return s.length;
}),
lower: new LuaBuiltinFunction((_sf, s: string) => {
return luaToString(s.toLowerCase());
}),
upper: new LuaBuiltinFunction((_sf, s: string) => {
return luaToString(s.toUpperCase());
}),
match: new LuaBuiltinFunction((_sf, s: string, pattern: string, init = 1) => {
const caps = patternMatch(s, pattern, init);
if (!caps) return null;
return capturesToLua(caps);
}),
rep: new LuaBuiltinFunction((_sf, s: string, n: number, sep?: string) => {
if (n <= 0) return "";
sep = sep ?? "";
const parts: string[] = [];
for (let i = 0; i < n; i++) {
parts.push(s);
}
return parts.join(sep);
}),
reverse: new LuaBuiltinFunction((_sf, s: string) => {
return s.split("").reverse().join("");
}),
sub: new LuaBuiltinFunction((_sf, s: string, i: number, j?: number) => {
const len = s.length;
let start: number;
if (i > 0) {
start = i;
} else if (i < -len) {
start = 1;
} else {
start = i === 0 ? 1 : len + i + 1;
}
let end: number;
if (j === undefined || j === null || j > len) {
end = len;
} else if (j >= 0) {
end = j;
} else if (j < -len) {
end = 0;
} else {
end = len + j + 1;
}
if (start <= end) {
return s.substring(start - 1, end);
}
return "";
len: new LuaBuiltinFunction((_sf, s: string) => s.length, {
kind: "builtin",
description: "Returns the length of a string.",
parameters: [{ name: "s", type: "string" }],
returns: [{ type: "integer" }],
}),
lower: new LuaBuiltinFunction(
(_sf, s: string) => luaToString(s.toLowerCase()),
{
kind: "builtin",
description: "Returns a copy of a string converted to lowercase.",
parameters: [{ name: "s", type: "string" }],
returns: [{ type: "string" }],
},
),
upper: new LuaBuiltinFunction(
(_sf, s: string) => luaToString(s.toUpperCase()),
{
kind: "builtin",
description: "Returns a copy of a string converted to uppercase.",
parameters: [{ name: "s", type: "string" }],
returns: [{ type: "string" }],
},
),
match: new LuaBuiltinFunction(
(_sf, s: string, pattern: string, init = 1) => {
const caps = patternMatch(s, pattern, init);
if (!caps) return null;
return capturesToLua(caps);
},
{
kind: "builtin",
description:
"Returns captures from the first Lua-pattern match, or `nil` when none is found.",
parameters: [
{ name: "s", type: "string" },
{ name: "pattern", type: "string" },
{ name: "init", type: "integer", optional: true },
],
returns: [{ description: "Pattern captures, whole match, or `nil`." }],
examples: [
{ code: 'local year, month = string.match("2024-03", "(%d+)%-(%d+)")' },
],
},
),
rep: new LuaBuiltinFunction(
(_sf, s: string, n: number, sep?: string) => {
if (n <= 0) return "";
sep = sep ?? "";
const parts: string[] = [];
for (let i = 0; i < n; i++) {
parts.push(s);
}
return parts.join(sep);
},
{
kind: "builtin",
description:
"Returns `n` copies of a string joined by an optional separator.",
parameters: [
{ name: "s", type: "string" },
{ name: "n", type: "integer" },
{ name: "sep", type: "string", optional: true },
],
returns: [{ type: "string" }],
},
),
reverse: new LuaBuiltinFunction(
(_sf, s: string) => s.split("").reverse().join(""),
{
kind: "builtin",
description: "Returns a string with its characters in reverse order.",
parameters: [{ name: "s", type: "string" }],
returns: [{ type: "string" }],
},
),
sub: new LuaBuiltinFunction(
(_sf, s: string, i: number, j?: number) => {
const len = s.length;
let start: number;
if (i > 0) {
start = i;
} else if (i < -len) {
start = 1;
} else {
start = i === 0 ? 1 : len + i + 1;
}
let end: number;
if (j === undefined || j === null || j > len) {
end = len;
} else if (j >= 0) {
end = j;
} else if (j < -len) {
end = 0;
} else {
end = len + j + 1;
}
if (start <= end) {
return s.substring(start - 1, end);
}
return "";
},
{
kind: "builtin",
description:
"Returns the substring from inclusive index `i` through `j`, supporting negative indices.",
parameters: [
{ name: "s", type: "string" },
{ name: "i", type: "integer" },
{ name: "j", type: "integer", optional: true },
],
returns: [{ type: "string" }],
},
),
split: new LuaBuiltinFunction((_sf, s: string, sep: string) => {
return s.split(sep);
split: new LuaBuiltinFunction((_sf, s: string, sep: string) => s.split(sep), {
kind: "builtin",
description:
"Splits a string on a literal separator and returns the substrings.",
parameters: [
{ name: "s", type: "string" },
{ name: "sep", type: "string" },
],
returns: [{ type: "table" }],
examples: [
{
code: 'for part in each(string.split("a,b,c", ",")) do\n print(part)\nend',
},
],
}),
pack: strPackFn,
@@ -165,34 +328,97 @@ export const stringApi = new LuaTable({
packsize: strPackSizeFn,
// Non-standard extensions
startsWith: new LuaBuiltinFunction((_sf, s: string, prefix: string) => {
return s.startsWith(prefix);
startsWith: new LuaBuiltinFunction(
(_sf, s: string, prefix: string) => s.startsWith(prefix),
{
kind: "builtin",
description: "Returns whether a string starts with a literal prefix.",
parameters: [
{ name: "s", type: "string" },
{ name: "prefix", type: "string" },
],
returns: [{ type: "boolean" }],
},
),
endsWith: new LuaBuiltinFunction(
(_sf, s: string, suffix: string) => s.endsWith(suffix),
{
kind: "builtin",
description: "Returns whether a string ends with a literal suffix.",
parameters: [
{ name: "s", type: "string" },
{ name: "suffix", type: "string" },
],
returns: [{ type: "boolean" }],
},
),
trim: new LuaBuiltinFunction((_sf, s: string) => s.trim(), {
kind: "builtin",
description: "Removes whitespace from both ends of a string.",
parameters: [{ name: "s", type: "string" }],
returns: [{ type: "string" }],
}),
endsWith: new LuaBuiltinFunction((_sf, s: string, suffix: string) => {
return s.endsWith(suffix);
trimStart: new LuaBuiltinFunction((_sf, s: string) => s.trimStart(), {
kind: "builtin",
description: "Removes whitespace from the beginning of a string.",
parameters: [{ name: "s", type: "string" }],
returns: [{ type: "string" }],
}),
trim: new LuaBuiltinFunction((_sf, s: string) => {
return s.trim();
}),
trimStart: new LuaBuiltinFunction((_sf, s: string) => {
return s.trimStart();
}),
trimEnd: new LuaBuiltinFunction((_sf, s: string) => {
return s.trimEnd();
}),
matchRegex: new LuaBuiltinFunction((_sf, s: string, pattern: string) => {
const regex = new RegExp(pattern);
const result = s.match(regex);
return jsToLuaValue(result);
}),
matchRegexAll: new LuaBuiltinFunction((_sf, s: string, pattern: string) => {
const regex = new RegExp(pattern, "g");
return () => {
const match = regex.exec(s);
if (!match) {
return;
}
return jsToLuaValue(match);
};
trimEnd: new LuaBuiltinFunction((_sf, s: string) => s.trimEnd(), {
kind: "builtin",
description: "Removes whitespace from the end of a string.",
parameters: [{ name: "s", type: "string" }],
returns: [{ type: "string" }],
}),
matchRegex: new LuaBuiltinFunction(
(_sf, s: string, pattern: string) => {
const regex = new RegExp(pattern);
const result = s.match(regex);
return jsToLuaValue(result);
},
{
kind: "builtin",
description:
"Matches a string with a JavaScript regular expression and returns the match array.",
parameters: [
{ name: "s", type: "string" },
{ name: "pattern", type: "string" },
],
returns: [{ type: "table|nil" }],
examples: [
{
code: 'local match = string.matchRegex("hello123", "([a-z]+)([0-9]+)")\nprint(match[1], match[2], match[3])',
},
],
},
),
matchRegexAll: new LuaBuiltinFunction(
(_sf, s: string, pattern: string) => {
const regex = new RegExp(pattern, "g");
return () => {
const match = regex.exec(s);
if (!match) {
return;
}
return jsToLuaValue(match);
};
},
{
kind: "builtin",
description:
"Returns an iterator over all JavaScript regular-expression matches.",
parameters: [
{ name: "s", type: "string" },
{ name: "pattern", type: "string" },
],
returns: [
{ type: "function", description: "Iterator yielding match arrays." },
],
examples: [
{
code: 'for match in string.matchRegexAll("a1b2", "([a-z])([0-9])") do\n print(match[1], match[2], match[3])\nend',
},
],
},
),
});