Doc-es: Programming Interface, - l.401

[lilypond.git] / Documentation / es / user / programming-interface.itely

@c -*- coding: utf-8; mode: texinfo; documentlanguage: es -*-
@c This file is part of lilypond.tely
@ignore
    Translation of GIT committish: 4a527608c5ff2ce31e596495d00dce181dc1b9ea

    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.11.61"

@node Interfaces for programmers
@chapter Interfaces for programmers

Se pueden realizar trucos avanzados mediante el uso de Scheme.  Si no
está familizarizado con Scheme, le conviene leer nuestro tutorial de
Scheme, @rlearning{Scheme tutorial}.

@menu
* Music functions::
* Programmer interfaces::
* Building complicated functions::
* Markup programmer interface::
* Contexts for programmers::
* Scheme procedures as properties::
* Using Scheme code instead of \tweak::
* Difficult tweaks::
@end menu


@node Music functions
@section Music functions

Esta sección trata sobre cómo crear funciones musicales dentro de
LilyPond.

@menu
* Overview of music functions::
* Simple substitution functions::
* Paired substitution functions::
* Mathematics in functions::
* Void functions::
* Functions without arguments::
* Overview of available music functions::
@end menu

@node Overview of music functions
@subsection Overview of music functions

Es fácil hacer una función que sustituya a una variable en código de
LilyPond.  La forma general de estas funciones es:

@example
funcion =
#(define-music-function (parser location @var{var1} @var{var2}... )
                        (@var{var1-type?} @var{var2-type?}...)
  #@{
    @emph{...música...}
  #@})
@end example

@noindent
donde

@multitable @columnfractions .33 .66
@item @var{argi}         @tab @var{i}-ésima variable
@item @var{argi-type?}   @tab tipo de variable
@item @var{...música...}  @tab entrada normal de LilyPond, usando las variables como @code{#$var1}.
@end multitable

Los siguientes tipos de entrada se pueden usar como variables en una
función musical.  Esta lista no es exhaustiva; consulte otros lugares
de la documentación específica de Scheme para ver otros tipos de
variables.

@multitable @columnfractions .33 .66
@headitem Tipo de entrada       @tab notación de @var{argi-type?}
@item Entero                    @tab @code{integer?}
@item Flotante (número decimal) @tab @code{number?}
@item Cadena de texto           @tab @code{string?}
@item Marcado                   @tab @code{markup?}
@item Expresión musical         @tab @code{ly:music?}
@item Pareja de variables          @tab @code{pair?}
@end multitable

Los argumentos @code{parser} y @code{location} son obligatorios, y
se usan en ciertas situaciones avanzadas.  El argumento
@code{parser} se usa para acceder al valor de otra variable de
LilyPond.  El argumento @code{location} se usa para establecer el
@q{origen} de la expresión musical que construye la función musical,
de forma que en caso de producirse un error de sintaxis LilyPond pueda
informar al usuario de un lugar adecuado donde buscar en el archivo de
entrada.


@node Simple substitution functions
@subsection Simple substitution functions

He aquí un ejemplo sencillo:

@lilypond[quote,verbatim,ragged-right]
padText = #(define-music-function (parser location padding) (number?)
  #{
    \once \override TextScript #'padding = #$padding
  #})

\relative c''' {
  c4^"piu mosso" b a b
  \padText #1.8
  c4^"piu mosso" d e f
  \padText #2.6
  c4^"piu mosso" fis a g
}
@end lilypond

También se pueden sustituir las expresiones musicales:

@lilypond[quote,verbatim,ragged-right]
custosNote = #(define-music-function (parser location note)
                                     (ly:music?)
  #{
    \once \override Voice.NoteHead #'stencil =
      #ly:text-interface::print
    \once \override Voice.NoteHead #'text =
      \markup \musicglyph #"custodes.mensural.u0"
    \once \override Voice.Stem #'stencil = ##f
    $note
  #})

{ c' d' e' f' \custosNote g' }
@end lilypond

Se pueden usar más de una variable:

@lilypond[quote,verbatim,ragged-right]
tempoMark = #(define-music-function (parser location padding marktext)
                                    (number? string?)
#{
  \once \override Score . RehearsalMark #'padding = $padding
  \once \override Score . RehearsalMark #'extra-spacing-width = #'(+inf.0 . -inf.0)
  \mark \markup { \bold $marktext }
#})

\relative c'' {
c2 e
\tempoMark #3.0 #"Allegro"
g c
}
@end lilypond


@node Paired substitution functions
@subsection Paired substitution functions

Algunas instrucciones @code{\override} requieren un par de números
(llamados en Scheme una @code{célula cons}).  Para pasar estos números
a una función, usamos una variable @code{pair?} o bien insertamos el
@code{cons} en la función musical.

@quotation
@example
manualBeam =
#(define-music-function (parser location beg-end)
                        (pair?)
#@{
  \once \override Beam #'positions = #$beg-end
#@})

\relative @{
  \manualBeam #'(3 . 6) c8 d e f
@}
@end example
@end quotation

@noindent
o bien

@lilypond[quote,verbatim,ragged-right]
manualBeam =
#(define-music-function (parser location beg end)
                        (number? number?)
#{
  \once \override Beam #'positions = #(cons $beg $end)
#})

\relative {
  \manualBeam #3 #6 c8 d e f
}
@end lilypond


@node Mathematics in functions
@subsection Mathematics in functions

Las funciones musicales pueden contar con programación de Scheme
además de la simple sustitución:

@lilypond[quote,verbatim,ragged-right]
AltOn = #(define-music-function (parser location mag) (number?)
  #{ \override Stem #'length = #$(* 7.0 mag)
     \override NoteHead #'font-size =
       #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag))) #})

AltOff = {
  \revert Stem #'length
  \revert NoteHead #'font-size
}

{ c'2 \AltOn #0.5 c'4 c'
  \AltOn #1.5 c' c' \AltOff c'2 }
@end lilypond

@noindent
Este ejemplo se puede reescribir de forma que pase expresiones
musicales:

@lilypond[quote,verbatim,ragged-right]
withAlt = #(define-music-function (parser location mag music) (number? ly:music?)
  #{ \override Stem #'length = #$(* 7.0 mag)
     \override NoteHead #'font-size =
       #$(inexact->exact (* (/ 6.0 (log 2.0)) (log mag)))
     $music
     \revert Stem #'length
     \revert NoteHead #'font-size #})

{ c'2 \withAlt #0.5 {c'4 c'}
  \withAlt #1.5 {c' c'} c'2 }
@end lilypond


@node Void functions
@subsection Void functions

Una función musical debe devolver una expresión musical, per 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).

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
noPointAndClick =
#(define-music-function (parser location) ()
   (ly:set-option 'point-and-click #f)
   (make-music 'SequentialMusic 'void #t))
...
\noPointAndClick   % desactivar la funcionalidad Apuntar y Pulsar.
@end example


@node Functions without arguments
@subsection Functions without arguments

En casi todos los casos, una función sin argumentos se debe escribir
con una variable:

@example
dolce = \markup@{ \italic \bold dolce @}
@end example

Sin embargo, en raras ocasiones puede ser de utilidad crear una
función musical sin argumentos:

@example
displayBarNum =
#(define-music-function (parser location) ()
   (if (eq? #t (ly:get-option 'display-bar-numbers))
       #@{ \once \override Score.BarNumber #'break-visibility = ##f #@}
       #@{#@}))
@end example

Para la imresión real de los números de compás donde se llama a esta
función, invoque a @command{lilypond} con

@example
lilypond -d display-bar-numbers ARCHIVO.ly
@end example


@node Overview of available music functions
@subsection Overview of available music functions

@c fixme ; this should be move somewhere else?
Las siguientes instrucciones son funciones musicales:

@include identifiers.tely


@node Programmer interfaces
@section Programmer interfaces

Esta sección contiene información sobre cómo mezclar LilyPond y
Scheme.

@menu
* Input variables and Scheme::
* Internal music representation::
@end menu

@node Input variables and Scheme
@subsection Input variables and Scheme

El formato de entrada contempla la noción de variables: en el ejemplo
siguiente, se asigna una expresión musical a una variable con el
nombre @code{traLaLa}.

@example
traLaLa = @{ c'4 d'4 @}
@end example

@noindent

También existe una forma de ámbito léxico: en el ejemplo siguiente, el
bloque @code{\layout} también contiene una variable @code{traLaLa},
que es independiente de la @code{\traLaLa} exterior.

@example
traLaLa = @{ c'4 d'4 @}
\layout @{ traLaLa = 1.0 @}
@end example
@c
De hecho, cada archivo de entrada es un ámbito léxico, y todos los
bloques @code{\header}, @code{\midi} y @code{\layout} son ámbitos
anidados dentro de dicho ámbito de nivel superior.

Tanto el ámbito léxico como las variables están implementados en el
sistema de módulos GUILE.  Se adjunta un módulo anónimo de Scheme a
cada ámbito.  Una asignación de la forma
@example
traLaLa = @{ c'4 d'4 @}
@end example

@noindent
se convierte internamente a una definición de Scheme
@example
(define traLaLa @var{Scheme value of `@code{... }'})
@end example

Esto supone que las variables de entrada y las variables de Scheme se
pueden intermezclar con libertad.  En el ejemplo siguiente, se
almacena un fragmento musical en la variable @code{traLaLa}, y se
dupplica utilizando Scheme.  El resultado se importa en un bloque
@code{\score} por medio de una segunda variable @code{twice}:

@lilypond[verbatim]
traLaLa = { c'4 d'4 }

%% dummy action to deal with parser lookahead
#(display "this needs to be here, sorry!")

#(define newLa (map ly:music-deep-copy
  (list traLaLa traLaLa)))
#(define twice
  (make-sequential-music newLa))

{ \twice }
@end lilypond

@c Due to parser lookahead

En este ejemplo, la asignación se produce después de que el analizador
sintáctico ha verificado que no ocurre nada interesante después de
@code{traLaLa = @{ ... @}}.  Sin el argumento mudo del ejemplo, la
definición @code{newLa} se ejecuta antes de que se defina
@code{traLaLa}, conduciendo a un error de sintaxis.

El ejemplo anterior muestra cómo @q{exportar} expresiones musicales
desde la entrada hasta el intérprete de Scheme.  También es posible lo
contrario.  Envolviendo un valor de Scheme en la función
@code{ly:export}, un valor de Scheme se interpreta como si hubiera
sido introducido en sintaxis de LilyPond.  En vez de definir
@code{\twice}, el ejemplo anterior podría también haberse escrito como
@example
@dots{}
@{ #(ly:export (make-sequential-music (list newLa))) @}
@end example

El sódigo de Scheme se evalúa tan pronto como el analizador sintáctico
lo encuentra.  Para definir código de Scheme en un macro (para
llamarlo con posterioridad), use @ref{Void functions}, o bien

@example
#(define (nopc)
  (ly:set-option 'point-and-click #f))

...
#(nopc)
@{ c'4 @}
@end example

@knownissues

No es posible mezclar variables de Scheme y de LilyPond con la opción
@code{--safe}.


@node Internal music representation
@subsection Internal music representation

@untranslated


@node Building complicated functions
@section Building complicated functions

@untranslated


@menu
* Displaying music expressions::
* Music properties::
* Doubling a note with slurs (example)::
* Adding articulation to notes (example)::
@end menu

@node Displaying music expressions
@subsection Displaying music expressions

@untranslated


@node Music properties
@subsection Music properties

@untranslated


@node Doubling a note with slurs (example)
@subsection Doubling a note with slurs (example)

@untranslated


@node Adding articulation to notes (example)
@subsection Adding articulation to notes (example)

@untranslated


@node Markup programmer interface
@section Markup programmer interface

@untranslated


@menu
* Markup construction in Scheme::
* How markups work internally::
* New markup command definition::
* New markup list command definition::
@end menu

@node Markup construction in Scheme
@subsection Markup construction in Scheme

@untranslated


@node How markups work internally
@subsection How markups work internally

@untranslated


@node New markup command definition
@subsection New markup command definition

@untranslated


@node New markup list command definition
@subsection New markup list command definition

@untranslated


@node Contexts for programmers
@section Contexts for programmers

@untranslated


@menu
* Context evaluation::
* Running a function on all layout objects::
@end menu

@node Context evaluation
@subsection Context evaluation

@untranslated


@node Running a function on all layout objects
@subsection Running a function on all layout objects

@untranslated


@node Scheme procedures as properties
@section Scheme procedures as properties

@untranslated



@node Using Scheme code instead of \tweak
@section Using Scheme code instead of @code{\tweak}

@untranslated


@node Difficult tweaks
@section Difficult tweaks

@untranslated