跳到主要内容

标准库

Sii 语言提供了丰富的标准库函数，通过 sii. 前缀调用，包括文件操作、系统调用、HTTP服务等功能。

文件操作​

文件读写​

sii.readText()​

读取文件内容并返回字符串。

语法：

sii.readText(文件路径: string): string

参数：

  • 文件路径：要读取的文件路径（字符串类型）

返回值：

  • 文件内容（字符串类型）

示例：

let content: string = sii.readText("./config.json");

sii.writeText()​

将内容写入文件。

语法：

sii.writeText(文件路径: string, 内容: string): void

参数：

  • 文件路径：要写入的文件路径（字符串类型）
  • 内容：要写入的内容（字符串类型）

返回值：

  • 无返回值（void）

示例：

sii.writeText("./log.txt", "应用启动时间：" + string(sii.now()));

示例：

// 读取配置文件
let config: string = sii.readText("./config.json");
sii.log("配置内容：" + config);

// 写入日志文件
sii.writeText("./log.txt", "应用启动时间：" + string(sii.now()));

文件系统操作​

sii.exists()​

检查文件或目录是否存在。

语法：

sii.exists(路径: string): obj

参数：

  • 路径：要检查的文件或目录路径（字符串类型）

返回值：

  • 存在状态（对象类型）

sii.mkdirs()​

创建目录（包括父目录）。

语法：

sii.mkdirs(目录路径: string): void

参数：

  • 目录路径：要创建的目录路径（字符串类型）

返回值：

  • 无返回值（void）

sii.pathJoin()​

拼接路径。

语法：

sii.pathJoin(路径1: string, 路径2: string): string

参数：

  • 路径1：第一个路径（字符串类型）
  • 路径2：第二个路径（字符串类型）

返回值：

  • 拼接后的完整路径（字符串类型）

sii.cwd()​

获取当前工作目录。

语法：

sii.cwd(): string

参数：

  • 无参数

返回值：

  • 当前工作目录路径（字符串类型）

示例：

// 检查并创建目录
if (sii.exists("./data")) {
    sii.log("数据目录已存在");
} else {
    sii.mkdirs("./data");
    sii.log("数据目录已创建");
}

// 构建文件路径
let logFile: string = sii.pathJoin(sii.cwd(), "logs", "app.log");
sii.writeText(logFile, "应用日志");

系统操作​

环境变量​

sii.env()​

获取环境变量值。

语法：

sii.env(变量名: string): string

参数：

  • 变量名：环境变量名称（字符串类型）

返回值：

  • 环境变量值（字符串类型）

示例：

let homeDir: string = sii.env("HOME");
let nodeEnv: string = sii.env("NODE_ENV");

时间戳​

sii.now()​

注意

注意：该功能当前已放弃支持，最高适配版本为 v1.1.0。

获取当前时间戳。

语法：

sii.now(): int

参数：

  • 无参数

返回值：

  • 当前时间戳（整数类型）

示例：

let timestamp: int = sii.now();
sii.log("当前时间戳：" + string(timestamp));

日期时间处理​

提示

版本要求：该功能从 v1.2.1 开始支持

sii.Date​

格式化当前日期时间。

语法：

sii.Date(): string
sii.Date(格式字符串: string): string

参数：

  • 无参数：返回 ISO 格式的日期时间字符串
  • 格式字符串：指定日期时间格式

返回值：

  • 格式化后的日期时间字符串

格式字符串支持：

  • YYYY：四位数年份
  • MM：两位数月份（01-12）
  • DD：两位数日期（01-31）
  • HH：两位数小时（00-23）
  • mm：两位数分钟（00-59）
  • ss：两位数秒数（00-59）
  • Y：年份（不补零）
  • M：月份（不补零）
  • D：日期（不补零）
  • H：小时（不补零）
  • m：分钟（不补零）
  • s：秒数（不补零）

示例：

// 获取 ISO 格式日期时间
let isoTime: string = sii.Date();
print("ISO格式：" + isoTime);

// 获取时间戳
let timestamp: int = sii.Date("now");
print("时间戳：" + string(timestamp));

// 自定义格式
let customFormat: string = sii.Date("YYYY-MM-DD HH:mm:ss");
print("自定义格式：" + customFormat);

// 简单格式
let simpleFormat: string = sii.Date("Y-M-D H:m:s");
print("简单格式：" + simpleFormat);

完整示例：

// 记录当前时间
let currentTime: string = sii.Date("YYYY-MM-DD HH:mm:ss");
print("当前时间：" + currentTime);

// 获取时间戳用于计算
let now: int = sii.Date("now");
print("当前时间戳：" + string(now));

// 格式化日志时间
let logTime: string = sii.Date("MM-DD HH:mm");
print("日志时间：" + logTime);

进程执行​

sii.exec()​

执行系统命令。

语法：

sii.exec(命令: string): int

参数：

  • 命令：要执行的系统命令（字符串类型）

返回值：

  • 命令退出码（整数类型）

sii.execOut()​

执行系统命令并获取输出。

语法：

sii.execOut(命令: string): string

参数：

  • 命令：要执行的系统命令（字符串类型）

返回值：

  • 命令输出内容（字符串类型）

示例：

let exitCode: int = sii.exec("ls -la");
let output: string = sii.execOut("echo 'Hello World'");
sii.log("命令输出：" + output);

示例：

// 检查Git状态
let gitStatus: string = sii.execOut("git status --porcelain");
if (gitStatus.length > 0) {
    sii.log("有未提交的更改");
} else {
    sii.log("工作区干净");
}

JSON 处理​

JSON 解析和序列化​

sii.jsonParse()​

解析JSON字符串为对象。

语法：

sii.jsonParse(json字符串: string): obj

参数：

  • json字符串：要解析的JSON字符串（字符串类型）

返回值：

  • 解析后的对象（对象类型）

sii.jsonStringify()​

将对象序列化为JSON字符串。

语法：

sii.jsonStringify(对象: obj): string

参数：

  • 对象：要序列化的对象（对象类型）

返回值：

  • JSON字符串（字符串类型）

示例：

// 解析JSON字符串
let data: obj = sii.jsonParse(jsonString);

// 将对象序列化为JSON
let jsonString: string = sii.jsonStringify(data);

示例：

// 读取JSON配置文件
let configText: string = sii.readText("./config.json");
let config: obj = sii.jsonParse(configText);

// 处理配置数据
let appName: string = config.appName;
let port: int = config.port;

// 保存修改后的配置
let updatedConfig: obj = config;
updatedConfig.lastModified = sii.now();
let newConfigText: string = sii.jsonStringify(updatedConfig);
sii.writeText("./config.json", newConfigText);

HTTP 服务​

服务器创建​

sii.listen()​

启动HTTP服务器。

语法：

sii.listen(端口号: int): void

参数：

  • 端口号：服务器监听的端口号（整数类型）

返回值：

  • 无返回值（void）

路由定义​

提示

版本要求：该功能从 v1.1.0 开始支持

sii.get()​

定义GET路由。

语法：

sii.get(路径: string, 处理函数名: string): void

参数：

  • 路径：路由路径（字符串类型）
  • 处理函数名：处理函数的名称（字符串类型）

返回值：

  • 无返回值（void）

sii.post()​

定义POST路由。

语法：

sii.post(路径: string, 处理函数名: string): void

参数：

  • 路径：路由路径（字符串类型）
  • 处理函数名：处理函数的名称（字符串类型）

返回值：

  • 无返回值（void）

sii.put()​

定义PUT路由。

语法：

sii.put(路径: string, 处理函数名: string): void

参数：

  • 路径：路由路径（字符串类型）
  • 处理函数名：处理函数的名称（字符串类型）

返回值：

  • 无返回值（void）

sii.delete()​

定义DELETE路由。

语法：

sii.delete(路径: string, 处理函数名: string): void

参数：

  • 路径：路由路径（字符串类型）
  • 处理函数名：处理函数的名称（字符串类型）

返回值：

  • 无返回值（void）

sii.options()​

定义OPTIONS路由。

语法：

sii.options(路径: string, 处理函数名: string): void

参数：

  • 路径：路由路径（字符串类型）
  • 处理函数名：处理函数的名称（字符串类型）

返回值：

  • 无返回值（void）

sii.head()​

定义HEAD路由。

语法：

sii.head(路径: string, 处理函数名: string): void

参数：

  • 路径：路由路径（字符串类型）
  • 处理函数名：处理函数的名称（字符串类型）

返回值：

  • 无返回值（void）

响应处理​

sii.respText()​

返回文本响应。

语法：

sii.respText(响应对象: obj, 文本内容: string): void

参数：

  • 响应对象：HTTP响应对象（对象类型）
  • 文本内容：要返回的文本内容（字符串类型）

返回值：

  • 无返回值（void）

sii.respJson()​

返回JSON响应。

语法：

sii.respJson(响应对象: obj, 数据对象: obj): void

参数：

  • 响应对象：HTTP响应对象（对象类型）
  • 数据对象：要返回的数据对象（对象类型）

返回值：

  • 无返回值（void）

sii.respHtml()​

返回HTML响应。

语法：

sii.respHtml(响应对象: obj, HTML内容: string): void

参数：

  • 响应对象：HTTP响应对象（对象类型）
  • HTML内容：要返回的HTML内容（字符串类型）

返回值：

  • 无返回值（void）

完整示例：

// 定义处理函数
func handleHome(req: obj, res: obj): void {
    sii.respText(res, "欢迎使用Sii HTTP服务!");
}

func handleApi(req: obj, res: obj): void {
    let data: obj = {
        message: "Hello from Sii API",
        timestamp: sii.now()
    };
    sii.respJson(res, data);
}

func handleUserUpdate(req: obj, res: obj): void {
    let userId: string = req.params.id;
    let userData: obj = req.body;
    sii.log("更新用户 " + userId + ": " + sii.jsonStringify(userData));
    sii.respJson(res, { success: true, message: "用户更新成功" });
}

func handleUserDelete(req: obj, res: obj): void {
    let userId: string = req.params.id;
    sii.log("删除用户: " + userId);
    sii.respJson(res, { success: true, message: "用户删除成功" });
}

func handleOptions(req: obj, res: obj): void {
    sii.respText(res, "CORS预检请求");
}

func handleHead(req: obj, res: obj): void {
    // HEAD请求通常不返回响应体，只返回状态码和头部
    sii.respText(res, "");
}

// 定义路由
sii.get("/", "handleHome");
sii.get("/api/hello", "handleApi");
sii.put("/api/users/:id", "handleUserUpdate");
sii.delete("/api/users/:id", "handleUserDelete");
sii.options("/api/*", "handleOptions");
sii.head("/api/status", "handleHead");

// 启动服务器
sii.listen(3000);
sii.log("服务器启动在端口 3000");

日志记录​

日志函数​

sii.log()​

记录普通日志信息。

语法：

sii.log(信息内容: string): void

参数：

  • 信息内容：要记录的日志信息（字符串类型）

返回值：

  • 无返回值（void）

sii.warn()​

记录警告日志信息。

语法：

sii.warn(警告内容: string): void

参数：

  • 警告内容：要记录的警告信息（字符串类型）

返回值：

  • 无返回值（void）

sii.error()​

记录错误日志信息。

语法：

sii.error(错误内容: string): void

参数：

  • 错误内容：要记录的错误信息（字符串类型）

返回值：

  • 无返回值（void）

示例：

// 普通日志
sii.log("应用启动成功");

// 警告日志
sii.warn("配置文件不存在，使用默认配置");

// 错误日志
sii.error("数据库连接失败");

示例：

func processData(data: string): void {
    sii.log("开始处理数据");
    
    if (data.length == 0) {
        sii.warn("数据为空，跳过处理");
        back;
    }
    
    // 处理逻辑
    sii.log("数据处理完成");
}

// 错误处理
func handleError(error: string): void {
    sii.error("处理失败：" + error);
}

完整应用示例​

简单的Web应用​

// 配置
let config: obj = {
    port: 3000,
    appName: "Sii Web App"
};

// 处理函数
func handleIndex(req: obj, res: obj): void {
    let html: string = `
        <html>
            <head><title>${config.appName}</title></head>
            <body>
                <h1>欢迎使用 ${config.appName}</h1>
                <p>当前时间：${string(sii.now())}</p>
            </body>
        </html>
    `;
    sii.respHtml(res, html);
}

func handleApi(req: obj, res: obj): void {
    let response: obj = {
        status: "success",
        message: "API调用成功",
        timestamp: sii.now()
    };
    sii.respJson(res, response);
}

// 路由设置
sii.get("/", "handleIndex");
sii.get("/api/status", "handleApi");

// 启动服务器
sii.listen(config.port);
sii.log("服务器启动在端口 " + string(config.port));

文件处理工具​

func processFiles(): void {
    let inputDir: string = "./input";
    let outputDir: string = "./output";
    
    // 确保输出目录存在
    if (!sii.exists(outputDir)) {
        sii.mkdirs(outputDir);
        sii.log("创建输出目录");
    }
    
    // 处理文件（简化示例）
    let files: arr = ["file1.txt", "file2.txt", "file3.txt"];
    
    forloop (i: int = 0; i < 3; i.toUp(1)) {
        let filename: string = files[i];
        let inputPath: string = sii.pathJoin(inputDir, filename);
        let outputPath: string = sii.pathJoin(outputDir, "processed_" + filename);
        
        if (sii.exists(inputPath)) {
            let content: string = sii.readText(inputPath);
            let processedContent: string = "处理后的内容：" + content;
            sii.writeText(outputPath, processedContent);
            sii.log("处理文件：" + filename);
        } else {
            sii.warn("文件不存在：" + filename);
        }
    }
}

// 执行文件处理
processFiles();

注意事项​

  1. 命名空间：所有标准库函数都通过 sii. 前缀调用
  2. 类型安全：所有函数都有严格的类型检查
  3. 错误处理：文件操作等可能失败的操作需要适当的错误处理
  4. 性能考虑：频繁的文件I/O操作可能影响性能
  5. 安全性：执行系统命令时要注意安全性
  6. 跨平台：路径操作在不同操作系统上可能有差异

最佳实践​

  1. 错误处理：在使用文件操作前检查文件是否存在
  2. 资源管理：及时关闭文件句柄和网络连接
  3. 日志记录：使用适当的日志级别记录信息
  4. 配置管理：将配置信息存储在JSON文件中
  5. 性能优化：避免在循环中进行重复的文件操作
  6. 安全考虑：验证用户输入，避免路径遍历攻击

通过标准库，Sii 语言提供了完整的系统编程能力，支持从简单的脚本到复杂的Web应用开发。