[ << Notation manual tables ] | [Top][Contents][Index][ ? ] | [ Cheat sheet >> ] | ||
[ < Identifiers ] | [ Up : Notation manual tables ] | [ Cheat sheet > ] |
B.15 Scheme functions
- Function: ly:add-listener list disp cl
Add the listener list to the dispatcher disp. Whenever disp hears an event of class cl, it is forwarded to list.
- Function: ly:assoc-get key alist default-value
Return value if key in alist, else
default-value
(or#f
if not specified).
- Function: ly:book-process book-smob default-paper default-layout output
Print book. output is passed to the backend unchanged. For example, it may be a string (for file based outputs) or a socket (for network based output).
- Function: ly:book-process-to-systems book-smob default-paper default-layout output
Print book. output is passed to the backend unchanged. For example, it may be a string (for file based outputs) or a socket (for network based output).
- Function: ly:bracket a iv t p
Make a bracket in direction a. The extent of the bracket is given by iv. The wings protrude by an amount of p, which may be negative. The thickness is given by t.
- Function: ly:chain-assoc-get key achain dfault
Return value for key from a list of alists achain. If no entry is found, return dfault or
#f
if no dfault is specified.
- Function: ly:clear-anonymous-modules
Plug a GUILE 1.6 and 1.7 memory leak by breaking a weak reference pointer cycle explicitly.
- Function: ly:context-events-below context
Return a
stream-distributor
that distributes all events from context and all its subcontexts.
- Function: ly:context-find context name
Find a parent of context that has name or alias name. Return
#f
if not found.
- Function: ly:context-grob-definition context name
Return the definition of name (a symbol) within context as an alist.
- Function: ly:context-id context
Return the ID string of context, i.e., for
\context Voice = one …
return the stringone
.
- Function: ly:context-name context
Return the name of context, i.e., for
\context Voice = one …
return the symbolVoice
.
- Function: ly:context-property-where-defined context name
Return the context above context where name is defined.
- Function: ly:context-pushpop-property context grob eltprop val
Do a single
\override
or\revert
operation in context. The grob definition grob is extended with eltprop (if val is specified) or reverted (if unspecified).
- Function: ly:context-set-property! context name val
Set value of property name in context context to val.
- Function: ly:dimension? d
Return d as a number. Used to distinguish length variables from normal numbers.
- Function: ly:dir? s
A type predicate. The direction
s
is-1
,0
or1
, where-1
represents left or down and1
represents right or up.
- Function: ly:error str rest
A Scheme callable function to issue the error str. The error is formatted with
format
and rest.
- Function: ly:eval-simple-closure delayed closure scm-start scm-end
Evaluate a simple closure with the given delayed argument. If scm-start and scm-end are defined, evaluate it purely with those start and end points.
- Function: ly:event-property sev sym
Get the property sym of stream event mus. If sym is undefined, return
'()
.
- Function: ly:find-accidentals-simple keysig pitch-scm barnum laziness octaveness
Checks the need for an accidental and a ‘restore’ accidental against a key signature. The laziness is the number of bars for which reminder accidentals are used (ie. if laziness is zero, we only cancel accidentals in the same bar; if laziness is three, we cancel accidentals up to three bars after they first appear. octaveness is either
'same-octave
or'any-octave
and it specifies whether accidentals should be canceled in different octaves.
- Function: ly:font-design-size font
Given the font metric font, return the design size, relative to the current output-scale.
- Function: ly:font-get-glyph font name
Return a stencil from font for the glyph named name. If the glyph is not available, return an empty stencil.
Note that this command can only be used to access glyphs from fonts loaded with
ly:system-font-load
; currently, this means either the Emmentaler or Aybabtu fonts, corresponding to the font encodingsfetaMusic
andfetaBraces
, respectively.
- Function: ly:font-glyph-name-to-charcode font name
Return the character code for glyph name in font.
Note that this command can only be used to access glyphs from fonts loaded with
ly:system-font-load
; currently, this means either the Emmentaler or Aybabtu fonts, corresponding to the font encodingsfetaMusic
andfetaBraces
, respectively.
- Function: ly:font-glyph-name-to-index font name
Return the index for name in font.
Note that this command can only be used to access glyphs from fonts loaded with
ly:system-font-load
; currently, this means either the Emmentaler or Aybabtu fonts, corresponding to the font encodingsfetaMusic
andfetaBraces
, respectively.
- Function: ly:font-index-to-charcode font index
Return the character code for index in font.
Note that this command can only be used to access glyphs from fonts loaded with
ly:system-font-load
; currently, this means either the Emmentaler or Aybabtu fonts, corresponding to the font encodingsfetaMusic
andfetaBraces
, respectively.
- Function: ly:font-magnification font
Given the font metric font, return the magnification, relative to the current output-scale.
- Function: ly:font-sub-fonts font
Given the font metric font of an OpenType font, return the names of the subfonts within font.
- Function: ly:format-output context
Given a global context in its final state, process it and return the
Music_output
object in its final state.
- Function: ly:get-all-function-documentation
Get a hash table with all LilyPond Scheme extension functions.
- Function: ly:get-glyph font index
Retrieve a stencil for the glyph numbered index in font.
Note that this command can only be used to access glyphs from fonts loaded with
ly:system-font-load
; currently, this means either the Emmentaler or Aybabtu fonts, corresponding to the font encodingsfetaMusic
andfetaBraces
, respectively.
- Function: ly:get-listened-event-classes
Return a list of all event classes that some translator listens to.
- Function: ly:grob-alist-chain grob global
Get an alist chain for grob grob, with global as the global default. If unspecified,
font-defaults
from the layout block is taken.
- Function: ly:grob-common-refpoint grob other axis
Find the common refpoint of grob and other for axis.
- Function: ly:grob-common-refpoint-of-array grob others axis
Find the common refpoint of grob and others (a grob-array) for axis.
- Function: ly:grob-extent grob refp axis
Get the extent in axis direction of grob relative to the grob refp.
- Function: ly:grob-object grob sym
Return the value of a pointer in grob g of property sym. It returns
'()
(end-of-list) if sym is undefined in g.
- Function: ly:grob-parent grob axis
Get the parent of grob. axis is 0 for the X-axis, 1 for the Y-axis.
- Function: ly:grob-property grob sym deflt
Return the value of a value in grob g of property sym. It returns
'()
(end-of-list) or deflt (if specified) if sym is undefined in g.
- Function: ly:grob-relative-coordinate grob refp axis
Get the coordinate in axis direction of grob relative to the grob refp.
- Function: ly:grob-robust-relative-extent grob refp axis
Get the extent in axis direction of grob relative to the grob refp, or
(0,0)
if empty.
- Function: ly:gulp-file name size
Read the file name, and return its contents in a string. The file is looked up using the search path.
- Function: ly:input-both-locations sip
Return input location in sip as
(file-name first-line first-column last-line last-column)
.
- Function: ly:input-file-line-char-column sip
Return input location in sip as
(file-name line char column)
.
- Function: ly:input-message sip msg rest
Print msg as a GNU compliant error message, pointing to the location in sip. msg is interpreted similar to
format
’s argument, using rest.
- Function: ly:interpret-music-expression mus ctx
Interpret the music expression mus in the global context ctx. The context is returned in its final state.
- Function: ly:interpret-stencil-expression expr func arg1 offset
Parse expr, feed bits to func with first arg arg1 having offset offset.
- Function: ly:item-break-dir it
The break status direction of item it.
-1
means end of line,0
unbroken, and1
beginning of line.
- Function: ly:lexer-keywords lexer
Return a list of
(KEY . CODE)
pairs, signifying the LilyPond reserved words list.
- Function: ly:make-book paper header scores
Make a
\book
of paper and header (which may be#f
as well) containing\scores
.
- Function: ly:make-duration length dotcount num den
length is the negative logarithm (base 2) of the duration: 1 is a half note, 2 is a quarter note, 3 is an eighth note, etc. The number of dots after the note is given by the optional argument dotcount.
The duration factor is optionally given by num and den.
A duration is a musical duration, i.e., a length of time described by a power of two (whole, half, quarter, etc.) and a number of augmentation dots.
- Function: ly:make-global-context output-def
Set up a global interpretation context, using the output block output_def. The context is returned.
- Function: ly:make-global-translator global
Create a translator group and connect it to the global context global. The translator group is returned.
- Function: ly:make-listener callback
Create a listener. Any time the listener hears an object, it will call callback with that object.
callback should take exactly one argument.
- Function: ly:make-moment n d gn gd
Create the rational number with main timing n/d, and optional grace timing gn/gd.
A moment is a point in musical time. It consists of a pair of rationals (m, g), where m is the timing for the main notes, and g the timing for grace notes. In absence of grace notes, g is zero.
- Function: ly:make-music props
Make a C++
Music
object and initialize it with props.This function is for internal use and is only called by
make-music
, which is the preferred interface for creating music objects.
- Function: ly:make-music-function signature func
Make a function to process music, to be used for the parser.
func
is the function, andsignature
describes its arguments.signature
is a list containing eitherly:music?
predicates or other type predicates.
- Function: ly:make-page-permission-marker symbol permission
Return page marker with page breaking and turning permissions.
- Function: ly:make-pango-description-string chain size
Make a
PangoFontDescription
string for the property alist chain at size size.
- Function: ly:make-paper-outputter port format
Create an outputter that evaluates within
output-
format, writing to port.
- Function: ly:make-pitch octave note alter
octave is specified by an integer, zero for the octave containing middle C. note is a number indexing the global default scale, with 0 corresponding to pitch C and 6 usually corresponding to pitch B. alter is a rational number of 200-cent whole tones for alteration.
- Function: ly:make-scale steps
Create a scale. The argument is a vector of rational numbers, each of which represents the number of 200 cent tones of a pitch above the tonic.
- Function: ly:make-simple-closure expr
Make a simple closure. expr should be form of
(func a1 A2 …)
, and will be invoked as(func delayed-arg a1 a2 …)
.
- Function: ly:make-stencil expr xext yext
Stencils are device independent output expressions. They carry two pieces of information:
- A specification of how to print this object. This specification is processed by the output backends, for example ‘scm/output-ps.scm’.
-
The vertical and horizontal extents of the object, given as pairs. If an extent is unspecified (or if you use
(1000 . -1000)
as its value), it is taken to be empty.
- Function: ly:make-stream-event cl proplist
Create a stream event of class cl with the given mutable property list.
- Function: ly:message str rest
A Scheme callable function to issue the message str. The message is formatted with
format
and rest.
- Function: ly:minimal-breaking pb
Break (pages and lines) the
Paper_book
object pb without looking for optimal spacing: stack as many lines on a page before moving to the next one.
- Function: ly:modules-lookup modules sym def
Look up sym in the list modules, returning the first occurence. If not found, return def or
#f
if def isn’t specified.
- Function: ly:music-length mus
Get the length of music expression mus and return it as a
Moment
object.
- Function: ly:music-mutable-properties mus
Return an alist containing the mutable properties of mus. The immutable properties are not available, since they are constant and initialized by the
make-music
function.
- Function: ly:music-property mus sym dfault
Get the property sym of music expression mus. If sym is undefined, return
'()
.
- Function: ly:note-head::stem-attachment font-metric glyph-name
Get attachment in font-metric for attaching a stem to notehead glyph-name.
- Function: ly:optimal-breaking pb
Optimally break (pages and lines) the
Paper_book
object pb to minimize badness in bother vertical and horizontal spacing.
- Function: ly:otf->cff otf-file-name
Convert the contents of an OTF file to a CFF file, returning it as a string.
- Function: ly:otf-font-glyph-info font glyph
Given the font metric font of an OpenType font, return the information about named glyph glyph (a string).
- Function: ly:otf-font-table-data font tag
Extract a table tag from font. Return empty string for non-existent tag.
- Function: ly:output-def-lookup pap sym def
Look up sym in the pap output definition (e.g.,
\paper
). Return the value or def (which defaults to'()
) if undefined.
- Function: ly:page-turn-breaking pb
Optimally break (pages and lines) the
Paper_book
object pb such that page turns only happen in specified places, returning its pages.
- Function: ly:pango-font-physical-fonts f
Return alist of
(ps-name file-name font-index)
lists for Pango font f.
- Function: ly:paper-get-font paper-smob chain
Return a font metric satisfying the font-qualifiers in the alist chain chain. (An alist chain is a list of alists, containing grob properties.)
- Function: ly:paper-score-paper-systems paper-score
Return vector of
paper_system
objects from paper-score.
- Function: ly:paper-system-minimum-distance sys1 sys2
Measure the minimum distance between these two paper-systems, using their stored skylines if possible and falling back to their extents otherwise.
- Function: ly:parser-lookup parser-smob symbol
Look up symbol in parser-smob’s module. Return
'()
if not defined.
- Function: ly:parser-parse-string parser-smob ly-code
Parse the string ly-code with parser-smob. Upon failure, throw
ly-file-failed
key.
- Function: ly:parser-set-note-names parser names
Replace current note names in parser. names is an alist of symbols. This only has effect if the current mode is notes.
- Function: ly:pitch-diff pitch root
Return pitch delta such that pitch transposed by delta equals root.
- Function: ly:pitch-transpose p delta
Transpose p by the amount delta, where delta is relative to middle C.
- Function: ly:position-on-line? sg spos
Return whether pos is on a line of the staff associated with the the grob sg (even on an extender line).
- Function: ly:programming-error str rest
A Scheme callable function to issue the internal warning str. The message is formatted with
format
and rest.
- Function: ly:progress str rest
A Scheme callable function to print progress str. The message is formatted with
format
and rest.
- Function: ly:property-lookup-stats sym
Return hash table with a property access corresponding to sym. Choices are
prob
,grob
, andcontext
.
- Function: ly:relative-group-extent elements common axis
Determine the extent of elements relative to common in the axis direction.
- Function: ly:round-filled-box xext yext blot
Make a
Stencil
object that prints a black box of dimensions xext, yext and roundness blot.
- Function: ly:round-filled-polygon points blot
Make a
Stencil
object that prints a black polygon with corners at the points defined by points (list of coordinate pairs) and roundness blot.
- Function: ly:run-translator mus output-def
Process mus according to output-def. An interpretation context is set up, and mus is interpreted with it. The context is returned in its final state.
Optionally, this routine takes an object-key to to uniquely identify the score block containing it.
- Function: ly:score-embedded-format score layout
Run score through layout (an output definition) scaled to correct output-scale already, returning a list of layout-lines. This function takes an optional
Object_key
argument.
- Function: ly:set-default-scale scale
Set the global default scale. This determines the tuning of pitches with no accidentals or key signatures. The first pitch is C. Alterations are calculated relative to this scale. The number of pitches in this scale determines the number of scale steps that make up an octave. Usually the 7-note major scale.
- Function: ly:set-grob-modification-callback cb
Specify a procedure that will be called every time LilyPond modifies a grob property. The callback will receive as arguments the grob that is being modified, the name of the C++ file in which the modification was requested, the line number in the C++ file in which the modification was requested, the name of the function in which the modification was requested, the property to be changed, and the new value for the property.
- Function: ly:set-middle-C! context
Set the
middleCPosition
variable in context based on the variablesmiddleCClefPosition
and middleCOffset.
- Function: ly:set-property-cache-callback cb
Specify a procedure that will be called whenever lilypond calculates a callback function and caches the result. The callback will receive as arguments the grob whose property it is, the name of the property, the name of the callback that calculated the property, and the new (cached) value of the property.
- Function: ly:solve-spring-rod-problem springs rods length ragged
Solve a spring and rod problem for count objects, that are connected by count-1 springs, and an arbitrary number of rods. count is implicitly given by springs and rods. The springs argument has the format
(ideal, inverse_hook)
and rods is of the form(idx1, idx2, distance)
.length is a number, ragged a boolean.
The function returns a list containing the force (positive for stretching, negative for compressing and
#f
for non-satisfied constraints) followed by spring-count+1 positions of the objects.
- Function: ly:spanner-bound slur dir
Get one of the bounds of slur. dir is
-1
for left, and1
for right.
- Function: ly:staff-symbol-line-thickness grob
Returns the line-thickness of the staff associated with grob.
- Function: ly:start-environment
Return the environment (a list of strings) that was in effect at program start.
- Function: ly:stencil-aligned-to stil axis dir
Align stil using its own extents. dir is a number.
-1
and1
are left and right, respectively. Other values are interpolated (so0
means the center).
- Function: ly:stencil-combine-at-edge first axis direction second padding minimum
Construct a stencil by putting second next to first. axis can be 0 (x-axis) or 1 (y-axis). direction can be -1 (left or down) or 1 (right or up). The stencils are juxtaposed with padding as extra space. If this puts the reference points closer than minimum, they are moved by the latter amount. first and second may also be
'()
or#f
.
- Function: ly:stencil-extent stil axis
Return a pair of numbers signifying the extent of stil in axis direction (
0
or1
for x and y axis, respectively).
- Function: ly:stencil-rotate stil angle x y
Return a stencil stil rotated angle degrees around the relative offset (x, y). E.g. an offset of (-1, 1) will rotate the stencil around the left upper corner.
- Function: ly:stencil-rotate-absolute stil angle x y
Return a stencil stil rotated angle degrees around point (x, y), given in absolute coordinates.
- Function: ly:stencil-translate stil offset
Return a stil, but translated by offset (a pair of numbers).
- Function: ly:stencil-translate-axis stil amount axis
Return a copy of stil but translated by amount in axis direction.
- Function: ly:system-font-load name
Load the OpenType system font ‘name.otf’. Fonts loaded with this command must contain three additional SFNT font tables called
LILC
,LILF
, andLILY
, needed for typesetting musical elements. Currently, only the Emmentaler and the Aybabtu fonts fulfill these requirements.Note that only
ly:font-get-glyph
and derived code (like\lookup
) can access glyphs from the system fonts; text strings are handled exclusively via the Pango interface.
- Function: ly:system-stretch system amount-scm
Stretch the system vertically by the given amount. This must be called before the system is drawn (for example with
ly:system-print
).
- Function: ly:text-dimension font text
Given the font metric in font and the string text, compute the extents of that text in that font. The return value is a pair of number-pairs.
- Function: ly:text-interface::interpret-markup
Convert a text markup into a stencil. Takes three arguments, layout, props, and markup.
layout is a
\layout
block; it may be obtained from a grob withly:grob-layout
. props is an alist chain, i.e. a list of alists. This is typically obtained with(ly:grob-alist-chain (ly:layout-lookup layout 'text-font-defaults))
. markup is the markup text to be processed.
- Function: ly:translator-name trans
Return the type name of the translator object trans. The name is a symbol.
- Function: ly:ttf->pfa ttf-file-name idx
Convert the contents of a TrueType font file to PostScript Type 42 font, returning it as a string. The optional idx argument is useful for TrueType collections (TTC) only; it specifies the font index within the TTC. The default value of idx is 0.
- Function: ly:ttf-ps-name ttf-file-name idx
Extract the PostScript name from a TrueType font. The optional idx argument is useful for TrueType collections (TTC) only; it specifies the font index within the TTC. The default value of idx is 0.
- Function: ly:warning str rest
A Scheme callable function to issue the warning
str
. The message is formatted withformat
andrest
.
[ << Notation manual tables ] | [Top][Contents][Index][ ? ] | [ Cheat sheet >> ] | ||
[ < Identifiers ] | [ Up : Notation manual tables ] | [ Cheat sheet > ] |