1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
4 Translation of GIT committish: 2763b2de261e4f6263e2d4751b45d7c40f1ef7ea
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
20 @cindex Scheme, código en línea
21 @cindex acceder a Scheme
22 @cindex evaluar Scheme
25 LilyPond utiliza el lenguaje de programación Scheme, tanto como parte
26 de la sintaxis del código de entrada, como para servir de mecanismo
27 interno que une los módulos del programa entre sí. Esta sección es
28 una panorámica muy breve sobre cómo introducir datos en Scheme. Si
29 quiere saber más sobre Scheme, consulte
30 @uref{http://@/www@/.schemers@/.org}.
32 LilyPond utiliza la implementación GNU Guile de Scheme, que está
33 basada en el estándar @qq{R5RS} del lenguaje. Si está aprendiendo
34 Scheme para usarlo con LilyPond, no se recomienda trabajar con una
35 implementación distinta (o que se refiera a un estándar diferente).
36 Hay información sobre Guile en
37 @uref{http://www.gnu.org/software/guile/}. El estándar de Scheme
38 @qq{R5RS} se encuentra en
39 @uref{http://www.schemers.org/Documents/Standards/R5RS/}.
42 * Introducción a Scheme::
43 * Scheme dentro de LilyPond::
44 * Construir funciones complicadas::
47 @node Introducción a Scheme
48 @section Introducción a Scheme
49 @translationof Introduction to Scheme
51 Comenzaremos con una introducción a Scheme. Para esta breve
52 introducción utilizaremos el intérprete GUILE para explorar la manera
53 en que el lenguaje funciona. Una vez nos hayamos familiarizado con
54 Scheme, mostraremos cómo se puede integrar el lenguaje en los archivos
59 * Cajón de arena de Scheme::
60 * Variables de Scheme::
61 * Tipos de datos simples de Scheme::
62 * Tipos de datos compuestos de Scheme::
63 * Cálculos en Scheme::
64 * Procedimientos de Scheme::
65 * Condicionales de Scheme::
68 @node Cajón de arena de Scheme
69 @subsection Cajón de arena de Scheme
70 @translationof Scheme sandbox
72 La instalación de LilyPond incluye también la de la implementación
73 Guile de Scheme. Sobre casi todos los sistemas puede experimentar en
74 una @qq{caja de arena} de Scheme abriendo una ventana del terminal y
75 tecleando @q{guile}. En algunos sistemas, sobre todo en Windows,
76 podría necesitar ajustar la variable de entorno @code{GUILE_LOAD_PATH}
77 a la carpeta @code{../usr/shr/guile/1.8} dentro de la instalación de
78 LilyPond (para conocer la ruta completa a esta carpeta, consulte
79 @rlearning{Otras fuentes de información}). Como alternativa, los
80 usuarios de Windows pueden seleccionar simplemente @q{Ejecutar} del
81 menú Inicio e introducir @q{guile}.
83 Una vez está funcionando el cajón de arena de Guile, verá un indicador
90 Podemos introducir expresiones de Scheme en este indicador para
91 experimentar con Scheme.
93 @node Variables de Scheme
94 @subsection Variables de Scheme
95 @translationof Scheme variables
97 Las variables de Scheme pueden tener cualquier valor válido de Scheme,
98 incluso un procedimiento de Scheme.
100 Las variables de Scheme se crean con @code{define}:
107 Las variables de Scheme se pueden evaluar en el indicador del sistema
108 de guile, simplemente tecleando el nombre de la variable:
116 Las variables de Scheme se pueden imprimir en la pantalla utilizando
125 Observe que el valor @code{2} y el indicador del sistema @code{guile}
126 se muestran en la misma línea. Esto se puede evitar llamando al
127 procedimiento de nueva línea o imprimiendo un carácter de nueva línea.
130 guile> (display a)(newline)
132 guile> (display a)(display "\n")
137 Una vez que se ha creado una variable, su valor se puede modificar con
141 guile> (set! a 12345)
147 @node Tipos de datos simples de Scheme
148 @subsection Tipos de datos simples de Scheme
149 @translationof Scheme simple data types
151 El concepto más básico de un lenguaje son sus tipos de datos: números,
152 cadenas de caracteres, listas, etc. He aquí una lista de los tipos de
153 datos que son de relevancia respecto de la entrada de LilyPond.
157 Los valores Booleanos son Verdadero y Falso. Verdadero en Scheme es
158 @code{#t} y Falso es @code{#f}.
163 Los números se escriben de la forma normal, @code{1} es el número
164 (entero) uno, mientras que @w{@code{-1.5}} es un número en coma flotante
165 (un número no entero).
168 Las cadenas se encierran entre comillas:
174 Las cadenas pueden abarcar varias líneas:
183 y los caracteres de nueva línea al final de cada línea se incluirán
186 Los caracteres de nueva línea también se pueden añadir mediante la
187 inclusión de @code{\n} en la cadena.
190 "esto\nes una\ncadena de varias líneas"
194 Las comillas dobles y barras invertidas se añaden a las cadenas
195 precediéndolas de una barra invertida. La cadena @code{\a dijo "b"}
204 Existen más tipos de datos de Scheme que no se estudian aquí. Para
205 ver un listado completo, consulte la guía de referencia de Guile,
206 @uref{http://www.gnu.org/software/guile/manual/html_node/Simple-Data-Types.html}.
208 @node Tipos de datos compuestos de Scheme
209 @subsection Tipos de datos compuestos de Scheme
210 @translationof Scheme compound data types
212 También existen tipos de datos compuestos en Scheme. Entre los tipos
213 más usados en la programación de LilyPond se encuentran las parejas,
214 las listas, las listas-A y las tablas de hash.
218 El tipo fundacional de datos compuestos de Scheme es la @code{pareja}.
219 Como se espera por su nombre, una pareja son dos valores unidos en uno
220 solo. El operador que se usa para formar una pareja se llama
229 Observe que la pareja se imprime como dos elementos rodeados por
230 paréntesis y separados por un espacio, un punto (@code{.}) y otro
231 espacio. El punto @emph{no es} un punto decimal, sino más bien un
234 Las parejas también se pueden introducir como valores literales
235 precediéndolos de un carácter de comilla simple o apóstrofo.
243 Los dos elementos de una pareja pueden ser cualquier valor válido de
249 guile> '("bla-bla" . 3.1415926535)
250 ("bla-bla" . 3.1415926535)
254 Se puede accede al primero y segundo elementos de la pareja mediante
255 los procedimientos de Scheme @code{car} y @code{cdr}, respectivamente.
258 guile> (define mipareja (cons 123 "Hola")
260 guile> (car mipareja)
262 guile> (cdr mipareja)
269 Nota: @code{cdr} se pronuncia "could-er", según Sussman y Abelson,
271 @uref{http://mitpress.mit.edu/sicp/full-text/book/book-Z-H-14.html#footnote_Temp_133}
276 Una estructura de datos muy común en Scheme es la @emph{lista}.
277 Formalmente, una lista se define como la lista vacía (representada
278 como @code{'()}, o bien como una pareja cuyo @code{cdr} es una lista.
280 Existen muchas formas de crear listas. Quizá la más común es con el
281 procedimiento @code{list}:
284 guile> (list 1 2 3 "abc" 17.5)
288 Como se ve, una lista se imprime en la forma de elementos individuales
289 separados por espacios y encerradas entre paréntesis. A diferencia de
290 las parejas, no hay ningún punto entre los elementos.
292 También se puede escribir una lista como una lista literal encerrando
293 sus elementos entre paréntesis y añadiendo un apóstrofo:
296 guile> '(17 23 "fulano" "mengano" "zutano")
297 (17 23 "fulano" "mengano" "zutano")
300 Las listas son una parte fundamental de Scheme. De hecho, Scheme se
301 considera un dialecto de Lisp, donde @q{lisp} es una abreviatura de
302 @q{List Processing} (proceso de listas). Todas las expresiones de
305 @subheading Listas asociativas (listas-A)
307 Un tipo especial de listas son las @emph{listas asociativas} o
308 @emph{listas-A}. Se puede usar una lista-A para almacenar datos para
309 su fácil recuperación posterior.
311 Las listas-A son listas cuyos elementos son parejas. El @code{car} de
312 cada elemento se llama @emph{clave}, y el @code{cdr} de cada elemento
313 se llama @emph{valor}. El procedimiento de Scheme @code{assoc} se usa
314 para recuperar un elemento de la lista-A, y @code{cdr} se usa para
318 guile> (define mi-lista-a '((1 . "A") (2 . "B") (3 . "C")))
320 ((1 . "A") (2 . "B") (3 . "C"))
321 guile> (assoc 2 mi-lista-a)
323 guile> (cdr (assoc 2 mi-lista-a))
328 Las listas-A se usan mucho en LilyPond para almacenar propiedades y
331 @subheading Tablas de hash
333 Estructuras de datos que se utilizan en LilyPond de forma ocasional.
334 Una tabla de hash es similar a una matriz, pero los índices de la
335 matriz pueden ser cualquier tipo de valor de Scheme, no sólo enteros.
337 Las tablas de hash son más eficientes que las listas-A si hay una gran
338 cantidad de datos que almacenar y los datos cambian con muy poca
341 La sintaxis para crear tablas de hash es un poco compleja, pero
342 veremos ejemplos de ello en el código fuente de LilyPond.
345 guile> (define h (make-hash-table 10))
348 guile> (hashq-set! h 'key1 "val1")
350 guile> (hashq-set! h 'key2 "val2")
352 guile> (hashq-set! h 3 "val3")
356 Los valores se recuperan de las tablas de hash mediante
360 guile> (hashq-ref h 3)
362 guile> (hashq-ref h 'key2)
367 Las claves y los valores se recuperan como una pareja con
368 @code{hashq-get-handle}. Ésta es la forma preferida, porque devuelve
369 @code{#f} si no se encuentra la clave.
372 guile> (hashq-get-handle h 'key1)
374 guile> (hashq-get-handle h 'frob)
379 @node Cálculos en Scheme
380 @subsection Cálculos en Scheme
381 @translationof Calculations in Scheme
384 Todo el tiempo hemos estado usando listas. Un cálculo, como @code{(+
385 1 2)} también es una lista (que contiene el símbolo @code{+} y los
386 números 1 y@tie{}2). Normalmente, las listas se interpretan como
387 cálculos, y el intérprete de Scheme sustituye el resultado del
388 cálculo. Para escribir una lista, detenemos la evaluación. Esto se
389 hace precediendo la lista por un apóstrofo @code{'}. Así, para los
390 cálculos no usamos ningún apóstrofo.
392 Dentro de una lista o pareja precedida de apóstrofo, no hay necesidad
393 de escribir ningún apóstrofo más. Lo siguiente es una pareja de
394 símbolos, una lista de símbolos y una lista de listas respectivamente:
398 #'(staff clef key-signature)
403 Scheme se puede usar para hacer cálculos. Utiliza sintaxis
404 @emph{prefija}. Sumar 1 y@tie{}2 se escribe como @code{(+ 1 2)} y no
405 como el tradicional @math{1+2}.
412 Los cálculos se pueden anidar; el resultado de una función se puede
413 usar para otro cálculo.
420 Estos cálculos son ejemplos de evaluaciones; una expresión como
421 @code{(* 3 4)} se sustituye por su valor @code{12}.
423 Los cálculos de Scheme son sensibles a las diferencias entre enteros y
424 no enteros. Los cálculos enteros son exactos, mientras que los no
425 enteros se calculan con los límites de precisión adecuados:
434 Cuando el intérprete de Scheme encuentra una expresión que es una
435 lista, el primer elemento de la lista se trata como un procedimiento a
436 evaluar con los argumentos del resto de la lista. Por tanto, todos
437 los operadores en Scheme son operadores prefijos.
439 Si el primer elemento de una expresión de Scheme que es una lista que
440 se pasa al intérprete @emph{no es} un operador o un procedimiento, se
450 <unnamed port>:52:1: In expression (1 2 3):
451 <unnamed port>:52:1: Wrong type to apply: 1
456 Aquí podemos ver que el intérprete estaba intentando tratar el 1 como
457 un operador o procedimiento, y no pudo hacerlo. De aquí que el error
458 sea "Wrong type to apply: 1".
460 Así pues, para crear una lista debemos usar el operador de lista, o
461 podemos precederla de un apóstrofo para que el intérprete no trate de
472 Esto es un error que puede aparecer cuando trabaje con Scheme dentro
476 La misma asignación se puede hacer también completamente en Scheme,
479 #(define veintiCuatro (* 2 doce))
482 @c this next section is confusing -- need to rewrite
484 El @emph{nombre} de una variable también es una expresión, similar a
485 un número o una cadena. Se introduce como
492 @cindex comillas en Scheme
494 El apóstrofo @code{'} evita que el intérprete de Scheme sustituya
495 @code{veintiCuatro} por @code{24}. En vez de esto, obtenemos el
496 nombre @code{veintiCuatro}.
500 @node Procedimientos de Scheme
501 @subsection Procedimientos de Scheme
502 @translationof Scheme procedures
504 Los procedimientos de Scheme son expresiones de Scheme ejecutables que
505 devuelven un valor resultante de su ejecución. También pueden
506 manipular variables definidas fuera del procedimiento.
508 @subheading Definir procedimientos
510 Los procedimientos se definen en Scheme con @code{define}:
513 (define (nombre-de-la-función arg1 arg2 ... argn)
514 expresión-de-scheme-que-devuelve-un-valor)
517 Por ejemplo, podemos definir un procedimiento para calcular la media:
520 guile> (define (media x y) (/ (+ x y) 2))
522 #<procedure media (x y)>
525 Una vez se ha definido un procedimiento, se llama poniendo el nombre
526 del procedimiento dentro de una lista. Por ejemplo, podemos calcular
534 @subheading Predicados
536 Los procedimientos de Scheme que devuelven valores booleanos se suelen
537 llamar @emph{predicados}. Por convenio (pero no por necesidad),
538 los nombres de predicados acaban en un signo de interrogación:
541 guile> (define (menor-que-diez? x) (< x 10))
542 guile> (menor-que-diez? 9)
544 guile> (menor-que-diez? 15)
548 @subheading Valores de retorno
550 Los procedimientos de Scheme siempre devuelven un valor de retorno,
551 que es el valor de la última expresión ejecutada en el procedimiento.
552 El valor de retorno puede ser cualquier valor de Scheme válido,
553 incluso una estructura de datos compleja o un procedimiento.
555 A veces, el usuario quiere tener varias expresiones de Scheme dentro
556 de un procedimiento. Existen dos formas en que se pueden combinar
557 distintas expresiones. La primera es el procedimiento @code{begin},
558 que permite evaluar varias expresiones, y devuelve el valor de la
562 guile> (begin (+ 1 2) (- 5 8) (* 2 2))
566 La segunda forma de combinar varias expresiones es dentro de un bloque
567 @code{let}. Dentro de un bloque let, se crean una serie de ligaduras
568 o asignaciones, y después se evalúa una secuencia de expresiones que
569 pueden incluir esas ligaduras o asignaciones. El valor de retorno del
570 bloque let es el valor de retorno de la última sentencia del bloque
574 guile> (let ((x 2) (y 3) (z 4)) (display (+ x y)) (display (- z 4))
575 ... (+ (* x y) (/ z x)))
579 @node Condicionales de Scheme
580 @subsection Condicionales de Scheme
581 @translationof Scheme conditionals
585 Scheme tiene un procedimiento @code{if}:
588 (if expresión-de-prueba expresión-de-cierto expresión-de-falso)
591 @var{expresión-de-prueba} es una expresión que devuelve un valor
592 booleano. Si @var{expresión-de-prueba} devuelve @code{#t}, el
593 procedimiento @code{if} devuelve el valor de la
594 @var{expresión-de-cierto}, en caso contrario devuelve el valor de la
595 @var{expresión-de-falso}.
600 guile> (if (> a b) "a es mayor que b" "a no es mayor que b")
601 "a no es mayor que b"
606 Otro procedimiento condicional en scheme es @code{cond}:
609 (cond (expresión-de-prueba-1 secuencia-de-expresiones-resultante-1)
610 (expresión-de-prueba-2 secuencia-de-expresiones-resultante-2)
612 (expresión-de-prueba-n secuencia-de-expresiones-resultante-n))
620 guile> (cond ((< a b) "a es menor que b")
621 ... ((= a b) "a es igual a b")
622 ... ((> a b) "a es mayor que b"))
626 @node Scheme dentro de LilyPond
627 @section Scheme dentro de LilyPond
628 @translationof Scheme in LilyPond
631 * Sintaxis del Scheme de LilyPond::
632 * Variables de LilyPond::
633 * Variables de entrada y Scheme::
634 * Propiedades de los objetos::
635 * Variables de LilyPond compuestas::
636 * Representación interna de la música::
639 @node Sintaxis del Scheme de LilyPond
640 @subsection Sintaxis del Scheme de LilyPond
641 @translationof LilyPond Scheme syntax
643 El intérprete Guile forma parte de LilyPond, lo que significa que se
644 puede incluir Scheme dentro de los archivos de entrada de LilyPond.
645 La marca de almohadilla@tie{}@code{#} se utiliza para indicar al analizador
646 sintáctico de LilyPond que lo siguiente es un valor de Scheme.
648 Una vez el analizador sintáctico se encuentra con un símbolo de
649 almohadilla, la entrada se le pasa al intérprete Guile para evaluar la
650 expresión de Scheme. El intérprete continúa procesando la entrada
651 hasta que se encuentra con el final de una expresión de Scheme.
653 Los procedimientos de Scheme se pueden definir dentro de los archivos
654 de entrada de LilyPond:
657 #(define (average a b c) (/ (+ a b c) 3))
660 Observe que los comentarios de LilyPond (@code{%} y @code{%@{ %@}}) no
661 se pueden utilizar dentro del código de Scheme, ni siquiera dentro de
662 un archivo de entrada de LilyPond input file, porque es el intérprete
663 Guile, y no el analizador sintáctico de LilyPond, el que está
664 interpretando la expresión de Scheme. Los comentarios en el Scheme de
665 Guile se introducen como sigue:
668 ; esto es un comentario de una línea
671 Esto es un comentario de bloque (no anidable) estilo Guile
672 Pero se usan rara vez por parte de los Schemers y nunca dentro del
673 código fuente de LilyPond
677 Durante el resto de esta sección, supondremos que los datos se
678 introducen en un archivo de música, por lo que añadiremos
679 almohadillas@tie{}@code{#} al principio de todas las expresiones de Scheme.
681 Todas las expresiones de Scheme del nivel jerárquico superior dentro
682 de un archivo de entrada de LilyPond se pueden combinar en una sola
683 expresión de Scheme mediante la utilización del operador @code{begin}:
688 (define menganito 1))
692 @node Variables de LilyPond
693 @subsection Variables de LilyPond
694 @translationof LilyPond variables
696 Las variables de LilyPond se almacenan internamente en la forma de
697 variables de Scheme. Así,
710 Esto significa que las variables de LilyPond están disponibles para su
711 uso dentro de expresiones de Scheme. Por ejemplo, podríamos usar
714 veintiCuatro = (* 2 doce)
718 lo que daría lugar a que el número 24 se almacenase dentro de la
719 variable @code{veintiCuatro} de LilyPond (y de Scheme).
721 @node Variables de entrada y Scheme
722 @subsection Variables de entrada y Scheme
723 @translationof Input variables and Scheme
725 El formato de entrada contempla la noción de variables: en el
726 siguiente ejemplo, se asigna una expresión musical a una variable con
727 el nombre @code{traLaLa}.
730 traLaLa = @{ c'4 d'4 @}
735 También hay una forma de ámbito: en el ejemplo siguiente, el bloque
736 @code{\layout} también contiene una variable @code{traLaLa}, que es
737 independiente de la @code{\traLaLa} externa.
740 traLaLa = @{ c'4 d'4 @}
741 \layout @{ traLaLa = 1.0 @}
745 En efecto, cada archivo de entrada constituye un ámbito, y cada bloque
746 @code{\header}, @code{\midi} y @code{\layout} son ámbitos anidados
747 dentro del ámbito de nivel superior.
749 Tanto las variables como los ámbitos están implementados en el sistema
750 de módulos de GUILE. A cada ámbito se adjunta un módulo anónimo de
751 Scheme. Una asignación de la forma:
754 traLaLa = @{ c'4 d'4 @}
758 se convierte internamente en una definición de Scheme:
761 (define traLaLa @var{Valor Scheme de `@code{... }'})
764 Esto significa que las variables de LilyPond y las variables de Scheme
765 se pueden mezclar con libertad. En el ejemplo siguiente, se almacena
766 un fragmento de música en la variable @code{traLaLa}, y se duplica
767 usando Scheme. El resultado se importa dentro de un bloque
768 @code{\score} por medio de una segunda variable @code{twice}:
771 traLaLa = { c'4 d'4 }
773 %% dummy action to deal with parser lookahead
774 #(display "this needs to be here, sorry!")
776 #(define newLa (map ly:music-deep-copy
777 (list traLaLa traLaLa)))
779 (make-sequential-music newLa))
784 @c Due to parser lookahead
786 En este ejemplo, la asignación se produce después de que el analizador
787 sintáctico ha verificado que no ocurre nada interesante después de
788 @code{traLaLa = @{ ... @}}. Sin la sentencia muda del ejemplo
789 anterior, la definición de @code{newLa} se ejecuta antes de que se
790 defina @code{traLaLa}, produciendo un error de sintaxis.
792 El ejemplo anterior muestra cómo @q{exportar} expresiones musicales
793 desde la entrada al intérprete de Scheme. Lo contrario también es
794 posible. Envolviendo un valor de Scheme en la función
795 @code{ly:export}, se interpreta un valor de Scheme como si hubiera
796 sido introducido en la sintaxis de LilyPond. En lugar de definir
797 @code{\twice}, el ejemplo anterior podría también haberse escrito como
801 @{ #(ly:export (make-sequential-music (list newLa))) @}
804 El código de Scheme se evalúa tan pronto como el analizador sintáctico
805 lo encuentra. Para definir código de Scheme dentro de un macro (para
806 llamarse más tarde), utilice @ref{Funciones de scheme vacías}, o bien
810 (ly:set-option 'point-and-click #f))
819 No es posible mezclar variables de Scheme y de LilyPond con la opción
823 @node Propiedades de los objetos
824 @subsection Propiedades de los objetos
825 @translationof Object properties
827 Las propiedades de los objetos se almacenan en LilyPond en forma de
828 cadenas de listas-A, que son listas de listas-A. Las propiedades se
829 establecen añadiendo valores al principio de la lista de propiedades.
830 Las propiedades se leen extrayendo valores de las listas-A.
832 El establecimiento de un valor nuevo para una propiedad requiere la
833 asignación de un valor a la lista-A con una clave y un valor. La
834 sintaxis de LilyPond para hacer esto es la siguiente:
837 \override Stem #'thickness = #2.6
840 Esta instrucción ajusta el aspecto de las plicas. Se añade una
841 entrada de lista-A @code{'(thickness . 2.6)} a la lista de propiedades
842 de un objeto @code{Stem}. @code{thickness} se mide a partir del
843 grosor de las líneas del pentagrama, y así estas plicas serán
844 @code{2.6} veces el grosor de las líneas del pentagrama. Esto hace
845 que las plicas sean casi el doble de gruesas de lo normal. Para
846 distinguir entre las variables que se definen en los archivos de
847 entrada (como @code{veintiCuatro} en el ejemplo anterior) y las
848 variables de los objetos internos, llamaremos a las últimas
849 @q{propiedades} y a las primeras @q{variables.} Así, el objeto plica
850 tiene una propiedad @code{thickness} (grosor), mientras que
851 @code{veintiCuatro} es una variable.
853 @cindex propiedades frente a variables
854 @cindex variables frente a propiedades
856 @c todo -- here we're getting interesting. We're now introducing
857 @c LilyPond variable types. I think this deserves a section all
860 @node Variables de LilyPond compuestas
861 @subsection Variables de LilyPond compuestas
862 @translationof LilyPond compound variables
864 @subheading Desplazamientos
866 Los desplazamientos bidimensionales (coordenadas X e Y) se almacenan
867 como @code{parejas}. El @code{car} del desplazamiento es la
868 coordenada X, y el @code{cdr} es la coordenada Y.
871 \override TextScript #'extra-offset = #'(1 . 2)
874 Esto asigna la pareja @code{(1 . 2)} a la propiedad
875 @code{extra-offset} del objeto TextScript. Estos números se miden en
876 espacios de pentagrama, y así esta instrucción mueve el objeto un
877 espacio de pentagrama a la derecha, y dos espacios hacia arriba.
879 Los procedimientos para trabajar con desplazamientos están en
880 @file{scm/lily-library.scm}.
882 @subheading Dimensiones
884 Las parejas se usan también para almacenar intervalos, que representan
885 un rango de números desde el mínimo (el @code{car}) hasta el máximo
886 (el @code{cdr}). Los intervalos se usan para almacenar las
887 dimensiones en X y en Y de los objetos imprimibles. Para dimensiones
888 en X, el @code{car} es la coordenada X de la parte izquierda, y el
889 @code{cdr} es la coordenada X de la parte derecha. Para las
890 dimensiones en Y, el @code{car} es la coordenada inferior, y el
891 @code{cdr} es la coordenada superior.
893 Los procedimientos para trabajar con intervalos están en
894 @file{scm/lily-library.scm}. Se deben usar estos procedimientos
895 siempre que sea posible, para asegurar la consistencia del código.
897 @subheading Listas-A de propiedades
899 Una lista-A de propiedades es una estructura de datos de LilyPond que
900 es una lista-A cuyas claves son propiedades y cuyos valores son
901 expresiones de Scheme que dan el valor deseado de la propiedad.
903 Las propiedades de LilyPond son símbolos de Scheme, como por ejemplo
906 @subheading Cadenas de listas-A
908 Una cadena de listas-A es una lista que contiene listas-A de
911 El conjunto de todas las propiedades que se aplican a un grob se
912 almacena por lo general como una cadena de listas-A. Para poder
913 encontrar el valor de una propiedad determinada que debería tener un
914 grob, se busca por todas las listas-A de la cadena, una a una,
915 tratando de encontrar una entrada que contenga la clave de la
916 propiedad. Se devuelve la primera entrada de lista-A que se
917 encuentre, y el valor es el valor de la propiedad.
919 El procedimiento de Scheme @code{chain-assoc-get} se usa normalmente
920 para obtener los valores de propiedades.
922 @node Representación interna de la música
923 @subsection Representación interna de la música
924 @translationof Internal music representation
926 Internamente, la música se representa como una lista de Scheme. La
927 lista contiene varios elementos que afectan a la salida impresa. El
928 análisis sintáctico es el proceso de convertir la música de la
929 representación de entrada de LilyPond a la representación interna de
932 Cuando se analiza una expresión musical, se convierte en un conjunto
933 de objetos musicales de Scheme. La propiedad definitoria de un objeto
934 musical es que ocupa un tiempo. El tiempo que ocupa se llama
935 @emph{duración}. Las duraciones se expresan como un número racional
936 que mide la longitud del objeto musical en redondas.
938 Un objeto musical tiene tres clases de tipos:
941 nombre musical: Cada expresión musical tiene un nombre. Por ejemplo,
942 una nota lleva a un @rinternals{NoteEvent}, y @code{\simultaneous}
943 lleva a una @rinternals{SimultaneousMusic}. Hay una lista de todas
944 las expresiones disponibles en el manual de Referencia de
945 funcionamiento interno, bajo el epígrafe @rinternals{Music
949 @q{type} (tipo) o interface: Cada nombre musical tiene varios
950 @q{tipos} o interfaces, por ejemplo, una nota es un @code{event}, pero
951 también es un @code{note-event}, un @code{rhythmic-event}, y un
952 @code{melodic-event}. Todas las clases de música están listadas en el
953 manual de Referencia de funcionamiento interno, bajo el epígrafe
954 @rinternals{Music classes}.
957 objeto de C++: Cada objeto musical está representado por un objeto de
958 la clase @code{Music} de C++.
961 La información real de una expresión musical se almacena en
962 propiedades. Por ejemplo, un @rinternals{NoteEvent} tiene propiedades
963 @code{pitch} y @code{duration} que almacenan la altura y la duración
964 de esa nota. Hay una lista de todas la propiedades disponibles en el
965 manual de Referencia de funcionamiento interno, bajo el epígrafe
966 @rinternals{Music properties}.
968 Una expresión musical compuesta es un objeto musical que contiene
969 otros objetos musicales dentro de sus propiedades. Se puede almacenar
970 una lista de objetos dentro de la propiedad @code{elements} de un
971 objeto musical, o un único objeto musical @q{hijo} dentro de la
972 propiedad @code{element}. Por ejemplo, @rinternals{SequentialMusic}
973 tiene su hijo dentro de @code{elements}, y @rinternals{GraceMusic}
974 tiene su argumento único dentro de @code{element}. El cuerpo de una
975 repetición se almacena dentro de la propiedad @code{element} de
976 @rinternals{RepeatedMusic}, y las alternativas dentro de
979 @node Construir funciones complicadas
980 @section Construir funciones complicadas
981 @translationof Building complicated functions
983 Esta sección explica cómo reunir la información necesaria para crear
984 funciones musicales complicadas.
987 * Presentación de las expresiones musicales::
988 * Propiedades musicales::
989 * Duplicar una nota con ligaduras (ejemplo)::
990 * Añadir articulaciones a las notas (ejemplo)::
994 @node Presentación de las expresiones musicales
995 @subsection Presentación de las expresiones musicales
996 @translationof Displaying music expressions
998 @cindex almacenamiento interno
999 @cindex imprimir expresiones musicales
1000 @cindex representación interna, impresión de
1001 @cindex displayMusic
1002 @funindex \displayMusic
1004 Si se está escribiendo una función musical, puede ser muy instructivo
1005 examinar cómo se almacena internamente una expresión musical. Esto se
1006 puede hacer con la función musical @code{\displayMusic}
1010 \displayMusic @{ c'4\f @}
1015 imprime lo siguiente:
1027 (ly:make-duration 2 0 1 1)
1029 (ly:make-pitch 0 0 0))
1031 'AbsoluteDynamicEvent
1036 De forma predeterminada, LilyPond imprime estos mensajes sobre la
1037 consola junto al resto de los mensajes. Para separar estos mensajes y
1038 guardar el resultado de @code{\display@{LOQUESEA@}}, redirija la
1039 salida a un archivo.
1042 lilypond archivo.ly >salida.txt
1045 Con la aplicación de un poco de formateo, la información anterior es
1049 (make-music 'SequentialMusic
1050 'elements (list (make-music 'EventChord
1051 'elements (list (make-music 'NoteEvent
1052 'duration (ly:make-duration 2 0 1 1)
1053 'pitch (ly:make-pitch 0 0 0))
1054 (make-music 'AbsoluteDynamicEvent
1058 Una secuencia musical @code{@{ ... @}} tiene el nombre
1059 @code{SequentialMusic}, y sus expresiones internas se almacenan coma
1060 una lista dentro de su propiedad @code{'elements}. Una nota se
1061 representa como una expresión @code{EventChord} que contiene un objeto
1062 @code{NoteEvent} (que almacena las propiedades de duración y altura) y
1063 cualquier información adicional (en este caso, un evento
1064 @code{AbsoluteDynamicEvent} con una propiedad @code{"f"} de texto.
1067 @node Propiedades musicales
1068 @subsection Propiedades musicales
1069 @translationof Music properties
1071 @c TODO -- make sure we delineate between @emph{music} properties,
1072 @c @emph{context} properties, and @emph{layout} properties. These
1073 @c are potentially confusing.
1075 El objeto @code{NoteEvent} es el primer objeto de la propiedad
1076 @code{'elements} de @code{someNote}.
1080 \displayMusic \someNote
1088 (ly:make-duration 2 0 1 1)
1090 (ly:make-pitch 0 0 0))))
1093 La función @code{display-scheme-music} es la función que se usa por
1094 parte de @code{\displayMusic} para imprimir la representación de
1095 Scheme de una expresión musical.
1098 #(display-scheme-music (first (ly:music-property someNote 'elements)))
1103 (ly:make-duration 2 0 1 1)
1105 (ly:make-pitch 0 0 0))
1108 Después se accede a la altura de la nota a través de la propiedad
1109 @code{'pitch} del objeto @code{NoteEvent}:
1112 #(display-scheme-music
1113 (ly:music-property (first (ly:music-property someNote 'elements))
1116 (ly:make-pitch 0 0 0)
1119 La altura de la nota se puede cambiar estableciendo el valor de esta
1120 propiedad @code{'pitch},
1122 @funindex \displayLilyMusic
1125 #(set! (ly:music-property (first (ly:music-property someNote 'elements))
1127 (ly:make-pitch 0 1 0)) ;; establecer la altura a d'.
1128 \displayLilyMusic \someNote
1134 @node Duplicar una nota con ligaduras (ejemplo)
1135 @subsection Duplicar una nota con ligaduras (ejemplo)
1136 @translationof Doubling a note with slurs (example)
1138 Supongamos que queremos crear una función que convierte una entrada
1139 como @code{a} en @code{a( a)}. Comenzamos examinando la
1140 representación interna de la música con la que queremos terminar.
1143 \displayMusic@{ a'( a') @}
1154 (ly:make-duration 2 0 1 1)
1156 (ly:make-pitch 0 5 0))
1167 (ly:make-duration 2 0 1 1)
1169 (ly:make-pitch 0 5 0))
1176 Las malas noticias son que las expresiones @code{SlurEvent} se deben
1177 añadir @q{dentro} de la nota (o para ser más exactos, dentro de la
1178 expresión @code{EventChord}).
1180 Ahora examinamos la entrada,
1192 (ly:make-duration 2 0 1 1)
1194 (ly:make-pitch 0 5 0))))))
1197 Así pues, en nuestra función, tenemos que clonar esta expresión (de
1198 forma que tengamos dos notas para construir la secuencia), añadir
1199 @code{SlurEvent} a la propiedad @code{'elements} de cada una de
1200 ellas, y por último hacer una secuencia @code{SequentialMusic} con los
1201 dos @code{EventChords}.
1204 doubleSlur = #(define-music-function (parser location note) (ly:music?)
1205 "Return: @{ note ( note ) @}.
1206 `note' is supposed to be an EventChord."
1207 (let ((note2 (ly:music-deep-copy note)))
1208 (set! (ly:music-property note 'elements)
1209 (cons (make-music 'SlurEvent 'span-direction -1)
1210 (ly:music-property note 'elements)))
1211 (set! (ly:music-property note2 'elements)
1212 (cons (make-music 'SlurEvent 'span-direction 1)
1213 (ly:music-property note2 'elements)))
1214 (make-music 'SequentialMusic 'elements (list note note2))))
1218 @node Añadir articulaciones a las notas (ejemplo)
1219 @subsection Añadir articulaciones a las notas (ejemplo)
1220 @translationof Adding articulation to notes (example)
1222 La manera fácil de añadir articulación a las notas es mezclar dos
1223 expresiones musicales en un solo contexto, como se explica en
1224 @ruser{Crear contextos}. Sin embargo, supongamos que queremos
1225 escribir una función musical que lo haga.
1227 Una @code{$variable} dentro de la notación @code{#@{...#@}} es como
1228 una @code{\variable} normal en la notación clásica de LilyPond.
1236 no funciona en LilyPond. Podríamos evitar este problema adjuntando la
1237 articulación a una nota falsa,
1240 @{ << \music s1*0-.-> @}
1244 pero a los efectos de este ejemplo, aprenderemos ahora cómo hacerlo en
1245 Scheme. Empezamos examinando nuestra entrada y la salida deseada,
1257 (ly:make-duration 2 0 1 1)
1259 (ly:make-pitch -1 0 0))))
1270 (ly:make-duration 2 0 1 1)
1272 (ly:make-pitch -1 0 0))
1279 Vemos que una nota (@code{c4}) se representa como una expresión
1280 @code{EventChord}, con una expresión @code{NoteEvent} en su lista de
1281 elementos. Para añadir una articulación de marcato, se debe añadir
1282 una expresión @code{ArticulationEvent} a la propiedad elements de la
1283 expresión @code{EventChord}.
1285 Para construir esta función, empezamos con
1288 (define (add-marcato event-chord)
1289 "Add a marcato ArticulationEvent to the elements of `event-chord',
1290 which is supposed to be an EventChord expression."
1291 (let ((result-event-chord (ly:music-deep-copy event-chord)))
1292 (set! (ly:music-property result-event-chord 'elements)
1293 (cons (make-music 'ArticulationEvent
1294 'articulation-type "marcato")
1295 (ly:music-property result-event-chord 'elements)))
1296 result-event-chord))
1299 La primera línea es la forma de definir una función en Scheme: el
1300 nombre de la función es @code{add-marcato}, y tiene una variable
1301 llamada @code{event-chord}. En Scheme, el tipo de variable suele
1302 quedar claro a partir de su nombre (¡esto también es una buena
1303 práctica en otros lenguajes de programación!)
1310 es una descripción de lo que hace la función. No es estrictamente
1311 necesaria, pero de igual forma que los nombres claros de variable, es
1315 (let ((result-event-chord (ly:music-deep-copy event-chord)))
1318 Se usa @code{let} para declarar las variables locales. Aquí usamos
1319 una variable local, llamada @code{result-event-chord}, a la que le
1320 damos el valor @code{(ly:music-deep-copy event-chord)}.
1321 @code{ly:music-deep-copy} es una función específica de LilyPond, como
1322 todas las funciones que comienzan por @code{ly:}. Se usa para hacer
1323 una copia de una expresión musical. Aquí, copiamos @code{event-chord}
1324 (el parámetro de la función). Recuerde que nuestro propósito es
1325 añadir un marcato a una expresión @code{EventChord}. Es mejor no
1326 modificar el @code{EventChord} que se ha dado como argumento, porque
1327 podría utilizarse en algún otro lugar.
1329 Ahora tenemos un @code{result-event-chord}, que es una expresión
1330 @code{NoteEventChord} y es una copia de @code{event-chord}. Añadimos
1331 el marcato a su propiedad de la lista de @code{'elements}.
1334 (set! lugar valor-nuevo)
1337 Aquí, lo que queremos establecer (el @q{lugar}) es la propiedad
1338 @code{'elements} de la expresión @code{result-event-chord}.
1341 (ly:music-property result-event-chord 'elements)
1344 @code{ly:music-property} es la función que se usa para acceder a las
1345 propiedades musicales (los @code{'elements}, @code{'duration},
1346 @code{'pitch}, etc, que vimos en la salida de @code{\displayMusic}
1347 anterior). El nuevo valor es la antigua propiedad @code{'elements},
1348 con un elemento adicional: la expresión @code{ArticulationEvent}, que
1349 copiamos a partir de la salida de @code{\displayMusic},
1352 (cons (make-music 'ArticulationEvent
1353 'articulation-type "marcato")
1354 (ly:music-property result-event-chord 'elements))
1357 @code{cons} se usa para añadir un elemento a una lista sin modificar
1358 la lista original. Esto es lo que queremos: la misma lista que antes,
1359 más la expresión @code{ArticulationEvent} nueva. El orden dentro de
1360 la propiedad @code{'elements} no es importante aquí.
1362 Finalmente, una vez hemos añadido la articulación marcato a su
1363 propiedad @code{elements}, podemos devolver @code{result-event-chord},
1364 de ahí la última línea de la función.
1366 Ahora transformamos la función @code{add-marcato} en una función
1370 addMarcato = #(define-music-function (parser location event-chord)
1372 "Add a marcato ArticulationEvent to the elements of `event-chord',
1373 which is supposed to be an EventChord expression."
1374 (let ((result-event-chord (ly:music-deep-copy event-chord)))
1375 (set! (ly:music-property result-event-chord 'elements)
1376 (cons (make-music 'ArticulationEvent
1377 'articulation-type "marcato")
1378 (ly:music-property result-event-chord 'elements)))
1379 result-event-chord))
1382 Podemos verificar que esta función musical funciona correctamente:
1385 \displayMusic \addMarcato c4
1395 * Trucos con Scheme::
1398 @c @nod e Trucos con Scheme
1399 @c @sectio n Trucos con Scheme
1400 @translationof Tweaking with Scheme
1402 Hemos visto cómo la salida de LilyPond se puede modificar
1403 profundamente usando instrucciones como @code{\override TextScript
1404 #'extra-offset = ( 1 . -1)}. Pero tenemos incluso mucho más poder si
1405 utilizamos Scheme. Para ver una explicación completa de esto,
1406 consulte el @ref{Tutorial de Scheme}, y @ruser{Interfaces para programadores}.
1408 Podemos usar Scheme simplemente para sobreescribir instrucciones con
1411 TODO Find a simple example
1412 @c This isn't a valid example with skylining
1413 @c It works fine without padText -td
1417 @lilypond[quote,verbatim,ragged-right]
1418 padText = #(define-music-function (parser location padding) (number?)
1420 \once \override TextScript #'padding = #$padding
1424 c4^"piu mosso" b a b
1426 c4^"piu mosso" d e f
1428 c4^"piu mosso" fis a g
1434 Lo podemos usar para crear instrucciones nuevas:
1436 @c Check this is a valid example with skylining
1437 @c It is - 'padding still works
1440 @lilypond[quote,verbatim,ragged-right]
1441 tempoPadded = #(define-music-function (parser location padding tempotext)
1444 \once \override Score.MetronomeMark #'padding = $padding
1445 \tempo \markup { \bold $tempotext }
1449 \tempo \markup { "Low tempo" }
1451 \tempoPadded #4.0 #"High tempo"
1457 Incluso se le pueden pasar expresiones musicales:
1459 @lilypond[quote,verbatim,ragged-right]
1460 pattern = #(define-music-function (parser location x y) (ly:music? ly:music?)
1467 \pattern {d16 dis} { ais16-> b\p }