dhall-eta
is a eta library that wraps the
haskell implementation
of dhall configuration language with a friendly java api.
Its main goal is to create a language binding to make possible configure java
libraries and applications with dhall
files.
We already can use eta
to compile the dhall haskell
implementation
and etlas (a
specific build tool for eta
) to install dhall
and its tools (dhall-to-json
or
dhall-text
)
as java cli applications. However, the classes generated by eta can't
be used directly in java code in a easy way. Hence the need for this library.
The quick way to explore the java api is use jshell
the java repl tool present since java 9.
> jshell --class-path /path/to/dhall-eta-all-${version}.jar
NOTE: The version of java used is openjdk-9.0.4.
To use the api in your project simply download from last release the dhall-eta-all-${version}.jar
and put it in the project classpath.
The project has an executable class with some more examples.
The main class to compile dhall expressions and get java objects is
the class org.dhall.eta.Input
.
jshell> import org.dhall.eta.Input
jshell> Input.bool("True")
$2 ==> true
jshell> Input.str("\"This is a dhall Text\"")
$3 ==> "This is a dhall Text"
jshell> Input.bigInt("-1234567890")
$4 ==> -1234567890
jshell> Input.natural("123456789 * 123456789")
$5 ==> Natural [15241578750190521]
Input.type
. To use it we
need to build a org.dhall.eta.Type<R>
used by the api to extract a
java value (of type R
) and typecheck the dhall expression. Methods for basic types are already defined in org.dhall.eta.Types
: jshell> import org.dhall.eta.Type
jshell> import org.dhall.eta.Types
jshell> Type<Boolean> boolTy = Types.bool()
boolTy ==> eta.org.dhall.eta.Type$Eta@67bf0d91
jshell> Input.type(boolTy, "True && False")
$6 ==> false
org.dhall.eta.Types
has methods to build standard "container" types as List
, Optional
or Map
.
Map
from a dhall record, we need to build a Map
with the keys and types of the fields expected and then use Types.objMap
to get a Type<Map<String, Object>>
suitable to use with Input.type
:jshell> Map<String,Type<? extends Object>> fieldTypes=new HashMap<>();
fieldTypes ==> {}
jshell> fieldTypes.put("name",Types.str());
$9 ==> null
jshell> fieldTypes.put("nats",Types.list(Types.natural()))
$10 ==> null
jshell> Type<Map<String,Object>> mapTy=Types.objMap(FieldTypes.upcast(fieldTypes))
mapTy ==> eta.org.dhall.eta.Type$Eta@35884aff
jshell> Input.type(mapTy, "{ name = \"name\", nats=[1, 2, 3] }")
$11 ==> {name=name, nats=[Natural[1], Natural[2], Natural[3]]}
Input.type
method and create the appropiate type:
Types.record
and implementing org.dhall.eta.RecordType
Types.union
and implementing org.dhall.eta.UnionType
org.dhall.eta.Type
interface and using directly Input.type
.org.dhall.eta.Parser
org.dhall.eta.Import
org.dhall.eta.Core
org.dhall.eta.TypeCheck
org.dhall.eta.Binary
Download etlas from https://eta-lang.org/docs/user-guides/eta-user-guide/installation/etlas
dhall-eta
can only be built using eta
and etlas
built themselves from master. We are in the cutting edge! Run etlas build --enable-uberjar-mode
to compile and generate an uberjar with all dependecies included in ./dist/build/eta-${version}/dhall-eta-${version}/x/dhall-eta-all/build/dhall-eta-all/dhall-eta-all.jar
etlas run dhall-eta-all
Run etlas test
to execute the test suite against dhall-lang
acceptance tests
dhall-lang
project in the same parent directory as dhall-eta
4.0.0
and we have to use a fixed version of tests for 4.0.0
in https://github.com/jneira/dhall-langdhall-eta
project dir):
> git clone --branch v4.0.0 --depth=1 https://github.com/jneira/dhall-lang.git ../dhall-lang
dhall-haskell
(and it should not do it!), only that the dhall-haskell
implementation compiled by eta
and dhall-eta
itself are consistent.gradle
build is configured to use the system wide versions of eta
and etlas
so you will must have them built from source and available in PATH
. We are in the cutting edge here too!gradle
plugin for eta and the proguard and shadow ones to generate a minimized jar with all the dependencies included.gradle
wrapper cause the eta gradle
plugin will likely work with it../gradlew build
will generate the following artifacts:
./lib/dhall-eta-${version}-all.jar
eta
: it is simply org.dhall
.gradle
subproject named dhall-model
in the folder ./java
./java/build/libs/dhall-model-${version}.jar
org.dhall.eta.examples.Client
.dhall-eta-examples
in the folder examples
./gradlew run
.