LilyPond Learning Manual: 2.2.2 Working on input files

[ << Tutorial ]	[Top][Contents][Index]	[ Common notation >> ]
[ < All together ]	[ Up : How to write input files ]	[ Dealing with errors > ]

2.2.2 Working on input files

LilyPond input files are similar to source files in many common programming languages. They contain a version statement, are case sensitive, and whitespace is generally ignored. Expressions are formed with curly braces { }, and comments are denoted with ‘%’ or ‘%{ … %}’.

If the previous sentences sound like nonsense, don’t worry! We are now going to explain what all these terms mean.

Version statement: Every LilyPond file should contain a version statement. A version statement is a line that describes the version of LilyPond for which the file was written, as in the following example:
```
\version "2.24.4"
```
By convention, the version statement is placed at the top of the LilyPond file.

The version statement is important for at least two reasons. First, it allows automatic updating of the input file as LilyPond syntax changes. Second, it describes the version of LilyPond needed to compile the file.

If the version statement is omitted from an input file, LilyPond prints a warning during the compilation of the file.
Case sensitive: It matters whether you enter a letter in lowercase (e.g., ‘a’, ‘b’, ‘s’, ‘t’) or uppercase (e.g., ‘A’, ‘B’, ‘S’, ‘T’). Notes are lowercase: ‘{ c d e }’ is valid input; ‘{ C D E }’ produces an error message.
Whitespace insensitive: It does not matter how many spaces (or tabs, or new lines) you add.
```
{ c4 d e}
```
means the same thing as
```
{ c4       d e }
```
or
```
{ c4                       d
                   e   }
```
Of course, the previous example is hard to read. A good rule of thumb is to indent code blocks with two spaces:
```
{
  c4 d e
}
```
However, whitespace is required to separate many syntactical elements from others. In other words, whitespace can always be added, but not always eliminated. Since missing whitespace can give rise to strange errors, it is advisable to always insert whitespace before and after every syntactic element, for example, before and after every curly brace.
Expressions: Every piece of LilyPond input needs to have { curly braces } placed around the input. These braces tell LilyPond that the input is a single music expression, just like parentheses ‘()’ in mathematics. The braces should be surrounded by a space unless they are at the beginning or end of a line to avoid ambiguities.
A LilyPond command followed by a simple expression in braces (such as ‘\relative { … }’) also counts as a single music expression.
Comments: A comment is a remark for the human reader of the music input; it is ignored while parsing, so it has no effect on the printed output. There are two types of comments. The percent symbol ‘%’ introduces a line comment; anything after ‘%’ on that line is ignored. By convention, a line comment is placed above the code it refers to.
```
a4 a a a
% this comment refers to the next line with the two bs
b2 b
```
A block comment marks a whole section of music input as a comment. Anything that is enclosed in %{ and %} is ignored. However, block comments do not ‘nest’. This means that you cannot place a block comment inside another block comment. If you try, the first %} will terminate both block comments. The following fragment shows possible uses for comments.
```
% notes for twinkle twinkle follow
c4 c g' g a a g2

%{
  This line, and the notes below are ignored,
  since they are in a block comment.

  f4 f e e d d c2
%}
```

[ << Tutorial ]	[Top][Contents][Index]	[ Common notation >> ]
[ < All together ]	[ Up : How to write input files ]	[ Dealing with errors > ]

2.2.2 Working on input files

LilyPond — Learning Manual v2.24.4 (stable-branch).