7 <A HREF="headfoot.html"><-- previous page</A>
9 <A HREF="index.html">Table of Contents</A> <A HREF="ifclause.html">next page --></A>
16 Simple Macros (without parameters)
19 Macros can be defined to avoid retyping or to give mnemonic names to
20 things. A macro is defined with the following syntax:
22 <B>define</B> <I> macro_name macro_text</I> <B>@</B>
26 The <I>macro_name</I> consists of one or more upper case letters, digits,
27 and underscores, with the first character being a letter.
28 The <I>macro_text</I> can be any text. It can be any length from empty
29 to many pages. The "@" terminates the macro. A literal "@" can be
30 placed in the <I>macro_text</I> by preceding it with a backslash.
31 If you want a literal backslash in the <I>macro_text</I>, it also must
32 be preceded by a backslash.
35 A macro is called by stating the <I>macro_name</I> in the input. The
36 <I>macro_name</I> is replaced by the <I>macro_text</I>.
37 A macro can be defined at any point in the input. It can be used as
38 often as desired any time after it has been defined. A given <I>macro_name</I>
39 can be redefined as many times as desired, with each new definition
40 overwriting the previous definition.
43 As an example, suppose you are printing an orchestral score, and the oboe
44 part happens to be on staff 5. Rather than having to remember which staff
45 it is, you could define a macro:
49 Not only is the name easier to remember than a number, but if you later
50 decide to move the oboe part to a different place in the score, only the
51 macro definition and perhaps a few other things would have to be changed.
54 Another common use of macros might be if a musical motif occurs several
55 times. You could define a macro for the motive:
57 define SCALE 8c;d;e;f;g;a;b;c+; @
59 then do something like:
65 It is possible to remove the definition of a macro using the "undef"
72 It is possible to have parts of the input skipped over depending on whether
73 certain macros are defined or not. This is done using
74 "ifdef," "else," and "endif." The keyword "ifdef" is followed by
75 a macro name. If a macro by that name is currently defined,
77 reading and processing input normally. If it finds a matching "else,"
78 it will skip over input until the matching "endif."
79 If the macro is not currently defined, Mup will skip over the input
80 until it finds a matching "else" or "endif." There is also
81 an "ifndef" command that uses the opposite logic: it will read the input
82 up to the "else" or "endif" only if the macro is NOT defined.
85 The ifdefs can be sprinkled between other items in the input;
86 they need not be on separate lines. They can be nested. Examples:
88 // make last c an octave higher if macro "FRED" is defined
89 1: c;e;g;c ifdef FRED + endif;
102 <A HREF="cmdargs.html#doption">Macros can also be set from the command line using the -D option.</A>
103 Only ordinary macros can be defined using the -D option,
104 not macros with parameters.
107 Macros with parameters
110 <A NAME="macparm">Macros defined within Mup input can be defined to have "parameters."</A>
112 when you have something that is repeated with small variations.
113 When defining a macro with parameters, the macro name must be followed
114 immediately by a ( with no space between the end of the name and the
115 parenthesis. The opening parenthesis is followed by one or more
116 parameter names, separated by commas, and ending with a close parenthesis.
117 Parameter names have the same rules as macro names: they consist of
118 upper case letters, numbers, and underscores, starting with an upper case
119 letter. The parameter names can then appear in the text of the macro
120 definition where you want a value to be substituted.
123 As an example, suppose you are doing a score with staffs 1 through 4
124 for vocal parts, and staffs 5 and 6 for a piano accompaniment, and that
125 you frequently want to mark a dymanics change at the same point in time
126 below each of the vocal scores and between the two piano staffs.
127 You could typically do this with something like:
129 boldital below 1-4: 1 "ff";
130 boldital between 5&6: 1 "ff";
132 but if you needed to do this lots of times, it could get tedious.
133 So let's define a macro with parameters:
135 define DYN( COUNT, VOLUME )
136 boldital below 1-4: COUNT VOLUME;
137 boldital between 5&6: COUNT VOLUME;
140 This macro has two parameters,
141 which have been given the names COUNT and VOLUME.
142 When you call the macro, you will give them values.
145 DYN(1,"ff")
147 would give a VOLUME of "ff" at COUNT 1, whereas
149 DYN(3.5,"mp")
151 would give a VOLUME of "mp" at COUNT 3.5.
154 When calling a macro with parameters, the values to give the parameters
155 are given inside parentheses. The values are separated by commas.
156 The values in the parentheses are copied exactly as they are,
157 including any spaces, newlines, macro names, etc.
158 There are only a few exceptions to this:
159 you can include a comma, closing parenthesis, or backslash
160 as part of a parameter value by preceding it with a backslash, and
161 a backslash followed by a newline
162 in a parameter value will be discarded. Thus a macro call of
166 has one parameter, the text of which is 3 characters long: a backslash,
167 comma, and closing parenthesis.
170 <A NAME="quoting">If in a macro definition a parameter is used inside backticks,</A>
171 as in `NAME`, the value of the parameter will be placed
172 inside double quotes. Thus, another way to do the example above would be:
174 define DYN( COUNT, VOLUME )
175 boldital below 1-4: COUNT `VOLUME`;
176 boldital between 5&6: COUNT `VOLUME`;
184 Conceptually, when the macro is expanded, the backticks are replaced
185 by double quote marks, but in addition,
186 any double quote mark found in the value being passed to the parameter will
187 have a backslash inserted before it, and any backslash that occurs
188 within double quotes in the value will also have a backslash inserted
189 before it. Thus, for example:
191 // If we define a macro like this:
192 define QUOTED(X) `X` @
194 // then for input value passed is `X` would be which would print as
196 print QUOTED(hello) hello "hello" hello
197 print QUOTED("hello") "hello" "\"hello\"" "hello"
198 print QUOTED(\\n) \n "\n" a literal newline
199 print QUOTED("\\n") "\n" "\"\\n\"" "\n"
203 Sometimes it can be a little tricky to get the number of backslashes right,
204 or other details like that.
205 <A HREF="cmdargs.html#Eoption">The -E Mup command line option</A>
206 shows how macros will expand, which may help you figure out what to do.
209 <A HREF="headfoot.html"><-- previous page</A> <A HREF="index.html">Table of Contents</A> <A HREF="ifclause.html">next page --></A>
~mdw / mup / blob