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.

Overview

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

• definitions contains information about the parsed source file
• tria contains environment information
• 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 = [ List of type names ],
  avoidedTypes = [ List of type names ],
  typedefs = { 'typedef name' = 'type name', ... },
  classes { 'class name' = { <Class> }, ... }
}

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).

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

Annotation

Annotation data.

<Annotation> = {
  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> = {
  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",
  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",
  access = <Access>, (Always "public")
  annotations = [ <Annotation>, ... ],
  type = <MethodType>,
  isVirtual = <bool>,
  isConst = <bool>,
  returnType = "Type name as given in the source file",
  arguments = [ <Variable>, ... ],
  hasOptionalArguments = <bool>,
  returnTypeIsPod = <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> = {
  type = <MethodType>,
  fromType = "Type name",
  toType = "Type name",
  isConst = <bool>
}

Enum

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

tria (API)

• compileTime Time of Trias compilation (Format is HH:MM:SS)
• compileDate Date of Trias compilation (Format is YYYY-MM-DD)
• 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

json (API)

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