@c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
@c This file is part of extending.tely
@ignore
- Translation of GIT committish: 2055f35c47a045a50a01ff4dba8524322cfc3b48
+ Translation of GIT committish: abf44faa7aff3481efcd8b241c352c6d5080ccd5
When revising a translation, copy the HEAD committish of the
version that you are working on. See TRANSLATION for details.
@end ignore
-@c \version "2.14.0"
+@c \version "2.15.17"
@node Interfaces para programadores
@chapter Interfaces para programadores
@menu
+* Bloques de código de LilyPond::
+* Funciones de Scheme::
* Funciones musicales::
+* Funciones de eventos::
* Funciones de marcado::
* Contextos para programadores::
* Funciones de callback::
* Trucos difíciles::
@end menu
-@node Funciones musicales
-@section Funciones musicales
-@translationof Music functions
+@node Bloques de código de LilyPond
+@section Bloques de código de LilyPond
+@translationof Lilypond code blocks
+
+Los bloques de código de LilyPond tienen el siguiente aspecto:
+@example
+ #@{ @var{código de LilyPond} #@}
+@end example
+Se pueden usar en cualquier lugar en el que se pueda escribir código
+de Scheme: el lector de Scheme en efecto se modifica para que pueda
+incorporar bloques de código de LilyPond. Mientras se está leyendo el
+bloque de código de LilyPond, se analiza sintácticamente de forma
+superficial y se sustituye por una llamada al analizador sintáctico de
+LilyPond, que funciona en tiempo de ejecución para que interprete el
+bloque de código de LilyPond.
+
+El objeto del análisis superficial es la interpretación de los
+símbolos @code{$} que se pueden usar para aislar expresiones del
+contexto léxico de Scheme que les rodea (como variables de @code{let}
+y parámetros de función). El @code{$} se puede usar de las maneras
+siguientes:
+
+@table @code
+@item $$
+simplemente pasa un único símbolo @code{$} al analizador de LilyPond.
+@item $@var{forma}
+evalúa la forma Scheme en tiempo de ejecución y la analiza como un
+identificador @code{\forma} en el analizador de LilyPond. Dependiendo
+del tipo del valor, se puede interpretar como varias entidades
+sintácticas diferentes.
+@item #$@var{forma}
+evalúa la forma de Scheme en tiempo de ejecución y analiza su valor
+como una expresión de Scheme dentro del analizador de LilyPond.
+@item #@var{forma}
+las formas que están dentro de expresiones de Scheme y que comienzan
+por @code{#} se leen y se analizan recursivamente hasta que se
+encuentran símbolos de @code{$}. Entonces se tratan como sigue:
+@item #@dots{}$@var{variable}
+analiza el valor de la variable dentro de la expresión circundante.
+@item #@dots{}($ @var{forma} @dots{})
+analiza el valor de la forma dentro de la expresión circundante. Al
+contrario que las @code{$@var{formas}} a nivel de LilyPond,
+necesitamos separar la forma con un espacio en blanco, haciendo que
+@code{$} sea reconocible como un símbolo de Scheme separado.
+@end table
-Las @emph{funciones musicales} son procedimientos de Scheme
-que pueden crear automáticamente expresiones musicales, y se
-pueden usar para simplificar enormemente el archivo de entrada.
+Un bloque de código de LilyPond puede contener cualquier cosa que
+podríamos utilizar en la parte derecha de una asignación. Además, un
+bloque de LilyPond vacío corresponde a una expresión musical vacía, y
+un bloque de LilyPond que contiene varios eventos musicales se
+convierte en una expresión de música secuencial.
+
+@node Funciones de Scheme
+@section Funciones de Scheme
+@translationof Scheme functions
+@cindex Scheme, funciones de (sintaxis de LilyPond)
+
+Las @emph{funciones de Scheme} son procedimientos de Scheme que pueden
+crear expresiones de Scheme a partir de código de entrada escrito en
+la sintaxis de LilyPond. Se pueden llamar desde prácticamente
+cualquier lugar en el que se permita el uso de @code{#} para la
+especificación de un valor en sintaxis de Scheme. Mientras que Scheme
+tiene funciones propias, este capítulo se ocupa de las funciones
+@emph{sintácticas}, funciones que reciben argumentos especificados en
+la sintaxis de LilyPond.
@menu
-* Sintaxis de las funciones musicales::
-* Funciones de sustitución sencillas::
-* Funciones de sustitución intermedias::
-* Matemáticas dentro de las funciones::
-* Funciones sin argumentos::
-* Funciones vacías::
+* Definición de funciones de Scheme::
+* Uso de las funciones de Scheme::
+* Funciones de Scheme vacías::
@end menu
-@node Sintaxis de las funciones musicales
-@subsection Sintaxis de las funciones musicales
-@translationof Music function syntax
+@node Definición de funciones de Scheme
+@subsection Definición de funciones de Scheme
+@translationof Scheme function definitions
+@funindex define-scheme-function
-La forma general de una función musical es:
+La forma general de la definición de una función de Scheme es:
@example
funcion =
-#(define-music-function
+#(define-scheme-function
(parser location @var{arg1} @var{arg2} @dots{})
(@var{type1?} @var{type2?} @dots{})
- @var{música})
+ @var{cuerpo})
@end example
@noindent
donde
@multitable @columnfractions .33 .66
+@item @code{parser}
+@tab tiene que ser literalmente @code{parser} para dar a los bloques de código
+de LilyPond (@code{#@{}@dots{}@code{#@}}) acceso al analizador sintáctico.
+
@item @code{@var{argN}}
@tab @var{n}-ésimo argumento
@item @code{@var{typeN?}}
@tab un @emph{predicado de tipo} de Scheme para el que @code{@var{argN}}
-deve devolver @code{#t}.
-
-@item @code{@var{música}}
-@tab una expresión musical, opcionalmente escrita en Scheme, con
-el código de LilyPond que pudiera tener, encerrado entre llaves
-con almohadilla
-(@tie{}@w{@code{#@{@dots{}#@}}}@tie{}). Dentro de los bloques
-de código de LilyPond, use @code{$} para referenciar a los argumentos
-de la función (p. ej. @samp{$arg1})
-o para iniciar una expresión en línea de Scheme
-que contenga argumentos de función
-(p.ej., @w{@samp{$(cons arg1 arg2)}}).
-
+debe devolver @code{#t}. Algunos de estos predicados se reconocen de
+forma especial por parte del analizador, véase más abajo. También
+existe una forma especial @code{(@emph{predicate?} @emph{default})}
+para especificar argumentos opcionales. Si el argumento actual no
+está presente cuando se llama a la función, el valor predeterminado se
+emplea en sustitución. Los valores predeterminados se evalúan en
+tiempo de definición (¡incluyendo los bloques de código de LilyPond!),
+de manera que se necesitamos un valor por omisión calculado en tiempo
+de ejecución, debemos escribir en su lugar un valor especial que
+podamos reconocer fácilmente. Si escribimos el predicado entre
+paréntesis pero no lo seguimos por el valor predeterminado, se usa
+@code{#f} como valor por omisión. Los valores por omisión no se
+verifican con @emph{predicate?} en tiempo de definición ni en tiempo
+de ejecución: es nuestra responsabilidad tratar con los valores que
+especifiquemos. Los valores por omisión que son expresiones musicales
+se copian mientras se establece @code{origin} al parámetro
+@code{location}.
+
+@item @code{@var{cuerpo}}
+@tab una secuencia de formas de Scheme que se evalúan ordenadamente; la
+última forma de la secuencia se usa como el valor de retorno de la
+función de Scheme. Puede contener bloques de código de LilyPond
+encerrados entre llaves con almohadillas
+(@tie{}@w{@code{#@{@dots{}#@}}}@tie{}), como se describe en
+@ref{Bloques de código de LilyPond}. Dentro de los bloques de código
+de LilyPond, use el símbolo del dólar @code{$} para hacer referencia a
+argumentos de función (p.ej. @samp{$arg1}) o para iniciar una
+expresión en línea de Scheme que contenga argumentos de función
+(p.ej. @w{@samp{$(cons arg1 arg2)}}). Si la función devuelve una
+expresión musical, se clona y se le da el @code{origin} correcto.
@end multitable
@noindent
+Ciertos predicados de tipo se reconocen de forma especial por parte
+del analizador sintáctico y hacen que éste busque los argumentos
+respectivos en la sintaxis de LilyPond en lugar de hacerlo en la
+sintaxis de Scheme. Actualmente son @code{ly:music?}, @code{markup?},
+@code{ly:pitch?} y @code{ly:duration?}.
+
+Si realmente quiere escribir uno de los elementos especiales como
+Scheme en lugar de como una expresión de LilyPond, puede escribirlos
+como una expresión de Scheme que llame a @code{ly:export} en su nivel
+exterior.
+
+Otros predicados de tipo, entre ellos los que están definidos por el
+usuario hacen que el argumento respectivo sólo se acepte como una
+expresión de Scheme, normalmente precedida de @code{#} o como
+resultado de llamar a una función de Scheme.
+
Para ver una lista de los predicados de tipo disponibles, consulte
@ruser{Predicados de tipo predefinidos}.
-También se permiten predicados de tipo definidos por el usuario.
+@seealso
+
+Referencia de la notación:
+@ruser{Predicados de tipo predefinidos}.
+
+Archivos instalados:
+@file{lily/music-scheme.cc},
+@file{scm/c++.scm},
+@file{scm/lily.scm}.
+
+
+@node Uso de las funciones de Scheme
+@subsection Uso de las funciones de Scheme
+@translationof Scheme function usage
+
+Las funciones de Scheme se pueden llamar casi desde cualquier lugar en
+que puede escribirse una expresión de Scheme que comience con la
+almohadilla@tie{}@code{#}. Llamamos a una función de Scheme
+escribiendo su nombre precedido de la barra invertida@tie{}@code{\}, y
+seguido por sus argumentos. El último argumento no puede ser un
+argumento opcional. Si hay varios argumentos opcionales seguidos, se
+rellenan con valores de izquierda a derecha. Desde el momento en que
+un argumento opcional no corresponde con la entrada, éste y todos los
+argumentos opcionales inmediatamente siguientes se sustituyen por sus
+valores predeterminados, y la correspondencia continúa con el
+siguiente argumento no opcional.
+
+Aparte de los lugares en que se requiere un valor de Scheme hay
+ciertos sitios en que se aceptan expresiones de almohadilla @code{#} y
+se evalúan por sus efectos secundarios, pero por lo demás se ignoran.
+Son, mayormente, los lugares en que también sería aceptable colocar
+una asignación.
+
+Hay ciertos lugares especiales en los que un argumento que corresponde
+a @code{ly:music?} tiene que ser un identificador musical o bien una
+expresión musical encerrada dentro de @code{@{}@dots{}@code{@}} o
+@code{<<}@dots{}@code{>>} de forma explícita, de manera que las
+duraciones o post-eventos opcionales que posiblemente le sigan no
+puedan confundirse con argumentos adicionales. Un sitio obvio es
+antes de un predicado @code{ly:duration?}. Otro es el último
+argumento de una función de Scheme cuando se utiliza en un lugar en
+que tales partes opcionales podrían, o no, considerarse como parte del
+argumento musical.
+
+En esos casos raros, tenemos que delimitar nuestros argumentos
+musicales de forma adecuada para evitar la confusión por parte de
+LilyPond.
+
+@node Funciones de Scheme vacías
+@subsection Funciones de Scheme vacías
+@translationof Void scheme functions
+
+A veces, una función se ejecuta solamente por sus efectos colaterales.
+En tal caso, la utilización de una función de Scheme supone que su
+valor no será considerado de la forma usual:
+
+@example
+noApuntarYPulsar =
+#(define-scheme-function
+ (parser location)
+ ()
+ (ly:set-option 'point-and-click #f))
+...
+\noApuntarYPulsar % desactivar la función de apuntar y pulsar
+@end example
+
+@node Funciones musicales
+@section Funciones musicales
+@translationof Music functions
+
+@cindex funciones musicales
+
+Las @emph{funciones musicales} son procedimientos de Scheme que pueden
+crear automáticamente expresiones musicales, y se pueden usar para
+simplificar enormemente el archivo de entrada.
+
+@menu
+* Definiciones de funciones musicales::
+* Uso de las funciones musicales::
+* Funciones de sustitución sencillas::
+* Funciones de sustitución intermedias::
+* Matemáticas dentro de las funciones::
+* Funciones sin argumentos::
+* Funciones musicales vacías::
+@end menu
+
+
+@node Definiciones de funciones musicales
+@subsection Definiciones de funciones musicales
+@translationof Music function definitions
+@cindex definición de funciones musicales
+@funindex define-music-function
+
+La forma general para definir funciones musicales es:
+
+@example
+funcion =
+#(define-music-function
+ (parser location @var{arg1} @var{arg2} @dots{})
+ (@var{tipo1?} @var{tipo2?} @dots{})
+ @var{cuerpo})
+@end example
+
+@noindent
+de forma bastante análoga a @ref{Definición de funciones de Scheme}.
+Lo más probable es que el @var{cuerpo} sea un
+@ref{Bloques de código de LilyPond,bloque de código de LilyPond}.
+Para ver una lista de los predicados de tipo disponibles, consulte
+@ruser{Predicados de tipo predefinidos}.
@seealso
@file{scm/lily.scm}.
+@node Uso de las funciones musicales
+@subsection Uso de las funciones musicales
+@translationof Music function usage
+
+Las funciones musicales se pueden actualmente utilizar en tres
+lugares. Dependiendo de dónde se usan, son de aplicación ciertas
+restricciones para que sea posible su análisis sintáctico de forma
+no ambigua. El resultado que devuelve una función musical debe ser
+compatible con el contexto desde el que se la llama.
+
+@itemize
+@item
+En el nivel superior dentro de una expresión musical. No existen
+especiales restricciones sobre la lista de argumentos.
+
+@item
+Como un post-evento, que comienza explícitamente con un indicador de
+dirección (a elegir entre @code{-}, @code{^} @w{y @code{_}}). Todos
+los argumentos añadidos al final de la función musical con el
+predicado @code{ly:music?} se analizan sintácticamente también como
+post-eventos (si el último argumento es una función de Scheme, éste
+contendrá en su lugar los argumentos @code{ly:music?} del final de la
+función de Scheme). Observe que se puede aceptar la devolución de un
+post-evento por parte de las funciones musicales que se llaman como
+música normal, lo que lleva a un resultado aproximadamente equivalente
+a
+@example
+s 1*0-\fun
+@end example
+
+@item
+Como componente de un acordes. Todos los argumentos añadidos al final
+de la función musical con el predicado @code{ly:music?} se analizarán
+sintácticamente también como componentes de acorde.
+@end itemize
+
+@noindent
+Las reglas especiales para los argumentos del final hacen posible
+escribir funciones polimórficas como @code{\tweak} que se pueden
+aplicar a construcciones distintas.
+
@node Funciones de sustitución sencillas
@subsection Funciones de sustitución sencillas
@translationof Simple substitution functions
@end example
-@node Funciones vacías
-@subsection Funciones vacías
-@translationof Void functions
-
-Una función musical debe devolver una expresión musical, pero a veces
-podemos necesitar una función en la que no hay música en juego (como
-la desactivación de la funcionalidad Apuntar y Pulsar). Para hacerlo,
-devolvemos una expresión musical @code{void} (vacía).
+@node Funciones musicales vacías
+@subsection Funciones musicales vacías
+@translationof Void music functions
+
+Una función musical debe devolver una expresión musical. Si quiere
+ejecutar una función exclusivamente por sus efectos secundarios,
+podría ser más sensato usar en su lugar una función de Scheme. Pero
+puede haber casos en los que a veces queremos producir una expresión
+musical, y a veces no (como en el ejemplo anterior). Devolver una
+expresión musical @code{void} (vacía) por medio de @code{#@{ #@}} lo
+hace posible.
+
+
+@node Funciones de eventos
+@section Funciones de eventos
+@translationof Event functions
+@funindex define-event-function
+@cindex event functions
+
+Para usar una función musical en el lugar de un evento, tenemos que
+escribir un indicador de dirección antes de ella. Pero a veces, ello
+hace que se pierda la correspondencia con la sintaxis de las
+construcciones que queremos sustituir. Por ejemplo, si queremos
+escribir instrucciones de matiz dinámico, éstos se adjuntan
+habitualmente sin indicador de dirección, como @code{c'\pp}. He aquí
+una forma de escribir indicaciones dinámicas arbitrarias:
+
+@lilypond[quote,verbatim,raggedright]
+dyn=#(define-event-function (parser location arg) (markup?)
+(make-dynamic-script arg)) \relative c' { c\dyn pfsss }
+@end lilypond
-Este es el motivo por el que la forma que se devuelve es
-@code{(make-music ...)}. Con el valor de la propiedad @code{'void}
-establecido a @code{#t}, le decimos al analizador que descarte la
-expresión musical devuelta. así, la parte importante de la función
-musical vacía es el proceso realizado por la función, no la expresión
-musical que se devuelve.
-
-@example
-noApuntarYPulsar =
-#(define-music-function (parser location) ()
- (ly:set-option 'point-and-click #f)
- (make-music 'SequentialMusic 'void #t))
-...
-\noApuntarYPulsar % desactivar la funcionalidad Apuntar y Pulsar.
-@end example
+Podríamos hacer lo mismo usando una función musical, pero entonces
+tendríamos que escribir siempre un indicador de dirección antes de
+llamarla, como @code{@w{c-\dyn pfsss}}.
@node Funciones de marcado
@noindent
equivale a:
@example
-\markup \column @{ \line @{ \bold \italic "hola" \raise #0.4 "mundo" @}
- \larger \line @{ fulano fulanito menganito @} @}
+#@{ \markup \column @{ \line @{ \bold \italic "hola" \raise #0.4 "mundo" @}
+ \larger \line @{ fulano fulanito menganito @} @} #@}
@end example
@noindent
Este ejemplo muestra las principales reglas de traducción entre la
sintaxis del marcado normal de LilyPond y la sintaxis del marcado de
-Scheme.
+Scheme. La utilización de @code{#@{ @dots{} #@}} para escribir en la
+sintaxis de LilyPond será con frecuencia lo más conveniente, pero
+explicamos cómo usar la macro @code{markup} para obtener una solución
+sólo con Scheme.
@quotation
@multitable @columnfractions .3 .3
Todo el lenguaje Scheme está accesible dentro del macro @code{markup}.
Por ejemplo, podemos usar llamadas a funciones dentro de @code{markup}
para así manipular cadenas de caracteres. Esto es útil si se están
-definiendo instrucciones de marcado nuevas (véase @ref{Definición de una instrucción de marcado nueva}).
+definiendo instrucciones de marcado nuevas (véase
+@ref{Definición de una instrucción de marcado nueva}).
@knownissues
Dado que la replicación de los argumentos precedentes para aplicar una
función de marcado a una lista de marcados es poco costosa
principalmente por los argumentos de Scheme, se evitan las caídas de
-reindimiento simplemente mediante la utilización de argumentos de
+rendimiento simplemente mediante la utilización de argumentos de
Scheme para los argumentos antecedentes de las funciones de marcado
que toman un marcado como su último argumento.
rectángulo doble alrededor de un fragmento de texto.
En primer lugar, necesitamos construir un resultado aproximado
-utilizando marcados. Una consulta a @ruser{Text markup commands} nos
-muestra que es útil la instrucción @code{\box}:
+utilizando marcados. Una consulta a @ruser{Instrucciones de marcado
+de texto} nos muestra que es útil la instrucción @code{\box}:
@lilypond[quote,verbatim,ragged-right]
\markup \box \box HELLO
muy pequeño, así que lo vamos a sobreescribir también:
@lilypond[quote,verbatim,ragged-right]
-\markup \override #'(box-padding . 0.4) \box \override #'(box-padding . 0.6) \box A
+\markup \override #'(box-padding . 0.4) \box
+ \override #'(box-padding . 0.6) \box A
@end lilypond
Repetir esta extensa instrucción de marcado una y otra vez sería un
@code{double-box}, que toma un argumento (el texto). Dibuja los dos
rectángulos y añade una separación.
+@lisp
+#(define-markup-command (double-box layout props text) (markup?)
+ "Trazar un rectángulo doble rodeando el texto."
+ (interpret-markup layout props
+ #@{\markup \override #'(box-padding . 0.4) \box
+ \override #'(box-padding . 0.6) \box @{ $text @}#@}))
+@end lisp
+
+or, equivalently
+
@lisp
#(define-markup-command (double-box layout props text) (markup?)
"Trazar un rectángulo doble rodeando el texto."
@code{markup?} es el tipo: lo identifica como un elemento de marcado.
La función @code{interpret-markup} se usa en casi todas las
instrucciones de marcado: construye un sello, usando @code{layout},
-@code{props}, y un elemento de marcado. Aquí, la marca se construye
-usando el macro de Scheme @code{markup}, véase @ref{Construcción de
-elementos de marcado en Scheme}. La transformación de una expresión
-@code{\markup} en una expresión de marcado de Scheme es directa.
+@code{props}, y un elemento de marcado. En el segundo caso, la marca
+se construye usando el macro de Scheme @code{markup}, véase
+@ref{Construcción de elementos de marcado en Scheme}. La
+transformación de una expresión @code{\markup} en una expresión de
+marcado de Scheme es directa.
La instrucción nueva se puede usar como sigue:
rectángulos. El @code{box-padding} se usará para el relleno interno.
Ahora el código nuevo es como se ve a continuación:
+@lisp
+#(define-markup-command (double-box layout props text) (markup?)
+ #:properties ((inter-box-padding 0.4)
+ (box-padding 0.6))
+ "Trazar un rectángulo doble rodeando el texto."
+ (interpret-markup layout props
+ #@{\markup \override #`(box-padding . ,$inter-box-padding) \box
+ \override #`(box-padding . ,$box-padding) \box
+ @{ $text @} #@}))
+@end lisp
+
+De nuevo, la versión equivalente que utiliza la macro de marcado sería:
+
@lisp
#(define-markup-command (double-box layout props text) (markup?)
#:properties ((inter-box-padding 0.4)
(box-padding 0.6))
"Draw a double box around text."
(interpret-markup layout props
- (markup #:override `(box-padding . ,inter-box-padding) #:box
- #:override `(box-padding . ,box-padding) #:box text)))
+ #{\markup \override #`(box-padding . ,$inter-box-padding) \box
+ \override #`(box-padding . ,$box-padding) \box
+ { $text } #}))
\markup \double-box A
\markup \override #'(inter-box-padding . 0.8) \double-box A
estando la primera de ellas sangrada. La anchura del sangrado se toma
del argumento @code{props}.
+@example
+#(define-markup-list-command (paragraph layout props args) (markup-list?)
+ #:properties ((par-indent 2))
+ (interpret-markup-list layout props
+ #@{\markuplist \justified-lines @{ \hspace #$par-indent $args @} #@}))
+@end example
+
+
+La versión que usa solamente Scheme es más compleja:
@example
#(define-markup-list-command (paragraph layout props args) (markup-list?)
#:properties ((par-indent 2))
llamada aquí @code{par-indent}, de la lista de propiedades
@code{props}. Si no se encuentra la propiedad, el valor
predeterminado es @code{2}. Después, se hace una lista de líneas
-justificadas usando la función
-@code{make-justified-lines-markup-list}, que está relacionada con la
-instrucción incorporada de lista de marcados @code{\justified-lines}.
-Se añade un espacio horizontal al principio usando la función
-@code{make-hspace-markup}. Finalmente, la lista de marcados se
+justificadas usando la instrucción incorporada de lista de marcados
+@code{\justified-lines}, que está relacionada con la función
+@code{make-justified-lines-markup-list}. Se añade un espacio
+horizontal al principio usando @code{\hspace} (o la función
+@code{make-hspace-markup}). Finalmente, la lista de marcados se
interpreta usando la función @code{interpret-markup-list}.
Esta nueva instrucción de lista de marcados se puede usar como sigue:
@example
-\markuplines @{
+\markuplist @{
\paragraph @{
El arte de la tipografía musical se llama \italic @{grabado (en plancha).@}
El término deriva del proceso tradicional de impresión de música.
\override Stem #'thickness = #2.0
@end example
-Las propiedades pueden fijarse también a un procedimiento de scheme,
+Las propiedades pueden fijarse también a un procedimiento de Scheme,
@lilypond[fragment,verbatim,quote,relative=2]
\override Stem #'thickness = #(lambda (grob)
projects / lilypond.git / blobdiff