1 @c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
2 @c This file is part of lilypond.tely
4 Translation of GIT committish: 4a527608c5ff2ce31e596495d00dce181dc1b9ea
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 for programmers
13 @chapter Interfaces for programmers
15 Se pueden realizar trucos avanzados mediante el uso de Scheme. Si no
16 está familizarizado con Scheme, le conviene leer nuestro tutorial de
17 Scheme, @rlearning{Scheme tutorial}.
21 * Programmer interfaces::
22 * Building complicated functions::
23 * Markup programmer interface::
24 * Contexts for programmers::
25 * Scheme procedures as properties::
26 * Using Scheme code instead of \tweak::
32 @section Music functions
34 Esta sección trata sobre cómo crear funciones musicales dentro de
38 * Overview of music functions::
39 * Simple substitution functions::
40 * Paired substitution functions::
41 * Mathematics in functions::
43 * Functions without arguments::
44 * Overview of available music functions::
47 @node Overview of music functions
48 @subsection Overview of music functions
50 Es fácil hacer una función que sustituya a una variable en código de
51 LilyPond. La forma general de estas funciones es:
55 #(define-music-function (parser location @var{var1} @var{var2}... )
56 (@var{var1-type?} @var{var2-type?}...)
65 @multitable @columnfractions .33 .66
66 @item @var{argi} @tab @var{i}-ésima variable
67 @item @var{argi-type?} @tab tipo de variable
68 @item @var{...música...} @tab entrada normal de LilyPond, usando las variables como @code{#$var1}.
71 Los siguientes tipos de entrada se pueden usar como variables en una
72 función musical. Esta lista no es exhaustiva; consulte otros lugares
73 de la documentación específica de Scheme para ver otros tipos de
76 @multitable @columnfractions .33 .66
77 @headitem Tipo de entrada @tab notación de @var{argi-type?}
78 @item Entero @tab @code{integer?}
79 @item Flotante (número decimal) @tab @code{number?}
80 @item Cadena de texto @tab @code{string?}
81 @item Marcado @tab @code{markup?}
82 @item Expresión musical @tab @code{ly:music?}
83 @item Pareja de variables @tab @code{pair?}
86 Los argumentos @code{parser} y @code{location} son obligatorios, y
87 se usan en ciertas situaciones avanzadas. El argumento
88 @code{parser} se usa para acceder al valor de otra variable de
89 LilyPond. El argumento @code{location} se usa para establecer el
90 @q{origen} de la expresión musical que construye la función musical,
91 de forma que en caso de producirse un error de sintaxis LilyPond pueda
92 informar al usuario de un lugar adecuado donde buscar en el archivo de
96 @node Simple substitution functions
97 @subsection Simple substitution functions
99 He aquí un ejemplo sencillo:
101 @lilypond[quote,verbatim,ragged-right]
102 padText = #(define-music-function (parser location padding) (number?)
104 \once \override TextScript #'padding = #$padding
112 c4^"piu mosso" fis a g
116 También se pueden sustituir las expresiones musicales:
118 @lilypond[quote,verbatim,ragged-right]
119 custosNote = #(define-music-function (parser location note)
122 \once \override Voice.NoteHead #'stencil =
123 #ly:text-interface::print
124 \once \override Voice.NoteHead #'text =
125 \markup \musicglyph #"custodes.mensural.u0"
126 \once \override Voice.Stem #'stencil = ##f
130 { c' d' e' f' \custosNote g' }
133 Se pueden usar más de una variable:
135 @lilypond[quote,verbatim,ragged-right]
136 tempoMark = #(define-music-function (parser location padding marktext)
139 \once \override Score . RehearsalMark #'padding = $padding
140 \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
141 \mark \markup { \bold $marktext }
146 \tempoMark #3.0 #"Allegro"
152 @node Paired substitution functions
153 @subsection Paired substitution functions
155 Algunas instrucciones @code{\override} requieren un par de números
156 (llamados en Scheme una @code{célula cons}). Para pasar estos números
157 a una función, usamos una variable @code{pair?} o bien insertamos el
158 @code{cons} en la función musical.
163 #(define-music-function (parser location beg-end)
166 \once \override Beam #'positions = #$beg-end
170 \manualBeam #'(3 . 6) c8 d e f
178 @lilypond[quote,verbatim,ragged-right]
180 #(define-music-function (parser location beg end)
183 \once \override Beam #'positions = #(cons $beg $end)
187 \manualBeam #3 #6 c8 d e f
192 @node Mathematics in functions
193 @subsection Mathematics in functions
195 Las funciones musicales pueden contar con programación de Scheme
196 además de la simple sustitución:
198 @lilypond[quote,verbatim,ragged-right]
199 AltOn = #(define-music-function (parser location mag) (number?)
200 #{ \override Stem #'length = #$(* 7.0 mag)
201 \override NoteHead #'font-size =
202 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) #})
205 \revert Stem #'length
206 \revert NoteHead #'font-size
209 { c'2 \AltOn #0.5 c'4 c'
210 \AltOn #1.5 c' c' \AltOff c'2 }
214 Este ejemplo se puede reescribir de forma que pase expresiones
217 @lilypond[quote,verbatim,ragged-right]
218 withAlt = #(define-music-function (parser location mag music) (number? ly:music?)
219 #{ \override Stem #'length = #$(* 7.0 mag)
220 \override NoteHead #'font-size =
221 #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
223 \revert Stem #'length
224 \revert NoteHead #'font-size #})
226 { c'2 \withAlt #0.5 {c'4 c'}
227 \withAlt #1.5 {c' c'} c'2 }
232 @subsection Void functions
234 Una función musical debe devolver una expresión musical, per a veces
235 podemos necesitar una función en la que no hay música en juego (como
236 la desactivación de la funcionalidad Apuntar y Pulsar). Para hacerlo,
237 devolvemos una expresión musical @code{void} (vacía).
239 Este es el motivo por el que la forma que se devuelve es
240 @code{(make-music ...)}. Con el valor de la propiedad @code{'void}
241 establecido a @code{#t}, le decimos al analizador que descarte la
242 expresión musical devuelta. así, la parte importante de la función
243 musical vacía es el proceso realizado por la función, no la expresión
244 musical que se devuelve.
248 #(define-music-function (parser location) ()
249 (ly:set-option 'point-and-click #f)
250 (make-music 'SequentialMusic 'void #t))
252 \noPointAndClick % desactivar la funcionalidad Apuntar y Pulsar.
256 @node Functions without arguments
257 @subsection Functions without arguments
259 En casi todos los casos, una función sin argumentos se debe escribir
263 dolce = \markup@{ \italic \bold dolce @}
266 Sin embargo, en raras ocasiones puede ser de utilidad crear una
267 función musical sin argumentos:
271 #(define-music-function (parser location) ()
272 (if (eq? #t (ly:get-option 'display-bar-numbers))
273 #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
277 Para la imresión real de los números de compás donde se llama a esta
278 función, invoque a @command{lilypond} con
281 lilypond -d display-bar-numbers ARCHIVO.ly
285 @node Overview of available music functions
286 @subsection Overview of available music functions
288 @c fixme ; this should be move somewhere else?
289 Las siguientes instrucciones son funciones musicales:
291 @include identifiers.tely
294 @node Programmer interfaces
295 @section Programmer interfaces
297 Esta sección contiene información sobre cómo mezclar LilyPond y
301 * Input variables and Scheme::
302 * Internal music representation::
305 @node Input variables and Scheme
306 @subsection Input variables and Scheme
308 El formato de entrada contempla la noción de variables: en el ejemplo
309 siguiente, se asigna una expresión musical a una variable con el
310 nombre @code{traLaLa}.
313 traLaLa = @{ c'4 d'4 @}
318 También existe una forma de ámbito léxico: en el ejemplo siguiente, el
319 bloque @code{\layout} también contiene una variable @code{traLaLa},
320 que es independiente de la @code{\traLaLa} exterior.
323 traLaLa = @{ c'4 d'4 @}
324 \layout @{ traLaLa = 1.0 @}
327 De hecho, cada archivo de entrada es un ámbito léxico, y todos los
328 bloques @code{\header}, @code{\midi} y @code{\layout} son ámbitos
329 anidados dentro de dicho ámbito de nivel superior.
331 Tanto el ámbito léxico como las variables están implementados en el
332 sistema de módulos GUILE. Se adjunta un módulo anónimo de Scheme a
333 cada ámbito. Una asignación de la forma
335 traLaLa = @{ c'4 d'4 @}
339 se convierte internamente a una definición de Scheme
341 (define traLaLa @var{Scheme value of `@code{... }'})
344 Esto supone que las variables de entrada y las variables de Scheme se
345 pueden intermezclar con libertad. En el ejemplo siguiente, se
346 almacena un fragmento musical en la variable @code{traLaLa}, y se
347 dupplica utilizando Scheme. El resultado se importa en un bloque
348 @code{\score} por medio de una segunda variable @code{twice}:
351 traLaLa = { c'4 d'4 }
353 %% dummy action to deal with parser lookahead
354 #(display "this needs to be here, sorry!")
356 #(define newLa (map ly:music-deep-copy
357 (list traLaLa traLaLa)))
359 (make-sequential-music newLa))
364 @c Due to parser lookahead
366 En este ejemplo, la asignación se produce después de que el analizador
367 sintáctico ha verificado que no ocurre nada interesante después de
368 @code{traLaLa = @{ ... @}}. Sin el argumento mudo del ejemplo, la
369 definición @code{newLa} se ejecuta antes de que se defina
370 @code{traLaLa}, conduciendo a un error de sintaxis.
372 El ejemplo anterior muestra cómo @q{exportar} expresiones musicales
373 desde la entrada hasta el intérprete de Scheme. También es posible lo
374 contrario. Envolviendo un valor de Scheme en la función
375 @code{ly:export}, un valor de Scheme se interpreta como si hubiera
376 sido introducido en sintaxis de LilyPond. En vez de definir
377 @code{\twice}, el ejemplo anterior podría también haberse escrito como
380 @{ #(ly:export (make-sequential-music (list newLa))) @}
383 El sódigo de Scheme se evalúa tan pronto como el analizador sintáctico
384 lo encuentra. Para definir código de Scheme en un macro (para
385 llamarlo con posterioridad), use @ref{Void functions}, o bien
389 (ly:set-option 'point-and-click #f))
398 No es posible mezclar variables de Scheme y de LilyPond con la opción
402 @node Internal music representation
403 @subsection Internal music representation
408 @node Building complicated functions
409 @section Building complicated functions
415 * Displaying music expressions::
417 * Doubling a note with slurs (example)::
418 * Adding articulation to notes (example)::
421 @node Displaying music expressions
422 @subsection Displaying music expressions
427 @node Music properties
428 @subsection Music properties
433 @node Doubling a note with slurs (example)
434 @subsection Doubling a note with slurs (example)
439 @node Adding articulation to notes (example)
440 @subsection Adding articulation to notes (example)
445 @node Markup programmer interface
446 @section Markup programmer interface
452 * Markup construction in Scheme::
453 * How markups work internally::
454 * New markup command definition::
455 * New markup list command definition::
458 @node Markup construction in Scheme
459 @subsection Markup construction in Scheme
464 @node How markups work internally
465 @subsection How markups work internally
470 @node New markup command definition
471 @subsection New markup command definition
476 @node New markup list command definition
477 @subsection New markup list command definition
482 @node Contexts for programmers
483 @section Contexts for programmers
489 * Context evaluation::
490 * Running a function on all layout objects::
493 @node Context evaluation
494 @subsection Context evaluation
499 @node Running a function on all layout objects
500 @subsection Running a function on all layout objects
505 @node Scheme procedures as properties
506 @section Scheme procedures as properties
512 @node Using Scheme code instead of \tweak
513 @section Using Scheme code instead of @code{\tweak}
518 @node Difficult tweaks
519 @section Difficult tweaks