Basic information

This page explains the basic concepts of the Marta API. Some of the ideas may seem trivial to you, especially if you have experience with different programming languages. However, reading the page will surely help you to dive into Marta plugin development.

Lua distribution

Marta bundles Lua 5.3.5 from lua.org with a few customizations:

Include search path: /Applications/Marta.app/Contents/Headers.
Library search path: /Applications/Marta.app/Contents/Frameworks.
Run Clang with the -llua option to compile against Lua library.

Declaration kinds

Marta API introduces several kinds of declarations. If you know some OOP language such as Java or Kotlin, this will be familiar to you.

All methods are called with a colon syntax: obj:method(). In Marta API there are no static methods.

Instantiable classes

If a class is marked as “instantiable”, you can create an instance of it in Lua and pass it to the API method.

The most obvious example is the action declaration. Normally, you define an action using the action() function that accepts a single argument of a ActionDeclaration type. Because the ActionDeclaration class is instantiable, we can create a table and pass it:

action({
    id = "id",
    name = "Name",
    apply = function(context) end
})

Lua allows to omit parentheses if the only argument type is a string literal, or a table constructor:

action {
    id = "id",
    name = "Name",
    apply = function(context) end
}

Type kinds

Marta API is strong-typed. If you pass a number value for a string-typed parameter, an error will occur. In some places, however, Marta API accepts values of several types (see union type below).

Here are the type kinds used in the API reference:

You do not need to use type annotations in Lua code, just pass values of correct types to API functions.

Built-in types

There are several built-in types:

Errors

Marta API functions typically do not throw errors. Instead, they return multiple values, first of which is an Error class instance.

For instance, here is how you can check if the File.canonicalize() call finished successfully:

local err, canonical = file:canonicalize()

if err then
    martax.alert("An error occurred: " .. err.description)
else
    martax.alert("Original path: " .. canonical.path)
end