tcllib2.0 package - csv

目录

一、csv 包核心定位

二、前置准备：加载包

三、核心命令分类详解（附实战示例）

1. CSV 基础判断：::csv::iscomplete

示例：判断 CSV 记录完整性

2. CSV 生成（列表 → CSV 字符串）

（1）单条记录：::csv::join

示例：生成单条 CSV 记录

（2）多条记录：::csv::joinlist

示例：生成多条 CSV 记录

（3）矩阵 → CSV：::csv::joinmatrix

示例：矩阵转 CSV

3. CSV 解析（CSV 字符串 → 列表）

（1）单条记录解析：::csv::split

示例：解析 CSV 字符串（官方示例延伸）

（2）解析到矩阵：::csv::split2matrix

示例：解析 CSV 到矩阵

（3）解析到队列：::csv::split2queue

示例：解析 CSV 到队列

4. CSV 文件读写（通道 / 文件 → 矩阵 / 队列）

（1）读取 CSV 文件到矩阵：::csv::read2matrix

示例：读取 CSV 文件

（2）将矩阵写入 CSV 文件：::csv::writematrix

示例：矩阵写入 CSV 文件

（3）队列写入 CSV 文件：::csv::writequeue

示例：队列写入 CSV 文件

5. 辅助命令：::csv::report

示例：矩阵格式化输出为 CSV

四、CSV 格式差异（关键避坑点）

五、实战综合示例：CSV 文件处理完整流程

总结（核心要点）

---

一、csv 包核心定位

csv 是 Tcllib 提供的CSV 格式处理工具包（需先 package require csv 加载），解决 CSV 解析 / 生成的核心痛点：

1. 自动处理「含分隔符 / 引号的字段」（如 "123,456" 解析为单个值）；
2. 支持自定义分隔符（如分号 ;）、引号字符；
3. 兼容「标准 CSV」和「MS 产品 Alternate CSV」两种格式；
4. 支持和 struct::matrix（矩阵）、struct::queue（队列）联动，方便批量处理 CSV 文件。

二、前置准备：加载包

使用前必须先加载 csv 包（指定版本可选）：

# 加载 Tcl 8.5+ 和 csv 包（版本≥0.8.1）
package require Tcl 8.5
package require csv 0.8.1

# 若使用 matrix/queue 联动功能，需额外加载对应包
package require struct::matrix
package require struct::queue

三、核心命令分类详解（附实战示例）

1. CSV 基础判断：::csv::iscomplete

语法：::csv::iscomplete data

核心作用：判断输入的字符串是否是「完整的 CSV 记录」（引号 / 分隔符配对完整），返回 1（完整）/0（不完整）。

示例：判断 CSV 记录完整性

# 完整记录（引号配对）
set complete_data {123,"hello,world","test"}
puts "完整记录：[::csv::iscomplete $complete_data]"  ;# 输出：1

# 不完整记录（引号未闭合）
set incomplete_data {123,"hello,world,test"}
puts "不完整记录：[::csv::iscomplete $incomplete_data]"  ;# 输出：0

2. CSV 生成（列表 → CSV 字符串）

这类命令将 Tcl 列表（单条 / 多条记录）转换为 CSV 格式字符串，核心是 join/joinlist/joinmatrix。

（1）单条记录：::csv::join

语法：::csv::join values ?sepChar? ?delChar? ?delMode?

参数	说明
values	Tcl 列表（单条 CSV 记录的字段值）
sepChar	分隔符，默认 ,
delChar	引号字符，默认 "
delMode	引号模式：auto（仅必要时加引号，默认）/ always（始终加引号）

示例：生成单条 CSV 记录

# 基础用法（默认分隔符、auto 引号）
set values {123 "123,521.2" {Mary says "Hello, I am Mary"} "\""}
set csv_line [::csv::join $values]
puts "生成的 CSV 行：$csv_line"
# 输出：123,"123,521.2","Mary says ""Hello, I am Mary""",""""

# 自定义分隔符（;）+ 始终加引号
set csv_line2 [::csv::join $values ";" "\"" "always"]
puts "自定义分隔符+始终加引号：$csv_line2"
# 输出："123";"123,521.2";"Mary says ""Hello, I am Mary""";""""

（2）多条记录：::csv::joinlist

语法：::csv::joinlist values ?sepChar? ?delChar? ?delMode?

核心作用：输入「列表的列表」（外层列表 = 多条记录，内层列表 = 单条记录字段），输出多行 CSV 字符串（记录间用换行分隔）。

示例：生成多条 CSV 记录

# 多条记录（列表的列表）
set records {
    {ID Name Age}
    {1 "Alice,Li" 25}
    {2 "Bob,Wang" 30}
}

# 生成多行 CSV 字符串
set csv_content [::csv::joinlist $records]
puts "多行 CSV 内容：\n$csv_content"

输出：

多行 CSV 内容：
ID,Name,Age
1,"Alice,Li",25
2,"Bob,Wang",30

（3）矩阵 → CSV：::csv::joinmatrix

语法：::csv::joinmatrix matrix ?sepChar? ?delChar? ?delMode?

核心作用：将 struct::matrix 矩阵的每行作为一条 CSV 记录，生成多行 CSV 字符串。