daml/language-support/scala/codegen/README.md

Developer's guide to DAML Scala code generator

For the User's guide to the Scala code generator see: docs/daml-scala-code-gen-user-guide.rst

Introduction

The DAML Scala code generator produces wrapper classes that correspond to DAML contract templates and DAML user defined types (records/variants that are the right hand side of a DAML type synonym). They are intended to be used by application developers and they provide the same level of type safety as the DAML langauge itself.

Working with Scala macros

The code makes heavy use of Scala macros and quasiquotes.

More information on Scala macros can be found here

There is some great documentation on quasiquotes here In particular, this page is a great reference

You may also find this guide on the Scala Reflection API useful as macros/quasiquotes make use of it. See here

The reference documentation for the Reflection API is available here

I have also found it very useful to use the Scala console to see the abstract syntax tree (AST) structure

showRaw is your friend

You can use the Reflection API's showRaw function to see which constructors are used in a quasiquoted expression/statement/definition.

From an SBT console open a Scala console with:

> console

Then:

scala> val universe: scala.reflect.runtime.universe.type = scala.reflect.runtime.universe
universe: reflect.runtime.universe.type = scala.reflect.runtime.JavaUniverse@712e80d8

scala> import universe._
import universe._

Then (for example):

scala> showRaw(q"obj.method")
res2: String = Select(Ident(TermName("obj")), TermName("method"))

Use Ctrl-D to get back to SBT console

Understanding the code

The best way to understand the structure of the generated code is to read DamlContractTemplate.scala and DamlUserDefinedType.scala. The Scala macros are quite readable and both classes have informative comments.