Node:Scheme functions, Next:, Previous:Backend, Up:Top



Scheme functions

Apply_context_iterator::constructor Function
Construct a Apply_context_iterator music iterator

Auto_change_iterator::constructor Function
Construct a Auto_change_iterator music iterator

Bar_check_iterator::constructor Function
Construct a Bar_check_iterator music iterator

Change_iterator::constructor Function
Construct a Change_iterator music iterator

Chord_tremolo_iterator::constructor Function
Construct a Chord_tremolo_iterator music iterator

Context_specced_music_iterator::constructor Function
Construct a Context_specced_music_iterator music iterator

Event_chord_iterator::constructor Function
Construct a Event_chord_iterator music iterator

Folded_repeat_iterator::constructor Function
Construct a Folded_repeat_iterator music iterator

Grace_iterator::constructor Function
Construct a Grace_iterator music iterator

Lyric_combine_music_iterator::constructor Function
Construct a Lyric_combine_music_iterator music iterator

Music_iterator::constructor Function
Construct a Music_iterator music iterator

Music_wrapper_iterator::constructor Function
Construct a Music_wrapper_iterator music iterator

Output_property_music_iterator::constructor Function
Construct a Output_property_music_iterator music iterator

Part_combine_music_iterator::constructor Function
Construct a Part_combine_music_iterator music iterator

Percent_repeat_iterator::constructor Function
Construct a Percent_repeat_iterator music iterator

Pop_property_iterator::constructor Function
Construct a Pop_property_iterator music iterator

Property_iterator::constructor Function
Construct a Property_iterator music iterator

Property_unset_iterator::constructor Function
Construct a Property_unset_iterator music iterator

Push_property_iterator::constructor Function
Construct a Push_property_iterator music iterator

Sequential_iterator::constructor Function
Construct a Sequential_iterator music iterator

Sequential_music_iterator::constructor Function
Construct a Sequential_music_iterator music iterator

Simple_music_iterator::constructor Function
Construct a Simple_music_iterator music iterator

Simultaneous_music_iterator::constructor Function
Construct a Simultaneous_music_iterator music iterator

Time_scaled_music_iterator::constructor Function
Construct a Time_scaled_music_iterator music iterator

Unfolded_repeat_iterator::constructor Function
Construct a Unfolded_repeat_iterator music iterator

Volta_repeat_iterator::constructor Function
Construct a Volta_repeat_iterator music iterator

ly:add-interface a b c Function
Add an interface description.

ly:add-moment a b Function
Add two moments.

ly:all-grob-interfaces Function
Get a hash table with all interface descriptions.

ly:bracket a iv t p Function
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.

ly:context-parent context Function
Return the parent of context, #f if none.

ly:context-properties context Function
Return all properties of context in an alist.

ly:context-property-where-defined context name Function
Return the context above context where name is defined.

ly:context-pushpop-property context grob eltprop val Function
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).

ly:context? x Function
Type predicate: is x a context?

ly:dimension? d Function
Return d is a number. Used to distinguish length variables from normal numbers.

ly:dir? s Function
type predicate. A direction is a -1, 0 or 1, where -1 represents left or down and 1 represents right or up.

ly:div-moment a b Function
Divide two moments.

ly:duration-dot-count dur Function
Extract the dot count from dur

ly:duration-factor dur Function
Extract the compression factor from dur. Return as a pair.

ly:duration-log dur Function
Extract the duration log from dur

ly:duration<? p1 p2 Function
Is p1 shorter than p2?

ly:duration? x Function
Check if x is a Duration object

ly:export arg Function
Export a Scheme object to the parser, so it is treated as an identifier.

ly:find-glyph-by-name font name Function
This function retrieves a Molecule for the glyph named name in font. The font must be available as an AFM file. If the glyph is not found, #f is returned.

ly:font-metric? x Function
Check if x is a Font_metric object

ly:fontify-atom met f Function
Add a font selection command for the font metric met to f.

ly:get-all-function-documentation Function
Get a hash table with all lilypond Scheme extension functions.

ly:get-all-translators Function
Return an list of a all translator objects that may be instantiated during a lilypond run.

ly:get-broken-into spanner Function
Return broken-into list for spanner.

ly:get-context-property context name Function
retrieve the value of name from context context

ly:get-default-font grob Function
Return the default font for grob gr.

ly:get-extent grob refp axis Function
Get the extent in axis direction of grob relative to the grob refp

ly:get-glyph font index Function
This function retrieves a Molecule for the glyph numbered index in font.

ly:get-grob-property grob sym Function
Get the value of a value in grob g of property sym. It will return '() (end-of-list) if g doesn't have sym set.

Grob properties are stored as GUILE association lists, with symbols as keys. All lookup functions identify undefined properties with end-of-list (i.e. '() in Scheme or SCM_EOL in C)

Properties are stored in two ways:

  • mutable properties. Grob properties that change from object to object. The storage of these are private to a grob. For example pointers to other grobs are always stored in the mutable properties.
  • immutable properties. Grob properties that are shared across different grobs of the same type. The storage is shared, and hence it is read-only. Typically, this is used to store function callbacks, and default settings. They are initially read from scm/grob-description.scm.

ly:get-mus-property mus sym Function
Get the property sym of music expression mus. If sym is undefined, return '().

ly:get-music-length mus Function
Get the length (in musical time) of music expression mus.

ly:get-mutable-properties mus Function
Return an alist signifying the mutable properties of mus. The immutable properties are not available; they should be initialized by the functions make-music-by-name function.

ly:get-option var Function
Get a global option setting. Supported options include
old-relative-used
Report whether old-relative compatibility mode is necessary
old-relative
Report whether old-relative compatibility mode is used
verbose
Report whether we are running in verbose mode

ly:get-original grob Function
Return the original Grob of grob

ly:get-paper-variable grob sym Function
Get a variable from the \paper block.

ly:get-parent grob axis Function
Get the parent of grob. axis is 0 for the X-axis, 1 for the Y-axis.

ly:get-spanner-bound slur dir Function
Get one of the bounds of spanner. dir is -1 for left, and 1 for right.

ly:get-system grob Function
Return the System Grob of grob.

ly:grob-paper grob Function
Get \paper definition from a grob.

ly:grob-pq-less? a b Function
Compare 2 Grob PQ entries. Internal

ly:grob-script-priority-less a b Function
Compare two grobs by script priority. For internal use.

ly:grob-staff-position sg Function
Return the Y-position of this grob relative to the staff.

ly:grob-suicide g Function
Kill g.

ly:grob-translate-axis! g d a Function
Translate g on axis a over distance d.

ly:grob? x Function
Check if x is a Grob object

ly:gulp-file name Function
Read the file named name, and return its contents in a string. The file is looked up using the lilypond search path.

ly:input-location? x Function
Return whether x is an input location

ly:input-message sip msg Function
Print msg as a GNU compliant error message, pointing to the location in sip.

ly:intlog2 d Function
The 2-logarithm of 1/d.

ly:iterator? x Function
Check if x is a Music_iterator object

ly:make-bare-music type props Function
Make a music object/expression of type type, init with props. Warning: this interface will likely change in the near future.

Music is the data type that music expressions are stored in. The data type does not yet offer many manipulations.

WARNING: only for internal use. Please use make-music-by-name.

ly:make-duration length dotcount num den Function

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

ly:make-molecule expr xext yext Function

The objective of any typesetting system is to put ink on paper in the right places. For LilyPond, this final stage is left to the TeX and the printer subsystem. For lily, the last stage in processing a score is outputting a description of what to put where. This description roughly looks like

                  PUT glyph AT (x,y)
                  PUT glyph AT (x,y)
                  PUT glyph AT (x,y)
          
you merely have to look at the tex output of lily to see this. Internally these instructions are encoded in Molecules.1 A molecule is what-to-print-where information that also contains dimension information (how large is this glyph?).

Conceptually, Molecules can be constructed from Scheme code, by translating a Molecule and by combining two molecules. In BNF notation:

          Molecule  :: COMBINE Molecule Molecule
                     | TRANSLATE Offset Molecule
                     | GLYPH-DESCRIPTION
                     ;
          

If you are interested in seeing how this information is stored, you can run with the -f scm option. The scheme expressions are then dumped in the output file.

ly:make-moment n d Function
create the rational number with main timing n/d.

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.

ly:make-pitch o n a Function
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 shift is zero for a natural, negative for flats, or positive for sharps.

ly:molecule-add args Function
Combine molecules. Takes any number of arguments.

ly:molecule-align-to! mol axis dir Function
Align mol using its own extents. dir is a number -1, 1 are left and right respectively. Other values are interpolated (so 0 means the center.

ly:molecule-combine-at-edge first axis direction second padding minimum Function
Construct a molecule 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 molecules are juxtaposed with padding as extra space. If this puts the reference points closer than minimum, they are moved by the latter amount.

ly:molecule-get-extent mol axis Function
Return a pair of numbers signifying the extent of mol in axis direction (0 or 1 for x and y axis respectively).

ly:molecule-set-extent! mol axis np Function
Set the extent (extent must be a pair of numbers) of mol in axis direction (0 or 1 for x- and y-axis respectively).

Note that an extent (A . B) is an interval and hence A is smaller than B, and is often negative.

ly:molecule-translate mol offset Function
Return a mol, but translated by offset (a pair of numbers).

ly:molecule-translate-axis mol amount axis Function
Return a mol, but translated by amount in axis direction

ly:molecule? x Function
Check if x is a Molecule object

ly:moment? x Function
Check if x is a Moment object

ly:mul-moment a b Function
Multiply two moments.

ly:music-deep-copy m Function
Copy m and all sub expressions of m

ly:music-duration-compress mus factor Function
Extract the duration field from mus, and compress it.

ly:music-duration-length mus Function
Extract the duration field from mus, and return the length.

ly:music-name mus Function
Return the name of music.

ly:music-transpose m p Function
Transpose m such that central C is mapped to p. Return m.

ly:music? x Function
Check if x is a Music object

ly:number->string s Function
converts num to a string without generating many decimals. It leaves a space at the end.

ly:option-usage Function
Print ly-set-option usage

ly:paper-get-font paper chain Function
Return a font metric satisfying the font-qualifiers in the alist chain chain.

The font object represents the metric information of a font. Every font that is loaded into LilyPond can be accessed via Scheme.

LilyPond only needs to know the dimension of glyph to be able to process them. This information is stored in font metric files. LilyPond can read two types of font-metrics: TeX Font Metric files (TFM files) and Adobe Font Metric files (AFM files). LilyPond will always try to load AFM files first since they are more versatile.

An alist chain is a list of alists, containing grob properties.

ly:paper-lookup pap sym Function
Lookup sym in pap. Return the value or '() if undefined.

ly:pitch-alteration pp Function
extract the alteration from pitch p.

ly:pitch-diff pitch root Function
Return pitch with value DELTA = PITCH - ROOT, ie, ROOT == (ly:pitch-transpose root delta).

ly:pitch-notename pp Function
extract the note name from pitch pp.

ly:pitch-octave pp Function
extract the octave from pitch p.

ly:pitch-quartertones pp Function
calculate the number of semitones of p from central C.

ly:pitch-semitones pp Function
calculate the number of semitones of p from central C.

ly:pitch-steps p Function
Number of steps counted from central C of the pitch p.

ly:pitch-transpose p delta Function
Transpose p by the amount delta, where delta is the pitch that central C is transposed to.

ly:pitch<? p1 p2 Function
Is p1 lower than p2? This uses lexicographic ordening.

ly:pitch? x Function
Check if x is a Pitch object

ly:round-filled-box xext yext blot Function
Make a filled-box of dimensions xext, yext and roundness blot.

ly:set-context-property! context name val Function
set value of property name in context context to val.

ly:set-grob-property! grob sym val Function
Set sym in grob grob to value val

ly:set-mus-property! mus sym val Function
Set property sym in music expression mus to val.

ly:set-option var val Function
Set a global option value. Supported options include
help
List all options.
midi-debug
If set to true, generate human readable MIDI
internal-type-checking
Set paranoia for property assignments
parse-protect
If protection is switched on, errors in inline scheme are caught in the parser. If off, GUILE will halt on errors, and give a stack trace. Default is protected evaluation.
old-relative
Relative for simultaneous functions similar to chord syntax
new-relative
Relative for simultaneous functions similar to sequential music

This function is useful to call from the command line: lilypond -e "(ly-set-option 'midi-debug #t_)".

ly:set-point-and-click what Function
Set the options for Point-and-click source specials output. The argument is a symbol. Possible options are none (no source specials), line and line-column

ly:text-dimension font text Function
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.

ly:translator-description me Function
Return an alist of properties of translator me.

ly:translator-find context name Function
Find a parent of context that has name or alias name. Return #f if not found.

ly:translator-name trans Function
Return the type name of the translator trans.

ly:translator? x Function
Check if x is a Translator object

ly:transpose-key-alist l pitch Function
Make a new key alist of l transposed by pitch pitch

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

ly:unset-context-property context name Function
Unset value of property name in context context.

ly:version Function
Return the current lilypond version as a list, e.g. (1 3 127 uu1).

ly:warn str Function
Scheme callable function to issue the warning msg.

music-list? l Function
Type predicate: return true if l is a list of music objects.


Footnotes

  1. At some point LilyPond also contained Atom-objects, but they have been replaced by Scheme expressions, making the name outdated.



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

Report errors to <bug-lilypond@gnu.org>.