3.1 KiB

Raw Permalink Blame History

Add-on Interface (Unstable)

Basic

Add-on is a Lua script.
Values passed or returned to Red Panda C++ must be JSON compatible, i.e.,
- nil (maps to null)
- boolean
- number
- string
- empty table (maps to null)
- table with only array part (maps to array)
- table with only hash part (maps to object)
Red Panda C++ APIs exposed to add-on are organized by groups.
- Each group is a Lua table.
- Each API is a function in the table.
- Available API groups vary by add-on kind.
- See env.d.tl for API definitions.
Add-on can be executed only if the API version is compatible.
Localization is handled by add-on.

API Version Check

Add-on must implement apiVersion that takes no argument and returns ApiVersion (env.d.tl).

Before execution, Red Panda C++ will call apiVersion() without injecting any API group¹ to check whether the add-on is compatible with current Red Panda C++ (host).

Add-on is compatible with host if and only if:

(add-on kind = host kind) ∧ (
  ((add-on major = host major = 0) ∧ (add-on minor = host minor)) ∨
  ((add-on major = host major ≥ 1) ∧ (add-on minor ≤ host minor))
)

That is to say:

API version is kind-specific.
For a given kind, API major reported by add-on must be equal to host major.
- API major = 0 means unstable, minor updates may break backward compatibility.
- API major ≥ 1 means stable, minor updates keep backward compatibility.

Types

Types in Red Panda C++ add-on interface are defined in Teal language, a typed dialect of Lua.

To make use of the type definitions, add-on can be written in Teal. To check and compile Teal add-on:

tl check --include-dir /path/to/RedPanda-CPP/addon --global-env-def defs/theme addon.tl
tl gen --include-dir /path/to/RedPanda-CPP/addon --global-env-def defs/theme --gen-compat off --gen-target 5.4 addon.tl

Localization

Example:

local lang = C_Desktop.language()
-- note: explicitly declare as `{string:string}` for Teal
local localizedName = {
    en_US = "System",
    pt_BR = "Sistema",
    zh_CN = "系统",
    zh_TW = "系統",
}
return {
    name = localizedName[lang] or localizedName.en_US,
    -- ...
}

Simple Add-on

A simple add-on is a Lua script with a main function returning single value.

Theme Add-on

Current API version: theme:0.1.

Available API groups:

C_Debug
C_Desktop
C_Util

main function takes no argument and returns Theme (theme.d.tl).

Compiler Hint Add-on

Current API version: compiler_hint:0.1.

If $appLibexecDir/compiler_hint.lua exists, it will be executed as compiler hint add-on when searching for compiler.