From f84572ebd4ca6e6a10a6c10a6a963b8aa91fab3e Mon Sep 17 00:00:00 2001
From: Nikolay Nechaev <Nikolay_Nechaev@mail.ru>
Date: Mon, 16 Jan 2023 18:38:52 +0300
Subject: [PATCH] Implemented actual config parsing, added explanations

The long description at config.py.example are going to be moved to
Wikis (#18)
---
 Rimokon/__main__.py       | 27 +++++----------------------
 Rimokon/config.py.example | 39 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 44 insertions(+), 22 deletions(-)

diff --git a/Rimokon/__main__.py b/Rimokon/__main__.py
index 20c00f2..575dae4 100644
--- a/Rimokon/__main__.py
+++ b/Rimokon/__main__.py
@@ -9,11 +9,10 @@
 from requests.exceptions import RequestException
 
 from .util import cmd_get_action_name, cmd_get_rest
-from .config import bot_token, admins_ids, emergency_shutdown_command, emergency_shutdown_public
-try:
-    from .config import quick_access_cmds
-except ImportError:
-    quick_access_cmds = []
+from .import_config import bot_token, admins_ids, \
+        emergency_shutdown_command, emergency_shutdown_public, \
+        quick_access_cmds, \
+        unified_actions
 
 
 bot = telebot.TeleBot(bot_token)
@@ -95,28 +94,12 @@ def shutdown(_):
 bot.register_message_handler(shutdown,
                              func=lambda message: message.text.strip() == emergency_shutdown_command.strip())
 
-# FIXME: everything will be imported from config
-from .plugins.screenshot import screen as p_screen, screenf as p_screenf
-from .plugins.run_rawrun_shell import run, rawrun, shell, run_parsed_command
-actions = {
-        'run': run,
-        'rawrun': rawrun,
-        'shell': shell,
-        'screen': p_screen,
-        'screenf': p_screenf,
-
-        # Simple alias (will be represented as string a string alias):
-        'key': lambda bot, msg, rest: rawrun(bot, msg, 'xdotool key ' + rest, notify=False),
-        # Complex alias:
-        'type': lambda bot, msg, rest: run_parsed_command(bot, msg, ['xdotool', 'type', rest], notify=False)
-}
-
 @bot.message_handler(func=lambda message: True)  # TODO: accept other content types
 @admins_only_handler
 def run_command(message):
     wanted_action_name = cmd_get_action_name(message.text)
     command_rest = cmd_get_rest(message.text)
-    for action_name, action_func in actions.items():
+    for action_name, action_func in unified_actions.items():
         if wanted_action_name == action_name:
             Thread(target=action_func, args=(bot, message, command_rest)).start()
             return
diff --git a/Rimokon/config.py.example b/Rimokon/config.py.example
index e46df84..576ffdd 100644
--- a/Rimokon/config.py.example
+++ b/Rimokon/config.py.example
@@ -32,3 +32,42 @@ emergency_shutdown_command = 'YOUR_COMMAND_HERE'
 #
 # It is recommended to leave this enabled and keep the emergency shutdown command in secret.
 emergency_shutdown_public = True
+
+
+# The following parameters `actions` and `aliases` define the actions your Rimokon instance will be able
+# to perform. To enable them, import the action functions from plugins and add them to the following
+# dictionaries.
+
+from .plugins.run_rawrun_shell import run, rawrun, shell, run_parsed_command
+from .plugins.screenshot import screen, screenf
+
+# This dictionary specifies a mapping from action name (i.e. the command that the user will use) to the
+# action function (it will be given positional arguments: `telebot.TeleBot` object to interact with user,
+# `telebot.types.Message` object corresponding to the received message, in case it needs any metadata,
+# and an `str` with the rest of the command (i.e. part after the action name)).
+actions = {
+    'run': run,
+    'rawrun': rawrun,
+    'shell': shell,
+    'screen': screen,
+    'screenf': screenf
+}
+
+# Aliases complement the set of actions. Here users can specify their commands that are based on the
+# plugins' functionalities. Aliases may be of two types: string (simple) aliases and
+# callable (complex) aliases. They are explained in more detail below. These examples rely on the
+# `xdotool` utility installed (which is well suited for Xorg, but you may want to use another one,
+# such as `ydotool`, which works on both Xorg and Wayland).
+aliases = {
+    # A "simple alias" (or "string alias") just expands the given action name in the beginning of the
+    # received commands to the value. Notice that it is interpreted just like other action names,
+    # i.e. letters lower/upper case or trailing slashes do not matter.
+    # For this alias, for example, a command "/Key 123 key 456" is expanded to "Run xdotool key 123 key 456".
+    'key': 'Run xdotool key',
+
+    # A "complex alias" (or "callable alias") takes the same form as an `actions` entry. It works exactly
+    # the same way and there is no technical difference whether it is defined as an alias or an action.
+    # There is only logical difference: the `actions` dictionary is intended for enabling plugins, while
+    # the `aliases` dictionary is for user-defined actions.
+    'type': lambda bot, msg, rest: run_parsed_command(bot, msg, ['xdotool', 'type', rest], notify=False)
+}