20.5 File structure

A .ly file may contain any number of top-level expressions, where a top-level expression is one of the following:

• An output definition, such as \paper, \midi, and \layout. Such a definition at the top-level changes the default book-wide settings. If more than one such definition of the same type is entered at the top level the definitions are combined, but in conflicting situations the later definitions take precedence. For details of how this affects the \layout block see The \layout block.
• A direct Scheme expression, such as #(set-default-paper-size "a7" 'landscape) or #(ly:set-option 'point-and-click #f).
• A \header block. This sets the global (i.e., the top of file) header block. This is the block containing the default settings of titling fields like composer, title, etc., for all books within the file (see Titles explained).
• A \score block. This score will be collected with other top-level scores, and combined as a single \book. This behavior can be changed by setting the variable toplevel-score-handler at top level. (The default handler is defined in the file ../scm/lily-library.scm and set in the file ../ly/declarations-init.ly.)
• A \book block logically combines multiple movements (i.e., multiple \score blocks) in one document. If there are a number of \scores, one output file will be created for each \book block, in which all corresponding movements are concatenated. The only reason to explicitly specify \book blocks in a .ly file is if you wish to create multiple output files from a single input file. One exception is within lilypond-book documents, where you explicitly have to add a \book block if you want more than a single \score or \markup in the same example. This behavior can be changed by setting the variable toplevel-book-handler at top level. The default handler is defined in the init file ../scm/lily.scm.
• A \bookpart block. A book may be divided into several parts, using \bookpart blocks, in order to ease the page breaking, or to use different \paper settings in different parts.
• A compound music expression, such as

  { c'4 d' e'2 }
  

  This will add the piece in a \score and format it in a single book together with all other top-level \scores and music expressions. In other words, a file containing only the above music expression will be translated into

  \book {
    \score {
      \new Staff {
        \new Voice {
          { c'4 d' e'2 }
        }
      }
      \layout { }
    }
    \paper { }
    \header { }
  }
  

  This behavior can be changed by setting the variable toplevel-music-handler at top level. The default handler is defined in the init file ../scm/lily.scm.

• A markup text, a verse for example

  \markup {
     2.  The first line verse two.
  }
  

  Markup texts are rendered above, between or below the scores or music expressions, wherever they appear.

• A variable or a nested structure of Scheme association lists (alists).

  foo = { c4 d e d }       % normal variable
  "Horn 3" = { c4 d e d }  % quoted variable
  verse.1 = { c4 d e d }   % nested alist
  

  Variables can be used later on in the file by prepending them with a backslash.

  \foo
  \"Horn 3"
  \verse.1
  

  The name of a variable should not contain (ASCII) numbers, multiple adjacent underscores, multiple adjacent dashes, or space characters. All other characters Unicode provides are allowed, for example Latin, Greek, Chinese, or Cyrillic. Non-adjacent single underscores and dashes are allowed, too. In other words, variable names like HornIII or Скрипка-II work.

  Any combination of characters is allowed if the variable name is enclosed in double quotation marks (not that you actually should use such a name).⁷ Examples: "foo bar", "a-b-c", "Horn 3".

  Nested alists provide a means to partially circumvent the abovementioned restriction of variable names not containing a number. A nested alist is a valid variable name followed by one or more sets of a dot and a key. In mus.violin.1 = { a1 } we have a variable called mus, which has an alist with a key called violin, which in turn has a key called 1, which is eventually assigned the value { a1 }. In "1.2"."3.4".5 the variable name is "1.2" and the keys are "3.4" and 5 – such rather illegible constructs might be useful for programmatically generated variable names.

  Neither a variable name nor a key in a nested alist is allowed to be a note name. If necessary, enclose those in double quotation marks, or better, change the offending name or key.

  For technical reasons, accessing nested alists might fail under some circumstances. In particular, they cannot be accessed at top-level (i.e., outside of a music block). If lilypond aborts with the error ‘bad expression type’, replace the nested alist with a normal or quoted variable.

The following example shows three things that may be entered at top level.

\layout {
  % Don't justify the output
  ragged-right = ##t
}

\header {
   title = "Do-re-mi"
}

{ c'4 d' e2 }

At any point in a file, any of the following lexical instructions can be entered:

• \version
• \include
• \sourcefilename
• \sourcefileline
• A single-line comment, introduced by a leading % sign.
• A multi-line comment delimited by %{ … %}.

Whitespace between items in the input stream is generally ignored, and may be freely omitted or extended to enhance readability. However, whitespace should always be used in the following circumstances to avoid errors:

• Around every opening and closing curly bracket.
• After every command or variable, i.e., every item that begins with a \ sign.
• After every item that is to be interpreted as a Scheme expression, i.e., every item that begins with a ‘#’ sign.
• To separate all elements of a Scheme expression.
• In lyricmode before and after \set and \override commands.

See also

Learning Manual: How LilyPond input files work.

Notation Reference: Titles explained, The \layout block.