LilyPond Notation Reference: A.22 Scheme functions

[ << Notation manual tables ] [Top][Contents][Index] [ Cheat sheet >> ]

[ < LilyPond exported predicates ] [ Up : Notation manual tables ] [ Cheat sheet > ]

A.22 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 callback disp cl: Add the single-argument procedure callback as listener to the dispatcher disp. Whenever disp hears an event of class cl, it calls callback with it.

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:angle x y: Calculates angle in degrees of given vector. With one argument, x is a number pair indicating the vector. With two arguments, x and y specify the respective coordinates.

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-matched-pop-property context grob cell: This undoes a particular \override, \once \override or \once \revert when given the specific alist pair to undo.

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 \temporary \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: Is d a dimension? 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:directed direction magnitude: Calculates an (x . y) pair with optional magnitude (defaulting to 1.0) and direction specified either as an angle in degrees or a coordinate pair giving the direction. If magnitude is a pair, the respective coordinates are scaled independently, useful for ellipse drawings.

Function: ly:disconnect-dispatchers to from: Stop the dispatcher to listening to events from from.

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: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:extract-subfont-from-collection collection-file-name idx subfont-file-name: Extract the subfont of index idx in TrueType collection (TTC) or OpenType/CFF collection (OTC) file collection_file_name and write it to file subfont_file_name.

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.

Function: ly:font-glyph-name-to-index font name

Return the index for name in font.

Function: ly:font-index-to-charcode font index

Return the character code for index in font.

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:generic-bound-extent grob common: Determine the extent of grob relative to common along the X axis, finding its extent as a bound when it a has bound-alignment-interfaces property list set and otherwise the full extent.

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-cff-offset font-file-name idx: Get the offset of ’CFF’ table for font_file_name, returning it as an integer. The optional idx argument is useful for OpenType/CFF collections (OTC) only; it specifies the font index within the OTC. The default value of idx is 0.

Function: ly:get-context-mods contextmod: Returns the list of context modifications stored in contextmod.

Function: ly:get-font-format font-file-name idx: Get the font format for font_file_name, returning it as a symbol. The optional idx argument is useful for TrueType Collections (TTC) and OpenType/CFF collections (OTC) only; it specifies the font index within the TTC/OTC. The default value of idx is 0.

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? x: Is x a Grob_properties object?

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-spanned-rank-interval grob: Returns a pair with the rank of the furthest left column and the rank of the furthest right column spanned by grob.

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:has-glyph-names? font-file-name idx: Does the font for font_file_name have glyph names? The optional idx argument is useful for TrueType Collections (TTC) and OpenType/CFF collections (OTC) only; it specifies the font index within the TTC/OTC. The default value of idx is 0.

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 a Input object?

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: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:item-get-column it: Return the PaperColumn or NonMusicalPaperColumn associated with this Item.

Function: ly:iterator? x: Is x a Music_iterator object?

Function: ly:length x y: Calculates magnitude of given vector. With one argument, x is a number pair indicating the vector. With two arguments, x and y specify the respective coordinates.

Function: ly:lily-lexer? x: Is x a Lily_lexer object?

Function: ly:lily-parser? x: Is x a Lily_parser object?

Function: ly:line-interface::line grob startx starty endx endy: Make a line using layout information from grob grob.

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-grob-properties alist: This packages the given property list alist in a grob property container stored in a context property with the name of a grob.

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 alist default-callback: Create an outputter dumping to port. alist should map symbols to procedures. See output-ps.scm for an example. If default_callback is given, it is called for unsupported expressions

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-rotation angle center: Make a transform rotating by angle in degrees. If center is given as a pair of coordinates, it is the center of the rotation, otherwise the rotation is around (0 . 0).

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-scaling scale scaley: Create a scaling transform from argument scale and optionally scaley. When both arguments are given, they must be real and give the scale in x and y direction. If only scale is given, it may also be complex to indicate a scaled rotation in the manner of complex number rotations, or a pair of reals for specifying different scales in x and y direction like with the first calling convention.

Function: ly:make-score music: Return score with music encapsulated in it.

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:

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 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-transform xx yx xy yy x0 y0: Create a transform. Without options, it is an identity transform. Given four arguments xx, yx, xy, and yy, it is a linear transform, given six arguments (with x0 and y0 last), it is an affine transform. Transforms can be called as functions on other transforms (concatening them) or on points given either as complex number or real number pair. See also ly:make-rotation, ly:make-scaling, and ly:make-translation.

Function: ly:make-translation x y: Make a transform translating by x and y. If only x is given, it can also be a complex number or a pair of numbers indicating the offset to use.

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 scale factor.

Function: ly:music-deep-copy m origin: Copy m and all sub expressions of m. m may be an arbitrary type; cons cells and music are copied recursively. If origin is given, it is used as the origin for one level of music by calling ly:set-origin! on the copy.

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 object?

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-auto-height-breaking pb: Put each score on a single line, and put each line on its own page. Modify the paper-width setting so that every page is wider than the widest line. Modify the paper-height setting to fit the height of the tallest line.

Function: ly:one-line-breaking pb: Put each score on a single line, and put each line on its own page. Modify the paper-width setting so that every page is wider than the widest line.

Function: ly:one-page-breaking pb: Put each score on a single page. The paper-height settings are modified so each score fits on one page, and the height of the page matches the height of the full score.

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 idx: Convert the contents of an OTF file to a CFF file, returning it as a string. The optional idx argument is useful for OpenType/CFF collections (OTC) only; it specifies the font index within the OTC. The default value of idx is 0.

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? x: Is x a Output_def object?

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-name if 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-output-scheme outputter expr: Output expr to the paper 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-column::break-align-width col align-syms: Determine the extent along the X-axis of a grob used for break-alignment organized by column col. The grob is specified by align-syms, which contains either a single break-align-symbol or a list of such symbols.

Function: ly:paper-column::print: Optional stencil for PaperColumn orNonMusicalPaperColumn. Draws the rank number of each column, its moment in time, a blue arrow showing the ideal distance, and a red arrow showing the minimum distance between columns.

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 error flag for parser, defaulting to current parser.

Function: ly:parser-clone closures location: Return a clone of current parser. 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! symbol val: Bind symbol to val in current parser’s module.

Function: ly:parser-error msg input: Display an error message and make current parser fail. Without a current parser, trigger an ordinary error.

Function: ly:parser-has-error? parser: Does parser (defaulting to current parser) have an error flag?

Function: ly:parser-include-string ly-code: Include the string ly-code into the input stream for current parser. Can only be used in immediate Scheme expressions ($ instead of #).

Function: ly:parser-lexer parser: Return the lexer for parser, defaulting to current parser

Function: ly:parser-lookup symbol: Look up symbol in current parser’s module. Return '() if not defined.

Function: ly:parser-output-name parser: Return the base name of the output file. If parser is left off, use currently active parser.

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 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-headers performance: Return the list of headers with the innermost first.

Function: ly:performance-write performance filename name: Write performance to filename storing name as the name of the performance in the file metadata.

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 root transposed by delta equals pitch.

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:pure-call data grob start end rest: Convert property data (unpure-pure container or procedure) to value in a pure context defined by grob, start, end, and possibly rest arguments.

Function: ly:randomize-rand-seed: Randomize C random generator.

Function: ly:register-stencil-expression symbol: Add symbol as head of a stencil expression.

Function: ly:register-translator creator name description: Register a translator creator (usually a descriptive alist or a function/closure returning one when given a context argument) with the given symbol name and the given description alist.

Function: ly:relative-group-extent elements common axis: Determine the extent of elements relative to common in the axis direction.

Function: ly:rename-file oldname newname: Rename oldname to newname. In contrast to Guile’s rename-file, this replaces the destination if it already exists. On Windows, fall back to copying the file contents if newname cannot be deleted.

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 extroversion: Make a Stencil object that prints a black polygon with corners at the points defined by points (list of coordinate pairs) and roundness blot. Optionalextroversion shifts the outline outward, with thedefault of -1.0 keeping the outer boundary ofthe outline just inside of the polygon.

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:separation-item::print: Optional stencil for PaperColumn orNonMusicalPaperColumn. Draws the horizontal-skylines of each PaperColumn, showing the shapes used to determine the minimum distances between PaperColumns at the note-spacing step, before staves have been spaced (vertically) on the page.

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-origin! m origin: This sets the origin given in origin to m. m will typically be a music expression or a list of music. List structures are searched recursively, but recursion stops at the changed music expressions themselves. origin is generally of type ly:input-location?, defaulting to (*location*). Other valid values for origin are a music expression which is then used as the source of location information, or #f or '() in which case no action is performed. The return value is m itself.

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: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:source-files parser-smob: A list of input files that have been opened up to here, including the files that have been closed already. a PARSER may optionally be specified.

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 current staff-line thickness in the staff associated with grob, expressed as a multiple of the current staff-space height.

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 current staff-space height in the staff associated with grob, expressed as a multiple of the default height of a staff-space in the traditional five-line staff.

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-in-color stc r g b a: Put stc in a different color.Accepts either three values for r,g, b and an optional valuefor a, or a single CSS-like string.

Function: ly:stencil-outline stil outline: Return a stencil with the stencil expression (inking) of stencil stil but with outline and dimensions from stencil outline.

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 stencil stil using the horizontal and vertical scaling factors x and y. Negative values will flip or mirror stil without changing its origin; this may result in collisions unless it is repositioned.

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:transform? x: Is x a Transform object?

Function: ly:transform->list transform: Convert a transform matrix to a list of six values. Values are xx, yx, xy, yy, x0, y0.

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 creator: Return an alist of properties of translator definition creator.

Function: ly:translator-group? x: Is x a Translator_group object?

Function: ly:translator-name creator: Return the type name of the translator definition creator. 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:type1->pfa type1-file-name: Convert the contents of a Type 1 font in PFB format to PFA format. If the file is already in PFA format, pass through it.

Function: ly:undead? x: Is x a Undead object?

Function: ly:unit: Return the unit used for lengths as a string.

Function: ly:unpure-call data grob rest: Convert property data (unpure-pure container or procedure) to value in an unpure context defined by grob and possibly rest arguments.

Function: ly:unpure-pure-container? x: Is x a Unpure_pure_container object?

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.

[ << Notation manual tables ] [Top][Contents][Index] [ Cheat sheet >> ]

[ < LilyPond exported predicates ] [ Up : Notation manual tables ] [ Cheat sheet > ]

A.22 Scheme functions

LilyPond — Notation Reference v2.21.82 (development-branch).