lilypond-internals: Scheme functions
4 Scheme functions
******************
-- Function: ly:add-context-mod contextmods modification
Adds the given context MODIFICATION to the list CONTEXTMODS of
context modifications.
-- Function: ly:add-file-name-alist alist
Add mappings for error messages from ALIST.
-- Function: ly:add-interface iface desc props
Add a new grob interface. IFACE is the interface name, DESC is the
interface description, and PROPS is the list of user-settable
properties for the interface.
-- 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:add-option sym val description
Add a program option SYM. VAL is the default value and DESCRIPTION
is a string description.
-- Function: ly:all-grob-interfaces
Return the hash table with all grob interface descriptions.
-- Function: ly:all-options
Get all option settings in an alist.
-- Function: ly:all-stencil-expressions
Return all symbols recognized as stencil expressions.
-- Function: ly:assoc-get key alist default-value strict-checking
Return value if KEY in ALIST, else DEFAULT-VALUE (or ‘#f’ if not
specified). If STRICT-CHECKING is set to ‘#t’ and KEY is not in
ALIST, a programming_error is output.
-- Function: ly:axis-group-interface::add-element grob grob-element
Set GROB the parent of GROB-ELEMENT on all axes of GROB.
-- Function: ly:basic-progress str rest
A Scheme callable function to issue a basic progress message STR.
The message is formatted with ‘format’ and REST.
-- Function: ly:beam-score-count
count number of beam scores.
-- Function: ly:book? x
Is X a ‘Book’ object?
-- Function: ly:book-add-bookpart! book-smob book-part
Add BOOK-PART to BOOK-SMOB book part list.
-- Function: ly:book-add-score! book-smob score
Add SCORE to BOOK-SMOB score list.
-- Function: ly:book-book-parts book
Return book parts in BOOK.
-- Function: ly:book-header book
Return header in BOOK.
-- Function: ly:book-paper book
Return paper in BOOK.
-- 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:book-scores book
Return scores in BOOK.
-- Function: ly:book-set-header! book module
Set the book header.
-- Function: ly:box? x
Is X a ‘Box’ object?
-- Function: ly:bp num
NUM bigpoints (1/72th inch).
-- 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:broadcast disp ev
Send the stream event EV to the dispatcher DISP.
-- Function: ly:camel-case->lisp-identifier name-sym
Convert ‘FooBar_Bla’ to ‘foo-bar-bla’ style symbol.
-- Function: ly:chain-assoc-get key achain default-value
strict-checking
Return value for KEY from a list of alists ACHAIN. If no entry is
found, return DEFAULT-VALUE or ‘#f’ if DEFAULT-VALUE is not
specified. With STRICT-CHECKING set to ‘#t’, a programming_error
is output in such cases.
-- Function: ly:check-expected-warnings
Check whether all expected warnings have really been triggered.
-- Function: ly:cm num
NUM cm.
-- Function: ly:command-line-code
The Scheme code specified on command-line with ‘-e’.
-- Function: ly:command-line-options
The Scheme options specified on command-line with ‘-d’.
-- Function: ly:connect-dispatchers to from
Make the dispatcher TO listen to events from FROM.
-- Function: ly:context? x
Is X a ‘Context’ object?
-- Function: ly:context-current-moment context
Return the current moment of CONTEXT.
-- Function: ly:context-def? x
Is X a ‘Context_def’ object?
-- Function: ly:context-def-lookup def sym val
Return the value of SYM in context definition DEF (e.g., ‘\Voice’).
If no value is found, return VAL or ‘'()’ if VAL is undefined. SYM
can be any of ‘default-child’, ‘consists’, ‘description’,
‘aliases’, ‘accepts’, ‘property-ops’, ‘context-name’, ‘group-type’.
-- Function: ly:context-def-modify def mod
Return the result of applying the context-mod MOD to the context
definition DEF. Does not change DEF.
-- Function: ly:context-event-source context
Return ‘event-source’ of context CONTEXT.
-- 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 string ‘one’.
-- Function: ly:context-mod? x
Is X a ‘Context_mod’ object?
-- Function: ly:context-mod-apply! context mod
Apply the context modification MOD to CONTEXT.
-- Function: ly:context-name context
Return the name of CONTEXT, i.e., for ‘\context Voice = "one" ...’
return the symbol ‘Voice’.
-- Function: ly:context-now context
Return ‘now-moment’ of context CONTEXT.
-- Function: ly:context-parent context
Return the parent of CONTEXT, ‘#f’ if none.
-- Function: ly:context-property context sym def
Return the value for property SYM in CONTEXT. If DEF is given, and
property value is ‘'()’, return DEF.
-- 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:context-unset-property context name
Unset value of property NAME in context CONTEXT.
-- Function: ly:debug str rest
A Scheme callable function to issue a debug message STR. The
message is formatted with ‘format’ and REST.
-- Function: ly:default-scale
Get the global default scale.
-- Function: ly:dimension? d
Return D as a number. Used to distinguish length variables from
normal numbers.
-- Function: ly:dir? s
Is S a direction? Valid directions are ‘-1’, ‘0’, or ‘1’, where
‘-1’ represents left or down, ‘1’ represents right or up, and ‘0’
represents a neutral direction.
-- Function: ly:dispatcher? x
Is X a ‘Dispatcher’ object?
-- Function: ly:duration? x
Is X a ‘Duration’ object?
-- Function: ly:duration<? p1 p2
Is P1 shorter than P2?
-- Function: ly:duration->string dur
Convert DUR to a string.
-- Function: ly:duration-dot-count dur
Extract the dot count from DUR.
-- Function: ly:duration-factor dur
Extract the compression factor from DUR. Return it as a pair.
-- Function: ly:duration-length dur
The length of the duration as a ‘moment’.
-- Function: ly:duration-log dur
Extract the duration log from DUR.
-- Function: ly:duration-scale dur
Extract the compression factor from DUR. Return it as a rational.
-- Function: ly:effective-prefix
Return effective prefix.
-- Function: ly:encode-string-for-pdf str
Encode the given string to either Latin1 (which is a subset of the
PDFDocEncoding) or if that’s not possible to full UTF-16BE with
Byte-Order-Mark (BOM).
-- Function: ly:engraver-announce-end-grob engraver grob cause
Announce the end of a grob (i.e., the end of a spanner) originating
from given ENGRAVER instance, with GROB being a grob. CAUSE should
either be another grob or a music event.
-- Function: ly:engraver-make-grob engraver grob-name cause
Create a grob originating from given ENGRAVER instance, with given
GROB-NAME, a symbol. CAUSE should either be another grob or a
music event.
-- 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? obj
Is OBJ a proper (non-rhythmic) event object?
-- Function: ly:event-deep-copy m
Copy M and all sub expressions of M.
-- Function: ly:event-property sev sym val
Get the property SYM of stream event SEV. If SYM is undefined,
return VAL or ‘'()’ if VAL is not specified.
-- Function: ly:event-set-property! ev sym val
Set property SYM in event EV to VAL.
-- Function: ly:expand-environment str
Expand ‘$VAR’ and ‘${VAR}’ in STR.
-- Function: ly:expect-warning str rest
A Scheme callable function to register a warning to be expected and
subsequently suppressed. If the warning is not encountered, a
warning about the missing warning will be shown. The message
should be translated with ‘(_ ...)’ and changing parameters given
after the format string.
-- Function: ly:find-file name
Return the absolute file name of NAME, or ‘#f’ if not found.
-- Function: ly:font-config-add-directory dir
Add directory DIR to FontConfig.
-- Function: ly:font-config-add-font font
Add font FONT to FontConfig.
-- Function: ly:font-config-display-fonts
Dump a list of all fonts visible to FontConfig.
-- Function: ly:font-config-get-font-file name
Get the file for font NAME.
-- Function: ly:font-design-size font
Given the font metric FONT, return the design size, relative to the
current output-scale.
-- Function: ly:font-file-name font
Given the font metric FONT, return the corresponding file name.
-- 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 Emmentaler-Brace fonts, corresponding to the font
encodings ‘fetaMusic’ and ‘fetaBraces’, 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 Emmentaler-Brace fonts, corresponding to the font
encodings ‘fetaMusic’ and ‘fetaBraces’, 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 Emmentaler-Brace fonts, corresponding to the font
encodings ‘fetaMusic’ and ‘fetaBraces’, 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 Emmentaler-Brace fonts, corresponding to the font
encodings ‘fetaMusic’ and ‘fetaBraces’, respectively.
-- Function: ly:font-magnification font
Given the font metric FONT, return the magnification, relative to
the current output-scale.
-- Function: ly:font-metric? x
Is X a ‘Font_metric’ object?
-- Function: ly:font-name font
Given the font metric FONT, return the corresponding name.
-- 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 str rest
LilyPond specific format, supporting ‘~a’ and ‘~[0-9]f’. Basic
support for ‘~s’ is also provided.
-- 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-all-translators
Return a list of all translator objects that may be instantiated.
-- Function: ly:get-context-mods contextmod
Returns the list of context modifications stored in CONTEXTMOD.
-- Function: ly:get-option var
Get a global option setting.
-- Function: ly:get-spacing-spec from-scm to-scm
Return the spacing spec going between the two given grobs, FROM_SCM
and TO_SCM.
-- Function: ly:get-undead undead
Get back object from UNDEAD.
-- Function: ly:gettext original
A Scheme wrapper function for ‘gettext’.
-- Function: ly:grob? x
Is X a ‘Grob’ object?
-- 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-array? x
Is X a ‘Grob_array’ object?
-- Function: ly:grob-array->list grob-arr
Return the elements of GROB-ARR as a Scheme list.
-- Function: ly:grob-array-length grob-arr
Return the length of GROB-ARR.
-- Function: ly:grob-array-ref grob-arr index
Retrieve the INDEXth element of GROB-ARR.
-- Function: ly:grob-basic-properties grob
Get the immutable properties of GROB.
-- Function: ly:grob-chain-callback grob proc sym
Find the callback that is stored as property SYM of grob GROB and
chain PROC to the head of this, meaning that it is called using
GROB and the previous callback’s result.
-- 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-default-font grob
Return the default font for grob GROB.
-- Function: ly:grob-extent grob refp axis
Get the extent in AXIS direction of GROB relative to the grob REFP.
-- Function: ly:grob-get-vertical-axis-group-index grob
Get the index of the vertical axis group the grob GROB belongs to;
return ‘-1’ if none is found.
-- Function: ly:grob-interfaces grob
Return the interfaces list of grob GROB.
-- Function: ly:grob-layout grob
Get ‘\layout’ definition from grob GROB.
-- Function: ly:grob-object grob sym
Return the value of a pointer in grob GROB of property SYM. It
returns ‘'()’ (end-of-list) if SYM is undefined in GROB.
-- Function: ly:grob-original grob
Return the unbroken original grob of GROB.
-- 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-pq<? a b
Compare two grob priority queue entries. This is an internal
function.
-- Function: ly:grob-properties grob
Get the mutable properties of GROB.
-- Function: ly:grob-property grob sym val
Return the value for property SYM of GROB. If no value is found,
return VAL or ‘'()’ if VAL is not specified.
-- Function: ly:grob-property-data grob sym
Return the value for property SYM of GROB, but do not process
callbacks.
-- Function: ly:grob-pure-height grob refp beg end val
Return the pure height of GROB given refpoint REFP. If no value is
found, return VAL or ‘'()’ if VAL is not specified.
-- Function: ly:grob-pure-property grob sym beg end val
Return the pure value for property SYM of GROB. If no value is
found, return VAL or ‘'()’ if VAL is not specified.
-- 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:grob-script-priority-less a b
Compare two grobs by script priority. For internal use.
-- Function: ly:grob-set-nested-property! grob symlist val
Set nested property SYMLIST in grob GROB to value VAL.
-- Function: ly:grob-set-object! grob sym val
Set SYM in grob GROB to value VAL.
-- Function: ly:grob-set-parent! grob axis parent-grob
Set PARENT-GROB the parent of grob GROB in axis AXIS.
-- Function: ly:grob-set-property! grob sym val
Set SYM in grob GROB to value VAL.
-- Function: ly:grob-staff-position sg
Return the Y-position of SG relative to the staff.
-- Function: ly:grob-suicide! grob
Kill GROB.
-- Function: ly:grob-system grob
Return the system grob of GROB.
-- Function: ly:grob-translate-axis! grob d a
Translate GROB on axis A over distance D.
-- Function: ly:grob-vertical<? a b
Does A lie above B on the page?
-- Function: ly:gulp-file name size
Read SIZE characters from the file NAME, and return its contents in
a string. If SIZE is undefined, the entire file is read. The file
is looked up using the search path.
-- Function: ly:hash-table-keys tab
Return a list of keys in TAB.
-- Function: ly:inch num
NUM inches.
-- 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-location? x
Is X an ‘input-location’?
-- 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:input-warning sip msg rest
Print MSG as a GNU compliant warning 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:intlog2 d
The 2-logarithm of 1/D.
-- Function: ly:item? g
Is G an ‘Item’ object?
-- Function: ly:item-break-dir it
The break status direction of item IT. ‘-1’ means end of line,
‘0’ unbroken, and ‘1’ beginning of line.
-- Function: ly:iterator? x
Is X a ‘Music_iterator’ object?
-- Function: ly:lexer-keywords lexer
Return a list of ‘(KEY . CODE)’ pairs, signifying the LilyPond
reserved words list.
-- Function: ly:lily-lexer? x
Is X a ‘Lily_lexer’ object?
-- Function: ly:lily-parser? x
Is X a ‘Lily_parser’ object?
-- Function: ly:listened-event-class? disp cl
Does DISP listen to any event type in the list CL?
-- Function: ly:listened-event-types disp
Return a list of all event types that DISP listens to.
-- Function: ly:listener? x
Is X a ‘Listener’ object?
-- 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-book-part scores
Make a ‘\bookpart’ containing ‘\scores’.
-- Function: ly:make-context-mod mod-list
Creates a context modification, optionally initialized via the list
of modifications MOD-LIST.
-- Function: ly:make-dispatcher
Return a newly created dispatcher.
-- 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 integers NUM and DEN,
alternatively by a single rational number.
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 m g gn gd
Create the moment with rational main timing M, and optional grace
timing G.
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.
For compatibility reasons, it is possible to write two numbers
specifying numerator and denominator instead of the rationals.
These forms cannot be mixed, and the two-argument form is
disambiguated by the sign of the second argument: if it is
positive, it can only be a denominator and not a grace timing.
-- 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, and SIGNATURE describes its arguments.
SIGNATURE’s cdr is a list containing either ‘ly:music?’ predicates
or other type predicates. Its car is the syntax function to call.
-- Function: ly:make-music-relative! music pitch
Make MUSIC relative to PITCH, return final pitch.
-- Function: ly:make-output-def
Make an output definition.
-- Function: ly:make-page-label-marker label
Return page marker with label LABEL.
-- 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.
Optional ALTER is a rational number of 200-cent whole tones for
alteration.
-- Function: ly:make-prob type init rest
Create a ‘Prob’ object.
-- 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-score music
Return score with MUSIC encapsulated in it.
-- 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-spring ideal min-dist
Make a spring. IDEAL is the ideal distance of the spring, and
MIN-DIST is the minimum distance.
-- Function: ly:make-stencil expr xext yext
Stencils are device independent output expressions. They carry two
pieces of information:
1. A specification of how to print this object. This
specification is processed by the output backends, for example
‘scm/output-ps.scm’.
2. The vertical and horizontal extents of the object, given as
pairs. If an extent is unspecified (or if you use
‘empty-interval’ 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:make-undead object
This packages OBJECT in a manner that keeps it from triggering
"Parsed object should be dead" messages.
-- Function: ly:make-unpure-pure-container unpure pure
Make an unpure-pure container. UNPURE should be an unpure
expression, and PURE should be a pure expression. If PURE is
omitted, the value of UNPURE will be used twice, except that a
callback is given two extra arguments that are ignored for the sake
of pure calculations.
-- 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:mm num
NUM mm.
-- Function: ly:module->alist mod
Dump the contents of module MOD as an alist.
-- Function: ly:module-copy dest src
Copy all bindings from module SRC into DEST.
-- 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:moment? x
Is X a ‘Moment’ object?
-- Function: ly:moment<? a b
Compare two moments.
-- Function: ly:moment-add a b
Add two moments.
-- Function: ly:moment-div a b
Divide two moments.
-- Function: ly:moment-grace mom
Extract grace timing as a rational number from MOM.
-- Function: ly:moment-grace-denominator mom
Extract denominator from grace timing.
-- Function: ly:moment-grace-numerator mom
Extract numerator from grace timing.
-- Function: ly:moment-main mom
Extract main timing as a rational number from MOM.
-- Function: ly:moment-main-denominator mom
Extract denominator from main timing.
-- Function: ly:moment-main-numerator mom
Extract numerator from main timing.
-- Function: ly:moment-mod a b
Modulo of two moments.
-- Function: ly:moment-mul a b
Multiply two moments.
-- Function: ly:moment-sub a b
Subtract two moments.
-- Function: ly:music? obj
Is OBJ a music object?
-- Function: ly:music-compress m factor
Compress music object M by moment FACTOR.
-- Function: ly:music-deep-copy m
Copy M and all sub expressions of M. M may be an arbitrary type;
cons cells and music are copied recursively.
-- Function: ly:music-duration-compress mus fact
Compress MUS by factor FACT, which is a ‘Moment’.
-- Function: ly:music-duration-length mus
Extract the duration field from MUS and return the length.
-- Function: ly:music-function? x
Is X a ‘music-function’?
-- Function: ly:music-function-extract x
Return the Scheme function inside X.
-- Function: ly:music-function-signature x
Return the function signature inside X.
-- Function: ly:music-length mus
Get the length of music expression MUS and return it as a ‘Moment’
object.
-- Function: ly:music-list? lst
Is LST a list of music objects?
-- 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-output? x
Is X a ‘Music_output’ object?
-- Function: ly:music-property mus sym val
Return the value for property SYM of music expression MUS. If no
value is found, return VAL or ‘'()’ if VAL is not specified.
-- Function: ly:music-set-property! mus sym val
Set property SYM in music expression MUS to VAL.
-- Function: ly:music-transpose m p
Transpose M such that central C is mapped to P. Return M.
-- Function: ly:note-column-accidentals note-column
Return the ‘AccidentalPlacement’ grob from NOTE-COLUMN if any, or
‘SCM_EOL’ otherwise.
-- Function: ly:note-column-dot-column note-column
Return the ‘DotColumn’ grob from NOTE-COLUMN if any, or ‘SCM_EOL’
otherwise.
-- 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:number->string s
Convert S to a string without generating many decimals.
-- Function: ly:one-line-breaking pb
Put each score on a single line, and put each line on its own page.
The paper-width setting will be modified so that every page will be
wider than the widest line.
-- 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:option-usage port
Print ‘ly:set-option’ usage. Optional PORT argumentfor the
destination defaults to current output port.
-- 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? font
Is FONT an OpenType font?
-- 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:otf-glyph-count font
Return the number of glyphs in FONT.
-- Function: ly:otf-glyph-list font
Return a list of glyph names for FONT.
-- Function: ly:output-def? def
Is DEF an output definition?
-- Function: ly:output-def-clone def
Clone output definition DEF.
-- Function: ly:output-def-lookup def sym val
Return the value of SYM in output definition DEF (e.g., ‘\paper’).
If no value is found, return VAL or ‘'()’ if VAL is undefined.
-- Function: ly:output-def-parent def
Return the parent output definition of DEF.
-- Function: ly:output-def-scope def
Return the variable scope inside DEF.
-- Function: ly:output-def-set-variable! def sym val
Set an output definition DEF variable SYM to VAL.
-- Function: ly:output-description output-def
Return the description of translators in OUTPUT-DEF.
-- Function: ly:output-find-context-def output-def context-name
Return an alist of all context defs (matching CONTEXT-NAMEif given)
in OUTPUT-DEF.
-- Function: ly:output-formats
Formats passed to ‘--format’ as a list of strings, used for the
output.
-- Function: ly:outputter-close outputter
Close port of OUTPUTTER.
-- Function: ly:outputter-dump-stencil outputter stencil
Dump stencil EXPR onto OUTPUTTER.
-- Function: ly:outputter-dump-string outputter str
Dump STR onto OUTPUTTER.
-- Function: ly:outputter-module outputter
Return output module of OUTPUTTER.
-- Function: ly:outputter-output-scheme outputter expr
Eval EXPR in module of OUTPUTTER.
-- Function: ly:outputter-port outputter
Return output port for OUTPUTTER.
-- Function: ly:page-marker? x
Is X a ‘Page_marker’ object?
-- 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? f
Is F a pango font?
-- Function: ly:pango-font-physical-fonts f
Return alist of ‘(ps-name file-name font-index)’ lists for Pango
font F.
-- Function: ly:paper-book? x
Is X a ‘Paper_book’ object?
-- Function: ly:paper-book-header pb
Return the header definition (‘\header’) in ‘Paper_book’ object PB.
-- Function: ly:paper-book-pages pb
Return pages in ‘Paper_book’ object PB.
-- Function: ly:paper-book-paper pb
Return the paper output definition (‘\paper’) in ‘Paper_book’
object PB.
-- Function: ly:paper-book-performances pb
Return performances in ‘Paper_book’ object PB.
-- Function: ly:paper-book-scopes pb
Return scopes in ‘Paper_book’ object PB.
-- Function: ly:paper-book-systems pb
Return systems in ‘Paper_book’ object PB.
-- Function: ly:paper-fonts def
Return a list containing the fonts from output definition DEF
(e.g., ‘\paper’).
-- Function: ly:paper-get-font def chain
Find a font metric in output definition DEF satisfying the
font-qualifiers in alist chain CHAIN, and return it. (An alist
chain is a list of alists, containing grob properties.)
-- Function: ly:paper-get-number def sym
Return the value of variable SYM in output definition DEF as a
double.
-- Function: ly:paper-outputscale def
Return the output-scale for output definition DEF.
-- Function: ly:paper-score-paper-systems paper-score
Return vector of ‘paper_system’ objects from PAPER-SCORE.
-- Function: ly:paper-system? obj
Is OBJ a C++ ‘Prob’ object of type ‘paper-system’?
-- 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:parse-file name
Parse a single ‘.ly’ file. Upon failure, throw ‘ly-file-failed’
key.
-- Function: ly:parse-string-expression parser-smob ly-code filename
line
Parse the string LY-CODE with PARSER-SMOB. Return the contained
music expression. FILENAME and LINE are optional source
indicators.
-- Function: ly:parsed-undead-list!
Return the list of objects that have been found live that should
have been dead, and clear that list.
-- Function: ly:parser-clear-error parser
Clear the error flag for the parser.
-- Function: ly:parser-clone parser-smob closures location
Return a clone of PARSER-SMOB. An association list of port
positions to closures can be specified in CLOSURES in order to have
‘$’ and ‘#’ interpreted in their original lexical environment. If
LOCATION is a valid location, it becomes the source of all music
expressions inside.
-- Function: ly:parser-define! parser-smob symbol val
Bind SYMBOL to VAL in PARSER-SMOB’s module.
-- Function: ly:parser-error parser msg input
Display an error message and make the parser fail.
-- Function: ly:parser-has-error? parser
Does PARSER have an error flag?
-- Function: ly:parser-include-string parser-smob ly-code
Include the string LY-CODE into the input stream for PARSER-SMOB.
Can only be used in immediate Scheme expressions (‘$’ instead of
‘#’).
-- Function: ly:parser-lexer parser-smob
Return the lexer for PARSER-SMOB.
-- Function: ly:parser-lookup parser-smob symbol
Look up SYMBOL in PARSER-SMOB’s module. Return ‘'()’ if not
defined.
-- Function: ly:parser-output-name parser
Return the base name of the output file.
-- 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:performance-write performance filename
Write PERFORMANCE to FILENAME.
-- Function: ly:pfb->pfa pfb-file-name
Convert the contents of a Type 1 font in PFB format to PFA format.
-- Function: ly:pitch? x
Is X a ‘Pitch’ object?
-- Function: ly:pitch<? p1 p2
Is P1 lexicographically smaller than P2?
-- Function: ly:pitch-alteration pp
Extract the alteration from pitch PP.
-- Function: ly:pitch-diff pitch root
Return pitch DELTA such that PITCH transposed by DELTA equals ROOT.
-- Function: ly:pitch-negate p
Negate P.
-- Function: ly:pitch-notename pp
Extract the note name from pitch PP.
-- Function: ly:pitch-octave pp
Extract the octave from pitch PP.
-- Function: ly:pitch-quartertones pp
Calculate the number of quarter tones of PP from middle C.
-- Function: ly:pitch-semitones pp
Calculate the number of semitones of PP from middle C.
-- Function: ly:pitch-steps p
Number of steps counted from middle C of the pitch P.
-- Function: ly:pitch-tones pp
Calculate the number of tones of PP from middle C as a rational
number.
-- Function: ly:pitch-transpose p delta
Transpose P by the amount DELTA, where DELTA is relative to
middle C.
-- Function: ly:pointer-group-interface::add-grob grob sym grob-element
Add GROB-ELEMENT to GROB’s SYM grob array.
-- Function: ly:position-on-line? sg spos
Return whether SPOS is on a line of the staff associated with the
grob SG (even on an extender line).
-- Function: ly:prob? x
Is X a ‘Prob’ object?
-- Function: ly:prob-immutable-properties prob
Retrieve an alist of immutable properties.
-- Function: ly:prob-mutable-properties prob
Retrieve an alist of mutable properties.
-- Function: ly:prob-property prob sym val
Return the value for property SYM of Prob object PROB. If no value
is found, return VAL or ‘'()’ if VAL is not specified.
-- Function: ly:prob-property? obj sym
Is boolean prop SYM of SYM set?
-- Function: ly:prob-set-property! obj sym value
Set property SYM of OBJ to VALUE.
-- Function: ly:prob-type? obj type
Is OBJ the specified prob-type?
-- 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’, and ‘context’.
-- Function: ly:protects
Return hash of protected objects.
-- Function: ly:pt num
NUM printer points.
-- Function: ly:register-stencil-expression symbol
Add SYMBOL as head of a stencil expression.
-- Function: ly:relative-group-extent elements common axis
Determine the extent of ELEMENTS relative to COMMON in the AXIS
direction.
-- Function: ly:reset-all-fonts
Forget all about previously loaded fonts.
-- 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? x
Is X a ‘Score’ object?
-- Function: ly:score-add-output-def! score def
Add an output definition DEF to SCORE.
-- 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.
-- Function: ly:score-error? score
Was there an error in the score?
-- Function: ly:score-header score
Return score header.
-- Function: ly:score-music score
Return score music.
-- Function: ly:score-output-defs score
All output definitions in a score.
-- Function: ly:score-set-header! score module
Set the score header.
-- 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
variables ‘middleCClefPosition’ and ‘middleCOffset’.
-- Function: ly:set-option var val
Set a program option.
-- 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:simple-closure? clos
Is CLOS a simple closure?
-- Function: ly:skyline? x
Is X a ‘Skyline’ object?
-- Function: ly:skyline-empty? sky
Return whether SKY is empty.
-- Function: ly:skyline-pair? x
Is X a ‘Skyline_pair’ object?
-- Function: ly:slur-score-count
count number of slur scores.
-- Function: ly:smob-protects
Return LilyPond’s internal smob protection list.
-- 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:source-file? x
Is X a ‘Source_file’ object?
-- Function: ly:spanner? g
Is G a spanner object?
-- Function: ly:spanner-bound spanner dir
Get one of the bounds of SPANNER. DIR is ‘-1’ for left, and ‘1’
for right.
-- Function: ly:spanner-broken-into spanner
Return broken-into list for SPANNER.
-- Function: ly:spanner-set-bound! spanner dir item
Set grob ITEM as bound in direction DIR for SPANNER.
-- Function: ly:spawn command rest
Simple interface to g_spawn_sync STR. The error is formatted with
‘format’ and REST.
-- Function: ly:spring? x
Is X a ‘Spring’ object?
-- Function: ly:spring-set-inverse-compress-strength! spring strength
Set the inverse compress STRENGTH of SPRING.
-- Function: ly:spring-set-inverse-stretch-strength! spring strength
Set the inverse stretch STRENGTH of SPRING.
-- Function: ly:staff-symbol-line-thickness grob
Returns the ‘line-thickness’ of the staff associated with GROB.
-- Function: ly:staff-symbol-staff-radius grob
Returns the radius of the staff associated with GROB.
-- Function: ly:staff-symbol-staff-space grob
Returns the ‘staff-space’ 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:stderr-redirect file-name mode
Redirect stderr to FILE-NAME, opened with MODE.
-- Function: ly:stencil? x
Is X a ‘Stencil’ object?
-- Function: ly:stencil-add args
Combine stencils. Takes any number of arguments.
-- Function: ly:stencil-aligned-to stil axis dir
Align STIL using its own extents. DIR is a number. ‘-1’ and ‘1’
are left and right, respectively. Other values are interpolated
(so ‘0’ means the center).
-- Function: ly:stencil-combine-at-edge first axis direction second
padding
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. FIRST and SECOND may also be ‘'()’ or ‘#f’.
-- Function: ly:stencil-empty? stil axis
Return whether STIL is empty. If an optional AXIS is supplied, the
emptiness check is restricted to that axis.
-- Function: ly:stencil-expr stil
Return the expression of STIL.
-- Function: ly:stencil-extent stil axis
Return a pair of numbers signifying the extent of STIL in AXIS
direction (‘0’ or ‘1’ for x and y axis, respectively).
-- Function: ly:stencil-fonts s
Analyze S, and return a list of fonts used in S.
-- Function: ly:stencil-in-color stc r g b
Put STC in a different color.
-- 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-scale stil x y
Scale STIL using the horizontal and vertical scaling factors X and
Y.
-- Function: ly:stencil-stack first axis direction second padding
mindist
Construct a stencil by stacking 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. FIRST and SECOND may also be ‘'()’ or ‘#f’. As opposed to
‘ly:stencil-combine-at-edge’, metrics are suited for successively
accumulating lines of stencils. Also, SECOND stencil is drawn
last.
If MINDIST is specified, reference points are placed apart at least
by this distance. If either of the stencils is spacing, PADDING
and MINDIST do not apply.
-- 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:stream-event? obj
Is ‘OBJ’ a ‘Stream_event’ object?
-- Function: ly:string-percent-encode str
Encode all characters in string STR with hexadecimal percent escape
sequences, with the following exceptions: characters ‘-’, ‘.’, ‘/’,
and ‘_’; and characters in ranges ‘0-9’, ‘A-Z’, and ‘a-z’.
-- Function: ly:string-substitute a b s
Replace string A by string B in string S.
-- 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’, and ‘LILY’, needed for typesetting musical
elements. Currently, only the Emmentaler and the Emmentaler-Brace
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: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 with
‘ly:grob-layout’. PROPS is an alist chain, i.e. a list of alists.
This is typically obtained with ‘(ly:grob-alist-chain grob
(ly:output-def-lookup layout 'text-font-defaults))’. MARKUP is the
markup text to be processed.
-- Function: ly:translate-cpp-warning-scheme str
Translates a string in C++ printf format and modifies it to use it
for scheme formatting.
-- Function: ly:translator? x
Is X a ‘Translator’ object?
-- Function: ly:translator-context trans
Return the context of the translator object TRANS.
-- Function: ly:translator-description me
Return an alist of properties of translator ME.
-- Function: ly:translator-group? x
Is X a ‘Translator_group’ object?
-- Function: ly:translator-name trans
Return the type name of the translator object TRANS. The name is a
symbol.
-- Function: ly:transpose-key-alist l pit
Make a new key alist of L transposed by pitch PIT.
-- Function: ly:truncate-list! lst i
Take at most the first I of list LST.
-- 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:undead? x
Is X a ‘Undead’ object?
-- Function: ly:unit
Return the unit used for lengths as a string.
-- Function: ly:unpure-pure-container? clos
Is CLOS an unpure pure container?
-- Function: ly:unpure-pure-container-pure-part pc
Return the pure part of PC.
-- Function: ly:unpure-pure-container-unpure-part pc
Return the unpure part of PC.
-- Function: ly:usage
Print usage message.
-- Function: ly:verbose-output?
Was verbose output requested, i.e. loglevel at least ‘DEBUG’?
-- Function: ly:version
Return the current lilypond version as a list, e.g., ‘(1 3 127
uu1)’.
-- Function: ly:warning str rest
A Scheme callable function to issue the warning STR. The message
is formatted with ‘format’ and REST.
-- Function: ly:warning-located location str rest
A Scheme callable function to issue the warning STR at the
specified location in an input file. The message is formatted with
‘format’ and REST.
-- Function: ly:wide-char->utf-8 wc
Encode the Unicode codepoint WC, an integer, as UTF-8.
Info Catalog
lilypond-internals: Backend
lilypond-internals: Top
lilypond-internals: Indices