Le langage ple (PLaTon Exercise)

La programmation d'un exercice sur la plateforme PLaTon nécessite une compréhension des fondamentaux de sa syntaxe, de la gestion des variables, des opérateurs, et des divers éléments qui composent un exercice interactif. Cette section fournit un guide détaillé pour démarrer avec la création d'exercices sur PLaTon.

Syntaxe

Les exercices sont écrits à l'aide du langage ple créé spécialement pour la plateforme. C'est un langage déclaratif simple permettant d'associer des valeurs à des clés. Les clés décrivent les éléments primordiaux permettant de mettre en jeu l'exercice de manière interactive devant l'utilisateur.

Ainsi, les premières clés caractérisant un exercice sont title dont la valeur donnera un titre à l'exercice ainsi que statement dont le contenu donnera le corps de l'énoncé. La création d'exercice repose donc sur la définition de clés précises qui seront interprétées par la plateforme afin d'afficher l'exercice.

Bien qu'il soit possible d'écrire des exercices sans aucune connaissance en informatique, des connaissances en HTML, JavaScript et Python pourront vous permettre de mieux personnaliser vos exercices.

Pour illustrer les concepts de base abordés dans cette documentation, nous allons partir d'un exemple simple d'exercice : une addition aléatoire.

# Choix de la sandbox
sandbox = "node"
 
# Initialisation des composants
input = :wc-input-box
input.type = "number"
input.placeholder = "Entrez votre réponse ici"
 
# Initialisation des composants de solution
inputSolution = :wc-input-box
inputSolution.type = "number"
inputSolution.disabled = true
inputSolution.placeholder = "Solution"
 
 
# Paramètrage des aides
hint = [
  @copycontent help.md,
  "Aide 2"
]
 
# Paramètrage des théories
theories = [
  { title: "Lien vers une ressource externe", url: "https://google.com" },
  { title: "Lien vers une ressource interne", url: @copyurl readme.md }
]
 
# Génération des nombres aléatoires
max = 10
 
builder == #!lang=js
 
a = Math.round(Math.random() * max)
b = Math.round(Math.random() * max)
inputSolution.value = a + b
 
==
 
# Évaluation de la réponse
grader == #!lang=js
 
grade = 0
feedback.type = "error"
feedback.content = "Mauvaise réponse"
if (input.value === inputSolution.value) {
  grade = 100
  feedback.type = "success"
  feedback.content = "Bonne réponse"
}
 
==
 
# Énoncé de l'exercice
title==
Addition aléatoire
==
 
statement ==
Combien font {{a}} + {{b}} ?
==
 
form==
{{input}}
==
 
solution==
{{inputSolution}}
==

Utilisation des Variables

Les variables dans PLaTon peuvent être de différents types et sont utilisées pour stocker des informations ou des éléments d'exercice.

Types de variables

• Nombres, chaînes de caractères, booléens.
• Références, objets, tableaux.
• URL de fichier, contenu de fichier.
• Composants (ex : :wc-input pour un champ de saisie).

Affectation de Variables :

• L'affectation se fait avec le symbole =.

# Primitives
mystring = "Hello World"
myint = 42
myfloat = 3.14
mynumber_with_underscores = 1_000_000 # Les underscores sont ignorés
mybool = true # Il est possible d'utiliser la syntaxe python avec True et False
 
# Manipulation de fichiers
myurl = @copyurl /path/to/file.txt
mycontent = @copycontent /path/to/file.txt
 
# Composants
mycomponent = :wc-input
 
# Références
myreference = mystring # Les variables peuvent être référencées entre elles
 
# Tableaux
myarray = [42, "Hello World", true, false, True, @copyurl /path/to/file.txt, @copycontent /path/to/file.txt, :wc-input]
 
# Objets
myobject = {
  key1: "value1",
  key2: :wc-input,
  key3: @copyurl /path/to/file.txt,
  key4: @copycontent /path/to/file.txt,
  "key with space": "value with space"
}
 
# Objects avec notation pointée
myobject_dot_notation.key1 = "value1"
myobject_dot_notation.key2 = :wc-input
myobject_dot_notation.key3 = @copyurl /path/to/file.txt

Opérateurs ==

L'opérateur == permet de saisir des chaînes multilignes brutes (sans échappement).

mystring ==
Ligne 1
Ligne 2
==

Cette opérateur est particulièrement utile pour entrer des textes, des scripts Python, des blocs HTML, etc.

myscript ==
lst = []
for k in range(5):
 lst.append(k**2)
==

Il est possible d'activer une coloration syntaxique dans l'éditeur PLaTon en ajoutant une balise en commentaire après l'opérateur ==. Dans l'exemple ci-dessous, la balise py active la coloration syntaxique Python pour le code contenu dans la clé myscript.

myscript == #!lang=py
lst = []
for k in range(5):
 lst.append(k**2)
==

PLaTon utilise monaco-editor (opens in a new tab) pour l'édition de code. Il est possible d'activer la coloration syntaxique pour de nombreux langages y compris le language PLaTon avec #!lang=pl-py ou #!lang=pl-js en fonction du type de sandbox.

Inclusion de Fichier dans l'environnement de l'exercice

Les exercices sont executés dans un environnement isolé (sandbox). Il est possible d'inclure des fichiers dans cet environnement afin de les lire pour générer notamment des données aléatoires. Un exemple d'utilisation est l'utilisation d'un fichier csv contenant des données pour générer des questions aléatoires.

• Utilisez @include CHEMIN pour inclure des fichiers dans l'environnement de l'exercice.
• Utilisez @include CHEMIN as NOM pour inclure des fichiers dans l'environnement de l'exercice et les renommer.

Héritage

Hériter d'un fichier .ple consiste à importer son contenu (clés, fichiers à charger). C'est avec l'opérateur @extends qu'on effectue cette opération.

• Permet de réutiliser et étendre le code d'autres exercices.
• Utilisez @extends CHEMIN pour hériter d'un autre exercice.

Exemple. L'exercice associé au fichier main.ple contiendra une clé key1 valant 0 et une clé key2 valant "toto".

@extends parent.ple
key1 = 0

Composition

La composition est la même chose que l'héritage à la différence que dans le cas d'une composition, on affecte les clés du fichier importé à une variable.

  mydict = @extends parent.ple
  mydict.key1 = 0

Les références de fichiers

Comme vue précédemment, certains opérateurs se servent de fichiers, il est donc important de savoir comment référencer ces fichiers dans les exercices.

Il y a quatre manière de référencer un fichier:

• Avec un chemin relatif à l'exercice
  • ex: readme.md
• Avec un chemin absolue vers un fichier du cercle parent de l'exercice, commençant par /CODE_DU_CERCLE
  • ex: /informatique/chemin/vers/fichier.ext
• Avec un chemin absolue vers une version particulière d'un fichier du cercle parent de l'exercice, commençant par /CODE_DU_CERCLE:VERSION
  • ex: /informatique:v1/chemin/vers/fichier.ext

Ainsi, avec une arbre de répertoires comme celui-ci:

• monexo est la racine de l'exercice
• informatique est le cercle parent de l'exercice
• platon est le cercle parent du cercle informatique
• #latest indique qu'on visualise la dernière version du cercle

• Il est possible de référencer base.ple du cercle informatique à l'intérieur de main.ple par :

/informatique/templates/base.ple

• Il est possible de référencer readme.md de l'exercice monexo à l'intérieur de main.ple par :

readme.md

• Il est possible de référencer readme.md du cercle platon à l'intérieur de main.ple par :

/platon:v1/readme.md