LilyPond — Extension des fonctionnalités

1.1.1 Le bac à sable de Scheme

L’installation de LilyPond comprend l’implémentation Guile de Scheme. Tous les paquetages de LilyPond disposent d’un « bac à sable » Scheme, accessible par la commande :

lilypond Scheme-sandbox

Une fois le bac à sable actif, vous obtiendrez l’invite :

guile>

Vous pouvez dès à présent saisir des expressions Scheme pour vous exercer. Si vous souhaitez pouvoir utiliser la bibliothèque GNU readline, qui offre une ligne de commande plus élaborée, consultez les informations contenues dans le fichier ly/Scheme-sandbox.ly. La bibliothèque readline, dans la mesure où elle est habituellement activée dans vos sessions Guile, devrait être effective y compris dans le bac à sable.

1.1.2 Scheme et les variables

Une variable Scheme peut contenir n’importe quelle valeur valide en Scheme, y compris une procédure Scheme.

Une variable Scheme se crée avec la fonction define :

guile> (define a 2)
guile>

L’évaluation d’une variable Scheme se réalise en saisissant le nom de cette variable à l’invite de Guile :

guile> a
2
guile>

Une variable Scheme s’affiche à l’écran à l’aide de la fonction display :

guile> (display a)
2guile>

Vous aurez remarqué que la valeur 2 et l’invite guile apparaissent sur une même ligne. On peut améliorer la présentation à l’aide de la procédure newline ou bien en affichant un caractère « retour chariot ».

guile> (display a)(newline)
2
guile> (display a)(display "\n")
2
guile>

Après avoir créé une variable, vous pouvez en modifier la valeur grâce à un set! :

guile> (set! a 12345)
guile> a
12345
guile>

Vous quitterez proprement le bac à sable à l’aide de l’instruction quit :

guile> (quit)

1.1.3 Types de données Scheme simples

L’un des concepts de base de tout langage est la saisie de données, qu’il s’agisse de nombres, de chaînes de caractères, de listes, etc. Voici les différents types de données Scheme simples utilisées couramment dans LilyPond.

Booléens

Les valeurs booléennes sont vrai ou faux. En Scheme, ce sera #t pour vrai, et #f pour faux.

Nombres

Les nombres se saisissent le plus communément : 1 est le nombre (entier) un, alors que -1.5 est un nombre à virgule flottante (un nombre non entier).

Chaînes

Les chaînes de caractères sont bornées par des guillemets informatiques :

"ceci est une chaîne"

Une chaîne peut s’étendre sur plusieurs lignes :

"ceci
est
une chaîne"

auquel cas les retours à la ligne seront inclus dans la chaîne.

Un caractère de retour à la ligne peut s’ajouter dans la chaîne, sous la forme d’un \n.

"ceci\nest une\nchaîne multiligne"

Guillemets et obliques inverses dans une chaîne doivent être précédés d’une oblique inverse. La chaîne \a dit "b" se saisit donc

"\\a dit \"b\""

Il existe bien d’autres types de données Scheme, dont nous ne parlerons pas ici. Vous en trouverez une liste exhaustive dans le guide de référence de Guile, à la page https://www.gnu.org/software/guile/docs/docs-1.8/guile-ref/Simple-Data-Types.html.

1.1.4 Types de données Scheme composites

Scheme prend aussi en charge des types de données composites. LilyPond utilise beaucoup les paires, listes, listes associatives et tables de hachage.

guile> (cons 4 5)
(4 . 5)
guile>

guile> '(4 . 5)
(4 . 5)
guile>

guile> (cons #t #f)
(#t . #f)
guile> '("blah-blah" . 3.1415926535)
("blah-blah" . 3.1415926535)
guile>

guile> (define mypair (cons 123 "hello there")
… )
guile> (car mypair)
123
guile> (cdr mypair)
"hello there"
guile>

guile> (list 1 2 3 "abc" 17.5)
(1 2 3 "abc" 17.5)

(1 . (2 . (3 . ("abc" . (17.5 . ())))))

guile> '(17 23 "foo" "bar" "bazzle")
(17 23 "foo" "bar" "bazzle")

guile> (define mon-alist '((1  . "A") (2 . "B") (3 . "C")))
guile> mon-alist
((1 . "A") (2 . "B") (3 . "C"))
guile> (assoc 2 mon-alist)
(2 . "B")
guile> (cdr (assoc 2 mon-alist))
"B"
guile>

guile> (define h (make-hash-table 10))
guile> h
#<hash-table 0/31>
guile> (hashq-set! h 'cle1 "valeur1")
"valeur1"
guile> (hashq-set! h 'key2 "valeur2")
"valeur2"
guile> (hashq-set! h 3 "valeur3")
"valeur3"

guile> (hashq-ref h 3)
"valeur3"
guile> (hashq-ref h 'cle2)
"valeur2"
guile>

guile> (hashq-get-handle h 'cle1)
(cle1 . "valeur1")
guile> (hashq-get-handle h 'zut)
#f
guile>

1.1.5 Scheme et les calculs

Scheme permet aussi d’effectuer des calculs. Il utilise alors un préfixe. Additionner 1 et 2 s’écrira (+ 1 2) et non 1+2 comme on aurait pu s’y attendre.

guile> (+ 1 2)
3

Les calculs peuvent s’imbriquer ; le résultat d’une fonction peut servir pour un autre calcul.

guile> (+ 1 (* 3 4))
13

Ces calculs sont un exemple d’évaluation : une expression telle que (* 3 4) est remplacée par sa valeur, soit 12.

En matière de calcul, Scheme fait la différence entre des nombres entiers ou non. Les calculs sur des nombres entiers seront exacts, alors que s’il s’agit de nombres non entiers, les calculs tiendront compte de la précision mentionnée :

guile> (/ 7 3)
7/3
guile> (/ 7.0 3.0)
2.33333333333333

Lorsque l’interpréteur Scheme rencontre une expression sous forme de liste, le premier élément de cette liste est considéré en tant que procédure qui prendra en argument le restant de la liste. C’est la raison pour laquelle, en Scheme, tous les opérateurs sont en préfixe.

Le fait que le premier élément d’une expression Scheme sous forme de liste ne soit pas un opérateur ou une procédure déclenchera une erreur de la part de l’interpréteur :

guile> (1 2 3)

Backtrace:
In current input:
  52: 0* [1 2 3]

<unnamed port>:52:1: In expression (1 2 3):
<unnamed port>:52:1: Wrong type to apply: 1
ABORT: (misc-error)
guile>

Vous pouvez constater que l’interpréteur a tenté de considérer 1 comme étant un opérateur ou une procédure, ce qu’il n’a pu réaliser. Il a donc renvoyé l’erreur « Wrong type to apply: 1 » (Application d’un type erroné : 1).

C’est pourquoi il est impératif, pour créer une liste, soit d’utiliser l’opérateur consacré (list), soit de faire précéder la liste d’une apostrophe, de telle sorte que l’interpréteur ne tente pas de l’évaluer.

guile> (list 1 2 3)
(1 2 3)
guile> '(1 2 3)
(1 2 3)
guile>

Vous pourrez être confronté à cette erreur lorsque vous intégrerez Scheme à LilyPond.

1.1.6 Scheme et les procédures

Une procédure Scheme est une expression Scheme qui renverra une valeur issue de son exécution. Les procédures Scheme sont capables de manipuler des variables qui ne sont pas définies en leur sein.

(define (nom-fonction argument1 argument2 … argumentn)
 expression-Scheme-qui-donnera-une-valeur-en-retour)

guile> (define (moyenne x y) (/ (+ x y) 2))
guile> moyenne
#<procedure moyenne (x y)>

guile> (moyenne 3 12)
15/2

guile> (define (moins-de-dix? x) (< x 10))
guile> (moins-de-dix? 9)
#t
guile> (moins-de-dix? 15)
#f

guile> (begin (+ 1 2) (- 5 8) (* 2 2))
4

guile> (let ((x 2) (y 3) (z 4)) (display (+ x y)) (display (- z 4))
… (+ (* x y) (/ z x)))
508

1.1.7 Scheme et les conditions

(if expression-test expression-affirmative expression-négative)

guile> (define a 3)
guile> (define b 5)
guile> (if (> a b) "a est plus grand que b" "a n'est pas plus grand que b")
"a n'est pas plus grand que b"

(cond (expression-test-1 expression-résultat-séquence-1)
      (expression-test-2 expression-résultat-séquence-2)
      …
      (expression-test-n expression-résultat-séquence-n))

guile> (define a 6)
guile> (define b 8)
guile> (cond ((< a b) "a est plus petit que b")
…          ((= a b) "a égale b")
…          ((> a b) "a est plus grand que b"))
"a est plus petit que b"

1.2.1 Syntaxe Scheme dans LilyPond

L’installation de LilyPond comprenant l’interpréteur Guile, les fichiers source LilyPond peuvent contenir du Scheme. Vous disposez de plusieurs méthodes pour inclure du Scheme dans vos fichiers LilyPond.

La méthode la plus simple consiste à insérer un hash (le caractère #, improprement appelé dièse) avant l’expression Scheme.

Rappelons-nous qu’un fichier source LilyPond est structuré en jetons et expressions, tout comme le langage humain est structuré en mots et phrases. LilyPond dispose d’un analyseur lexical (appelé lexer) qui sait identifier les jetons – nombres, chaînes, éléments Scheme, hauteurs, etc. – ainsi que d’un analyseur syntaxique (appelé parser). Dès lors que le programme sait quelle règle grammaticale particulière doit s’appliquer, il exécute les consignes qui lui sont associées.

Le recours à un hash pour mettre en exergue du Scheme est tout à fait approprié. Dès qu’il rencontre un #, l’analyseur lexical passe le relais au lecteur Scheme qui va alors déchiffrer l’intégralité de l’expression Scheme – ce peut être un identificateur, une expression bornée par des parenthèses ou bien d’autres choses encore. Une fois cette expression lue, elle est enregistrée en tant que valeur d’un élément grammatical SCM_TOKEN. Puisque l’analyseur syntaxique sait comment traiter ce jeton, il charge Guile d’évaluer l’expression Scheme. Dans la mesure où le parser requiert une lecture en avance de la part du lexer pour prendre une décision, cette distinction entre lecture et évaluation – lexer et parser – révèle toute sa pertinence lorsqu’il s’agit d’exécuter conjointement des expressions LilyPond et des expressions Scheme. C’est la raison pour laquelle nous vous recommandons, dans toute la mesure du possible, d’utiliser un signe hash lorsque vous faites appel à Scheme.

Une autre manière de faire appel à l’interpréteur Scheme à partir de LilyPond consiste à introduire une expression Scheme par un caractère dollar au lieu d’un caractère dièse – un $ au lieu d’un #. En pareil cas, LilyPond évalue le code dès sa lecture par l’analyseur lexical, vérifie le type d’expression Scheme qui en résulte et détermine un type de jeton (l’un des xxx_IDENTIFIER de la grammaire) qui lui correspond, puis en fait une copie qui servira à traiter la valeur de ce jeton. Lorsque la valeur de l’expression est void, autrement dit une valeur Guile *unspecified* (pour non spécifiée), aucune information n’est transmise à l’analyseur grammatical.

C’est, en réalité, la manière dont LilyPond opère lorsque vous rappelez une variable ou une fonction par son nom – au travers d’un \nom –, à la seule différence que sa finalité est déterminée par l’analyseur lexical de LilyPond sans consultation du lecteur Scheme ; le nom de la variable rappelée doit donc être en corrélation avec le mode LilyPond actif à ce moment là.

L’immédiateté de l’opérateur $ peut entraîner des effets indésirables dont nous reparlerons à la rubrique Saisie de variables et Scheme ; aussi est-il préférable d’utiliser un # dès que l’analyseur grammatical le supporte. Dans le cadre d’une expression musicale, une expression qui aura été créée à l’aide d’un # sera interprétée comme étant de la musique. Elle ne sera cependant pas recopiée avant utilisation. Si la structure qui l’abrite devait être réutilisée, un appel expicite à ly:music-deep-copy pourrait être requis.

Les opérateurs $@ et #@ agissent comme des « colleurs de liste » : leur fonction consiste à insérer tous les éléments d’une liste dans le contexte environnant.

Examinons à présent du vrai code Scheme. Nous pouvons définir des procédures Scheme au milieu d’un fichier source LilyPond :

#(define (moyenne a b c) (/ (+ a b c) 3))

Pour mémoire, vous noterez que les commentaires LilyPond (% ou %{…%}) ne peuvent s’utiliser dans du code Scheme, même si celui-ci se trouve au sein d’un fichier LilyPond. Ceci tient au fait que l’expression Scheme est lue par l’interpréteur Guile, et en aucune façon par l’analyseur lexical de LilyPond. Voici comment introduire des commentaires dans votre code Scheme :

; ceci n'est qu'une simple ligne de commentaire

#!
  Ceci constitue un bloc de commentaire (non imbricable)
  dans le style Guile.
  En fait, les Schemeurs les utilisent très rarement,
  et vous n'en trouverez jamais dans le code source
  de LilyPond.
!#

Dans la suite de notre propos, nous partons du principe que les données sont incluses dans un fichier musical, aussi toutes les expressions Scheme seront introduites par un #.

Toutes les expressions Scheme de haut niveau incluses dans un fichier LilyPond peuvent se combiner en une expression Scheme unique à l’aide de la clause begin :

#(begin
  (define foo 0)
  (define bar 1))

1.2.2 Variables LilyPond

Les variables LilyPond sont enregistrées en interne sous la forme de variables Scheme. Ainsi,

douze = 12

est équivalant à

#(define douze 12)

Ceci a pour conséquence que toute variable LilyPond peut être utilisée dans une expression Scheme. Par exemple, nous pourrions dire

vingtQuatre = #(* 2 douze)

ce qui aurait pour conséquence que le nombre 24 sera stocké dans la variable LilyPond (et Scheme) vingtQuatre.

Scheme autorise la modification d’expressions complexes au fil de l’eau, ce que réalise LilyPond dans le cadre des fonctions musicales. Toutefois, lorsqu’une expression musicale est stockée dans une variable plutôt que saisie au fur et à mesure, on s’attend, alors qu’elle est passée à une fonction musicale, à ce que sa valeur originale ne soit en rien modifiée. C’est la raison pour laquelle faire référence à une variable à l’aide d’une oblique inverse – autrement dit saisir \vingtQuatre – aura pour effet que LilyPond créera une copie de la valeur musicale de cette variable aux fins de l’utiliser au sein de l’expression musicale au lieu d’utiliser directement la valeur de cette variable.

Par voie de conséquence, une expression musicale introduite par # ne devrait pas contenir de matériau inexistant auparavant ou bien littéralement recopié, mais plutôt une référence explicite.

Voir aussi

Manuel d’extension : Syntaxe Scheme dans LilyPond.

1.2.3 Débogage de code Scheme

Lorsque l’on débogue de larges portions de code Scheme, il est bien appréciable que soit mise en évidence la ligne du programme à la source même de l’erreur. Lilypond permet la localisation dans les sources pour les erreurs Scheme dès lors d’ezst ajoutée à la ligne de commande l’option -dcompile-Scheme-code. L’ajout d’une ligne #(ly:set-option 'compile-Scheme-code) en tête d’un fichier LilyPond aura le même effet.

Par ailleurs, il est possible d’obtenir encore plus d’informations au sujet de l’erreur grâce à l’option -ddebug-eval – ou une ligne #(debug-enable 'backtrace) dans le fichier. Grâce à ce mode, et dès la survenance d’une erreur, s’affiche en mode verbeux une « trace inverse » contenant des informations sur tous les appels de fonction, ce qui permet de remonter le fil jusqu’àa la pierre d’achoppement.

Problèmes connus et avertissements

En raison d’une limitation dans l’implémentation de Guile, l’option -dcompile-Scheme-code ne permet pas de compiler des fichiers LilyPond comportant au-delà de quelques milliers d’expressions Scheme.

1.2.4 Saisie de variables et Scheme

Le format de saisie prend en charge la notion de variable – ou identificateur. Dans l’exemple suivant, une expression musicale se voit attribuer un identificateur qui portera le nom de traLaLa.

traLaLa = { c'4 d'4 }

Une variable a aussi une portée. Dans l’exemple suivant, le bloc \layout contient une variable traLaLa tout à fait indépendante de l’autre \traLaLa.

traLaLa = { c'4 d'4 }
\layout { traLaLa = 1.0 }

Dans les faits, chaque fichier a un domaine de compétence, et les différents blocs \header, \midi et \layout ont leur propre champ de compétence, imbriqué dans ce domaine principal.

Variables et champs de compétence sont implémentés par le système de modules de Guile. Un module anonyme Scheme est attaché à chacun de ces domaines. Une assertion telle que

traLaLa = { c'4 d'4 }

est convertie, en interne, en une définition Scheme :

(define traLaLa valeur Scheme de '…')

Cela signifie que variables LilyPond et variables Scheme peuvent tout à fait se mélanger. Dans l’exemple suivant, un fragment musical est stocké dans la variable traLaLa puis dupliqué à l’aide de Scheme. Le résultat est alors importé dans un bloc \score au moyen d’une seconde variable twice.

traLaLa = { c'4 d'4 }

#(define newLa (map ly:music-deep-copy
  (list traLaLa traLaLa)))
#(define twice
  (make-sequential-music newLa))

\twice

Cet exemple est particulièrement intéressant. L’assignation n’interviendra qu’une fois que l’analyseur grammatical aura l’assurance que rien du type de \addlyrics ne suit ; il doit donc vérifier ce qui vient après. Le parser lit le # et l’expression Scheme qui le suit sans l’évaluer, de telle sorte qu’il peut procéder à l’assignation, et ensuite exécuter le code Scheme sans problème.

1.2.5 Import de code Scheme dans LilyPond

L’exemple précédent illustre la manière « d’exporter » une expression musicale à partir des saisies et à destination de l’interpréteur Scheme. L’inverse est aussi réalisable : en la plaçant derrière un $, une valeur Scheme sera interprétée comme si elle avait été saisie en syntaxe LilyPond. Au lieu de définir \twice, nous aurions tout aussi bien pu écrire

…
$(make-sequential-music newLa)

Vous pouvez utiliser $ suivi d’une expression Scheme partout où vous auriez utilisé \nom, dès lors que vous aurez assigné à cette expression Scheme le nom de variable nom. La substitution intervenant au niveau de l’analyseur lexical (le lexer), LilyPond ne saurait faire la différence.

Cette manière de procéder comporte cependant un inconvénient au niveau de la temporisation. Si nous avions défini newLa avec un $ plutôt qu’un #, la définition Scheme suivante aurait échoué du fait que traLaLa n’était pas encore défini. Pour plus d’information quant au problème de synchronisation, voir la rubrique Syntaxe Scheme dans LilyPond.

Une autre façon de procéder serait de recourir aux « colleurs de liste » $@ et #@ dont la fonction est d’insérer les éléments d’une liste dans le contexte environnant. Grâce à ces opérateurs, la dernière partie de notre fonction pourrait s’écrire ainsi :

…
{ #@newLa }

Ici, chaque élément de la liste stockée dans newLa est pris à son tour et inséré dans la liste, tout comme si nous avions écrit

{ #(premier newLa) #(deuxième newLa) }

Dans ces deux dernières formes, le code Scheme est évalué alors même que le code initial est en cours de traitement, que ce soit par le lexer ou par le parser. Si le code Scheme ne doit être exécuté que plus tard, consultez la rubrique Fonctions Scheme fantômes, ou stockez-le dans une procédure comme ici :

#(define (nopc)
  (ly:set-option 'point-and-click #f))

…
#(nopc)
{ c'4 }

1.2.6 Propriétés des objets

Les propriétés des objets sont stockées dans LilyPond sous la forme d’enchaînements de listes associatives, autrement dit des listes de listes associatives. Une propriété se détermine par l’ajout de valeurs en début de liste de cette propriété. Les caractéristiques d’une propriété s’ajustent donc à la lecture des différentes valeurs des listes associatives.

La modification d’une valeur pour une propriété donnée requiert l’assignation d’une valeur de la liste associative, tant pour la clé que pour la valeur associée. Voici comment procéder selon la syntaxe de LilyPond :

\override Stem.thickness = #2.6

Cette instruction ajuste l’apparence des hampes. Une entrée '(thickness . 2.6) de la alist est ajoutée à la liste de la propriété de l’objet Stem. thickness devant s’exprimer en unité d’épaisseur de ligne, les hampes auront donc une épaisseur de 2,6 lignes de portée, et à peu près le double de leur épaisseur normale. Afin de faire la distinction entre les variables que vous définissez au fil de vos fichiers – tel le vingtQuatre que nous avons vu plus haut – et les variables internes des objets, nous parlerons de « propriétés » pour ces dernières, et de « variables » pour les autres. Ainsi, l’objet hampe possède une propriété thickness, alors que vingtQuatre est une variable.

1.2.7 Variables LilyPond composites

\override TextScript.extra-offset = #'(1 . 2)

1.2.8 Représentation interne de la musique

Dans les entrailles du programme, la musique se présente comme une liste Scheme. Cette liste comporte les différents éléments qui affecteront la sortie imprimable. L’analyse grammaticale (l’opération parsing) est le processus chargé de convertir la musique représentée par le code LilyPond en présentation interne Scheme.

L’analyse d’une expression musicale se traduit par un jeu d’objets musicaux en Scheme. Une objet musical est déterminé par le temps qu’il occupe, que l’on appelle durée. Les durées s’expriment par des nombres rationnels représentant la longueur d’un objet musical par rapport à la ronde.

Un objet musical dispose de trois types :

• un nom de musique : toute expression musicale a un nom. Par exemple, une note amène à un NoteEvent, un \simultaneous à un SimultaneousMusic. Une liste exhaustive des différentes expressions est disponible dans la référence des propriétés internes, à la rubrique Music expressions.
• un « type » ou interface : tout nom de musique dispose de plusieurs types ou interfaces. Ainsi, une note est tout à la fois un event, un note-event, un rhythmic-event et un melodic-event. Les différentes classes musicales sont répertoriées à la rubrique Music classes de la référence des propriétés internes.
• un objet C++ : tout objet musical est représenté par un objet de la classe C++ Music.

L’information réelle d’une expression musicale est enregistrée sous forme de propriétés. Par exemple, un NoteEvent dispose des propriétés pitch et duration, respectivement chargées de stocker la hauteur et la durée de cette note. Les différentes propriétés sont répertoriées à la rubrique Music properties de la référence des propriétés internes.

Une expression composite est un objet musical dont les propriétés contiennent d’autres objets musicaux. S’il s’agit d’une liste d’objets, elle sera stockée dans la propriété elements d’un objet musical ; s’il n’y a qu’un seul objet « enfant », il sera stocké dans la propriété element. Ainsi, par exemple, les enfants de SequentialMusic iront dans elements, alors que l’argument unique de GraceMusic ira dans element. De même, le corps d’une répétition ira dans la propriété element d’un VoltaRepeatedMusic, les alternatives quant à elles dans la propriété elements.

1.3.1 Première approche (exemple)

1. La problématique

   Partant du code suivant, l’indication « espressivo » (les deux petits soufflets) devrait être plus large, mais pas gagner en hauteur.

   { f'\espressivo }
   

   

2. Les solutions envisageables
   1. créer un nouveau stencil
   2. redimensionner le stencil par défaut sur l’axe des X
3. Réflexions sur l’Thoughts about previous item

   La solution A est réalisable, mais demandera plus d’effort de codage. Quant à la solution B, bien que moins exigeante, elle a le désavantage de ne pas donner de résultats acceptables dans tous les cas – mais on ne le saura pas avant d’avoir essayé.

   ⇒ opter pour la solution B.

4. Codage
   • Si ’lon veut manipuler le stencil par défaut, il faut s’informer à son sujet.

     L’indication d’espressivo est un objet graphique Script. En consultant la référence des propriétés internes, on lit

     ‘stencil’ (stencil):
          ‘ly:script-interface::print’
     

     Voyons voir si tout cela marche. Pour être assurés d’affecter le bon grob, nous utiliserons des couleurs. Il existe une fonction prédéfinie à cet effet – voir Scheme functions.

     -- Fonction: stencil-with-color stencil couleur
         Renvoie une version modifiée du stencil donné, teint
         dans la couleur donnée. Voir ‘normalize-color’ pour
         les formats de couleur possibles.
     

     -- Fonction: normalize-color couleur
         Convertit une couleur donnée dans l'un des formats pris en
         charge en une liste de 4 nombres : R, G, B, A. Les formats
         possibles sont : une liste de 4 nombres ; une liste de 3
         nombres (transparence par défaut à 1.0) ; une chaîne CSS
         (nom de couleur, ou “#RRGGBB”, “#RRGGBBAA”, “#RGB” ou
         “#RGBA”).
     

     Utilisant un nom de couleur (‘red’), nous obtenons le code suivant :

     colorDefaultStencil =
     \once \override Script.stencil =
       % `lambda` starts a procedure; its argument is `grob`.
       #(lambda (grob)
          ;; With `let`, local variables are defined.
          (let ((stil (ly:script-interface::print grob)))
            ;; The procedure returns the colored default stencil.
            (stencil-with-color stil red)))
     
     { \colorDefaultStencil f'\espressivo }
     

     

     Parfait, cela fonctionne.

   • Ce type d’opération – prendre un stencil ou une propriété par défaut et en retourner une version modifiée – est très courante, et LilyPond dispose d’une fonction dédiée à cet effet : grob-transformer.

     -- Function: grob-transformer property func
         Create an override value good for applying FUNC to either
         pure or unpure values.  FUNC is called with the
         respective grob as first argument and the default value
         (after resolving all callbacks) as the second.
     

     Laissons-nous tenter. Les concepts de pur ou impur seront vus plus avant, dans Conteneurs requalifiants ; ignorons-les pour l’instant.

     colorDefaultStencil =
     \once \override Script.stencil =
       #(grob-transformer 'stencil
          (lambda (grob orig)
            (stencil-with-color orig red)))
     
     { \colorDefaultStencil f'\espressivo }
     

     

     Excellent !

   • Pour obtenir un stencil redimensionné, il faut utiliser

     -- Function: ly:stencil-scale stil x y
         Scale stencil STIL using the horizontal and vertical
         scaling factors X and optional Y (defaulting to X).
         Negative values flip or mirror STIL without changing its
         origin; this may result in collisions unless it is
         repositioned.
     

     à partir du même chapitre de la référence des propriétés internes.

     Résultat :

     scaleColorDefaultStencil =
     \once \override Script.stencil =
       #(grob-transformer 'stencil
          (lambda (grob orig)
            (stencil-with-color
             (ly:stencil-scale
              orig
              ;; 1 is the neutral element with ly:stencil-scale,
              ;; i.e., scaling with '1 1' (for x- and y-axis)
              ;; returns a visibly unchanged stencil.
              2 1)
             red)))
     
     { \scaleColorDefaultStencil f'\espressivo }
     

     

     Mis à part la couleur, cela ressemble fort à ce que l’on voulait.

   • Certains problèmes subsistent cependant, comme le montre l’exemple suivant :

     { \scaleColorDefaultStencil f'_\espressivo ^\fermata }
     

     

     • − Le point d’orgue est redimensionné lui aussi.
     • − Devoir taper la commande avant les notes et \espressivo après ces notes n’est pas pratique.

     Solution aux deux inconvénients : utilisons \tweak !

     {
       f'-\tweak stencil
           #(grob-transformer 'stencil
              (lambda (grob orig)
                (stencil-with-color
                 (ly:stencil-scale orig 2 1)
                 red)))
           _\espressivo
         ^\fermata
     }
     

     

     Cela fait ce qui est demandé, mais autant de saisie n’est pas la panacée ; pourquoi ne pas définir une variable que l’on utiliserait dans le tweak ? Après un peu de copier coller, nous obtenons

     #(define longer-script
        (grob-transformer 'stencil
          (lambda (grob orig)
            (stencil-with-color
             (ly:stencil-scale orig 2 1)
             red))))
     
     {
       f'-\tweak stencil #longer-script _\espressivo
         ^\fermata
     }
     

     

     Cela fonctionne correctement, bien que les valeurs soient codées en dur et que taper -\tweak stencil #longer-script sans arrêt soit rébarbatif.

     Pour régler cela, commençons par introduire des variables dans longer-script pour les valeurs de redimensionnement x et y.

     #(define (longer-script x y)
        (grob-transformer 'stencil
          (lambda (grob orig)
            (stencil-with-color
             (ly:stencil-scale orig x y)
             red))))
     

     Ensuite, et pour réduire la frappe, nous définissons une fonction événementielle – voir Fonctions événementielles. Les éléments du premier groupe entre parenthèses – (x-val y-val) – sont les variables de la fonction, et les éléments du second groupe entre parenthèses sont les types respectifs de variable (on cherche deux fois un nombre – voir Types de prédicat prédéfinis pour les possibilités de test).

     scaleEspr =
     #(define-event-function (x-val y-val) (number? number?)
       #{
         \tweak stencil #(longer-script x-val y-val)
         \espressivo
       #})
     
     { f'_\scaleEspr 2 1
          ^\fermata }
     

     

     Cela fonctionne à merveille ! Notez l’utilisation de #{ … #} : dans cette construction Scheme, il est tout à fait possible d’utiliser la syntaxe de LilyPond, et les arguments de la fonction, tel que x-val, sont correctement expansés – voir Blocs de code LilyPond.

5. Le code finalisé

   Pour terminer, faisons un peu de ménage.

   • − Nous souhaitons redimensionner uniquement dans l’horizontalité ; nous pouvons donc forcer le redimensionnement vertical dans la fonction événementielle.
   • − Supprimons la couleur.

   Ceci nous amène au code suivant.

   #(define (longer-script x y)
      (grob-transformer 'stencil
        (lambda (grob orig)
          (ly:stencil-scale orig x y))))
   
   longEspressivo =
   #(define-event-function (x-val) (number?)
     #{
       \tweak stencil #(longer-script x-val 1)
       \espressivo
     #})
   
   { f'^\longEspressivo #2 _\fermata }
   

   

   Voilà !

   Le principal bénéfice à l’utilisation de grob-transformer réside dans le fait que nul n’est besoin de connaître le nom exact de la fonction de stencil. Dans l’exemple qui suit, nous pivotons une liaison et une ligature de 90 degrés – que les fonction de stencil s’appellent respectivement ly:slur::print et ly:beam::print n’est d’aucun intérêt en l’occurrence.

   #(define rotate-90
      (grob-transformer 'stencil
        (lambda (grob orig)
          (ly:stencil-rotate orig 90 0 0))))
   
   { f'8( g')
     f'8-\tweak stencil #rotate-90 ( g')
     f'8[ g']
     f'8-\tweak stencil #rotate-90 [ g'] }
   

   

1.3.2 Affichage d’expressions musicales

Lorsque l’on veut écrire une fonction musicale, il est intéressant d’examiner comment une expression musicale est représentée en interne. Vous disposez à cet effet de la fonction musicale \displayMusic.

{
  \displayMusic { c'4\f }
}

affichera

(make-music
  'SequentialMusic
  'elements
  (list (make-music
          'NoteEvent
          'articulations
          (list (make-music
                  'AbsoluteDynamicEvent
                  'text
                  "f"))
          'duration
          (ly:make-duration 2 0 1/1)
          'pitch
          (ly:make-pitch 0 0 0))))

Par défaut, LilyPond affichera ces messages sur la console, parmi toutes les autres informations. Vous pouvez, afin de les isoler et de garder le résultat des commandes \display{TRUC}, spécifier un port optionnel à utiliser pour la sortie :

{
  \displayMusic #(open-output-file "display.txt") { c'4\f }
}

Ceci aura pour effet d’écraser tout fichier précédemment généré. Lorsque plusieurs expressions doivent être retranscrites, il suffit de faire appel à une variable pour le port puis de la réutiliser :

{
  port = #(open-output-file "display.txt")
  \displayMusic \port { c'4\f }
  \displayMusic \port { d'4 }
  #(close-output-port port)
}

La documentation de Guile fournit une description détaillée des ports. Clôturer un port n’est requis que si vous désirez consulter le fichier avant que LilyPond n’ait fini, ce dont nous ne nous sommes pas préoccupé dans le premier exemple.

L’information sera encore plus lisible après un peu de mise en forme :

(make-music 'SequentialMusic
  'elements (list
	     (make-music 'NoteEvent
               'articulations (list
			       (make-music 'AbsoluteDynamicEvent
				 'text
				 "f"))
	       'duration (ly:make-duration 2 0 1/1)
	       'pitch    (ly:make-pitch 0 0 0))))

Une séquence musicale { … } se voit attribuer le nom de SequentialMusic, et les expressions qu’elle contient sont enregistrées en tant que liste dans sa propriété 'elements. Une note est représentée par un objet NoteEvent – contenant les propriétés de durée et hauteur – ainsi que l’information qui lui est attachée – en l’occurrence un AbsoluteDynamicEvent ayant une propriété text de valeur "f" – et stockée dans sa propriété articulations.

La fonction \displayMusic renvoie la musique qu’elle affiche ; celle-ci sera donc aussi interprétée. L’insertion d’une commande \void avant le \displayMusic permet de s’affranchir de la phase d’interprétation.

1.3.3 Propriétés musicales

Nous abordons ici les propriétés music, et non pas les propriétés context ou layout.

Partons de cet exemple simple :

someNote = c'
\displayMusic \someNote
===>
(make-music
  'NoteEvent
  'duration
  (ly:make-duration 2 0 1/1)
  'pitch
  (ly:make-pitch 0 0 0))

L’objet NoteEvent est la représentation brute de someNote. Voyons ce qui se passe lorsque nous plaçons ce c’ dans une construction d’accord :

someNote = <c'>
\displayMusic \someNote
===>
(make-music
  'EventChord
  'elements
  (list (make-music
          'NoteEvent
          'duration
          (ly:make-duration 2 0 1/1)
          'pitch
          (ly:make-pitch 0 0 0))))

L’objet NoteEvent est maintenant le premier objet de la propriété 'elements de someNote.

\displayMusic utilise la fonction display-Scheme-music pour afficher la représentation en Scheme d’une expression musicale :

#(display-Scheme-music (first (ly:music-property someNote 'elements)))
===>
(make-music
  'NoteEvent
  'duration
  (ly:make-duration 2 0 1/1)
  'pitch
  (ly:make-pitch 0 0 0))

La hauteur de la note est accessible au travers de la propriété 'pitch de l’objet NoteEvent :

#(display-Scheme-music
   (ly:music-property (first (ly:music-property someNote 'elements))
                      'pitch))
===>
(ly:make-pitch 0 0 0)

La hauteur de la note se modifie en définissant sa propriété 'pitch :

#(set! (ly:music-property (first (ly:music-property someNote 'elements))
                          'pitch)
       (ly:make-pitch 0 1 0)) ;; set the pitch to d'.
\displayLilyMusic \someNote
===>
d'4

1.3.4 Doublement d’une note avec liaison (exemple)

Supposons que nous ayons besoin de créer une fonction transformant une saisie a en { a( a) }. Commençons par examiner comment le résultat est représenté en interne.

\displayMusic{ a'( a') }
===>
(make-music
  'SequentialMusic
  'elements
  (list (make-music
          'NoteEvent
          'articulations
          (list (make-music
                  'SlurEvent
                  'span-direction
                  -1))
          'duration
          (ly:make-duration 2 0 1/1)
          'pitch
          (ly:make-pitch 0 5 0))
        (make-music
          'NoteEvent
          'articulations
          (list (make-music
                  'SlurEvent
                  'span-direction
                  1))
          'duration
          (ly:make-duration 2 0 1/1)
          'pitch
          (ly:make-pitch 0 5 0))))

Mauvaise nouvelle ! Les expressions SlurEvent doivent s’ajouter « à l’intérieur » de la note – dans sa propriété articulations.

Examinons à présent la saisie :

\displayMusic a'
===>
(make-music
  'NoteEvent
  'duration
  (ly:make-duration 2 0 1/1)
  'pitch
  (ly:make-pitch 0 5 0))))

Nous aurons donc besoin, dans notre fonction, de cloner cette expression – de telle sorte que les deux notes constituent la séquence – puis d’ajouter un SlurEvent à la propriété 'articulations de chacune d’elles, et enfin réaliser un SequentialMusic de ces deux éléments NoteEvent. En tenant compte du fait que, dans le cadre d’un ajout, une propriété non définie est lue '() (une liste vide), aucune vérification n’est requise avant d’introduire un nouvel élément en tête de la propriété articulations.

doubleSlur = #(define-music-function (note) (ly:music?)
         "Renvoie : { note ( note ) }.
         `note` est censé être une note unique."
         (let ((note2 (ly:music-deep-copy note)))
           (set! (ly:music-property note 'articulations)
                 (cons (make-music 'SlurEvent 'span-direction -1)
                       (ly:music-property note 'articulations)))
           (set! (ly:music-property note2 'articulations)
                 (cons (make-music 'SlurEvent 'span-direction 1)
                       (ly:music-property note2 'articulations)))
           (make-music 'SequentialMusic 'elements (list note note2))))

1.3.5 Ajout d’articulation à des notes (exemple)

Le moyen d’ajouter une articulation à des notes consiste à juxtaposer deux expressions musicales. L’option de réaliser nous-mêmes une fonction musicale à cette fin.

Un $variable au milieu de la notation #{ … #} se comporte exactement comme un banal \variable en notation LilyPond traditionnelle. Nous pourrions écrire

{ \musique -. -> }

mais, pour les besoins de la démonstration, nous allons voir comment réaliser ceci en Scheme. Commençons par examiner une saisie simple et le résultat auquel nous désirons aboutir :

%  saisie
\displayMusic c4
===>
(make-music
  'NoteEvent
  'duration
  (ly:make-duration 2 0 1/1)
  'pitch
  (ly:make-pitch -1 0 0))))
=====
%  résultat attendu
\displayMusic c4->
===>
(make-music
  'NoteEvent
  'articulations
  (list (make-music
          'ArticulationEvent
          'articulation-type 'accent))
  'duration
  (ly:make-duration 2 0 1/1)
  'pitch
  (ly:make-pitch -1 0 0))

Nous voyons qu’une note (c4) est représentée par une expression NoteEvent. Si nous souhaitons ajouter une articulation accent, nous devrons ajouter une expression ArticulationEvent à la propriété articulations de l’expression NoteEvent.

Construisons notre fonction en commençant par

(define (ajoute-accent note-event)
  "Ajoute un accent (ArticulationEvent) aux articulations de `note-event`,
  qui est censé être une expression NoteEvent."
  (set! (ly:music-property note-event 'articulations)
        (cons (make-music 'ArticulationEvent
                'articulation-type 'accent)
              (ly:music-property note-event 'articulations)))
  note-event)

La première ligne est la manière de définir une fonction en Scheme : la fonction Scheme a pour nom ajoute-accent et elle comporte une variable appelée note-event. En Scheme, le type d’une variable se déduit la plupart de temps de par son nom – c’est d’ailleurs une excellente pratique que l’on retrouve dans de nombreux autres langages.

"Ajoute un accent…"

décrit ce que fait la fonction. Bien que ceci ne soit pas primordial, tout comme des noms de variable évidents, tâchons néanmoins de prendre de bonnes habitudes dès nos premiers pas.

Vous pouvez vous demander pourquoi nous modifions directement l’événement note plutôt que d’en manipuler une copie – on pourrait utiliser ly:music-deep-copy à cette fin. La raison en est qu’il existe un contrat tacite : les fonctions musicales sont autorisées à modifier leurs arguments – ils sont générés en partant de zéro (comme les notes que vous saisissez) ou déjà recopiés (faire référence à une variable musicale avec ‘\nom’ ou à de la musique issue d’expressions Scheme ‘$(…)’ aboutit à une copie). Dans la mesure où surmultiplier les copies serait contre productif, la valeur de retour d’une fonction musicale n’est pas recopiée. Afin de respecter ce contrat, n’utilisez pas un même argument à plusieurs reprises, et n’oubliez pas que le retourner compte pour une utilisation.

Dans un exemple précédent, nous avons construit de la musique en répétant un certain argument musical. Dans ce cas là, l’une des répétitions se devait d’être une copie. Dans le cas contraire, certaines bizarreries auraient pu survenir. Par exemple, la présence d’un \relative ou d’un \transpose, après plusieurs répétitions du même élément, entraînerait des « relativisations » ou transpositions en cascade. Si nous les assignons à une variable musicale, l’enchaînement est rompu puisque la référence à ‘\nom’ créera une nouvelle copie sans toutefois prendre en considération l’identité des éléments répétés.

Cette fonction n’étant pas une fonction musicale à part entière, elle peut s’utiliser dans d’autres fonctions musicales. Il est donc sensé de respecter le même contrat que pour les fonctions musicales : l’entrée peut être modifiée pour arriver à une sortie, et il est de la responsabilité de l’appelant d’effectuer des copies s’il a réellement besoin de l’argument dans son état originel. Vous constaterez, à la lecture des fonctions propres à LilyPond, comme music-map, que ce principe est toujours respecté.

Revenons à nos moutons… Nous disposons maintenant d’un note-event que nous pouvons modifier, non pas grâce à un ly:music-deep-copy, mais plutôt en raison de notre précédente réflexion. Nous ajoutons l’accent à la liste de ses propriétés 'articulations.

(set! emplacement nouvelle-valeur)

L’emplacement est ce que nous voulons ici définir. Il s’agit de la propriété 'articulations de l’expression note-event.

(ly:music-property note-event 'articulations)

La fonction ly:music-property permet d’accéder aux propriétés musicales – les 'articulations, 'duration, 'pitch, etc. que \displayMusic nous a indiquées. La nouvelle valeur sera l’ancienne propriété 'articulations, augmentée d’un élément : l’expression ArticulationEvent, que nous recopions à partir des informations de \displayMusic.

(cons (make-music 'ArticulationEvent
        'articulation-type 'accent)
      (ly:music-property result-event-chord 'articulations))

cons permet d’ajouter un élément en tête de liste sans pour autant modifier la liste originale. C’est exactement ce que nous recherchons : la même liste qu’auparavant, plus la nouvelle expression ArticulationEvent. L’ordre au sein de la propriété 'articulations n’a ici aucune importance.

Enfin, après avoir ajouté l’articulation accent à sa propriété articulations, nous pouvons renvoyer le note-event, ce que réalise la dernière ligne de notre fonction.

Nous pouvons à présent transformer la fonction ajoute-accent en fonction musicale, à l’aide d’un peu d’enrobage syntaxique et mention du type de son argument.

ajouteAccent = #(define-music-function (note-event) (ly:music?)
  "Ajoute un accent (ArticulationEvent) aux articulations de `note-event`,
  qui est censé être une expression NoteEvent."
  (set! (ly:music-property note-event 'articulations)
        (cons (make-music 'ArticulationEvent
                'articulation-type 'accent)
              (ly:music-property note-event 'articulations)))
  note-event)

Par acquis de conscience, vérifions que tout ceci fonctione :

\displayMusic \ajouteAccent c4

2.2.1 Définition de fonctions Scheme

D’une manière générale, une fonction Scheme se définit ainsi :

fonction =
#(define-scheme-function
     (arg1 arg2…)
     (type1? type2?…)
   corps)

où

argN

n-ième argument.

typeN?

Un type de prédicat Scheme pour lequel argN devra retourner #t. Il existe aussi une forme spécifique – (prédicat? default) – qui permet de fournir des argument optionnels. En l’absence d’argument réel au moment de l’appel à la fonction, c’est la valeur par défaut qui lui sera substituée. Les valeurs par défaut sont évaluées dès l’apparition de la définition, y compris dans le cas de blocs de code LilyPond ; vous devrez donc, si ces valeurs par défaut ne peuvent être déterminées que plus tard, mentionner une valeur spéciale que vous reconnaîtrez facilement. Lorsque vous mentionnez un prédicat entre parenthèses sans toutefois fournir sa valeur par défaut, celle-ci sera considérée comme étant #f. Les valeurs par défaut d’un prédicat? ne sont vérifiées ni au moment de la définition, ni à l’exécution ; il est de votre ressort de gérer les valeurs que vous spécifiez. Une valeur par défaut constituée d’une expression musicale est recopiée dès la définition de origin à l’emplacement courant du code.

corps

Une séquence de formules Scheme évaluées dans l’ordre, la dernière servant de valeur de retour de la fonction. Il peut contenir des blocs de code LilyPond, enchâssés dans des accolades et hashes – #{…#} – comme indiqué à la rubrique Blocs de code LilyPond. Au sein d’un bloc de code LilyPond, un ‘#’ permet de référencer des arguments de la fonction – tel #arg1 – ou d’ouvrir une expression Scheme contenant les arguments de la fonction – par exemple ‘#(cons arg1 arg2)’. Dans le cas où une expression Scheme introduite par ‘#’ ne vous permet pas de parvenir à vos fins, vous pourriez devoir revenir à une expression Scheme « immédiate » à l’aide d’un ‘$’, comme $music.

Lorsque votre fonction retourne une expression musicale, lui est attribuée la valeur origin.

La recevabilité des arguments est déterminée par un appel effectif au prédicat après que LilyPond les a déjà convertis en expression Scheme. Par voie de conséquence, l’argument peut tout à fait se libeller en syntaxe Scheme – introduite par un ‘#’ ou en tant que résultat d’un appel à une fonction Scheme. Par ailleurs, LilyPond convertira en Scheme un certain nombre de constructions purement LilyPond avant même d’en avoir vérifié le prédicat. C’est notamment le cas de la musique, des postévénements, des chaînes simples (avec ou sans guillemets), des nombres, des markups et listes de markups, ainsi que des blocs score, book, bookpart, ou qui définissent un contexte ou un format de sortie.

Il existe certaines situations pour lesquelles LilyPond lèvera toute ambiguïté grâce aux fonctions de prédicat : un ‘-3’ est-il un postévénement de type doigté ou un nombre négatif ? Un "a" 4 en mode paroles est-il une chaîne suivie d’un nombre ou bien un événement syllabe de durée 4 ? LilyPond répondra à ces questions par des interprétations successives du prédicat de l’argument, dans un ordre défini de sorte à minimiser les interprétations erronées et le besoin de lecture en avance.

Un prédicat qui accepte par exemple aussi bien une expression musicale qu’une hauteur considèrera c'' comme étant une hauteur plutôt qu’une expression musicale. Les durées ou postévénements qui viennent juste après viendront modifier cette interprétation. C’est la raison pour laquelle il vaut mieux éviter des prédicats par trop permissifs tel que Scheme? lorsque l’application fait plutôt appel à des types d’argument plus spécifiques.

Les différents types de prédicat propres à LilyPond sont recensés à l’annexe Types de prédicats prédéfinis.

Voir aussi

Manuel de notation : Types de prédicats prédéfinis.

Fichiers d’initialisation : lily/music-Scheme.cc, scm/c++.scm, scm/lily.scm.

2.2.2 Utilisation de fonctions Scheme

Vous pouvez appeler une fonction Scheme pratiquement partout où une expression Scheme derrière un ‘#’ peut prendre place. Vous appelez une fonction Scheme à partir de LilyPond en faisant précéder son nom d’un ‘\’, et en le faisant suivre de ses arguments. Lorsqu’un prédicat d’argument optionnel ne correspond pas à un argument, LilyPond l’ignore ainsi que tous les arguments optionnels qui suivent, les remplaçant par leur valeur par défaut, et « sauvegarde » en tant que prochain argument obligatoire l’argument qui ne correspondait pas. Dans la mesure où l’argument sauvegardé doit servir, les argument optionnels ne sont en fait pas considérés comme optionnels, sauf à être suivis d’un argument obligatoire.

Une exception cependant à cette règle : le fait de donner un \default en tant qu’argument optionnel aura pour résultat que cet argument et tous les autres arguments optionnels qui suivent seront ignorés et remplacés par leur valeur par défaut. Il en va de même lorsqu’aucun argument obligatoire ne suit, du fait que \default ne requiert pas de sauvegarde. C’est d’ailleurs ainsi que fonctionnent les commandes mark et key, qui retrouvent leur comportement par défaut lorsque vous les faites suivre d’un \default.

En plus de là où une expression Scheme est requise, il y a quelques endroits où des expressions ‘#’ sont acceptées et évaluées uniquement pour leurs effets annexes. Il s’agit, dans la plupart des cas, d’endroits où une affectation serait tout à fait envisageable.

Dans la mesure où il n’est pas bon de renvoyer une valeur qui pourrait être mal interprétée dans certains contextes, nous vous enjoignons à utiliser des fonctions Scheme normales uniquement dans les cas où vous renvoyez toujours une valeur utile, et une fonction fantôme – voir Fonctions Scheme fantômes – dans le cas contraire.

Pour des raisons de commodité, il est possible de faire appel à des fonctions Scheme directement en Scheme, courcircuitant ainsi l’analyseur de LilyPond. Leur nom s’utilise comme n’importe quel nom de fonction. Le contrôle de typologie des arguments et l’omission des arguments optionnels seront traîtés de la même manière que lorsque l’appel est fait à partir de LilyPond, la valeur Scheme *unspecified* ayant le rôle du mot réservé \default pour omettre explicitement les arguments optionnels. Les arguments optionnels en fin de liste d’arguments peuvent être omsi sans plus d’indication lorsque l’appel est fait au sein même de Scheme.

2.2.3 Fonctions Scheme fantômes

Il arrive qu’une procédure soit exécutée pour réaliser une action, non pour renvoyer une valeur. Certains langages de programmation, tels le C et Scheme, utilisent des fonctions dans les deux cas et se débarrassent tout bonnement de la valeur renvoyée ; en règle générale, il suffit que l’expression fasse office de déclaration, et d’ignorer le résultat. C’est futé, mais pas sans risque d’erreur : la plupart des compilateurs C actuels déclenchent un avertissement si l’on se débarrasse de certaines expressions non-void. Pour de nombreuses fonctions réalisant une action, les standards Scheme déclarent que la valeur de retour est indéfinie. L’interpréteur Guile qu’utilise le Scheme de LilyPond dispose d’une valeur unique *unspecified* qu’il retourne alors, en règle générale – notamment lorsqu’on utilise set! directement sur une variable – mais malheureusement pas toujours.

Une fonction LilyPond définie à l’aide de la clause define-void-function vous apporte l’assurance que c’est cette valeur spéciale – la seule valeur qui satisfasse au prédicat void? – qui sera retournée.

noPointAndClick =
#(define-void-function
     ()
     ()
   (ly:set-option 'point-and-click #f))
…
\noPointAndClick   % desactive le "pointer-cliquer"

L’utilisation d’un préfixe \void permet ainsi d’évaluer une expression pour ses effets annexes sans interprétation d’une quelconque valeur de retour :

\void #(hashq-set! une-table une-clé une-valeur)

Vous serez alors assuré que LilyPond ne tentera pas d’affecter un sens à la valeur de retour, à quelque endroit qu’elle ressorte. Ceci est aussi opérationnel dans le cadre de fonctions musicales telles que \displayMusic.

2.3.1 Définition de fonctions musicales

Une fonction musicale se définit ainsi :

fonction =
#(define-music-function
     (arg1 arg2…)
     (type1? type2?…)
   corps)

de manière similaire aux fonctions Scheme. La plupart du temps, le corps sera constitué d’un bloc de code LilyPond.

Les différents types des prédicat sont recensés à l’annexe Types de prédicats prédéfinis.

Voir aussi

Manuel de notation : Types de prédicats prédéfinis.

Fichiers d’initialisation : lily/music-Scheme.cc, scm/c++.scm, scm/lily.scm.

2.3.2 Utilisation de fonctions musicales

En ce qui concerne la gestion des listes d’argments, les fonctions musicales ne diffèrent en rien des fonction Scheme – voir Utilisation de fonctions Scheme.

Une « fonction musicale » doit impérativement renvoyer une expression répondant au prédicat ly:music?. Ceci a pour conséquence d’autoriser l’appel à une fonction musicale en tant qu’argument de type ly:music? dans le cadre de l’appel à une autre fonction musicale.

Certaines restrictions s’appliqueront selon le contexte où une fonction musicale est utilisée, de telle sorte que l’analyse syntaxique soit sans ambiguïté.

• Dans une expression musicale de haut niveau, aucun postévénement n’est toléré.
• Lorsqu’une fonction musicale – contrairement à une fonction événementielle – renvoie une expression de type postévénement, LilyPond requiert son introduction par un indicateur de positionnement – à savoir -, ^ ou _ – de telle sorte que le postévénement produit par l’appel à cette fonction s’intègre correctement dans l’expression environnante.
• En tant que partie d’un accord, l’expression musicale renvoyée doit être du type rhythmic-event, et plus particulièrement un NoteEvent.

Des fonctions « polymorphes » telles que \tweak peuvent s’appliquer aux postévénements, constituants d’accord et expressions de haut niveau.

2.3.3 Fonctions de substitution simple

Une fonction de substitution simple renvoie une expression musicale écrite au format LilyPond et contient des arguments au format de l’expression résultante. Vous en trouverez une description détaillée à la rubrique Exemples de fonction de substitution.

2.3.4 Fonctions de substitution intermédiaires

Une fonction de substitution intermédiaire est une fonction dont l’expression musicale résultante mélangera du code Scheme au code LilyPond.

Certaines commandes \override nécessitent un argument supplémentaire constitué d’une paire de nombres, appelée cons cell en Scheme – que l’on pourrait traduire par « construction de cellule ».

Cette paire peut se mentionner directement dans la fonction musicale à l’aide d’une variable pair? :

manualBeam =
#(define-music-function
     (beg-end)
     (pair?)
   #{
     \once \override Beam.positions = #beg-end
   #})

\relative c' {
  \manualBeam #'(3 . 6) c8 d e f
}

Autre manière de procéder, les nombres formant la paire sont transmis comme arguments séparés ; le code Scheme chargé de créer la paire pourra alors être inclus dans l’expression musicale :

manualBeam =
#(define-music-function
     (beg end)
     (number? number?)
   #{
     \once \override Beam.positions = #(cons beg end)
   #})

\relative c' {
  \manualBeam #3 #6 c8 d e f
}

L’entretien des propriétés peut se voir comme un empilement par propriété par objet par contexte. Les fonctions musicales peuvent nécessiter des dérogations pour une ou plusieurs propriétés pour la durée de la fonction, puis de revenir aux valeurs précédentes avant de quitter. Néanmoins, une dérogation normale va retirer de la pile – ou dépiler – et supprimer le sommet de la pile de la propriété avant d’y ajouter quoi que ce soit – ou empiler – ; la valeur précédente de la propriété est de fait perdue. Lorsque la valeur antérieure doit être préservée, l’instruction \override devra être préfixée d’un \temporary, comme ceci :

\temporary \override …

L’utilisation d’un \temporary a pour effet d’effacer la propriété pop-first (commence par dépiler normalement activée) de la dérogation ; la valeur antérieure ne sera alors pas supprimée de la pile de la propriété avant d’y empiler la nouvelle valeur. Lorsqu’un \revert viendra par la suite supprimer la valeur dérogatoire temporaire, réapparaitra la valeur antérieure.

En d’autres termes, un \revert qui suit un \temporary \override pour la même propriété n’apporte rien. Ce principe est aussi valable pour un couple \temporary et \undo sur la même musique contenant des dérogations.

Voici un exemple de fonction musicale utilisant cette fonctionnalité. La présence du \temporary permet de s’assurer qu’en sortant de la fonction, les propriétés cross-staff et style retrouveront les valeurs qu’elles avaient avant que ne soit appelée la fonction crossStaff. En l’absence de \temporary, ces propriétés auraient retrouvé leurs valeurs par défaut à la sortie de la fonction.

crossStaff =
#(define-music-function (notes) (ly:music?)
  (_i "Create cross-staff stems")
  #{
  \temporary \override Stem.cross-staff = #cross-staff-connect
  \temporary \override Flag.style = #'no-flag
  #notes
  \revert Stem.cross-staff
  \revert Flag.style
#})

2.3.5 De l’usage des mathématiques dans les fonctions

Une fonction musicale peut requérir, en plus d’une simple substitution, une part de programmation en Scheme.

AltOn =
#(define-music-function
     (mag)
     (number?)
   #{
     \override Stem.length = #(* 7.0 mag)
     \override NoteHead.font-size =
       #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
   #})

AltOff = {
  \revert Stem.length
  \revert NoteHead.font-size
}

\relative {
  c'2 \AltOn #0.5 c4 c
  \AltOn #1.5 c c \AltOff c2
}

Cette fonction pourrait tout à fait être réécrite de telle sorte qu’elle s’applique à une expression musicale :

withAlt =
#(define-music-function
     (mag music)
     (number? ly:music?)
   #{
     \override Stem.length = #(* 7.0 mag)
     \override NoteHead.font-size =
       #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
     #music
     \revert Stem.length
     \revert NoteHead.font-size
   #})

\relative {
  c'2 \withAlt #0.5 { c4 c }
  \withAlt #1.5 { c c } c2
}

2.3.6 Fonctions dépourvues d’argument

Dans la plupart des cas, une fonction dépourvue d’argument devrait être créée à l’aide d’une variable :

dolce = \markup{ \italic \bold dolce }

Il peut, dans certains cas particuliers, s’avérer utile de créer une fonction sans argument comme ici,

displayBarNum =
#(define-music-function
     ()
     ()
   (if (eq? #t (ly:get-option 'display-bar-numbers))
       #{ \once \override Score.BarNumber.break-visibility = ##f #}
       #{#}))

de manière à pouvoir afficher les numéros de mesure grâce à un appel à cette fonction. En pareil cas, vous devrez invoquer lilypond en respectant la syntaxe

lilypond -d display-bar-numbers MONFICHIER.ly

2.3.7 Fonctions musicales fantômes

Une fonction musicale doit renvoyer une expression musicale. Toutefois, une fonction musicale peut n’être exécutée que dans le but d’en retenir les effets annexes ; vous devrez alors utiliser une procédure define-void-function. Il peut cependant arriver que vous ayez besoin d’une fonction qui, selon le cas, produise ou non (comme dans l’exemple de la rubrique précédente) une expression musicale. L’utilisation d’un #{ #} vous permettra de renvoyer une expression musicale void.

2.5.1 Construction d’un markup en Scheme

Les expressions markup sont représentées en Scheme de manière interne par la macro markup :

(markup expression)

La commande \displayScheme permet d’obtenir la représentation en Scheme d’une expression markup :

\displayScheme
\markup {
  \column {
    \line { \bold \italic "hello" \raise #0.4 "world" }
    \larger \line { foo bar baz }
  }
}

Compiler ce code renverra en console les lignes suivantes :

(markup
  #:line
  (#:column
   (#:line
    (#:bold (#:italic "hello") #:raise 0.4 "world")
    #:larger
    (#:line ("foo" "bar" "baz")))))

L’impression du markup sera suspendue dès lors qu’apparaîtra un ‘\void \displayScheme markup’. Tout comme pour la commande \displayMusic, le résultat de \displayScheme peut être sauvegardé dans un fichier séparé. Voir à ce sujet Affichage d’expressions musicales.

Vous pouvez constater les principales règles de traduction entre les syntaxes respectives de LilyPond et de Scheme en matière de markup. Bien que le passage en syntaxe LilyPond grâce à #{ … #} apporte de la souplesse, nous allons voir comment utiliser la macro markup en Scheme exclusivement.

LilyPond	Scheme
\markup markup1	(markup markup1)
\markup { markup1 markup2… }	(markup markup1 markup2… )
\commande-markup	#:commande-markup
\variable	variable
\center-column { … }	#:center-column ( … )
chaîne	"chaîne"
#argument-Scheme	argument-Scheme

L’intégralité du langage Scheme est accessible à l’intérieur même de la macro markup. Vous pouvez ainsi appeler des fonctions à partir de markup pour manipuler des chaînes de caractères, ce qui est particulièrement pratique lorsque vous créez votre propre commande de markup – voir Définition d’une nouvelle commande de markup.

Problèmes connus et avertissements

L’argument markup-list des commandes #:line, #:center-column ou #:column ne saurait être une variable ni le résultat de l’appel à une fonction.

(markup #:line (fonction-qui-retourne-des-markups))

n’est pas valide. Il vaut mieux, en pareil cas, utiliser les fonctions make-line-markup, make-center-column-markup ou make-column-markup :

(markup (make-line-markup (fonction-qui-retourne-des-markups)))

2.5.2 Fonctionnement interne des markups

Dans un markup tel que

\raise #0.5 "text example"

\raise représente en fait la fonction raise-markup. L’expression markup est enregistrée sous la forme

(list raise-markup 0.5 "text example")

Lorsque ce markup est converti en objets imprimables (stencils), la fonction raise-markup est appelée ainsi :

(apply raise-markup
       \layout objet
       liste des alists de propriété
       0.5
       le markup "text example")

La fonction raise-markup commence par créer le stencil pour la chaîne text example, puis remonte ce stencil d’un demi espace de portée. Il s’agit là d’un exemple relativement simple, et nous en aborderons de plus complexes au fil des paragraphes suivants ; d’autres exemples se trouvent directement dans le fichier scm/define-markup-commands.scm.

2.5.3 Définition d’une nouvelle commande de markup

Nous allons étudier dans ce qui suit la manière de définir une nouvelle commande de markup.

(define-markup-command (nom-commande layout props arg1 arg2…)
    (arg1-type? arg2-type?…)
    [ #:properties ((propriété1 valeur-par-défaut1)
                    …) ]
    [ #:as-string expression ]
  …corps de la commande…)

(ly:output-def-lookup layout 'line-width)

#(define-markup-command (double-box layout props text) (markup?)
  "Dessine un double encadrement autour du texte."
  (interpret-markup layout props
    #{\markup \override #'(box-padding . 0.4) \box
            \override #'(box-padding . 0.6) \box { #text }#}))

#(define-markup-command (double-box layout props text) (markup?)
  "Dessine un double encadrement autour du texte."
  (interpret-markup layout props
    (markup #:override '(box-padding . 0.4) #:box
            #:override '(box-padding . 0.6) #:box text)))

\markup \double-box A

#(define-markup-command (double-box layout props text) (markup?)
  #:properties ((inter-box-padding 0.4)
                (box-padding 0.6))
  "Dessine un double encadrement autour du texte."
  (interpret-markup layout props
    #{\markup \override #`(box-padding . ,inter-box-padding) \box
               \override #`(box-padding . ,box-padding) \box
               { #text } #}))

#(define-markup-command (double-box layout props text) (markup?)
  #:properties ((inter-box-padding 0.4)
                (box-padding 0.6))
  "Dessine un double encadrement autour du texte."
  (interpret-markup layout props
    (markup #:override `(box-padding . ,inter-box-padding) #:box
            #:override `(box-padding . ,box-padding) #:box text)))

(define-markup-command (draw-line layout props dest)
  (number-pair?)
  #:category graphic
  #:properties ((thickness 1))
  "…documentation…"
  (let ((th (* (ly:output-def-lookup layout 'line-thickness)
               thickness))
        (x (car dest))
        (y (cdr dest)))
    (make-line-stencil th 0 0 x y)))

(define-markup-command (draw-double-line layout props dest)
  (number-pair?)
  #:properties ((thickness 1))
  "…documentation…"
  (let ((th (* (ly:output-def-lookup layout 'line-thickness)
               thickness))
        (x (car dest))
        (y (cdr dest)))
    (make-line-stencil th 0 0 x y)))

(define-markup-command (draw-double-line layout props dest)
  (number-pair?)
  #:properties ((thickness 1)
                (line-gap 0.6))
  "…documentation…"
  …

2.5.4 Définition d’une nouvelle commande de liste de markups

Une commande traitant une liste de markups se définit à l’aide de la macro Scheme define-markup-list-command, de manière analogue à la macro define-markup-command abordée à la rubrique Définition d’une nouvelle commande de markup, à ceci près que cette dernière renvoie un seul stencil, non une liste de stencils.

La fonction interpret-markup-list, à l’instar de la fonction interpret-markup, permet de convertir une liste de markups en liste de stencils.

Dans l’exemple suivant, nous définissons \paragraph, une commande de liste de markups, qui renverra une liste de lignes justifiées dont la première sera indentée. La largeur de l’alinéa sera récupérée par l’argument props.

#(define-markup-list-command (paragraph layout props args) (markup-list?)
   #:properties ((par-indent 2))
   (interpret-markup-list layout props
     #{\markuplist \justified-lines { \hspace #par-indent #args } #}))

La version purement Scheme est un peu plus complexe :

#(define-markup-list-command (paragraph layout props args) (markup-list?)
   #:properties ((par-indent 2))
   (interpret-markup-list layout props
     (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
                                             args))))

En dehors des habituels arguments layout et props, la commande de liste de markups paragraph prend en argument une liste de markups appelée args. Le prédicat des listes de markups est markup-list?.

Pour commencer, la fonction récupère la taille de l’alinéa, propriété ici dénommée par-indent, à partir de la liste de propriétés props. En cas d’absence, la valeur par défaut sera de 2. Ensuite est créée une liste de lignes justifiées grâce à la commande prédéfinie \justified-lines, liée à la fonction make-justified-lines-markup-list. Un espace horizontal est ajouté en tête, grâce à \hspace ou à la fonction make-hspace-markup. Enfin, la liste de markups est interprétée par la fonction interpret-markup-list.

Voici comment utiliser cette nouvelle commande de liste de markups :

\markuplist {
  \paragraph {
    The art of music typography is called \italic {(plate) engraving.}
    The term derives from the traditional process of music printing.
    Just a few decades ago, sheet music was made by cutting and stamping
    the music into a zinc or pewter plate in mirror image.
  }
  \override-lines #'(par-indent . 4) \paragraph {
    The plate would be inked, the depressions caused by the cutting
    and stamping would hold ink.  An image was formed by pressing paper
    to the plate.  The stamping and cutting was completely done by
    hand.
  }
}

2.6.1 Évaluation d’un contexte

Un contexte peut être modifié, au moment même de son interprétation, par du code Scheme. La syntaxe consacrée au sein d’un bloc LilyPond est

\applyContext fonction

et, dans le cadre d’un code Scheme :

(make-apply-context fonction)

fonction est constitué d’une fonction Scheme comportant un unique argument : le contexte au sein duquel la commande \applyContext est appelée. Cette fonction peut accéder aussi bien aux propriétés de grob (y compris modifiées par \override ou \set) qu’aux propriétés de contexte. Toute action entreprise par la fonction et qui dépendrait de l’état du contexte sera limitée à l’état de ce contexte au moment de l’appel à la fonction. Par ailleurs, les adaptations résultant d’un appel à \applyContext seront effectives jusqu’à ce qu’elles soient à nouveau directement modifiées ou bien annulées, quand bien même les conditions initiales dont elles dépendent auraient changé.

Voici quelques fonctions Scheme utiles avec \applyContext :

ly:context-property

recherche la valeur d’une propriété de contexte,

ly:context-set-property!

détermine une propriété de contexte,

ly:context-grob-definition

ly:assoc-get

recherche la valeur d’une propriété de grob,

ly:context-pushpop-property

réalise un \temporary \override ou un \revert sur une propriété de grob.

L’exemple suivant recherche la valeur en cours de fontSize puis la double :

doubleFontSize =
\applyContext
  #(lambda (context)
     (let ((fontSize (ly:context-property context 'fontSize)))
       (ly:context-set-property! context 'fontSize (+ fontSize 6))))

{
  \set fontSize = -3
  b'4
  \doubleFontSize
  b'
}

L’exemple suivant recherche la couleur des objets NoteHead, Stem et Beam, puis diminue pour chacun d’eux le degré de saturation.

desaturate =
\applyContext
  #(lambda (context)
     (define (desaturate-grob grob)
       (let* ((grob-def (ly:context-grob-definition context grob))
              (color (ly:assoc-get 'color grob-def black))
              (new-color (map (lambda (x) (min 1 (/ (1+ x) 2))) color)))
         (ly:context-pushpop-property context grob 'color new-color)))
     (for-each desaturate-grob '(NoteHead Stem Beam)))

\relative {
  \time 3/4
  g'8[ g] \desaturate g[ g] \desaturate g[ g]
 \override NoteHead.color = #darkred
  \override Stem.color = #darkred
  \override Beam.color = #darkred
  g[ g] \desaturate g[ g] \desaturate g[ g]
}

Ceci pourrait tout à fait s’implémenter sous la forme d’une fonction musicale, afin d’en réduire les effets à un seul bloc de musique. Notez comment ly:context-pushpop-property est utilisé à la fois pour un \temporary \override et pour un \revert :

desaturate =
#(define-music-function
   (music) (ly:music?)
   #{
     \applyContext
     #(lambda (context)
        (define (desaturate-grob grob)
          (let* ((grob-def (ly:context-grob-definition context grob))
                 (color (ly:assoc-get 'color grob-def black))
                 (new-color (map (lambda (x) (min 1 (/ (1+ x) 2))) color)))
            (ly:context-pushpop-property context grob 'color new-color)))
        (for-each desaturate-grob '(NoteHead Stem Beam)))
     #music
     \applyContext
     #(lambda (context)
        (define (revert-color grob)
          (ly:context-pushpop-property context grob 'color))
        (for-each revert-color '(NoteHead Stem Beam)))
   #})

\relative {
  \override NoteHead.color = #darkblue
  \override Stem.color = #darkblue
  \override Beam.color = #darkblue
  g'8 a b c
  \desaturate { d c b a }
  g b d b g2
}

2.6.2 Application d’une fonction à tous les objets de mise en forme

La manière la plus souple d’affiner un objet consiste à utiliser la commande \applyOutput. Celle-ci va insérer un événement (ApplyOutputEvent) dans le contexte spécifié. Elle répond aussi bien à la syntaxe

\applyOutput Contexte procédure

que

\applyOutput Contexte.Grob procédure

où procédure est une fonction Scheme à trois arguments.

Lors de l’interprétation de cette commande, la fonction procédure est appelée pout tout objet de rendu (nommé Grob si celui-ci est spécifié) appartenant au contexte Contexte à cet instant précis, avec les arguments suivants :

• l’objet de rendu en lui-même,
• le contexte au sein duquel cet objet est créé,
• le contexte dans lequel \applyOutput est effectué.

De plus, ce qui est à l’origine de l’objet de rendu – l’expression musicale ou l’objet qui l’a générée – se retrouve en tant que propriété d’objet cause. Il s’agit, pour une tête de note, d’un événement NoteHead, et d’un objet Stem pour une hampe.

Voici une fonction utilisable avec la commande \applyOutput : elle « blanchit » la tête des notes se trouvant sur la ligne médiane ou bien directement à son contact.

#(define (blanker grob grob-origin context)
   (if (< (abs (ly:grob-property grob 'staff-position)) 2)
       (set! (ly:grob-property grob 'transparent) #t)))

\relative {
  a'4 e8 <<\applyOutput Voice.NoteHead #blanker a c d>> b2
}

La procédure sera interprétée au niveau Score (partition) ou Staff (portée) dès lors que vous utiliserez l’une des syntaxes

\applyOutput Score…
\applyOutput Staff…