Pour démarrer

Le bac à sable Scheme

Le bac à sable (sandbox en anglais) est un moyen pratique de faire des tests. Il s’agit d’une invite interactive, ou Read-Eval-Print-Loop : on saisit du code Scheme, il est exécuté au fur et à mesure, et le résultat est affiché. On peut le voir comme une calculatrice.

Pour lancer le bac à sable, il faut ouvrir un terminal. Les utilisateurs de GNU/Linux trouveront bien. Sous macOS, lancer l’application Terminal. Sous Windows, se placer dans un dossier quelconque dans l’explorateur de fichiers et sélectionner Windows PowerShell dans le menu Fichier.

Dans le terminal, exécuter la commande  :

/chemin/complet/vers/lilypond-x.y.z/bin/lilypond scheme-sandbox

ou bien sous Windows :

C:\chemin\complet\vers\lilypond-x.y.z\bin\lilypond scheme-sandbox

Quel que soit votre système, il faut remplacer le chemin par le chemin complet vers le dossier où vous avez placé LilyPond lorsque vous l’avez installé. (Si vous l’avez obtenu à travers un gestionnaire de paquets, ou bien l’avez mis manuellement dans votre variable PATH, vous pouvez utiliser simplement lilypond scheme-sandbox.)

En exécutant cette commande, vous devriez obtenir un écran comme celui-ci :

GNU LilyPond 2.24.1 (running Guile 2.2)
Traitement de « /share/lilypond/2.24.1/ly/scheme-sandbox.ly »
Analyse...
GNU Guile 2.2.7
Copyright (C) 1995-2019 Free Software Foundation, Inc.

Guile comes with ABSOLUTELY NO WARRANTY; for details type `,show w'.
This program is free software, and you are welcome to redistribute it
under certain conditions; type `,show c' for details.

Enter `,help' for help.
scheme@(#{ g101}#)>

La ligne scheme@... nous indique que Guile est là, prêt à nous servir. En saisissant un extrait de code, il est évalué. Commençons par le plus simple, un nombre.

guile> 42
42

À nouveau, le principe est similaire à une calculette : 42 s’évalue bien à 42. Écrivons maintenant un calcul (la syntaxe sera expliquée bientôt)  :

guile> (+ 42 5)
47

Ici, on a effectué l’addition 42 + 5, qui donne bien 47.

Vous pouvez suivre ce tutoriel en copiant les exemples de code dans le bac à sable et en observant ce qui se passe avec des variantes de ces programmes. Dans la suite de ce tutoriel, le signe « ⇒ » est utilisé pour donner la valeur d’une expression. Mettons qu’il soit écrit :

(+ 42 5)
⇒ 47

Cela signifie qu’avec le code (+ 42 5), vous obtiendrez le résultat 47. En particulier, pour tester vous-même, vous pouvez taper (+ 42 5) dans l’interpréteur interactif, et il vous répondra 47. Notez que cette convention est également utilisée dans les manuels de Guile.

Pour quitter le bac à sable, entrez (quit), ou tapez plus simplement Control-D.

Pour finir, mentionnons un détail que vous avez pu trouver ennuyeux si vous avez déjà commencé à taper les exemples ci-dessus dans le bac à sable. Si vous essayez de supprimer un caractère, cela peut ne pas fonctionner et afficher des caractères étranges. Il est possible d’y remédier en installant le programme rlwrap et en entrant dans le bac à sable avec rlwrap ...lilypond scheme-sandbox au lieu de simplement ...lilypond scheme-sandbox. Sous GNU/Linux, rlwrap est probablement dans les paquets de votre distribution. Sous macOS, il se trouve dans Homebrew ou MacPorts. Sous Windows, si vous en avez le courage, vous pouvez sans doute l’installer à travers Cygwin (débutants s’abstenir).

Insertion de code Scheme dans un fichier LilyPond

Quasiment partout dans le code d’une partition, on peut passer en Scheme à l’aide d’un croisillon (caractère #). La lecture s’arrête dès qu’une expression Scheme complète est terminée. Les exemples suivants seront familiers :

#(set-global-staff-size 18)

\markup \vspace #5

\shape #'((0 . 0) (0.1 . 0.3) (0.1 . 0.5) (0 . 1.0)) Slur

Scheme est souvent utilisé pour saisir des valeurs, comme le nombre 5 pour \markup \vspace, ou bien la liste des décalages passée à \shape. Si on saisit ces valeurs telles quelles, elles se perdent le plus souvent dans la nature, contrairement au bac à sable qui les affiche. Par exemple, le fichier LilyPond suivant ne produit ni sortie graphique ni message dans la console.

#'((0 . 0) (0.1 . 0.3) (0.1 . 0.5) (0 . 1.0))

On peut provoquer l’affichage d’une valeur dans le fichier journal à l’aide de la fonction display (admettez pour l’instant la syntaxe, qui sera décortiquée plus tard)  :

#(display '((0 . 0) (0.1 . 0.3) (0.1 . 0.5) (0 . 1.0)))

À l’intérieur d’une expression Scheme, il existe la possibilité pratique d’insérer une partie en syntaxe LilyPond, entourée par les délimiteurs #{ et #}. Par exemple  :

#(skip-of-length #{ { c'8 d' e' f' e' d' } #})

Commentaires

En LilyPond, les commentaires commencent par un signe % et courent jusqu’à la fin d’une ligne. La syntaxe Scheme est légèrement différente, avec le caractère ;. Le principe reste le même : les commentaires permettent d’expliquer le code source pour le lecteur humain. Ils sont totalement ignorés par l’interpréteur.

; Ceci est un commentaire. Il n'a aucun effet.
42.0 ; Un autre commentaire, après une ligne de code.

Il existe également une syntaxe de commentaires multilignes, équivalente à %{ et %} en LilyPond. Les délimiteurs sont #! et !#.

#!/usr/bin/guile
Nous voici dans un commentaire multiligne. Les utilisateurs
de systèmes UNIX (comme GNU/Linux et macOS) auront remarqué
que la syntaxe de ces commentaires est adaptée aux shebangs.
Si vous ne savez pas ce que c'est, cela n'a aucune importance.
!#

Littéraux

Cette partie traite de l’écriture des valeurs courantes, que tout utilisateur de LilyPond rencontre régulièrement.

Commençons par le commencement : les nombres. Ils s’écrivent en Scheme comme autre part :

5
⇒ 5
-10
⇒ -10

Les nombres décimaux s’écrivent avec un point (notation anglo-saxonne).

5.3
⇒ 5.3
-10.42
⇒ -10.42

Quant aux chaînes de caractères, c’est-à-dire des extraits de texte comme suites de caractères, elles se saisissent entre guillemets doubles.

"Sonata IV"
⇒ "Sonata IV"

Elles peuvent contenir des retours à la ligne.

"J'entends le loup, le renard et la belette,
J'entends le loup et le renard chanter."
⇒ "J'entends le loup, le renard et la belette,
J'entends le loup et le renard chanter."

On peut également indiquer les retours à la ligne à l’aide de \n. Les deux formes sont strictement équivalentes.

"J'entends le loup, le renard et la belette,\nJ'entends le loup et le renard chanter."
⇒ "J'entends le loup, le renard et la belette,
J'entends le loup et le renard chanter."

Pour écrire un guillemet dans la chaîne, il faut le faire précéder d’un antislash afin qu’il ne soit pas interprété comme la fin de la chaîne.

"Rondo \"alla turca\""
⇒ "Rondo \"alla turca\""

Pour afficher une chaîne, il suffit d’appeler dessus la fonction display.

(display "Rondo \"alla turca\"\n")
⊨ Rondo "alla turca"

C’est l’occasion d’introduire une autre convention pour ce tutoriel : le symbole « ⊨ » signifie « affiche ». Ainsi, le code ci-dessus affiche Rondo "alla turca" à l’écran. Attention à la différence entre afficher une valeur avec display (symbole « ⊨ ») et sans display (symbole « ⇒ ») dans l’invite interactive Guile. En dépit des apparences, "Rondo" et (display "Rondo") ne font pas du tout la même chose. Lorsque vous écrivez "Rondo", cela donne la chaîne de caractère « Rondo ». Vous pouvez en faire quelque chose, par exemple la donner à LilyPond  :

\header {
  title = "Rondo"
}

En revanche, avec display, vous donnez l’ordre d’afficher à l’écran la valeur de la chaîne. Une fois l’ordre exécuté, display ne vous donne pas un objet que vous pouvez manipuler. display sert juste à afficher, ce qui est pratique pour le débogage.

Il faut bien faire la différence entre la manière dont on écrit une chaîne et la manière dont elle s’affiche. Une chaîne de caractères n’est rien qu’une suite de caractères. La chaîne "\"\"\n" ne contient que trois caractères seulement, à savoir deux guillemets et un retour à la ligne. S’il faut mettre ces antislashs, c’est simplement pour éviter une confusion dans la lecture de la chaîne. Cependant, display nous confirme le contenu de la chaîne :

(display "\"\"\n")
⊨ ""

Notez que LilyPond accepte pour les nombres et chaînes de caractères une syntaxe proche de celle de Scheme. Ainsi, les codes suivants sont équivalents  :

\override TextScript.Y-offset = 5.2
\override TextScript.Y-offset = #5.2

De même, on a l’équivalence entre  :

title = #"Rondo"
title = "Rondo"
title = Rondo

(Bien entendu, la troisième syntaxe ne peut fonctionner qu’avec un seul mot, et il faut des guillemets pour une chaîne de caractères contenant des espaces.)

Définition de variables

Les utilisateurs de LilyPond savent que leur code sera bien plus simple s’ils l’organisent à l’aide de variables.

clarinette = \relative {
  ...
}

{ \clarinette }
{ \transpose c d \clarinette }

L’avantage est double. D’une part, il est possible de se servir de la valeur en plusieurs endroits distincts sans la recopier. D’autre part, même pour un seul usage, définir une variable rend le code plus compréhensible et donc plus facile à modifier plus tard.

En Scheme, les variables se définissent à l’aide de la syntaxe :

(define nom valeur)

Par exemple, pour affecter à x la valeur 5, on écrira :

(define x 5)

Par la suite, il suffit d’écrire le nom de la variable, qui est automatiquement remplacé par sa valeur (alors que LilyPond a besoin d’un antislash).

(define x 5)
(display x)
⊨ 5

Si le nom d’une variable contient plusieurs mots, la convention est de les séparer par des tirets.

(define ma-variable 44)

De manière peut-être surprenante, les noms de variables peuvent contenir certains caractères spéciaux. Ces caractères sont notamment acceptés : +, -, *, /, ?, !, =, &, |, @. Quelques caractères ne sont pas acceptés, comme les parenthèses et guillemets. (Les règles précises sur la formation des noms de variables sont légèrement complexes, et inutiles à connaître dans le détail.)

(define x+|^ 34)
(display x+|^)
⊨ 34