Outils pour utilisateurs
local:moodlescript:syntaxspecification
Différences
Ci-dessous, les différences entre deux révisions de la page.
| Prochaine révision | Révision précédente | ||
|
local:moodlescript:syntaxspecification [2019/03/26 13:06] admin créée |
local:moodlescript:syntaxspecification [2024/04/04 15:52] (Version actuelle) |
||
|---|---|---|---|
| Ligne 52: | Ligne 52: | ||
| IN, FOR, TO, IF EXISTS, IF NOT EXISTS | IN, FOR, TO, IF EXISTS, IF NOT EXISTS | ||
| - | ==== Arguments, identifiers and variables ==== | + | ==== Arguments, identifiants et variables ==== |
| - | Arguments are usually moodle object identifiers, terminal values or eventually global variables, for finding or setting values. the nature of the argument will vary across the syntax, and refers usually to the most common or trivial object type that is expected in the syntax. | + | Les arguments sont le plus souvent des identifiants d'objets moodle, des valeurs littérales terminales (qui s'expriment telle qu'écrites) ou éventuellement des appels à des variables globales ^permettant d'obtenir des "valeurs". La nature et la signification de la valeur peut varier au fil de l'expression, mais se référera toujours à la donnée la plus "logiquement" attendue à cet endroit de la "phase". |
| - | F.E., for en enrolment syntax: | + | Par exemple, pour une instruction d'inscription, l'expression : |
| ENROL id:33 IN id:3 AS shortname:student USING manual | ENROL id:33 IN id:3 AS shortname:student USING manual | ||
| - | shows 4 attributes that are naturally refering to (successively) a user, a course, a role and an enrol method. | + | montre 4 attributs qui se réfèrent (successivement) à un Utilisateur, un Cours, un Role et une méthode d'inscription. |
| - | In case the expression have some possible ambiguity, additional keywords will be used to discriminate possible cases. | + | Dans le cas où une commande viendrait à créer des ambiguités, la syntaxe devra comporter des "adverbes" propres à lever cette ambiguité. |
| - | === Identifiers === | + | === Identifiants === |
| - | when the syntax requires to identify an existing object, and this object may be identified by several information, we will use an explicit field discriminator and value couple, f.e. for a user, there are usually 4 admitted possible identifiers as primary id, username, idnumber or email. | + | Lorsque l'expression doit identifier un objet déjà existant dans Moodle, et que plusieurs informations permettent d'identifier cet objet, un discriminateur explicite devra être utilisé pour exprimer la valeur, par exemple. pour un utilisateur, il existe actuellement quatre identifiants possibles: l'identifiant numérique primaire de base de données (id), l'identifiant de connexion (username), le numéro d'identification (idnumber) ou l'email. |
| - | Thus the following identifiers are usable when searching for a user : | + | Les expressions suivantes sont donc utilisables pour désigner un utilisateur dans moodle : |
| id:33 | id:33 | ||
| + | |||
| username:johndoe | username:johndoe | ||
| + | |||
| idnumber:JD@35465 | idnumber:JD@35465 | ||
| - | email:john.doe@gmail.com | ||
| - | === Special identifier case : identifier given by a function === | + | email:john.doe@gmail.com |
| - | In some applications, we want an identifier being given by a custom or existing function, depending on some current context. the identifier form will accept the 'func' prefix to identifiy some plugin function to call to get an identifier: | + | === Techniques spéciales d'identification : utiliser une fonction pour obtenir un identifiant === |
| - | Example: | + | Dans certains usages, nous souhaiterions que l'identifiant soit fourni par une fonction existante (ou nouvelle) dans l'API moodle, qui s'exécutera dans le contexte courant du moteur. L'identifiant fera alors figurer le préfixe supplémentaire 'func', suivi d'un identifiant de fonction localisé dans son plugin comme suit : |
| idnumber:func:local_ent_installer@get_teacher_cat_idnumber | idnumber:func:local_ent_installer@get_teacher_cat_idnumber | ||
| - | will invoke the function ''local_ent_installer_get_teacher_cat_idnumber()'' in the plugin ''local_ent_installer' ''locallib.php'' (or by default, ''lib.php'') local library to get the expected identifier. the result of the function will be used as idnumber to find ethe primary identifier of the objet. | + | L'expression ci-dessus invoquera la fonction ''local_ent_installer_get_teacher_cat_idnumber()'' du plugin local ''local_ent_installer'', en allant la chercher dans le fichier ''locallib.php'' ( ou ''lib.php'' par defaut). La fonction devra retourner l'identifiant attendu. Dans l'exemple ci-dessus, la fonction devra retourner le numéro d'identification de l'objet administrable souhaité. |
| - | You cannot pass any parameters to this call, so the identifier must be fully determined using current environment globals such as $USER, $COURSE, etc. to compute the expected identifier. | + | Vous ne pouvez pas passer de paramètres à cet appel, La fonction invoquée devra donc pouvoir fournir la réponse par la seule connaissance du contexte courant, grâce aux variables globales de moodle telles que $USER, $COURSE, etc. |
| - | Here is a sample of an application function that computes the current user's owned category to move a course in: | + | Voici un exemple développé de l'usage d'une telle fonction qui obtient l'identifiant de la catégorie attribuée à un utilisateur lors de la création d'un cours: |
| /** | /** | ||
| Ligne 108: | Ligne 109: | ||
| } | } | ||
| - | Called in a moodlescript stack context, it will compute the category idnumber of the current user, so we can write a moodlescript move instruction as follows, moving the current course to the adequate destination: | + | Appelé dans un contexte d'exécution d'un Moodlescript, elle calculera l'identifiant de catégorie pour l'utilisateur "actuellement détenteur" de la session courante, et nous pourrons écrire l'instruction de script suivante qui déplacera le cours "courant" dans la destination souhaitée pour l'utilisateur courant (celui au nom duquel le moteur de script est exécuté): |
| MOVE COURSE current TO idnumber:func:local_ent_installer@get_teacher_cat_idnumber | MOVE COURSE current TO idnumber:func:local_ent_installer@get_teacher_cat_idnumber | ||
| - | === Literal Argument === | + | Lire plus loin pour la notion de contexte courant et le méta-identifieur "current". |
| - | Literal arguments are simple words or strings. There is at the moment a restriction on syntax as strings are not specifically delimited (or only delimited by keywords). So strings should not contain keywords expressions. this is likely why we chose keywords in strict uppercase, to minimize syntactic collision with literal usual strings. | + | === Arguments littéraux === |
| + | |||
| + | Les arguments littéraux sont des mots simples ou des chaines de caractère. Dans la version actuelle du moteur, les chaînes ne sont pas délimitée syntaxiquement autrement que par la survenue d'un mot-clef attendu de l'expression. La conséquence est qu'il faudra éviter d'utiliser des littéraux qui utilisent les mots clefs du Moodlescript. C'est une des raisons principales pour laquelle nous avons décidé de forcer l'expression en majuscules de ces mots clefs, car cela diminue le risque de collision avec du texte usuel. | ||
| === Variables === | === Variables === | ||
| - | We may need to inject some environmental values in the script to replace some non terminal placeholders. An execution stack can be fed at launch time with a global context data stub that will be merged with each instruction local context (adding or overriding values). Global context variables can be placed whereever in script statements or attribute lists using the Moodle common SQL named variable form: | + | Nous aurons probablement à injecter dans le script des valeurs provenant de variables contextuelles. Pour cela nous mettrons en place des symboles "non terminaux" qui seront remplacés par leur valeur à l'exécution. La pile d'exécution d'un script peut être chargée au départ avec un contexte global de données qui sera abondé au contexte local qu'utilise une instruction pendant son exécution (le contexte local lui ajoutant ou surchargeant des valeurs). Ces valriables peuvent être placées n'importe où dans la syntaxe, en respectant la forme typique des arguments SQL dans une requête au format Moodle : |
| :varname | :varname | ||
| - | To be valid, the placeholder expression MUST have at least one space character before it. | + | Pour être reconaissable, l'appel à la variable DOIT être précédée par au moins un espace. |
| - | You may obtain a list of the available variables in the stack logger using the following instruction: | + | Une liste complète des variables de contexte disponibles pour les instructions peut être visualisée dans la trace d'exécution par l'instruction spéciale : |
| LIST GLOBALS | LIST GLOBALS | ||
| - | this will output, e.g. in the admin tool console, giving the console environment preset variables: | + | Ceci affichera, par ex. dans la console Moodlescript des outils d'administration : |
| > GLOBAL CONTEXT | > GLOBAL CONTEXT | ||
| Ligne 136: | Ligne 139: | ||
| > siteshortname: DEV31 | > siteshortname: DEV31 | ||
| - | Any local invocation of a MoodleScript stack may run the stack with his own global environment variable set, to serve some specific component scoped scripting needs. | + | //Usage en intégration : // |
| - | ==== Special keywords (metas) ==== | + | Toute invocation d'une pile d'exécution MoodleScript peut être chargée avec un contexte d'entrée de départ, permettant à tout plugin d'y injecter le contexte dont il a besoin pour l'exécution de ses propres scriptlets. |
| + | |||
| + | ==== Mots-clefs spéciaux (metas) ==== | ||
| ==='current'=== | ==='current'=== | ||
| - | 'current' is a special keyword in place of an expected identifier that will resolve into the nearest current object in the executing environment. F.e, if the expected object is a user identifier, current will resolve to $USER->id. If 'current' addresses a course identifier, it wil usually resolve as $COURSE->id, unless another course id is given to the execution stack by the global context (for plugin developers). | + | 'current' est un mot-clef spécial qui se substitue en lieu et place d'un identifiant d'objet et qui se résoudra par l'objet du type attendu le plus "proche" dans l'environnement d'exécution. Par exmple, si l'identifiant attendu à cet emplacement est un identifiant d'un utilisateur, alors 'current' désignera le plus souvent $USER->id. Si 'current' désigne un identifiant de cours, alors il se résoudra le plus souvent comme $COURSE->id. En général, l'exécution d'une création d'un objet imposera la valeur courante du "dernier identifiant connu" par la pile d'exécution, afin que les instructions suivantes puissent naturellement le réutiliser. Ce concept du "dernier objet connu" par le contexte sous-tendra toute la programmation interne des commandes du Moodlescript. |
| - | The use of current will simplify scripts run within a known context, by using shorten expressions: | + | L'utilisation du mot clef 'current' simplifie la compréhension de scripts qui se déroulent dans un contexte connu, en raccourcissant les instructions : |
| ADD ENROL METHOD guest TO current | ADD ENROL METHOD guest TO current | ||
| - | For adding an enrolment method to the current course. | + | Pour ajouter la méthode d'inscription autorisant l'accès des invités dans le dernier cours connu par le contexte. |
| ENROL current INTO current AS student | ENROL current INTO current AS student | ||
| - | For enrolling the current user (the $USER being executing the script) into the current course. | + | Pour inscrire le dernier utilisateur connu (en général l'utilisateur $USER pour lequel le script est exécuté) dans le cours courant. (dernier cours créé, dernier cours mis à jour, etc.) |
| - | ==='last' or 'first'=== | + | ==='last' ou 'first'=== |
| - | this usually addresses the first available or last available item in the current syntax context. this is used f.e. for blocks location in a region, but might also address any object locaton being sorted with a sortorder attribute. | + | Ceci désignera généralement le premier ou dernier objet connu dans le contexte, lorsque la valeur associée au mot clef désigne un ensemble. Il est actuellement expérimentalement utilisé pour trouver la première zone de blocs disponible dans un format de cours, et sera étendu à d'autre usages où l'intérrogation d'une liste ordonnée d'objets est souhaitable. |
| ==='runtime'=== | ==='runtime'=== | ||
| - | Usually identifiers and variable can be evaluated at parse time or at check time, because they are litterals in the script, or they come from some input or global context. But this is not true in all cases. Lets take an example: | + | Par défaut, les identifiants et les variables sont évaluées au moment de la compilation du script ou sa validation. car les valeurs sont soit statiques (littéraux), soit proviennent de valeurs chargées //a priori// dans le contexte d'exécution. Mais ce n'est pas toujours le cas. Prenons un exemple : |
| - | In the following scriptlet: | + | Dans le sriptlet suivant : |
| - | ADD CATEGORY "New category" TO idnumber:EXISTINGCAT HAVING | + | ADD CATEGORY "Nouvelle catégorie" TO idnumber:PARENTE HAVING |
| - | idnumber: NEWCAT | + | idnumber: NOUVELLE |
| - | MOVE COURSE idnumber:SOMECOURSE TO idnumber:NEWCAT | + | MOVE COURSE idnumber:UNCOURS TO idnumber:NOUVELLE |
| - | We run into an issue because at parse time or at check time, NEWCAT category is not yet created. Thus we must tell the engine that in the second statement, we need the engine waiting the latest moment to evaulate the identifier to move the course in. | + | Il y a de manière évidente un problème à la compilation ou à la validation, car la catégorie désignée par NOUVELLE n'est pas encore créée. Nous devons donc indiquer à la deuxième instruction qu'il faudra attendre lors de l'exécution pour résoudre l'identifiant de la catégorie où le cours doit être déplacé. |
| - | This can be done by the special keywork runtime: and we'll rewrite the scriplet as follows: | + | Ceci peut être fait en ajoutant le préfixe spécial 'runtime:' et nous réécrirons le script comme suit : |
| - | ADD CATEGORY "New category" TO idnumber:EXISTINGCAT HAVING | + | ADD CATEGORY "Nouvelle catégorie" TO idnumber:PARENTE HAVING |
| idnumber: NEWCAT | idnumber: NEWCAT | ||
| - | MOVE COURSE idnumber:SOMECOURSE TO runtime:idnumber:NEWCAT | + | MOVE COURSE idnumber:UNCOURS TO runtime:idnumber:NOUVELLE |
| - | Using the runtime: special keyword will prevent the parser to evaluate and resolve the identifier, and will store it's initial definition in the handler class. The handler will also NOT try to resolve it at check time, as check time only checks the conditions of execution of all the statements without executing them. At real execution time, the identifier will be resolved to get it's definitive actual value. | + | En utlisant le mot-clef 'runtime:' nous empêchons l'interpéteur syntaxique de résoudre cette valeur, et stockons sa définition initiale (sa référence à remplacer). The handler will also NOT try to resolve it at check time, as check time only checks the conditions of execution of all the statements without executing them. At real execution time, the identifier will be resolved to get it's definitive actual value. |
| Note that 'runtime' variables may raise a real error situation that cannot be recovered or anticipated by the engine and may terminate in a tecnhical failure of the script and the calling process. | Note that 'runtime' variables may raise a real error situation that cannot be recovered or anticipated by the engine and may terminate in a tecnhical failure of the script and the calling process. | ||
| [[:local:moodlescript|Revenir à l'index du composant]] | [[:local:moodlescript|Revenir à l'index du composant]] | ||
local/moodlescript/syntaxspecification.1553601977.txt.gz · Dernière modification: 2024/04/04 15:52 (modification externe)
