{"id":24915149,"url":"https://github.com/bjoernloetters/jar-jar-parse","last_synced_at":"2025-10-17T01:31:44.704Z","repository":{"id":271892649,"uuid":"914888257","full_name":"BjoernLoetters/Jar-Jar-Parse","owner":"BjoernLoetters","description":"A small library for parser combinators in Java with a special focus on simplicity.","archived":false,"fork":false,"pushed_at":"2025-01-31T14:27:10.000Z","size":103,"stargazers_count":3,"open_issues_count":4,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-31T14:32:30.973Z","etag":null,"topics":["clojure","compiler","domain-specific-language","java","kotlin","parser","parser-combinators","scala","syntax"],"latest_commit_sha":null,"homepage":"","language":"Java","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/BjoernLoetters.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}},"created_at":"2025-01-10T14:13:04.000Z","updated_at":"2025-01-31T09:35:59.000Z","dependencies_parsed_at":null,"dependency_job_id":"dc3b8ed4-9ad3-4163-afb5-d569290c34c9","html_url":"https://github.com/BjoernLoetters/Jar-Jar-Parse","commit_stats":null,"previous_names":["bjoernloetters/java-parser-combinators","bjoernloetters/jar-jar-parse"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BjoernLoetters%2FJar-Jar-Parse","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BjoernLoetters%2FJar-Jar-Parse/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BjoernLoetters%2FJar-Jar-Parse/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BjoernLoetters%2FJar-Jar-Parse/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BjoernLoetters","download_url":"https://codeload.github.com/BjoernLoetters/Jar-Jar-Parse/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":236761735,"owners_count":19200661,"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":["clojure","compiler","domain-specific-language","java","kotlin","parser","parser-combinators","scala","syntax"],"created_at":"2025-02-02T07:16:27.592Z","updated_at":"2025-10-17T01:31:44.698Z","avatar_url":"https://github.com/BjoernLoetters.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"![Unit Test](https://github.com/BjoernLoetters/Java-Parser-Combinators/actions/workflows/test.yml/badge.svg?branch=main)\n![License](https://img.shields.io/github/license/BjoernLoetters/Jar-Jar-Parse?label=License\u0026logo=github)\n![Release](https://img.shields.io/github/v/release/BjoernLoetters/Java-Parser-Combinators?label=Release\u0026logo=github)\n![Maven](https://img.shields.io/maven-central/v/io.github.bjoernloetters/jjparse-core?label=Maven%20Central\u0026logo=github)\n\n# Jar Jar Parse\n*\"Yousa needin’ a parser? Meesa help!\"*\n\n### 🚀 What is Jar Jar Parse?\n**Jar Jar Parse** (or **JJParse** for short) is a lightweight library designed for the rapid prototyping of parsers in Java.\nIt is highly inspired by the [Scala Parser Combinators](https://github.com/scala/scala-parser-combinators) and aims to balance ease of use and functionality, deliberately placing less emphasis on performance.\nIf you are new to the idea of parser combinators feel free to check out the [Section \"What are Parser Combinators?\"](#what-are-parser-combinators).\nSee [Section \"Example\"](#example) for a quick overview and [Section \"Getting Started\"](#getting-started) to install and use this library.\nIf you find this project interesting, please consider [contributing](#contributing) or sharing it with others.\n\n### 🎯 Features\n\n- [x] Easy to use and fully typed ♥️\n- [x] Supports backtracking by default \n- [x] Scanner-less parsing with regular expressions\n- [x] Built-in support for whitespace skipping\n- [x] 🌟 Unicode 🦄 support with code point positions\n- [x] Abstract parsers and inputs for advanced use cases\n- [x] Tested and documented ✅\n\n### 📖 Getting Started\n\n##### Installation \n\n**JJParse** is available via the [Maven Central Repository](https://central.sonatype.com/artifact/io.github.bjoernloetters/jjparse-core), so installing it is as easy as pie!\n\n###### Automatic Installation\n\nIf you are already using `maven`, just copy and paste the following dependency to your `pom.xml`: \n```xml\n\u003cdependency\u003e\n    \u003cgroupId\u003eio.github.bjoernloetters\u003c/groupId\u003e\n    \u003cartifactId\u003ejjparse-core\u003c/artifactId\u003e\n    \u003cversion\u003e1.0.1\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nThanks to the widespread use of the Maven Central Repository, you can also include **JJParse** in other build tools:\n\u003cdetails\u003e\n   \u003csummary\u003eGradle\u003c/summary\u003e\n\n   ```\n   implementation group: 'io.github.bjoernloetters', name: 'jjparse-core', version: '1.0.1'\n   ```\n   \n\u003c/details\u003e\n\u003cdetails\u003e\n   \u003csummary\u003eSBT\u003c/summary\u003e\n\n   ```scala\n    libraryDependencies += \"io.github.bjoernloetters\" % \"jjparse-core\" % \"1.0.1\"\n   ```\n\n\u003c/details\u003e\n\u003cdetails\u003e\n   \u003csummary\u003eIvy\u003c/summary\u003e\n\n   ```xml\n   \u003cdependency org=\"io.github.bjoernloetters\" name=\"jjparse-core\" rev=\"1.0.1\"/\u003e\n   ```\n   \n\u003c/details\u003e\n\n###### Manual Installation\n\nIf the above options do not fit your needs, you can also install **JJParse** manually by downloading the latest `jar`-release via the [release page](https://github.com/BjoernLoetters/Java-Parser-Combinators/releases).\nTo install **JJParse** in this way, follow these steps:\n1. Download the latest `jar`-file from the [release page](https://github.com/BjoernLoetters/Java-Parser-Combinators/releases).\n2. Add the `jar`-file to your project's classpath.\n    - In **IntelliJ IDEA**: Right-click the `jar`-file → Select **\"Add as Library ...\"**\n    - In **Eclipse**: Right-click your project → **Build Path** → **Add External Archives ...** and select the `jar`-file.\n3. (Optional) Add the JavaDoc `jar`-file to your development environment.  \n\n##### First Steps\n\nTo start using **JJParse**, create a class that extends either `Parsing` or `StringParsing`:\n- `Parsing` offers the core functionality and allows defining parsers for **arbitrary input types** (e.g., a custom token stream provided by a scanner).\n- `StringParsing` is the best choice if you simply want to prototype a language. It provides utilities for **character-based and scanner-less parsing** (including regular expressions) and already skips any white space characters by default. \n\nIn general, a parser in **JJParse** is simply a function that transforms an `Input\u003cT\u003e` into a `Result\u003cU\u003e`. \nHere, an instance of `Input\u003cT\u003e` can be seen as a stream of tokens of type `T`.\nIn case of `StringParsing`, this type `T` is fixed to be `Character`, while for `Parsing` it is up to you to choose an appropriate token type. \nThe `Result\u003cU\u003e` can either be a `Success\u003cU\u003e`, containing the parsed value of type `U`, or a `Failure\u003cU\u003e`, carrying an error message with further details.\n\nTo parse an input, instantiate your parser class and call `parse(parser, input)` (to parse the whole input) or `parser.apply(input)` (to parse only a portion of the input).\nFor a quick start, also have a look at the [Section \"Example\"](#example).\n\n### 🔍 Example\n\nThe example below provides a brief overview of the library. For a more detailed example, check out the subprojects in the [examples directory](examples).\n\n```java\nimport jjparse.StringParsing;\nimport jjparse.input.Input;\n\n// Extend 'StringParsing' for convenient character-based parsers.\npublic class MyParser extends StringParsing {\n\n    // A parser which parses a signed integer.\n    public Parser\u003cInteger\u003e number = regex(\"[+-]?[0-9]+\").map(Integer::parseInt);\n\n    // A parser which parses additions and returns their result.\n    public Parser\u003cInteger\u003e add = number.keepLeft(character('+')).and(number)\n            .map(product -\u003e product.first() + product.second());\n\n    public static void main(final String[] arguments) {\n        // Create an input of characters with the name 'My Test Input' (for error reporting).\n        Input\u003cCharacter\u003e input = Input.of(\"My Test Input\", \"42 + 0\");\n\n        // Use the 'add' parser to parse the above input.\n        MyParser parser = new MyParser();\n        Result\u003cInteger\u003e result = parser.parse(parser.add, input);\n\n        // The following statement prints 'Success: 42'.\n        switch (result) {\n            case Success\u003cInteger\u003e success:\n                System.out.printf(\"Success: %s\\n\", success.value);\n                break;\n            case Failure\u003cInteger\u003e failure:\n                System.err.printf(\"Failure: %s\\n\", failure.message);\n                break;\n        }\n    }\n\n}\n```\n\n### 💡 What are Parser Combinators?\n\nIn traditional parsing approaches, commonly taught in university courses, we often rely on parser generators. \nThese tools take a grammar specification as input and generate a parser implementation based on it. \nWhile the generated parsers are typically fast, this method has some downsides.\n\nFirstly, modifying the grammar requires regenerating the entire parser, which can be cumbersome. \nAdditionally, to produce meaningful output with your parser, you must embed code from your programming language within the grammar specification itself. \nThe tool support for such embedded code can sometimes be difficult to work with and frustrating to debug.\n\nThis is where parser combinators come into play. \nA parser combinator is a powerful technique for constructing complex parsers by combining simpler, reusable parsers. \nEach individual parser is responsible for recognizing a specific part of the input, and combinators are functions that combine these basic parsers into more complex ones — hence the name \"combinators\".\n\nThe key advantage of this approach is that it enables the rapid development of parsers within the constraints and benefits of a general-purpose programming language. \nInstead of relying on a third-party tool to generate a parser from a grammar specification, parser combinators allow us to \"program\" the syntax of a language directly in our favourite programming language.\n\nIn the case of **JJParse**, parsers are implemented as functions that take an `Input\u003cT\u003e` and produce a `Result\u003cU\u003e`. \nHere ...\n- ... the type `T` represents the element type of the input, which is `Character` in many cases.\n- ... the type `U` denotes the type of the result.\n\nFor example:\n- A character parser takes an `Input\u003cCharacter\u003e` and produces a `Result\u003cCharacter\u003e`.\n- A string parser takes an `Input\u003cCharacter\u003e` and produces a `Result\u003cString\u003e`.\n- A parser that combines a character parser with a string parser produces a `Result\u003cProduct\u003cCharacter, String\u003e\u003e`.\n\nAs with any parsing method, things don’t always go smoothly. \nA parsing attempt can fail, which is why a `Result\u003cU\u003e` may either be a `Success\u003cU\u003e` (containing the successful result) or a `Failure\u003cU\u003e` (containing an error message).\n\nThis approach, while simple, provides flexibility and expressiveness that traditional parser generators often lack, making it an ideal solution for day-to-day parsing tasks.\n\n### 🤝 Contributing\n\nContributions of any kind are welcome! \nWhether it’s reporting issues, suggesting features, or submitting pull requests, your help is appreciated. \nIf you find this library useful, consider sharing it with others.\n\n### ⚖️ License\n\nThis project is licensed under the [MIT](LICENSE) license.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjoernloetters%2Fjar-jar-parse","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbjoernloetters%2Fjar-jar-parse","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbjoernloetters%2Fjar-jar-parse/lists"}