Mantis 1571
P1800-2008/D3a
Add defaults for text macro arguments
The proposal is based on
In
Section 21.5.1
CHANGE
Change the syntax in Syntax
21-2 from
list_of_formal_arguments ::=
formal_argument_identifier { ,
formal_argument_identifier }
formal_argument_identifier ::=
simple_identifier
TO
list_of_formal_arguments ::=
formal_argument_identifier { , formal_argument_identifier }
formal_argument
{ ,
formal_argument }
formal_argument
::=
simple_identifier [ = default_text ]
formal_argument_identifier
::=
simple_identifier
CHANGE
If formal arguments are
used, the list of formal argument names shall be enclosed in
parentheses
following
the name of the macro. The
formal argument names shall be simple_identifiers,
separated by commas and
optionally
whitespace. The left parenthesis shall follow the text macro name
immediately,
with no space in between.
TO
If formal arguments are
used, the list of formal argument names shall be enclosed in
parentheses
following
the name of the macro. The
formal argument names shall be simple_identifiers,
separated by commas and
optionally
whitespace. The left parenthesis shall follow the text macro name
immediately,
with no space in between.
A formal macro argument may have a
default. A default
is specified by appending an "=" symbol after the formal argument
name, followed by the default text. The default text is substituted for
the
formal argument if no corresponding actual argument is specified.
The default text
may be explicitly specified to be empty by adding
an "=" symbol after the formal argument name, followed by a comma (or
a right parenthesis if it is the last argument in the argument list.)
CHANGE
To use a macro defined
with arguments, the name of the text macro shall be followed by a list
of
actual arguments in
parentheses, separated by commas. White space shall be allowed between
the text
macro name and the left parenthesis.
The number of actual arguments
shall
match the number of formal arguments. However, an actual argument may be empty or white
space only, in which case the formal argument is substituted by
nothing. Commas
must still be used to maintain the correct number of arguments.
Example:
`define D(x,y) initial
$display("start", x , y, "end");
`D( "msg1" , "msg2"
) // prints "startmsg1msg2end"
`D( " msg1", ) // prints "start msg1 end"
`D(, "msg2 ") // prints "start msg2 end"
`D(,)
// prints "start end"
`D( ,
) // prints "start end"
`D("msg1") // illegal, only one argument
`D()
// illegal, only one empty
argument
(The green text
was added by
Mantis 1957.)
TO
To use a macro defined
with arguments, the name of the text macro shall be followed by a list
of
actual arguments in
parentheses, separated by commas. Actual
arguments and
defaults shall not contain comma or right parenthesis characters
outside
matched pairs of left and right parentheses (), square brackets [],
braces {},
double quotes "", or an escaped identifier.
White space shall be allowed
between the
text macro name and the left parenthesis in
the macro
usage.
If fewer actual
arguments are specified than the number of formal
arguments and all the remaining formal arguments have defaults, then
the
defaults are substituted for the additional formal arguments. It shall
be an
error if any of the remaining formal arguments does not have a default
specified. For a macro with arguments,
the parentheses are always required in the macro call, even if
all the
arguments have defaults. For macros without arguments, it shall be an
error to
add parentheses. It shall be an error to specify more actual arguments
than the
number of formal arguments.
Example without defaults:
`define D(x,y) initial
$display("start", x , y, "end");
`D( "msg1" , "msg2"
) // expands
to 'initial
$display("start", "msg1" , "msg2",
"end");'
prints
"startmsg1msg2end"
`D( " msg1", ) // expands to 'initial
$display("start", " msg1" , , "end");' prints "start msg1 end"
`D(, "msg2 ") // expands to 'initial
$display("start", , "msg2 ", "end");' prints "start msg2 end"
`D(,)
// expands to 'initial
$display("start", , ,
"end");'
prints
"start end"
`D( ,
) // expands to 'initial
$display("start", , ,
"end");'
prints
"start end"
`D("msg1") // illegal, only one argument
`D()
// illegal, only one empty
argument
`D(,,)
// illegal, more actual than
formal arguments
Example with
defaults:
`define
MACRO1(a=5,b="B",c)
$display(a,,b,,c);
`MACRO1 ( , 2, 3 ) // argument a
omitted, replaced by default
// expands to
'$display(5,,2,,3);'
`MACRO1 ( 1 , , 3 ) // argument b omitted, replaced by default
// expands to
'$display(1,,"B",,3);'
`MACRO1 ( , 2, ) // ILLEGAL: c
omitted, no default
`MACRO1 ( 1 ) // ILLEGAL: b and c
omitted, no default for c
`define MACRO2(a=5,
b, c="C") $display(a,,b,,c);
`MACRO2 (1, , 3) // ILLEGAL: b
omitted, no default
`MACRO2 (, 2, ) // a and c omitted,
replaced by defaults
// expands to
'$display(1,,2,,"C");'
`MACRO2 (, 2) // a and c omitted,
replaced by defaults
// expands to
'$display(1,,2,,"C");'
`define MACRO3(a=5, b=0, c="C") $display(a,,b,,c);
`MACRO3 ( 1 ) // b and c omitted,
replaced by defaults
// expands to
'$display(1,,0,,"C");'
`MACRO3 ( ) // all
arguments replaced by defaults
// expands to
'$display(5,,0,,"C");'
`MACRO3 // ILLEGAL:
parentheses required
CHANGE
Each actual argument is
substituted for the corresponding formal argument literally. Therefore,
when an
expression is used as an actual argument, the expression will be
substituted in
its entirety. This may cause an expression to be evaluated more than
once if
the formal argument was used more than once in the macro text. For
example:
`define max(a,b)((a)
> (b) ? (a) : (b))
n = `max(p+q, r+s)
;
will expand as
n = ((p+q) > (r+s))
? (p+q) :
(r+s) ;
Here, the larger of the two
expressions p + q and r + s will be evaluated twice.
TO
Each actual argument is
substituted for the corresponding formal argument literally. Therefore,
when an
expression is used as an actual argument, the expression will be
substituted in
its entirety. This may cause an expression to be evaluated more than
once if
the formal argument was used more than once in the macro text. For
example:
`define max(a,b)((a)
> (b) ? (a) : (b))
n = `max(p+q, r+s)
;
will expand as
n = ((p+q) > (r+s))
? (p+q) :
(r+s) ;
Here, the larger of
the two
expressions p
+ q and
r + s will
be
evaluated twice.
The macro
text and argument defaults may contain usages of
other text macros. Such usages shall be substituted after the outer
macro is
substituted, not when it is defined. If an actual argument or an
argument
default contains a macro usage, the macro usage shall be expanded only
after
substitution into the outer macro text.
Note that if
a formal argument has a non-empty default and
one wants to replace the formal argument with an empty actual argument,
one
cannot simply omit the actual argument, as then the default will be
used.
However, one can define an empty text macro, say `EMPTY, and use that
as the
actual argument. This will be substituted in place of the formal
argument, and
will be replaced after expansion by empty text.
When a macro
usage is passed
as an actual argument to another macro, the argument expansion shall
not introduce
new uses of the formal arguments to the top-level macro.
`define
TOP(a,b) a + b
`TOP( `TOP(b,1), `TOP(42,a) )
expands
to: b + 1
+ 42 + a
not into: 42 + a + 1 + 42 + a
nor into: b + 1 + 42 + b + 1
It shall be an error
for a macro
to expand directly or indirectly to text containing another usage of
itself (a
recursive macro).