TextFormator：可擴充的文字格式化與統計分析框架

緣起與動機

TextFormator 框架的誕生源自兩件事：

1. 年初在 CSDN 論壇詢問「好的程式碼統計分析工具」卻無回應
2. 同事展示業餘開發的小工具，能將 C++ 程式碼轉為帶語法著色的 HTML

尋找通用解決方案過程中，利用一週時間完成設計、編碼、文件與測試，重拾大學時期用組合語言寫「學生檔案管理程式」的創作熱情。雖或許有現成工具更完善，但這是一次實踐 OO 設計與 STL 的好機會，開源釋出期望拋磚引玉，讓有興趣者能在此基礎上延伸。

功能特色

• 多語言支援：C/C++、Java、Pascal、Masm 等原始碼，亦支援純文字處理
• 格式化輸出：HTML 語法著色、縮排排版、移除註解等
• 統計分析：關鍵字搜尋、註解行統計、函數統計等
• 開源與可攜性：基於 C++ STL，追求跨平台可攜性
• 高擴充性：採 Strategy Pattern 類似架構，執行期動態註冊 Handler

整體處理流程

圖一：文字處理流程

1. 原始文字以字元流讀入記憶體
2. 逐行解析，產生 Token 序列
3. Token 流作為格式化/統計處理的輸入
4. 格式化後輸出至檔案或標準輸出；統計結果直接輸出

類別架構

圖二：框架類別圖

核心採類似 Strategy Pattern 組織：

核心組件

ParseHandler (抽象類別)

所有解析 Handler 基類，定義 accept() 方法：從目前位置按指定方式解析當前行。成功則填入 TokenInfo、前進位置並回傳 true；失敗回傳 false 讓框架嘗試下一個 Handler。

優先權機制：參考 Java 執行緒優先權設計。註解與字串解析需高優先權 (MAX_PRIORITY)，避免關鍵字在註解/字串中被誤判。預設 DefaultParseHandler 為 MIN_PRIORITY，作為最後防線防止死循環。

LineParser

逐行逐字解析，透過 getTokensInfoList() 取得結果。支援 registParseHandler()/unregistParseHandler() 執行期動態調整，同一 Parser 物件可切換解析 C++ 或組合語言。

FormatHandler (抽象類別)

格式化 Handler 基類，定義 format() 方法。處理結果直接修改傳入字串，多 Handler 依註冊順序鏈式處理。附帶統計功能：若不修改字串僅分析內容，即可實作關鍵字統計、註解行統計等。

LineFormator

逐行格式化，getFormattedLines() 取得結果。允許同類 Token 註冊多個 Handler (如先縮排再 HTML 化)，提供極大彈性。

輔助類別

• Session：模仿 ASP/JSP Session，Handler 間傳遞資料的 Map 容器
• Context：解析/格式化上下文 (行號、當前 Token、位置等)，內含 Session 成員
• FileHelper：檔案讀寫輔助
• FileFinder：目錄遞迴搜尋特定檔案 (Windows 平台需定義 __WINDOWS__)

擴充組件 (extend)

解析 Handler：StringParseHandler、NumberParseHandler、OperatorParseHandler、IdentifierParseHandler、WhitespaceParseHandler、CommentParseHandler

格式化 Handler：Htmlize::BodyOutputHandler、Indent::NormalOutputHandler、Indent::WhitespaceOutputHandler、Indent::OperatorOutputHandler

統計 Handler：Count::KeywordCountHandler、Count::CommentCountHandler

檔案清單

已知問題與改進方向

• 效率與彈性權衡：非最佳效率，但換取高擴充性
• LineFormator 統計模式冗餘：部分介面在統計用途下多餘
• 新語言支援需改原始碼：未來可考慮 Template 檔案方案，無需重編譯
• 缺乏 GUI：僅提供命令列示範，GUI 擴充不屬框架核心範疇

命名空間建議

• 通用 Parse Handler：TextFormator::XXX
• 特定語言 Handler：TextFormator::Language_Name::XXX
• 具體應用擴充：TextFormator::Util_Name::XXX

聯絡資訊

歡迎建議與討論：moying@etang.com