1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
2 @c This file is part of extending.tely
4 Translation of GIT committish: 1f0a00b69403290b7fc7527b9ab100f95533f954
6 When revising a translation, copy the HEAD committish of the
7 version that you are working on. See TRANSLATION for details.
12 @node Interfaces para programadores
13 @chapter Interfaces para programadores
14 @translationof Interfaces for programmers
16 Se pueden realizar trucos avanzados mediante el uso de Scheme. Si no
17 está familiarizado con Scheme, le conviene leer nuestro tutorial de
18 Scheme, @ref{Tutorial de Scheme}.
22 * Bloques de código de LilyPond::
23 * Funciones de Scheme::
24 * Funciones musicales::
25 * Funciones de eventos::
26 * Funciones de marcado::
27 * Contextos para programadores::
28 * Funciones de callback::
29 * Código de Scheme en línea::
33 @node Bloques de código de LilyPond
34 @section Bloques de código de LilyPond
35 @translationof Lilypond code blocks
37 Los bloques de código de LilyPond tienen el siguiente aspecto:
39 #@{ @var{código de LilyPond} #@}
41 Se pueden usar en cualquier lugar en el que se pueda escribir código
42 de Scheme: el lector de Scheme en efecto se modifica para que pueda
43 incorporar bloques de código de LilyPond y pueda ocuparse de las
44 expresiones de Scheme incrustadas que comienzan por @code{$} y@w{ }@code{#}.
46 Extrae el bloque de código de LilyPond y genera una llamada al
47 @code{parser} o analizador sintáctico de LilyPond, que corre en tiempo
48 de ejecución para interpretar el bloque de código de LilyPond.
49 Cualquier expresión de Scheme que se halle incrustada se ejecuta en el
50 entorno léxico del bloque de código de LilyPond, de manera que tenemos
51 acceso a las variables locales y a los parámetros de función en el
52 punto en que se encuentra escrito el bloque de código de LilyPond.
54 Un bloque de código de LilyPond puede contener cualquier cosa que
55 podríamos utilizar en la parte derecha de una asignación. Además, un
56 bloque de LilyPond vacío corresponde a una expresión musical vacía, y
57 un bloque de LilyPond que contiene varios eventos musicales se
58 convierte en una expresión de música secuencial.
60 @node Funciones de Scheme
61 @section Funciones de Scheme
62 @translationof Scheme functions
63 @cindex Scheme, funciones de (sintaxis de LilyPond)
65 Las @emph{funciones de Scheme} son procedimientos de Scheme que pueden
66 crear expresiones de Scheme a partir de código de entrada escrito en
67 la sintaxis de LilyPond. Se pueden llamar desde prácticamente
68 cualquier lugar en el que se permita el uso de @code{#} para la
69 especificación de un valor en sintaxis de Scheme. Mientras que Scheme
70 tiene funciones propias, este capítulo se ocupa de las funciones
71 @emph{sintácticas}, funciones que reciben argumentos especificados en
72 la sintaxis de LilyPond.
75 * Definición de funciones de Scheme::
76 * Uso de las funciones de Scheme::
77 * Funciones de Scheme vacías::
80 @node Definición de funciones de Scheme
81 @subsection Definición de funciones de Scheme
82 @translationof Scheme function definitions
83 @funindex define-scheme-function
85 La forma general de la definición de una función de Scheme es:
89 #(define-scheme-function
90 (parser location @var{arg1} @var{arg2} @dots{})
91 (@var{tipo1?} @var{tipo2?} @dots{})
98 @multitable @columnfractions .33 .66
100 @tab tiene que ser literalmente @code{parser} para dar a los bloques de código
101 de LilyPond (@code{#@{}@dots{}@code{#@}}) acceso al analizador
104 @item @code{@var{argN}}
105 @tab @var{n}-ésimo argumento
107 @item @code{@var{typeN?}}
108 @tab un @emph{predicado de tipo} de Scheme para el que @code{@var{argN}}
109 debe devolver @code{#t}. Algunos de estos predicados se reconocen de
110 forma especial por parte del analizador, véase más abajo. También
111 existe una forma especial @code{(@emph{predicate?} @emph{default})}
112 para especificar argumentos opcionales. Si el argumento actual no
113 está presente cuando se ll ama a la función, el valor predeterminado se
114 emplea en sustitución. Los valores predeterminados se evalúan en
115 tiempo de definición (¡incluyendo los bloques de código de LilyPond!),
116 de manera que se necesitamos un valor por omisión calculado en tiempo
117 de ejecución, debemos escribir en su lugar un valor especial que
118 podamos reconocer fácilmente. Si escribimos el predicado entre
119 paréntesis pero no lo seguimos por el valor predeterminado, se usa
120 @code{#f} como valor por omisión. Los valores por omisión no se
121 verifican con @emph{predicate?} en tiempo de definición ni en tiempo
122 de ejecución: es nuestra responsabilidad tratar con los valores que
123 especifiquemos. Los valores por omisión que son expresiones musicales
124 se copian mientras se establece @code{origin} al parámetro
127 @item @code{@var{cuerpo}}
128 @tab una secuencia de formas de Scheme que se evalúan ordenadamente; la
129 última forma de la secuencia se usa como el valor de retorno de la
130 función de Scheme. Puede contener bloques de código de LilyPond
131 encerrados entre llaves con almohadillas
132 (@tie{}@w{@code{#@{@dots{}#@}}}@tie{}), como se describe en
133 @ref{Bloques de código de LilyPond}. Dentro de los bloques de código
134 de LilyPond, use el símbolo @code{#} para hacer referencia a
135 argumentos de función (p.ej. @samp{#arg1}) o para iniciar una
136 expresión en línea de Scheme que contenga argumentos de función
137 (p.ej. @w{@samp{#(cons arg1 arg2)}}). Donde las expresiones de Scheme
138 normales que usan @code{#} no funcionan, podríamos necesitar volver a
139 expresiones de Scheme inmediatas que usan @code{$}, como por ejemplo
142 Si nuestra función devuelve una expresión musical, recibe un valor
147 Ciertos predicados de tipo se manejan de forma especial por parte del
148 analizador sintáctico ya que de otro modo éste no es capaz de
149 reconocer los argumentos eficientemente. Actualmente son
150 @code{ly:pitch?} y @code{ly:duration?}.
152 La idoneidad de lpos argumentos para el resto de los predicados viene
153 determinada mediante llamadas reales al predicado después de que
154 LilyPond ya las ha convertido en una expresión de Scheme. Como
155 consecuencia, el argumento se puede especificar en la sintaxis de
156 Scheme si se desea (precedido de @code{#} o como resultado de haber
157 llamado a una función de Scheme), pero LilyPond también convierte
158 algunas construcciones de LilyPond en Scheme antes de hacer
159 efectivamente la comprobación del predicado sobre ellas. Actualmente
160 se encuentran entre ellas la música, los post-eventos, las cadenas
161 simples (entrecomilladas o no), los números, los elementos de marcado
162 y de listas de marcado, score (partitura), book (libro), bookpart
163 (parte de libro), las definiciones de contexto y los bloques de
164 definición de salida.
166 Para ciertos tipos de expresión (como la mayor parte de la música que
167 no está encerrada entre llaves) LilyPond necesita más allá de la
168 expresión misma para poder determinar su final. Si tal expresión se
169 considerase un argumento opcional mediante la evaluación de su
170 predicado, LilyPond no podría recuperarse después de decidir que la
171 expresión no se corresponde con el parámetro. Así, ciertas formas de
172 música necesitan ir encerradas entre llaves para que LilyPond pueda
173 aceptarlas. Existen también otras ambigüedades que LilyPond resuelve
174 mediante la comprobación con funciones de predicado: ¿es @samp{-3} un
175 post-evento de digitación o un nnúmero negativo? ¿Es @code{"a" 4} en
176 el modo de letra una cadena seguida por un número, o un evento de
177 letra con la duración @code{4}? LilyPond lo decide preguntándole a
178 los predicados. Ello significa que un debemos evitar los
179 predicados permisivos como @code{scheme?} si tenemos en mente
180 un uso particular en vez de una función de uso general.
182 Para ver una lista de los predicados de tipo disponibles, consulte
183 @ruser{Predicados de tipo predefinidos}.
187 Referencia de la notación:
188 @ruser{Predicados de tipo predefinidos}.
191 @file{lily/music-scheme.cc},
196 @node Uso de las funciones de Scheme
197 @subsection Uso de las funciones de Scheme
198 @translationof Scheme function usage
200 Las funciones de Scheme se pueden llamar casi desde cualquier lugar en
201 que puede escribirse una expresión de Scheme que comience con la
202 almohadilla@tie{}@code{#}. Llamamos a una función de Scheme
203 escribiendo su nombre precedido de la barra invertida@tie{}@code{\}, y
204 seguido por sus argumentos. Una vez que un argumento opcional no
205 corresponde a ningún argumento, LilyPond se salta este argumento y
206 todos los que le siguen, sustituyéndolos por su valor por omisión
207 especificado, y @q{recupera} el argumento que no correspondía al lugar
208 del siguiente argumento obligatorio. Dado que el argumento recuperado
209 necesita ir a algún lugar, los argumentos opcionales no se consideran
210 realmente opcionales a no ser que vayan seguidos de un argumento
213 Existe una excepción: si escribimos @code{\default} en el lugar de un
214 argumento opcional, este argumento y todos los argumentos opcionales
215 que le siguen se saltan y se sustituyen por sus valores
216 predeterminados. Esto funciona incluso si no sigue ningún argumento
217 obligatorio porque @code{\default} no necesita recuperarse. Las
218 instrucciones @code{mark} y @code{key} hacen uso de este truco para
219 ofrecer su comportamiento predeterminado cuando van seguidas solamente
222 Aparte de los lugares en que se requiere un valor de Scheme hay
223 ciertos sitios en que se aceptan expresiones de almohadilla @code{#} y
224 se evalúan por sus efectos secundarios, pero por lo demás se ignoran.
225 Son, mayormente, los lugares en que también sería aceptable colocar
228 Dado que no es buena idea devolver valores que puedan malinterpretarse
229 en algún contexto, debería usar funciones de Scheme normales solo para
230 los casos en que siempre se devuelve un valor útil, y usar funciones
231 de Scheme vacías (@pxref{Funciones de Scheme vacías}) en caso
235 @node Funciones de Scheme vacías
236 @subsection Funciones de Scheme vacías
237 @translationof Void scheme functions
238 @funindex define-void-function
241 En ocasiones, un procedimiento se ejecuta con el objeto de llevar a
242 cabo alguna acción más que para devolver un valor. Algunos lenguajes
243 de programación (como C y Scheme) usan las funciones para los dos
244 conceptos y se limitan a descartar el valor devuelto (usualmente
245 haciendo que cualquier expresión pueda actuar como instrucción,
246 ignorando el resultado devuelto). Esto puede parecer inteligente pero
247 es propenso a errores: casi todos los compiladores de C de hoy en día
248 emiten advertencias cuando se descarta una expresión no vacía. Para
249 muchas funciones que ejecutan una acción, los estándares de Scheme
250 declaran que el valor de retorno sea no especificado. Guile, el
251 intérprete de Scheme de LilyPond, tiene un valor único
252 @code{*unspecified*} que en tales casos devuelve de forma usual (como
253 cuando se usa directamente @code{set!} sobre una variable), pero
254 desgraciadamente no de forma consistente.
256 Definir una función de LilyPond con @code{define-void-function}
257 asegura que se devuelve este valor especial, el único valor que
258 satisface el predicado @code{void?}.
262 #(define-void-function
265 (ly:set-option 'point-and-click #f))
267 \noApuntarYPulsar % desactivar la función de apuntar y pulsar
270 Si queremos evaluar una expresión sólo por su efecto colateral y no
271 queremos que se interprete ningún valor que pueda devolver, podemos
272 hacerlo anteponiendo el prefijo @code{\void}:
275 \void #(hashq-set! some-table some-key some-value)
278 De esta forma podemos asegurar que LilyPond no asignará ningún
279 significado al valor devuelto, independientemente de dónde lo
280 encuentre. También funciona para funciones musicales como
281 @code{\displayMusic}.
283 @node Funciones musicales
284 @section Funciones musicales
285 @translationof Music functions
287 @cindex funciones musicales
289 Las @emph{funciones musicales} son procedimientos de Scheme que pueden
290 crear automáticamente expresiones musicales, y se pueden usar para
291 simplificar enormemente el archivo de entrada.
294 * Definiciones de funciones musicales::
295 * Uso de las funciones musicales::
296 * Funciones de sustitución sencillas::
297 * Funciones de sustitución intermedias::
298 * Matemáticas dentro de las funciones::
299 * Funciones sin argumentos::
300 * Funciones musicales vacías::
304 @node Definiciones de funciones musicales
305 @subsection Definiciones de funciones musicales
306 @translationof Music function definitions
307 @cindex definición de funciones musicales
308 @funindex define-music-function
310 La forma general para definir funciones musicales es:
314 #(define-music-function
315 (parser location @var{arg1} @var{arg2} @dots{})
316 (@var{tipo1?} @var{tipo2?} @dots{})
321 de forma bastante análoga a @ref{Definición de funciones de Scheme}.
322 Lo más probable es que el @var{cuerpo} sea un
323 @ref{Bloques de código de LilyPond,bloque de código de LilyPond}.
325 Para ver una lista de los predicados de tipo disponibles, consulte
326 @ruser{Predicados de tipo predefinidos}.
330 Referencia de la notación:
331 @ruser{Predicados de tipo predefinidos}.
334 @file{lily/music-scheme.cc},
339 @node Uso de las funciones musicales
340 @subsection Uso de las funciones musicales
341 @translationof Music function usage
343 Las funciones musicales se pueden actualmente utilizar en varios
344 lugares. Dependiendo de dónde se usan, son de aplicación ciertas
345 restricciones para que sea posible su análisis sintáctico de forma
346 no ambigua. El resultado que devuelve una función musical debe ser
347 compatible con el contexto desde el que se la llama.
351 En el nivel superior dentro de una expresión musical. Aquí
352 no se aplica ninguna restricción.
355 Como un post-evento, que comienza explícitamente con un indicador de
356 dirección (a elegir entre @code{-}, @code{^} @w{y @code{_}}).
357 Observe que se puede aceptar la devolución de un
358 post-evento por parte de las funciones musicales que se llaman como
359 música normal, lo que lleva a un resultado aproximadamente equivalente
365 En este caso, no podemos usar una expresión musical @emph{abierta}
366 como último argumento, que terminaría en una expresión musical
367 capaz de aceptar post-eventos adicionales.
370 Como componente de un acorde. La expresión devuelta debe ser
371 del tipo @code{rhythmic-event}, probablemente un @code{NoteEvent}.
375 Las reglas especiales para los argumentos del final hacen posible
376 escribir funciones polimórficas como @code{\tweak} que se pueden
377 aplicar a construcciones distintas.
379 @node Funciones de sustitución sencillas
380 @subsection Funciones de sustitución sencillas
381 @translationof Simple substitution functions
383 Una función de sustitución sencilla es una función musical cuya
384 expresión musical de salida está escrita en código de LilyPond
385 y contiene argumentos de la función en la expresión de salida.
386 Están descritas en @ruser{Ejemplos de funciones de sustitución}.
389 @node Funciones de sustitución intermedias
390 @subsection Funciones de sustitución intermedias
391 @translationof Intermediate substitution functions
393 Las funciones de sustitución intermedias contienen una
394 mezcla de código de Scheme y de LilyPond
395 dentro de la expresión musical que se devuelve.
397 Algunas instrucciones @code{\override} requieren un argumento que
398 consiste en una pareja de números (llamada una @emph{célula cons} en
401 La pareja se puede pasar directamente dentro de la función musical,
402 usando una variable @code{pair?}:
406 #(define-music-function
407 (parser location principio-final)
410 \once \override Beam #'positions = #principio-final
414 \barraManual #'(3 . 6) c8 d e f
418 De forma alternativa, los números que componen la pareja se pueden
419 pasar como argumentos separados, y el código de Scheme que se ha usado
420 para crear la pareja se puede incluir dentro de la expresión musical:
422 @lilypond[quote,verbatim,ragged-right]
424 #(define-music-function
425 (parser location beg end)
428 \once \override Beam #'positions = #(cons beg end)
432 \manualBeam #3 #6 c8 d e f
437 @node Matemáticas dentro de las funciones
438 @subsection Matemáticas dentro de las funciones
439 @translationof Mathematics in functions
441 Las funciones musicales pueden contar con programación de Scheme
442 además de la simple sustitución:
444 @lilypond[quote,verbatim,ragged-right]
446 #(define-music-function
447 (parser location mag)
450 \override Stem #'length = #(* 7.0 mag)
451 \override NoteHead #'font-size =
452 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
456 \revert Stem #'length
457 \revert NoteHead #'font-size
462 \AltOn #1.5 c c \AltOff c2
467 Este ejemplo se puede reescribir de forma que pase expresiones
470 @lilypond[quote,verbatim,ragged-right]
472 #(define-music-function
473 (parser location mag music)
476 \override Stem #'length = #(* 7.0 mag)
477 \override NoteHead #'font-size =
478 #(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
480 \revert Stem #'length
481 \revert NoteHead #'font-size
485 c2 \withAlt #0.5 { c4 c }
486 \withAlt #1.5 { c c } c2
491 @node Funciones sin argumentos
492 @subsection Funciones sin argumentos
493 @translationof Functions without arguments
495 En casi todos los casos, una función sin argumentos se debe escribir
499 dolce = \markup@{ \italic \bold dolce @}
502 Sin embargo, en raras ocasiones puede ser de utilidad crear una
503 función musical sin argumentos:
506 mostrarNumeroDeCompas =
507 #(define-music-function
510 (if (eq? #t (ly:get-option 'display-bar-numbers))
511 #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
515 Para la impresión real de los números de compás donde se llama a esta
516 función, invoque a @command{lilypond} con
519 lilypond -d display-bar-numbers ARCHIVO.ly
523 @node Funciones musicales vacías
524 @subsection Funciones musicales vacías
525 @translationof Void music functions
527 Una función musical debe devolver una expresión musical. Si quiere
528 ejecutar una función exclusivamente por sus efectos secundarios,
529 debería usar @code{define-void-function}. Pero
530 puede haber casos en los que a veces queremos producir una expresión
531 musical, y a veces no (como en el ejemplo anterior). Devolver una
532 expresión musical @code{void} (vacía) por medio de @code{#@{ #@}} lo
536 @node Funciones de eventos
537 @section Funciones de eventos
538 @translationof Event functions
539 @funindex define-event-function
540 @cindex event functions
542 Para usar una función musical en el lugar de un evento, tenemos que
543 escribir un indicador de dirección antes de ella. Pero a veces, ello
544 hace que se pierda la correspondencia con la sintaxis de las
545 construcciones que queremos sustituir. Por ejemplo, si queremos
546 escribir instrucciones de matiz dinámico, éstos se adjuntan
547 habitualmente sin indicador de dirección, como @code{c'\pp}. He aquí
548 una forma de escribir indicaciones dinámicas arbitrarias:
550 @lilypond[quote,verbatim,ragged-right]
551 dyn=#(define-event-function (parser location arg) (markup?)
552 (make-dynamic-script arg))
553 \relative c' { c\dyn pfsss }
556 Podríamos hacer lo mismo usando una función musical, pero entonces
557 tendríamos que escribir siempre un indicador de dirección antes de
558 llamarla, como @code{@w{c-\dyn pfsss}}.
561 @node Funciones de marcado
562 @section Funciones de marcado
563 @translationof Markup functions
565 Los elementos de marcado están implementados como funciones de Scheme
566 especiales que producen un objeto @code{Stencil} dada una serie de
571 * Construcción de elementos de marcado en Scheme::
572 * Cómo funcionan internamente los elementos de marcado::
573 * Definición de una instrucción de marcado nueva::
574 * Definición de nuevas instrucciones de lista de marcado::
577 @node Construcción de elementos de marcado en Scheme
578 @subsection Construcción de elementos de marcado en Scheme
579 @translationof Markup construction in Scheme
581 @cindex marcado, definir instrucciones de
583 El macro @code{markup} construye expresiones de marcado en Scheme,
584 proporcionando una sintaxis similar a la de LilyPond. Por ejemplo:
587 (markup #:column (#:line (#:bold #:italic "hola" #:raise 0.4 "mundo")
588 #:larger #:line ("fulano" "fulanito" "menganito")))
594 #@{ \markup \column @{ \line @{ \bold \italic "hola" \raise #0.4 "mundo" @}
595 \larger \line @{ fulano fulanito menganito @} @} #@}
599 Este ejemplo muestra las principales reglas de traducción entre la
600 sintaxis del marcado normal de LilyPond y la sintaxis del marcado de
601 Scheme. La utilización de @code{#@{ @dots{} #@}} para escribir en la
602 sintaxis de LilyPond será con frecuencia lo más conveniente, pero
603 explicamos cómo usar la macro @code{markup} para obtener una solución
607 @multitable @columnfractions .3 .3
608 @item @b{LilyPond} @tab @b{Scheme}
609 @item @code{\markup marcado1} @tab @code{(markup marcado1)}
610 @item @code{\markup @{ marcado1 marcado2 ... @}} @tab
611 @code{(markup marcado1 marcado2 ... )}
612 @item @code{\instruccion} @tab @code{#:instruccion}
613 @item @code{\variable} @tab @code{variable}
614 @item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}
615 @item @code{cadena} @tab @code{"cadena"}
616 @item @code{#argumento-de-scheme} @tab @code{argumento-de-scheme}
620 Todo el lenguaje Scheme está accesible dentro del macro @code{markup}.
621 Por ejemplo, podemos usar llamadas a funciones dentro de @code{markup}
622 para así manipular cadenas de caracteres. Esto es útil si se están
623 definiendo instrucciones de marcado nuevas (véase
624 @ref{Definición de una instrucción de marcado nueva}).
629 El argumento markup-list de instrucciones como @code{#:line},
630 @code{#:center} y @code{#:column} no puede ser una variable ni el
631 resultado de la llamada a una función.
634 (markup #:line (funcion-que-devuelve-marcados))
638 no es válido. Hay que usar las funciones @code{make-line-markup},
639 @code{make-center-markup} o @code{make-column-markup} en su lugar:
642 (markup (make-line-markup (funcion-que-devuelve-marcados)))
646 @node Cómo funcionan internamente los elementos de marcado
647 @subsection Cómo funcionan internamente los elementos de marcado
648 @translationof How markups work internally
650 En un elemento de marcado como
653 \raise #0.5 "ejemplo de texto"
657 @code{\raise} se representa en realidad por medio de la función
658 @code{raise-markup}. La expresión de marcado se almacena como
661 (list raise-markup 0.5 (list simple-markup "ejemplo de texto"))
664 Cuando el marcado se convierte en objetos imprimibles (Stencils o
665 sellos), se llama la función @code{raise-markup} como
669 @var{\objeto de marcado}
670 @var{lista de listas asociativas de propiedades}
672 @var{el marcado "ejemplo de texto"})
675 Primero la función @code{raise-markup} crea el sello para la cadena
676 @code{ejemplo de texto}, y después eleva el sello Stencil en 0.5
677 espacios de pentagrama. Este es un ejemplo bastante simple; en el
678 resto de la sección podrán verse ejemplos más complejos, así como en
679 @file{scm/define-markup-commands.scm}.
682 @node Definición de una instrucción de marcado nueva
683 @subsection Definición de una instrucción de marcado nueva
684 @translationof New markup command definition
686 Esta sección trata sobre la definición de nuevas instrucciones de
691 * Sintaxis de la definición de instrucciones de marcado::
692 * Acerca de las propiedades::
693 * Un ejemplo completo::
694 * Adaptación de instrucciones incorporadas::
697 @node Sintaxis de la definición de instrucciones de marcado
698 @unnumberedsubsubsec Sintaxis de la definición de instrucciones de marcado
699 @translationof Markup command definition syntax
701 Se pueden definir instrucciones de marcado nuevas usando el macro de
702 Scheme @code{define-markup-command}, en el nivel sintáctico superior.
705 (define-markup-command (@var{nombre-de-la-instruccion} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
706 (@var{tipo-de-arg1?} @var{tipo-de-arg2?} ...)
707 [ #:properties ((@var{propiedad1} @var{valor-predeterminado1})
715 @item @var{nombre-de-la-instruccion}
716 nombre de la instrucción de marcado
718 la definición de @q{layout} (disposición).
720 una lista de listas asociativas, que contienen todas las propiedades
723 argumento @var{i}-ésimo de la instrucción
724 @item @var{tipo-de-argi?}
725 predicado de tipo para el argumento @var{i}-ésimo
728 Si la instrucción utiliza propiedades de los argumentos @code{props},
729 se puede usar la palabra clave @code{#:properties} para especificar
730 qué propiedades se usan, así como sus valores predeterminados.
732 Los argumentos se distinguen según su tipo:
734 @item un marcado, que corresponde al predicado de tipo @code{markup?};
735 @item una lista de marcados, que corresponde al predicado de tipo
737 @item cualquier otro objeto de Scheme, que corresponde a predicados de tipo como
738 @code{list?}, @code{number?}, @code{boolean?}, etc.
741 No existe ninguna limitación en el orden de los argumentos (después de
742 los argumentos estándar @code{layout} y @code{props}). Sin embargo, las
743 funciones de marcado que toman un elemento de marcado como su último
744 argumento son un poco especiales porque podemos aplicarlas a una lista
745 de marcados y el resultado es una lista de marcados donde la función
746 de marcado (con los argumentos antecedentes especificados) se ha
747 aplicado a todos los elementos de la lista de marcados original.
749 Dado que la replicación de los argumentos precedentes para aplicar una
750 función de marcado a una lista de marcados es poco costosa
751 principalmente por los argumentos de Scheme, se evitan las caídas de
752 rendimiento simplemente mediante la utilización de argumentos de
753 Scheme para los argumentos antecedentes de las funciones de marcado
754 que toman un marcado como su último argumento.
756 @node Acerca de las propiedades
757 @unnumberedsubsubsec Acerca de las propiedades
758 @translationof On properties
760 Los argumentos @code{layout} y @code{props} de las instrucciones de
761 marcado traen a escena un contexto para la interpretación del marcado:
762 tamaño de la tipografía, grueso de línea, etc.
764 El argumento @code{layout} permite el acceso a las propiedades
765 definidas en los bloques @code{paper}, usando la función
766 @code{ly:output-def-lookup}. Por ejemplo, el grueso de línea (el
767 mismo que el que se usa en las partituras) se lee usando:
770 (ly:output-def-lookup layout 'line-width)
773 El argumento @code{props} hace accesibles algunas propiedades a las
774 instrucciones de marcado. Por ejemplo, cuando se interpreta el
775 marcado del título de un libro, todas las variables definidas dentro
776 del bloque @code{\header} se añaden automáticamente a @code{props}, de
777 manera que el marcado del título del libro puede acceder al título del
778 libro, el autor, etc. También es una forma de configurar el
779 comportamiento de una instrucción de marcado: por ejemplo, cuando una
780 instrucción utiliza tamaños de tipografía durante el procesado, el
781 tamaño se lee de @code{props} en vez de tener un argumento
782 @code{font-size}. El que llama a una instrucción de marcado puede
783 cambiar el valor de la propiedad del tamaño de la tipografía con el
784 objeto de modificar el comportamiento. Utilice la palabra clave
785 @code{#:properties} de @code{define-markup-command} para especificar
786 qué propiedades se deben leer a partir de los argumentos de
789 El ejemplo de la sección siguiente ilustra cómo acceder y
790 sobreescribir las propiedades de una instrucción de marcado.
793 @node Un ejemplo completo
794 @unnumberedsubsubsec Un ejemplo completo
795 @translationof A complete example
797 El ejemplo siguiente define una instrucción de marcado para trazar un
798 rectángulo doble alrededor de un fragmento de texto.
800 En primer lugar, necesitamos construir un resultado aproximado
801 utilizando marcados. Una consulta a @ruser{Instrucciones de marcado
802 de texto} nos muestra que es útil la instrucción @code{\box}:
804 @lilypond[quote,verbatim,ragged-right]
805 \markup \box \box HELLO
808 Ahora, consideramos que es preferible tener más separación entre el
809 texto y los rectángulos. Según la documentación de @code{\box}, esta
810 instrucción usa una propiedad @code{box-padding}, cuyo valor
811 predeterminado es 0.2. La documentación también menciona cómo
812 sobreescribir este valor:
814 @lilypond[quote,verbatim,ragged-right]
815 \markup \box \override #'(box-padding . 0.6) \box A
818 Después, el relleno o separación entre los dos rectángulos nos parece
819 muy pequeño, así que lo vamos a sobreescribir también:
821 @lilypond[quote,verbatim,ragged-right]
822 \markup \override #'(box-padding . 0.4) \box
823 \override #'(box-padding . 0.6) \box A
826 Repetir esta extensa instrucción de marcado una y otra vez sería un
827 quebradero de cabeza. Aquí es donde se necesita una instrucción de
828 marcado. Así pues, escribimos una instrucción de marcado
829 @code{double-box}, que toma un argumento (el texto). Dibuja los dos
830 rectángulos y añade una separación.
833 #(define-markup-command (double-box layout props text) (markup?)
834 "Trazar un rectángulo doble rodeando el texto."
835 (interpret-markup layout props
836 #@{\markup \override #'(box-padding . 0.4) \box
837 \override #'(box-padding . 0.6) \box @{ $text @}#@}))
843 #(define-markup-command (double-box layout props text) (markup?)
844 "Trazar un rectángulo doble rodeando el texto."
845 (interpret-markup layout props
846 (markup #:override '(box-padding . 0.4) #:box
847 #:override '(box-padding . 0.6) #:box text)))
850 @code{text} es el nombre del argumento de la instrucción, y
851 @code{markup?} es el tipo: lo identifica como un elemento de marcado.
852 La función @code{interpret-markup} se usa en casi todas las
853 instrucciones de marcado: construye un sello, usando @code{layout},
854 @code{props}, y un elemento de marcado. En el segundo caso, la marca
855 se construye usando el macro de Scheme @code{markup}, véase
856 @ref{Construcción de elementos de marcado en Scheme}. La
857 transformación de una expresión @code{\markup} en una expresión de
858 marcado de Scheme es directa.
860 La instrucción nueva se puede usar como sigue:
863 \markup \double-box A
866 Sería buen hacer que la instrucción @code{double-box} fuera
867 personalizable: aquí, los valores de relleno @code{box-padding} son
868 fijos, y no se pueden cambiar por parte del usuario. Además, sería
869 mejor distinguir la separación entre los dos rectángulos, del relleno
870 entre el rectángulo interno y el texto. Así pues, introducimos una
871 nueva propiedad, @code{inter-box-padding}, para el relleno entre los
872 rectángulos. El @code{box-padding} se usará para el relleno interno.
873 Ahora el código nuevo es como se ve a continuación:
876 #(define-markup-command (double-box layout props text) (markup?)
877 #:properties ((inter-box-padding 0.4)
879 "Trazar un rectángulo doble rodeando el texto."
880 (interpret-markup layout props
881 #@{\markup \override #`(box-padding . ,inter-box-padding) \box
882 \override #`(box-padding . ,box-padding) \box
886 De nuevo, la versión equivalente que utiliza la macro de marcado sería:
889 #(define-markup-command (double-box layout props text) (markup?)
890 #:properties ((inter-box-padding 0.4)
892 "Trazar un rectángulo doble rodeando el texto."
893 (interpret-markup layout props
894 (markup #:override `(box-padding . ,inter-box-padding) #:box
895 #:override `(box-padding . ,box-padding) #:box text)))
898 Aquí, la palabra clave @code{#:properties} se usa de manera que las
899 propiedades @code{inter-box-padding} y @code{box-padding} se leen a
900 partir del argumento @code{props}, y se les proporcionan unos valores
901 predeterminados si las propiedades no están definidas.
903 Después estos valores se usan para sobreescribir las propiedades
904 @code{box-padding} usadas por las dos instrucciones @code{\box}.
905 Observe el apóstrofo invertido y la coma en el argumento de
906 @code{\override}: nos permiten introducir un valor de variable dentro
907 de una expresión literal.
909 Ahora, la instrucción se puede usar dentro de un elemento de marcado,
910 y el relleno de los rectángulos se puede personalizar:
912 @lilypond[quote,verbatim,ragged-right]
913 #(define-markup-command (double-box layout props text) (markup?)
914 #:properties ((inter-box-padding 0.4)
916 "Draw a double box around text."
917 (interpret-markup layout props
918 #{\markup \override #`(box-padding . ,inter-box-padding) \box
919 \override #`(box-padding . ,box-padding) \box
922 \markup \double-box A
923 \markup \override #'(inter-box-padding . 0.8) \double-box A
924 \markup \override #'(box-padding . 1.0) \double-box A
928 @node Adaptación de instrucciones incorporadas
929 @unnumberedsubsubsec Adaptación de instrucciones incorporadas
930 @translationof Adapting builtin commands
932 Una buena manera de comenzar a escribir una instrucción de marcado
933 nueva, es seguir el ejemplo de otra instrucción ya incorporada. Casi
934 todas las instrucciones de marcado que están incorporadas en LilyPond
935 se pueden encontrar en el archivo
936 @file{scm/define-markup-commands.scm}.
938 Por ejemplo, querríamos adaptar la instrucción @code{\draw-line}, para
939 que trace una línea doble. La instrucción @code{\draw-line} está
940 definida como sigue (se han suprimido los comentarios de
944 (define-markup-command (draw-line layout props dest)
947 #:properties ((thickness 1))
948 "...documentación..."
949 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
953 (make-line-stencil th 0 0 x y)))
956 Para definir una instrucción nueva basada en otra existente, copie la
957 definición y cámbiele el nombre. La palabra clave @code{#:category}
958 se puede eliminar sin miedo, pues sólo se utiliza para generar
959 documentación de LilyPond, y no tiene ninguna utilidad para las
960 instrucciones de marcado definidas por el usuario.
963 (define-markup-command (draw-double-line layout props dest)
965 #:properties ((thickness 1))
966 "...documentación..."
967 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
971 (make-line-stencil th 0 0 x y)))
974 A continuación se añade una propiedad para establecer la separación
975 entre las dos líneas, llamada @code{line-gap}, con un valor
976 predeterminado de p.ej. 0.6:
979 (define-markup-command (draw-double-line layout props dest)
981 #:properties ((thickness 1)
983 "...documentación..."
987 Finalmente, se añade el código para trazar las dos líneas. Se usan
988 dos llamadas a @code{make-line-stencil} para trazar las líneas, y los
989 sellos resultantes se combinan usando @code{ly:stencil-add}:
991 @lilypond[quote,verbatim,ragged-right]
992 #(define-markup-command (my-draw-line layout props dest)
994 #:properties ((thickness 1)
997 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
1001 (w (/ line-gap 2.0))
1002 (x (cond ((= dx 0) w)
1004 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
1005 (y (* (if (< (* dx dy) 0) 1 -1)
1008 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
1009 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
1010 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
1012 \markup \my-draw-line #'(4 . 3)
1013 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
1017 @node Definición de nuevas instrucciones de lista de marcado
1018 @subsection Definición de nuevas instrucciones de lista de marcado
1019 @translationof New markup list command definition
1021 Las instrucciones de listas de marcado se definen con el macro de
1022 Scheme @code{define-markup-list-command}, que es similar al macro
1023 @code{define-markup-command} descrito en @ref{Definición de una
1024 instrucción de marcado nueva}, excepto que donde éste devuelve un
1025 sello único, aquél devuelve una lista de sellos.
1027 En el siguiente ejemplo se define una instrucción de lista de marcado
1028 @code{\paragraph}, que devuelve una lista de líneas justificadas,
1029 estando la primera de ellas sangrada. La anchura del sangrado se toma
1030 del argumento @code{props}.
1033 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1034 #:properties ((par-indent 2))
1035 (interpret-markup-list layout props
1036 #@{\markuplist \justified-lines @{ \hspace #par-indent $args @} #@}))
1040 La versión que usa solamente Scheme es más compleja:
1042 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1043 #:properties ((par-indent 2))
1044 (interpret-markup-list layout props
1045 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
1049 Aparte de los argumentos usuales @code{layout} y @code{props}, la
1050 instrucción de lista de marcados @code{paragraph} toma un argumento de
1051 lista de marcados, llamado @code{args}. El predicado para listas de
1052 marcados es @code{markup-list?}.
1054 En primer lugar, la función toma el ancho del sangrado, una propiedad
1055 llamada aquí @code{par-indent}, de la lista de propiedades
1056 @code{props}. Si no se encuentra la propiedad, el valor
1057 predeterminado es @code{2}. Después, se hace una lista de líneas
1058 justificadas usando la instrucción incorporada de lista de marcados
1059 @code{\justified-lines}, que está relacionada con la función
1060 @code{make-justified-lines-markup-list}. Se añade un espacio
1061 horizontal al principio usando @code{\hspace} (o la función
1062 @code{make-hspace-markup}). Finalmente, la lista de marcados se
1063 interpreta usando la función @code{interpret-markup-list}.
1065 Esta nueva instrucción de lista de marcados se puede usar como sigue:
1070 El arte de la tipografía musical se llama \italic @{grabado (en plancha).@}
1071 El término deriva del proceso tradicional de impresión de música.
1072 hace sólo algunas décadas, las partituras se hacían cortando y estampando
1073 la música en una plancha de zinc o lata en una imagen invertida.
1075 \override-lines #'(par-indent . 4) \paragraph @{
1076 La plancha se tenía que entintar, y las depresiones causadas por los cortes
1077 y estampados retienen la tinta. Se formaba una imagen presionando el papel
1078 contra la plancha. El estampado y cortado se hacía completamente
1085 @node Contextos para programadores
1086 @section Contextos para programadores
1087 @translationof Contexts for programmers
1090 * Evaluación de contextos::
1091 * Ejecutar una función sobre todos los objetos de la presentación::
1094 @node Evaluación de contextos
1095 @subsection Evaluación de contextos
1096 @translationof Context evaluation
1098 @cindex código, llamadas durante la interpretación
1099 @funindex \applyContext
1101 Se pueden modificar los contextos durante la interpretación con código
1102 de Scheme. La sintaxis para esto es
1105 \applyContext @var{función}
1108 @code{@var{función}} debe ser una función de Scheme que toma un único
1109 argumento, que es el contexto al que aplicarla. El código siguiente
1110 imprime el número del compás actual sobre la salida estándar durante
1116 (format #t "\nSe nos ha llamado en el compás número ~a.\n"
1117 (ly:context-property x 'currentBarNumber)))
1121 @node Ejecutar una función sobre todos los objetos de la presentación
1122 @subsection Ejecutar una función sobre todos los objetos de la presentación
1123 @translationof Running a function on all layout objects
1125 @cindex código, llamar sobre objetos de presentación
1126 @funindex \applyOutput
1129 La manera más versátil de realizar el ajuste fino de un objeto es
1130 @code{\applyOutput}, que
1131 funciona insertando un evento dentro del contexto especificado
1132 (@rinternals{ApplyOutputEvent}). Su sintaxis es
1135 \applyOutput @var{contexto} @var{proc}
1139 donde @code{@var{proc}} es una función de Scheme que toma tres argumentos.
1141 Al interpretarse, la función @code{@var{proc}} se llama para cada objeto de
1142 presentación que se encuentra en el contexto @code{@var{contexto}}
1143 en el tiempo actual, con los siguientes argumentos:
1146 @item el propio objeto de presentación,
1147 @item el contexto en que se creó el objeto de presentación, y
1148 @item el contexto en que se procesa @code{\applyOutput}.
1152 Además, la causa del objeto de presentación, es decir el objeto o
1153 expresión musical que es responsable de haberlo creado, está en la
1154 propiedad @code{cause} del objeto. Por ejemplo, para la cabeza de una
1155 nota, éste es un evento @rinternals{NoteHead}, y para un objeto
1156 plica, éste es un objeto @rinternals{Stem}.
1158 He aquí una función que usar para @code{\applyOutput}; borra las
1159 cabezas de las notas que están sobre la línea central y junto a ella:
1161 @lilypond[quote,verbatim,ragged-right]
1162 #(define (blanker grob grob-origin context)
1163 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
1164 (< (abs (ly:grob-property grob 'staff-position)) 2))
1165 (set! (ly:grob-property grob 'transparent) #t)))
1168 a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
1173 @node Funciones de callback
1174 @section Funciones de callback
1175 @translationof Callback functions
1177 Las propiedades (como @code{thickness} (grosor), @code{direction}
1178 (dirección), etc.) se pueden establecer a valores fijos con \override,
1182 \override Stem #'thickness = #2.0
1185 Las propiedades pueden fijarse también a un procedimiento de Scheme,
1187 @lilypond[fragment,verbatim,quote,relative=2]
1188 \override Stem #'thickness = #(lambda (grob)
1189 (if (= UP (ly:grob-property grob 'direction))
1196 En este caso, el procedimiento se ejecuta tan pronto como el valor de
1197 la propiedad se reclama durante el proceso de formateo.
1199 Casi todo el motor de tipografiado está manejado por estos
1200 @emph{callbacks}. Entre las propiedades que usan normalmente
1201 @emph{callbacks} están
1205 La rutina de impresión, que construye un dibujo para el símbolo
1207 La rutina que establece la posición horizontal
1209 La rutina que calcula la anchura de un objeto
1212 El procedimiento siempre toma un argumento único, que es el grob (el
1215 Si se deben llamar rutinas con varios argumentos, el grob actual se
1216 puede insertar con una cerradura de grob. He aquí un ajuste
1217 procedente de @code{AccidentalSuggestion},
1221 ,(ly:make-simple-closure
1223 ,(ly:make-simple-closure
1224 (list ly:self-alignment-interface::centered-on-x-parent))
1225 ,(ly:make-simple-closure
1226 (list ly:self-alignment-interface::x-aligned-on-self)))))
1230 En este ejemplo, tanto
1231 @code{ly:self-alignment-interface::x-aligned-on-self} como
1232 @code{ly:self-alignment-interface::centered-on-x-parent} se llaman con
1233 el grob como argumento. El resultado se añade con la función
1234 @code{+}. Para asegurar que esta adición se ejecuta adecuadamente,
1235 todo ello se encierra dentro de @code{ly:make-simple-closure}.
1237 De hecho, usar un solo procedimiento como valor de una propiedad
1241 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
1245 El @code{ly:make-simple-closure} interior aporta el grob como
1246 argumento de @var{proc}, el exterior asegura que el resultado de la
1247 función es lo que se devuelve, en lugar del objeto
1248 @code{simple-closure}.
1250 Desde dentro de un callback, el método más fácil para evaluar un
1251 elemento de marcado es usar grob-interpret-markup. Por ejemplo:
1254 mi-callback = #(lambda (grob)
1255 (grob-interpret-markup grob (markup "fulanito")))
1259 @node Código de Scheme en línea
1260 @section Código de Scheme en línea
1261 @translationof Inline Scheme code
1263 La principal desventaja de @code{\tweak} es su inflexibilidad
1264 sintáctica. Por ejemplo, lo siguiente produce un error de sintaxis.
1267 F = \tweak #'font-size #-3 -\flageolet
1275 Usando Scheme, se puede dar un rodeo a este problema. La ruta hacia
1276 el resultado se da en @ref{Añadir articulaciones a las notas
1277 (ejemplo)}, especialmente cómo usar @code{\displayMusic} como guía de
1281 F = #(let ((m (make-music 'ArticulationEvent
1282 'articulation-type "flageolet")))
1283 (set! (ly:music-property m 'tweaks)
1284 (acons 'font-size -3
1285 (ly:music-property m 'tweaks)))
1294 Aquí, las propiedades @code{tweaks} del objeto flageolet @code{m}
1295 (creado con @code{make-music}) se extraen con
1296 @code{ly:music-property}, se antepone un nuevo par clave-valor para
1297 cambiar el tamaño de la tipografía a la lista de propiedades con la
1298 función de Scheme @code{acons}, y finalmente el resultado se escribe
1299 de nuevo con @code{set!}. El último elemento del bloque @code{let} es
1300 el valor de retorno, el propio @code{m}.
1303 @node Trucos difíciles
1304 @section Trucos difíciles
1305 @translationof Difficult tweaks
1307 Hay un cierto número de tipos de ajustes difíciles.
1313 Un tipo de ajuste difícil es la apariencia de los objetos de
1314 extensión, como las ligaduras de expresión y de unión. Inicialmente,
1315 sólo se crea uno de estos objetos, y pueden ajustarse con el mecanismo
1316 normal. Sin embargo, en ciertos casos los objetos extensores cruzan
1317 los saltos de línea. Si esto ocurre, estos objetos se clonan. Se
1318 crea un objeto distinto por cada sistema en que se encuentra. Éstos
1319 son clones del objeto original y heredan todas sus propiedades,
1320 incluidos los @code{\override}s.
1322 En otras palabras, un @code{\override} siempre afecta a todas las
1323 piezas de un objeto de extensión fragmentado. Para cambiar sólo una
1324 parte de un extensor en el salto de línea, es necesario inmiscuirse en
1325 el proceso de formateado. El @emph{callback}
1326 @code{after-line-breaking} contiene el procedimiento Scheme que se
1327 llama después de que se han determinado los saltos de línea, y los
1328 objetos de presentación han sido divididos sobre los distintos
1331 En el ejemplo siguiente, definimos un procedimiento
1332 @code{my-callback}. Este procedimiento
1336 determina si hemos sido divididos por los saltos de línea
1338 en caso afirmativo, reúne todos los objetos divididos
1340 comprueba si somos el último de los objetos divididos
1342 en caso afirmativo, establece @code{extra-offset}.
1345 Este procedimiento se instala en @rinternals{Tie} (ligadura de unión),
1346 de forma que la última parte de la ligadura dividida se traslada hacia
1349 @lilypond[quote,verbatim,ragged-right]
1350 #(define (my-callback grob)
1352 ;; have we been split?
1353 (orig (ly:grob-original grob))
1355 ;; if yes, get the split pieces (our siblings)
1356 (siblings (if (ly:grob? orig)
1357 (ly:spanner-broken-into orig)
1360 (if (and (>= (length siblings) 2)
1361 (eq? (car (last-pair siblings)) grob))
1362 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1365 \override Tie #'after-line-breaking =
1373 Al aplicar este truco, la nueva función de callback
1374 @code{after-line-breaking} también debe llamar a la antigua,
1375 si existe este valor predeterminado. Por ejemplo, si se usa con
1376 @code{Hairpin}, se debe llamar también a
1377 @code{ly:spanner::kill-zero-spanned-time}.
1380 @item Algunos objetos no se pueden cambiar con @code{\override} por
1381 razones técnicas. Son ejemplos @code{NonMusicalPaperColumn} y
1382 @code{PaperColumn}. Se pueden cambiar con la función
1383 @code{\overrideProperty} que funciona de forma similar a @code{\once
1384 \override}, pero usa una sintaxis distinta.
1388 #"Score.NonMusicalPaperColumn" % Nombre del grob
1389 #'line-break-system-details % Nombre de la propiedad
1390 #'((next-padding . 20)) % Valor
1393 Observe, sin embargo, que @code{\override}, aplicado a
1394 @code{NonMusicalPaperColumn} y a @code{PaperColumn}, aún funciona
1395 como se espera dentro de los bloques @code{\context}.
1400 @node Interfaces de Scheme de LilyPond
1401 @chapter Interfaces de Scheme de LilyPond
1402 @translationof LilyPond Scheme interfaces
1404 Este capítulo cubre las diversas herramientas proporcionadas por
1405 LilyPond como ayuda a los programadores de Scheme a extraer e
1406 introducir información de los flujos musicales.
1408 HACER @c TODO -- figure out what goes in here and how to organize it