Commit | Line | Data |
---|---|---|
fac14bbe MW |
1 | <HTML> |
2 | <HEAD><TITLE> | |
3 | Mup macros | |
4 | </TITLE></HEAD> | |
5 | <BODY> | |
6 | <P> | |
7 | <A HREF="headfoot.html"><-- previous page</A> | |
8 | ||
9 | <A HREF="index.html">Table of Contents</A> <A HREF="ifclause.html">next page --></A> | |
10 | </P> | |
11 | ||
12 | <H2> | |
13 | Macros | |
14 | </H2> | |
15 | <H3> | |
16 | Simple Macros (without parameters) | |
17 | </H3> | |
18 | <P> | |
19 | Macros can be defined to avoid retyping or to give mnemonic names to | |
20 | things. A macro is defined with the following syntax: | |
21 | <BR><PRE> | |
22 | <B>define</B> <I> macro_name macro_text</I> <B>@</B> | |
23 | </PRE><BR> | |
24 | </P> | |
25 | <P> | |
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. | |
33 | </P> | |
34 | <P> | |
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. | |
41 | </P> | |
42 | <P> | |
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: | |
46 | <BR><PRE> | |
47 | define OBOE 5: @ | |
48 | </PRE><BR> | |
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. | |
52 | </P> | |
53 | <P> | |
54 | Another common use of macros might be if a musical motif occurs several | |
55 | times. You could define a macro for the motive: | |
56 | <BR><PRE> | |
57 | define SCALE 8c;d;e;f;g;a;b;c+; @ | |
58 | </PRE><BR> | |
59 | then do something like: | |
60 | <BR><PRE> | |
61 | OBOE SCALE | |
62 | </PRE><BR> | |
63 | </P> | |
64 | <P> | |
65 | It is possible to remove the definition of a macro using the "undef" | |
66 | statement: | |
67 | <BR><PRE> | |
68 | undef OBOE | |
69 | </PRE><BR> | |
70 | </P> | |
71 | <P> | |
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, | |
76 | Mup will continue | |
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. | |
83 | </P> | |
84 | <P> | |
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: | |
87 | <BR><PRE> | |
88 | // make last c an octave higher if macro "FRED" is defined | |
89 | 1: c;e;g;c ifdef FRED + endif; | |
90 | ||
91 | ifdef PIANO | |
92 | staff 1 visible=n | |
93 | else | |
94 | ifdef VIOLIN | |
95 | staff 2 visible=n | |
96 | staff 3 visible=n | |
97 | endif | |
98 | endif | |
99 | </PRE><BR> | |
100 | </P> | |
101 | <P> | |
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. | |
105 | </P> | |
106 | <H3> | |
107 | Macros with parameters | |
108 | </H3> | |
109 | <P> | |
110 | <A NAME="macparm">Macros defined within Mup input can be defined to have "parameters."</A> | |
111 | This may be useful | |
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. | |
121 | </P> | |
122 | <P> | |
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: | |
128 | <BR><PRE> | |
129 | boldital below 1-4: 1 "ff"; | |
130 | boldital between 5&6: 1 "ff"; | |
131 | </PRE><BR> | |
132 | but if you needed to do this lots of times, it could get tedious. | |
133 | So let's define a macro with parameters: | |
134 | <BR><PRE> | |
135 | define DYN( COUNT, VOLUME ) | |
136 | boldital below 1-4: COUNT VOLUME; | |
137 | boldital between 5&6: COUNT VOLUME; | |
138 | @ | |
139 | </PRE><BR> | |
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. | |
143 | For example, | |
144 | <BR><PRE> | |
145 | DYN(1,"ff") | |
146 | </PRE><BR> | |
147 | would give a VOLUME of "ff" at COUNT 1, whereas | |
148 | <BR><PRE> | |
149 | DYN(3.5,"mp") | |
150 | </PRE><BR> | |
151 | would give a VOLUME of "mp" at COUNT 3.5. | |
152 | </P> | |
153 | <P> | |
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 | |
163 | <BR><PRE> | |
164 | MAC(\\\,\)) | |
165 | </PRE><BR> | |
166 | has one parameter, the text of which is 3 characters long: a backslash, | |
167 | comma, and closing parenthesis. | |
168 | </P> | |
169 | <P> | |
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: | |
173 | <BR><PRE> | |
174 | define DYN( COUNT, VOLUME ) | |
175 | boldital below 1-4: COUNT `VOLUME`; | |
176 | boldital between 5&6: COUNT `VOLUME`; | |
177 | @ | |
178 | ||
179 | DYN(1,ff) | |
180 | DYN(3.5,mp) | |
181 | </PRE><BR> | |
182 | </P> | |
183 | <P> | |
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: | |
190 | <BR><PRE> | |
191 | // If we define a macro like this: | |
192 | define QUOTED(X) `X` @ | |
193 | ||
194 | // then for input value passed is `X` would be which would print as | |
195 | ||
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" | |
200 | </PRE><BR> | |
201 | </P> | |
202 | <P> | |
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. | |
207 | </P> | |
208 | <HR><P> | |
209 | <A HREF="headfoot.html"><-- previous page</A> <A HREF="index.html">Table of Contents</A> <A HREF="ifclause.html">next page --></A> | |
210 | </P> | |
211 | </BODY></HTML> |