{"id":16487207,"url":"https://github.com/nerdsupremacist/syntax","last_synced_at":"2025-12-11T23:01:39.020Z","repository":{"id":38273089,"uuid":"183608602","full_name":"nerdsupremacist/Syntax","owner":"nerdsupremacist","description":"Write value-driven parsers quickly in Swift with an intuitive SwiftUI-like DSL","archived":false,"fork":false,"pushed_at":"2022-07-03T03:05:05.000Z","size":2830,"stargazers_count":147,"open_issues_count":5,"forks_count":11,"subscribers_count":7,"default_branch":"develop","last_synced_at":"2025-02-27T12:14:41.928Z","etag":null,"topics":["dsl","parser-combinators","parsing","swift"],"latest_commit_sha":null,"homepage":"https://quickbirdstudios.com/blog/swift-string-parse/","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/nerdsupremacist.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-04-26T10:24:39.000Z","updated_at":"2025-02-17T13:41:25.000Z","dependencies_parsed_at":"2022-08-18T13:11:30.280Z","dependency_job_id":null,"html_url":"https://github.com/nerdsupremacist/Syntax","commit_stats":null,"previous_names":["nerdsupremacist/ogma"],"tags_count":10,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerdsupremacist%2FSyntax","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerdsupremacist%2FSyntax/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerdsupremacist%2FSyntax/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nerdsupremacist%2FSyntax/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nerdsupremacist","download_url":"https://codeload.github.com/nerdsupremacist/Syntax/tar.gz/refs/heads/develop","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":243826783,"owners_count":20354220,"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":["dsl","parser-combinators","parsing","swift"],"created_at":"2024-10-11T13:33:11.880Z","updated_at":"2025-12-11T23:01:38.619Z","avatar_url":"https://github.com/nerdsupremacist.png","language":"Swift","readme":"\u003cp align=\"center\"\u003e\n    \u003cimg src=\"logo.png\" width=\"400\" max-width=\"90%\" alt=\"Syntax\" /\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/Swift-5.7-orange.svg\" /\u003e\n    \u003ca href=\"https://swift.org/package-manager\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/swiftpm-compatible-brightgreen.svg?style=flat\" alt=\"Swift Package Manager\" /\u003e\n    \u003c/a\u003e\n    \u003ca href=\"https://twitter.com/nerdsupremacist\"\u003e\n        \u003cimg src=\"https://img.shields.io/badge/twitter-@nerdsupremacist-blue.svg?style=flat\" alt=\"Twitter: @nerdsupremacist\" /\u003e\n    \u003c/a\u003e\n\u003c/p\u003e\n\n# Syntax\n\nSay goodbye to Scanner's and Abstract Syntax Trees. \nSyntax will take text, and turn it into the model that you actually need.\n\nSyntax is a SwiftUI-like data-driven parser builder DSL. You use composition and functional programming to implement a top-down LL(n) parser with minimal effort.\nThe result is a Parser tailor made to fit your desired output model ;)\n\n## Installation\n### Swift Package Manager\n\nYou can install Syntax via [Swift Package Manager](https://swift.org/package-manager/) by adding the following line to your `Package.swift`:\n\n```swift\nimport PackageDescription\n\nlet package = Package(\n    [...]\n    dependencies: [\n        .package(url: \"https://github.com/nerdsupremacist/Syntax.git\", from: \"3.0.0\"), // for Swift 5.7\n        .package(url: \"https://github.com/nerdsupremacist/Syntax.git\", from: \"2.0.0\"), // for Swift 5.4\n        .package(url: \"https://github.com/nerdsupremacist/Syntax.git\", from: \"1.0.0\"), // for Swift 5.3\n    ]\n)\n```\n\n## Usage\n\nSyntax allows you to write parsers that perfectly fit the model that you want.\nFor example, let's say you want to parse the output of [FizzBuzz](https://en.wikipedia.org/wiki/Fizz_buzz). \nWith syntax you begin writing your model:\n\n```swift\nenum FizzBuzzValue {\n    case number(Int)\n    case fizz\n    case buzz\n    case fizzBuzz\n}\n```\n\nAnd then you can just write a parser. Parser's in Syntax are structs that return a `body` much like in SwiftUI.\n\n```swift\nimport Syntax\n\nstruct FizzBuzzParser: Parser {\n    var body: any Parser\u003c[FizzBuzzValue]\u003e {\n        Repeat {\n            Either {\n                IntLiteral().map { FizzBuzzValue.number($0) }\n\n                Word(\"FizzBuzz\").map(to: FizzBuzzValue.fizzBuzz)\n                Word(\"Fizz\").map(to: FizzBuzzValue.fizz)\n                Word(\"Buzz\").map(to: FizzBuzzValue.buzz)\n            }\n        }\n    }\n}\n```\n\nLet's break that down:\n\n- `Repeat` signals that it should parse multiple values.\n- `Either` signals that you expect any of the following options.\n- `IntLiteral` will match the next integer literal it sees.\n- `Word` will match the word you give it, and only if it exists by itself.\n- `map` will map the value of a parser into something else.\n- `map(to:)` will map the value to a constant, useful for matching things like keywords.\n\nTo use this parser you can call the `parse` function:\n\n```swift\nlet text = \"1 2 Fizz\"\nlet values = try FizzBuzzParser().parse(text) // [.number(1), .number(2), .fizz]\n```\n\n### Syntax Tree's\n\nSyntax supports outputing an Abstract Syntax Tree. All nodes in the Syntax Tree are annotated with a kind. The kind will be automatically derived from the name of a parser, but you can also specify it yourself:\n\n```swift\nimport Syntax\n\nstruct FizzBuzzParser: Parser {\n    var body: any Parser\u003c[FizzBuzzValue]\u003e {\n        Repeat {\n            Either {\n                IntLiteral().map { FizzBuzzValue.number($0) }\n\n                Word(\"FizzBuzz\").map(to: FizzBuzzValue.fizzBuzz).kind(\"keyword.fizzbuzz\")\n                Word(\"Fizz\").map(to: FizzBuzzValue.fizz).kind(\"keyword.fizz\")\n                Word(\"Buzz\").map(to: FizzBuzzValue.buzz).kind(\"keyword.buzz\")\n            }\n        }\n    }\n}\n```\n\nTo get the AST you can ask for it via the `syntaxTree` function:\n\n```swift\nlet text = \"1 2 Fizz\"\nlet tree = FizzBuzzParser().syntaxTree(text)\n```\n\nThe AST is Encodable, so you can encode it into JSON. For example:\n\n```json\n{\n  \"startLocation\": { \"line\": 0, \"column\": 0 },\n  \"kind\": \"fizz.buzz\",\n  \"startOffset\": 0,\n  \"endLocation\": { \"line\": 0, \"column\": 8 },\n  \"endOffset\": 8,\n  \"children\": [\n    {\n      \"startLocation\": { \"line\": 0, \"column\": 0 },\n      \"kind\": \"int.literal\",\n      \"startOffset\": 0,\n      \"endLocation\": { \"line\": 0, \"column\": 1 },\n      \"endOffset\": 1,\n      \"value\": 1\n    },\n    {\n      \"startLocation\": { \"line\": 0, \"column\": 2 },\n      \"kind\": \"int.literal\",\n      \"startOffset\": 2,\n      \"endLocation\": { \"line\": 0, \"column\": 3 },\n      \"endOffset\": 3,\n      \"value\": 2\n    },\n    {\n      \"match\": \"Fizz\",\n      \"startLocation\": { \"line\": 0, \"column\": 4 },\n      \"kind\": \"keyword.fizz\",\n      \"startOffset\": 4,\n      \"endLocation\": { \"line\": 0, \"column\": 8 },\n      \"endOffset\": 8\n    }\n  ]\n}\n```\n\n### Syntax Highlighting\n\nYou can use your parser to highlight code on a [Publish](https://github.com/JohnSundell/Publish) Site using this [plugin](https://github.com/nerdsupremacist/syntax-highlight-publish-plugin).\n\n\n```swift\nimport SyntaxHighlightPublishPlugin\n\nextension Grammar {\n    // define Fizz Buzz Grammar\n    static let fizzBuzz = Grammar(name: \"FizzBuzz\") {\n        FizzBuzzParser()\n    }\n}\n\ntry MyPublishSite().publish(using: [\n    ...\n    // use plugin and include your Grammar\n    .installPlugin(.syntaxHighlighting(.fizzbuzz)),\n])\n```\n\n### More complex parsing\n\nAlright. I hear you. FizzBuzz isn't exactly a challenge. So let's take it up a notch and parse JSON instead.\nTo be able to parse JSON, we have to understand what JSON even is. JSON consists of \n\na) the primitive values like strings, numbers, booleans \nand b) any combinations of objects (dictionaries) and arrays.\n\nSo a possible model for JSON would be:\n\n```swift\nenum JSON {\n    case object([String : JSON])\n    case array([JSON])\n    case int(Int)\n    case double(Double)\n    case bool(Bool)\n    case string(String)\n    case null\n}\n```\n\nSyntax comes with constructs for most of these out of the box, like: `StringLiteral` and `IntLiteral`. \nSo we can rely on those. We can put most of our cases in an `Either` which will try to parse whichever case works:\n\n```swift\nstruct JSONParser: Parser {\n    var body: any Parser\u003cJSON\u003e {\n        Either {\n            /// TODO: Arrays and Objects\n\n            StringLiteral().map(JSON.string)\n            IntLiteral().map(JSON.int)\n            DoubleLiteral().map(JSON.double)\n            BooleanLiteral().map(JSON.bool)\n                \n            Word(\"null\").map(to: JSON.null)\n        }\n    }\n}\n```\n\nYou will notice that we put a `map` at the end of each line. \nThis is because parsers like `StringLiteral` will return a String and not JSON. So we need to map that string to JSON.\n\nSo the rest of our job will go into parsing objects and literals. The first thing we notice though is that Arrays and Objects need to parse JSON again. \nThis recursion needs to be stated explicitely. To use a Parser recursively, we implement a different protocol called `RecursiveParser`: \n\n```swift\nstruct JSONParser: RecursiveParser {\n    var body: any Parser\u003cJSON\u003e {\n        Either {\n            /// TODO: Arrays and Objects\n\n            StringLiteral().map(JSON.string)\n            IntLiteral().map(JSON.int)\n            DoubleLiteral().map(JSON.double)\n            BooleanLiteral().map(JSON.bool)\n                \n            Word(\"null\").map(to: JSON.null)\n        }\n    }\n}\n```\n\nThe name `RecursiveParser` describes quite accurately what it does. It's a `Parser`, which can have a cycle inside. \n**Note:** the protocol `RecursiveParser` expects that your Parser type will also conform to `Hashable`. \nIf your type only has `Hashable` properties, this conformance will be synthesized by the compiler.\n\nNow, let's get parsing of these recursive definitions going.\nWe can start with arrays. We can create an array parser that will parse multiple values of `JSON` separated by commas, inside `[` and `]`. In Syntax that looks like this:\n\n```swift\nstruct JSONArrayParser: Parser {\n    var body: any Parser\u003c[JSON]\u003e {\n        \"[\"\n\n        // we can just reuse our JSON Parser here.\n        JSONParser()\n            .separated(by: \",\")\n\n        \"]\"\n    }\n}\n```\n\nEasy, right? It's pretty much what we said in words. Dictionaries are pretty similar, except that we have a key-value pairs separated by commas:\n\n```swift\nstruct JSONDictionaryParser: Parser {\n    var body: any Parser\u003c[String : JSON]\u003e {\n        \"{\"\n\n        // Group acts kinda like parenthesis here.\n        // It groups the key-value pair into one parser\n        Group {\n            StringLiteral()\n\n            \":\"\n\n            JSONParser()\n        }\n        .separated(by: \",\")\n        .map { values in\n            // put the pairs in a dictionary\n            return Dictionary(values) { $1 }\n        }\n\n        \"}\"\n    }\n}\n```\n\nAnd for the final act, we add those two to our `Either` for JSON:\n\n```swift\nstruct JSONParser: RecursiveParser {\n    var body: any Parser\u003cJSON\u003e {\n        Either {\n            JSONDictionaryParser().map(JSON.object)\n            JSONArrayParser().map(JSON.array)\n\n            StringLiteral().map(JSON.string)\n            IntLiteral().map(JSON.int)\n            DoubleLiteral().map(JSON.double)\n            BooleanLiteral().map(JSON.bool)\n                \n            Word(\"null\").map(to: JSON.null)\n        }\n    }\n}\n\nlet text = \"[42, 1337]\"\nlet json = try JSONParser().parse(text) // .array([.int(42), .int(1337)])\n```\n\n## Contributions\nContributions are welcome and encouraged!\n\n## License\nSyntax is available under the MIT license. See the LICENSE file for more info.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnerdsupremacist%2Fsyntax","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnerdsupremacist%2Fsyntax","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnerdsupremacist%2Fsyntax/lists"}