librime-lua

librime-lua is a plugin for the RIME input method engine that allows users to extend its core functionality using Lua scripts. It is loaded dynamically as a librime plugin and provides the ability to implement or modify several key RIME components:

• Processors: Handle input events (e.g., key presses).
• Segmentors: Break input sequences into segments.
• Translators: Convert segments into candidate words.
• Filters: Modify the candidate list.

For translators and filters, the project provides a high-level programming model to simplify implementation.

librime-lua allows you to extend the RIME input engine by implementing its core components using Lua scripts. The library provides C++ wrapper classes that map RIME's internal interfaces to Lua functions. The primary extension points (gears) are:

• Processor: Handles key events (ProcessKeyEvent).
• Segmentor: Handles text segmentation (Proceed).
• Translator: Converts input segments into candidates (Query).
• Filter: Modifies or filters candidate lists (Apply).
• Component: A generic way to instantiate the above gears within the RIME engine.

The Lua class provides several methods to execute Lua code from C++:

• call<O, ...I>(I... input): Calls a Lua function with the provided arguments and returns a LuaResult<O> containing the result of type O.
• void_call<...I>(I... input): Calls a Lua function that returns no value, returning a LuaResult<void> to indicate success or failure.
• resume(std::shared_ptr<LuaObj> f): Resumes a coroutine/thread represented by the LuaObj f.

All these methods return a LuaResult<T>, which is a Result<T, LuaErr> type. If the call fails, the LuaErr contains a status code and an error message e.

// Calling a Lua function that returns an integer
LuaResult<int> result = lua_engine.call<int>("add", 10, 20);
if (result) {
    int val = *result;
} else {
    std::string err = result.error().e;
}

The Lua class is the primary interface for managing the Lua engine lifecycle within RIME. It handles the creation and destruction of the lua_State. You can use it to retrieve global objects, create new execution threads, and manage garbage collection.

// Example of initializing the Lua engine
Lua lua_engine;

// Accessing a global Lua object
auto my_global = lua_engine.getglobal("my_function");

You can create new Lua threads (coroutines) using the Lua class:

• newthread(I... input): Creates a new thread with the specified arguments.
• newthreadx(lua_State *L, int nargs): A lower-level constructor for creating threads from an existing lua_State.

Threads can be managed and resumed using the resume method on the Lua instance.

A LuaFilter is used to modify the list of candidates produced by a translator. It implements the Apply method.

Key behaviors:

• Apply(translation, candidates): The core logic where the Lua script processes the current translation and the candidate list.
• AppliesToSegment(segment): An optional check to determine if the filter should be applied to a specific segment. This can be controlled via a Lua function that returns a boolean. If the Lua call fails, it logs an error and returns false.

A LuaProcessor intercepts and handles raw key events.

Key method:

• ProcessKeyEvent(key_event): Receives a KeyEvent and returns a ProcessResult, allowing the Lua script to decide if the event should be consumed or passed through.

A LuaTranslator converts input strings into RIME translations.

Key method:

• Query(input, segment): Takes the current input string and the current segment, then executes the associated Lua function to return a Translation object.

To manage memory within the Lua engine, use the following methods on the Lua instance:

• gc(): Triggers a full garbage collection cycle.
• gc_step(int kb): Performs a single step of the incremental garbage collection process, taking kb as a parameter to control the amount of work.

A LuaSegmentor manages how input is broken down into segments.

Key method:

• Proceed(segmentation): Executes the Lua logic to decide how to proceed with the current segmentation state.