Add isEmpty() to Compositor & Node; Plus buffs & doc fixes. (#54)

* Compositor & Node // +isEmpty. (#51)

* Documentation fixes & Deprecating compareScore(). (#52)

* Unigram // Deprecating compareScore().

* Documentation fixes.

* Remove mutLM from Node. (#53)

* Explicitly mark certain values public.

README.md

@@ -10,7 +10,7 @@ Megrez Engine is a module made for processing lingual data of an input method. T
 
 ### §1. 初期化
 
-在你的 ctlInputMethod (InputMethodController) 或者 KeyHandler 內初期化一份 Megrez.Compositor 分節讀音槽副本（這裡將該副本命名為「`compositor`」）。由於 Megrez.Compositor 的型別是 Class 型別，所以其副本可以用 let 來宣告。
+在你的 ctlInputMethod (InputMethodController) 或者 KeyHandler 內初期化一份 Megrez.Compositor 組字器副本（這裡將該副本命名為「`compositor`」）。由於 Megrez.Compositor 的型別是 Class 型別，所以其副本可以用 let 來宣告。
 
 以 KeyHandler 為例：
 ```swift
@@ -35,10 +35,10 @@ class ctlInputMethod: IMKInputController {
 
 這裡就需要在 init() 時使用參數：
 ```swift
-  /// 分節讀音槽。
+  /// 組字器。
   /// - Parameters:
   ///   - lm: 語言模型。可以是任何基於 Megrez.LanguageModel 的衍生型別。
-  ///   - length: 指定該分節讀音槽內可以允許的最大詞長，預設為 10 字。
+  ///   - length: 指定該組字器內可以允許的最大詞長，預設為 10 字。
   ///   - separator: 多字讀音鍵當中用以分割漢字讀音的記號，預設為空。
   let compositor: Megrez.Compositor = .init(lm: lmTest, length: 13, separator: "-")
 ```

Sources/Megrez/1_Compositor.swift

@@ -24,48 +24,51 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
 
 extension Megrez {
-  /// 分節讀音槽。
+  /// 組字器。
   public class Compositor {
     /// 給被丟掉的節點路徑施加的負權重。
     private let kDroppedPathScore: Double = -999
-    /// 該分節讀音槽的游標位置。
+    /// 該組字器的游標位置。
     private var mutCursorIndex: Int = 0
-    /// 該分節讀音槽的讀音陣列。
+    /// 該組字器的讀音陣列。
     private var mutReadings: [String] = []
-    /// 該分節讀音槽的軌格。
+    /// 該組字器的軌格。
     private var mutGrid: Grid = .init()
-    /// 該分節讀音槽所使用的語言模型。
+    /// 該組字器所使用的語言模型。
     private var mutLM: LanguageModel
 
-    /// 公開該分節讀音槽內可以允許的最大詞長。
+    /// 公開：該組字器內可以允許的最大詞長。
     public var maxBuildSpanLength: Int { mutGrid.maxBuildSpanLength }
     /// 公開：多字讀音鍵當中用以分割漢字讀音的記號，預設為空。
     public var joinSeparator: String = ""
-    /// 公開：該分節讀音槽的游標位置。
+    /// 公開：該組字器的游標位置。
     public var cursorIndex: Int {
       get { mutCursorIndex }
       set { mutCursorIndex = (newValue < 0) ? 0 : min(newValue, mutReadings.count) }
     }
 
-    /// 公開：該分節讀音槽的軌格（唯讀）。
+    /// 公開：該組字器是否為空。
+    public var isEmpty: Bool { mutGrid.isEmpty }
+
+    /// 公開：該組字器的軌格（唯讀）。
     public var grid: Grid { mutGrid }
-    /// 公開：該分節讀音槽的長度，也就是內建漢字讀音的數量（唯讀）。
+    /// 公開：該組字器的長度，也就是內建漢字讀音的數量（唯讀）。
     public var length: Int { mutReadings.count }
-    /// 公開：該分節讀音槽的讀音陣列（唯讀）。
+    /// 公開：該組字器的讀音陣列（唯讀）。
     public var readings: [String] { mutReadings }
 
-    /// 分節讀音槽。
+    /// 組字器。
     /// - Parameters:
     ///   - lm: 語言模型。可以是任何基於 Megrez.LanguageModel 的衍生型別。
-    ///   - length: 指定該分節讀音槽內可以允許的最大詞長，預設為 10 字。
+    ///   - length: 指定該組字器內可以允許的最大詞長，預設為 10 字。
     ///   - separator: 多字讀音鍵當中用以分割漢字讀音的記號，預設為空。
     public init(lm: LanguageModel, length: Int = 10, separator: String = "") {
       mutLM = lm
       mutGrid = .init(spanLength: abs(length))  // 防呆
       joinSeparator = separator
     }
 
-    /// 分節讀音槽自我清空專用函數。
+    /// 組字器自我清空專用函數。
     public func clear() {
       mutCursorIndex = 0
       mutReadings.removeAll()
@@ -109,7 +112,7 @@ extension Megrez {
       return true
     }
 
-    /// 移除該分節讀音槽的第一個讀音單元。
+    /// 移除該組字器最先被輸入的第 X 個讀音單元。
     ///
     /// 用於輸入法組字區長度上限處理：
     /// 將該位置要溢出的敲字內容遞交之後、再執行這個函數。

Sources/Megrez/2_Grid.swift

@@ -32,12 +32,16 @@ extension Megrez {
     /// 該幅位內可以允許的最大詞長。
     private var mutMaxBuildSpanLength = 10
 
-    /// 公開：該幅位內可以允許的最大詞長。
+    /// 公開：該軌格內可以允許的最大幅位長度。
     public var maxBuildSpanLength: Int { mutMaxBuildSpanLength }
 
-    /// 軌格的寬度，也就是其內的幅位陣列當中的幅位數量。
-    var width: Int { mutSpans.count }
+    /// 公開：軌格的寬度，也就是其內的幅位陣列當中的幅位數量。
+    public var width: Int { mutSpans.count }
 
+    /// 公開：軌格是否為空。
+    public var isEmpty: Bool { mutSpans.isEmpty }
+
+    /// 初期化轨格。
     public init(spanLength: Int = 10) {
       mutMaxBuildSpanLength = spanLength
       mutSpans = [Megrez.Span]()
@@ -190,6 +194,8 @@ extension Megrez {
     }
 
     /// 將給定位置的節點的候選字詞改為與給定的字串一致的候選字詞。
+    ///
+    /// 該函數可以僅用作過程函數。
     /// - Parameters:
     ///   - location: 位置。
     ///   - value: 給定字串。
@@ -242,6 +248,7 @@ extension Megrez {
 // MARK: - DumpDOT-related functions.
 
 extension Megrez.Grid {
+  /// 生成用以交給 GraphViz 診斷的資料檔案內容，純文字。
   public var dumpDOT: String {
     var strOutput = "digraph {\ngraph [ rankdir=LR ];\nBOS;\n"
     for (p, span) in mutSpans.enumerated() {

Sources/Megrez/3_Span.swift

@@ -32,7 +32,7 @@ extension Megrez {
     private var mutMaximumLength: Int = 0
 
     /// 公開：最長幅距（唯讀）。
-    var maximumLength: Int {
+    public var maximumLength: Int {
       mutMaximumLength
     }
 

Sources/Megrez/4_Node.swift

@@ -26,8 +26,6 @@ CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 extension Megrez {
   /// 節點。
   public class Node {
-    /// 當前節點對應的語言模型。
-    private let mutLM: LanguageModel = .init()
     /// 鍵。
     private var mutKey: String = ""
     /// 當前節點的當前被選中的候選字詞「在該節點內的」目前的權重。
@@ -54,21 +52,21 @@ extension Megrez {
     }
 
     /// 公開：候選字詞陣列（唯讀），以鍵值陣列的形式存在。
-    var candidates: [KeyValuePair] { mutCandidates }
+    public var candidates: [KeyValuePair] { mutCandidates }
     /// 公開：用來登記「當前選中的單元圖」的索引值的變數（唯讀）。
-    var isCandidateFixed: Bool { mutCandidateFixed }
+    public var isCandidateFixed: Bool { mutCandidateFixed }
 
     /// 公開：鍵（唯讀）。
-    var key: String { mutKey }
+    public var key: String { mutKey }
     /// 公開：當前節點的當前被選中的候選字詞「在該節點內的」目前的權重（唯讀）。
-    var score: Double { mutScore }
+    public var score: Double { mutScore }
     /// 公開：當前被選中的候選字詞的鍵值配對。
-    var currentKeyValue: KeyValuePair {
+    public var currentKeyValue: KeyValuePair {
       mutSelectedUnigramIndex >= mutUnigrams.count ? KeyValuePair() : mutCandidates[mutSelectedUnigramIndex]
     }
 
     /// 公開：給出當前單元圖陣列內最高的權重數值。
-    var highestUnigramScore: Double { mutUnigrams.isEmpty ? 0.0 : mutUnigrams[0].score }
+    public var highestUnigramScore: Double { mutUnigrams.isEmpty ? 0.0 : mutUnigrams[0].score }
 
     /// 初期化一個節點。
     /// - Parameters:

Sources/Megrez/5_LanguageModel.swift

@@ -30,17 +30,17 @@ extension Megrez {
 
     // 這裡寫了一點假內容，不然有些 Swift 格式化工具會破壞掉函數的參數設計。
 
-    /// 給定鍵，讓語言模型找給一筆單元圖。
+    /// 給定鍵，讓語言模型找給一組單元圖陣列。
     open func unigramsFor(key: String) -> [Megrez.Unigram] {
       key.isEmpty ? [Megrez.Unigram]() : [Megrez.Unigram]()
     }
 
-    /// 給定當前鍵與前述鍵，讓語言模型找給一筆雙元圖。
+    /// 給定當前鍵與前述鍵，讓語言模型找給一組雙元圖陣列。
     open func bigramsForKeys(precedingKey: String, key: String) -> [Megrez.Bigram] {
       precedingKey == key ? [Megrez.Bigram]() : [Megrez.Bigram]()
     }
 
-    /// 給定鍵，
+    /// 給定鍵，確認是否有單元圖記錄在庫。
     open func hasUnigramsFor(key: String) -> Bool {
       key.count != 0
     }

Sources/Megrez/6_Unigram.swift

@@ -49,11 +49,6 @@ extension Megrez {
       hasher.combine(score)
     }
 
-    // 這個函數不再需要了。
-    public static func compareScore(a: Unigram, b: Unigram) -> Bool {
-      a.score > b.score
-    }
-
     public static func == (lhs: Unigram, rhs: Unigram) -> Bool {
       lhs.keyValue == rhs.keyValue && lhs.score == rhs.score
     }

Sources/Megrez/7_KeyValuePair.swift

@@ -35,7 +35,7 @@ extension Megrez {
       "(" + key + "," + value + ")"
     }
 
-    /// 初期化一組鍵值配對
+    /// 初期化一組鍵值配對。
     /// - Parameters:
     ///   - key: 鍵。一般情況下用來放置讀音等可以用來作為索引的內容。
     ///   - value: 資料值。