PhraseKit

PhraseKit 是一个 Swift 包，旨在生成由各种词性（如形容词、名词、动词和副词）组成的随机、人类可读的短语。它提供了灵活的选项来生成具有不同单词类型组合的短语，确保每个短语都是独特的且语法上合理的。

为何使用此包？

在各种需要生成随机但有意义的短语的应用场景中，PhraseKit 都是理想之选。以下是一些 PhraseKit 特别有用的情景：

随机文件名： 生成独特、描述性的文件名，易于识别和记忆，例如 happy-banana.txt 或 swift-cloud.png。
用户名或显示名： 为用户创建随机的用户名或显示名，例如 brave-panda 或 running-tiger。
会话 ID 或令牌： 生成人类可读的会话 ID 或令牌，与随机字符字符串相比，更易于识别和调试。
创意写作： 将 PhraseKit 用作生成随机提示或想法的工具，用于创意写作、头脑风暴会议或游戏开发。
命名约定： 简化变量、函数或项目的命名过程，使其既系统化又随机化。
任何需要随机短语的地方： 无论您是在构建应用程序、编写脚本，还是仅仅需要随机短语进行测试，PhraseKit 都提供了一个灵活且易于使用的解决方案。

凭借其自定义单词列表和组合类型的能力，PhraseKit 不仅仅是一个随机生成器，它还是一个适应您特定需求的工具。

功能特性

随机短语生成： 创建包含形容词、名词、动词和副词组合的短语。
可配置的单词计数： 生成包含两个或三个单词的短语。
自定义组合类型： 指定单词组合的类型（例如，形容词 + 名词，动词 + 名词）。
唯一性保证： 确保每个生成的短语都是唯一的，并防止重复。
错误处理： 为所有可能的组合都已用尽的情况提供错误处理。
可扩展性： 易于扩展和集成到其他项目中。

安装

Swift Package Manager

要将 PhraseKit 添加到您的项目中，请使用 Swift Package Manager。

在 Xcode 中打开您的项目。
转到 File > Add Packages。
在搜索栏中，输入 PhraseKit 仓库的 URL
```
https://github.com/markbattistella/PhraseKit
```
点击 Add Package。

用法

基本用法

导入 PhraseKit 包并创建 PhraseGenerator 的实例以开始生成短语。

import PhraseKit

let generator = PhraseGenerator()

// Generate a random two-word phrase
if let phrase = generator.generatePhrase() {
  print("Generated phrase: \(phrase)")
}

// Generate a random three-word phrase
if let threeWordPhrase = generator.generatePhrase(wordCount: .three) {
  print("Generated three-word phrase: \(threeWordPhrase)")
}

自定义组合类型

您可以指定要生成的单词组合类型

let adjectiveNounPhrase = generator.generatePhrase(combinationType: .adjectiveNoun)
print("Adjective + Noun phrase: \(adjectiveNounPhrase ?? "Failed to generate")")

let adverbVerbPhrase = generator.generatePhrase(combinationType: .adverbVerb)
print("Adverb + Verb phrase: \(adverbVerbPhrase ?? "Failed to generate")")

处理耗尽的组合

PhraseKit 提供了各种方法来处理所有可能的组合都已耗尽的情况

// Throw an error if all combinations are exhausted
do {
  let uniquePhrase = try generator.generateUniquePhrase()
  print("Unique phrase: \(uniquePhrase)")
} catch {
  print("Error: \(error)")
}

// Return a default phrase if all combinations are exhausted
let defaultPhrase = generator.generateUniquePhrase(orDefault: "default-phrase")
print("Phrase or default: \(defaultPhrase)")

// Return a custom message if all combinations are exhausted
let customMessagePhrase = generator.generateUniquePhrase(orMessage: "No more phrases available")
print("Phrase or custom message: \(customMessagePhrase)")

// Silent failure: returns an empty string if all combinations are exhausted
let silentPhrase = generator.uniquePhrase
print("Silent phrase: \(silentPhrase.isEmpty ? "No phrase available" : silentPhrase)")

排除列表

PhraseKit 允许您指定一个排除列表，其中包含应从任何生成的短语中排除的单词。如果您想防止某些单词出现在输出中，例如不恰当的词语、保留字或任何其他不需要的术语，这将特别有用。

使用排除列表

您可以在初始化 PhraseGenerator 时提供排除列表。此列表将在生成任何短语之前，从可用的词汇库（名词、动词、形容词、副词或自定义单词）中过滤掉指定的单词。

import PhraseKit

// Example exclusion list
let exclusionWords = ["apple", "orange", "badWord"]

// Initialize the PhraseGenerator with the exclusion list
let generator = PhraseGenerator(exclusionList: exclusionWords)

// Generate a random two-word phrase, ensuring excluded words are not used
if let phrase = generator.generatePhrase() {
    print("Generated phrase: \(phrase)")
}

排除列表的工作原理

排除列表适用于短语生成过程中使用的所有单词列表，包括名词、动词、形容词、副词和任何自定义单词列表。
在生成任何短语之前，将应用排除列表，确保词汇库中不存在任何排除的单词。
getWordCombinationCount 函数也将遵守排除列表，在排除后提供可能的组合的准确计数。

此功能确保您生成的短语满足特定要求并避免任何不需要的术语，使 PhraseKit 具有高度的可定制性，并能适应各种用例。

可扩展性

PhraseKit 库在设计时就考虑了可扩展性，允许您自定义和扩展其功能，以满足您项目的独特需求。无论您是想加载自定义单词列表还是调整生成单词组合的逻辑，PhraseKit 都提供了一个灵活的框架来实现这一点。

自定义单词加载

默认情况下，PhraseKit 从库中包含的 JSON 文件加载单词列表（名词、动词、形容词和副词）。但是，您可以通过提供自定义单词列表来轻松覆盖此行为。如果您需要使用特定的单词集生成短语，或者您的应用程序需要不同的或额外的词性，这将特别有用。

使用自定义单词加载器

要加载自定义单词列表，请在您自己的类中实现 WordLoaderProtocol，并通过此加载器提供自定义单词。以下是如何执行此操作的示例

import PhraseKit

// Implement the WordLoaderProtocol
class MyCustomWordLoader: WordLoaderProtocol {
  func loadWords() -> [String] {
    // Load your custom words from a source, e.g., a local file, database, or API
    return ["customWord1", "customWord2", "customWord3"]
  }
}

// Initialize PhraseGenerator with the custom loader
let customLoader = MyCustomWordLoader()
let generator = PhraseGenerator(customLoader: customLoader)

// Generate a phrase using the custom words
if let phrase = generator.generatePhrase() {
  print("Generated phrase: \(phrase)")
}

在此示例中，PhraseGenerator 将专门使用 MyCustomWordLoader 提供的自定义单词进行短语生成，而忽略默认的从 JSON 文件加载的单词列表。

扩展单词组合

PhraseGenerator 类默认支持各种类型的单词组合，例如形容词-名词或动词-名词。但是，如果您的项目需要不同类型的组合，或者您想包含额外的逻辑，您可以扩展 PhraseGenerator 或在您的单词加载器中实现您的自定义逻辑。

示例：自定义组合逻辑

您可能希望引入新的逻辑，根据特定规则或模式配对单词。这可以通过扩展 CombinationType 枚举或通过在 PhraseGenerator 的子类中的 generateWordPair 方法中添加自定义逻辑来完成。

import PhraseKit

class CustomPhraseGenerator: PhraseGenerator {
  
  override func generateWordPair(combinationType: CombinationType? = nil) -> String? {
    // Custom logic for generating word pairs
    let customType = combinationType ?? .adjectiveNoun
    
    switch customType {
      case .adjectiveNoun:
        return generatePair(from: adjectives, and: nouns)
      // Add your custom combination logic here
      default:
        return super.generateWordPair(combinationType: combinationType)
    }
  }
}

let customGenerator = CustomPhraseGenerator()
if let phrase = customGenerator.generatePhrase() {
  print("Custom generated phrase: \(phrase)")
}

此示例演示了如何扩展或修改组合逻辑以适应特定需求，同时仍然利用 PhraseKit 的底层结构。

测试

PhraseKit 配备了全面的测试套件，以确保可靠性和正确性。这些测试涵盖了各种场景，包括默认短语生成、特定单词组合和错误处理。

要运行测试，请使用

swift test

贡献

欢迎贡献！如果您有建议或改进，请 Fork 仓库并提交 Pull Request。

许可证

PhraseKit 在 MIT 许可证下发布。有关详细信息，请参阅 LICENSE。