Merge pull request #106 from plx-pdg/docs-cleanup-readme

docs: clean up readme

Author: samuelroland

README.md

@@ -5,139 +5,83 @@
 
 ### **P**ractice programming exos in a delightful **L**earning e**X**perience
 
-**STATUT: conception pour le projet PDG en HES d'été**
+###### Useful links
+[Website](https://plx.rs) -
+[WHY ?](https://plx.rs/book/why.html) -
+[Git repository of PLX](https://github.com/plx-pdg/plx) -
+[Git repository of this website](https://github.com/plx-pdg/plx-pdg.github.io)
 
-Au lieu de faire un projet juste pour "passer PDG", investissons ces 3 semaines à développer quelque chose qui peut avoir un fort impact sur l'expérience d'apprentissage à la HEIG-VD sur le long terme ! Si le projet atteint un état assez fonctionnel, il pourra déjà être utilisé 2 semaines plus tard à la rentrée sur des exercices de PRG1, PCO et SYE!
 
-> *The age of features is over, we are living in the age of experiences.*  
-> Aral Balkan, [dans une conférence sur l'UX intitulée "Superheroes & Villains in Design"](https://small-tech.org/videos/ux-talk/).
+### Introduction
 
-Ce n'est pas juste un projet stylé parce que le Rust c'est hype, qu'il y a un mode watch super réactif, un feedback riche... **on développe une nouvelle expérience d'apprentissage pour s'approcher de la pratique délibérée en informatique !!**
+PLX is a project developed to enhance the learning of programming languages, with a focus on a smooth and optimized learning experience. The goal of this project is to reduce the usual friction involved in completing coding exercises (such as manual compilation, running, testing, and result verification) by automating these steps.
 
-## Pourquoi
-Les exercices de code sont au coeur de l'apprentissage d'un language de programmation, cependant avoir des exercices avec des petits programmes ou fonctions à implémenter ne garantit pas que l'expérience de pratique sera efficiente. Selon la pratique délibérée, l'apprentissage profond passe par une boucle de feedback la plus courte possible, or l'expérience actuelle est loin d'être fluide et efficace.
+PLX offers a terminal user interface (TUI) developed in Rust and supports multiple languages (currently C and C++). It enables automatic compilation as soon as a file is saved, automated checks to compare program outputs, and instant display of errors and output differences. The solution code can also be displayed. The project draws inspiration from [Rustlings](https://rustlings.cool/) and aims to create a more efficient learning experience, particularly for programming courses at HEIG-VD.
 
-Prenons l'exemple d'un exercice un *petit programme en C qui demande le prénom, nom et l'âge* et affiche une phrase incluant ces 2 valeurs. L'exo fourni dans un PDF, inclut une consigne, un bout de code de départ et un exemple d'exécution, ainsi qu'un code de solution sur la page suivante.  
-Pour résoudre l'exercice, une fois la consigne lue, nous allons ouvrir un IDE, créer un fichier `main.c` manuellement, copier-coller le code de départ, lire le code existant et compléter les parties à développer.  
-Une fois terminé, passons à la compilation en ouvrant un terminal dans l'IDE en tapant `gcc main main.c & main`, euh zut c'était `gcc -o main main.c && ./main`, on rentre prénom, nom et age, puis comparons l'output manuellement pour voir si c'est bien le résultat attendu, réouvrons la consigne et non il manque l'affichage de l'âge! Revenons au code, on ajoute l'âge et on relance le build et l'exécution, on rentre prénom, nom et âge à nouveau. Est-ce que l'output est bon cette fois ? Vérifions maintenant notre code avec la solution. Okay, on aurait pu utiliser `printf` au lieu de 2 fois `puts()` pour afficher le nom complet. Passons à l'exo suivant, cherchons sa consigne, la voilà, on recommence le cycle,...
+### Installation
 
-Tous ces petites étapes supplémentaires autour de la rédaction du code semblent insignifiantes à première vue mais leur cumul résulte en une friction générale importante. En plus, il n'y aura que peu d'exécutions manuels c'est-à-dire très peu d'occasions de connaître la progression et d'ajuster son code au fur et à mesure, en plus d'une petite charge mentale pour compiler et lancer à la main.
+#### Prerequisites
 
-Imaginons que dans un laboratoire de C *nous développions maintenant une bataille navale dans le terminal*. Tester de bout en bout de manière automatique un programme en C n'est pas une tâche évidente, en partie par manque d'outil adapté. Pour tester le fonctionnement global, il faut manuellement lancer une partie et jouer plusieurs coups pour vérifier le fonctionnement et vérifier à chaque étape si le jeu est cohérent dans son état et affichage. Une fois qu'une partie du jeu fonctionne, en développant le reste on risque de casser d'autres parties sans s'en rendre compte.
+- [Cargo](https://www.rust-lang.org/tools/install)
 
-Un dernier cas concret, en *développant un petit shell en C++*, pour tester l'implémentation des pipes, il faudra compiler le shell ainsi que les CLIs accessibles, lancer le shell, puis taper quelques commandes du type `echo hey there | toupper` voir si l'output est bien `HEY THERE`, ce qui est très lent! Tester plein de plein de cas limites (plusieurs pipes, symbole de pipe collé, redirection stdout et non stderr, exit du CLI à droite du pipe, ...)
+Once you have cargo installed, simply run
 
-En résumé, le manque de validation automatisée ralentit le développement et l'apprentissage. Simplement ajouter des tests automatisés ne résoud pas tous les problèmes, car les tests runner ne sont pas adaptés à des tests sur des exos (pas de consigne, pas d'indices, affichage pas adapté, pas de mode watch, ...), il manque une partie d'automatisation autour. De plus, le travail d'écriture de tests pour des tous petits exos serait beaucoup trop conséquent, dans plein de cas comparer l'output avec une solution suffit à estimer si le programme est fonctionnel.
-
-## Expérience PLX
-**Le défi est d'arriver à réduire la friction au strict minimum, d'automatiser toutes les étapes administratives et de fournir un feedback riche, automatique et rapide durant l'entrainement.**
-
-Cette expérience sera atteinte via
-1. **La suppression des étapes de compilation et d'exécution manuelles**  
-Aucune connaissance du système de compilation ou de ses commandes n'est nécessaire, tout se fait automatiquement dès qu'un des fichiers est sauvé (il suffit donc de taper Ctrl+S ou d'attendre que l'IDE sauve automatiquement)
-1. **La suppression de toutes les rédactions manuelles de valeurs dans le terminal**  
-Permettre de définir des arguments du programme et un contenu à injecter en `stdin`, avec des variantes pour tester différents cas.
-1. **La suppression des étapes de comparaison d'output**  
-L'output sera automatiquement comparé et une diff précise (avec surlignage des différences sur chaque ligne) sera affichée pour voir immédiatemment les différences. La diff pourrait supporter du trimming de l'output ou des lignes afin d'ignorer certains espaces blancs insignifiants. Les retours à la ligne et tabulations seront affichées avec un symbole visible.
-1. **Une affichage et comparaison avec solution**  
-Une fois l'exo résolu, pouvoir auto évaluer sa réponse avec la solution d'un prof est déjà d'une grande aide. Il sera possible de voir une diff de sa réponse avec la solution directement dans PLX.
-1. **Une transition fluide entre exos**  
-Passer à l'exo suivant devrait prendre moins de 4 secondes, le temps de passer de l'IDE à PLX (Alt+Tab), d'un raccourci (n) dans PLX pour afficher l'exo suivant et le temps que l'IDE réagisse à la demande d'ouverture du fichier.
-1. **Aucun changement de fenêtre durant l'exo**  
-PLX à gauche avec toute la consigne, l'IDE à droite dans un seul fichier utile, une fois les 2 fenêtres ouvertes, il n'y a plus de changement à faire comme tout est déjà disponible. La consigne s'affiche dans PLX, dès que le fichier ouvert est sauvé, le build et l'exécution se relance. Les erreurs de build sont visibles ainsi que les résultats des tests.
-
-## Contexte
-Ce projet tire inspiration de [Rustlings](https://rustlings.cool/) qui permet de s'habituer aux erreurs du compilateur Rust en corrigeant des problèmes de compilation ou en complétant une centaine de petits exercices. Dans la même idée, d'autres languages ont suivis avec golings, cplings, ziglings, ... Ce même projet a inspirée [PRJS](https://github.com/samuelroland/prjs) (Practice Runner for JavaScript), développée à l'occasion du dernier labo libre de WEB et qui permet de s'entrainer sur des fonctions vérifiées via des tests unitaires écrits et lancés avec Vitest en arrière plan.
-
-PLX pousse encore plus loin l'expérience en supportant plusieurs languages, en y incluant la compilation automatique ainsi que le support de types de tests plus primitifs et plus simple à mettre en place qu'avec un framework de test.
+```bash
+cargo install plx
+```
 
-Note: contrairement à Rustlings, ce repository ne contient pas d'exercices réels, seulement le code de la TUI PLX. Des exercices de démonstration seront écrits dans différents languages dans un sous dossier `examples`.
+### Testing using our example folder
 
-## Types de tests
-Tous les tests pourront inclure les arguments à passer au programme. Il y a cependant différent types de tests imaginés.
+Once you have plx installed, you can try it on this repo's example folder
 
-- **Output simples**  
-Comparer l'output console d'un exo soit avec un bout de texte définie, ou si la solution est définie, directement avec son output (évitant de maintenir un output de solution séparé).
-- **Output avec injection stdin**  
-Pareil mais avec la possibilité d'injecter une string d'un coup ou par morceau (avec des délais d'attente) pour simuler des entrées utilisateurs.
-- **External command output**  
-Parfois l'output utile à comparer n'est pas celui du programme mais celui d'une commande externe. Par ex. si un programme doit créer 3 fichiers .txt, le critère de vérification pourrait être que l'output de `cat *.txt` soit le même qu'après avoir lancé le programme solution dans un autre dossier.
-- **Assertions primitives sur le code**  
-Pour vérifier que l'étudiant a ou n'a pas utilisé certaines fonctions ou mot-clés, il serait possible d'écrire une expression du type `not contains for` pour interdire le fait d'utiliser le mot clé `for` dans un exercice de récursivité qui pourrait aussi se résoudre avec un boucle. Si on veut entrainer la manipulation de string en C++ et s'assurer que la méthode `replace` soit utilisé au lieu d'un algorithme fait main, en précisant en plus un message d'erreur spécifique, cela donnerait `contains .replace "Vous devez utiliser la méthode replace !"`.
-- **Test runner**  
-Supporter les tests runner existants, ici le plus utilisé pour le C++: GoogleTest, en lançant ces tests runner en arrière plan, en générant un export des résultats et de les afficher dans PLX
+> [!IMPORTANT] 
+> Set the $EDITOR environment variable if you wish for your editor to be opened when starting an exo
 
-## Format de fichier texte
-Afin de décrire les exos (titre, consigne, les tests associés de tous types), des fichiers textes seront utilisés pour être facilement versionnable et éditable. Soit on invente un format de zéro, soit on définit juste un schéma dans un format existant (JSON, YAML, TOML, ...)
+> [!WARNING] 
+> The open editor feature is currently unstable, using a terminal based editor causes problems
+> The following editors were tested and work fine: `code`, `idea` and `codium`
 
-<!-- Voici un exemple de quelques idées de syntaxe pour se donner une idée -->
-TODO: encore à définir...
+> [!IMPORTANT] 
+> Only C and C++ exercises are valid for now, java and other languages support is comming soon™
 
-## Détails sur l'idée de projet pour PDG 2024
-Techniquement, PLX sera une TUI (Text User Interface) en Rust (probablement en utilisant un framework de TUI comme ratatui) développée avec une équipe de gens motivés par apprendre un peu le Rust cet été. Elle sera donc crossplateform pour permettre un usage sous Linux, Windows et Mac.
+```bash
+git clone [email protected]:plx-pdg/plx.git
+cd plx/examples/full
+plx
+```
 
-**Fonctionnalités à implémenter durant PDG**
-Dans l'ordre de priorité. Le support du Java étant la dernière priorité et sera fait si le temps le permet.
-1. Format de fichiers à définir, affiner, demander des feedbacks à des profs, tester de convertir différents types d'exos pour trouver les limites.
-1. Choisir un outil de build ([xmake](https://xmake.io/#/) par ex.)
-1. Implémenter le build et l'exécution de code C++, avec passage d'arguments
-1. Implémentation du chargement et de la navigation dans les listes de compétences et exos
-1. Implémenter un affichage des détails d'un exo durant l'entrainement
-1. Implémenter un mode watch solide pour lancer build+run automatiquement
-1. Support des tests sur l'output simple
-1. Support de GoogleTest
-1. Support des assertions primitives sur le code
-1. Support du C
-1. Support du Java
+On Linux and MacOS, you can easily change `EDITOR` just for PLX, here is an example for `VSCode`.
+```sh
+EDITOR=code plx
+```
 
-**Exercices disponibles**  
-Le recueil de [PRG1](https://github.com/PRG1-HEIGVD/PRG1_Recueil_Exercices) et celui de [PRG2](https://github.com/PRG2-HEIGVD/PRG2_Recueil_Exercices), ainsi que les exos de PCO avec des suites de tests GoogleTest, sont des bonnes références sur laquel réfléchir à la conception, tenter de transformer dans un nouveau format, ...
+The useful shortcuts are defined under shortcut `?`, you can mostly type `l`, `j` or `k` to move up and down, until you you reach the exo, then the editor should open and then you can do the exo (or just fill the solution next to it see `.sol.c` file), save and see changes...
 
-**Conception**  
-3 étudiants de PRG2 (cours de C) ont été interviewé et les problèmes exprimés plus haut se confirment. La vision générale a déjà été travaillée comme le montre ce README, mais il reste toute la conception détaillée pour définir à quoi va ressembler les listes d'exos et les détails de l'expérience de pratique: comment afficher les erreurs de compilation et de crash, supporter les couleurs, faire des belles diff, permettre de naviguer dans des grands outputs et voir le détail des tests avec beaucoup d'output, ...  
-Il reste tout autant de considérations techniques: comment compiler facilement sans config (si possible) du C, C++ et du Java, afficher l'exécution au fur et à mesure, quel outil de diffing choisir, comment implémenter un mode watch efficace, gérer les compilations en arrière plan, récupérer le résultat de GoogleTest, parser les fichiers textes décrivant les exos, produire des binaires de la TUI pour les 3 OS...
+### Building from source
 
-**Equipe**  
-Je souhaiterai travailler avec une équipe de 5 personnes motivées par cette vision de cette expérience PLX, si possible avec des bases de Rust ou l'envie d'apprendre/d'expérimenter cet été. Le but est aussi de faire des review de codes pour chaque PR et d'avoir des suite de tests, pour simplifier la maintenance à long terme et faciliter le développement bouillonnant sur 3 semaines.
+- Clone this repo
 
-## Usage
-**En tant qu'étudiant**  
-PLX se lance dans le terminal, sans option pour ouvrir la TUI:
-```sh
-plx
+```bash
+git clone [email protected]:plx-pdg/plx.git
 ```
 
-Pour accéder à l'aide, incluant notamment la liste des raccourcis, il est possible d'utiliser l'option `-h` ou `--help`
-```sh
-plx -h
-```
+- Build using `cargo`
 
-Pour afficher les informations de versions, notamment sur les versions minimales des dépendances installées séparement (comme xmake), il est possible d'utiliser l'option `-v` ou `--version`.
-```sh
-plx -v
+```bash
+cargo build --release
 ```
 
-Pour voir toute la hiéarchie des exos et leur états (pas commencé, commencé ou terminé), cette commande n'ouvre pas la TUI.
-```sh
-plx tree
-```
+This will install all necessary dependencies and build the program
 
-**En tant qu'enseignant**  
-Afin de faciliter la vérification régulière que tous les exos sont complets au fur et à mesure des vérifications, une commande de check serait disponible
-```sh
-plx check
-```
-Cette vérification incluerait:
-1. Qu'il y ait au moins un test qui ne passe pas dans l'exo de départ
-1. Que chaque exo ait une solution associée
-1. Que chaque solution compile et passe bien tous ses tests
+### Contributing
 
-## Usage à la HEIG-VD
-En considérant le nombre important de cours qui propose déjà actuellement des exercices en C++ (PRG1, ASD, PCO), C (PRG2, SYE), Java (POO, DAI, POA), l'impact de cet outil et cette nouvelle expérience pourrait être assez large si les enseignants sont motivés à l'adopter.  
-Le but est de limiter au maximum la quantité de travail de restructuration des exercices existants et que les configurations de compilation soient non nécessaires ou très simple à mettre en place. Je pense qu'il sera facile de motiver 2-3 étudiants pour aider à faire la migration de ces différents cours.
+Please take a look at some of the issues [here](https://github.com/plx-pdg/plx/issues).
 
-Si l'outil est utilisable et déployable à la rentrée 2024 et que les exercices peuvent être facilement et rapidement adaptés (transformer les fichiers Markdown existants pour PRG1 par ex.), les étudiants de PRG1 pourront déjà en bénéficier dès les premières semaines ! Si GoogleTest est supporté, les exos de PCO pourront aussi être entrainé avec PLX. En SYE, les labos dans SO3 pourraient aussi être aidé (beaucoup d'étudiants perdent du temps à lancer les commandes de build, à éxecuter, à tester des commandes).
+- Fork this project
+- Create a branch
+- Develop your solution
+- Create a Pull Request
 
-## Licence
-Ce projet n'a pas encore de licence libre, il est donc techniquement propriétaire pour le moment. Une fois le projet PDG terminé, le projet ne va pas s'arrêter, des finitions seront probablement nécessaires et la maintenance continuera sur le temps libre. Tout comme PRJS, l'objectif important est de demander à l'école de reprendre les droits d'auteurs afin de pouvoir publier ce projet sous licence libre. Une condition pour faire partie de l'équipe est donc d'être d'accord de cette finalité pour qu'au moment de faire les démarches administratives tout le monde soit déjà d'accord.
+### License
 
+We are currently waiting for our school's approval before applying an open source license.

src/app/app.rs

@@ -247,7 +247,9 @@ impl App {
     ) -> Result<ExoStatusReport, StartExoFail> {
         App::cleanup_previous_run(wh);
         // Open editor, Compile exo and start watchers
-        App::open_editor(wh, exo).ok_or(StartExoFail::CouldNotLaunchEditor)?;
+        // TODO warn user if we couldn't open editor but ignore error for now so it doesn't stop us
+        // from launching
+        let _ = App::open_editor(wh, exo); // Ignore Error while opening editor for now
         let output_path =
             App::compile(wh, exo).map_err(|err| StartExoFail::CouldNotStartCompilation(err))?;
         App::start_watcher(wh, exo);

src/core/editor/editor.rs

@@ -3,7 +3,18 @@ use std::env;
 // Collects the EDITOR set using the env variable
 pub fn get_default_editor() -> Option<String> {
     match env::var("EDITOR") {
-        Ok(editor) => Some(editor.into()),
+        Ok(editor) => {
+            let valid_editors: Vec<String> = vec![
+                String::from("code"),
+                String::from("codium"),
+                String::from("idea"),
+            ];
+            if valid_editors.contains(&editor) {
+                Some(editor)
+            } else {
+                None
+            }
+        }
         Err(_) => None,
     }
 }