docs(parser/examples): Add various examples (also the trinitrix main api)

trixy-parser/example/derives.tri

@@ -0,0 +1,54 @@
+/*
+* 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/>.
+*/
+
+/// Call out an outstanding person
+fn outstanding(name: String);
+
+enum DogTraining {
+    Sheep,
+    Wolf,
+    Blind,
+}
+
+#[derive("Error")]
+enum TrainingMistake {
+    GotBitten,
+}
+
+struct Dog {
+    name: String,
+}
+
+struct TrainedDog {
+    name: String,
+    training: DogTraining,
+}
+
+mod one {
+    /// Say hi to a name
+    fn hi(name: String) -> String;
+
+    /// Train a dog (if it is there, otherwise do nothing)
+    fn train_dog(dog: Option<Dog>) -> Result<TrainedDog, TrainingMistake>;
+}
+
+// Trixy is a subset of Rust
+// vim: syntax=rust cms=//%s

trixy-parser/example/derives_minimal.tri

@@ -0,0 +1,6 @@
+#[derive("Error")]
+enum A {}
+
+// This derive should fail (and produce a wrong spanned error)
+#[derive("Error")]
+mod B {}

trixy-parser/example/failing_derives.tri

@@ -0,0 +1,55 @@
+/*
+* 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/>.
+*/
+
+/// Call out an outstanding person
+fn outstanding(name: String);
+
+enum DogTraining {
+    Sheep,
+    Wolf,
+    Blind,
+}
+
+#[derive("Error")]
+enum TrainingMistake {
+    GotBitten,
+}
+
+struct Dog {
+    name: String,
+}
+
+struct TrainedDog {
+    name: String,
+    training: DogTraining,
+}
+
+#[derive("Error")]
+mod one {
+    /// Say hi to a name
+    fn hi(name: String) -> String;
+
+    /// Train a dog (if it is there, otherwise do nothing)
+    fn train_dog(dog: Option<Dog>) -> Result<TrainedDog, TrainingMistake>;
+}
+
+// Trixy is a subset of Rust
+// vim: syntax=rust cms=//%s

trixy-parser/example/functions.tri

@@ -0,0 +1,31 @@
+/*
+* 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/>.
+*/
+
+/// Call out an outstanding person
+fn call_me_back_outstanding(callback: fn(name: String) -> String);
+
+mod one {
+    /// Call out a person
+    fn call_me_back(callback: fn(age: u32));
+}
+
+// Trixy is a subset of Rust
+// vim: syntax=rust cms=//%s

trixy-parser/example/trinitrix_api.tri

@@ -0,0 +1,117 @@
+//// 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>
+// This is implemented only for lua
+/* fn print(CommandTransferValue); */
+
+mod 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
+    mod std {}
+
+    /// General API to change stuff in Trinitrix
+    mod api {
+        /// Closes the application
+        fn exit();
+
+        /// Send a message to the current room
+        /// The send message is interpreted literally.
+        fn room_message_send(message: 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
+        // TODO(@soispha): To be implemented <2024-03-09>
+        // fn help(Option<String>);
+
+        //// Register a function to be used with the Trinitrix api
+        // (This function is not actually implemented here)
+        /* declare register_function: false, */
+
+        /// Function that change the UI, or UI state
+        mod 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.
+        mod keymaps {
+            /// Add a new keymapping
+            fn add(mode: String, key: String, callback: fn());
+
+            /// Remove a keymapping
+            ///
+            /// Does nothing, if the keymapping doesn't exists yet
+            fn remove(mode: String, key: String);
+
+            /// List declared keymappings
+            fn get(mode: String);
+        }
+
+        /// Functions only used internally within Trinitrix
+        mod raw {
+            /// Send an error to the default error output
+            fn raise_error(error_message: String);
+
+            /// Send output to the default output
+            /// This is mainly used to display the final
+            /// output of evaluated lua commands.
+            fn display_output(output_message: 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
+            mod __private {}
+        }
+    }
+}
+// vim: syntax=rust