| 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> |