LilyPond — Extender

A.1.1 Banc de sorra de l’Scheme

La instal·lacio del LilyPond inclou també la de la implementació Guile de l’Scheme. Es pot experimentar a un “banc de sorra” de l’Scheme obrint una finestra del terminal i teclejant ‘guile’. En alguns sistemes, sobreto a Windows, pot caldre ajustar la variable d’entorn GUILE_LOAD_PATH a la carpeta ../usr/share/guile/1.8 dins de la instal·lació del LilyPond (per conèixer la ruta completa a aquesta carpet, consulteu Altres fonts d’informació). Com alternativa, els usuaris del Windows poden seleccionar simplement ‘Executar’ del menú Inici i introduir ‘guile’.

No obstant, està disponible un banc de sorra de l’Scheme llest per funcionar amb tot el LilyPond carregat, amb aquesta ordre a la línia d’ordres:

lilypond scheme-sandbox

Un cop està funcionant el banc de sorra, veureu un indicador del sistema de Guile:

guile>

Podem introduir expressions de l’Scheme en aquest indicador per experimentar amb l’Scheme. Si voleu usar la biblioteca readline de GNU per a una més còmoda edició de la línia d’ordrs de l’Scheme, consulteu el fitxer ly/scheme-sandbox.ly per a més informació. Si ja heu activat la biblioteca readline per a les sessions de Guile interactives fora del LilyPond, hauria de funcionar també en el banc de sorra.

A.1.2 Variables de l’Scheme

Les variables de l’Scheme poden tenir qualsevol volar vàlid de l’Scheme, fins i tot un procediment de l’Scheme.

Les variables de l’Scheme es creen amb define:

guile> (define a 2)
guile>

Les variables de l’Scheme es poden avaluar a l’indicar del sistema del Guile, simplement teclejant el nom de la variable:

guile> a
2
guile>

Les variables de l’Scheme es poden imprimir en la pantalla utilitzant la funció display:

guile> (display a)
2guile>

Observeu que el valor 2 i l’indicador del sistema guile es mostren en la misma línia. Això es pot evitar cridant al procediment de la nova línia o imprimint un caràcter de la nova línia.

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

Un cop que s’ha creat una variable, el seu valor es pot modificar amb set!:

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

A.1.3 Tipus de dades simples de l’Scheme

El concepte més bàsic d’una llenguatge els seus tipus de dades: números, cadenes de caràcters, llistes, etc. Vet aquí una llista dels tipus de dades que són de rellevància respecte de l’entrada del LilyPond.

Booleanos

Els valors Booleans són Vertader i Fals. Vertader en l’Scheme és #t i Fals és #f.

Números

Els nombres s’escriuen de la forma normal, 1 és el nombre (enter) u, mentre que -1.5 és un nombre en coma flotant (un nombre no enter).

Cadenas

Las cadenes s’envolten entre cometes:

"això és una cadena"

Les cadenes poden abastar diverses línies:

"això
és
una cadena"

i els caràcters de línia nova al final de cada línia s’incloiran dins de la cadena.

Els caràcters de línia nova també es poden afegir mitjançant la inclusió de \n en la cadena.

"això\nés una\ncadena de divereses línies"

Les cometes dobles i barres invertides s’afageixen a les cadenes precedint-les d’una barra invertida. La cadena \a va dir "b" s’introdueix com

"\\a va dir \"b\""

Existeixen més tipus de dades de l’Scheme que no s’estudien aquí. Per veure un llistat complet, consulteu la guia de referència del Guile, https://www.gnu.org/software/guile/docs/docs-1.8/guile-ref/Simple-Data-Types.html.

A.1.4 Tipus de dades compostes de l’Scheme

També hi ha tipus de dades compostes a l’Scheme. Entre els tipus més usats en la programació del LilyPond es troben les parelles, les llistes, les llistes-A i les tables de hash.

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

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

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

guile> (defineix lamevaparella (cons 123 "Hola")
… )
guile> (car lamevaparella)
123
guile> (cdr lamevaparella)
"Hola"
guile>

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

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

guile> '(17 23 "pep" "pepet" "pepepet")
(17 23 "pep" "pepet" "pepepet")

guile> (defineix la-meva-llista-a '((1  . "A") (2 . "B") (3 . "C")))
guile> la-meva-llista-a
((1 . "A") (2 . "B") (3 . "C"))
guile> (assoc 2 la-meva-llista-a)
(2 . "B")
guile> (cdr (assoc 2 la-meva-llista-a))
"B"
guile>

guile> (defineix h (make-hash-table 10))
guile> h
#<hash-table 0/31>
guile> (hashq-set! h 'key1 "val1")
"val1"
guile> (hashq-set! h 'key2 "val2")
"val2"
guile> (hashq-set! h 3 "val3")
"val3"

guile> (hashq-ref h 3)
"val3"
guile> (hashq-ref h 'key2)
"val2"
guile>

guile> (hashq-get-handle h 'key1)
(key1 . "val1")
guile> (hashq-get-handle h 'frob)
#f
guile>

A.1.5 Càlculs a l’Scheme

L’Scheme es pot usar per fer càlculs. Utilitza sintaxi prefixa. Sumar 1 i 2 s’escriu com (+ 1 2) i no com el tradicional 1+2.

guile> (+ 1 2)
3

Els càlculs es poden niuar; el resultat d’una funció es pot usar per a un altre càlcul.

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

Aquests càlculs són exemple d’avaluacions; una expressió com (* 3 4) es substitueix pel seu valor 12.

Els càlculs de l’Scheme són sensibles a les diferències entre enters i no enters. Els càlculs enters són exactes, mentre que els no enters es calculen amb els límits de precisió adequats:

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

Quan l’intèrpret de l’Scheme troba una expressió que és una llista, el primer element de la llista es tracta com un procediment a avaluar amb els arguments de la resta de la llista. Per tant, tots els operadors a l’Scheme són operadors prefixos.

Si el primer element d’una expressió de l’Scheme que és una llista que es passa a l’intèrpret no és un operador o un procediment, es produeix un error:

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>

Aquí podem veure que l’intèrpret estava intentant tractar l’1 com un operador o procediment, i no ho va poder fer. D’aquí que l’error sigu "Wrong type to apply: 1".

Així doncs, per crear una llista hem d’usar l’operador de llista, o podem precedir-la d’un apòstrof perquè l’intèrpret no intenti avaluar-la.

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

Això és un error que pot aparèixer quan treballeu amb l’Scheme dins del LilyPond.

A.1.6 Procediments de l’Scheme

Els procediments de l’Scheme són expressions de l’Scheme executables que retornen un valor resultant de la seva execució. També poden manipular variables definides fora del procediment.

(define (nom-de-la-funció arg1 arg2 ... argn)
 expressió-de-scheme-que-retorna-un-valor)

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

guile> (mitjana 3 12)
15/2

guile> (define (menor-que-deu? x) (< x 10))
guile> (menor-que-deu? 9)
#t
guile> (menor-que-deu? 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

A.1.7 Condicionals de l’Scheme

(if expressió-de-prova expressió-de-cert expressió-de-fals)

guile> (define a 3)
guile> (define b 5)
guile> (if (> a b) "a és més gran que b" "a no és més gran que b")
"a no és més gran que b"

(cond (expressió-de-prova-1 seqüència-de-expressions-resultant-1)
      (expressió-de-prova-2 seqüència-de-expressions-resultant-2)
      …
      (expressió-de-prova-n seqüència-de-expressions-resultant-n)

guile> (define a 6)
guile> (define b 8)
guile> (cond ((< a b) "a és més petit que b")
...          ((= a b) "a és igual a b")
...          ((> a b) "a és més gran que b"))
"a és més petit que b"

A.2.1 Sintaxi de l’Scheme del LilyPond

L’intèrpret Guile forma part del LilyPond, cosa que significa que es pot incloure Scheme dins dels fitxers d’entrada del LilyPond. Hi ha diversos mètodes per incloure Shcme dins del LilyPond.

La manera més fàcil és utilitzar el símbol de coixinet # abans d’una expressió de l’Scheme.

Ara bé, el codi d’entrada del LilyPond s’estructura en elements i expressions, de forma semblant a com el llenguatge humà s’estructura en paraules i frases. El LilyPond té un analitzador lèxic que reconeix elements indivisibles (nombres literals, cadenes de text, elements de l’Scheme, noms de nota, etc.), i un analitzador que entèn la sintaxi, la Gramàtica del Lilypond (LilyPond grammar). Un cop que sap que s’aplica una regla sintàctica concreta, executa les accions associades amb ella.

El mètode del símbol coixinet # per incrustar Scheme s’adapta de forma natural a aquest sistema. Un cop que l’analitzador lèxic veu un símbol de coixinet, crida al lector de l’Scheme perquè llegeixi una expressió de l’Scheme completa (que pot ser un identificador, una expressió envoltada entre parèntesis, o algunes altes coses). Després que s’hagi llegit l’expressió de l’Scheme, s’emmagatzema com el valor d’un element SCM_TOKEN de la gramàtica. Després que el analitzador sintàctic ja sap com fer ús d’aquest element, crida a Guile perquè avaluï l’expressió de Scheme. Atès que l’analitzador sintàctic sol requerir una mica de lectura per endavant per part de l’analitzador lèxic per prendre les seves decisions d’anàlisi sintàctica, aquesta separació de lectura i avaluació entre els analitzadors lèxic i sintàctic és justament el que cal per mantenir sincronitzades les execucions d’expressions del LilyPond i de l’Scheme. Per aquest motiu s’ha d’usar el símbol de coixinet # per cridar a l’Scheme sempre que sigui possible.

Una altra forma de cridar a l’intèrpret de l’Scheme des del LilyPond és l’ús del símbol de dòlar $ enlloc del coixinet per introduir les expressions de l’Scheme. En aquest cas, el LilyPond avalua el codi just després que l’analitzador lèxic l’hagi llegit. Comprova el tipus resultant de l’expressió de l’Scheme i després selecciona un tipus d’element (un dels diversos elements xxx_IDENTIFIER dins de la sintaxi) per a ell. Crea una còpia del valor i l’usa com a valor de l’element. Si el valor de l’expressió és buit (El valor del Guile de *unspecified*), no es passa res en absolut a l’analitzador sintàctic.

Aquest és, de fet, el mateix mecanisme exactament que el LilyPond fa servir quan cridem a qualsevol variable o funció musical pel seu nom, com \nom, amb l’única diferència que el nom ve determinat per l’analitzador lèxic del LilyPond sense consultar al lector de l’Scheme, i així solament s’accepten els noms de variable consistents amb el mode actul del LilyPond.

L’acció immediata de $ pot portar a alguna que altra sorpresa, vegeu Importació de l’Scheme dins del LilyPond. La utilització de # on l’analitzador sintàctic li dóna suport és normalment preferible. Dins de les expressions musicals, aquelles que es creen utilitzant # s’interpreten com a música. No obstant, no es copien abans de ser utilitzades. Si formen part d’alguna estructura que encara podria tener algun ús, potser hàgiu de fer servir explícitament ly:music-deep-copy.

També hi ha els operadors de ‘divisió de llistes’ $@ i #@ que insereixen tots els elements d’una llista dins del context que l’envolta.

Ara fem una ullada a alguna cosa de codi de l’Scheme real. Els procediments de l’Scheme es poden definir dins dels fitxers d’entrada del LilyPond:

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

Observeu que els comentaris del LilyPond (% y %{ %}) no es poden utilitzar dins del codi de l’Scheme, ni tan sols dins d’un fitxer d’entrada del LilyPond, perquè és l’intèrpret Guile, i no l’analitzador lèxic del LilyPond, el que està llegint l’expressió de l’Scheme. Els comentaris a l’Scheme del Guile s’introdueixen de la manera següent:

; això és un comentari d'una línia

#!
  Això és un comentari de bloc (que no es pot niuar) estil Guile
  Però s'usen en comptades ocasions pels Schemer i mai dins 
  del codi fon del LilyPond
!#

Durant la resta d’aquesta secció suposarem que les dades s’introdueixen en un fitxer de música, per la qual cosa afegim un coixinet # al principi de cada una de les expressions de l’Scheme.

Totes les expressions de l’Scheme del nivell jeràrquic superior dins d’un fitxer d’entrada del LilyPond es poden combinar en una sola expressió de l’Scheme mitjançant la utilització de l’operador begin:

#(begin
  (define Pep 0)
  (define Pepet 1))

A.2.2 Variables del LilyPond

Les variables del LilyPond s’emmagatzemen internament en la forma de variables de l’Scheme. Així,

dotze = 12

equival a

#(define dotze 12)

Això significa que les variables del LiyPond estan disponibles per al seu ús dins d’expressions de l’Scheme. Per exemple, podríem usar

vintiQuatre = (* 2 dotze)

cosa que faria que el nombre 24 s’emmagatzemés dins de la variable vintiQuatre del LilyPond (i de l’Scheme).

El llenguatge Scheme permet la modificació d’expressions complexes in situ i el LilyPond fa ús d’aquesta ‘modificació in situ’ en fer servir funcions musicals. Però quan les expressions musicals s’emmagatzemen dins de variables en lloc de ser intruïdes directament, el que habitualment s’espera quan es passen funcions musicals seria que el valor original quedés intacte. Així doncs, quan es fa referència a una variable musical amb la barra invertida (com ara \vintiQuatre), el LilyPond crea una còpia del valor musical d’aquesta variable per utilizar-la dins de l’expressió musical que l’envolta, enlloc d’usar el valor de la variable directament.

Per això, les expressions musicals de l’Scheme escrites amb la sintaxi de coixinet # s’haurien d’utilitzar per a qualsevol material creat ‘partint de zero’ (o que s’hagi copiat explícitament) enlloc d’utilitzar-se per fer referència a música directament.

Vegeu també

Manual de extensió: Sintaxi de l’Scheme del LilyPond.

A.2.3 Variables d’entrada i l’Scheme

El format d’entrada inclou la noció de variables: a l’exemple següent, s’assigna una expressió musical a una variable amb el nom de traLaLa.

traLaLa = { c'4 d'4 }

També hi ha una forma d’àmbit: a l’exemple següent, el bloc \layout també conté una variable traLaLa, que és independent de la \traLaLa externa.

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

En efecte, cada fitxer d’entrada constitueix un àmbit, i cada bloc \header, \midi i \layout son àmbits niuats dins de l’àmbit de nivell superior.

Tant les variables com els àmbits estan implementats al sistema de mòduls del Guile. A cada àmbit s’adjunta un mòdul anònim de l’Scheme. Una assignació de la forma:

traLaLa = { c'4 d'4 }

es converteix internament en una definició de l’Scheme:

(define traLaLa Valor Scheme de `…')

Això significa que les variables del LilyPond i les variables de l’Scheme es poden barregar amb llibertat. A l’excemple següent, s’emmagatzema un fragment de música a la variable traLaLa, i es duplica usant l’Scheme. El resultat s’importa dins d’un bloc \score per mitjà d’una segona variable twice:

traLaLa = { c'4 d'4 }

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

\twice

En realitat, això és un exemple força interessant. L’assignació sols té lloc després que l’analitzador sintàctic s’ha assegurat que no segueix res semblan a \addlyrics, de manera que cal comprovar el que ve a continuació. Llegeix el símbol # i l’expressió de l’Scheme següent sense avaluar-la, de forma que pot procedir a l’assignació, i posteriorment executar el codi de l’Scheme sense problema.

A.2.4 Importació de l’Scheme dins del LilyPond

L’exemple anterior mostra com ‘exportar’ expressions musicals des de l’entrada a l’intèrpret de l’Scheme. El contrari també és possible. Col·locant-lo després de $, un valor de l’Scheme s’interpreta com si hagués estat introduït en la sintaxi del LilyPond. En comptes de definir \twice, l’exemple anterior podria també haver-se escrit com

…
$(make-sequential-music newLa)

Podem utilitzar $ amb una expressió de l’Scheme a qualsevol lloc en el qual usaríem \nom després d’ahver assignat l’expressió de l’Scheme a una variable nom. Aquesta substitució es produeix dins de l’‘analitzador lèxic’, de manera que el LilyPond no arriba a assabentar-se de la diferència.

No obstant, hi ha un inconvenient, el de la mesura del temps. Si haguéssim estat usant $ en comptes de # per definir newLa a l’exemple anterior, la següent definició de l’Scheme hagués fracassat perquè traLaLa no hauria estat definida encara. Per veure una explicació d’aquest problema de moment temporal, vegeu Sintaxi de l’Scheme del LilyPond.

Un aspecte posterior convenient poden ser els operadors d ‘divisió de llistes’ $@ i #@ per a la inserció dels elements d’una llista dins del context que l’envolta. Utilitzant-los, l’última part de l’exemple es podria haver escrit com como

…
{ #@newLa }

Aquí, cada element de la llista que està emmagatzemat a newLa s’agafa en seqüència i s’insereix a la llista, com si haguéssim escrit

{ #(first newLa) #(second newLa) }

Ara bé, en totes aquestes formes, el codi de l’Scheme s’avalua en el moment en el qual el codi d’entrada encara s’està processant, ja sigui a l’analitzador lèxic o a l’analitzador sintàctic. Si ens ca que s’executi en un moment posterior, hem de consultar Funcions de l’Scheme buides, o emmagatzermar-ho dins d’un procediment.

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

…
#(nopc)
{ c'4 }

Advertiments i problemes coneguts

No és possible barregar variables de l’Scheme i del LilyPond amb l’opció --safe.

A.2.5 Propietats dels objectes

Les propietats dels objectes s’emmagatzemen al LilyPond en forma de cadenes de llistes-A, que són de llistes-A. Les propietats s’estableixen afegint valors al principi de la llista de propietats. Les propietats es llegeixen extraient valors de les llistes-A.

L’establiment d’un valor nou per a una propietat requereix l’assignació d’un valor a la llista-A amb una clau i un valor. La sintaxi del LilyPond per fer això és la següent:

\override Stem.thickness = #2.6

Aquesta ordre ajusta l’aspecte de les pliques. S’afegeix una entrada de llista-A '(thickness . 2.6) a la llista de propietats d’un objecte Stem. thickness es mesura a partir del gruix de les línies del pentagrama, i així aquestes pliques seran 2.6 vegades el gruix de les línies del pentagrama. Això fa que les pliques siguin gairebé el doble de gruixudes del normal. Per distingir entre les variables que es defineixen als fitxers d’entrada (como vintiQuatre a l’exemple anterior) i les variables dels objectes propers, anomenarem a les últimes ‘propietats’ i a les primeres ‘variables.’ Així, l’objecte plica té una propietat thickness (gruix), mentre que vintiQuatre és una variable. mientras que veintiCuatro es una variable.

A.2.6 Variables del LilyPond compostes

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

A.2.7 Representació interna de la música

Internament, la música es representa com una llista de l’Scheme. la llista conté diversos elements que afecten a la sortida impresa. L’anàlisi sintàctica és el procés de convertir la música de la representació d’entrada del LilyPond a la representació interna de l’Scheme.

Quan s’analitza una expressió musical, es converteix en un conjunt d’objectes musicals de l’Scheme. La propietat definitòria d’un objecte musical és que ocupa un temps. El temps que ocupa s’anomena duració. Les duracions s’expressen com un nombre racional que mesura la longitud de l’objecte musical en rodones.

Un objecte musical té tres classes de tipus:

• nom musical: Cada expressió musical té un nom. Per exemple, una nota porta a un NoteEvent, i \simultaneous porta a una SimultaneousMusic. Hi ha una llista de totes les expressions disponibles al manual de funcionament intern, sota l’epígraf Music expressions.
• ‘type’ (tipus) o interfície: Cada nom musical té diversos ‘tipus’ o interfícies, per exemple, una nota és un event, pero también es un note-event, un rhythmic-event, i un melodic-event. Totes les classes de música estan llistades en el manual de Referència de funcionament intern, sota l’epígraf Music classes.
• objecte de C++: Cada objecte està representat per un objecte de la classe Music de C++.

La informació real d’una expressió musical s’emmagatzema en propietats. Per exemple, un NoteEvent té propietats pitch i duration que emmagatzemen l’altura i la duració d’aquesta nota. HI ha una llista de totes les propietats disponibles al manual de Referència de funcionament intern, sota l’epígraf Music properties.

Una expresión musical compuesta es un objeto musical que contiene otros objetos musicales dentro de sus propiedades. Se puede almacenar una lista de objetos dentro de la propiedad elements de un objeto musical, o un único objeto musical ‘hijo’ dentro de la propiedad element. Por ejemplo, SequentialMusic tiene su hijo dentro de elements, y GraceMusic tiene su argumento único dentro de element. El cuerpo de una repetición se almacena dentro de la propiedad element de RepeatedMusic, y las alternativas dentro de elements.

A.3.1 Presentación de las expresiones musicales

Si se está escribiendo una función musical, puede ser muy instructivo examinar cómo se almacena internamente una expresión musical. Esto se puede hacer con la función musical \displayMusic.

{
  \displayMusic { c'4\f }
}

imprime lo siguiente:

(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))))

De forma predeterminada, LilyPond imprime estos mensajes sobre la consola junto al resto de los mensajes. Para separar estos mensajes y guardar el resultado de \display{LOQUESEA}, puede especificar que se use un puerto de salida opcional:

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

Esto sobreescribe el archivo de salida anterior cada vez ques e llama; si necesitamos escribir más de una expresión, debemos usar una variable para el puerto y reutilizarla:

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

El manual de Guile describe los puertos detalladamente. Solo es realmente necesario cerrar el puerto si necesitamos leer el archivo antes de que LilyPond termine; en el primer ejemplo, no nos hemos molestado en hacerlo.

Un poco de reformateo hace a la información anterior más fácil de leer:

(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))))

Una secuencia musical { … } tiene el nombre SequentialMusic, y sus expresiones internas se almacenan coma una lista dentro de su propiedad 'elements. Una nota se representa como un objeto NoteEvent (que almacena las propiedades de duración y altura) con información adjunta (en este caso, un evento AbsoluteDynamicEvent con una propiedad "f" de texto) almacenada en su propiedad articulations.

\displayMusic devuelve la música que imprime en la consola, y por ello se interpretará al tiempo que se imprime en la consola. Para evitar la interpretación, escriba \void antes de \displayMusic.

A.3.2 Propiedades musicales

Veamos un ejemplo:

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

El objeto NoteEvent es la representación de someNote. Sencillo. ¿Y si ponemos el c’ dentro de un acorde?

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))))

Ahora el objeto NoteEvent es el primer objeto de la propiedad 'elements de someNote.

La función display-scheme-music es la función que se usa por parte de \displayMusic para imprimir la representación de Scheme de una expresión musical.

#(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))

Después se accede a la altura de la nota a través de la propiedad 'pitch del objeto NoteEvent:

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

La altura de la nota se puede cambiar estableciendo el valor de esta propiedad 'pitch.

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

A.3.3 Duplicar una nota con ligaduras (ejemplo)

Supongamos que queremos crear una función que convierte una entrada como a en { a( a) }. Comenzamos examinando la representación interna de la música con la que queremos terminar.

\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))))

La mala noticia es que las expresiones SlurEvent se deben añadir ‘dentro’ de la nota (dentro de la propiedad articulations).

Ahora examinamos la entrada.

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

Así pues, en nuestra función, tenemos que clonar esta expresión (de forma que tengamos dos notas para construir la secuencia), añadir SlurEvent a la propiedad 'articulations de cada una de ellas, y por último hacer una secuencia SequentialMusic con los dos elementos NoteEvent. Para añadir a una propiedad, es útil saber que una propiedad no establecida se lee como '(), la lista vacía, así que no se requiere ninguna comprobación especial antes de que pongamos otro elemento delante de la propiedad articulations.

doubleSlur = #(define-music-function (note) (ly:music?)
         "Return: { note ( note ) }.
         `note' is supposed to be a single note."
         (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))))

A.3.4 Añadir articulaciones a las notas (ejemplo)

La manera fácil de añadir articulación a las notas es juxtaponer dos expresiones musicales. Sin embargo, supongamos que queremos escribir una función musical que lo haga.

Una $variable dentro de la notación #{…#} es como una \variable normal en la notación clásica de LilyPond. Podríamos escribir

{ \music -. -> }

pero a los efectos de este ejemplo, aprenderemos ahora cómo hacerlo en Scheme. Empezamos examinando nuestra entrada y la salida deseada.

%  input
\displayMusic c4
===>
(make-music
  'NoteEvent
  'duration
  (ly:make-duration 2 0 1/1)
  'pitch
  (ly:make-pitch -1 0 0))))
=====
%  desired output
\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))

Vemos que una nota (c4) se representa como una expresión NoteEvent. Para añadir una articulación de acento, se debe añadir una expresión ArticulationEvent a la propiedad articulations de la expresión NoteEvent.

Para construir esta función, empezamos con

(define (add-accent note-event)
  "Add an accent ArticulationEvent to the articulations of `note-event',
  which is supposed to be a NoteEvent expression."
  (set! (ly:music-property note-event 'articulations)
        (cons (make-music 'ArticulationEvent
                'articulation-type 'accent)
              (ly:music-property note-event 'articulations)))
  note-event)

La primera línea es la forma de definir una función en Scheme: el nombre de la función es add-accent, y tiene una variable llamada note-event. En Scheme, el tipo de variable suele quedar claro a partir de su nombre (¡esto también es una buena práctica en otros lenguajes de programación!)

"Add an accent…"

es una descripción de lo que hace la función. No es estrictamente necesaria, pero de igual forma que los nombres claros de variable, es una buena práctica.

Se preguntará por qué modificamos el evento de nota directamente en lugar de trabajar sobre una copia (se puede usar ly:music-deep-copy para ello). La razón es un contrato silencioso: se permite que las funciones musicales modifiquen sus argumentos; o bien se generan partiendo de cero (como la entrada del usuario) o están ya copiadas (referenciar una variable de música con ‘\name’ o la música procedente de expresiones de Scheme inmediatas ‘$(…)’ proporcionan una copia). Dado que sería ineficiente crear copias innecesarias, el valor devuelto de una función musical no se copia. Así pues, para cumplir dicho contrato, no debemos usar ningún argumento más de una vez, y devolverlo cuenta como una vez.

En un ejemplo anterior, hemos construido música mediante la repetición de un argumento musical dado. En tal caso, al menos una repetidión tuvo que ser una copia de sí misma. Si no lo fuese, podrían ocurrir cosas muy extrañas. Por ejemplo, si usamos \relative o \transpose sobre la música resultante que contiene los mismos elementos varias veces, estarían sujetos varias veces a la relativización o al transporte. Si los asignamos a una variable de música, se rompe el curso porque hacer referencia a ‘\name’ creará de nuevo una copia que no retiene la identidad de los elementos repetidos.

Ahora bien, aun cuando la función anterior no es una función musical, se usará normalmente dentro de funciones musicales. Así pues, tiene sentido obedecer el mismo convenio que usamos para las funciones musicales: la entrada puede modificarse para producir la salida, y el código que llama es responsable de crear las copias si aún necesita el propio argumento sin modificar. Si observamos las propias funciones de LilyPond como music-map, veremos que se atienen a los mismos principios.

¿En qué punto nos encontramos? Ahora tenemos un note-event que podemos modificar, no a causa de la utilización de ly:music-deep-copy sino por una explicación muy desarrollada. Añadimos el acento a su propiedad de lista 'articulations.

(set! place new-value)

Aquí, lo que queremos establecer (el ‘place’) es la propiedad 'articulations de la expresión note-event.

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

ly:music-property es la función ustilizada para acceder a las propiedades musicales (las 'articulations, 'duration, 'pitch, etc, que vemos arriba en la salida de \displayMusic). El nuevo valor es la antigua propiedad 'articulations, con un elemento adicional: la expresión ArticulationEvent, que copiamos a partir de la salida de \displayMusic,

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

Se usa cons para añadir un elemento a la parte delantera de una lista sin modificar la lista original. Esto es lo que queremos: la misma lista de antes, más la nueva expresión ArticulationEvent. El orden dentro de la propiedad 'articulations no tiene importancia aquí.

Finalmente, una vez hemos añadido la articulación de acento a su propiedad articulations, podemos devolver note-event, de aquí la última línea de la función.

Ahora transformamos la función add-accent en una función musical (es cuestión de un poco de aderezo sintáctico y una declaración del tipo de su argumento).

addAccent = #(define-music-function (note-event)
                                     (ly:music?)
  "Add an accent ArticulationEvent to the articulations of `note-event',
  which is supposed to be a NoteEvent expression."
  (set! (ly:music-property note-event 'articulations)
        (cons (make-music 'ArticulationEvent
                'articulation-type 'accent)
              (ly:music-property note-event 'articulations)))
  note-event)

A continuación verificamos que esta función musical funciona correctamente:

\displayMusic \addAccent c4