Release v1.2.0

.github/workflows/build-and-test.yml

@@ -20,7 +20,11 @@ jobs:
         run: |
           rustup update stable
           rustup default stable
+          rustup component add rustfmt
           rustup component add clippy
+
+      - name: Check formatting
+        run: cargo fmt --check
 
       - name: Build
         run: cargo build --verbose

CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.2.0] - 2026-04-21
+
+### Added
+
+- `read rows` column selection with `--select <col1,col2>`.
+- `read rows` and `read records` filtering with repeated `--filter field:op:value` conditions combined with AND semantics.
+- Filter operators for equality, inequality, numeric comparisons, string contains, regular expressions, null checks, and non-null checks.
+- Pagination controls with `--limit` and `--offset`.
+- `--non-empty` to drop all-empty rows from read results.
+- `read records <file>` for header-keyed records by default.
+- `--output-shape rows|records|jsonl` on row and record reads.
+- JSON Lines output for stream-friendly record processing.
+- Read-only TUI query preview with `:preview` and `:pv`.
+- Regression coverage for filtering, output shapes, invalid query errors, no-match results, help text, and query preview behavior.
+- CI formatting enforcement with `cargo fmt --check`.
+
+### Changed
+
+- Enriched read metadata now reports applied filters, selected columns, returned row count, truncation, and output shape.
+- Package version updated to `1.2.0`.
+
 ## [1.1.0] - 2026-04-21
 
 ### Added
@@ -174,7 +195,8 @@ This is the initial release of excel-cli, a lightweight terminal-based Excel vie
 - Copy, cut, and paste functionality with `y`, `d`, and `p` keys
 - Support for pipe operator when exporting to JSON
 
-[Unreleased]: https://github.com/fuhan666/excel-cli/compare/v1.1.0...HEAD
+[Unreleased]: https://github.com/fuhan666/excel-cli/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/fuhan666/excel-cli/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/fuhan666/excel-cli/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/fuhan666/excel-cli/releases/tag/v1.0.0
 [0.5.2]: https://github.com/fuhan666/excel-cli/releases/tag/v0.5.2

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "excel-cli"
-version = "1.1.0"
+version = "1.2.0"
 edition = "2021"
 description = "Excel CLI for AI, scripting, and terminal users. Headless JSON API for automation, plus a Vim-like TUI for interactive browsing and editing."
 license = "MIT"
@@ -23,6 +23,7 @@ indexmap = { version = "2.0", features = ["serde"] }
 tui-textarea = "0.4.0"
 quick-xml = "0.37.5"
 zip = "2.5.0"
+regex = "1"
 
 [profile.release]
 opt-level = 3

README.md

@@ -8,8 +8,10 @@ An Excel CLI for AI, scripting, and terminal users. Inspect and read headlessly
 - Create, switch, and delete sheets in multi-sheet workbooks
 - Edit cell contents directly in the terminal
 - Export data to JSON format
+- Select, filter, paginate, and stream read results for automation
 - Delete rows and columns
 - Search functionality with highlighting
+- Read-only query preview in the TUI
 - Command mode for advanced operations
 
 ## Installation & Uninstallation
@@ -83,6 +85,16 @@ excel-cli read rows path/to/your/file.xlsx --sheet Orders
 # Read rows with explicit header row (1-based)
 excel-cli read rows path/to/your/file.xlsx --sheet Orders --header-row 1
 
+# Read selected columns as records
+excel-cli read records path/to/your/file.xlsx --sheet Orders --select order_id,total,status
+
+# Filter, paginate, and stream records as JSON Lines
+excel-cli read records path/to/your/file.xlsx --sheet Orders \
+  --filter status:eq:open \
+  --filter total:gte:100 \
+  --limit 50 \
+  --output-shape jsonl
+
 # Open interactive TUI browser
 excel-cli ui path/to/your/file.xlsx
 ```
@@ -98,6 +110,50 @@ All headless commands (`inspect`, `read`, `check`) default to JSON output. Use `
 - Failure returns a non-zero exit code (see Exit Codes below)
 - Empty cells output `null` in JSON mode and empty string in text mode
 
+### Reading Rows and Records
+
+`read rows` returns positional arrays by default. Use `--output-shape records` to return objects keyed by the resolved header row, or use `read records` when record-shaped output is the default.
+
+```bash
+excel-cli read rows report.xlsx --sheet Orders --output-shape rows
+excel-cli read rows report.xlsx --sheet Orders --output-shape records
+excel-cli read records report.xlsx --sheet Orders
+```
+
+`--select` keeps only named columns. Names come from the resolved header row, with duplicate or blank headers made stable in the same way as `inspect columns`.
+
+```bash
+excel-cli read records report.xlsx --sheet Orders --select order_id,customer,total
+```
+
+`--filter field:op:value` filters rows by column name. Repeat `--filter` to combine conditions with AND semantics. Supported operators are `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, `regex`, `isnull`, and `notnull`.
+
+```bash
+excel-cli read records report.xlsx --sheet Orders --filter status:eq:open
+excel-cli read records report.xlsx --sheet Orders --filter total:gte:100
+excel-cli read records report.xlsx --sheet Orders --filter customer:contains:Inc
+excel-cli read records report.xlsx --sheet Orders --filter order_id:regex:^INV-[0-9]+$
+excel-cli read records report.xlsx --sheet Orders --filter optional_note:isnull:
+```
+
+`--limit` and `--offset` apply after filtering. `--non-empty` removes rows where every cell is empty. No-match filters are successful queries: they return an empty `rows` or `records` array with exit code `0`.
+
+```bash
+excel-cli read records report.xlsx --sheet Orders \
+  --filter status:eq:open \
+  --offset 25 \
+  --limit 25 \
+  --non-empty
+```
+
+`--output-shape jsonl` writes newline-delimited JSON records directly to stdout instead of the standard envelope. It uses the same selection, filtering, pagination, and header resolution rules as record output.
+
+```bash
+excel-cli read records report.xlsx --sheet Orders --output-shape jsonl
+```
+
+Invalid selected columns, unknown filter columns, unsupported operators, malformed filters, invalid numeric comparisons, and invalid regular expressions return structured `invalid_query` errors with exit code `6`.
+
 ### Exit Codes
 
 | Code | Meaning |
@@ -316,6 +372,7 @@ The JSON files are saved in the same directory as the original Excel file.
 
 - `:nohlsearch` or `:noh` - Disable search highlighting
 - `:help` - Show available commands
+- `:preview` or `:pv` - Show a read-only preview of the current sheet target and sample rows
 
 ## File Saving Logic
 

README_zh.md

@@ -8,8 +8,10 @@
 - 在多工作表工作簿中创建、切换和删除工作表
 - 直接在终端中编辑单元格内容
 - 将数据导出为 JSON 格式
+- 选择、筛选、分页和流式读取结果，支持自动化场景
 - 删除行和列
 - 搜索功能并支持高亮显示
+- TUI 中只读查询预览
 - 命令模式支持高级操作
 
 ## 安装与卸载
@@ -83,6 +85,16 @@ excel-cli read rows path/to/your/file.xlsx --sheet Orders
 # 读取行并指定表头行（从 1 开始计数）
 excel-cli read rows path/to/your/file.xlsx --sheet Orders --header-row 1
 
+# 读取指定列作为记录
+excel-cli read records path/to/your/file.xlsx --sheet Orders --select order_id,total,status
+
+# 筛选、分页并以 JSON Lines 流式输出记录
+excel-cli read records path/to/your/file.xlsx --sheet Orders \
+  --filter status:eq:open \
+  --filter total:gte:100 \
+  --limit 50 \
+  --output-shape jsonl
+
 # 打开交互式 TUI 浏览器
 excel-cli ui path/to/your/file.xlsx
 ```
@@ -98,6 +110,50 @@ excel-cli ui path/to/your/file.xlsx
 - 失败返回非零退出码（见下方退出码说明）
 - 空单元格在 JSON 模式下输出 `null`，在文本模式下输出空字符串
 
+### 读取行与记录
+
+`read rows` 默认返回位置数组。使用 `--output-shape records` 可以返回以解析后的表头为键的对象，或者直接使用 `read records`，此时记录形式输出为默认。
+
+```bash
+excel-cli read rows report.xlsx --sheet Orders --output-shape rows
+excel-cli read rows report.xlsx --sheet Orders --output-shape records
+excel-cli read records report.xlsx --sheet Orders
+```
+
+`--select` 保留指定的列，列名来自解析后的表头行，重复或空白的表头会按与 `inspect columns` 相同的方式处理为稳定名称。
+
+```bash
+excel-cli read records report.xlsx --sheet Orders --select order_id,customer,total
+```
+
+`--filter 字段:操作符:值` 按列名筛选行。重复 `--filter` 会以 AND 逻辑组合条件。支持的操作符有 `eq`、`ne`、`gt`、`gte`、`lt`、`lte`、`contains`、`regex`、`isnull` 和 `notnull`。
+
+```bash
+excel-cli read records report.xlsx --sheet Orders --filter status:eq:open
+excel-cli read records report.xlsx --sheet Orders --filter total:gte:100
+excel-cli read records report.xlsx --sheet Orders --filter customer:contains:Inc
+excel-cli read records report.xlsx --sheet Orders --filter order_id:regex:^INV-[0-9]+$
+excel-cli read records report.xlsx --sheet Orders --filter optional_note:isnull:
+```
+
+`--limit` 和 `--offset` 在筛选后生效。`--non-empty` 会移除所有单元格为空的行。未匹配的筛选仍是成功的查询：返回空的 `rows` 或 `records` 数组，退出码为 `0`。
+
+```bash
+excel-cli read records report.xlsx --sheet Orders \
+  --filter status:eq:open \
+  --offset 25 \
+  --limit 25 \
+  --non-empty
+```
+
+`--output-shape jsonl` 将换行分隔的 JSON 记录直接输出到 stdout，而不是标准的信封格式。它使用与记录输出相同的选择、筛选、分页和表头解析规则。
+
+```bash
+excel-cli read records report.xlsx --sheet Orders --output-shape jsonl
+```
+
+无效的选择列、未知的筛选列、不支持的操作符、格式错误的筛选条件、无效的数值比较和无效的正则表达式会返回结构化的 `invalid_query` 错误，退出码为 `6`。
+
 ### 退出码
 
 | 代码 | 含义 |
@@ -317,6 +373,7 @@ JSON 文件保存在与原始 Excel 文件相同的目录中。
 
 - `:nohlsearch` 或 `:noh` - 关闭搜索高亮
 - `:help` - 显示可用命令
+- `:preview` 或 `:pv` - 显示当前工作表目标和样本行的只读预览
 
 ## 文件保存逻辑
 

src/app/mod.rs

@@ -1,5 +1,6 @@
 mod edit;
 mod navigation;
+mod query_preview;
 mod search;
 mod sheet;
 mod state;
@@ -8,5 +9,6 @@ mod undo_manager;
 mod vim;
 mod word;
 
+pub use query_preview::*;
 pub use state::*;
 pub use vim::*;