{"id":13537440,"url":"https://github.com/kotlinx/ast","last_synced_at":"2025-04-02T04:30:49.020Z","repository":{"id":41677492,"uuid":"207099876","full_name":"kotlinx/ast","owner":"kotlinx","description":"Generic AST parsing library for kotlin multiplatform","archived":false,"fork":false,"pushed_at":"2024-08-25T00:21:42.000Z","size":2276,"stargazers_count":315,"open_issues_count":29,"forks_count":22,"subscribers_count":9,"default_branch":"master","last_synced_at":"2024-08-25T23:49:02.030Z","etag":null,"topics":["ast","kotlin","multiplatform"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kotlinx.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":"2019-09-08T11:04:39.000Z","updated_at":"2024-08-25T00:21:45.000Z","dependencies_parsed_at":"2024-08-24T23:31:48.413Z","dependency_job_id":"19af6d98-53b6-4458-a5cd-a42093c2d371","html_url":"https://github.com/kotlinx/ast","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kotlinx%2Fast","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kotlinx%2Fast/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kotlinx%2Fast/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kotlinx%2Fast/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kotlinx","download_url":"https://codeload.github.com/kotlinx/ast/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222798733,"owners_count":17039349,"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":["ast","kotlin","multiplatform"],"created_at":"2024-08-01T09:00:59.133Z","updated_at":"2024-11-03T02:31:29.498Z","avatar_url":"https://github.com/kotlinx.png","language":"Java","funding_links":[],"categories":["Libraries"],"sub_categories":["Build \u0026 Development Tools"],"readme":"[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)\n[![Release](https://jitpack.io/v/kotlinx/ast.svg)](https://jitpack.io/#kotlinx/ast)\n\n\n# kotlinx.ast\n\n`kotlinx.ast` is a generic AST (Abstract Syntax Tree) parsing library, Kotlin is currently the only supported language.\nThe library is designed that other languages can be easily added.\n`kotlinx.ast` does not use the Kotlin Compiler for parsing,\nit is using ANTLR (the Kotlin variant: https://github.com/Strumenta/antlr-kotlin)\nusing the official Kotlin Grammar (https://kotlinlang.org/docs/reference/grammar.html).\n\nOne Component is [Klass](common/src/commonMain/kotlin/kotlinx/ast/common/klass),\na collection of language independent data classes\nused to represent and easily access the AST.\n\n## Status\nThe Project is in an early stage, but it is already possible to parse Kotlin code.\nBug reports, feature requests and pull requests are very welcome.\n\n`kotlinx.ast` is a multiplatform project, but currently, JVM is the only supported target.\nSupport for JS and native is planned.\n\n`antlr-java`, `antlr-optimized` and `antlr-kotlin` are supported on the JVM.\nMultiplatform support (Kotlin Native and Kotlin JavaScript) for `antlr-kotlin` is planned.\nBecause `antlr-java` and `antlr-optimized` are JVM-only, support for other platforms is not possible.\n\n## Prior art\n[kastree](https://github.com/cretz/kastree) is using the kotlin compiler for parsing,\nit can only parse kotlin files.\nJS and native support is not possible. `kastree` is currently not under active development.\n\n## Example\n\nThis Kotlin Code:\n```\n@Annotation1(\"abc\")\n// line comment between annotations\n@Annotation2(\"\\${123}\")\nfun parse() {}\n```\n\nwill be parsed as:\n```\nPackageHeader()\nimportList\nKlassDeclaration(fun parse)\n  KlassAnnotation(Annotation1)\n    KlassArgument()\n      KlassString\n        \"abc\"\n  KlassAnnotation(Annotation2)\n    KlassArgument()\n      KlassString\n        Escape(\"\\$\")\n        \"{123}\"\n```\n\nThere are more examples in directory [testdata](grammar-kotlin-parser-test/src/commonMain/resources/testdata).\n* Files named \"*.kt.txt\" contains the kotlin source to parse\n* Files named \"*.raw.txt\" contains the parsed raw kotlin AST as defined by the official Kotlin Grammar\n* Files named \"*.summary.txt\" contains the AST summary\n\n## Open Tasks\n\nThere are some parts missing, for example the _importList_ is not converted into an easy-to-use data class\n\n## Overview\n\nCurrently, there are some libraries that are part of kotlinx.ast:\n* `kotlinx.ast:common` contains the code that can later be reused by other grammar parsers\n* `kotlinx.ast:common-test` contains the dependencies to test frameworks, used by `kotlinx.ast` unit tests\n* `kotlinx.ast:parser-antlr-java` contains the shared code required to parse grammars using the official antlr4 JVM implementation.\n* `kotlinx.ast:parser-antlr-kotlin` contains the shared code required to parse grammars using antlr-kotlin\n* `kotlinx.ast:parser-antlr-optimized` contains the shared code required to parse grammars using the optimized fork of antlr.\n* `kotlinx.ast:grammar-kotlin-parser-common` contains the shared code required to parse kotlin source\n* `kotlinx.ast:grammar-kotlin-parser-antlr-java` provides a kotlin ast parsed using antlr-java\n* `kotlinx.ast:grammar-kotlin-parser-antlr-kotlin` provides a kotlin ast parsed using antlr-kotlin\n* `kotlinx.ast:grammar-kotlin-parser-test` contains the test data used by the kotlin parsers\n* `kotlinx.ast:grammar-antlr4-parser-common` contains the shared code required to parse antlr4 grammar files\n* `kotlinx.ast:grammar-antlr4-parser-antlr-java` provides an antlr4 grammar ast parser using antlr-java\n* `kotlinx.ast:grammar-antlr4-parser-test` contains the test data used by the antlr4 grammar parsers\n\n## External Dependencies\n\n[antlr-kotlin](https://github.com/Strumenta/antlr-kotlin)\n* `${Versions.antlrKotlinGroup}:antlr-kotlin-runtime:${Versions.antlrKotlin}`\nis required at runtime to be able to parse kotlin code into an AST when using `kotlinx.ast:grammar-kotlin-parser-antlr-kotlin`.\n\n[antlr-java](https://github.com/antlr/antlr4)\n* `org.antlr:antlr4:${Versions.antlrJava}`\nis required at runtime to be able to parse kotlin code into an AST when using `kotlinx.ast:grammar-kotlin-parser-antlr-java`.\n\n[antlr-optimized](https://github.com/tunnelvisionlabs/antlr4)\n* `com.tunnelvisionlabs:antlr4:${Versions.antlrOptimized}`\nis required at runtime to be able to parse kotlin code into an AST when using `kotlinx.ast:grammar-kotlin-parser-antlr-optimized`.\n*NOTE:* `antlr-optimized` is a drop-in replacement of `antlr-java`.\nBoth jars provide the same API, namely the package `org.antlr.v4`, so you can't use both at the same time.\n`kotlinx.ast:parser-antlr-optimized` depends on `kotlinx.ast:parser-antlr-java`, both provide the same `kotlinx.ast` API.\nThe difference is that `parser-antlr-optimized` will exclude the dependency to `org.antlr:antlr4`\nand instead include `com.tunnelvisionlabs:antlr4`.\nThe generated code of these two libraries is not equal, therefore two different grammar modules are required:\n* [kotlinx.ast:parser-antlr-java](grammar-kotlin-parser-antlr-java/src/main/java/kotlinx/ast/grammar/kotlin/target/antlr/java/generated)\n* [kotlinx.ast:parser-antlr-optimized](grammar-kotlin-parser-antlr-optimized/src/main/java/kotlinx/ast/grammar/kotlin/target/antlr/optimized/generated)\n(the generated code is linked, for the case that you want to compare it)\n\n(`Versions` can be found here: [Versions.kt](buildSrc/src/main/kotlin/Versions.kt))\n\n## How to use kotlinx.ast\nThere is a small example to get started:\n* for `antlr-kotlin` [ExampleMain.kt](grammar-kotlin-parser-antlr-kotlin/src/jvmTest/kotlin/kotlinx/ast/example/ExampleMain.kt)\n* for `antlr-java` [ExampleMain.kt](grammar-kotlin-parser-antlr-java/src/test/kotlin/kotlinx/ast/example/ExampleMain.kt)\n* for `antlr-optimized` [ExampleMain.kt](grammar-kotlin-parser-antlr-optimized/src/test/kotlin/kotlinx/ast/example/ExampleMain.kt)\n\n## Using with Gradle\n`kotlinx.ast` is accessible on Maven \u0026 Gradle through Jitpack. In Jitpack basically you can use every commit or tag as a version number. You can find recent versions on the Jitpack page for `kotlinx.ast`.\n\nYou have to add this line to `settings.gradle.kts` if use Gradle lower than 5.3: (otherwise, the jars are not resolved):\n```\n// Enables KotlinMultiplatform publication and resolving (in dependencies)\nenableFeaturePreview(\"GRADLE_METADATA\")\n```\n\nYou have to add Jitpack to `build.gradle.kts`:\n```\nrepositories {\n  maven(\"https://jitpack.io\")\n}\n```\n\nAdd the dependency to `kotlinx.ast` into your project:\n```\nkotlin {\n    jvm()\n\n    sourceSets {\n        val commonMain by getting {\n            dependencies {\n                // please look at https://jitpack.io/#drieks/antlr-kotlin to find the latest version\n                api(\"com.github.kotlinx.ast:grammar-kotlin-parser-antlr-kotlin:0123456789\")\n            }\n        }\n    }\n}\n```\n\nIf you don't use `kotlin-multiplatform` add this line:\n```\n// please look at https://jitpack.io/#drieks/antlr-kotlin to find the latest version\nimplementation(\"com.github.kotlinx.ast:grammar-kotlin-parser-antlr-kotlin:0123456789\")\n```\nOr, if you prefer to use the `antlr-java` parser (JVM only):\n```\n// please look at https://jitpack.io/#drieks/antlr-kotlin to find the latest version\nimplementation(\"com.github.kotlinx.ast:grammar-kotlin-parser-antlr-java:0123456789\")\n```\nThe latest version can be be seen in the Jitpack-Badge at the top of this page.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkotlinx%2Fast","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkotlinx%2Fast","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkotlinx%2Fast/lists"}