Anatomy of a loomlib

A loomlib is a self-contained, portable code library for the LoomScript language. Loomlibs can be dynamically loaded into the LoomScript virtual machine at runtime, or statically linked against at compile time.

Info
Loomlibs are valid JSON files, containing Base64 encoded bytecode, documentation comments, and type metadata.

See the sections below for details of the data structures found in a loomlib.

• assemblies
  • modules
    • dependencies
    • types
      • classattributes
      • constructor
      • delegateReturnType
      • delegateTypes
      • fields
        • fieldattributes
      • imports
      • interfaces
      • properties
        • propertyattributes
  • references
• common data structures
  • docString
  • metainfo
  • methods
    • methodattributes
    • parameters
  • templatetypes

assemblies

type: ASSEMBLY
top level structure, synonymous with a .loomlib file

{
  "debugbuild":true,
  "jit":true,
  "loomconfig":"...",
  "modules":[],
  "name":"...",
  "references":[],
  "type":"ASSEMBLY",
  "uid":"...",
  "version":"..."
}

substructures

• modules
• references

modules

type: MODULE
typically (always?) one per assembly

"modules": [
  {
    "dependencies":[],
    "name":"...",
    "type":"MODULE",
    "types":[],
    "version":"..."
  }
]

substructures

• dependencies
• types

dependencies

?? ever used?

types

type: CLASS, DELEGATE, ENUM, INTERFACE, STRUCT

"types": [
  {
    "baseType": "...",
    "bytecode_instanceinitializer": "<base64>",
    "bytecode_instanceinitializer_fr2": "<base64>",
    "bytecode_staticinitializer": "<base64>",
    "bytecode_staticinitializer_fr2": "<base64>",
    "classattributes": [],
    "constructor": {},
    "delegateReturnType": null,
    "delegateTypes": [],
    "docString": "...",
    "fields": [],
    "imports": [],
    "interfaces": [],
    "line": 0,
    "metainfo": {},
    "methods": [],
    "name": "...",
    "package": "...",
    "properties": [],
    "source": "...",
    "type": "CLASS|DELEGATE|ENUM|INTERFACE|STRUCT",
    "typeid": 0
  }
]

substructures

• classattributes
• constructor (a method of type CONSTRUCTOR)
• delegateReturnType
• delegateTypes
• docString
• fields
• imports
• interfaces
• metainfo
• methods
• properties

classattributes

annotations for class access and mutability
final, private, public, static

"classattributes": "final|private|public|static"

constructor

a method of type: CONSTRUCTOR

delegateReturnType

a fully qualified type string, or null if no return
e.g. "system.Number" or null

"delegateReturnType": null,
"delegateReturnType": "<f.q.type>"

delegateTypes

array of fully qualified type strings used in delegate signature

"delegateTypes":[
  "<f.q.type>",
  "<f.q.type>"
]

fields

variables and constants
see properties for getters and setters

"fields":[
  {
    "docString":"...",
    "fieldattributes":[],
    "line":0,
    "metainfo":{},
    "name":"...",
    "ordinal":0,
    "source":"...",
    "templatetypes":null,
    "type":"..."
  }
]

substructures

• docString
• fieldattributes
• metainfo
• templatetypes

fieldattributes

const, native, private, protected, public, static

"fieldattributes": "const|native|private|protected|public|static"

imports

types linked with import directive
NOTE: this is not a reliable indication of dependencies; it comes verbatim from the source file and may include unused references

"imports":[
  "<f.q.type>",
  "<f.q.type>"
]

interfaces

interface types referenced via extends or implements

"interfaces":[
  "<f.q.type>",
  "<f.q.type>"
]

properties

getters and setters
see fields for variables and constants

"properties":[
  {
    "docString":"...",
    "getter":{},
    "line":0,
    "metainfo":{},
    "name":"...",
    "ordinal":0,
    "propertyattributes":[],
    "setter":{},
    "source":"...",
    "templatetypes":null,
    "type":"..."
  }
]

substructures

• docString
• getter (a method of type METHOD with no parameters that returns type)
• metainfo
• propertyattributes
• setter (a method of type METHOD with parameter of type and no return value)
• templatetypes

propertyattributes

annotations for property access and scope
private, protected, public, static

"propertyattributes": "private|protected|public|static"

references

linkage dependencies (other loomlibs)

"references":[
  {
     "name":"System"
  },
  {
     "name":"Loom"
  }
]

common data structures

Data structures shared at multiple levels

docString

documentation strings extracted from doc comment fields (/** .. */). unicode is supported.
NOTE: comment fields are associated with the construct they preceed. blank lines between a comment field and a target construct will break the association.
NOTE: during extraction, whitespace is collapsed and newlines and double quotes are escaped

"docString":"..."

metainfo

arbitrary annotations for use with the reflection API
built-in support: Inject, Bind, Native, Deprecated
custom: [MyMetadata(flagKey, key1=value1, key2=value2)] (see Reflection Guide)

"metainfo":{
  "Native":[
    [
      "managed",
      ""
    ]
  ]
}

methods

callable sub-routines
type: CONSTRUCTOR, METHOD

"methods":[
  {
    "bytecode":"<base64>",
    "bytecode_fr2":"<base64>",
    "docString":"...",
    "line":0,
    "metainfo":{},
    "methodattributes":[],
    "name":"...",
    "ordinal":0,
    "parameters":[],
    "returntype":"...",
    "source":"...",
    "templatetypes":null,
    "type":"CONSTRUCTOR|METHOD"
  }
]

substructures

• docString
• metainfo
• methodattributes
• parameters
• templatetypes

methodattributes

annotations for method access and scope
native, operator, private, protected, public, static, supercall

"methodattributes": "native|operator|private|protected|public|static|supercall"

parameters

inputs to method calls
typical: function f(p:Type):void
default: function f(p:Boolean=true):void
varargs: function f(...args):void (type of args is always Vector.<Object>)

"parameters":[
  {
    "hasdefault":false,
    "isvarargs":false,
    "name":"...",
    "templatetypes":null,
    "type":"..."
  },
  {
    "defaultvalue":"...",
    "hasdefault":true,
    "isvarargs":false,
    "name":"...",
    "templatetypes":null,
    "type":"..."
  },
  {
    "hasdefault":false,
    "isvarargs":true,
    "name":"...",
    "templatetypes":{
      "type":"system.Vector",
      "types":[
        "system.Object"
      ]
    },
    "type":"system.Vector"
  }
]

templatetypes

templated container types, i.e. Vector (array) or Dictionary (map)
type: system.Vector, system.Dictionary

:Vector.<Object>

"templatetypes":{
  "type":"system.Vector",
  "types":[
    "system.Object"
  ]
}

:Dictionary.<String,Object>

"templatetypes":{
  "type":"system.Dictionary",
  "types":[
    "system.String",
    "system.Object"
  ]
}

Nested types are valid. For example, a mapping of Type to array of Objects:

:Dictionary.<Type,Vector.<Object>>

"templatetypes":{
  "type":"system.Dictionary",
  "types":[
    "system.reflection.Type",
    {
      "type":"system.Vector",
      "types":[
        "system.Object"
      ]
    }
  ]
}