trixy 0.4.0

/*
 * Copyright (C) 2023 - 2024:
 * The Trinitrix Project <soispha@vhack.eu, antifallobst@systemausfall.org>
 * SPDX-License-Identifier: GPL-3.0-or-later
 *
 * 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 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 GNU General Public License along with this program.
 * If not, see <https://www.gnu.org/licenses/>.
 */

#if !defined TRIXY_MAIN_HEADER
#define TRIXY_MAIN_HEADER

#include "common.h"
#include "errno.h"
#include "option.h"
#include "result.h"
#include "string.h"
#include "vec.h"

/**
 * Closes the application
 */
extern int trinitrix_api_exit ();

/**
 * Send a message to the current room
 * The send message is interpreted literally.
 */
extern int trinitrix_api_room_message_send (const char *message);

enum Mode
{
  /**
   * Default mode (navigation mode)
   */
  Normal,
  /**
   * Allows you to insert things
   */
  Insert,
  /**
   * actives the command line
   */
  Command,
};

/**
 * Change the active mode
 */
extern int trinitrix_api_ui_set_mode (enum Mode mode);

/**
 * Go to the next plane
 */
extern int trinitrix_api_ui_cycle_planes ();

/**
 * Go to the previous plane
 */
extern int trinitrix_api_ui_cycle_planes_rev ();

/**
 * Add a new keymapping
 */
extern int trinitrix_api_keymaps_add (const char *mode, const char *key,
                                      void (*callback) ());

/**
 * Remove a keymapping
 *
 * Does nothing, if the keymapping doesn't exists yet
 */
extern int trinitrix_api_keymaps_remove (const char *mode, const char *key);

/**
 * List declared keymappings
 */
extern int trinitrix_api_keymaps_get (const char *mode);

/**
 * Send an error to the default error output
 */
extern int trinitrix_api_raw_raise_error (const char *error_message);

/**
 * Send output to the default output
 * This is mainly used to display the final
 * output of evaluated lua commands.
 */
extern int trinitrix_api_raw_display_output (const char *output_message);

/**
 * 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
 */
extern int trinitrix_api_raw_send_input_unprocessed (const char *input);

/**
 * 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
 */
struct stdi
{
};

/**
 * Function that change the UI, or UI state
 */
struct ui
{
  int (*set_mode) (enum Mode);
  int (*cycle_planes) (void);
  int (*cycle_planes_rev) (void);
};

/**
 * 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.
 */
struct keymaps
{
  int (*add) (const char *, const char *, void (*callback) ());
  int (*remove) (const char *, const char *);
  int (*get) (const char *);
};

/**
 * 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
 */
struct __private
{
};

/**
 * Functions only used internally within Trinitrix
 */
struct raw
{
  int (*raise_error) (const char *);
  int (*display_output) (const char *);
  int (*send_input_unprocessed) (const char *);
  struct __private __private;
};

/**
 * General API to change stuff in Trinitrix
 */
struct api
{
  int (*exit) (void);
  int (*room_message_send) (const char *);
  struct ui ui;
  struct keymaps keymaps;
  struct raw raw;
};

struct trinitrix
{
  struct stdi stdi;
  struct api api;
};

const struct stdi stdi = {};
const struct ui ui = {
  .set_mode = trinitrix_api_ui_set_mode,
  .cycle_planes = trinitrix_api_ui_cycle_planes,
  .cycle_planes_rev = trinitrix_api_ui_cycle_planes_rev,
};
const struct keymaps keymaps = {
  .add = trinitrix_api_keymaps_add,
  .remove = trinitrix_api_keymaps_remove,
  .get = trinitrix_api_keymaps_get,
};
const struct __private __private = {};
const struct raw raw = {
  .raise_error = trinitrix_api_raw_raise_error,
  .display_output = trinitrix_api_raw_display_output,
  .send_input_unprocessed = trinitrix_api_raw_send_input_unprocessed,
  .__private = __private,
};
const struct api api = {
  .exit = trinitrix_api_exit,
  .room_message_send = trinitrix_api_room_message_send,
  .ui = ui,
  .keymaps = keymaps,
  .raw = raw,
};
const struct trinitrix trinitrix = {
  .stdi = stdi,
  .api = api,
};

#endif // if !defined TRIXY_MAIN_HEADER
// vim: filetype=c