--!strict

--- Contains types for building ReaLearn MIDI scripts in Lua.
local module = {}

--- Type of the `y` variable in MIDI scripts, which represents the input value of the MIDI script.
---
--- This input value is usually generated by the "Target" and/or the "Glue" section.
export type InputValue = OffInputValue | NumericInputValue | TextInputValue | ComplexInputValue

--- Whenever the input value is `nil`, ReaLearn wants you to "switch off" feedback.
---
--- Meaning of "switch off" depending on the type of feedback element:
---
--- - LED: Switch LED off
--- - Motor fader: Tear it completely down
--- - Text display: Clear all characters
export type OffInputValue = nil

--- A simple numeric value.
---
--- ReaLearn sends this if the feedback type in the "Glue" section is set to "Numeric feedback".
---
--- Currently, this should always be a value within the unit interval, that is a value between 0.0 (= 0%)
--- and 1.0 (= 100%).
export type NumericInputValue = number

--- A chunk of text.
---
--- ReaLearn sends this if the feedback type in the "Glue" section is set to "Textual feedback".
---
--- This is obviously most useful for text displays. But it can also be used for LED. When you design
--- a virtual control scheme, you could for example declare that the text "blinking" should make the LED blink.
export type TextInputValue = string

--- A value that could be anything, from a simple number to a complex table.
---
--- ReaLearn sends this if the feedback type in the "Glue" section is set to "Dynamic feedback".
export type ComplexInputValue = any

--- Provides access to some data that might come in useful to create the outgoing MIDI messages.
export type Context = {
    feedback_event: FeedbackEvent
}

--- More data about the feedback event which triggered the execution of this MIDI script.
export type FeedbackEvent = {
    --- Color as set in the "Glue" section.
    ---
    --- Either the default color (= `nil`) or an RGB color.
    color: RgbColor?,
    --- Background color as set in the "Glue" section.
    background_color: RgbColor?,
}

--- Color in the RGB color system.
export type RgbColor = {
    r: number,
    g: number,
    b: number,
}

--- You are supposed to return a value structured like that.
export type Output = {
    --- Feedback address.
    ---
    --- Each distinct feedback element on the controller (LED, motor fader, etc.) should get a unique feedback address.
    --- If you get this value wrong or don't set it at all, you might experience weird feedback behavior, e.g. LEDs that 
    --- stay on or switch off when they shouldn't.
    address: number?,
    --- A list MIDI messages to be sent to the controller.
    messages: { MidiMessage }
}

--- Array containing the raw bytes of a MIDI message.
---
--- You can express any kind of MIDI message with that.
export type MidiMessage = { number }

return module