/*
* Copyright (C) 2023 - 2024:
* The Trinitrix Project <soispha@vhack.eu, antifallobst@systemausfall.org>
*
* This file is part of the Trixy crate for Trinitrix.
*
* Trixy is free software: you can redistribute it and/or modify
* it under the terms of the Lesser GNU General Public License as
* published by the Free Software Foundation, either version 3 of
* the License, or (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* and the Lesser GNU General Public License along with this program.
* If not, see <https://www.gnu.org/licenses/>.
*/



/// Prints to the output, with a newline.
// HACK(@soispha): The stdlib Lua `print()` function has stdout as output hardcoded,
// redirecting stdout seems too much like a hack thus we are just redefining the print function
// to output to a controlled output.  <2023-09-09>
//fn print(input: CommandTransferValue);

nasp trinitrix {
    /// Language specific functions, which mirror the `trinitrix.api` namespace.
    /// That is, if you have to choose between a `std` and a `api` function choose the `std`
    /// one as it will most likely be more high-level and easier to use (as it isn't abstracted
    /// over multiple languages). Feel free to drop down to the lower level api, if you feel
    /// like that more, it should be as stable and user-oriented as the `std` functions
    nasp std {}

    /// Debug only functions, these are effectively useless
    nasp debug {
        enum UserGreet {
            Friendly,
            Angrily,
            Hastly
        };
        struct GreetedUser {
            names: Vec<String>,
            new: GreetedUser,
            state: UserGreet
        };
        /// Greets the user
        fn greet(input: String) -> String;

        /// Returns a table of greeted users
        fn greet_multiple() -> GreetedUser;
    }

    /// General API to change stuff in Trinitrix
    nasp api {
        /// Closes the application
        fn exit();

        /// Send a message to the current room
        /// The send message is interpreted literally.
        fn room_message_send(msg: String);

        /// Open the help pages at the first occurrence of
        /// the input string if it is Some, otherwise open
        /// the help pages at the start
        fn help(input: Option<String>);

        // Register a function to be used with the Trinitrix API
        // (This function is actually implemented in the std namespace)
        /* fn register_function(function: RawFunction); */

        /// Function that change the UI, or UI state
        nasp ui {
            /// Shows the command line
            fn command_line_show();

            /// Hides the command line
            fn command_line_hide();

            /// Go to the next plane
            fn cycle_planes();
            /// Go to the previous plane
            fn cycle_planes_rev();

            /// Sets the current app mode to Normal / navigation mode
            fn set_mode_normal();
            /// Sets the current app mode to Insert / editing mode
            fn set_mode_insert();
        }

        /// Manipulate keymappings, the mode is specified as a String build up of all mode
        /// the keymapping should be active in. The mapping works as follows:
        ///     n => normal Mode
        ///     c => command Mode
        ///     i => insert Mode
        ///
        /// The key works in a similar matter, specifying the required keypresses to trigger the
        /// callback. For example "aba" for require the user to press "a" then "b" then "a" again
        /// to trigger the mapping. Special characters are encoded as follows:
        ///     "<C-a>ba" => "Ctrl+a" then "b" then "a"
        ///     "<S-a>" => "A" or "Shift+a"
        ///     "A" => "A"
        ///     "<M-a> " => "Alt+a" (<A-a>) or "Meta+a"(<M-a>) (most terminals can't really differentiate between these characters)
        ///     "a<C-b><C-a>" => "a" then "Ctrl+b" then "Ctrl+a" (also works for Shift, Alt and Super)
        ///     "<CSM-b>" => "Ctrl+Shift+Alt+b" (the ordering doesn't matter)
        ///     "a " => "a" then a literal space (" ")
        ///     "å🙂" => "å" then "🙂" (full Unicode support!)
        ///     "<ESC>" => escape key
        ///     "<F3>" => F3 key
        ///     "<BACKSPACE>" => backspace key (and so forth)
        ///     "<DASH>" => a literal "-"
        ///     "<ANGULAR_BRACKET_OPEN>" or "<ABO>"  => a literal "<"
        ///     "<ANGULAR_BRACKET_CLOSE>" or "<ABC>" => a literal ">"
        ///
        /// The callback MUST be registered first by calling
        /// `trinitrix.api.register_function()` the returned value can than be used to
        /// set the keymap.
        nasp keymaps {
            /// Add a new keymapping
            fn add(mode: String, key: String, callback: Function);

            /// Remove a keymapping
            ///
            /// Does nothing, if the keymapping doesn't exists
            fn remove(mode: String, key: String);

            /// List declared keymappings
            fn get(mode: String);
        }

        /// Functions only used internally within Trinitrix
        nasp raw {
            /// Send an error to the default error output
            fn raise_error(input: String);

            /// Send output to the default output
            /// This is mainly used to display the final
            /// output of evaluated lua commands.
            fn display_output(input: String);

            /// Input a character without checking for possible keymaps
            /// If the current state does not expect input, this character is ignored
            /// The encoding is the same as in the `trinitrix.api.keymaps` commands
            fn send_input_unprocessed(input: String);

            /// This namespace is used to store some command specific data (like functions, as
            /// ensuring memory locations stay allocated in garbage collected language is hard)
            ///
            /// Treat it as an implementation detail
            nasp __private {}
        }
    }
}

// That's a flat out lie, but it results in a rather nice syntax highlight compared to nothing:
// vim: syntax=rust