模块与标准库

CIN 用 import 引入其它 .cin 文件。解析规则只有两条, 且 import 必须出现在 文件顶部 (列首, 缩进前)。

解析规则

写法	解析到
import "./util.cin"、import "../shared/x.cin"	相对当前 .cin 文件所在目录 (可带子目录)
import "math"、import "math.cin"、import "lib/math.cin"	codecin 内置标准库 codecin/lib/<name>/src/ (随 pip 包分发)
import "rich"、import "rich/util.cin"	已安装的 pic 包入口 / 包内文件
import "rich:*"、import "rich:table"	pic 包的分块导入 (全部公开模块 / 指定模块)
import "rich::1.1.1:*"	指定版本的 pic 包分块导入

一句话记住

想引用自己项目里的文件就写 "./" 前缀; 不写前缀一律当作内置库名。 lib/ 前缀是历史写法的兼容别名, import "lib/math.cin" 等价于 import "math.cin"。

// main.cin
// 注意: import 行不能写行尾注释 (会报 Expected IDENT)
import "math.cin"
import "str.cin"
import "./helpers.cin"

function main() -> int {
    int v = f_floor(3.9)              // math 库: 向下取整
    string up = s_upper("hi")         // str 库: 转大写
    println(float_to_str(f_round(2.5)) + " " + up + " " + int_to_str(v))
    return v
}

import 行不要写行尾注释

实测: import "math.cin" // 数学 会编译失败 (Compiler error: Expected IDENT but got STRING)。把注释挪到上一行或下一行。

实测输出 (examples/modules_demo.cin, 见 示例程序集):

abs=3.25
floor(2.7)=2 ceil(2.1)=3
round(2.5)=3 max=4.25
clamp=10
upper=ABCDE lower=hello
indexof(world)=6
contains(bana)=1
ends_with(.txt)=1 count(aa in aaa)=1
repeat(ab,3)=ababab

包含规则

• 同一文件在一次编译中只包含一次 (自动去重, 不会重复定义);
• 模块可以层层 import (构成 DAG); 主文件编译时按需展开, 普通 import 仍是源码级展开, 没有自动的独立编译单元;
• 需要独立编译/链接时, 用下面的 extern + --emit-object / --link 显式建立符号边界;
• 循环引用会报错;
• 找不到文件时报 Import file not found, 并指出查了哪里;
• 模块里的函数与全局变量对外可见, 因此命名建议加前缀避免冲突: f_* (浮点) / i_* (整数) / s_* (字符串) / a_* (数组) …

import 不能在函数里

import 只允许出现在文件顶部。写在函数体内会当作语法错误处理。

pic 库的分块导入

安装后的 pic 包除了入口，还可以按模块/版本选择导入，避免一次性展开整个库：

import "rich"                 // 只导入入口 (兼容旧写法)
import "rich:*"               // 入口 + 全部公开模块
import "rich:table"           // 只导入 table 模块
import "rich:table,markdown"  // 多个模块 (也可用 + 分隔)
import "rich::1.1.1"          // 指定版本的入口
import "rich::1.1.1:*"        // 指定版本的全部公开模块
import "rich::1.1.1:table"    // 指定版本的 table 模块

• * 只包含公开模块，跳过 main.cin、test/、demo/、internal/；
• 模块名可用 pic modules <包名> 查看；
• 私有模块可显式写 rich:internal/table（会先展开入口以保证符号完整）；
• 不写版本时默认使用最高已安装版本（与 pic use 的 current 指针无关）；
• 像 rich 这样公开 API 都集中在入口的包，rich:* 与 rich 等价；
• 指定版本时必须已经安装该版本，否则提示 pic install <包名>@<版本>；
• 旧的 import "rich/table.cin" 包内路径写法仍然可用。

自建模块示例

// helpers.cin (与 main.cin 同目录)
function helper_double(int x) -> int {
    return x * 2
}

function helper_greet(string name) -> void {
    println("hello, " + name)
}

// main.cin
import "./helpers.cin"

function main() -> int {
    helper_greet("CIN")                        // hello, CIN
    println(int_to_str(helper_double(21)))     // 42
    return 0
}

独立编译与链接

普通 import 在编译期展开源码；如果希望把库单独编译成对象再链接，使用顶层 extern function / extern <type> 声明跨对象符号：

// lib.cin —— 不写 main, 作为函数库对象
int counter = 5

function bump() {
    counter = counter + 1
}

function get() -> int {
    return counter
}

// main.cin
extern int counter
extern function bump()
extern function get() -> int

function main() -> int {
    bump()
    println(int_to_str(get()))   // 6
    return 0
}

codecin --emit-object lib.cin  -o lib.co
codecin --emit-object main.cin -o main.co
codecin --link main.co --link lib.co -o app --optimize 3 --gc-sections

# 也可以直接把源文件交给链接器
codecin --link main.cin --link lib.cin -o app

规则与限制：

• 无 main 的 .cin 文件自动作为函数库对象，入口桩会被去掉；
• 支持 extern 函数、extern 全局（标量/数组）；
• 字符串/标量全局/struct 指针槽的数据地址会随对象数据基址重定位；
• 同名全局/函数在链接时是重复符号；库内辅助函数建议加前缀；
• 复杂标签算术（多符号表达式）仍是对象内解析；跨对象只支持裸符号与 NAME±N；
• 静态库归档：codecin --emit-archive --link a.co --link b.co -o lib.colib， 链接时只拉取能解决未定义符号的成员。

详见 AOT 独立可执行文件 · 对象、链接与静态库。

官方标准库清单

内置库是 codecin/lib/<name>/ 下的 41 个 pic 包（src/<name>.cin），随 pip 包一起分发 (安装后即可 import, 不需要额外下载):

库	前缀	主要函数
cstd.cin	C 名称	C 语言兼容层 (ctype.h / string.h / stdlib.h / stdio.h / math.h 常用函数)
cppstd.cin	std_	C++ STL 兼容层 (std::string / std::vector / std::stack / std::queue 常用方法)
gostd.cin	go_	Go 标准库兼容层 (strings / strconv / math / slices / os 常用函数)
ffi.cin	ffi_	FFI 动态库调用 (ffi_load / ffi_find / ffi_call* / ffi_free), 需原生运行时
net.cin	net_ http_	HTTP / TCP / UDP / DNS 便捷封装, 需原生运行时
math.cin	f_ i_	f_abs f_floor f_ceil f_round f_min f_max i_min i_max i_clamp
str.cin	s_	s_upper s_lower s_contains s_starts_with s_ends_with s_count s_repeat
array.cin	a_	a_sum a_max a_min a_avg a_find a_contains a_count a_reverse a_fill a_copy a_index_of_max a_index_of_min a_sum_range a_lower_bound
sort.cin	sort_ bin_	sort_bubble sort_selection sort_insertion sort_quick sort_quick_all sort_is_sorted bin_search
conv.cin	c_	c_to_hex c_parse_hex c_to_bin c_parse_bin c_pad_left c_pad_right c_pad_int c_repeat c_chr c_to_int c_parse_float
vec.cin	v_	v_sum v_mean v_var v_std v_dot v_min v_max v_add v_scale v_normalize v_norm v_lerp
rand.cin	r_	r_range r_bool r_float r_float_range r_shuffle r_choice r_chance
json.cin	j_	j_raw j_str j_int j_float j_bool j_has (扁平 JSON 取值)
time.cin	t_	t_now t_hms t_ms t_breakdown t_human t_two
io.cin	io_	io_read io_write io_append io_exists io_size io_remove io_mkdir io_list io_join io_basename io_dirname io_line_count io_get_line io_split_get io_split_count
gui.cin	g_	g_rgb g_new g_clear g_rect_outline g_bar_chart g_line_chart g_grid g_save g_show
termux.cin	tx_	tx_ok tx_notify tx_toast tx_copy tx_paste tx_vibrate tx_say tx_sms tx_battery_level tx_battery_temp tx_battery_plugged tx_latitude tx_longitude tx_wifi_ssid tx_prompt tx_alert
key.cin	k_ K_	k_ctrl k_is_special key_wait + enum Key 键码常量 (K_UP..K_F10、K_ESC K_ENTER K_TAB K_BACKSPACE)
test.cin	t_	t_eq_int t_eq_str t_near t_true t_false t_reset t_report
bits.cin	bits_	bits_popcount bits_clz bits_ctz bits_is_pow2 bits_next_pow2 bits_test bits_set bits_clear bits_toggle bits_rotl bits_rotr bits_reverse bits_range_mask bits_extract bits_insert bits_bswap
stat.cin	stat_	stat_sum stat_min stat_max stat_range stat_mean stat_count stat_mode stat_median_sorted stat_percentile_sorted stat_q1_sorted stat_q3_sorted stat_histogram stat_variance_x1000 stat_stdev_x100 stat_is_sorted
hash.cin	hash_	hash_djb2 hash_fnv1a hash_sdbm hash_int hash_combine hash_bucket hash_string_bucket
validate.cin	val_	val_is_digit val_is_alpha val_is_alnum val_is_hex val_is_space val_is_upper val_is_lower val_is_int val_is_float val_is_ident val_is_blank val_is_hex_color val_count_char val_clamp_int val_parse_int
matrix.cin	mat_	mat_zero mat_identity mat_get mat_set mat_add mat_sub mat_scale mat_mul mat_transpose mat_trace mat_sum mat_equals mat_is_symmetric mat_det mat_print
queue.cin	queue_ stack_	queue_clear queue_push queue_pop queue_front queue_back queue_size queue_is_empty queue_is_full queue_capacity + stack_clear stack_push stack_pop stack_peek stack_size stack_is_empty stack_capacity
bigint.cin	bi_	bi_from_str bi_to_str bi_from_int bi_add bi_sub bi_mul bi_pow bi_fact
bitset.cin	bs_	bs_set bs_clear bs_test bs_count bs_first_set bs_shift_left bs_and bs_not
codec.cin	codec_	codec_hex_encode codec_hex_decode codec_url_encode codec_base64_encode codec_base64_decode codec_rle_encode codec_morse_encode codec_rot13
combin.cin	comb_	comb_gcd comb_is_prime comb_sieve comb_fact comb_choose comb_catalan comb_fib comb_mod_pow
csv.cin	csv_	csv_count csv_get csv_get_int csv_get_float csv_has csv_quote csv_escape csv_line_add
dp.cin	dp_	dp_fib dp_fact dp_knapsack01 dp_lcs dp_edit_distance dp_coin_change dp_lis dp_max_subarray
fmt.cin	fmt_	fmt_thousands fmt_float_dec fmt_percent fmt_align fmt_center fmt_bar fmt_cell fmt_border
frac.cin	fr_	fr_make fr_add fr_sub fr_mul fr_div fr_cmp fr_to_str fr_to_float
graph.cin	graph_	graph_reset graph_add_edge graph_bfs graph_dfs graph_topo_order graph_dijkstra graph_component_count graph_is_cyclic
heap.cin	heap_	heap_reset heap_push heap_pop heap_peek heap_build heap_sort heap_is_valid
path.cin	path_	path_str_join path_str_basename path_str_dirname path_ext path_stem path_normalize path_within path_change_ext
set.cin	set_	set_add set_remove set_contains set_union_into set_intersect_into set_diff_into set_is_subset set_to_str
text.cin	txt_	txt_replace txt_replace_first txt_slice txt_insert txt_delete_range txt_title txt_word_count txt_swap_case
token.cin	tok_	tok_count tok_get tok_len tok_find tok_first tok_last tok_word_count tok_word_get
tree.cin	tree_	tree_insert tree_contains tree_min tree_max tree_height tree_inorder_str tree_preorder_str
unionfind.cin	uf_	uf_reset uf_find uf_union uf_connected uf_count uf_size

依赖宿主能力的库

io.cin / gui.cin / termux.cin / key.cin 封装的是宿主能力 (文件、画布、Termux API、键盘轮询), 由 Go 原生引擎执行 (沙箱模式下会被拦截); 其余库为纯 CIN, 无宿主依赖。

逐库逐函数的签名、返回值与边界行为见 标准库参考; 总览与命名约定见 标准库概览。

常见错误

错误信息	原因	修正
Import file not found	文件名写错, 或自建模块忘了 "./" 前缀	自建模块写 import "./x.cin"; 内置库写裸名
循环引用报错	A → B → A	抽出公共模块, 或合并文件
import 写在函数里报错	位置不合法	移到文件顶部
库函数未定义	忘记 import "xxx.cin"	补上 import 语句
函数名冲突	模块间同名函数	给自己的函数加前缀

相关页面

• 标准库概览 — 41 个库的定位与依赖
• 标准库参考 — 全部函数签名
• 宿主能力 — io / gui / termux / key 的底层内建
• 示例程序集 — modules_demo.cin、stdlib_demo.cin