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.6 from with a few customizations:

Include search path: /Applications/
Library search path: /Applications/
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:

    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

Equatable Classes

If a class is marked as “equatable”, you can compare its instances using the == operator:

local folder = actionContext.activePane.model.folder
if folder then
    print(folder.fileSystem == localFileSystem)

Note that two comparisons above are not identical. There might be virtual file systems on top of local one, such as the file system used for the Analyze disk usage action.

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:


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)
    martax.alert("Original path: " .. canonical.path)