[mup] / mup / docs / uguide / macros.html

<HTML>
<HEAD><TITLE>
Mup macros
</TITLE></HEAD>
<BODY>
<P>
&nbsp;&nbsp;&nbsp;<A HREF="headfoot.html">&lt;-- previous page</A>

&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="index.html">Table of Contents</A>&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="ifclause.html">next page --&gt;</A>
</P>
         
<H2>
Macros
</H2>
<H3>
Simple Macros (without parameters)
</H3>
<P>
Macros can be defined to avoid retyping or to give mnemonic names to
things. A macro is defined with the following syntax:
<BR><PRE>
<B>define</B> <I> macro_name macro_text</I> <B>@</B>
</PRE><BR>
</P>
<P>
The <I>macro_name</I> consists of one or more upper case letters, digits,
and underscores, with the first character being a letter.
The <I>macro_text</I> can be any text. It can be any length from empty
to many pages. The &quot;@&quot; terminates the macro. A literal &quot;@&quot; can be
placed in the <I>macro_text</I> by preceding it with a backslash.
If you want a literal backslash in the <I>macro_text</I>, it also must
be preceded by a backslash.
</P>
<P>
A macro is called by stating the <I>macro_name</I> in the input. The
<I>macro_name</I> is replaced by the <I>macro_text</I>. 
A macro can be defined at any point in the input. It can be used as
often as desired any time after it has been defined. A given <I>macro_name</I>
can be redefined as many times as desired, with each new definition
overwriting the previous definition.
</P>
<P>
As an example, suppose you are printing an orchestral score, and the oboe
part happens to be on staff 5. Rather than having to remember which staff
it is, you could define a macro:
<BR><PRE>
define OBOE 5: @
</PRE><BR>
Not only is the name easier to remember than a number, but if you later
decide to move the oboe part to a different place in the score, only the
macro definition and perhaps a few other things would have to be changed.
</P>
<P>
Another common use of macros might be if a musical motif occurs several
times. You could define a macro for the motive:
<BR><PRE>
define SCALE 8c;d;e;f;g;a;b;c+; @
</PRE><BR>
then do something like:
<BR><PRE>
OBOE SCALE
</PRE><BR>
</P>
<P>
It is possible to remove the definition of a macro using the &quot;undef&quot;
statement:
<BR><PRE>
undef OBOE
</PRE><BR>
</P>
<P>
It is possible to have parts of the input skipped over depending on whether
certain macros are defined or not. This is done using
&quot;ifdef,&quot; &quot;else,&quot; and &quot;endif.&quot; The keyword &quot;ifdef&quot; is followed by
a macro name. If a macro by that name is currently defined,
Mup will continue
reading and processing input normally. If it finds a matching &quot;else,&quot;
it will skip over input until the matching &quot;endif.&quot;
If the macro is not currently defined, Mup will skip over the input
until it finds a matching &quot;else&quot; or &quot;endif.&quot;  There is also
an &quot;ifndef&quot; command that uses the opposite logic: it will read the input
up to the &quot;else&quot; or &quot;endif&quot; only if the macro is NOT defined.
</P>
<P>
The ifdefs can be sprinkled between other items in the input;
they need not be on separate lines. They can be nested. Examples:
<BR><PRE>
// make last c an octave higher if macro &quot;FRED&quot; is defined
1: c;e;g;c ifdef FRED + endif;

ifdef PIANO
    staff 1 visible=n
else
    ifdef VIOLIN
        staff 2 visible=n
        staff 3 visible=n
    endif
endif
</PRE><BR>
</P>
<P>
<A HREF="cmdargs.html#doption">Macros can also be set from the command line using the -D option.</A>
Only ordinary macros can be defined using the -D option,
not macros with parameters.
</P>
<H3>
Macros with parameters
</H3>
<P>
<A NAME="macparm">Macros defined within Mup input can be defined to have "parameters."</A>
This may be useful
when you have something that is repeated with small variations.
When defining a macro with parameters, the macro name must be followed
immediately by a ( with no space between the end of the name and the
parenthesis. The opening parenthesis is followed by one or more
parameter names, separated by commas, and ending with a close parenthesis.
Parameter names have the same rules as macro names: they consist of
upper case letters, numbers, and underscores, starting with an upper case
letter. The parameter names can then appear in the text of the macro
definition where you want a value to be substituted.
</P>
<P>
As an example, suppose you are doing a score with staffs 1 through 4
for vocal parts, and staffs 5 and 6 for a piano accompaniment, and that
you frequently want to mark a dymanics change at the same point in time
below each of the vocal scores and between the two piano staffs.
You could typically do this with something like:
<BR><PRE>
boldital below 1-4: 1 &quot;ff&quot;;
boldital between 5&amp;6: 1 &quot;ff&quot;;
</PRE><BR>
but if you needed to do this lots of times, it could get tedious.
So let's define a macro with parameters:
<BR><PRE>
define DYN( COUNT, VOLUME )
boldital below 1-4: COUNT VOLUME;
boldital between 5&amp;6: COUNT VOLUME;
@
</PRE><BR>
This macro has two parameters,
which have been given the names COUNT and VOLUME.
When you call the macro, you will give them values.
For example,
<BR><PRE>
DYN(1,&quot;ff&quot;)
</PRE><BR>
would give a VOLUME of &quot;ff&quot; at COUNT 1, whereas
<BR><PRE>
DYN(3.5,&quot;mp&quot;)
</PRE><BR>
would give a VOLUME of &quot;mp&quot; at COUNT 3.5.
</P>
<P>
When calling a macro with parameters, the values to give the parameters
are given inside parentheses. The values are separated by commas.
The values in the parentheses are copied exactly as they are,
including any spaces, newlines, macro names, etc.
There are only a few exceptions to this:
you can include a comma, closing parenthesis, or backslash
as part of a parameter value by preceding it with a backslash, and
a backslash followed by a newline
in a parameter value will be discarded. Thus a macro call of
<BR><PRE>
MAC(\\\,\))
</PRE><BR>
has one parameter, the text of which is 3 characters long: a backslash,
comma, and closing parenthesis.
</P>
<P>
<A NAME="quoting">If in a macro definition a parameter is used inside backticks,</A>
as in `NAME`, the value of the parameter will be placed
inside double quotes. Thus, another way to do the example above would be:
<BR><PRE>
define DYN( COUNT, VOLUME )
boldital below 1-4: COUNT `VOLUME`;
boldital between 5&amp;6: COUNT `VOLUME`;
@

DYN(1,ff)
DYN(3.5,mp)
</PRE><BR>
</P>
<P>
Conceptually, when the macro is expanded, the backticks are replaced
by double quote marks, but in addition,
any double quote mark found in the value being passed to the parameter will
have a backslash inserted before it, and any backslash that occurs
within double quotes in the value will also have a backslash inserted
before it. Thus, for example:
<BR><PRE>
// If we define a macro like this:
define QUOTED(X) `X` @

// then for input    value passed is    `X` would be    which would print as

print QUOTED(hello)       hello          &quot;hello&quot;          hello
print QUOTED(&quot;hello&quot;)     &quot;hello&quot;        &quot;\&quot;hello\&quot;&quot;      &quot;hello&quot;
print QUOTED(\\n)         \n             &quot;\n&quot;             a literal newline
print QUOTED(&quot;\\n&quot;)       &quot;\n&quot;           &quot;\&quot;\\n\&quot;&quot;        &quot;\n&quot;
</PRE><BR>
</P>
<P>
Sometimes it can be a little tricky to get the number of backslashes right,
or other details like that.
<A HREF="cmdargs.html#Eoption">The -E Mup command line option</A>
shows how macros will expand, which may help you figure out what to do.
</P>
<HR><P>
&nbsp;&nbsp;&nbsp;<A HREF="headfoot.html">&lt;-- previous page</A>&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="index.html">Table of Contents</A>&nbsp;&nbsp;&nbsp;&nbsp;<A HREF="ifclause.html">next page --&gt;</A>
</P>
</BODY></HTML>
Commit	Line	Data
69695f33 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>