Tria Lua API

This document describes the API for Lua generator scripts

For general information on Lua (functions, syntax, ..) see: http://www.lua.org/manual/5.2/manual.html

Note: The NuriaProject Framework, this includes Tria, uses the LuaJIT implementation of Lua.

Usage

To tell Tria to run a custom generator script, pass -lua-generator=<Script>:<Outfile>[:<Arguments>]. The Arguments part is optional. If given, its value will be made available to the script in tria.arguments.

Helper functions for writing scripts can be found in 'util'. You can load it in your own scripts using require: require "util". Please see the file source for information.

For debugging purposes, the dumper.lua script is built-in and can be included by doing require "dumper"

Interactive shell

For easy testing and hacking, it's possible to start a minimal Lua shell in Tria by passing -shell. The shell itself runs in the generator environment, thus, you can use this shell to quickly test generators etc.

Overview

Tria exports a bunch of global tables for scripts. These are:

• definitions contains information about the parsed source file
• tria contains environment information
• log contains logging functions
• json exposes a JSON writer (Internally, Qt5's QJsonDocument is used)
• write is a function, which will write the given string argument into the output file.

definitions (Definition)

The overall structure looks like this:

"definitions" = {
  declaredTypes = [ List of type names ],
  declareTypes = { 'type name' = <true/false> },
  avoidedTypes = [ List of type names ],
  typedefs = { 'typedef name' = 'type name', ... },
  classes = { 'class name' = <Class>, ... }
}

declareTypes contains a mapping which types must be declared to make the definition useful in a C++ context. The key of each element is the type name, and the value is true if it was fully declared or false if not.

Access

<Access> is a string, refering to the corresponding C++ access modifier. The possible values are:

• "public"
• "protected"
• "private"
• "none"

AnnotationType

<AnnotationType> is a string with a value of:

• "introspect" -> NURIA_INTROSPECT
• "skip" -> NURIA_SKIP (You'll never see this, just for sake of completeness)
• "read" -> NURIA_READ (Rely on the class variables)
• "write" -> NURIA_WRITE
• "require" -> NURIA_REQUIRE (The annotation value is the given condition)
• "custom" -> NURIA_ANNOTATE(Name, Value)

Class

The parsed definition of a class (or struct). If isFakeClass is true, the class is only used to expose global symbols of the source file(s). This means, that this class does not really exist, and that all functions are static.

<Class> = {
  name = <class name>,
  loc = <Location>,
  annotations = [ <Annotation>, ... ],
  hasValueSemantics = <bool>,
  hasDefaultCtor = <bool>,
  hasCopyCtor = <bool>,
  hasAssignmentOperator = <bool>,
  hasPureVirtuals = <bool>,
  implementsCtor = <bool>,
  implementsCopyCtor = <bool>,
  isFakeClass = <bool>,
  bases = [ <type name> = <Base>, ... ],
  variables = [ <Variable>, ... ],
  methods = [ <Method>, ... ],
  conversions = [ <Conversion>, ... ],
  enums = { <enum name> = <Enum>, ... }
}

Annotation

Annotation data.

<Annotation> = {
  loc = <Location>,
  name = "the name",
  value = "the value",
  type = <AnnotationType>,
  valueType = <The QMetaType id of 'value'>,
  typeName = <The type name according to the Qt meta system>
}

Base

Base classes of a ("struct MyType : Base, AnotherBase, .. {")

<Base> = {
  loc = <Location>,
  access = <Access>,
  isVirtual = <bool>
}

Variable

Used for variables and arguments. isConst and isReference refer to the type itself. If getter and setter are empty, then it's a raw variable. If only getter is not empty, then the variable is read-only. If both getter and setter are not empty, the variable is read-write. If setterReturnsBool is ''true'', the setter returns ''true'' or ''false'' to indicate success or failure.

<Variable> = {
  name = "field/argument name",
  loc = <Location>,
  annotations = [ <Annotation>, ... ],
  access = <Access>, (Is always "public")
  type = "Type name as given in the source file",
  getter = "Getter",
  setter = "Setter",
  isConst = <bool>,
  isReference = <bool>,
  isPodType = <bool>,
  isOptional = <bool>,
  setterReturnsBool = <bool>
}

Method

Method definition. name is the method name itself, not the prototype (E.g. "foo", not "int foo()"). Overloaded methods (This includes methods with default arguments!), there's a per version of the method itself. This means, that void foo (int a = 1, int b = 2) would create three versions. isConst refers to the cv-qualifier. If the is the product of a function with default arguments, hasOptionalArguments is 'true'.

<Method> = {
  name = "method name",
  loc = <Location>,
  access = <Access>, (Always "public")
  annotations = [ <Annotation>, ... ],
  type = <MethodType>,
  isVirtual = <bool>,
  isPure = <bool>,
  isConst = <bool>,
  returnType = <Variable>,
  arguments = [ <Variable>, ... ],
  hasOptionalArguments = <bool>
}

<MethodType> is one of:

• "static" - A static method
• "member" - A member method
• "constructor" - A constructor
• "destructor" - Destructor, internal only

Conversion

A conversion as found by Tria while parsing the source file(s). If the type is "constructor", then toType will be the class name to be constructed and fromType will be the only argument to be passed to it. If it's "member", then it's a "toX" style function, which takes no arguments and is to be called on a instance of fromType and returns a instance of toType. If it's "static", it's a "fromX" style function, which takes an argument of type fromType and returns an instance of toType.

isConst refers to the argument to be passed (or the instance to be called on).

<Conversion> = {
  loc = <Location>,
  type = <MethodType>,
  fromType = "Type name",
  toType = "Type name",
  isConst = <bool>
}

Enum

<Enum> = {
  name = "the enums name",
  loc = <Location>,
  annotations = [ <Annotation>, ... ],
  elements = { "Element name" = <Element value>, ... }
}

Location

<Location> is a userdata type wrapping a clang::SourceRange instance. It does not offer direct access, but you can dump its content using tostring(). It's primarily useful for the logging functions.

tria (API)

• compileTime Time of Trias compilation (Format: HH:MM:SS)
• compileDate Date of Trias compilation (Format: MMM DD YYYY)
• llvmVersion Version of the linked LLVM/Clang (Format: Major.Minor)
• arguments Argument string as given by the user
• sourceFile The source file
• outFile Name of the output file
• currentDateTime The current date-time in ISO format

log (API)

log offers the following functions, all with the same prototype:

• ignored
• note
• remark
• warning
• error
• fatal

These map directly to the corresponding logger levels of Clang. Each method supports three ways of calling:

function (range : clang::SourceRange, message : string) : void

Logs the message pointing to the begin of range

function (object : table, message : string) : void

Same as the version above, except that the clang::SourceRange is accessed via object.loc. This makes it easy to quickly log stuff pointing at a <Class>, <Method>, etc.

function (message : String) : void

Logs message without pointing to anything.

json (API)

• json.serialize(table) Takes the ''table'' and returns the serialized JSON data.