diff --git a/.gitignore b/.gitignore index a4d573c..a2fe01f 100644 --- a/.gitignore +++ b/.gitignore @@ -248,6 +248,7 @@ modules.xml # Package Files # *.jar +!gradle/wrapper/gradle-wrapper.jar *.war *.nar *.ear diff --git a/README.adoc b/README.adoc new file mode 100644 index 0000000..473ab07 --- /dev/null +++ b/README.adoc @@ -0,0 +1,501 @@ += PartiQL IR Generator +:toc: + +[frame=none,grid=none,cols="^,^,^,^"] +|=== +| PIG Generator | PIG Runtime | LICENSE | CI + +a| [link=https://search.maven.org/artifact/org.partiql/partiql-ir-generator] +image::https://maven-badges.herokuapp.com/maven-central/org.partiql/partiql-ir-generator/badge.svg?[PIG Generator] + +a| [fit=line,link=https://search.maven.org/artifact/org.partiql/partiql-ir-generator-runtime] +image::https://maven-badges.herokuapp.com/maven-central/org.partiql/partiql-ir-generator-runtime/badge.svg?[PIG Runtime] + +a| [link=https://github.com/partiql/partiql-ir-generator/blob/main/LICENSE] +image::https://img.shields.io/hexpm/l/plug.svg[License] + +a| [link=https://github.com/partiql/partiql-ir-generator/actions?query=workflow%3A%22Build+and+run+tests%22] +image::https://github.com/partiql/partiql-ir-generator/actions/workflows/build.yml/badge.svg[CI Build] + +|=== + +== About + +PIG is a compiler framework, domain modeling tool and code generator for tree data structures such as ASTs (Abstract Syntax Tree), database logical plans, database physical plans, and other intermediate representations. +Using PIG, the developer concisely defines the structure of a tree by specifying named constraints for every node and its attributes. +Check out the https://github.com/partiql/partiql-ir-generator/wiki[wiki]! + +== CLI + +PIG can be used as a command line tool. + +=== Installation + +* Clone this repository. +* Check out the tag of the [release](https://github.com/partiql/partiql-ir-generator/releases) you wish to utilize, e.g. `git checkout v1.0.0` +* Execute `./gradlew install` + +After the build completes, the `pig` executable and dependencies will be located in `./pig/build/install/pig/bin/pig`. +You can move the install to a permanent location and add the executable script to your path. +For this doc, we'll add an alias for the local path `alias pig=./pig/build/install/pig/bin/pig`. + +You can check the version with `pig --version`. + +=== PIG 1.x + +PIG 1.x introduces a new modeling language and generator which enable features such as: + +.Modeling Additions +* List, Map, and Set Types +* Int, Float, Double, Bytes, String types +* Enum Types +* Imported Types +* Sum type definition as the variant of a sum type +* Inline type definitions +* Scoped type definitions +* Scoped type names + +.Kotlin Specific Features +* No runtime library +* Primitives nodes are optional, #79 +* Explicit library mode, #64 +* Visitors use conventional style, #123 #66 +* Nodes have a children construct, enabling recursion without a visitor. +* Dynamic code generation via poems rather than templating. +* Generated DSL now uses builders rather than just factory methods +* Generated DSL allows for a custom factory +* Jackson databind integration for serializing a tree to arbitrary Jackson formats, #119 + +==== Breaking Changes + +PIG 1.x currently does not support the 0.x modeling language or permuted domains. +The 0.x language and permuted domains are still accessible via the `legacy` subcommand. +If an issue is raised, permuted domains may get added to the 1.x language. + +==== Usage + +[source,shell] +---- +pig --help + + Usage: pig [-hv] [COMMAND] + -h, --help display this help message + -v, --version Prints current version + Commands: + generate PartiQL IR Generator 1.x + legacy PartiQL IR Generator 0.x + +pig generate --help + + Usage: pig generate [-h] [COMMAND] + PartiQL IR Generator 1.x + -h, --help display this help message + Commands: + kotlin Generates Kotlin sources from type universe definitions + + +pig generate kotlin --help + + Usage: pig generate kotlin [-h] [-m=] [-o=] [-p=] + [-u=] [--poems=[,...]]... + Generates Kotlin sources from type universe definitions + Type definition file + -h, --help display this help message + -m, --modifier= + Generated node class modifier. Options FINAL, DATA, OPEN + -o, --out= Generated source output directory + -p, --package= + Package root + --poems=[,...] + Poem templates to apply + -u, --universe= Universe identifier +---- + +=== PIG 0.x + +PIG 0.x uses a Nanopass style domain modeling language and notably has the ability to define permuted domains. +If you wish to use these features, the latest version of PIG maintains them under the `legacy` sub-command. +The https://github.com/partiql/partiql-ir-generator/wiki[wiki] has documentation on the 0.x modeling language and Kotlin target. + +The options and command behavior remains the same, only the `legacy` keyword needs to be added as the first argument. + +==== Usage + +[source,shell] +---- +pig legacy --help + +Usage: legacy [-hv] [-d=] [-e=