Switching to a script-based configuration file format

[polluxcodes]

I've been thinking of a way to improve the customizability of Picom, but since in would require some significant changes to the code and how users interact with it, I thought it would be worthwile to open a discussion about it.

What

Use an established scripting language (e.g. LuaJIT) for configuration.

The existing picom.conf file would be replaced with a picom.lua file, or something similar, that would be run at startup.

I will try to implement this myself, but I would like some input from people more experienced with Picom. Since I am planning to use Lua, I will refer to it for the rest of this issue, but many of the points I make hold regardless of which language is used.

Why

The degree of customization required of Picom is much more than in the past, and upcoming features such as animation will require even more. A script-based configuration format would make adding such features easier since it would alleviate the need to write configuration parsers for them. It would also allow for more sophisticated interactions between Picom and user configuration.

A few examples of current and planned features that could benefit from this:

• Exclude/include conditions could be implemented as calls to Lua functions that would allow for more complex logic. For example using Lua's built-in regex library.
• Window animations can also be replaced with function calls; letting users define their own easing functions using Lua's math library, or randomize aspects of it using Lua's math.random.
• An external interface could be made to allow direct calls to user-defined Lua functions to alter certain aspects of Picom's behavior during runtime.

Using an existing scripting language will also simplify Picom's documentation, since complex features with custom syntax, such as the conditions, could be explained well with just a description of the expected arguments and return type of a single user-defined Lua function.

Example

Here is an example of what part of such a configuration file could look like:

picom.shadow = {
    enabled = false
}

picom.blur = {
    enabled = true,
    method = 'dual_kawase',
    strength = 15,
    blur_background = true,
    exclude = function (window)
        return window.type == 'dock' or window.type == 'desktop'
    end
}

-- Potential animation definition based on @yshui's animation framework
picom.animations = {
    {
        triggers = { 'close', 'hide' },
        duration = 1,
        callback = function (window, t)
            return {
                opacity = 1,
                offset_y = -t * (window.height + window.y)
            }
        end
    }
}

-- Potential external interface definition for the future, could be called using
-- something like `picomctl toggleblur`, or through D-Bus.
picom.interface = {
    toggleblur = function(args)
        picom.blur.enabled = not picom.blur.enabled
    end
}

Supporting Mutable State

Allowing calls to user-defined functions would also allow the user to change parts of the configuration during runtime. I think this would be a good thing to allow for certain configuration options, but I am unsure as to the best way to implement it without sacrificing performance or compatibility.

Option 1: Transfer configuration to existing options struct at startup

The first option would be to run the configuration script at startup and transfer the resulting configuration to the existing options struct at startup. Certain configuration options can be references to Lua functions that can be called when required.

This would have the advantage of requiring the least amount of code to be rewritten, since the means of accessing the configuration options is left intact. It would also likely have the smallest performance impact for this reason, as subsequent calls to Lua libraries are minimized. This also means that any performance impact would be limited to features using Lua function calls.

The disadvantage of this is that mutable state would be limited to the internal state of the Lua runtime, where it could only affect features that rely on calls to Lua functions.

Option 2: Replace options struct with Lua state

The second option would be to replace the options struct entirely and rely solely on lua_State to store the configuration.

This would require significant changes to the codebase, since accessing configuration options would require multiple calls to the Lua library and would probably impact performance negatively.

It would also allow the user to modify configuration options that should not change, which would likely result in instability.

Option 3: Update options struct using Lua runtime periodically

The final approach would be to periodically update any mutable configuration in the options struct using the corresponding state in the Lua library.

This in my opinion is the best approach, as it allows for mutable state without significantly affecting performance. It also ensures that any immutable options are not changed, as they can be excluded from subsequent updates.

Possible Concerns

Performance

Depending on how and how well it is implemented, this feature could significantly affect performance. However, I am confident that it could be implemented in a way that results in minimal performance impact without sacrificing many of the advantages mentioned above.

Usability

As Lua is a Turing-complete programming language, using it for configuration could make configuring Picom difficult (see: AwesomeWM). However, as the majority of Picom's configuration are values that need to be set, and not complex behavior that needs to be defined, a Lua configuration file would be quite intuitive and mostly consist of a few assignment operations to a table like in the example above. I don't think such a configuration file would be much harder to understand or edit than the existing configuration file.