Scheme functions - LilyPond program-reference
Description: LilyPond program-reference

Next: Indexes, Previous: Backend, Up: Top

## Scheme functions

— Function: ly:add-file-name-alist alist

> Add mappings for error messages from specified alist

— Function: ly:add-interface a b c

> Add an interface description.

— Function: ly:add-option sym val description

> Add a program option sym with default val.

— Function: ly:all-grob-interfaces

> Get a hash table with all interface descriptions.

— Function: ly:all-stencil-expressions

> Return all symbols recognized as stencil expressions.

— Function: ly:all-tweaks

> all tweaks

— Function: ly:assoc-get key alist default-value

> Return value if KEY in ALIST, else DEFAULT-VALUE (or #f if not specified).

— Function: ly:book-process book-smob default-paper default-layout output

> Print book. output is passed to the backend unchanged. Eg. it may be a string (for file based outputs) or a socket (for network based output).

— 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 protude by an amount of p, which may be negative. The thickness is given by t.

— Function: ly:chain-assoc-get key achain dfault

> Return value for key from a list of alists achain. If no if no entry is found, return DFAULT, or #f if no DFAULT not specified.

— Function: ly:clear-anonymous-modules

> Plug a GUILE 1.6 and 1.7 memory leak by breaking a weak reference pointer cycle explicitly.

— Function: ly:clone-parser parser-smob

> Return a clone of PARSER_SMOB.

— Function: ly:cm num

> num cm

— Function: ly:command-line-verbose?

> Was be_verbose_global set?

— 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-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 c name

> Return the value of name from context c

— 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:context? x

> Is x a `Context` object?

— Function: ly:dimension? d

> Return d is a number. Used to distinguish length variables from normal numbers.

— Function: ly:dir? s

> type predicate. A direction is `-1`, `0` or `1`, where `-1` represents left or down and `1` represents right or up.

— Function: ly:dumper-definitions dumper

> Return list of key definitions.

— Function: ly:dumper-key-serial dumper key

> Return the key serial number key.

— Function: ly:duration-dot-count dur

> Extract the dot count from dur

— Function: ly:duration-factor dur

> Extract the compression factor from dur. Return as a pair.

— Function: ly:duration-log dur

> Extract the duration log from dur

— Function: ly:duration<? p1 p2

> Is p1 shorter than p2?

— Function: ly:duration? x

> Is x a `Duration` object?

— Function: ly:effective-prefix

> Return effective prefix.

— Function: ly:error str rest

> Scheme callable function to issue the error `msg`. The error is formatted with `format` and `rest`.

— Function: ly:export arg

> Export a Scheme object to the parser, so it is treated as an identifier.

— Function: ly:find-file name

> Return the absolute file name of name, or `#f` if not found.

— 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. font must be available as an AFM file. If the glyph is not available, return `#f`.

— 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 font.

— Function: ly:font-load name

> Load the font name.

— Function: ly:font-magnification font

> Given the font metric font, return the magnification, relative to the current outputs-cale.

— 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-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-glyph font index

> Retrieve a Stencil for the glyph numbered index in font.

— Function: ly:get-option var

> Get a global option setting.

— Function: ly:gettext string

> Gettext wrapper.

— 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-length grob-arr

> Return the grob_array length.

— Function: ly:grob-array-ref grob-arr index

> Retrieve the `index` element of `grob-arr`.

— Function: ly:grob-array? x

> Is x a `Grob_array` object?

— Function: ly:grob-basic-properties grob

> Get the immutable properties of grob.

— 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 gr.

— Function: ly:grob-extent grob refp axis

> Get the extent in axis direction of grob relative to the grob refp

— Function: ly:grob-insert-tweak grob tweak

> add new tweak for grob.

— Function: ly:grob-interfaces grob

> Return the interfaces list of grob grob.

— Function: ly:grob-key grob

> Return the object-key for grob.

— Function: ly:grob-layout g

> Get `\layout` definition from grob g.

— Function: ly:grob-object grob sym

> Return the value of a pointer in grob g of property sym. It will return `' ()` (end-of-list) if sym is undefined in g.

— 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-less? a b

> Compare 2 grob priority queue entries. Internal

— Function: ly:grob-properties grob

> Get the mutable proprerties of grob.

— Function: ly:grob-property grob sym deflt

> Return the value of a value in grob g of property sym. It will return `'()` or deflt (if specified) if sym is undefined in g.

— Function: ly:grob-property-data grob sym

> Retrieve sym for grob but don't process callbacks.

— Function: ly:grob-relative-coordinate grob refp axis

> Get the coordinate in axis direction of grob relative to the grob refp

— Function: ly:grob-replace-tweak grob tweak

> Replace tweak for grob.

— Function: ly:grob-script-priority-less a b

> Compare two grobs by script priority. For internal use.

— 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! g

> Kill g.

— Function: ly:grob-system g

> Return the System Grob of g.

— Function: ly:grob-translate-axis! g d a

> Translate g on axis a over distance d.

— Function: ly:grob? x

> Is x a `Grob` object?

— Function: ly:gulp-file name size

> Read the file name, and return its contents in a string. The file is looked up using the search path.

— Function: ly: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

— Function: ly:interpret-stencil-expression expr func arg1 offset

> Parse EXPR, feed bits to FUNC with first arg ARG1

— Function: ly:intlog2 d

> The 2-logarithm of 1/d.

— Function: ly:item-break-dir it

> The break status dir of item it. `-1` is end of line, `0` unbroken, and `1` begin of line.

— Function: ly:item? g

> Is g an `Item` object?

— Function: ly:iterator? x

> Is x a `Music_iterator` object?

— Function: ly:layout-def? def

> Is def a layout definition?

— Function: ly:lily-lexer? x

> Is x a `Lily_lexer` object?

— Function: ly:lily-parser? x

> Is x a `Lily_parser` object?

— Function: ly:load-text-dimensions dimension-alist

> Load dimensions from TeX in a (KEY . (W H D)) format alist

— 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-dumper

> Create a key dumper.

— Function: ly:make-duration length dotcount num den

> length is the negative logarithm (base 2) of the duration: 1 is a half note, 2 is a quarter note, 3 is an eighth note, etc. The number of dots after the note is given by the optional argument dotcount.

> The duration factor is optionally given by num and den.

> A duration is a musical duration, i.e. a length of time described by a power of two (whole, half, quarter, etc.) and a number of augmentation dots.

— Function: ly:make-moment n d gn gd

> Create the rational number with main timing n/d, and optional grace timin gn/gd.

> Moment is a point in musical time. It is consists of a pair of rationals (m, g), where m is the timing for the main notes, and g the timing for grace notes. In absence of grace notes, g is zero.

— Function: ly:make-music props

> Make a C++ Music object, initialize 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` is a list containing either `ly:music?` predicates or other type predicates.

— Function: ly:make-output-def

> Make a output def.

— 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 from 0 to 6, with 0 corresponding to C and 6 corresponding to B. The alter is zero for a natural, negative for flats, or positive for sharps.

— Function: ly:make-prob type init rest

> Create a Prob.

— Function: ly:make-score music

> Return score with music encapsulated in score.

— Function: ly:make-simple-closure expr

> Make a simple closure. expr should be form of `(`func a1 A2`...)`, and will be invoked as `(`func delayed-arg a1 a2`... )`.

— Function: ly:make-stencil expr xext yext

> Stencils are a 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.

— Function: ly:make-undumper

> Create a key undumper.

— Function: ly:message str rest

> Scheme callable function to issue the message `msg`. The message is formatted with `format` and `rest`.

— 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

> Lookup sym in the list modules, returning the first occurence. If not found, return default, or `#f`.

— Function: ly:moment-add a b

> Add two moments.

— Function: ly:moment-div a b

> Divide two moments.

— 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-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:moment<? a b

> Compare two moments.

— Function: ly:moment? x

> Is x a `Moment` 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

— 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-length mus

> Get the length of music expression mus, and return as a `Moment` object.

— Function: ly:music-list? lst

> Type predicate: return true if lst is 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 dfault

> Get the property sym of music expression mus. If sym is undefined, return `'()`.

— 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:music? obj

> Type predicate

— Function: ly:number->string s

> Convert num to a string without generating many decimals.

— Function: ly:option-usage

> Print ly:set-option usage

— Function: ly:otf->cff otf-file-name

> Convert the contents of a OTF file to CFF file, returning it as a string.

— Function: ly:otf-font-glyph-info font glyph

> Given the font metric font of an OpenType font, return the information about named glyph glyph (a string)

— Function: ly:otf-font-table-data font tag

> Extract a table tag from font. Return empty string for non-existent tag.

— Function: ly:otf-font? font

> Is font an OpenType font?

— Function: ly:otf-glyph-list font

> Return a list of glyphnames for font.

— Function: ly:output-backend

> Return name of output backend.

— Function: ly:output-def-clone def

> Clone def.

— Function: ly:output-def-lookup pap sym def

> Lookup sym in pap. Return the value or def (which defaults to `'()`) if undefined.

— Function: ly:output-def-parent def

> Get the parent output-def of def.

— Function: ly:output-def-parser odef

> Return the parser where odef is coming from.

— Function: ly:output-def-scope def

> Get the variable scope inside def.

— Function: ly:output-description output-def

> Return the description of translators 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

> Eval expr in module of outputter.

— Function: ly:outputter-port outputter

> Return output port for outputter.

— Function: ly:pango-font-physical-fonts f

> Return alist of (PSNAME . FILENAME) tuples.

— Function: ly:pango-font? f

> Is f a pango font?

— Function: ly:paper-book-pages pb

> Return pages in book PB.

— Function: ly:paper-book-paper pb

> Return pages in book PB.

— Function: ly:paper-book-performances paper-book

> Return performances in book paper-book.

— Function: ly:paper-book-scopes book

> Return pages in layout book book.

— Function: ly:paper-book-systems pb

> Return systems in book PB.

— Function: ly:paper-book? x

> Is x a `Paper_book` object?

— Function: ly:paper-fonts bp

> Return fonts from the `\paper` block bp.

— Function: ly:paper-get-font paper-smob chain

> Return a font metric satisfying the font-qualifiers in the alist chain chain. (An alist chain is a list of alists, containing grob properties).

— Function: ly:paper-get-number layout-smob name

> Return the layout variable name.

— Function: ly:paper-outputscale bp

> Get output-scale for BP.

— Function: ly:paper-score-paper-systems paper-score

> Return vector of paper_system objects from paper-score.

— Function: ly:paper-system? obj

> Type predicate.

— Function: ly:parse-file name

> Parse a single `.ly` file. Upon failure, throw `ly-file-failed` key.

— Function: ly:parse-string ly-code

> Parse the string LY_CODE. Upon failure, throw `ly-file-failed` key.

— Function: ly:parser-define! parser-smob symbol val

> Bind SYMBOL to VAL in PARSER_SMOB's module.

— Function: ly:parser-lookup parser-smob symbol

> Lookup symbol in parser_smob's module. Undefined is '().

— 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 PFB file to PFA.

— Function: ly:pitch-alteration pp

> Extract the alteration from pitch p.

— Function: ly:pitch-diff pitch root

> Return pitch delta such that `pitch` transposed by delta equals root

— Function: ly:pitch-notename pp

> Extract the note name from pitch pp.

— Function: ly:pitch-octave pp

> Extract the octave from pitch p.

— Function: ly:pitch-quartertones pp

> Calculate the number of quarter tones of p from middle C.

— Function: ly:pitch-semitones pp

> calculate the number of semitones of p from middle C.

— Function: ly:pitch-steps p

> Number of steps counted from middle C of the pitch p.

— Function: ly:pitch-transpose p delta

> Transpose p by the amount delta, where delta is relative to middle C.

— Function: ly:pitch<? p1 p2

> Is p1 lexicographically smaller than p2?

— Function: ly:pitch? x

> Is x a `Pitch` object?

— Function: ly:prob-property obj sym dfault

> Return the value for sym.

— Function: ly:prob-property? obj sym

> Is boolean prop sym set?

— Function: ly:prob-set-property! obj sym value

> Set property sym of obj to value

— Function: ly:prob-type? obj type

> If obj the specified prob-type?

— Function: ly:prob? x

> Is x a `Prob` object?

— Function: ly:programming-error str rest

> Scheme callable function to issue the warning `msg`. The message is formatted with `format` and `rest`.

— Function: ly:progress str rest

> Scheme callable function to print progress `str`. The message is formatted with `format` and `rest`.

— 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:round-filled-box xext yext blot

> Make a `Stencil` that prints a black box of dimensions xext, yext and roundness blot.

— Function: ly:run-translator mus output-def key

> Process mus according to output_def. An interpretation context is set up, and mus is interpreted with it. The context is returned in its final state.

> Optionally, this routine takes an Object-key to to uniquely identify the Score block containing it.

— Function: ly:score-embedded-format score layout key

> Run score through layout, an output definition, scaled to correct output-scale already, return a list of layout-lines. Take optional Object_key argument.

— Function: ly:score-process score-smob default-header default-paper default-layout basename

> Print score without page-layout: just print the systems.

— Function: ly:score? x

> Is x a `Score` object?

— Function: ly:set-option var val

> Set a program option. Try setting 'help for a help string.

— Function: ly:set-point-and-click what

> Deprecated.

— Function: ly:simple-closure? clos

> Type predicate.

— Function: ly:smob-protects

> Return lily'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 Springs have the format (ideal, hooke) and rods (idx1, idx2, distance) length is a number, ragged a boolean Return: a list containing the force (positive for stretching, negative for compressing and #f for non-satisfied constraints) followed by the spring-count+1 positions of the objects.

— Function: ly:spanner-bound slur 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? g

> Is g a spanner object?

— Function: ly:stderr-redirect file-name mode

> Redirect stderr to FILE-NAME, opened with MODE.

— 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, 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 minimum

> Construct a stencil by putting second next to first. axis can be 0 (x-axis) or 1 (y-axis), direction can be -1 (left or down) or 1 (right or up). The stencils are juxtaposed with padding as extra space. If this puts the reference points closer than minimum, they are moved by the latter amount.first and second may also be '() or #f.

— Function: ly:stencil-empty? stil

> Return whether stil is empty

— 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

> Analyse 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-moved-to-edge first axis direction second padding minimum

> Similar to `ly:stencil-combine-edge`, but returns second positioned to be next to first.

— Function: ly:stencil-origin stil axis

> Return a pair of numbers signifying the origin stil in axis direction (0 or 1 for x and y axis respectively).

— 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:stencil? x

> Is x a `Stencil` object?

— Function: ly:text-dimension font text

> Given the font metric in font and the string text, compute the extents of that text in that font. The return value is a pair of number-pairs.

— Function: ly: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:translator? x

> Is x a `Translator` object?

— Function: ly:transpose-key-alist l pit

> Make a new key alist of l transposed by pitch pit

— Function: ly:ttf->pfa ttf-file-name

> Convert the contents of a TTF file to Type42 PFA, returning it as a string.

— Function: ly:ttf-ps-name ttf-file-name

> Extract the PostScript name from a TrueType font.

— Function: ly:tweak-clear-registry

> Clear global tweak registry

— Function: ly:tweak-define-keys keys

> Read keys

— Function: ly:tweak-define-tweaks tweaks

> Read tweaks

— Function: ly:undumper-lookup undumper serial

> Return the object key for number serial.

— Function: ly:undumper-read-keys undumper keys

> Read serialized keys into undumper.

— Function: ly:unit

> Return the unit used for lengths as a string.

— Function: ly:usage

> Print usage message.

— Function: ly:version

> Return the current lilypond version as a list, e.g. `(1 3 127 uu1)`.

— Function: ly:warning str rest

> Scheme callable function to issue the warning `str`. The message is formatted with `format` and `rest`.

— Function: ly:wide-char->utf-8 wc

> Encode the Unicode codepoint wc as UTF-8

This page is for LilyPond-2.8.8 (stable-branch).

Other languages: English.
Using automatic language selection.