1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
2 @c This file is part of extending.tely
4 Translation of GIT committish: abf44faa7aff3481efcd8b241c352c6d5080ccd5
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. Mientras se está leyendo el
44 bloque de código de LilyPond, se analiza sintácticamente de forma
45 superficial y se sustituye por una llamada al analizador sintáctico de
46 LilyPond, que funciona en tiempo de ejecución para que interprete el
47 bloque de código de LilyPond.
49 El objeto del análisis superficial es la interpretación de los
50 símbolos @code{$} que se pueden usar para aislar expresiones del
51 contexto léxico de Scheme que les rodea (como variables de @code{let}
52 y parámetros de función). El @code{$} se puede usar de las maneras
57 simplemente pasa un único símbolo @code{$} al analizador de LilyPond.
59 evalúa la forma Scheme en tiempo de ejecución y la analiza como un
60 identificador @code{\forma} en el analizador de LilyPond. Dependiendo
61 del tipo del valor, se puede interpretar como varias entidades
62 sintácticas diferentes.
64 evalúa la forma de Scheme en tiempo de ejecución y analiza su valor
65 como una expresión de Scheme dentro del analizador de LilyPond.
67 las formas que están dentro de expresiones de Scheme y que comienzan
68 por @code{#} se leen y se analizan recursivamente hasta que se
69 encuentran símbolos de @code{$}. Entonces se tratan como sigue:
70 @item #@dots{}$@var{variable}
71 analiza el valor de la variable dentro de la expresión circundante.
72 @item #@dots{}($ @var{forma} @dots{})
73 analiza el valor de la forma dentro de la expresión circundante. Al
74 contrario que las @code{$@var{formas}} a nivel de LilyPond,
75 necesitamos separar la forma con un espacio en blanco, haciendo que
76 @code{$} sea reconocible como un símbolo de Scheme separado.
79 Un bloque de código de LilyPond puede contener cualquier cosa que
80 podríamos utilizar en la parte derecha de una asignación. Además, un
81 bloque de LilyPond vacío corresponde a una expresión musical vacía, y
82 un bloque de LilyPond que contiene varios eventos musicales se
83 convierte en una expresión de música secuencial.
85 @node Funciones de Scheme
86 @section Funciones de Scheme
87 @translationof Scheme functions
88 @cindex Scheme, funciones de (sintaxis de LilyPond)
90 Las @emph{funciones de Scheme} son procedimientos de Scheme que pueden
91 crear expresiones de Scheme a partir de código de entrada escrito en
92 la sintaxis de LilyPond. Se pueden llamar desde prácticamente
93 cualquier lugar en el que se permita el uso de @code{#} para la
94 especificación de un valor en sintaxis de Scheme. Mientras que Scheme
95 tiene funciones propias, este capítulo se ocupa de las funciones
96 @emph{sintácticas}, funciones que reciben argumentos especificados en
97 la sintaxis de LilyPond.
100 * Definición de funciones de Scheme::
101 * Uso de las funciones de Scheme::
102 * Funciones de Scheme vacías::
105 @node Definición de funciones de Scheme
106 @subsection Definición de funciones de Scheme
107 @translationof Scheme function definitions
108 @funindex define-scheme-function
110 La forma general de la definición de una función de Scheme es:
114 #(define-scheme-function
115 (parser location @var{arg1} @var{arg2} @dots{})
116 (@var{type1?} @var{type2?} @dots{})
123 @multitable @columnfractions .33 .66
125 @tab tiene que ser literalmente @code{parser} para dar a los bloques de código
126 de LilyPond (@code{#@{}@dots{}@code{#@}}) acceso al analizador sintáctico.
128 @item @code{@var{argN}}
129 @tab @var{n}-ésimo argumento
131 @item @code{@var{typeN?}}
132 @tab un @emph{predicado de tipo} de Scheme para el que @code{@var{argN}}
133 debe devolver @code{#t}. Algunos de estos predicados se reconocen de
134 forma especial por parte del analizador, véase más abajo. También
135 existe una forma especial @code{(@emph{predicate?} @emph{default})}
136 para especificar argumentos opcionales. Si el argumento actual no
137 está presente cuando se llama a la función, el valor predeterminado se
138 emplea en sustitución. Los valores predeterminados se evalúan en
139 tiempo de definición (¡incluyendo los bloques de código de LilyPond!),
140 de manera que se necesitamos un valor por omisión calculado en tiempo
141 de ejecución, debemos escribir en su lugar un valor especial que
142 podamos reconocer fácilmente. Si escribimos el predicado entre
143 paréntesis pero no lo seguimos por el valor predeterminado, se usa
144 @code{#f} como valor por omisión. Los valores por omisión no se
145 verifican con @emph{predicate?} en tiempo de definición ni en tiempo
146 de ejecución: es nuestra responsabilidad tratar con los valores que
147 especifiquemos. Los valores por omisión que son expresiones musicales
148 se copian mientras se establece @code{origin} al parámetro
151 @item @code{@var{cuerpo}}
152 @tab una secuencia de formas de Scheme que se evalúan ordenadamente; la
153 última forma de la secuencia se usa como el valor de retorno de la
154 función de Scheme. Puede contener bloques de código de LilyPond
155 encerrados entre llaves con almohadillas
156 (@tie{}@w{@code{#@{@dots{}#@}}}@tie{}), como se describe en
157 @ref{Bloques de código de LilyPond}. Dentro de los bloques de código
158 de LilyPond, use el símbolo del dólar @code{$} para hacer referencia a
159 argumentos de función (p.ej. @samp{$arg1}) o para iniciar una
160 expresión en línea de Scheme que contenga argumentos de función
161 (p.ej. @w{@samp{$(cons arg1 arg2)}}). Si la función devuelve una
162 expresión musical, se clona y se le da el @code{origin} correcto.
166 Ciertos predicados de tipo se reconocen de forma especial por parte
167 del analizador sintáctico y hacen que éste busque los argumentos
168 respectivos en la sintaxis de LilyPond en lugar de hacerlo en la
169 sintaxis de Scheme. Actualmente son @code{ly:music?}, @code{markup?},
170 @code{ly:pitch?} y @code{ly:duration?}.
172 Si realmente quiere escribir uno de los elementos especiales como
173 Scheme en lugar de como una expresión de LilyPond, puede escribirlos
174 como una expresión de Scheme que llame a @code{ly:export} en su nivel
177 Otros predicados de tipo, entre ellos los que están definidos por el
178 usuario hacen que el argumento respectivo sólo se acepte como una
179 expresión de Scheme, normalmente precedida de @code{#} o como
180 resultado de llamar a una función de Scheme.
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. El último argumento no puede ser un
205 argumento opcional. Si hay varios argumentos opcionales seguidos, se
206 rellenan con valores de izquierda a derecha. Desde el momento en que
207 un argumento opcional no corresponde con la entrada, éste y todos los
208 argumentos opcionales inmediatamente siguientes se sustituyen por sus
209 valores predeterminados, y la correspondencia continúa con el
210 siguiente argumento no opcional.
212 Aparte de los lugares en que se requiere un valor de Scheme hay
213 ciertos sitios en que se aceptan expresiones de almohadilla @code{#} y
214 se evalúan por sus efectos secundarios, pero por lo demás se ignoran.
215 Son, mayormente, los lugares en que también sería aceptable colocar
218 Hay ciertos lugares especiales en los que un argumento que corresponde
219 a @code{ly:music?} tiene que ser un identificador musical o bien una
220 expresión musical encerrada dentro de @code{@{}@dots{}@code{@}} o
221 @code{<<}@dots{}@code{>>} de forma explícita, de manera que las
222 duraciones o post-eventos opcionales que posiblemente le sigan no
223 puedan confundirse con argumentos adicionales. Un sitio obvio es
224 antes de un predicado @code{ly:duration?}. Otro es el último
225 argumento de una función de Scheme cuando se utiliza en un lugar en
226 que tales partes opcionales podrían, o no, considerarse como parte del
229 En esos casos raros, tenemos que delimitar nuestros argumentos
230 musicales de forma adecuada para evitar la confusión por parte de
233 @node Funciones de Scheme vacías
234 @subsection Funciones de Scheme vacías
235 @translationof Void scheme functions
237 A veces, una función se ejecuta solamente por sus efectos colaterales.
238 En tal caso, la utilización de una función de Scheme supone que su
239 valor no será considerado de la forma usual:
243 #(define-scheme-function
246 (ly:set-option 'point-and-click #f))
248 \noApuntarYPulsar % desactivar la función de apuntar y pulsar
251 @node Funciones musicales
252 @section Funciones musicales
253 @translationof Music functions
255 @cindex funciones musicales
257 Las @emph{funciones musicales} son procedimientos de Scheme que pueden
258 crear automáticamente expresiones musicales, y se pueden usar para
259 simplificar enormemente el archivo de entrada.
262 * Definiciones de funciones musicales::
263 * Uso de las funciones musicales::
264 * Funciones de sustitución sencillas::
265 * Funciones de sustitución intermedias::
266 * Matemáticas dentro de las funciones::
267 * Funciones sin argumentos::
268 * Funciones musicales vacías::
272 @node Definiciones de funciones musicales
273 @subsection Definiciones de funciones musicales
274 @translationof Music function definitions
275 @cindex definición de funciones musicales
276 @funindex define-music-function
278 La forma general para definir funciones musicales es:
282 #(define-music-function
283 (parser location @var{arg1} @var{arg2} @dots{})
284 (@var{tipo1?} @var{tipo2?} @dots{})
289 de forma bastante análoga a @ref{Definición de funciones de Scheme}.
290 Lo más probable es que el @var{cuerpo} sea un
291 @ref{Bloques de código de LilyPond,bloque de código de LilyPond}.
293 Para ver una lista de los predicados de tipo disponibles, consulte
294 @ruser{Predicados de tipo predefinidos}.
298 Referencia de la notación:
299 @ruser{Predicados de tipo predefinidos}.
302 @file{lily/music-scheme.cc},
307 @node Uso de las funciones musicales
308 @subsection Uso de las funciones musicales
309 @translationof Music function usage
311 Las funciones musicales se pueden actualmente utilizar en tres
312 lugares. Dependiendo de dónde se usan, son de aplicación ciertas
313 restricciones para que sea posible su análisis sintáctico de forma
314 no ambigua. El resultado que devuelve una función musical debe ser
315 compatible con el contexto desde el que se la llama.
319 En el nivel superior dentro de una expresión musical. No existen
320 especiales restricciones sobre la lista de argumentos.
323 Como un post-evento, que comienza explícitamente con un indicador de
324 dirección (a elegir entre @code{-}, @code{^} @w{y @code{_}}). Todos
325 los argumentos añadidos al final de la función musical con el
326 predicado @code{ly:music?} se analizan sintácticamente también como
327 post-eventos (si el último argumento es una función de Scheme, éste
328 contendrá en su lugar los argumentos @code{ly:music?} del final de la
329 función de Scheme). Observe que se puede aceptar la devolución de un
330 post-evento por parte de las funciones musicales que se llaman como
331 música normal, lo que lleva a un resultado aproximadamente equivalente
338 Como componente de un acordes. Todos los argumentos añadidos al final
339 de la función musical con el predicado @code{ly:music?} se analizarán
340 sintácticamente también como componentes de acorde.
344 Las reglas especiales para los argumentos del final hacen posible
345 escribir funciones polimórficas como @code{\tweak} que se pueden
346 aplicar a construcciones distintas.
348 @node Funciones de sustitución sencillas
349 @subsection Funciones de sustitución sencillas
350 @translationof Simple substitution functions
352 Una función de sustitución sencilla es una función musical cuya
353 expresión musical de salida está escrita en código de LilyPond
354 y contiene argumentos de la función en la expresión de salida.
355 Están descritas en @ruser{Ejemplos de funciones de sustitución}.
358 @node Funciones de sustitución intermedias
359 @subsection Funciones de sustitución intermedias
360 @translationof Intermediate substitution functions
362 Las funciones de sustitución intermedias contienen una
363 mezcla de código de Scheme y de LilyPond
364 dentro de la expresión musical que se devuelve.
366 Algunas instrucciones @code{\override} requieren un argumento que
367 consiste en una pareja de números (llamada una @emph{célula cons} en
370 La pareja se puede pasar directamente dentro de la función musical,
371 usando una variable @code{pair?}:
375 #(define-music-function
376 (parser location principio-final)
379 \once \override Beam #'positions = $principio-final
383 \barraManual #'(3 . 6) c8 d e f
387 De forma alternativa, los números que componen la pareja se pueden
388 pasar como argumentos separados, y el código de Scheme que se ha usado
389 para crear la pareja se puede incluir dentro de la expresión musical:
391 @lilypond[quote,verbatim,ragged-right]
393 #(define-music-function
394 (parser location beg end)
397 \once \override Beam #'positions = $(cons beg end)
401 \manualBeam #3 #6 c8 d e f
406 @node Matemáticas dentro de las funciones
407 @subsection Matemáticas dentro de las funciones
408 @translationof Mathematics in functions
410 Las funciones musicales pueden contar con programación de Scheme
411 además de la simple sustitución:
413 @lilypond[quote,verbatim,ragged-right]
415 #(define-music-function
416 (parser location mag)
419 \override Stem #'length = $(* 7.0 mag)
420 \override NoteHead #'font-size =
421 $(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
425 \revert Stem #'length
426 \revert NoteHead #'font-size
431 \AltOn #1.5 c c \AltOff c2
436 Este ejemplo se puede reescribir de forma que pase expresiones
439 @lilypond[quote,verbatim,ragged-right]
441 #(define-music-function
442 (parser location mag music)
445 \override Stem #'length = $(* 7.0 mag)
446 \override NoteHead #'font-size =
447 $(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
449 \revert Stem #'length
450 \revert NoteHead #'font-size
454 c2 \withAlt #0.5 { c4 c }
455 \withAlt #1.5 { c c } c2
460 @node Funciones sin argumentos
461 @subsection Funciones sin argumentos
462 @translationof Functions without arguments
464 En casi todos los casos, una función sin argumentos se debe escribir
468 dolce = \markup@{ \italic \bold dolce @}
471 Sin embargo, en raras ocasiones puede ser de utilidad crear una
472 función musical sin argumentos:
475 mostrarNumeroDeCompas =
476 #(define-music-function
479 (if (eq? #t (ly:get-option 'display-bar-numbers))
480 #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
484 Para la impresión real de los números de compás donde se llama a esta
485 función, invoque a @command{lilypond} con
488 lilypond -d display-bar-numbers ARCHIVO.ly
492 @node Funciones musicales vacías
493 @subsection Funciones musicales vacías
494 @translationof Void music functions
496 Una función musical debe devolver una expresión musical. Si quiere
497 ejecutar una función exclusivamente por sus efectos secundarios,
498 podría ser más sensato usar en su lugar una función de Scheme. Pero
499 puede haber casos en los que a veces queremos producir una expresión
500 musical, y a veces no (como en el ejemplo anterior). Devolver una
501 expresión musical @code{void} (vacía) por medio de @code{#@{ #@}} lo
505 @node Funciones de eventos
506 @section Funciones de eventos
507 @translationof Event functions
508 @funindex define-event-function
509 @cindex event functions
511 Para usar una función musical en el lugar de un evento, tenemos que
512 escribir un indicador de dirección antes de ella. Pero a veces, ello
513 hace que se pierda la correspondencia con la sintaxis de las
514 construcciones que queremos sustituir. Por ejemplo, si queremos
515 escribir instrucciones de matiz dinámico, éstos se adjuntan
516 habitualmente sin indicador de dirección, como @code{c'\pp}. He aquí
517 una forma de escribir indicaciones dinámicas arbitrarias:
519 @lilypond[quote,verbatim,raggedright]
520 dyn=#(define-event-function (parser location arg) (markup?)
521 (make-dynamic-script arg)) \relative c' { c\dyn pfsss }
524 Podríamos hacer lo mismo usando una función musical, pero entonces
525 tendríamos que escribir siempre un indicador de dirección antes de
526 llamarla, como @code{@w{c-\dyn pfsss}}.
529 @node Funciones de marcado
530 @section Funciones de marcado
531 @translationof Markup functions
533 Los elementos de marcado están implementados como funciones de Scheme
534 especiales que producen un objeto @code{Stencil} dada una serie de
539 * Construcción de elementos de marcado en Scheme::
540 * Cómo funcionan internamente los elementos de marcado::
541 * Definición de una instrucción de marcado nueva::
542 * Definición de nuevas instrucciones de lista de marcado::
545 @node Construcción de elementos de marcado en Scheme
546 @subsection Construcción de elementos de marcado en Scheme
547 @translationof Markup construction in Scheme
549 @cindex marcado, definir instrucciones de
551 El macro @code{markup} construye expresiones de marcado en Scheme,
552 proporcionando una sintaxis similar a la de LilyPond. Por ejemplo:
555 (markup #:column (#:line (#:bold #:italic "hola" #:raise 0.4 "mundo")
556 #:larger #:line ("fulano" "fulanito" "menganito")))
562 #@{ \markup \column @{ \line @{ \bold \italic "hola" \raise #0.4 "mundo" @}
563 \larger \line @{ fulano fulanito menganito @} @} #@}
567 Este ejemplo muestra las principales reglas de traducción entre la
568 sintaxis del marcado normal de LilyPond y la sintaxis del marcado de
569 Scheme. La utilización de @code{#@{ @dots{} #@}} para escribir en la
570 sintaxis de LilyPond será con frecuencia lo más conveniente, pero
571 explicamos cómo usar la macro @code{markup} para obtener una solución
575 @multitable @columnfractions .3 .3
576 @item @b{LilyPond} @tab @b{Scheme}
577 @item @code{\markup marcado1} @tab @code{(markup marcado1)}
578 @item @code{\markup @{ marcado1 marcado2 ... @}} @tab
579 @code{(markup marcado1 marcado2 ... )}
580 @item @code{\instruccion} @tab @code{#:instruccion}
581 @item @code{\variable} @tab @code{variable}
582 @item @code{\center-column @{ ... @}} @tab @code{#:center-column ( ... )}
583 @item @code{cadena} @tab @code{"cadena"}
584 @item @code{#argumento-de-scheme} @tab @code{argumento-de-scheme}
588 Todo el lenguaje Scheme está accesible dentro del macro @code{markup}.
589 Por ejemplo, podemos usar llamadas a funciones dentro de @code{markup}
590 para así manipular cadenas de caracteres. Esto es útil si se están
591 definiendo instrucciones de marcado nuevas (véase
592 @ref{Definición de una instrucción de marcado nueva}).
597 El argumento markup-list de instrucciones como @code{#:line},
598 @code{#:center} y @code{#:column} no puede ser una variable ni el
599 resultado de la llamada a una función.
602 (markup #:line (funcion-que-devuelve-marcados))
606 no es válido. Hay que usar las funciones @code{make-line-markup},
607 @code{make-center-markup} o @code{make-column-markup} en su lugar:
610 (markup (make-line-markup (funcion-que-devuelve-marcados)))
614 @node Cómo funcionan internamente los elementos de marcado
615 @subsection Cómo funcionan internamente los elementos de marcado
616 @translationof How markups work internally
618 En un elemento de marcado como
621 \raise #0.5 "ejemplo de texto"
625 @code{\raise} se representa en realidad por medio de la función
626 @code{raise-markup}. La expresión de marcado se almacena como
629 (list raise-markup 0.5 (list simple-markup "ejemplo de texto"))
632 Cuando el marcado se convierte en objetos imprimibles (Stencils o
633 sellos), se llama la función @code{raise-markup} como
637 @var{\objeto de marcado}
638 @var{lista de listas asociativas de propiedades}
640 @var{el marcado "ejemplo de texto"})
643 Primero la función @code{raise-markup} crea el sello para la cadena
644 @code{ejemplo de texto}, y después eleva el sello Stencil en 0.5
645 espacios de pentagrama. Este es un ejemplo bastante simple; en el
646 resto de la sección podrán verse ejemplos más complejos, así como en
647 @file{scm/define-markup-commands.scm}.
650 @node Definición de una instrucción de marcado nueva
651 @subsection Definición de una instrucción de marcado nueva
652 @translationof New markup command definition
654 Esta sección trata sobre la definición de nuevas instrucciones de
659 * Sintaxis de la definición de instrucciones de marcado::
660 * Acerca de las propiedades::
661 * Un ejemplo completo::
662 * Adaptación de instrucciones incorporadas::
665 @node Sintaxis de la definición de instrucciones de marcado
666 @unnumberedsubsubsec Sintaxis de la definición de instrucciones de marcado
667 @translationof Markup command definition syntax
669 Se pueden definir instrucciones de marcado nuevas usando el macro de
670 Scheme @code{define-markup-command}, en el nivel sintáctico superior.
673 (define-markup-command (@var{nombre-de-la-instruccion} @var{layout} @var{props} @var{arg1} @var{arg2} ...)
674 (@var{tipo-de-arg1?} @var{tipo-de-arg2?} ...)
675 [ #:properties ((@var{propiedad1} @var{valor-predeterminado1})
683 @item @var{nombre-de-la-instruccion}
684 nombre de la instrucción de marcado
686 la definición de @q{layout} (disposición).
688 una lista de listas asociativas, que contienen todas las propiedades
691 argumento @var{i}-ésimo de la instrucción
692 @item @var{tipo-de-argi?}
693 predicado de tipo para el argumento @var{i}-ésimo
696 Si la instrucción utiliza propiedades de los argumentos @code{props},
697 se puede usar la palabra clave @code{#:properties} para especificar
698 qué propiedades se usan, así como sus valores predeterminados.
700 Los argumentos se distinguen según su tipo:
702 @item un marcado, que corresponde al predicado de tipo @code{markup?};
703 @item una lista de marcados, que corresponde al predicado de tipo
705 @item cualquier otro objeto de Scheme, que corresponde a predicados de tipo como
706 @code{list?}, @code{number?}, @code{boolean?}, etc.
709 No existe ninguna limitación en el orden de los argumentos (después de
710 los argumentos estándar @code{layout} y @code{props}). Sin embargo, las
711 funciones de marcado que toman un elemento de marcado como su último
712 argumento son un poco especiales porque podemos aplicarlas a una lista
713 de marcados y el resultado es una lista de marcados donde la función
714 de marcado (con los argumentos antecedentes especificados) se ha
715 aplicado a todos los elementos de la lista de marcados original.
717 Dado que la replicación de los argumentos precedentes para aplicar una
718 función de marcado a una lista de marcados es poco costosa
719 principalmente por los argumentos de Scheme, se evitan las caídas de
720 rendimiento simplemente mediante la utilización de argumentos de
721 Scheme para los argumentos antecedentes de las funciones de marcado
722 que toman un marcado como su último argumento.
724 @node Acerca de las propiedades
725 @unnumberedsubsubsec Acerca de las propiedades
726 @translationof On properties
728 Los argumentos @code{layout} y @code{props} de las instrucciones de
729 marcado traen a escena un contexto para la interpretación del marcado:
730 tamaño de la tipografía, grueso de línea, etc.
732 El argumento @code{layout} permite el acceso a las propiedades
733 definidas en los bloques @code{paper}, usando la función
734 @code{ly:output-def-lookup}. Por ejemplo, el grueso de línea (el
735 mismo que el que se usa en las partituras) se lee usando:
738 (ly:output-def-lookup layout 'line-width)
741 El argumento @code{props} hace accesibles algunas propiedades a las
742 instrucciones de marcado. Por ejemplo, cuando se interpreta el
743 marcado del título de un libro, todas las variables definidas dentro
744 del bloque @code{\header} se añaden automáticamente a @code{props}, de
745 manera que el marcado del título del libro puede acceder al título del
746 libro, el autor, etc. También es una forma de configurar el
747 comportamiento de una instrucción de marcado: por ejemplo, cuando una
748 instrucción utiliza tamaños de tipografía durante el procesado, el
749 tamaño se lee de @code{props} en vez de tener un argumento
750 @code{font-size}. El que llama a una instrucción de marcado puede
751 cambiar el valor de la propiedad del tamaño de la tipografía con el
752 objeto de modificar el comportamiento. Utilice la palabra clave
753 @code{#:properties} de @code{define-markup-command} para especificar
754 qué propiedades se deben leer a partir de los argumentos de
757 El ejemplo de la sección siguiente ilustra cómo acceder y
758 sobreescribir las propiedades de una instrucción de marcado.
761 @node Un ejemplo completo
762 @unnumberedsubsubsec Un ejemplo completo
763 @translationof A complete example
765 El ejemplo siguiente define una instrucción de marcado para trazar un
766 rectángulo doble alrededor de un fragmento de texto.
768 En primer lugar, necesitamos construir un resultado aproximado
769 utilizando marcados. Una consulta a @ruser{Instrucciones de marcado
770 de texto} nos muestra que es útil la instrucción @code{\box}:
772 @lilypond[quote,verbatim,ragged-right]
773 \markup \box \box HELLO
776 Ahora, consideramos que es preferible tener más separación entre el
777 texto y los rectángulos. Según la documentación de @code{\box}, esta
778 instrucción usa una propiedad @code{box-padding}, cuyo valor
779 predeterminado es 0.2. La documentación también menciona cómo
780 sobreescribir este valor:
782 @lilypond[quote,verbatim,ragged-right]
783 \markup \box \override #'(box-padding . 0.6) \box A
786 Después, el relleno o separación entre los dos rectángulos nos parece
787 muy pequeño, así que lo vamos a sobreescribir también:
789 @lilypond[quote,verbatim,ragged-right]
790 \markup \override #'(box-padding . 0.4) \box
791 \override #'(box-padding . 0.6) \box A
794 Repetir esta extensa instrucción de marcado una y otra vez sería un
795 quebradero de cabeza. Aquí es donde se necesita una instrucción de
796 marcado. Así pues, escribimos una instrucción de marcado
797 @code{double-box}, que toma un argumento (el texto). Dibuja los dos
798 rectángulos y añade una separación.
801 #(define-markup-command (double-box layout props text) (markup?)
802 "Trazar un rectángulo doble rodeando el texto."
803 (interpret-markup layout props
804 #@{\markup \override #'(box-padding . 0.4) \box
805 \override #'(box-padding . 0.6) \box @{ $text @}#@}))
811 #(define-markup-command (double-box layout props text) (markup?)
812 "Trazar un rectángulo doble rodeando el texto."
813 (interpret-markup layout props
814 (markup #:override '(box-padding . 0.4) #:box
815 #:override '(box-padding . 0.6) #:box text)))
818 @code{text} es el nombre del argumento de la instrucción, y
819 @code{markup?} es el tipo: lo identifica como un elemento de marcado.
820 La función @code{interpret-markup} se usa en casi todas las
821 instrucciones de marcado: construye un sello, usando @code{layout},
822 @code{props}, y un elemento de marcado. En el segundo caso, la marca
823 se construye usando el macro de Scheme @code{markup}, véase
824 @ref{Construcción de elementos de marcado en Scheme}. La
825 transformación de una expresión @code{\markup} en una expresión de
826 marcado de Scheme es directa.
828 La instrucción nueva se puede usar como sigue:
831 \markup \double-box A
834 Sería buen hacer que la instrucción @code{double-box} fuera
835 personalizable: aquí, los valores de relleno @code{box-padding} son
836 fijos, y no se pueden cambiar por parte del usuario. Además, sería
837 mejor distinguir la separación entre los dos rectángulos, del relleno
838 entre el rectángulo interno y el texto. Así pues, introducimos una
839 nueva propiedad, @code{inter-box-padding}, para el relleno entre los
840 rectángulos. El @code{box-padding} se usará para el relleno interno.
841 Ahora el código nuevo es como se ve a continuación:
844 #(define-markup-command (double-box layout props text) (markup?)
845 #:properties ((inter-box-padding 0.4)
847 "Trazar un rectángulo doble rodeando el texto."
848 (interpret-markup layout props
849 #@{\markup \override #`(box-padding . ,$inter-box-padding) \box
850 \override #`(box-padding . ,$box-padding) \box
854 De nuevo, la versión equivalente que utiliza la macro de marcado sería:
857 #(define-markup-command (double-box layout props text) (markup?)
858 #:properties ((inter-box-padding 0.4)
860 "Trazar un rectángulo doble rodeando el texto."
861 (interpret-markup layout props
862 (markup #:override `(box-padding . ,inter-box-padding) #:box
863 #:override `(box-padding . ,box-padding) #:box text)))
866 Aquí, la palabra clave @code{#:properties} se usa de manera que las
867 propiedades @code{inter-box-padding} y @code{box-padding} se leen a
868 partir del argumento @code{props}, y se les proporcionan unos valores
869 predeterminados si las propiedades no están definidas.
871 Después estos valores se usan para sobreescribir las propiedades
872 @code{box-padding} usadas por las dos instrucciones @code{\box}.
873 Observe el apóstrofo invertido y la coma en el argumento de
874 @code{\override}: nos permiten introducir un valor de variable dentro
875 de una expresión literal.
877 Ahora, la instrucción se puede usar dentro de un elemento de marcado,
878 y el relleno de los rectángulos se puede personalizar:
880 @lilypond[quote,verbatim,ragged-right]
881 #(define-markup-command (double-box layout props text) (markup?)
882 #:properties ((inter-box-padding 0.4)
884 "Draw a double box around text."
885 (interpret-markup layout props
886 #{\markup \override #`(box-padding . ,$inter-box-padding) \box
887 \override #`(box-padding . ,$box-padding) \box
890 \markup \double-box A
891 \markup \override #'(inter-box-padding . 0.8) \double-box A
892 \markup \override #'(box-padding . 1.0) \double-box A
896 @node Adaptación de instrucciones incorporadas
897 @unnumberedsubsubsec Adaptación de instrucciones incorporadas
898 @translationof Adapting builtin commands
900 Una buena manera de comenzar a escribir una instrucción de marcado
901 nueva, es seguir el ejemplo de otra instrucción ya incorporada. Casi
902 todas las instrucciones de marcado que están incorporadas en LilyPond
903 se pueden encontrar en el archivo
904 @file{scm/define-markup-commands.scm}.
906 Por ejemplo, querríamos adaptar la instrucción @code{\draw-line}, para
907 que trace una línea doble. La instrucción @code{\draw-line} está
908 definida como sigue (se han suprimido los comentarios de
912 (define-markup-command (draw-line layout props dest)
915 #:properties ((thickness 1))
916 "...documentación..."
917 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
921 (make-line-stencil th 0 0 x y)))
924 Para definir una instrucción nueva basada en otra existente, copie la
925 definición y cámbiele el nombre. La palabra clave @code{#:category}
926 se puede eliminar sin miedo, pues sólo se utiliza para generar
927 documentación de LilyPond, y no tiene ninguna utilidad para las
928 instrucciones de marcado definidas por el usuario.
931 (define-markup-command (draw-double-line layout props dest)
933 #:properties ((thickness 1))
934 "...documentación..."
935 (let ((th (* (ly:output-def-lookup layout 'line-thickness)
939 (make-line-stencil th 0 0 x y)))
942 A continuación se añade una propiedad para establecer la separación
943 entre las dos líneas, llamada @code{line-gap}, con un valor
944 predeterminado de p.ej. 0.6:
947 (define-markup-command (draw-double-line layout props dest)
949 #:properties ((thickness 1)
951 "...documentación..."
955 Finalmente, se añade el código para trazar las dos líneas. Se usan
956 dos llamadas a @code{make-line-stencil} para trazar las líneas, y los
957 sellos resultantes se combinan usando @code{ly:stencil-add}:
959 @lilypond[quote,verbatim,ragged-right]
960 #(define-markup-command (my-draw-line layout props dest)
962 #:properties ((thickness 1)
965 (let* ((th (* (ly:output-def-lookup layout 'line-thickness)
970 (x (cond ((= dx 0) w)
972 (else (/ w (sqrt (+ 1 (* (/ dx dy) (/ dx dy))))))))
973 (y (* (if (< (* dx dy) 0) 1 -1)
976 (else (/ w (sqrt (+ 1 (* (/ dy dx) (/ dy dx))))))))))
977 (ly:stencil-add (make-line-stencil th x y (+ dx x) (+ dy y))
978 (make-line-stencil th (- x) (- y) (- dx x) (- dy y)))))
980 \markup \my-draw-line #'(4 . 3)
981 \markup \override #'(line-gap . 1.2) \my-draw-line #'(4 . 3)
985 @node Definición de nuevas instrucciones de lista de marcado
986 @subsection Definición de nuevas instrucciones de lista de marcado
987 @translationof New markup list command definition
989 Las instrucciones de listas de marcado se definen con el macro de
990 Scheme @code{define-markup-list-command}, que es similar al macro
991 @code{define-markup-command} descrito en @ref{Definición de una
992 instrucción de marcado nueva}, excepto que donde éste devuelve un
993 sello único, aquél devuelve una lista de sellos.
995 En el siguiente ejemplo se define una instrucción de lista de marcado
996 @code{\paragraph}, que devuelve una lista de líneas justificadas,
997 estando la primera de ellas sangrada. La anchura del sangrado se toma
998 del argumento @code{props}.
1001 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1002 #:properties ((par-indent 2))
1003 (interpret-markup-list layout props
1004 #@{\markuplist \justified-lines @{ \hspace #$par-indent $args @} #@}))
1008 La versión que usa solamente Scheme es más compleja:
1010 #(define-markup-list-command (paragraph layout props args) (markup-list?)
1011 #:properties ((par-indent 2))
1012 (interpret-markup-list layout props
1013 (make-justified-lines-markup-list (cons (make-hspace-markup par-indent)
1017 Aparte de los argumentos usuales @code{layout} y @code{props}, la
1018 instrucción de lista de marcados @code{paragraph} toma un argumento de
1019 lista de marcados, llamado @code{args}. El predicado para listas de
1020 marcados es @code{markup-list?}.
1022 En primer lugar, la función toma el ancho del sangrado, una propiedad
1023 llamada aquí @code{par-indent}, de la lista de propiedades
1024 @code{props}. Si no se encuentra la propiedad, el valor
1025 predeterminado es @code{2}. Después, se hace una lista de líneas
1026 justificadas usando la instrucción incorporada de lista de marcados
1027 @code{\justified-lines}, que está relacionada con la función
1028 @code{make-justified-lines-markup-list}. Se añade un espacio
1029 horizontal al principio usando @code{\hspace} (o la función
1030 @code{make-hspace-markup}). Finalmente, la lista de marcados se
1031 interpreta usando la función @code{interpret-markup-list}.
1033 Esta nueva instrucción de lista de marcados se puede usar como sigue:
1038 El arte de la tipografía musical se llama \italic @{grabado (en plancha).@}
1039 El término deriva del proceso tradicional de impresión de música.
1040 hace sólo algunas décadas, las partituras se hacían cortando y estampando
1041 la música en una plancha de zinc o lata en una imagen invertida.
1043 \override-lines #'(par-indent . 4) \paragraph @{
1044 La plancha se tenía que entintar, y las depresiones causadas por los cortes
1045 y estampados retienen la tinta. Se formaba una imagen presionando el papel
1046 contra la plancha. El estampado y cortado se hacía completamente
1053 @node Contextos para programadores
1054 @section Contextos para programadores
1055 @translationof Contexts for programmers
1058 * Evaluación de contextos::
1059 * Ejecutar una función sobre todos los objetos de la presentación::
1062 @node Evaluación de contextos
1063 @subsection Evaluación de contextos
1064 @translationof Context evaluation
1066 @cindex código, llamadas durante la interpretación
1067 @funindex \applyContext
1069 Se pueden modificar los contextos durante la interpretación con código
1070 de Scheme. La sintaxis para esto es
1073 \applyContext @var{función}
1076 @code{@var{función}} debe ser una función de Scheme que toma un único
1077 argumento, que es el contexto al que aplicarla. El código siguiente
1078 imprime el número del compás actual sobre la salida estándar durante
1084 (format #t "\nSe nos ha llamado en el compás número ~a.\n"
1085 (ly:context-property x 'currentBarNumber)))
1089 @node Ejecutar una función sobre todos los objetos de la presentación
1090 @subsection Ejecutar una función sobre todos los objetos de la presentación
1091 @translationof Running a function on all layout objects
1093 @cindex código, llamar sobre objetos de presentación
1094 @funindex \applyOutput
1097 La manera más versátil de realizar el ajuste fino de un objeto es
1098 @code{\applyOutput}, que
1099 funciona insertando un evento dentro del contexto especificado
1100 (@rinternals{ApplyOutputEvent}). Su sintaxis es
1103 \applyOutput @var{contexto} @var{proc}
1107 donde @code{@var{proc}} es una función de Scheme que toma tres argumentos.
1109 Al interpretarse, la función @code{@var{proc}} se llama para cada objeto de
1110 presentación que se encuentra en el contexto @code{@var{contexto}}
1111 en el tiempo actual, con los siguientes argumentos:
1114 @item el propio objeto de presentación,
1115 @item el contexto en que se creó el objeto de presentación, y
1116 @item el contexto en que se procesa @code{\applyOutput}.
1120 Además, la causa del objeto de presentación, es decir el objeto o
1121 expresión musical que es responsable de haberlo creado, está en la
1122 propiedad @code{cause} del objeto. Por ejemplo, para la cabeza de una
1123 nota, éste es un evento @rinternals{NoteHead}, y para un objeto
1124 plica, éste es un objeto @rinternals{Stem}.
1126 He aquí una función que usar para @code{\applyOutput}; borra las
1127 cabezas de las notas que están sobre la línea central y junto a ella:
1129 @lilypond[quote,verbatim,ragged-right]
1130 #(define (blanker grob grob-origin context)
1131 (if (and (memq 'note-head-interface (ly:grob-interfaces grob))
1132 (< (abs (ly:grob-property grob 'staff-position)) 2))
1133 (set! (ly:grob-property grob 'transparent) #t)))
1136 a'4 e8 <<\applyOutput #'Voice #blanker a c d>> b2
1141 @node Funciones de callback
1142 @section Funciones de callback
1143 @translationof Callback functions
1145 Las propiedades (como @code{thickness} (grosor), @code{direction}
1146 (dirección), etc.) se pueden establecer a valores fijos con \override,
1150 \override Stem #'thickness = #2.0
1153 Las propiedades pueden fijarse también a un procedimiento de Scheme,
1155 @lilypond[fragment,verbatim,quote,relative=2]
1156 \override Stem #'thickness = #(lambda (grob)
1157 (if (= UP (ly:grob-property grob 'direction))
1164 En este caso, el procedimiento se ejecuta tan pronto como el valor de
1165 la propiedad se reclama durante el proceso de formateo.
1167 Casi todo el motor de tipografiado está manejado por estos
1168 @emph{callbacks}. Entre las propiedades que usan normalmente
1169 @emph{callbacks} están
1173 La rutina de impresión, que construye un dibujo para el símbolo
1175 La rutina que establece la posición horizontal
1177 La rutina que calcula la anchura de un objeto
1180 El procedimiento siempre toma un argumento único, que es el grob (el
1183 Si se deben llamar rutinas con varios argumentos, el grob actual se
1184 puede insertar con una cerradura de grob. He aquí un ajuste
1185 procedente de @code{AccidentalSuggestion},
1189 ,(ly:make-simple-closure
1191 ,(ly:make-simple-closure
1192 (list ly:self-alignment-interface::centered-on-x-parent))
1193 ,(ly:make-simple-closure
1194 (list ly:self-alignment-interface::x-aligned-on-self)))))
1198 En este ejemplo, tanto
1199 @code{ly:self-alignment-interface::x-aligned-on-self} como
1200 @code{ly:self-alignment-interface::centered-on-x-parent} se llaman con
1201 el grob como argumento. El resultado se añade con la función
1202 @code{+}. Para asegurar que esta adición se ejecuta adecuadamente,
1203 todo ello se encierra dentro de @code{ly:make-simple-closure}.
1205 De hecho, usar un solo procedimiento como valor de una propiedad
1209 (ly:make-simple-closure (ly:make-simple-closure (list @var{proc})))
1213 El @code{ly:make-simple-closure} interior aporta el grob como
1214 argumento de @var{proc}, el exterior asegura que el resultado de la
1215 función es lo que se devuelve, en lugar del objeto
1216 @code{simple-closure}.
1218 Desde dentro de un callback, el método más fácil para evaluar un
1219 elemento de marcado es usar grob-interpret-markup. Por ejemplo:
1222 mi-callback = #(lambda (grob)
1223 (grob-interpret-markup grob (markup "fulanito")))
1227 @node Código de Scheme en línea
1228 @section Código de Scheme en línea
1229 @translationof Inline Scheme code
1231 La principal desventaja de @code{\tweak} es su inflexibilidad
1232 sintáctica. Por ejemplo, lo siguiente produce un error de sintaxis.
1235 F = \tweak #'font-size #-3 -\flageolet
1243 En otras palabras, @code{\tweak} no se comporta como una articulación
1244 en cuando a la sintaxis; concretamente, no se puede adjuntar con
1245 @code{^} y @code{_}.
1247 Usando Scheme, se puede dar un rodeo a este problema. La ruta hacia
1248 el resultado se da en @ref{Añadir articulaciones a las notas
1249 (ejemplo)}, especialmente cómo usar @code{\displayMusic} como guía de
1253 F = #(let ((m (make-music 'ArticulationEvent
1254 'articulation-type "flageolet")))
1255 (set! (ly:music-property m 'tweaks)
1256 (acons 'font-size -3
1257 (ly:music-property m 'tweaks)))
1266 Aquí, las propiedades @code{tweaks} del objeto flageolet @code{m}
1267 (creado con @code{make-music}) se extraen con
1268 @code{ly:music-property}, se antepone un nuevo par clave-valor para
1269 cambiar el tamaño de la tipografía a la lista de propiedades con la
1270 función de Scheme @code{acons}, y finalmente el resultado se escribe
1271 de nuevo con @code{set!}. El último elemento del bloque @code{let} es
1272 el valor de retorno, el propio @code{m}.
1275 @node Trucos difíciles
1276 @section Trucos difíciles
1277 @translationof Difficult tweaks
1279 Hay un cierto número de tipos de ajustes difíciles.
1285 Un tipo de ajuste difícil es la apariencia de los objetos de
1286 extensión, como las ligaduras de expresión y de unión. Inicialmente,
1287 sólo se crea uno de estos objetos, y pueden ajustarse con el mecanismo
1288 normal. Sin embargo, en ciertos casos los objetos extensores cruzan
1289 los saltos de línea. Si esto ocurre, estos objetos se clonan. Se
1290 crea un objeto distinto por cada sistema en que se encuentra. Éstos
1291 son clones del objeto original y heredan todas sus propiedades,
1292 incluidos los @code{\override}s.
1294 En otras palabras, un @code{\override} siempre afecta a todas las
1295 piezas de un objeto de extensión fragmentado. Para cambiar sólo una
1296 parte de un extensor en el salto de línea, es necesario inmiscuirse en
1297 el proceso de formateado. El @emph{callback}
1298 @code{after-line-breaking} contiene el procedimiento Scheme que se
1299 llama después de que se han determinado los saltos de línea, y los
1300 objetos de presentación han sido divididos sobre los distintos
1303 En el ejemplo siguiente, definimos un procedimiento
1304 @code{my-callback}. Este procedimiento
1308 determina si hemos sido divididos por los saltos de línea
1310 en caso afirmativo, reúne todos los objetos divididos
1312 comprueba si somos el último de los objetos divididos
1314 en caso afirmativo, establece @code{extra-offset}.
1317 Este procedimiento se instala en @rinternals{Tie} (ligadura de unión),
1318 de forma que la última parte de la ligadura dividida se traslada hacia
1321 @lilypond[quote,verbatim,ragged-right]
1322 #(define (my-callback grob)
1324 ;; have we been split?
1325 (orig (ly:grob-original grob))
1327 ;; if yes, get the split pieces (our siblings)
1328 (siblings (if (ly:grob? orig)
1329 (ly:spanner-broken-into orig)
1332 (if (and (>= (length siblings) 2)
1333 (eq? (car (last-pair siblings)) grob))
1334 (ly:grob-set-property! grob 'extra-offset '(-2 . 5)))))
1337 \override Tie #'after-line-breaking =
1345 Al aplicar este truco, la nueva función de callback
1346 @code{after-line-breaking} también debe llamar a la antigua,
1347 si existe este valor predeterminado. Por ejemplo, si se usa con
1348 @code{Hairpin}, se debe llamar también a
1349 @code{ly:spanner::kill-zero-spanned-time}.
1352 @item Algunos objetos no se pueden cambiar con @code{\override} por
1353 razones técnicas. Son ejemplos @code{NonMusicalPaperColumn} y
1354 @code{PaperColumn}. Se pueden cambiar con la función
1355 @code{\overrideProperty} que funciona de forma similar a @code{\once
1356 \override}, pero usa una sintaxis distinta.
1360 #"Score.NonMusicalPaperColumn" % Nombre del grob
1361 #'line-break-system-details % Nombre de la propiedad
1362 #'((next-padding . 20)) % Valor
1365 Observe, sin embargo, que @code{\override}, aplicado a
1366 @code{NonMusicalPaperColumn} y a @code{PaperColumn}, aún funciona
1367 como se espera dentro de los bloques @code{\context}.
1372 @node Interfaces de Scheme de LilyPond
1373 @chapter Interfaces de Scheme de LilyPond
1374 @translationof LilyPond Scheme interfaces
1376 Este capítulo cubre las diversas herramientas proporcionadas por
1377 LilyPond como ayuda a los programadores de Scheme a extraer e
1378 introducir información de los flujos musicales.
1380 HACER @c TODO -- figure out what goes in here and how to organize it