-
Notifications
You must be signed in to change notification settings - Fork 38
General Interface
Given you have properly installed openLilyLib you initialize it
by inserting
\include "openlilylib"at the top of your input file. If you have several input files (or e.g. library
files) you can use that command multiple times without worries as openLilyLib
will only be included and parsed once.
Once openLilyLib has been initialized you have access to the libraries that
are its individual parts. But apart from this you will already have access to
openLilyLib's infrastructure, which consists of several concepts and a number
of useful commands. (Basically openLilyLib makes the functionality it needs
for itself available for end users or library developers.) This is discussed
in Common Functionality.
This page describes the general concepts and commands for using openLilyLib.
For information on any given library please refer to the library's documentation.
openLilyLib is a collection of libraries that extend LilyPond's functionality
with specific features. In order to use these features a library has to be
loaded with the command \useLibrary which exists in two forms:
\useLibrary <library-name> % Library names are case-insensitive
\useLibrary \with {
optionOne = value % option values can be of any Scheme type
optionTwo = value
}
<library-name>
% Example
\include "openlilylib"
\useLibrary GridLY
\useLibrary \with
colorize = ##f
}
scholarly\useLibrary will load the given library if it hasn't already been loaded. If
options are given they are passed to the library, but it is up to each library
to make any use of them. Passing options that are not recognized by a library
simply does nothing, so it doesn't harm either.
Some libraries expose their full functionality as a self-contained unit by loading the library, while others provide more control and allow loading their functionality in fine-grained units or modules.
Loading a module is very similar to loading a library, and the command \useModule
has a very similar interface to \useLibrary:
\useModule #'(<library> path to module)
\useModule \with {
optionOne = value
optionOne = value
}
#'(<library> path to module)
% Example:
\include "openlilylib"
\useLibrary ScholarLY
\useModule #'(scholarly annotate)Again, modules are loaded only once, and it is up to the library maintainers to support options or not.
Note: Before a module is loaded the containing library has to be loaded, as
\useModule isn't capable of implicitly loading the library (yet).
Note: In theory \useModule can also be invoked using the dotted list
notation, e.g. \useModule scholarly.annotate, but due to a parser bug in
LilyPond (that was discovered on this occasion) this can cause problems depending
on what comes next in the input file. Basically if the next item is a Scheme
expression everything works fine but LilyPond expressions tend to fail. If you
want to use the more modern dot notation you can always add an "empty" expression
afterwards, e.g.
\include "openlilylib"
\useLibrary ScholarLY
\useModule scholarly.annotate
#(display "")
%...openLilyLib provides a unified interface to handling library configuration.
Libraries and modules can expose options to configure their behaviour. You
have already seen the options that can be passed to a library or module while
loading them, but options can be set (with some more control) with the
independent command \setOption:
\setOption <library.path.to.option> <value>
% Examples
\setOption scholarly.annotate.print ##t
\setOption comptools.page-breaks #'(20 37 52 66 83 91)Some options may be changed along the way (e.g. to switch a feature on and off) while others have a global effect. Please refer to the library's documentation for more information on the available options and their effects.
Users can make use of this unified interface to store data or options for their own purposes, e.g. in house or project libraries. Please refer to Common Functionality for more information.