KeyChord - v2 AutoHotKey Class

/**
 *  KeyChord.ahk
 *
 *  A class for writing key chords in AutoHotKey.
 *  Now combinations like "Ctrl+Win+d, x, u" are supported!
 *
 *  @version 1.0
 *  @author Komrad Toast ([email protected])
 *  @see https://autohotkey.com/boards/<RELEASE PAGE LINK>
 *  @license
 *  Copyright (c) 2024 Tyler J. Colby (Komrad Toast)
 *
 *  Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated
 *  documentation files (the "Software"), to deal in the Software without restriction, including without limitation
 *  the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software,
 *  and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
 *
 *  The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
 *
 *  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
 *  OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
 *  LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR
 *  IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 *
**/

#Requires AutoHotkey v2.0

/**
 *  KeyChord class
 *  This class provides a way to map keys to commands or nested key Chords.
 *  It allows for executing commands or nested key Chords based on user input.
 *  @class KeyChord
 *  @method `Add(key)`
 *  @method `Delete(key)`
 *  @method `Clear()`
 *  @method `Execute(timeout)`
**/
class KeyChord
{
    /**
     *  @type {Map}
     *  @private
     *  @desc Map of keys to commands
    **/
    commands := Map()

    /**
     *  @type {Map}
     *  @private
     *  @desc Map of keys to nested KeyChord instances
    **/
    nestedChords := Map()

    /**
     *  Add a key-command mapping or a nested key Chord.
     *  @public
     *  @param {String} key The key to map
     *  @param {String|Integer|Float|BoundFunc|KeyChord} command - The command or nested key Chord to map
     *  @returns {Void}
    **/
    Add(key, command)
    {
        if IsObject(command) && (Type(command) == "KeyChord")
        {
            this.nestedChords.Set(key, command)
        }
        else
        {
            this.commands.Set(key, command)
        }
    }

    /**
     *  Remove a key-command mapping or a nested key Chord.
     *  @public
     *  @param {String} key The key to remove
     *  @returns {Void}
    **/
    Remove(key)
    {
        if this.commands.Has(key)
        {
            if (Type(key) == "KeyChord")
                this.nestedChords.Delete(key)
            else
                this.commands.Delete(key)
        }
    }

    /**
     *  Clear all key-command mappings and nested key Chords.
     *  @public
     *  @returns {Void}
    **/
    Clear()
    {
        commands := Map()
        nestedChords := Map()
    }

    /**
     *  Execute the command or nested key Chord mapped to the user input.
     *  @public
     *  @param {Integer} timeout The timeout (in milliseconds) for user input
     *  @returns {Void}
    **/
    Execute(timeout)
    {
        key := GetUserInput(timeout)

        if this.commands.Has(key)
        {
            command := this.commands.Get(key)
            this.ExecuteCommand(command, timeout)
            return
        }
        else if this.nestedChords.Has(key)
        {
            nestedChord := this.nestedChords.Get(key)
            nestedChord.Execute(timeout)
            return
        }
        else
        {
            MsgBox("Key not found: " . key, "Error")
        }
    }

    /**
     *  Execute the given command based on its type.
     *  @private
     *  @param {BoundFunc|Boolean|Integer|String|Float|KeyChord} command The "command" to execute
     *  @param {Integer} timeout The timeout (in milliseconds) for user input
     *  @returns {Void}
    **/
    ExecuteCommand(command, timeout)
    {
        cmdType := Type(command)

        Switch cmdType
        {
            Case "String":
                Send(command)
                return
            Case "Integer":
                Send(command)
                return
            Case "Float":
                Send(command)
                return
            Case "Boolean":
                Send(command)
                return
            Case "KeyChord":
                this.ExecuteNestedChord(timeout)
                return
            Case "BoundFunc":
                command.Call()
                return
            Default:
                MsgBox("Invalid Key Chord type: " cmdType, "Error")
                return
        }
    }

    /**
     *  Execute a nested key Chord.
     *  @private
     *  @param {Integer} timeout - The timeout (in milliseconds) for user input
     *  @returns {Void}
    **/
    ExecuteNestedChord(timeout)
    {
        this.Execute(timeout)
    }

    SendValue(val)
    {
        Send(val)
        return
    }
}