Base trait to simplify creating classes that contain a reference to a value in the Isabelle process. Classes inheriting from this trait contain an MLValue that refers to a value in the Isabelle process. (That is, unless the inheriting class specifies further fields, this is the only data carried by the class. In particular, the class will not transfer data from the Isabelle process.)

Examples of classes based on MLValueWrapper are pure.Context, pure.Thm, pure.Position.

The minimal implementation of a class based on MLValueWrapper is as follows:

final class Something private (val mlValue: MLValue[Something]) extends MLValueWrapper[Something]

object Something extends MLValueWrapper.Companion[Something] {
  override protected val mlType: String = "Something"
  override protected def instantiate(mlValue: MLValue[Something]): Something = new Something(mlValue)
}

Here Something is the name of the Scala class that we want to implement, and something is the ML type of the corresponding values in the Isabelle process.

After importing Something.converter, the type Something can be transparently used to refer to something in the Isabelle process. E.g., MLValue.compileFunction[String,Something] or MLValue(st) for st of type Something or mlst.retrieveNow for mlst of type MLValue[Something].

The class Something may be customized in several ways:

• By default, an ML value st : something is encoded as an exception (see the description of MLValue) as EXN st where EXN is an ML exception whose name is returned by Something.exceptionName. The name EXN is automatically chosen and the exception declared. If this is not desired, a different exception name can be provided by defining predefinedException in the companion object Something.
• Arbitrary additional methods and fields can be added to the definition of the class Something or the companion object Something. However, it should be noted that the constructor of Something can only have arguments mlValue : MLValue[Something] and optionally an Isabelle instance and an ExecutionContext and not other user defined values. (This is because the constructor needs to be invoked by Something.instantiate which does not have access to other data.)
• To implement functions that invoke ML code in the Isabelle process, it is recommended to place the compiled values inside an Ops class (see OperationCollection) in the companion object Something. Since the base trait MLValueWrapper.Companion already defines Ops, this needs to be done as follows:

override protected def newOps(implicit isabelle: Isabelle, ec: ExecutionContext): Ops = new Ops
protected class Ops(implicit isabelle: Isabelle, ec: ExecutionContext) extends super.Ops {
  // Example:
  lazy val test: MLFunction[Something,String] = compileFunction[Something,String]("... : something -> string")
}

The class Something represents an asynchronous value. That is, it is possible to have get an instance of Something even if the computation computing the corresponding ML value is still ongoing or has failed. To wait for that computation to terminate successfully, use the methods from FutureValue which Something inherits.

Note: Another possibility for defining wrapper classes for MLValues is AdHocConverter. Classes derived using AdHocConverter cannot be customized but only minimal boilerplate is needed.