{"id":15066974,"url":"https://github.com/markbattistella/phrasekit","last_synced_at":"2025-07-12T16:33:13.871Z","repository":{"id":253237094,"uuid":"842898224","full_name":"markbattistella/PhraseKit","owner":"markbattistella","description":"PhraseKit is a Swift package that generates random, human-readable phrases using customizable word combinations. Perfect for creating unique filenames, usernames, session IDs, and more. Easily extensible with custom word lists and combination logic.","archived":false,"fork":false,"pushed_at":"2024-10-11T06:08:17.000Z","size":754,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-17T17:39:47.478Z","etag":null,"topics":["hacktoberfest","human-readable","ios","macos","phrase-generator","random-generator","random-phrases","spm","swift","swift-package","tvos","visionos","watchos","word-combinations"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/markbattistella.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"custom":["https://www.paypal.me/markbattistella/5AUD","https://www.paypal.me/markbattistella/10AUD","https://www.paypal.me/markbattistella/20AUD"]}},"created_at":"2024-08-15T10:44:17.000Z","updated_at":"2024-10-20T16:59:07.000Z","dependencies_parsed_at":"2024-08-15T12:24:00.233Z","dependency_job_id":"7c008751-d3ec-47ec-aa51-4911f785caad","html_url":"https://github.com/markbattistella/PhraseKit","commit_stats":null,"previous_names":["markbattistella/phrasekit"],"tags_count":3,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markbattistella%2FPhraseKit","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markbattistella%2FPhraseKit/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markbattistella%2FPhraseKit/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/markbattistella%2FPhraseKit/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/markbattistella","download_url":"https://codeload.github.com/markbattistella/PhraseKit/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225829240,"owners_count":17530666,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["hacktoberfest","human-readable","ios","macos","phrase-generator","random-generator","random-phrases","spm","swift","swift-package","tvos","visionos","watchos","word-combinations"],"created_at":"2024-09-25T01:14:39.920Z","updated_at":"2024-11-22T01:40:28.750Z","avatar_url":"https://github.com/markbattistella.png","language":"Swift","funding_links":["https://www.paypal.me/markbattistella/5AUD","https://www.paypal.me/markbattistella/10AUD","https://www.paypal.me/markbattistella/20AUD"],"categories":[],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable MD033 MD041 --\u003e\n\u003cdiv align=\"center\"\u003e\n\n# PhraseKit\n\n[![Swift Version][Shield1]](https://swiftpackageindex.com/markbattistella/PhraseKit)\n\n[![OS Platforms][Shield2]](https://swiftpackageindex.com/markbattistella/PhraseKit)\n\n[![Licence][Shield3]](https://github.com/markbattistella/PhraseKit/blob/main/LICENSE)\n\n\u003c/div\u003e\n\n`PhraseKit` is a Swift package designed to generate random, human-readable phrases composed of various parts of speech, such as adjectives, nouns, verbs, and adverbs. It provides flexible options for generating phrases with different combinations of word types, ensuring that each phrase is unique and grammatically meaningful.\n\n## Why Use This Package?\n\n`PhraseKit` is ideal for a variety of applications where you need to generate random, yet meaningful, phrases. Here are some scenarios where `PhraseKit` could be particularly useful:\n\n- **Random File Names:** Generate unique, descriptive filenames that are easy to recognise and remember, like happy-banana.txt or swift-cloud.png.\n- **Usernames or Display Names:** Create random usernames or display names for users, such as brave-panda or running-tiger.\n- **Session IDs or Tokens:** Produce human-readable session IDs or tokens that are easier to identify and debug compared to random strings of characters.\n- **Creative Writing:** Use PhraseKit as a tool for generating random prompts or ideas for creative writing, brainstorming sessions, or game development.\n- **Naming Conventions:** Simplify the process of naming variables, functions, or projects in a way that is both systematic and random.\n- **Anywhere You Need Random Phrases:** Whether you’re building an app, writing scripts, or just need random phrases for testing, PhraseKit offers a flexible and easy-to-use solution.\n\nWith its ability to customise word lists and combination types, PhraseKit is not just a random generator—it's a tool that adapts to your specific needs.\n\n## Features\n\n- **Random Phrase Generation:** Create phrases with combinations of adjectives, nouns, verbs, and adverbs.\n- **Configurable Word Count:** Generate phrases with two or three words.\n- **Custom Combination Types:** Specify the types of word combinations (e.g., adjective + noun, verb + noun).\n- **Uniqueness Guarantee:** Ensures that each generated phrase is unique and prevents duplicates.\n- **Error Handling:** Provides error handling for cases where all possible combinations are exhausted.\n- **Extensibility:** Easy to extend and integrate into other projects.\n\n## Installation\n\n### Swift Package Manager\n\nTo add `PhraseKit` to your project, use the Swift Package Manager.\n\n1. Open your project in Xcode.\n1. Go to `File \u003e Add Packages`.\n1. In the search bar, enter the URL of the `PhraseKit` repository:\n  \n    ```url\n    https://github.com/markbattistella/PhraseKit\n    ```\n\n1. Click `Add Package`.\n\n## Usage\n\n### Basic Usage\n\nImport the `PhraseKit` package and create an instance of `PhraseGenerator` to start generating phrases.\n\n```swift\nimport PhraseKit\n\nlet generator = PhraseGenerator()\n\n// Generate a random two-word phrase\nif let phrase = generator.generatePhrase() {\n  print(\"Generated phrase: \\(phrase)\")\n}\n\n// Generate a random three-word phrase\nif let threeWordPhrase = generator.generatePhrase(wordCount: .three) {\n  print(\"Generated three-word phrase: \\(threeWordPhrase)\")\n}\n```\n\n### Custom Combination Types\n\nYou can specify the type of word combination you'd like to generate:\n\n```swift\nlet adjectiveNounPhrase = generator.generatePhrase(combinationType: .adjectiveNoun)\nprint(\"Adjective + Noun phrase: \\(adjectiveNounPhrase ?? \"Failed to generate\")\")\n\nlet adverbVerbPhrase = generator.generatePhrase(combinationType: .adverbVerb)\nprint(\"Adverb + Verb phrase: \\(adverbVerbPhrase ?? \"Failed to generate\")\")\n```\n\n#### Handling Exhausted Combinations\n\n`PhraseKit` provides various methods to handle cases where all possible combinations are exhausted:\n\n```swift\n// Throw an error if all combinations are exhausted\ndo {\n  let uniquePhrase = try generator.generateUniquePhrase()\n  print(\"Unique phrase: \\(uniquePhrase)\")\n} catch {\n  print(\"Error: \\(error)\")\n}\n\n// Return a default phrase if all combinations are exhausted\nlet defaultPhrase = generator.generateUniquePhrase(orDefault: \"default-phrase\")\nprint(\"Phrase or default: \\(defaultPhrase)\")\n\n// Return a custom message if all combinations are exhausted\nlet customMessagePhrase = generator.generateUniquePhrase(orMessage: \"No more phrases available\")\nprint(\"Phrase or custom message: \\(customMessagePhrase)\")\n\n// Silent failure: returns an empty string if all combinations are exhausted\nlet silentPhrase = generator.uniquePhrase\nprint(\"Silent phrase: \\(silentPhrase.isEmpty ? \"No phrase available\" : silentPhrase)\")\n```\n\n### Exclusion List\n\n`PhraseKit` allows you to specify an exclusion list of words that should be excluded from any generated phrases. This is particularly useful if you want to prevent certain words from appearing in the output, such as inappropriate words, reserved words, or any other undesired terms.\n\n#### Using the Exclusion List\n\nYou can provide an exclusion list when initialising the `PhraseGenerator`. This list will filter out the specified words from the available word pools (nouns, verbs, adjectives, adverbs, or custom words) before any phrases are generated.\n\n```swift\nimport PhraseKit\n\n// Example exclusion list\nlet exclusionWords = [\"apple\", \"orange\", \"badWord\"]\n\n// Initialize the PhraseGenerator with the exclusion list\nlet generator = PhraseGenerator(exclusionList: exclusionWords)\n\n// Generate a random two-word phrase, ensuring excluded words are not used\nif let phrase = generator.generatePhrase() {\n    print(\"Generated phrase: \\(phrase)\")\n}\n```\n\n#### How the Exclusion List Works\n\n- The exclusion list applies to all word lists used in the phrase generation process, including nouns, verbs, adjectives, adverbs, and any custom word lists.\n- Before any phrase is generated, the exclusion list is applied, ensuring that no excluded words are present in the word pool.\n- The `getWordCombinationCount` function will also respect the exclusion list, providing an accurate count of possible combinations after exclusions.\n\nThis feature ensures that your generated phrases meet specific requirements and avoid any unwanted terms, making PhraseKit highly customisable and adaptable to various use cases.\n\n## Extensibility\n\nThe `PhraseKit` library is designed with extensibility in mind, allowing you to customise and extend its functionality to meet the unique needs of your project. Whether you want to load custom word lists or adjust the logic for generating word combinations, `PhraseKit` provides a flexible framework to do so.\n\n### Custom Word Loading\n\nBy default, `PhraseKit` loads word lists (nouns, verbs, adjectives, and adverbs) from JSON files included in the library. However, you can easily override this behaviour by providing your custom word lists. This is especially useful if you need to generate phrases using a specific set of words or if your application requires different or additional parts of speech.\n\n#### Using a Custom Word Loader\n\nTo load custom word lists, implement the `WordLoaderProtocol` in your own class and provide the custom words through this loader. Here’s an example of how to do this:\n\n```swift\nimport PhraseKit\n\n// Implement the WordLoaderProtocol\nclass MyCustomWordLoader: WordLoaderProtocol {\n  func loadWords() -\u003e [String] {\n    // Load your custom words from a source, e.g., a local file, database, or API\n    return [\"customWord1\", \"customWord2\", \"customWord3\"]\n  }\n}\n\n// Initialize PhraseGenerator with the custom loader\nlet customLoader = MyCustomWordLoader()\nlet generator = PhraseGenerator(customLoader: customLoader)\n\n// Generate a phrase using the custom words\nif let phrase = generator.generatePhrase() {\n  print(\"Generated phrase: \\(phrase)\")\n}\n```\n\nIn this example, the `PhraseGenerator` will exclusively use the custom words provided by `MyCustomWordLoader` for phrase generation, ignoring the default word lists that are otherwise loaded from JSON files.\n\n### Extending Word Combinations\n\nThe `PhraseGenerator` class supports various types of word combinations by default, such as adjective-noun or verb-noun. However, if your project requires a different type of combination or you want to include additional logic, you can extend the `PhraseGenerator` or implement your custom logic in your word loader.\n\n#### Example: Custom Combination Logic\n\nYou might want to introduce new logic that pairs words based on a specific rule or pattern. This can be done by extending the `CombinationType` enum or by adding custom logic to the generateWordPair method in a subclass of `PhraseGenerator`.\n\n```swift\nimport PhraseKit\n\nclass CustomPhraseGenerator: PhraseGenerator {\n  \n  override func generateWordPair(combinationType: CombinationType? = nil) -\u003e String? {\n    // Custom logic for generating word pairs\n    let customType = combinationType ?? .adjectiveNoun\n    \n    switch customType {\n      case .adjectiveNoun:\n        return generatePair(from: adjectives, and: nouns)\n      // Add your custom combination logic here\n      default:\n        return super.generateWordPair(combinationType: combinationType)\n    }\n  }\n}\n\nlet customGenerator = CustomPhraseGenerator()\nif let phrase = customGenerator.generatePhrase() {\n  print(\"Custom generated phrase: \\(phrase)\")\n}\n```\n\nThis example demonstrates how you can extend or modify the combination logic to suit specific requirements, while still leveraging the underlying structure of `PhraseKit`.\n\n## Testing\n\n`PhraseKit` comes with a comprehensive test suite to ensure reliability and correctness. The tests cover various scenarios, including default phrase generation, specific word combinations, and error handling.\n\nTo run the tests, use:\n\n```bash\nswift test\n```\n\n## Contributing\n\nContributions are welcome! If you have suggestions or improvements, please fork the repository and submit a pull request.\n\n## License\n\n`PhraseKit` is released under the MIT license. See [LICENSE](https://github.com/markbattistella/PhraseKit/blob/main/LICENSE) for details.\n\n[Shield1]: https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fmarkbattistella%2FPhraseKit%2Fbadge%3Ftype%3Dswift-versions\n\n[Shield2]: https://img.shields.io/endpoint?url=https%3A%2F%2Fswiftpackageindex.com%2Fapi%2Fpackages%2Fmarkbattistella%2FPhraseKit%2Fbadge%3Ftype%3Dplatforms\n\n[Shield3]: https://img.shields.io/badge/Licence-MIT-white?labelColor=blue\u0026style=flat\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkbattistella%2Fphrasekit","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmarkbattistella%2Fphrasekit","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmarkbattistella%2Fphrasekit/lists"}