Lumesh 内置函数库

Lumesh 内置函数文档：核心模块

模块

模块	目标	代表函数
fs	文件系统操作	read, write, ls, dirs
string	字符串操作	split, join, replace, lower, upper
regex	正则操作	match, replace, search
list	列表操作	first, last, map, filter
map	映射操作	keys, values, merge
math	数学函数	sin, cos, sqrt, rand
rand	随机数操作	generation int, float, choice, shuffle
time	日期和时间操作	now, parse, fmt, stamp
parse	数据转换操作	json, toml, expr, cmd
into	数据转换操作	int,string,filesize,time,table
os	操作系统相关	name,family
sys	环境变量操作	env, define, defined
console	控制台操作	color, table, prompt
widget	UI 小组件	prompt, progress, table
ui	UI组件	fzp, fzpi
log	日志操作	debug, info, warn, error
fmt	格式化操作	red,pad,format,strip

顶层函数

一、环境控制函数

cd
- 功能：更改当前工作目录
- 参数：
  - path: String | Symbol - 目标路径（支持 ~ 表示家目录）
- 返回：None
- 示例：

cd "~/projects"  # 切换到用户家目录下的projects文件夹

exit
- 功能：终止进程
- 参数：
  - [可选] code: Integer - 退出状态码（默认0）
- 返回：无（直接终止进程）
- 示例：

exit 1  # 以状态码1退出

set
- 功能：设置顶级环境变量
- 参数：
  - var: Symbol - 变量名
  - value: any - 值
- 返回：无（直接终止进程）
- 示例：

set PATH PATH+"/usr/bin"

等同 sys.set

unset
等同 sys.unset

二、输入输出函数

print / println
- 功能：打印参数（println 自动换行）
- 参数：
  - ...values: Any - 任意数量参数
- 返回：None
- 示例：

print "Result:" 25  # 输出: Result: 25

pprint
- 功能：美化打印，列表和字典将以表格形式打印。
- 参数：
  - value: Any - 参数
- 返回：None
- 示例：

0...10 | pprint()   # 输出: 表格
fs.ls -l |  pprint()  # 输出: 表格

eprint / eprintln
- 功能：红色错误流输出（带ANSI颜色代码）
- 参数：
  - ...values: Any - 任意数量参数
- 返回：None
- 示例：

eprintln "Error: File not found"  # 红色错误信息

tap
- 功能：打印参数值并原样返回
- 参数：
  - ...values: Any - 任意数量参数
- 返回：最后一个参数或参数列表
- 示例：

tap 0...5 | list.map(x -> x*2)       # 先打印[0,1,2,3,4]再执行map

read
- 功能：读取用户输入
- 参数：
  - [可选] ...prompt: Any - 任意数量的提示信息
- 返回：String
- 示例：

let name = read "Enter name:"  # 显示提示并等待输入

三、类型操作函数

type
- 功能：获取值的类型名称
- 参数：
  - value: Any - 任意类型值
- 返回：String
- 示例：

type [1, 2, 3]  # 返回 "List"

类型转换操作请参考into模块。

四、数据结构函数

** get **
- 功能: 使用点分路径从嵌套复杂数据中获取值
- 语法:
  map.get(path, target_collection)
- 参数:
  - path: String - 点分路径（如 “a.b.c”,”1.name”）
  - target_collection: Nested Map/List/Range - 映射/列表/区间，可嵌套
- 返回值: Any - 路径对应的值，如果路径不存在则报错
- 示例:_map/list/range or mixed
  let nested = {a: {b: {c: [42,43]}},r:[0..3,10..15]};
  map.get("a.b.c.0", nested) # 返回 42
  map.get("a.r.0", nested) # 返回 0..3
  map.get("a.r.0.1", nested) # 返回 1
insert
- 功能：向容器插入元素
- 参数：
  - index: Integer | String - 索引（列表用数字，字典用字符串）
  - value: Any - 插入值
  - container: List | HMap | Map | String - 目标容器
- 返回：新容器
- 示例：

insert 0 "X" ["A", "B"]  # 返回 ["X" "A" "B"]
insert "key" 42 {}      # 返回 {key: 42}

len
- 功能：获取容器长度
- 参数：
  - container: List | HMap | Map | String | Bytes
- 返回：Integer
- 示例：

len "hello"  # 返回 5

rev
- 功能：反转序列
- 参数：
  - container: List | String | Symbol | Bytes
- 返回：同类型反转结果
- 示例：

rev "abc"  # 返回 "cba"

flatten
- 功能：扁平化嵌套结构
- 参数：
  - container: List | HMap | Map
- 返回：List
- 示例：

flatten [[1] {a: [2]}]  # 返回 [1, 2]

五、高级操作函数

where
- 功能：过滤表格行（对外部命令，需配合 parse.cmd 使用）
- 参数：
  - condition: Lambda/Function - 布尔条件
  - rows: List - 行数据列表（每行为 Map/HMap）
- 返回：List
- 示例：
支持变量LINENO, LINES 以及map中的字段名。

fs.ls -l | where(size<1K)

fs.ls -l | where(LINENO>1)

select
- 功能：过滤表格行（对外部命令，需配合 parse.cmd 使用）
- 参数：
  - headers: 一个List/ 多个symbol - 列名列表
  - rows: List - 行数据列表（每行为 Map/HMap）
- 返回：List
- 示例：

fs.ls -l | select(name,size)

repeat
- 功能：重复生成值
- 参数：
  - count: Integer - 重复次数
  - generator: Expression - 生成表达式
- 返回：List
- 示例：

repeat 3 "A"  # 返回 ["A" "A" "A"]

六、脚本导入和执行函数

import
- 功能：导入并执行脚本文件（创建新环境）
- 参数：
  - path: String - 文件路径（基于当前工作目录）
- 返回：文件最后一个表达式的执行结果
- 示例：

import "utils.lm"  # 导入同级目录的脚本

include
- 功能：导入并执行脚本文件（共享当前环境）
- 参数：
  - path: String - 文件路径
- 返回：文件最后一个表达式的执行结果
- 注意：与 import 的区别在于环境共享机制
- 示例：

include "config.lm"  # 在当前环境执行脚本

eval
- 功能：动态执行表达式（创建新环境）
- 参数：
  - expression: Any - 可执行表达式
- 返回：表达式执行结果
- 示例：

eval(parse.expr "(1 + 2) * 3")  # 返回 9

exec_str
- 功能：动态执行字串表达式（共享当前环境）
- 参数：
  - expression: String - 可执行表达式
- 返回：表达式执行结果
- 示例：

exec_str("(1 + 2) * 3")  # 返回 9

exec
- 功能：动态执行表达式（共享当前环境）
- 参数：
  - expression: Any - 可执行表达式
- 返回：表达式执行结果
- 示例：

exec(parse.expr "(1 + 2) * 3")  # 返回 9

七、调试工具函数

debug
- 功能：打印参数的调试信息（带类型标识）
- 参数：
  - ...values: Any - 任意数量参数
- 返回：None
- 示例：

debug [1, "text", true]  # 输出: [Integer(1), String("text"), Boolean(true)]

report
- 功能：格式化打印复杂数据结构
- 参数：
  - value: HMap | Map | String - 结构化数据
- 返回：None
- 示例：

report {name: "Alice", age: 30}  # 格式化输出字典

八、帮助系统函数

help
- 功能：显示内置函数文档
- 参数：
  - [可选] name: String - 模块名/函数名
- 返回：
  - 无参数时返回所有函数列表
  - 有参数时返回指定函数的文档
- 示例：

help len  # 显示len函数的文档

help about

# 返回
+-------------------------------------------------+
| KEY         VALUE                               |
+=================================================+
| version     "0.4.4"                             |
| git         "https://codeberg.com/santo/lumesh" |
| author      "Adam McDaniel, santo"              |
| path        "/tmp/target/debug/lume"            |
| suggestion  "Use the `?:` to handle errors and  |
|             read error messages!"               |
| homepage    "https://codeberg.com/santo/lumesh" |
| prelude     None                                |
| license     "APACHE-2.0"                        |
+-------------------------------------------------+

注意：所有内置函数均支持两种调用语法：
func(arg1, arg2) 或 func arg1 arg2
当参数包含复杂结构时建议使用第一种形式

updated at 2025-06-23

# libs # top