add lz4 modules

docs/api/scripts/extension-modules/core/compress/lz4.md

@@ -0,0 +1,220 @@
+
+# lz4
+
+The lz4 module provides compression and decompression functions based on the LZ4 algorithm. It is an extension module of xmake.
+
+LZ4 is an extremely fast lossless compression algorithm, focusing on compression and decompression speed.
+
+::: tip TIP
+To use this module, you need to import it first: `import("core.compress.lz4")`
+:::
+
+## lz4.compress
+
+- Compress data (frame format)
+
+```lua
+import("core.compress.lz4")
+
+local compressed = lz4.compress("hello world")
+local compressed = lz4.compress(bytes_data)
+```
+
+Compresses data using the LZ4 frame format. Supports string or bytes object as input and returns a compressed bytes object.
+
+The frame format contains complete metadata and is self-contained, recommended for general scenarios. Compared to block format, it includes additional header information and checksums, requiring no extra information for decompression:
+
+```lua
+import("core.compress.lz4")
+
+-- Compress text data
+local data = "hello world"
+local compressed = lz4.compress(data)
+print("Original size:", #data)
+print("Compressed size:", compressed:size())
+```
+
+## lz4.decompress
+
+- Decompress data (frame format)
+
+```lua
+import("core.compress.lz4")
+
+local decompressed = lz4.decompress(compressed_data)
+```
+
+Decompresses data compressed using the LZ4 frame format and returns a decompressed bytes object.
+
+Complete compression and decompression example:
+
+```lua
+import("core.compress.lz4")
+
+local original = "hello world"
+local compressed = lz4.compress(original)
+local decompressed = lz4.decompress(compressed)
+assert(decompressed:str() == original)
+```
+
+## lz4.block_compress
+
+- Compress data (block format)
+
+```lua
+import("core.compress.lz4")
+
+local compressed = lz4.block_compress("hello world")
+local compressed = lz4.block_compress(bytes_data)
+```
+
+Compresses data using the LZ4 block format. The block format is more lightweight, does not include frame header information, resulting in smaller compressed data, but requires managing and recording the original data size information yourself.
+
+Suitable for scenarios with higher compression ratio requirements where you can manage metadata yourself.
+
+## lz4.block_decompress
+
+- Decompress data (block format)
+
+```lua
+import("core.compress.lz4")
+
+local decompressed = lz4.block_decompress(compressed_data, realsize)
+```
+
+Decompresses data compressed using the LZ4 block format. The original data size `realsize` must be provided.
+
+Block format compression and decompression example:
+
+```lua
+import("core.compress.lz4")
+
+local original = "hello world"
+local original_size = #original
+
+-- Compress
+local compressed = lz4.block_compress(original)
+
+-- Decompress with original size
+local decompressed = lz4.block_decompress(compressed, original_size)
+assert(decompressed:str() == original)
+```
+
+## lz4.compress_file
+
+- Compress a file
+
+```lua
+import("core.compress.lz4")
+
+lz4.compress_file("input.txt", "output.lz4")
+```
+
+Directly compresses a file using the LZ4 frame format. Compared to reading the entire file content and then compressing, this interface is more suitable for handling large files with lower memory usage:
+
+```lua
+import("core.compress.lz4")
+
+-- Compress build output
+local srcfile = "build/output.log"
+local dstfile = "build/output.log.lz4"
+lz4.compress_file(srcfile, dstfile)
+print("File compressed:", dstfile)
+```
+
+## lz4.decompress_file
+
+- Decompress a file
+
+```lua
+import("core.compress.lz4")
+
+lz4.decompress_file("input.lz4", "output.txt")
+```
+
+Directly decompresses a file and restores the original file content:
+
+```lua
+import("core.compress.lz4")
+
+-- Decompress log file
+local srcfile = "build/output.log.lz4"
+local dstfile = "build/output.log"
+lz4.decompress_file(srcfile, dstfile)
+
+-- Read decompressed content
+local content = io.readfile(dstfile)
+print(content)
+```
+
+## lz4.compress_stream
+
+- Open a compression stream
+
+```lua
+import("core.compress.lz4")
+
+local stream = lz4.compress_stream()
+```
+
+Creates a compression stream object for streaming data compression. The compression stream supports the following methods:
+
+- `stream:write(data, opt)` - Write data for compression
+- `stream:read(buffer, size, opt)` - Read compressed data
+
+Streaming compression is suitable for the following scenarios:
+- Handling large files, compressing while reading, without loading all content at once
+- Real-time data compression, such as network streams
+- Scenarios requiring controlled memory usage
+
+Example:
+
+```lua
+import("core.compress.lz4")
+
+local stream = lz4.compress_stream()
+local buffer = bytes(8192)
+
+-- Write data
+stream:write("hello ")
+stream:write("world", {beof = true})  -- Mark end on last write
+
+-- Read compression result
+local count, data = stream:read(buffer, 8192)
+if count > 0 then
+    print("Compressed " .. count .. " bytes")
+end
+```
+
+## lz4.decompress_stream
+
+- Open a decompression stream
+
+```lua
+import("core.compress.lz4")
+
+local stream = lz4.decompress_stream()
+```
+
+Creates a decompression stream object for streaming data decompression. The decompression stream supports the following methods:
+
+- `stream:write(data, opt)` - Write compressed data
+- `stream:read(buffer, size, opt)` - Read decompressed data
+
+Streaming decompression example:
+
+```lua
+import("core.compress.lz4")
+
+local stream = lz4.decompress_stream()
+local buffer = bytes(8192)
+
+-- Write compressed data
+stream:write(compressed_data, {beof = true})
+
+-- Read decompression result
+local count, data = stream:read(buffer, 8192)
+if count > 0 then
+    print("Decompressed:", data:str())
+end
+```

docs/sidebar.ts

@@ -15,14 +15,15 @@ export function builtinModulesApiSidebarItems(): DefaultTheme.SidebarItem[] {
     { text: 'vformat', link: 'builtin-modules/vformat' },
     { text: 'raise', link: 'builtin-pmodules/raise' },
     { text: 'os', link: 'builtin-modules/os' },
-    { text: 'winos', link: 'builtin-modules/winos' },
-    { text: 'macos', link: 'builtin-modules/macos' },
-    { text: 'linuxos', link: 'builtin-modules/linuxos' },
     { text: 'io', link: 'builtin-modules/io' },
     { text: 'path', link: 'builtin-modules/path' },
+    { text: 'hash', link: 'builtin-modules/hash' },
     { text: 'table', link: 'builtin-modules/table' },
     { text: 'string', link: 'builtin-modules/string' },
     { text: 'coroutine', link: 'builtin-modules/coroutine' },
+    { text: 'winos', link: 'builtin-modules/winos' },
+    { text: 'macos', link: 'builtin-modules/macos' },
+    { text: 'linuxos', link: 'builtin-modules/linuxos' },
     { text: 'signal', link: 'builtin-modules/signal' },
   ]
 }
@@ -47,6 +48,7 @@ function coreModulesApiSidebar(): DefaultTheme.SidebarItem {
     collapsed: true,
     items: [
       coreBaseModulesApiSidebar(),
+      coreCompressModulesApiSidebar(),
       coreLanguageModulesApiSidebar(),
       coreProjectModulesApiSidebar(),
       coreToolModulesApiSidebar(),
@@ -69,6 +71,16 @@ function coreBaseModulesApiSidebar(): DefaultTheme.SidebarItem {
   }
 }
 
+function coreCompressModulesApiSidebar(): DefaultTheme.SidebarItem {
+  return {
+    text: 'compress',
+    collapsed: true,
+    items: [
+      { text: 'lz4', link: 'extension-modules/core/compress/lz4' },
+    ]
+  }
+}
+
 function coreLanguageModulesApiSidebar(): DefaultTheme.SidebarItem {
   return {
     text: 'language',

docs/zh/api/scripts/extension-modules/core/compress/lz4.md

@@ -0,0 +1,220 @@
+
+# lz4
+
+lz4 模块提供了基于 LZ4 算法的压缩和解压功能，属于 xmake 的扩展模块。
+
+LZ4 是一个非常快速的无损压缩算法，专注于压缩和解压速度。
+
+::: tip 提示
+使用此模块需要先导入：`import("core.compress.lz4")`
+:::
+
+## lz4.compress
+
+- 压缩数据（帧格式）
+
+```lua
+import("core.compress.lz4")
+
+local compressed = lz4.compress("hello world")
+local compressed = lz4.compress(bytes_data)
+```
+
+使用 LZ4 帧格式压缩数据，支持字符串或 bytes 对象作为输入，返回压缩后的 bytes 对象。
+
+帧格式包含完整的元数据，自包含，推荐用于一般场景。相比块格式，它包含额外的头信息和校验和，解压时不需要额外信息：
+
+```lua
+import("core.compress.lz4")
+
+-- 压缩文本数据
+local data = "hello world"
+local compressed = lz4.compress(data)
+print("原始大小:", #data)
+print("压缩后大小:", compressed:size())
+```
+
+## lz4.decompress
+
+- 解压数据（帧格式）
+
+```lua
+import("core.compress.lz4")
+
+local decompressed = lz4.decompress(compressed_data)
+```
+
+解压使用 LZ4 帧格式压缩的数据，返回解压后的 bytes 对象。
+
+完整的压缩解压示例：
+
+```lua
+import("core.compress.lz4")
+
+local original = "hello world"
+local compressed = lz4.compress(original)
+local decompressed = lz4.decompress(compressed)
+assert(decompressed:str() == original)
+```
+
+## lz4.block_compress
+
+- 压缩数据（块格式）
+
+```lua
+import("core.compress.lz4")
+
+local compressed = lz4.block_compress("hello world")
+local compressed = lz4.block_compress(bytes_data)
+```
+
+使用 LZ4 块格式压缩数据。块格式更轻量，不包含帧头信息，压缩后的数据更小，但需要自行管理和记录原始数据大小信息。
+
+适合对压缩率要求较高，且可以自行管理元数据的场景。
+
+## lz4.block_decompress
+
+- 解压数据（块格式）
+
+```lua
+import("core.compress.lz4")
+
+local decompressed = lz4.block_decompress(compressed_data, realsize)
+```
+
+解压使用 LZ4 块格式压缩的数据，必须提供原始数据的大小 `realsize`。
+
+块格式的压缩解压示例：
+
+```lua
+import("core.compress.lz4")
+
+local original = "hello world"
+local original_size = #original
+
+-- 压缩
+local compressed = lz4.block_compress(original)
+
+-- 解压时需要提供原始大小
+local decompressed = lz4.block_decompress(compressed, original_size)
+assert(decompressed:str() == original)
+```
+
+## lz4.compress_file
+
+- 压缩文件
+
+```lua
+import("core.compress.lz4")
+
+lz4.compress_file("input.txt", "output.lz4")
+```
+
+直接压缩文件，使用 LZ4 帧格式。相比一次性读取整个文件内容再压缩，这个接口更适合处理大文件，内存占用更低：
+
+```lua
+import("core.compress.lz4")
+
+-- 压缩构建输出
+local srcfile = "build/output.log"
+local dstfile = "build/output.log.lz4"
+lz4.compress_file(srcfile, dstfile)
+print("文件已压缩:", dstfile)
+```
+
+## lz4.decompress_file
+
+- 解压文件
+
+```lua
+import("core.compress.lz4")
+
+lz4.decompress_file("input.lz4", "output.txt")
+```
+
+直接解压文件，恢复原始文件内容：
+
+```lua
+import("core.compress.lz4")
+
+-- 解压日志文件
+local srcfile = "build/output.log.lz4"
+local dstfile = "build/output.log"
+lz4.decompress_file(srcfile, dstfile)
+
+-- 读取解压后的内容
+local content = io.readfile(dstfile)
+print(content)
+```
+
+## lz4.compress_stream
+
+- 打开压缩流
+
+```lua
+import("core.compress.lz4")
+
+local stream = lz4.compress_stream()
+```
+
+创建一个压缩流对象，用于流式压缩数据。压缩流支持以下方法：
+
+- `stream:write(data, opt)` - 写入数据进行压缩
+- `stream:read(buffer, size, opt)` - 读取压缩后的数据
+
+流式压缩适合以下场景：
+- 处理大文件，边读边压缩，不需要一次性加载全部内容
+- 实时数据压缩，如网络流
+- 需要控制内存占用的场景
+
+示例：
+
+```lua
+import("core.compress.lz4")
+
+local stream = lz4.compress_stream()
+local buffer = bytes(8192)
+
+-- 写入数据
+stream:write("hello ")
+stream:write("world", {beof = true})  -- 最后一次写入标记结束
+
+-- 读取压缩结果
+local count, data = stream:read(buffer, 8192)
+if count > 0 then
+    print("压缩了 " .. count .. " 字节")
+end
+```
+
+## lz4.decompress_stream
+
+- 打开解压流
+
+```lua
+import("core.compress.lz4")
+
+local stream = lz4.decompress_stream()
+```
+
+创建一个解压流对象，用于流式解压数据。解压流支持以下方法：
+
+- `stream:write(data, opt)` - 写入压缩数据
+- `stream:read(buffer, size, opt)` - 读取解压后的数据
+
+流式解压示例：
+
+```lua
+import("core.compress.lz4")
+
+local stream = lz4.decompress_stream()
+local buffer = bytes(8192)
+
+-- 写入压缩数据
+stream:write(compressed_data, {beof = true})
+
+-- 读取解压结果
+local count, data = stream:read(buffer, 8192)
+if count > 0 then
+    print("解压后:", data:str())
+end
+```