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