1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
4 Translation of GIT committish: 1f0a00b69403290b7fc7527b9ab100f95533f954
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. For details, see the Contributors'
8 Guide, node Updating translation committishes..
13 @node Tutorial de Scheme
14 @appendix Tutorial de Scheme
15 @translationof Scheme tutorial
19 @cindex Scheme, código en línea
20 @cindex acceder a Scheme
21 @cindex evaluar Scheme
24 LilyPond utiliza el lenguaje de programación Scheme, tanto como parte
25 de la sintaxis del código de entrada, como para servir de mecanismo
26 interno que une los módulos del programa entre sí. Esta sección es
27 una panorámica muy breve sobre cómo introducir datos en Scheme. Si
28 quiere saber más sobre Scheme, consulte
29 @uref{http://@/www@/.schemers@/.org}.
31 LilyPond utiliza la implementación GNU Guile de Scheme, que está
32 basada en el estándar @qq{R5RS} del lenguaje. Si está aprendiendo
33 Scheme para usarlo con LilyPond, no se recomienda trabajar con una
34 implementación distinta (o que se refiera a un estándar diferente).
35 Hay información sobre Guile en
36 @uref{http://www.gnu.org/software/guile/}. El estándar de Scheme
37 @qq{R5RS} se encuentra en
38 @uref{http://www.schemers.org/Documents/Standards/R5RS/}.
41 * Introducción a Scheme::
42 * Scheme dentro de LilyPond::
43 * Construir funciones complicadas::
46 @node Introducción a Scheme
47 @section Introducción a Scheme
48 @translationof Introduction to Scheme
50 Comenzaremos con una introducción a Scheme. Para esta breve
51 introducción utilizaremos el intérprete GUILE para explorar la manera
52 en que el lenguaje funciona. Una vez nos hayamos familiarizado con
53 Scheme, mostraremos cómo se puede integrar el lenguaje en los archivos
58 * Cajón de arena de Scheme::
59 * Variables de Scheme::
60 * Tipos de datos simples de Scheme::
61 * Tipos de datos compuestos de Scheme::
62 * Cálculos en Scheme::
63 * Procedimientos de Scheme::
64 * Condicionales de Scheme::
67 @node Cajón de arena de Scheme
68 @subsection Cajón de arena de Scheme
69 @translationof Scheme sandbox
71 La instalación de LilyPond incluye también la de la implementación
72 Guile de Scheme. Sobre casi todos los sistemas puede experimentar en
73 una @qq{caja de arena} de Scheme abriendo una ventana del terminal y
74 tecleando @q{guile}. En algunos sistemas, sobre todo en Windows,
75 podría necesitar ajustar la variable de entorno @code{GUILE_LOAD_PATH}
76 a la carpeta @code{../usr/shr/guile/1.8} dentro de la instalación de
77 LilyPond (para conocer la ruta completa a esta carpeta, consulte
78 @rlearning{Otras fuentes de información}). Como alternativa, los
79 usuarios de Windows pueden seleccionar simplemente @q{Ejecutar} del
80 menú Inicio e introducir @q{guile}.
82 Sin embargo, está disponible un cajón de arena de Scheme listo para
83 funcionar con todo LilyPond cargado, con esta instrucción de la línea
86 lilypond scheme-sandbox
90 Una vez está funcionando el cajón de arena, verá un indicador
97 Podemos introducir expresiones de Scheme en este indicador para
98 experimentar con Scheme.
100 @node Variables de Scheme
101 @subsection Variables de Scheme
102 @translationof Scheme variables
104 Las variables de Scheme pueden tener cualquier valor válido de Scheme,
105 incluso un procedimiento de Scheme.
107 Las variables de Scheme se crean con @code{define}:
114 Las variables de Scheme se pueden evaluar en el indicador del sistema
115 de guile, simplemente tecleando el nombre de la variable:
123 Las variables de Scheme se pueden imprimir en la pantalla utilizando
132 Observe que el valor @code{2} y el indicador del sistema @code{guile}
133 se muestran en la misma línea. Esto se puede evitar llamando al
134 procedimiento de nueva línea o imprimiendo un carácter de nueva línea.
137 guile> (display a)(newline)
139 guile> (display a)(display "\n")
144 Una vez que se ha creado una variable, su valor se puede modificar con
148 guile> (set! a 12345)
154 @node Tipos de datos simples de Scheme
155 @subsection Tipos de datos simples de Scheme
156 @translationof Scheme simple data types
158 El concepto más básico de un lenguaje son sus tipos de datos: números,
159 cadenas de caracteres, listas, etc. He aquí una lista de los tipos de
160 datos que son de relevancia respecto de la entrada de LilyPond.
164 Los valores Booleanos son Verdadero y Falso. Verdadero en Scheme es
165 @code{#t} y Falso es @code{#f}.
170 Los números se escriben de la forma normal, @code{1} es el número
171 (entero) uno, mientras que @w{@code{-1.5}} es un número en coma flotante
172 (un número no entero).
175 Las cadenas se encierran entre comillas:
181 Las cadenas pueden abarcar varias líneas:
190 y los caracteres de nueva línea al final de cada línea se incluirán
193 Los caracteres de nueva línea también se pueden añadir mediante la
194 inclusión de @code{\n} en la cadena.
197 "esto\nes una\ncadena de varias líneas"
201 Las comillas dobles y barras invertidas se añaden a las cadenas
202 precediéndolas de una barra invertida. La cadena @code{\a dijo "b"}
211 Existen más tipos de datos de Scheme que no se estudian aquí. Para
212 ver un listado completo, consulte la guía de referencia de Guile,
213 @uref{http://www.gnu.org/software/guile/manual/html_node/Simple-Data-Types.html}.
215 @node Tipos de datos compuestos de Scheme
216 @subsection Tipos de datos compuestos de Scheme
217 @translationof Scheme compound data types
219 También existen tipos de datos compuestos en Scheme. Entre los tipos
220 más usados en la programación de LilyPond se encuentran las parejas,
221 las listas, las listas-A y las tablas de hash.
225 El tipo fundacional de datos compuestos de Scheme es la @code{pareja}.
226 Como se espera por su nombre, una pareja son dos valores unidos en uno
227 solo. El operador que se usa para formar una pareja se llama
236 Observe que la pareja se imprime como dos elementos rodeados por
237 paréntesis y separados por un espacio, un punto (@code{.}) y otro
238 espacio. El punto @emph{no es} un punto decimal, sino más bien un
241 Las parejas también se pueden introducir como valores literales
242 precediéndolos de un carácter de comilla simple o apóstrofo.
250 Los dos elementos de una pareja pueden ser cualquier valor válido de
256 guile> '("bla-bla" . 3.1415926535)
257 ("bla-bla" . 3.1415926535)
261 Se puede accede al primero y segundo elementos de la pareja mediante
262 los procedimientos de Scheme @code{car} y @code{cdr}, respectivamente.
265 guile> (define mipareja (cons 123 "Hola")
267 guile> (car mipareja)
269 guile> (cdr mipareja)
276 Nota: @code{cdr} se pronuncia "could-er", según Sussman y Abelson,
278 @uref{http://mitpress.mit.edu/sicp/full-text/book/book-Z-H-14.html#footnote_Temp_133}
283 Una estructura de datos muy común en Scheme es la @emph{lista}.
284 Formalmente, una lista se define como la lista vacía (representada
285 como @code{'()}, o bien como una pareja cuyo @code{cdr} es una lista.
287 Existen muchas formas de crear listas. Quizá la más común es con el
288 procedimiento @code{list}:
291 guile> (list 1 2 3 "abc" 17.5)
295 Como se ve, una lista se imprime en la forma de elementos individuales
296 separados por espacios y encerradas entre paréntesis. A diferencia de
297 las parejas, no hay ningún punto entre los elementos.
299 También se puede escribir una lista como una lista literal encerrando
300 sus elementos entre paréntesis y añadiendo un apóstrofo:
303 guile> '(17 23 "fulano" "mengano" "zutano")
304 (17 23 "fulano" "mengano" "zutano")
307 Las listas son una parte fundamental de Scheme. De hecho, Scheme se
308 considera un dialecto de Lisp, donde @q{lisp} es una abreviatura de
309 @q{List Processing} (proceso de listas). Todas las expresiones de
312 @subheading Listas asociativas (listas-A)
314 Un tipo especial de listas son las @emph{listas asociativas} o
315 @emph{listas-A}. Se puede usar una lista-A para almacenar datos para
316 su fácil recuperación posterior.
318 Las listas-A son listas cuyos elementos son parejas. El @code{car} de
319 cada elemento se llama @emph{clave}, y el @code{cdr} de cada elemento
320 se llama @emph{valor}. El procedimiento de Scheme @code{assoc} se usa
321 para recuperar un elemento de la lista-A, y @code{cdr} se usa para
325 guile> (define mi-lista-a '((1 . "A") (2 . "B") (3 . "C")))
327 ((1 . "A") (2 . "B") (3 . "C"))
328 guile> (assoc 2 mi-lista-a)
330 guile> (cdr (assoc 2 mi-lista-a))
335 Las listas-A se usan mucho en LilyPond para almacenar propiedades y
338 @subheading Tablas de hash
340 Estructuras de datos que se utilizan en LilyPond de forma ocasional.
341 Una tabla de hash es similar a una matriz, pero los índices de la
342 matriz pueden ser cualquier tipo de valor de Scheme, no sólo enteros.
344 Las tablas de hash son más eficientes que las listas-A si hay una gran
345 cantidad de datos que almacenar y los datos cambian con muy poca
348 La sintaxis para crear tablas de hash es un poco compleja, pero
349 veremos ejemplos de ello en el código fuente de LilyPond.
352 guile> (define h (make-hash-table 10))
355 guile> (hashq-set! h 'key1 "val1")
357 guile> (hashq-set! h 'key2 "val2")
359 guile> (hashq-set! h 3 "val3")
363 Los valores se recuperan de las tablas de hash mediante
367 guile> (hashq-ref h 3)
369 guile> (hashq-ref h 'key2)
374 Las claves y los valores se recuperan como una pareja con
375 @code{hashq-get-handle}. Ésta es la forma preferida, porque devuelve
376 @code{#f} si no se encuentra la clave.
379 guile> (hashq-get-handle h 'key1)
381 guile> (hashq-get-handle h 'frob)
386 @node Cálculos en Scheme
387 @subsection Cálculos en Scheme
388 @translationof Calculations in Scheme
391 Todo el tiempo hemos estado usando listas. Un cálculo, como @code{(+
392 1 2)} también es una lista (que contiene el símbolo @code{+} y los
393 números 1 y@tie{}2). Normalmente, las listas se interpretan como
394 cálculos, y el intérprete de Scheme sustituye el resultado del
395 cálculo. Para escribir una lista, detenemos la evaluación. Esto se
396 hace precediendo la lista por un apóstrofo @code{'}. Así, para los
397 cálculos no usamos ningún apóstrofo.
399 Dentro de una lista o pareja precedida de apóstrofo, no hay necesidad
400 de escribir ningún apóstrofo más. Lo siguiente es una pareja de
401 símbolos, una lista de símbolos y una lista de listas respectivamente:
405 #'(staff clef key-signature)
410 Scheme se puede usar para hacer cálculos. Utiliza sintaxis
411 @emph{prefija}. Sumar 1 y@tie{}2 se escribe como @code{(+ 1 2)} y no
412 como el tradicional @math{1+2}.
419 Los cálculos se pueden anidar; el resultado de una función se puede
420 usar para otro cálculo.
427 Estos cálculos son ejemplos de evaluaciones; una expresión como
428 @code{(* 3 4)} se sustituye por su valor @code{12}.
430 Los cálculos de Scheme son sensibles a las diferencias entre enteros y
431 no enteros. Los cálculos enteros son exactos, mientras que los no
432 enteros se calculan con los límites de precisión adecuados:
441 Cuando el intérprete de Scheme encuentra una expresión que es una
442 lista, el primer elemento de la lista se trata como un procedimiento a
443 evaluar con los argumentos del resto de la lista. Por tanto, todos
444 los operadores en Scheme son operadores prefijos.
446 Si el primer elemento de una expresión de Scheme que es una lista que
447 se pasa al intérprete @emph{no es} un operador o un procedimiento, se
457 <unnamed port>:52:1: In expression (1 2 3):
458 <unnamed port>:52:1: Wrong type to apply: 1
463 Aquí podemos ver que el intérprete estaba intentando tratar el 1 como
464 un operador o procedimiento, y no pudo hacerlo. De aquí que el error
465 sea "Wrong type to apply: 1".
467 Así pues, para crear una lista debemos usar el operador de lista, o
468 podemos precederla de un apóstrofo para que el intérprete no trate de
479 Esto es un error que puede aparecer cuando trabaje con Scheme dentro
483 La misma asignación se puede hacer también completamente en Scheme,
486 #(define veintiCuatro (* 2 doce))
489 @c this next section is confusing -- need to rewrite
491 El @emph{nombre} de una variable también es una expresión, similar a
492 un número o una cadena. Se introduce como
499 @cindex comillas en Scheme
501 El apóstrofo @code{'} evita que el intérprete de Scheme sustituya
502 @code{veintiCuatro} por @code{24}. En vez de esto, obtenemos el
503 nombre @code{veintiCuatro}.
507 @node Procedimientos de Scheme
508 @subsection Procedimientos de Scheme
509 @translationof Scheme procedures
511 Los procedimientos de Scheme son expresiones de Scheme ejecutables que
512 devuelven un valor resultante de su ejecución. También pueden
513 manipular variables definidas fuera del procedimiento.
515 @subheading Definir procedimientos
517 Los procedimientos se definen en Scheme con @code{define}:
520 (define (nombre-de-la-función arg1 arg2 ... argn)
521 expresión-de-scheme-que-devuelve-un-valor)
524 Por ejemplo, podemos definir un procedimiento para calcular la media:
527 guile> (define (media x y) (/ (+ x y) 2))
529 #<procedure media (x y)>
532 Una vez se ha definido un procedimiento, se llama poniendo el nombre
533 del procedimiento dentro de una lista. Por ejemplo, podemos calcular
541 @subheading Predicados
543 Los procedimientos de Scheme que devuelven valores booleanos se suelen
544 llamar @emph{predicados}. Por convenio (pero no por necesidad),
545 los nombres de predicados acaban en un signo de interrogación:
548 guile> (define (menor-que-diez? x) (< x 10))
549 guile> (menor-que-diez? 9)
551 guile> (menor-que-diez? 15)
555 @subheading Valores de retorno
557 Los procedimientos de Scheme siempre devuelven un valor de retorno,
558 que es el valor de la última expresión ejecutada en el procedimiento.
559 El valor de retorno puede ser cualquier valor de Scheme válido,
560 incluso una estructura de datos compleja o un procedimiento.
562 A veces, el usuario quiere tener varias expresiones de Scheme dentro
563 de un procedimiento. Existen dos formas en que se pueden combinar
564 distintas expresiones. La primera es el procedimiento @code{begin},
565 que permite evaluar varias expresiones, y devuelve el valor de la
569 guile> (begin (+ 1 2) (- 5 8) (* 2 2))
573 La segunda forma de combinar varias expresiones es dentro de un bloque
574 @code{let}. Dentro de un bloque let, se crean una serie de ligaduras
575 o asignaciones, y después se evalúa una secuencia de expresiones que
576 pueden incluir esas ligaduras o asignaciones. El valor de retorno del
577 bloque let es el valor de retorno de la última sentencia del bloque
581 guile> (let ((x 2) (y 3) (z 4)) (display (+ x y)) (display (- z 4))
582 ... (+ (* x y) (/ z x)))
586 @node Condicionales de Scheme
587 @subsection Condicionales de Scheme
588 @translationof Scheme conditionals
592 Scheme tiene un procedimiento @code{if}:
595 (if expresión-de-prueba expresión-de-cierto expresión-de-falso)
598 @var{expresión-de-prueba} es una expresión que devuelve un valor
599 booleano. Si @var{expresión-de-prueba} devuelve @code{#t}, el
600 procedimiento @code{if} devuelve el valor de la
601 @var{expresión-de-cierto}, en caso contrario devuelve el valor de la
602 @var{expresión-de-falso}.
607 guile> (if (> a b) "a es mayor que b" "a no es mayor que b")
608 "a no es mayor que b"
613 Otro procedimiento condicional en scheme es @code{cond}:
616 (cond (expresión-de-prueba-1 secuencia-de-expresiones-resultante-1)
617 (expresión-de-prueba-2 secuencia-de-expresiones-resultante-2)
619 (expresión-de-prueba-n secuencia-de-expresiones-resultante-n))
627 guile> (cond ((< a b) "a es menor que b")
628 ... ((= a b) "a es igual a b")
629 ... ((> a b) "a es mayor que b"))
633 @node Scheme dentro de LilyPond
634 @section Scheme dentro de LilyPond
635 @translationof Scheme in LilyPond
638 * Sintaxis del Scheme de LilyPond::
639 * Variables de LilyPond::
640 * Variables de entrada y Scheme::
641 * Propiedades de los objetos::
642 * Variables de LilyPond compuestas::
643 * Representación interna de la música::
646 @node Sintaxis del Scheme de LilyPond
647 @subsection Sintaxis del Scheme de LilyPond
648 @translationof LilyPond Scheme syntax
652 El intérprete Guile forma parte de LilyPond, lo que significa que se
653 puede incluir Scheme dentro de los archivos de entrada de LilyPond.
654 Existen varios métodos para incluir Scheme dentro de LilyPond.
656 La manera más sencilla es utilizar el símbolo de
657 almohadilla@tie{}@code{#} antes de una expresión de Scheme.
659 Ahora bien, el código de entrada de LilyPond se estructura en
660 elementos y expresiones, de forma parecida a cómo el lenguaje humano
661 se estructura en palabras y frases. LilyPond tiene un analizador
662 léxico que reconoce elementos indivisibles (números literales, cadenas
663 de texto, elementos de Scheme, nombres de nota, etc.), y un analizador
664 sintáctico que entiende la sintaxis, la @ruser{Gramática de LilyPond}.
665 Una vez que sabe que se aplica una regla sintáctica concreta, ejecuta
666 las acciones asociadas con ella.
668 El método del símbolo de almohadilla@tie{}@code{#} para incrustar
669 Scheme se adapta de forma natural a este sistema. Una vez que el
670 analizador léxico ve un símbolo de almohadilla, llama al lector de
671 Scheme para que lea una expresión de Scheme completa (que puede ser un
672 identificador, una expresión encerrada entre paréntesis, o algunas
673 otras cosas). Después de que se ha leído la expresión de Scheme, se
674 almacena como el valor de un elemento @code{SCM_TOKEN} de la
675 gramática. Después de que el analizador sintáctico ya sabe cómo hacer
676 uso de este elemento, llama a Guila para que evalúe la expresión de
677 Scheme. Dado que el analizador sintáctico suele requerir un poco de
678 lectura por delante por parte del analizador léxico para tomar sus
679 decisiones de análisis sintáctico, esta separación de lectura y
680 evaluación entre los analizadores léxico y sintáctico es justamente lo
681 que se necesita para mantener sincronizadas las ejecuciones de
682 expresiones de LilyPond y de Scheme. Por este motivo se debe usar el
683 símbolo de almohadilla@tie{}@code{#} para llamar a Scheme siempre que
686 Otra forma de llamar al intérprete de Scheme desde lilyPond es el uso
687 del símbolo de dólar@tie{}@code{$} en lugar de la almohadilla para
688 introducir las expresiondes de Scheme. En este caso, LilyPond evalúa
689 el código justo después de que el analizador léxico lo ha leído.
690 Comprueba el tipo resultante de la expresión de Scheme y después
691 selecciona un tipo de elemento (uno de los varios elementos
692 @code{xxx_IDENTIFIER} dentro de la sintaxis) para él. Crea una
693 @emph{copia} del valor y la usa como valor del elemento. Si el valor
694 de la expresión es vacío (El valor de Guile de @code{*unspecified*}),
695 no se pasa nada en absoluto al analizador sintáctico.
697 Éste es, de hecho, el mismo mecanismo exactamente que LilyPond emplea
698 cuando llamamos a cualquier variable o función musical por su nombre,
699 como @code{\nombre}, con la única diferencia de que su final viene
700 determinado por el analizador léxico de LilyPond sin consultar al
701 lector de Scheme, y así solamente se aceptan los nombres de variable
702 consistentes con el modo actual de LilyPond.
704 La acción inmediata de @code{$} puede llevar a alguna que otra
705 sorpresa, véase @ref{Variables de entrada y Scheme}. La utilización
706 de @code{#} donde el analizador sintáctico lo contempla es normalmente
709 Ahora echemos un vistazo a algo de código de Scheme real. Los
710 procedimientos de Scheme se pueden definir dentro de los archivos de
714 #(define (media a b c) (/ (+ a b c) 3))
717 Observe que los comentarios de LilyPond (@code{%} y @code{%@{ %@}}) no
718 se pueden utilizar dentro del código de Scheme, ni siquiera dentro de
719 un archivo de entrada de LilyPond, porque es el intérprete Guile, y no
720 el analizador léxico de LilyPond, el que está leyendo la expresión de
721 Scheme. Los comentarios en el Scheme de Guile se introducen como
725 ; esto es un comentario de una línea
728 Esto es un comentario de bloque (no anidable) estilo Guile
729 Pero se usan rara vez por parte de los Schemers y nunca dentro del
730 código fuente de LilyPond
734 Durante el resto de esta sección, supondremos que los datos se
735 introducen en un archivo de música, por lo que añadiremos
736 almohadillas@tie{}@code{#} al principio de todas las expresiones de Scheme.
738 Todas las expresiones de Scheme del nivel jerárquico superior dentro
739 de un archivo de entrada de LilyPond se pueden combinar en una sola
740 expresión de Scheme mediante la utilización del operador @code{begin}:
745 (define menganito 1))
749 @node Variables de LilyPond
750 @subsection Variables de LilyPond
751 @translationof LilyPond variables
753 Las variables de LilyPond se almacenan internamente en la forma de
754 variables de Scheme. Así,
767 Esto significa que las variables de LilyPond están disponibles para su
768 uso dentro de expresiones de Scheme. Por ejemplo, podríamos usar
771 veintiCuatro = (* 2 doce)
775 lo que daría lugar a que el número 24 se almacenase dentro de la
776 variable @code{veintiCuatro} de LilyPond (y de Scheme).
778 La forma usual de referirse a las variables de LilyPond,
779 @ref{Sintaxis del Scheme de LilyPond},
781 es llamarlas usando una barra invertida, es decir
782 @code{\veintiCuatro}. Dado que esto crea una copia para la mayor
783 parte de los tipos internos de LilyPond, concretamente las expresiones
784 musicales, las funciones musicales no sueln crear copias del material
785 que ellas mismas modifican. Por este motivo, las expresiones
786 musicales dadas con @code{#} no deberían, por lo general, contener
787 material que no se haya creado partiendo de cero o copiado
788 explícitamente en lugar de estar referenciado directamente.
790 @node Variables de entrada y Scheme
791 @subsection Variables de entrada y Scheme
792 @translationof Input variables and Scheme
794 El formato de entrada contempla la noción de variables: en el
795 siguiente ejemplo, se asigna una expresión musical a una variable con
796 el nombre @code{traLaLa}.
799 traLaLa = @{ c'4 d'4 @}
804 También hay una forma de ámbito: en el ejemplo siguiente, el bloque
805 @code{\layout} también contiene una variable @code{traLaLa}, que es
806 independiente de la @code{\traLaLa} externa.
809 traLaLa = @{ c'4 d'4 @}
810 \layout @{ traLaLa = 1.0 @}
814 En efecto, cada archivo de entrada constituye un ámbito, y cada bloque
815 @code{\header}, @code{\midi} y @code{\layout} son ámbitos anidados
816 dentro del ámbito de nivel superior.
818 Tanto las variables como los ámbitos están implementados en el sistema
819 de módulos de GUILE. A cada ámbito se adjunta un módulo anónimo de
820 Scheme. Una asignación de la forma:
823 traLaLa = @{ c'4 d'4 @}
827 se convierte internamente en una definición de Scheme:
830 (define traLaLa @var{Valor Scheme de `@code{... }'})
833 Esto significa que las variables de LilyPond y las variables de Scheme
834 se pueden mezclar con libertad. En el ejemplo siguiente, se almacena
835 un fragmento de música en la variable @code{traLaLa}, y se duplica
836 usando Scheme. El resultado se importa dentro de un bloque
837 @code{\score} por medio de una segunda variable @code{twice}:
840 traLaLa = { c'4 d'4 }
842 #(define newLa (map ly:music-deep-copy
843 (list traLaLa traLaLa)))
845 (make-sequential-music newLa))
850 @c Due to parser lookahead
852 En realidad, éste es un ejemplo bastante interesante. La asignación
853 solo tiene lugar después de que el analizador sintáctico se ha
854 asegurado de que no sigue nada parecido a @code{\addlyrics}, de manera
855 que necesita comprobar lo que viene a continuación. Lee el símbolo
856 @code{#} y la expresión de Scheme siguiente @emph{sin} evaluarla, de
857 forma que puede proceder a la asignación, y @emph{posteriormente}
858 ejecutar el código de Scheme sin problema.
860 El ejemplo anterior muestra cómo @q{exportar} expresiones musicales
861 desde la entrada al intérprete de Scheme. Lo contrario también es
862 posible. Colocándolo después de @code{$}, un valor de Scheme se
863 interpreta como si hubiera sido introducido en la sintaxis de
864 LilyPond. En lugar de definir @code{\twice}, el ejemplo anterior
865 podría también haberse escrito como
869 @{ $(make-sequential-music (list newLa)) @}
872 Podemos utilizar @code{$} con una expresión de Scheme en cualquier
873 lugar en el que usaríamos @code{\@var{nombre}} después de haber
874 asignado la expresión de Scheme a una variable @var{nombre}. Esta
875 sustitución se produce dentro del @q{analizador léxico}, de manera que
876 LilyPond no llega a darse cuenta de la diferencia.
878 Sin embargo, existe un inconveniente, el de la medida del tiempo. Si
879 hubiésemos estado usando @code{$} en vez de @code{#} para definir
880 @code{newLa} en el ejemplo anterior, la siguiente definición de Scheme
881 habría fracasado porque @code{traLaLa} no habría sido definida aún.
882 Para ver una explicación de este problema de momento temporal, véase
883 @ref{Sintaxis del Scheme de LilyPond}.
885 En cualquier caso, la evaluación del código de Scheme se produce
886 dentro del analizador sintáctico como muy tarde. Si necesitamos que
887 se ejecute en un punto temporal más tardío,
888 usaríamos @ref{Funciones de Scheme vacías}, o lo almacenaríamos en un
893 (ly:set-option 'point-and-click #f))
902 No es posible mezclar variables de Scheme y de LilyPond con la opción
906 @node Propiedades de los objetos
907 @subsection Propiedades de los objetos
908 @translationof Object properties
910 Las propiedades de los objetos se almacenan en LilyPond en forma de
911 cadenas de listas-A, que son listas de listas-A. Las propiedades se
912 establecen añadiendo valores al principio de la lista de propiedades.
913 Las propiedades se leen extrayendo valores de las listas-A.
915 El establecimiento de un valor nuevo para una propiedad requiere la
916 asignación de un valor a la lista-A con una clave y un valor. La
917 sintaxis de LilyPond para hacer esto es la siguiente:
920 \override Stem #'thickness = #2.6
923 Esta instrucción ajusta el aspecto de las plicas. Se añade una
924 entrada de lista-A @code{'(thickness . 2.6)} a la lista de propiedades
925 de un objeto @code{Stem}. @code{thickness} se mide a partir del
926 grosor de las líneas del pentagrama, y así estas plicas serán
927 @code{2.6} veces el grosor de las líneas del pentagrama. Esto hace
928 que las plicas sean casi el doble de gruesas de lo normal. Para
929 distinguir entre las variables que se definen en los archivos de
930 entrada (como @code{veintiCuatro} en el ejemplo anterior) y las
931 variables de los objetos internos, llamaremos a las últimas
932 @q{propiedades} y a las primeras @q{variables.} Así, el objeto plica
933 tiene una propiedad @code{thickness} (grosor), mientras que
934 @code{veintiCuatro} es una variable.
936 @cindex propiedades frente a variables
937 @cindex variables frente a propiedades
939 @c todo -- here we're getting interesting. We're now introducing
940 @c LilyPond variable types. I think this deserves a section all
943 @node Variables de LilyPond compuestas
944 @subsection Variables de LilyPond compuestas
945 @translationof LilyPond compound variables
947 @subheading Desplazamientos
949 Los desplazamientos bidimensionales (coordenadas X e Y) se almacenan
950 como @emph{parejas}. El @code{car} del desplazamiento es la
951 coordenada X, y el @code{cdr} es la coordenada Y.
954 \override TextScript #'extra-offset = #'(1 . 2)
957 Esto asigna la pareja @code{(1 . 2)} a la propiedad
958 @code{extra-offset} del objeto TextScript. Estos números se miden en
959 espacios de pentagrama, y así esta instrucción mueve el objeto un
960 espacio de pentagrama a la derecha, y dos espacios hacia arriba.
962 Los procedimientos para trabajar con desplazamientos están en
963 @file{scm/lily-library.scm}.
965 @subheading Fractions
967 Fractions as used by LilyPond are again stored as @emph{pairs}, this
968 time of unsigned integers. While Scheme can represent rational numbers
969 as a native type, musically @samp{2/4} and @samp{1/2} are not the same,
970 and we need to be able to distinguish between them. Similarly there are
971 no negative @q{fractions} in LilyPond's mind. So @code{2/4} in LilyPond
972 means @code{(2 . 4)} in Scheme, and @code{#2/4} in LilyPond means
973 @code{1/2} in Scheme.
975 @subheading Dimensiones
977 Las parejas se usan también para almacenar intervalos, que representan
978 un rango de números desde el mínimo (el @code{car}) hasta el máximo
979 (el @code{cdr}). Los intervalos se usan para almacenar las
980 dimensiones en X y en Y de los objetos imprimibles. Para dimensiones
981 en X, el @code{car} es la coordenada X de la parte izquierda, y el
982 @code{cdr} es la coordenada X de la parte derecha. Para las
983 dimensiones en Y, el @code{car} es la coordenada inferior, y el
984 @code{cdr} es la coordenada superior.
986 Los procedimientos para trabajar con intervalos están en
987 @file{scm/lily-library.scm}. Se deben usar estos procedimientos
988 siempre que sea posible, para asegurar la consistencia del código.
990 @subheading Listas-A de propiedades
992 Una lista-A de propiedades es una estructura de datos de LilyPond que
993 es una lista-A cuyas claves son propiedades y cuyos valores son
994 expresiones de Scheme que dan el valor deseado de la propiedad.
996 Las propiedades de LilyPond son símbolos de Scheme, como por ejemplo
999 @subheading Cadenas de listas-A
1001 Una cadena de listas-A es una lista que contiene listas-A de
1004 El conjunto de todas las propiedades que se aplican a un grob se
1005 almacena por lo general como una cadena de listas-A. Para poder
1006 encontrar el valor de una propiedad determinada que debería tener un
1007 grob, se busca por todas las listas-A de la cadena, una a una,
1008 tratando de encontrar una entrada que contenga la clave de la
1009 propiedad. Se devuelve la primera entrada de lista-A que se
1010 encuentre, y el valor es el valor de la propiedad.
1012 El procedimiento de Scheme @code{chain-assoc-get} se usa normalmente
1013 para obtener los valores de propiedades.
1015 @node Representación interna de la música
1016 @subsection Representación interna de la música
1017 @translationof Internal music representation
1019 Internamente, la música se representa como una lista de Scheme. La
1020 lista contiene varios elementos que afectan a la salida impresa. El
1021 análisis sintáctico es el proceso de convertir la música de la
1022 representación de entrada de LilyPond a la representación interna de
1025 Cuando se analiza una expresión musical, se convierte en un conjunto
1026 de objetos musicales de Scheme. La propiedad definitoria de un objeto
1027 musical es que ocupa un tiempo. El tiempo que ocupa se llama
1028 @emph{duración}. Las duraciones se expresan como un número racional
1029 que mide la longitud del objeto musical en redondas.
1031 Un objeto musical tiene tres clases de tipos:
1034 nombre musical: Cada expresión musical tiene un nombre. Por ejemplo,
1035 una nota lleva a un @rinternals{NoteEvent}, y @code{\simultaneous}
1036 lleva a una @rinternals{SimultaneousMusic}. Hay una lista de todas
1037 las expresiones disponibles en el manual de Referencia de
1038 funcionamiento interno, bajo el epígrafe @rinternals{Music
1042 @q{type} (tipo) o interface: Cada nombre musical tiene varios
1043 @q{tipos} o interfaces, por ejemplo, una nota es un @code{event}, pero
1044 también es un @code{note-event}, un @code{rhythmic-event}, y un
1045 @code{melodic-event}. Todas las clases de música están listadas en el
1046 manual de Referencia de funcionamiento interno, bajo el epígrafe
1047 @rinternals{Music classes}.
1050 objeto de C++: Cada objeto musical está representado por un objeto de
1051 la clase @code{Music} de C++.
1054 La información real de una expresión musical se almacena en
1055 propiedades. Por ejemplo, un @rinternals{NoteEvent} tiene propiedades
1056 @code{pitch} y @code{duration} que almacenan la altura y la duración
1057 de esa nota. Hay una lista de todas la propiedades disponibles en el
1058 manual de Referencia de funcionamiento interno, bajo el epígrafe
1059 @rinternals{Music properties}.
1061 Una expresión musical compuesta es un objeto musical que contiene
1062 otros objetos musicales dentro de sus propiedades. Se puede almacenar
1063 una lista de objetos dentro de la propiedad @code{elements} de un
1064 objeto musical, o un único objeto musical @q{hijo} dentro de la
1065 propiedad @code{element}. Por ejemplo, @rinternals{SequentialMusic}
1066 tiene su hijo dentro de @code{elements}, y @rinternals{GraceMusic}
1067 tiene su argumento único dentro de @code{element}. El cuerpo de una
1068 repetición se almacena dentro de la propiedad @code{element} de
1069 @rinternals{RepeatedMusic}, y las alternativas dentro de
1072 @node Construir funciones complicadas
1073 @section Construir funciones complicadas
1074 @translationof Building complicated functions
1076 Esta sección explica cómo reunir la información necesaria para crear
1077 funciones musicales complicadas.
1080 * Presentación de las expresiones musicales::
1081 * Propiedades musicales::
1082 * Duplicar una nota con ligaduras (ejemplo)::
1083 * Añadir articulaciones a las notas (ejemplo)::
1087 @node Presentación de las expresiones musicales
1088 @subsection Presentación de las expresiones musicales
1089 @translationof Displaying music expressions
1091 @cindex almacenamiento interno
1092 @cindex imprimir expresiones musicales
1093 @cindex representación interna, impresión de
1094 @cindex displayMusic
1095 @funindex \displayMusic
1097 Si se está escribiendo una función musical, puede ser muy instructivo
1098 examinar cómo se almacena internamente una expresión musical. Esto se
1099 puede hacer con la función musical @code{\displayMusic}
1103 \displayMusic @{ c'4\f @}
1108 imprime lo siguiente:
1118 'AbsoluteDynamicEvent
1122 (ly:make-duration 2 0 1 1)
1124 (ly:make-pitch 0 0 0))))
1127 De forma predeterminada, LilyPond imprime estos mensajes sobre la
1128 consola junto al resto de los mensajes. Para separar estos mensajes y
1129 guardar el resultado de @code{\display@{LOQUESEA@}}, redirija la
1130 salida a un archivo.
1133 lilypond archivo.ly >salida.txt
1136 Con un poco de magia combinada de LilyPond y Scheme, podemos realmente
1137 hacer que LilyPond dirija solamente esta salida a su propio archivo:
1141 $(with-output-to-file "display.txt"
1142 (lambda () #@{ \displayMusic @{ c'4\f @} #@}))
1147 Un poco de reformateo hace a la información anterior más fácil de
1151 (make-music 'SequentialMusic
1153 (make-music 'NoteEvent
1154 'articulations (list
1155 (make-music 'AbsoluteDynamicEvent
1158 'duration (ly:make-duration 2 0 1 1)
1159 'pitch (ly:make-pitch 0 0 0))))
1162 Una secuencia musical @code{@{ ... @}} tiene el nombre
1163 @code{SequentialMusic}, y sus expresiones internas se almacenan coma
1164 una lista dentro de su propiedad @code{'elements}. Una nota se
1165 representa como un objeto @code{NoteEvent} (que almacena las
1166 propiedades de duración y altura) con información adjunta (en este
1167 caso, un evento @code{AbsoluteDynamicEvent} con una propiedad
1168 @code{"f"} de texto) almacenada en su propiedad @code{articulations}.
1171 @code{\displayMusic} devuelve la música que imprime en la consola, y
1172 por ello se interpretará al tiempo que se imprime en la consola. Para
1173 evitar la interpretación, escriba @code{\void} antes de
1174 @code{\displayMusic}.
1176 @node Propiedades musicales
1177 @subsection Propiedades musicales
1178 @translationof Music properties
1180 @c TODO -- make sure we delineate between @emph{music} properties,
1181 @c @emph{context} properties, and @emph{layout} properties. These
1182 @c are potentially confusing.
1188 \displayMusic \someNote
1193 (ly:make-duration 2 0 1 1)
1195 (ly:make-pitch 0 0 0))
1198 The @code{NoteEvent} object is the representation of @code{someNote}.
1199 Straightforward. How about putting c' in a chord?
1203 \displayMusic \someNote
1211 (ly:make-duration 2 0 1 1)
1213 (ly:make-pitch 0 0 0))))
1216 Ahora el objeto @code{NoteEvent} es el primer objeto
1217 de la propiedad @code{'elements} de @code{someNote}.
1219 La función @code{display-scheme-music} es la función que se usa por
1220 parte de @code{\displayMusic} para imprimir la representación de
1221 Scheme de una expresión musical.
1224 #(display-scheme-music (first (ly:music-property someNote 'elements)))
1229 (ly:make-duration 2 0 1 1)
1231 (ly:make-pitch 0 0 0))
1234 Después se accede a la altura de la nota a través de la propiedad
1235 @code{'pitch} del objeto @code{NoteEvent}:
1238 #(display-scheme-music
1239 (ly:music-property (first (ly:music-property someNote 'elements))
1242 (ly:make-pitch 0 0 0)
1245 La altura de la nota se puede cambiar estableciendo el valor de esta
1246 propiedad @code{'pitch},
1248 @funindex \displayLilyMusic
1251 #(set! (ly:music-property (first (ly:music-property someNote 'elements))
1253 (ly:make-pitch 0 1 0)) ;; establecer la altura a d'.
1254 \displayLilyMusic \someNote
1260 @node Duplicar una nota con ligaduras (ejemplo)
1261 @subsection Duplicar una nota con ligaduras (ejemplo)
1262 @translationof Doubling a note with slurs (example)
1264 Supongamos que queremos crear una función que convierte una entrada
1265 como @code{a} en @code{@{ a( a) @}}. Comenzamos examinando la
1266 representación interna de la música con la que queremos terminar.
1269 \displayMusic@{ a'( a') @}
1282 (ly:make-duration 2 0 1 1)
1284 (ly:make-pitch 0 5 0))
1293 (ly:make-duration 2 0 1 1)
1295 (ly:make-pitch 0 5 0))))
1298 La mala noticia es que las expresiones @code{SlurEvent} se deben
1299 añadir @q{dentro} de la nota (dentro de la
1300 propiedad @code{articulations}).
1302 Ahora examinamos la entrada,
1310 (ly:make-duration 2 0 1 1)
1312 (ly:make-pitch 0 5 0))))
1315 Así pues, en nuestra función, tenemos que clonar esta expresión (de
1316 forma que tengamos dos notas para construir la secuencia), añadir
1317 @code{SlurEvent} a la propiedad @code{'articulations} de cada una de
1318 ellas, y por último hacer una secuencia @code{SequentialMusic} con los
1319 dos @code{EventChords}. Para añadir a una propiedad, es útil saber
1320 que una propiedad no establecida se lee como @code{'()}, la lista
1321 vacía, así que no se requiere ninguna comprobación especial antes de
1322 que pongamos otro elemento delante de la propiedad
1323 @code{articulations}.
1327 doubleSlur = #(define-music-function (parser location note) (ly:music?)
1328 "Return: @{ note ( note ) @}.
1329 `note' is supposed to be a single note."
1330 (let ((note2 (ly:music-deep-copy note)))
1331 (set! (ly:music-property note 'articulations)
1332 (cons (make-music 'SlurEvent 'span-direction -1)
1333 (ly:music-property note 'articulations)))
1334 (set! (ly:music-property note2 'articulations)
1335 (cons (make-music 'SlurEvent 'span-direction 1)
1336 (ly:music-property note2 'articulations)))
1337 (make-music 'SequentialMusic 'elements (list note note2))))
1341 @node Añadir articulaciones a las notas (ejemplo)
1342 @subsection Añadir articulaciones a las notas (ejemplo)
1343 @translationof Adding articulation to notes (example)
1345 La manera fácil de añadir articulación a las notas es mezclar dos
1346 expresiones musicales en un solo contexto, como se explica en
1347 @ruser{Crear contextos}. Sin embargo, supongamos que queremos
1348 escribir una función musical que lo haga. Esto tiene la ventaja
1349 adicional de que podemos usar esa función musical para añadir una
1350 articulación (como una instrucción de digitación) a una nota única
1351 dentro de un acorde, lo cual no es posible si nos limitamos a mezclar
1352 fragmentos de música independientes.
1354 Una @code{$variable} dentro de la notación @code{#@{...#@}} es como
1355 una @code{\variable} normal en la notación clásica de LilyPond.
1363 no funciona en LilyPond. Podríamos evitar este problema adjuntando la
1364 articulación a una nota falsa,
1367 @{ << \music s1*0-.-> @}
1371 pero a los efectos de este ejemplo, aprenderemos ahora cómo hacerlo en
1372 Scheme. Empezamos examinando nuestra entrada y la salida deseada,
1381 (ly:make-duration 2 0 1 1)
1383 (ly:make-pitch -1 0 0))))
1396 (ly:make-duration 2 0 1 1)
1398 (ly:make-pitch -1 0 0))
1401 Vemos que una nota (@code{c4}) se representa como una expresión
1402 @code{NoteEvent}. Para añadir una articulación de acento, se debe
1403 añadir una expresión @code{ArticulationEvent} a la propiedad
1404 @code{articulations} de la expresión @code{NoteEvent}.
1406 Para construir esta función, empezamos con
1409 (define (add-accent note-event)
1410 "Add an accent ArticulationEvent to the articulations of `note-event',
1411 which is supposed to be a NoteEvent expression."
1412 (set! (ly:music-property note-event 'articulations)
1413 (cons (make-music 'ArticulationEvent
1414 'articulation-type "accent")
1415 (ly:music-property note-event 'articulations)))
1419 La primera línea es la forma de definir una función en Scheme: el
1420 nombre de la función es @code{add-accent}, y tiene una variable
1421 llamada @code{note-event}. En Scheme, el tipo de variable suele
1422 quedar claro a partir de su nombre (¡esto también es una buena
1423 práctica en otros lenguajes de programación!)
1430 es una descripción de lo que hace la función. No es estrictamente
1431 necesaria, pero de igual forma que los nombres claros de variable, es
1434 Se preguntará porqué modificamos el evento de nota directamente en
1435 lugar de trabajar sobre una copia (se puede usar
1436 @code{ly:music-deep-copy} para ello). La razón es un contrato
1437 silencioso: se permite que las funciones musicales modifiquen sus
1438 argumentos; o bien se generan partiendo de cero (como la entrada del
1439 usuario) o están ya copiadas (referenciar una variable de música con
1440 @samp{\name} o la música procedente de expresiones de Scheme
1441 inmediatas @samp{$(@dots{})} proporcionan una copia). Dado que sería
1442 ineficiente crear copias innecesarias, el valor devuelto de una
1443 función musical @emph{no} se copia. Así pues, para cumplir dicho
1444 contrato, no debemos usar ningún argumento más de una vez, y
1445 devolverlo cuenta como una vez.
1447 En un ejemplo anterior, hemos construido música mediante la repetición
1448 de un argumento musical dado. En tal caso, al menos una repetidión
1449 tuvo que ser una copia de sí misma. Si no lo fuese, podrían ocurrir
1450 cosas muy extrañas. Por ejemplo, si usamos @code{\relative} o
1451 @code{\transpose} sobre la música resultante que contiene los mismos
1452 elementos varias veces, estarían sujetos varias veces a la
1453 relativización o al transporte. Si los asignamos a una variable de
1454 música, se rompe el curso porque hacer referencia a @samp{\name}
1455 creará de nuevo una copia que no retiene la identidad de los elementos
1458 Ahora bien, aun cuando la función anterior no es una función musical,
1459 se usará normalmente dentro de funciones musicales. Así pues, tiene
1460 sentido obedecer el mismo convenio que usamos para las funciones
1461 musicales: la entrada puede modificarse para producir la salida, y el
1462 código que llama es responsable de crear las copias si aún necesita el
1463 propio argumento sin modificar. Si observamos las propias funciones
1464 de LilyPond como @code{music-map}, veremos que se atienen a los mismos
1467 ¿En qué punto nos encontramos? Ahora tenemos un @code{note-event} que
1468 podemos modificar, no a causa de la utilización de
1469 @code{ly:music-deep-copy} sino por una explicación muy desarrollada.
1470 Añadimos el acento a su propiedad de lista @code{'articulations}.
1473 (set! place new-value)
1476 Aquí, lo que queremos establecer (el @q{place}) es la propiedad
1477 @code{'articulations} de la expresión @code{note-event}.
1480 (ly:music-property note-event 'articulations)
1483 @code{ly:music-property} es la función ustilizada para acceder a las
1484 propiedades musicales (las @code{'articulations}, @code{'duration},
1485 @code{'pitch}, etc, que vemos arriba en la salida de
1486 @code{\displayMusic}). El nuevo valor es la antigua propiedad
1487 @code{'articulations}, con un elemento adicional: la expresión
1488 @code{ArticulationEvent}, que copiamos a partir de la salida de
1489 @code{\displayMusic},
1492 (cons (make-music 'ArticulationEvent
1493 'articulation-type "accent")
1494 (ly:music-property result-event-chord 'articulations))
1497 Se usa @code{cons} para añadir un elemento a la parte delantera de una
1498 lista sin modificar la lista original. Esto es lo que queremos: la
1499 misma lista de antes, más la nueva expresión @code{ArticulationEvent}.
1500 El orden dentro de la propiedad @code{'articulations} no tiene
1503 Finalmente, una vez hemos añadido la articulación de acento a su
1504 propiedad @code{articulations}, podemos devolver @code{note-event}, de
1505 aquí la última línea de la función.
1507 Ahora transformamos la función @code{add-accent} en una función
1508 musical (es cuestión de un poco de aderezo sintáctico y una
1509 declaración del tipo de su único argumento @q{real}).
1512 addAccent = #(define-music-function (parser location note-event)
1514 "Add an accent ArticulationEvent to the articulations of `note-event',
1515 which is supposed to be a NoteEvent expression."
1516 (set! (ly:music-property note-event 'articulations)
1517 (cons (make-music 'ArticulationEvent
1518 'articulation-type "accent")
1519 (ly:music-property note-event 'articulations)))
1523 Podemos verificar que esta función musical funciona correctamente:
1526 \displayMusic \addAccent c4
1532 * Trucos con Scheme::
1535 @c @nod e Trucos con Scheme
1536 @c @sectio n Trucos con Scheme
1537 @c @transl ationof Tweaking with Scheme
1539 Hemos visto cómo la salida de LilyPond se puede modificar
1540 profundamente usando instrucciones como @code{\override TextScript
1541 #'extra-offset = ( 1 . -1)}. Pero tenemos incluso mucho más poder si
1542 utilizamos Scheme. Para ver una explicación completa de esto,
1543 consulte el @ref{Tutorial de Scheme}, y @ruser{Interfaces para programadores}.
1545 Podemos usar Scheme simplemente para sobreescribir instrucciones con
1548 TODO Find a simple example
1549 @c This isn't a valid example with skylining
1550 @c It works fine without padText -td
1554 @lilypond[quote,verbatim,ragged-right]
1555 padText = #(define-music-function (parser location padding) (number?)
1557 \once \override TextScript #'padding = #padding
1561 c4^"piu mosso" b a b
1563 c4^"piu mosso" d e f
1565 c4^"piu mosso" fis a g
1571 Lo podemos usar para crear instrucciones nuevas:
1573 @c Check this is a valid example with skylining
1574 @c It is - 'padding still works
1577 @lilypond[quote,verbatim,ragged-right]
1578 tempoPadded = #(define-music-function (parser location padding tempotext)
1581 \once \override Score.MetronomeMark #'padding = $padding
1582 \tempo \markup { \bold #tempotext }
1586 \tempo \markup { "Low tempo" }
1588 \tempoPadded #4.0 #"High tempo"
1594 Incluso se le pueden pasar expresiones musicales:
1596 @lilypond[quote,verbatim,ragged-right]
1597 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
1604 \pattern {d16 dis} { ais16-> b\p }