LilyPond — Extender

A.1.1 Cajón de arena de Scheme

La instalación de LilyPond incluye también la de la implementación Guile de Scheme. Sobre casi todos los sistemas puede experimentar en una “caja de arena” de Scheme abriendo una ventana del terminal y tecleando ‘guile’. En algunos sistemas, sobre todo en Windows, podría necesitar ajustar la variable de entorno GUILE_LOAD_PATH a la carpeta ../usr/share/guile/1.8 dentro de la instalación de LilyPond (para conocer la ruta completa a esta carpeta, consulte Otras fuentes de información). Como alternativa, los usuarios de Windows pueden seleccionar simplemente ‘Ejecutar’ del menú Inicio e introducir ‘guile’.

Sin embargo, está disponible un cajón de arena de Scheme listo para funcionar con todo LilyPond cargado, con esta instrucción de la línea de órdenes:

lilypond scheme-sandbox

Una vez está funcionando el cajón de arena, verá un indicador del sistema de Guile:

guile>

Podemos introducir expresiones de Scheme en este indicador para experimentar con Scheme. Si quiere usar la biblioteca readline de GNU para una más cómoda edición de la línea de órdenes de Scheme, consulte el archivo ly/scheme-sandbox.ly para más información. Si ya ha activado la biblioteca readline para las sesiones de Guile interactivas fuera de LilyPond, debería funcionar también en el cajón de arena.

A.1.2 Variables de Scheme

Las variables de Scheme pueden tener cualquier valor válido de Scheme, incluso un procedimiento de Scheme.

Las variables de Scheme se crean con define:

guile> (define a 2)
guile>

Las variables de Scheme se pueden evaluar en el indicador del sistema de guile, simplemente tecleando el nombre de la variable:

guile> a
2
guile>

Las variables de Scheme se pueden imprimir en la pantalla utilizando la función display:

guile> (display a)
2guile>

Observe que el valor 2 y el indicador del sistema guile se muestran en la misma línea. Esto se puede evitar llamando al procedimiento de nueva línea o imprimiendo un carácter de nueva línea.

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

Una vez que se ha creado una variable, su valor se puede modificar con set!:

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

A.1.3 Tipos de datos simples de Scheme

El concepto más básico de un lenguaje son sus tipos de datos: números, cadenas de caracteres, listas, etc. He aquí una lista de los tipos de datos que son de relevancia respecto de la entrada de LilyPond.

Booleanos

Los valores Booleanos son Verdadero y Falso. Verdadero en Scheme es #t y Falso es #f.

Números

Los números se escriben de la forma normal, 1 es el número (entero) uno, mientras que -1.5 es un número en coma flotante (un número no entero).

Cadenas

Las cadenas se encierran entre comillas:

"esto es una cadena"

Las cadenas pueden abarcar varias líneas:

"esto
es
una cadena"

y los caracteres de nueva línea al final de cada línea se incluirán dentro de la cadena.

Los caracteres de nueva línea también se pueden añadir mediante la inclusión de \n en la cadena.

"esto\nes una\ncadena de varias líneas"

Las comillas dobles y barras invertidas se añaden a las cadenas precediéndolas de una barra invertida. La cadena \a dijo "b" se introduce como

"\\a dijo \"b\""

Existen más tipos de datos de Scheme que no se estudian aquí. Para ver un listado completo, consulte la guía de referencia de Guile, https://www.gnu.org/software/guile/docs/docs-1.8/guile-ref/Simple-Data-Types.html.

A.1.4 Tipos de datos compuestos de Scheme

También existen tipos de datos compuestos en Scheme. Entre los tipos más usados en la programación de LilyPond se encuentran las parejas, las listas, las listas-A y las tablas 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> (define mipareja (cons 123 "Hola")
… )
guile> (car mipareja)
123
guile> (cdr mipareja)
"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 "fulano" "mengano" "zutano")
(17 23 "fulano" "mengano" "zutano")

guile> (define mi-lista-a '((1  . "A") (2 . "B") (3 . "C")))
guile> mi-lista-a
((1 . "A") (2 . "B") (3 . "C"))
guile> (assoc 2 mi-lista-a)
(2 . "B")
guile> (cdr (assoc 2 mi-lista-a))
"B"
guile>

guile> (define 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álculos en Scheme

Scheme se puede usar para hacer cálculos. Utiliza sintaxis prefija. Sumar 1 y 2 se escribe como (+ 1 2) y no como el tradicional 1+2.

guile> (+ 1 2)
3

Los cálculos se pueden anidar; el resultado de una función se puede usar para otro cálculo.

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

Estos cálculos son ejemplos de evaluaciones; una expresión como (* 3 4) se sustituye por su valor 12.

Los cálculos de Scheme son sensibles a las diferencias entre enteros y no enteros. Los cálculos enteros son exactos, mientras que los no enteros se calculan con los límites de precisión adecuados:

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

Cuando el intérprete de Scheme encuentra una expresión que es una lista, el primer elemento de la lista se trata como un procedimiento a evaluar con los argumentos del resto de la lista. Por tanto, todos los operadores en Scheme son operadores prefijos.

Si el primer elemento de una expresión de Scheme que es una lista que se pasa al intérprete no es un operador o un procedimiento, se produce 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í podemos ver que el intérprete estaba intentando tratar el 1 como un operador o procedimiento, y no pudo hacerlo. De aquí que el error sea "Wrong type to apply: 1".

Así pues, para crear una lista debemos usar el operador de lista, o podemos precederla de un apóstrofo para que el intérprete no trate de evaluarla.

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

Esto es un error que puede aparecer cuando trabaje con Scheme dentro de LilyPond.

A.1.6 Procedimientos de Scheme

Los procedimientos de Scheme son expresiones de Scheme ejecutables que devuelven un valor resultante de su ejecución. También pueden manipular variables definidas fuera del procedimiento.

(define (nombre-de-la-función arg1 arg2 ... argn)
 expresión-de-scheme-que-devuelve-un-valor)

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

guile> (media 3 12)
15/2

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

(if expresión-de-prueba expresión-de-cierto expresión-de-falso)

guile> (define a 3)
guile> (define b 5)
guile> (if (> a b) "a es mayor que b" "a no es mayor que b")
"a no es mayor que b"

(cond (expresión-de-prueba-1 secuencia-de-expresiones-resultante-1)
      (expresión-de-prueba-2 secuencia-de-expresiones-resultante-2)
      …
      (expresión-de-prueba-n secuencia-de-expresiones-resultante-n))

guile> (define a 6)
guile> (define b 8)
guile> (cond ((< a b) "a es menor que b")
...          ((= a b) "a es igual a b")
...          ((> a b) "a es mayor que b"))
"a es menor que b"

A.2.1 Sintaxis del Scheme de LilyPond

El intérprete Guile forma parte de LilyPond, lo que significa que se puede incluir Scheme dentro de los archivos de entrada de LilyPond. Existen varios métodos para incluir Scheme dentro de LilyPond.

La manera más sencilla es utilizar el símbolo de almohadilla # antes de una expresión de Scheme.

Ahora bien, el código de entrada de LilyPond se estructura en elementos y expresiones, de forma parecida a cómo el lenguaje humano se estructura en palabras y frases. LilyPond tiene un analizador léxico que reconoce elementos indivisibles (números literales, cadenas de texto, elementos de Scheme, nombres de nota, etc.), y un analizador que entiende la sintaxis, la Gramática de LilyPond (LilyPond grammar). Una vez que sabe que se aplica una regla sintáctica concreta, ejecuta las acciones asociadas con ella.

El método del símbolo de almohadilla # para incrustar Scheme se adapta de forma natural a este sistema. Una vez que el analizador léxico ve un símbolo de almohadilla, llama al lector de Scheme para que lea una expresión de Scheme completa (que puede ser un identificador, una expresión encerrada entre paréntesis, o algunas otras cosas). Después de que se ha leído la expresión de Scheme, se almacena como el valor de un elemento SCM_TOKEN de la gramática. Después de que el analizador sintáctico ya sabe cómo hacer uso de este elemento, llama a Guila para que evalúe la expresión de Scheme. Dado que el analizador sintáctico suele requerir un poco de lectura por delante por parte del analizador léxico para tomar sus decisiones de análisis sintáctico, esta separación de lectura y evaluación entre los analizadores léxico y sintáctico es justamente lo que se necesita para mantener sincronizadas las ejecuciones de expresiones de LilyPond y de Scheme. Por este motivo se debe usar el símbolo de almohadilla # para llamar a Scheme siempre que sea posible.

Otra forma de llamar al intérprete de Scheme desde LilyPond es el uso del símbolo de dólar $ en lugar de la almohadilla para introducir las expresiondes de Scheme. En este caso, LilyPond evalúa el código justo después de que el analizador léxico lo ha leído. Comprueba el tipo resultante de la expresión de Scheme y después selecciona un tipo de elemento (uno de los varios elementos xxx_IDENTIFIER dentro de la sintaxis) para él. Crea una copia del valor y la usa como valor del elemento. Si el valor de la expresión es vacío (El valor de Guile de *unspecified*), no se pasa nada en absoluto al analizador sintáctico.

Éste es, de hecho, el mismo mecanismo exactamente que LilyPond emplea cuando llamamos a cualquier variable o función musical por su nombre, como \nombre, con la única diferencia de que el nombre viene determinado por el analizador léxico de LilyPond sin consultar al lector de Scheme, y así solamente se aceptan los nombres de variable consistentes con el modo actual de LilyPond.

La acción inmediata de $ puede llevar a alguna que otra sorpresa, véase Importación de Scheme dentro de LilyPond. La utilización de # donde el analizador sintáctico lo contempla es normalmente preferible. Dentro de las expresiones musicales, aquellas que se crean utilizando # se interprentan como música. Sin embargo, no se copian antes de ser utilizadas. Si forman parte de alguna estructura que aún podría tener algún uso, quizá tenga que utilizar explícitamente ly:music-deep-copy.

También existen los operadores de ‘división de listas’ $@ y #@ que insertan todos los elementos de una lista dentro del contexto circundante.

Ahora echemos un vistazo a algo de código de Scheme real. Los procedimientos de Scheme se pueden definir dentro de los archivos de entrada de LilyPond:

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

Observe que los comentarios de LilyPond (% y %{ %}) no se pueden utilizar dentro del código de Scheme, ni siquiera dentro de un archivo de entrada de LilyPond, porque es el intérprete Guile, y no el analizador léxico de LilyPond, el que está leyendo la expresión de Scheme. Los comentarios en el Scheme de Guile se introducen como sigue:

; esto es un comentario de una línea

#!
  Esto es un comentario de bloque (no anidable) estilo Guile
  Pero se usan rara vez por parte de los Schemers
  y nunca dentro del código fuente de LilyPond
!#

Durante el resto de esta sección, supondremos que los datos se introducen en un archivo de música, por lo que añadiremos una almohadilla # al principio de cada una de las expresiones de Scheme.

Todas las expresiones de Scheme del nivel jerárquico superior dentro de un archivo de entrada de LilyPond se pueden combinar en una sola expresión de Scheme mediante la utilización del operador begin:

#(begin
  (define fulanito 0)
  (define menganito 1))

A.2.2 Variables de LilyPond

Las variables de LilyPond se almacenan internamente en la forma de variables de Scheme. Así,

doce = 12

equivale a

#(define doce 12)

Esto significa que las variables de LilyPond están disponibles para su uso dentro de expresiones de Scheme. Por ejemplo, podríamos usar

veintiCuatro = (* 2 doce)

lo que daría lugar a que el número 24 se almacenase dentro de la variable veintiCuatro de LilyPond (y de Scheme).

El lenguaje Scheme permite la modificación de expresiones complejas in situ y LilyPond hace uso de esta ‘modificación in situ’ al usar funciones musicales. Pero cuando las expresiones musicales se almacenan dentro de variables en lugar de ser introducidas directamente, lo que habitualmente se espera cuando se pasan a funciones musicales sería que el valor original quedase intacto. Así pues, cuando se referencia una variable musical con la barra invertida (como \veintiCuatro), LilyPond crea una copia del valor musical de tal variable para utilizarla dentro de la expresión musical circundante, en lugar de usar el valor de la variable directamente.

Por ello, las expresiones musicales de Scheme escritas con la sintasis de almohadilla # deberían utilizarse para cualquier material creado ‘partiendo de cero’ (o que se ha copiado explícitamente) en lugar de utilizarse para referenciar música directamente.

Véase también

Manual de extensión: Sintaxis del Scheme de LilyPond.

A.2.3 Variables de entrada y Scheme

El formato de entrada contempla la noción de variables: en el siguiente ejemplo, se asigna una expresión musical a una variable con el nombre traLaLa.

traLaLa = { c'4 d'4 }

También hay una forma de ámbito: en el ejemplo siguiente, el bloque \layout también contiene una variable traLaLa, que es independiente de la \traLaLa externa.

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

En efecto, cada archivo de entrada constituye un ámbito, y cada bloque \header, \midi y \layout son ámbitos anidados dentro del ámbito de nivel superior.

Tanto las variables como los ámbitos están implementados en el sistema de módulos de Guile. A cada ámbito se adjunta un módulo anónimo de Scheme. Una asignación de la forma:

traLaLa = { c'4 d'4 }

se convierte internamente en una definición de Scheme:

(define traLaLa Valor Scheme de `…')

Esto significa que las variables de LilyPond y las variables de Scheme se pueden mezclar con libertad. En el ejemplo siguiente, se almacena un fragmento de música en la variable traLaLa, y se duplica usando Scheme. El resultado se importa dentro de un bloque \score por medio de una segunda 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 realidad, éste es un ejemplo bastante interesante. La asignación solo tiene lugar después de que el analizador sintáctico se ha asegurado de que no sigue nada parecido a \addlyrics, de manera que necesita comprobar lo que viene a continuación. Lee el símbolo # y la expresión de Scheme siguiente sin evaluarla, de forma que puede proceder a la asignación, y posteriormente ejecutar el código de Scheme sin problema.

A.2.4 Importación de Scheme dentro de LilyPond

El ejemplo anterior muestra cómo ‘exportar’ expresiones musicales desde la entrada al intérprete de Scheme. Lo contrario también es posible. Colocándolo después de $, un valor de Scheme se interpreta como si hubiera sido introducido en la sintaxis de LilyPond. En lugar de definir \twice, el ejemplo anterior podría también haberse escrito como

…
$(make-sequential-music newLa)

Podemos utilizar $ con una expresión de Scheme en cualquier lugar en el que usaríamos \nombre después de haber asignado la expresión de Scheme a una variable nombre. Esta sustitución se produce dentro del ‘analizador léxico’, de manera que LilyPond no llega a darse cuenta de la diferencia.

Sin embargo, existe un inconveniente, el de la medida del tiempo. Si hubiésemos estado usando $ en vez de # para definir newLa en el ejemplo anterior, la siguiente definición de Scheme habría fracasado porque traLaLa no habría sido definida aún. Para ver una explicación de este problema de momento temporal, véase Sintaxis del Scheme de LilyPond.

Un conveniente aspecto posterior pueden ser los operadores de ‘división de listas’ $@ y #@ para la inserción de los elementos de una lista dentro del contexto circundante. Utilizándolos, la última parte del ejemplo se podría haber escrito como

…
{ #@newLa }

Aquí, cada elemento de la lista que está almacenado en newLa se toma en secuencia y se inserta en la lista, como si hubiésemos escrito

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

Ahora bien, en todas esas formas, el código de Scheme se evalúa en el momento en que el código de entrada aún se está procesando, ya sea en el analizador léxico o en el analizador sintáctico. Si necesitamos que se ejecute en un momento posterior, debemos consultar Funciones de Scheme vacías, o almacenarlo dentro de un procedimiento:

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

…
#(nopc)
{ c'4 }

Advertencias y problemas conocidos

No es posible mezclar variables de Scheme y de LilyPond con la opción --safe.

A.2.5 Propiedades de los objetos

Las propiedades de los objetos se almacenan en LilyPond en forma de cadenas de listas-A, que son listas de listas-A. Las propiedades se establecen añadiendo valores al principio de la lista de propiedades. Las propiedades se leen extrayendo valores de las listas-A.

El establecimiento de un valor nuevo para una propiedad requiere la asignación de un valor a la lista-A con una clave y un valor. La sintaxis de LilyPond para hacer esto es la siguiente:

\override Stem.thickness = #2.6

Esta instrucción ajusta el aspecto de las plicas. Se añade una entrada de lista-A '(thickness . 2.6) a la lista de propiedades de un objeto Stem. thickness se mide a partir del grosor de las líneas del pentagrama, y así estas plicas serán 2.6 veces el grosor de las líneas del pentagrama. Esto hace que las plicas sean casi el doble de gruesas de lo normal. Para distinguir entre las variables que se definen en los archivos de entrada (como veintiCuatro en el ejemplo anterior) y las variables de los objetos internos, llamaremos a las últimas ‘propiedades’ y a las primeras ‘variables.’ Así, el objeto plica tiene una propiedad thickness (grosor), mientras que veintiCuatro es una variable.

A.2.6 Variables de LilyPond compuestas

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

A.2.7 Representación interna de la música

Internamente, la música se representa como una lista de Scheme. La lista contiene varios elementos que afectan a la salida impresa. El análisis sintáctico es el proceso de convertir la música de la representación de entrada de LilyPond a la representación interna de Scheme.

Cuando se analiza una expresión musical, se convierte en un conjunto de objetos musicales de Scheme. La propiedad definitoria de un objeto musical es que ocupa un tiempo. El tiempo que ocupa se llama duración. Las duraciones se expresan como un número racional que mide la longitud del objeto musical en redondas.

Un objeto musical tiene tres clases de tipos:

• nombre musical: Cada expresión musical tiene un nombre. Por ejemplo, una nota lleva a un NoteEvent, y \simultaneous lleva a una SimultaneousMusic. Hay una lista de todas las expresiones disponibles en el manual de Referencia de funcionamiento interno, bajo el epígrafe Music expressions.
• ‘type’ (tipo) o interface: Cada nombre musical tiene varios ‘tipos’ o interfaces, por ejemplo, una nota es un event, pero también es un note-event, un rhythmic-event, y un melodic-event. Todas las clases de música están listadas en el manual de Referencia de funcionamiento interno, bajo el epígrafe Music classes.
• objeto de C++: Cada objeto musical está representado por un objeto de la clase Music de C++.

La información real de una expresión musical se almacena en propiedades. Por ejemplo, un NoteEvent tiene propiedades pitch y duration que almacenan la altura y la duración de esa nota. Hay una lista de todas la propiedades disponibles en el manual de Referencia de funcionamiento interno, bajo el epígrafe 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 VoltaRepeatedMusic, 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