From b69251bc56bca21b7ee25028e3bab57bb725db63 Mon Sep 17 00:00:00 2001
From: Ahurac <ahurac@mailbox.org>
Date: Sun, 21 Jan 2024 00:27:08 +0100
Subject: [PATCH] =?UTF-8?q?qemush=20:=20ajout=20de=20commentaires=20d?=
 =?UTF-8?q?=C3=A9crivant=20les=20fonctions?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 bin/qemush | 33 +++++++++++++++++++++++++++++++++
 1 file changed, 33 insertions(+)

diff --git a/bin/qemush b/bin/qemush
index b99160e..ff5f4c3 100755
--- a/bin/qemush
+++ b/bin/qemush
@@ -1,5 +1,6 @@
 #!/bin/bash
 
+# Function to re-exec the script as another user via sudo (only if needed)
 exec_as() {
     local user
     user="$1"
@@ -10,13 +11,19 @@ exec_as() {
     fi
 }
 
+# Exec the script as qemu
 exec_as qemu "$@"
 
+# Directories used in the program
 bin="${HOME}/launchers"
 images="${HOME}/disks"
+
+# Environment
 PATH="${bin}:${HOME}/bin:${PATH}"
 EDITOR="${EDITOR:-nvim}"
 export QEMUSH_NAME
+
+# Aliases
 alias ls='ls --color=auto'
 alias exec='exec '
 if [ -t 1 ]; then
@@ -25,15 +32,20 @@ else
     alias pretty_cat=cat
 fi
 shopt -s expand_aliases
+
+# Set a restrictive umask to make sure qemu user files are private
 umask 027
 
+# Function to print a colored error
 perror() {
     >&2 printf '\033[1;31mERROR:\033[0m \033[1m%s\033[0m\n' "$*"
 }
 
+# Function to show the usage
 public_help() {
     local name
     name="$(basename "$0")"
+
     exec cat << EOF
 ${name}: usage:
   ${name} active                           - (default behaviour) list active VMs
@@ -53,12 +65,15 @@ ${name}: usage:
 EOF
 }
 
+# Function to throw an invalid usage error (skill issue)
 error_usage() {
     perror "Invalid usage"
     >&2 public_help
     return 1
 }
 
+# Function to start a virtual machine ; fails if the virtual machine is
+# already started thanks to tmux
 public_start() {
     QEMUSH_NAME="$1"
     shift
@@ -69,21 +84,26 @@ public_start() {
         "$@"
 }
 
+# Attach to a running virtual machine output, the latest opened if no
+# argument is provided
 public_watch() {
     [ -n "$1" ] && set -- -t "$1"
 
     exec tmux attach "$@"
 }
 
+# List running virtual machines
 public_active() {
     exec tmux list-sessions
 }
 
+# List available virtual machines entrypoints
 public_ls() {
     echo "Available machines:"
     exec ls "$bin"
 }
 
+# Create a copy-on-write disk for a virtual machine
 public_diskadd() {
     QEMUSH_NAME="$1"
     shift
@@ -91,6 +111,7 @@ public_diskadd() {
     exec qemu-img create -f qcow2 "$(pathof disk)" "$1"
 }
 
+# Delete a disk
 public_diskrm() {
     QEMUSH_NAME="$1"
     shift
@@ -98,47 +119,59 @@ public_diskrm() {
     exec rm -vi -- "$(pathof disk)"
 }
 
+# List available disks
 public_diskls() {
     echo "Available disks:"
     exec ls "$images"
 }
 
+# Edit a virtual machine entrypoint with a text editor
 public_edit() {
     local file="${bin}/${1}"
     "$EDITOR" "$file"
     [ -f "$file" ] && exec chmod u+x "$file"
 }
 
+# Delete a virtual machine entrypoint
 public_rm() {
     exec rm -vi -- "${bin}/${1}"
 }
 
+# Invoke bash as qemu user in its home directory
 public_shell() {
     cd || return
     exec bash -i
 }
 
+# Output the content of an entrypoint, with coloration if on a virtual
+# terminal
 public_cat() {
     pretty_cat "${bin}/${1}"
 }
 
+# Copy a file in entrypoints folder
 public_add() {
     trap return EXIT
     set -e
     local name="${2:-$(basename "$1")}"
     cp -v -i -- "$1" "${bin}/${2}"
     chmod 740 "${bin}/${name}"
+
     set +e
     trap - EXIT
 }
 
+# Run shell commands as qemu
 public_do() {
     exec sh -c "$*"
 }
 
+# Retrieve user requested function
 function="$1"
 shift
 
+# Defauts to `active` if no function is supplied; else checks for a public
+# function named after the argument; else fails
 if [ -z "$function" ]; then
     public_active
 elif declare -F | cut -d \  -f 3- | grep '^public_' | sed 's/^public_//' | grep -q "^${function}$"; then