sync: update from private repo (2336949a)

docs/tools/read.md

@@ -33,19 +33,56 @@
 | パラメータ | 説明 |
 |-----------|------|
 | `file_path` | workspace 内の相対 / 絶対パス（必須） |
-| `offset` | 読み始める行番号（0-indexed）。**テキスト読みのみ有効**（PDF/Office では無視される） |
-| `limit` | 読む最大行数。**テキスト読みのみ有効**（PDF/Office では無視される） |
-| `byte_offset` | 読み始めるバイト位置。改行の無い巨大ファイル向け。`offset` / `limit` と排他。テキスト読みのみ有効 |
-| `byte_length` | 読むバイト数。`byte_offset` と併用。テキスト読みのみ有効 |
-| `page_range` | **PDF のページ範囲**（例 `5-10` / `3`）。PDF を途中から / 一部だけ読むときは `offset` ではなくこれを使う |
+| `offset` | 読み始める行番号（0-indexed）。**行数以上を指定するとエラー**。**テキストと `.msg` 本文のみ有効**（PDF/Office に渡すと**エラーになり本文は返らない**） |
+| `limit` | 読む最大行数。**テキストと `.msg` 本文のみ有効**（PDF/Office に渡すと**エラーになり本文は返らない**） |
+| `byte_offset` | 読み始めるバイト位置。改行の無い巨大ファイル向け。**ファイルサイズ以上を指定するとエラー**。`offset` / `limit` と排他。テキスト読みのみ有効（PDF/Office/`.msg` に渡すとエラー） |
+| `byte_length` | 読むバイト数。`byte_offset` と併用。テキスト読みのみ有効（PDF/Office/`.msg` に渡すとエラー） |
+| `page_range` | **PDF のページ範囲 / PowerPoint のスライド範囲**（例 `5-10` / `3`）。途中から / 一部だけ読むときは `offset` ではなくこれを使う。**実在しないページ・スライドを指すとエラー**。PDF と PowerPoint 専用（テキストファイルに渡すとエラー） |
 
 大きすぎる出力は残コンテキスト予算に収まるよう自動で切り詰められ、続きの読み方が
 注記される。
 
-> **PDF/Office をずらして読むとき**: `offset` / `limit` / `byte_*` は**テキスト専用**で、
-> PDF・Excel・Word・PowerPoint では黙って無視される（＝常に先頭から返る）。PDF は
-> `page_range`、Excel は `sheet` / `range` を使うこと。これらのフォーマットに
-> `offset` / `limit` を渡すと、出力の先頭に正しいパラメータへの誘導注記が付く。
+> **範囲指定は形式ごとに専用**。合わない組み合わせは **エラーになり、本文は一切返らない**。
+>
+> | 読むもの | 使うパラメータ |
+> |---|---|
+> | テキスト | `offset` / `limit`（行）、`byte_offset` / `byte_length`（バイト） |
+> | PDF | `page_range` / `query` |
+> | Excel | `sheet` / `range` |
+> | Word | `max_paragraphs` |
+> | PowerPoint | `page_range`（PDF と同じ名前） |
+> | `.msg` | `offset` / `limit`（**抽出した本文の行**） |
+>
+> 以前は合わない指定でも注記を添えて本文を返していたが、注記が読み飛ばされて
+> 先頭部分だけを「全部」と扱う事故が起きていたため、拒否に変えた（#1009）。
+> テキストにドキュメント用の指定を渡す逆向きは注記すら出なかった（#1041）。
+> どちらもエラー本文に、その形式で使うべきパラメータが書いてある。
+
+### 範囲外の位置を指したとき（#1170）
+
+`offset` がファイルの行数以上、または `byte_offset` がファイルサイズ以上のとき、
+`Read` は **エラーを返す**。以前は行指定なら空文字列を、バイト指定なら「範囲外」という
+文を、どちらも成功として返していたため、「読めたが中身が空だった＝まだ続きがある」と
+誤解する事故が起きていた。
+
+エラー本文には **指定した位置** と **そのファイルの実際の行数 / バイト数** が入る。
+続きが要る場合の手順はこの通り。
+
+| 何が起きたか | 次にやること |
+|---|---|
+| `offset` が行数以上 | エラー本文の行数を上限として、`0` 以上その値未満で指定し直す |
+| `byte_offset` がサイズ以上 | エラー本文のバイト数未満で指定し直す |
+| そもそも全体を読みたい | `offset` / `byte_offset` を外して呼び直す（自動切り詰めが効く） |
+
+境界の扱いも書いておく。
+
+| 場合 | 結果 |
+|---|---|
+| `offset` = 行数（末尾ちょうど。読める行が 1 行も無い） | エラー |
+| 空ファイル（0 行）に `offset: 0` | エラー（`0 行` と返る） |
+| 空ファイルを `offset` 無しで読む | 成功（空文字列） |
+| `offset` は範囲内で `limit` が余る | 成功（読めた分だけ返る） |
+| 末尾が改行のファイル（`a\nb\n` は **2 行**）に `offset: 2` | エラー |
 
 ## フォーマット固有の詳細オプション（inline schema には無いが実行時に受理される）
 
@@ -57,10 +94,19 @@
 |-----------|------|
 | `sheet` | シート名（省略時は全シート） |
 | `range` | セル範囲（例 `A1:D10`、省略時はシート全体） |
-| `max_cells` | 最大セル数（デフォルト 1000） |
+| `max_cells` | 最大セル数（デフォルト 1000）。**ブック全体の合計**で数える |
 | `include_styles` | `true` で背景色 / フォント / 罫線 / 書式 / 結合を `### Styles` として追記（デフォルト false） |
 | `max_style_ranges` | `include_styles` 時の style range 上限（デフォルト 250） |
 
+出力の先頭には、ブックにあるシートの一覧（名前・行数・列数・読めたかどうか）が
+`## Sheets` として必ず載る。`max_cells` はブック全体の合計なので、1 枚目で使い切ると
+2 枚目以降は 1 セルも読まれない。その場合、一覧のそのシートは `NOT READ` になり、
+途中で切れたシートには最後に読めたセルの番地が付く（#1165）。
+
+> 一覧を先頭に置くのは、末尾が出力の文字数上限とトークン持ち分の両方で
+> 切られるため。以前は落ちたシートが出力に一切現れず、受け取った側からは
+> 1 枚しか無いブックに見えていた。
+
 ### Word（.docx）
 | オプション | 説明 |
 |-----------|------|
@@ -82,11 +128,42 @@
 ### PowerPoint（.pptx）
 | オプション | 説明 |
 |-----------|------|
-| `slideRange` | スライド範囲（例 `1-5` / `3`、省略時は全スライド） |
+| `page_range` | スライド範囲（例 `2-4` / `3`、省略時は全スライド）。inline schema にも公開済み |
+
+スライドの範囲は PDF のページ範囲と**同じ `page_range`** で指定する。形式ごとに別の
+名前を覚えなくてよい。
+
+`page_range` を外せば全スライドが返る。外した場合を除いて**黙って全体を返すことはない**。
+
+| 渡したもの | 結果 |
+|---|---|
+| 実在するスライドを含む範囲（`2-3`、`4`） | その範囲だけ返す |
+| 実在しないスライドだけを指す範囲（5 枚のファイルに `9-10`） | **エラー**。本文に実際の枚数（`presentation has 5 slide(s)`）が入る |
+| 書式が読めない範囲（`abc` / `2-` / 空文字列 / 数値） | **エラー**（`Invalid page_range: ...`）。以前は黙って**全スライド**が返っていた |
+| `offset` / `limit` / `byte_offset` / `byte_length` | **エラー**。`page_range` を使う |
+
+範囲外・書式不正のときは本文を一切返さない。先頭だけ返して成功にすると、受け取った
+側が「これで全部」と扱う（#1009 と同じ壊れ方）。
 
 ### Outlook メール（.msg）
+| オプション | 説明 |
+|-----------|------|
+| `offset` | **抽出した本文**の読み始め行（0-indexed）。本文の行数以上を指定するとエラー |
+| `limit` | 本文から読む最大行数 |
+
+絞る単位を本文の行にしたのは、件名・送信者・宛先・添付の一覧が出力の骨格で、量を
+食っているのが本文だけだからである（自動切り詰めも本文にしか掛かっていない）。
+行なのでテキスト読みと同じ `offset` / `limit` をそのまま使う。
+
+| 渡したもの | 結果 |
+|---|---|
+| `offset` / `limit`（本文の行数の内側） | ヘッダーと添付一覧は全件、本文はその範囲だけ返す |
+| 本文の行数以上の `offset` | **エラー**。本文に実際の行数が入る。**添付も保存しない** |
+| `byte_offset` / `byte_length` | **エラー**。`.msg` は OLE2 の複合ファイルで、ファイル上のバイト位置は抽出した本文と対応しない |
+
 - 件名・送信者・宛先・本文を抽出する。
-- 添付ファイルは `input/` に保存し、保存先パスを出力に列挙する。
+- 添付ファイルは `input/` に保存し、保存先パスを出力に列挙する。**範囲を絞っても
+  添付の一覧は全件残す**（保存先パスは呼び出し側が必要とするため）。
 - 読み取り専用フェーズ（verify 等、edit 不可）では添付を保存せず、その旨を注記する。
 - ファイル名衝突時は `name-1.ext` のように連番で退避し、既存ファイルは上書きしない。
 
@@ -98,8 +175,9 @@ Read({ file_path: "input/sales.xlsx", sheet: "Q1", range: "A1:D20" })
 Read({ file_path: "input/spec.docx", mode: "text" })
 Read({ file_path: "input/manual.pdf", page_range: "5-10" })   // PDF の 5-10 ページ目
 Read({ file_path: "input/manual.pdf", query: "認証", context_lines: 3 })
-Read({ file_path: "input/deck.pptx", slideRange: "2-4" })
+Read({ file_path: "input/deck.pptx", page_range: "2-4" })      // 2-4 枚目のスライド
 Read({ file_path: "input/mail.msg" })                         // 添付は input/ へ
+Read({ file_path: "input/mail.msg", offset: 100, limit: 50 })  // 本文の 100 行目から 50 行
 Read({ file_path: "logs/huge.log", byte_offset: 0, byte_length: 4096 })
 ```