Reference:User Defined Macros - Revision history

Clipka: canonicalize a version number

2021-06-09T14:28:08Z

canonicalize a version number

Jholsenback: technical correction

2018-12-08T11:04:41Z

technical correction

Jholsenback: version changes

2017-06-26T10:05:18Z

version changes

Jholsenback: version changes

2017-06-26T10:04:31Z

version changes

Jholsenback: /version changes

2017-06-26T10:03:53Z

/version changes

Clipka: Indexentries fix

2016-12-16T15:20:13Z

Indexentries fix

Jholsenback: minor updates and link redirect

2016-12-14T11:44:47Z

minor updates and link redirect

Jholsenback: corrected link formatting issue

2016-07-19T09:59:56Z

corrected link formatting issue

Jholsenback: minor New layout change

2016-07-18T16:36:02Z

minor New layout change

Jholsenback: updated syntax diagrams

2016-07-18T16:23:15Z

updated syntax diagrams

@@ Line 4: / Line 4: @@
 {{#indexentry:macro}}
 {{#indexentry:Directives, language, #macro}}
-<p>POV-Ray 3.1 introduced user defined macros with parameters. This feature,
+<p>POV-Ray v3.1 introduced user defined macros with parameters. This feature,
 along with the ability to declare <code>#local</code> variables, turned the
 POV-Ray Language into a fully functional programming language. Consequently,

@@ Line 292: / Line 292: @@
 #declare X=1;
 #declare Y=2;
-Foo(X,Y);
+Foo(X,Y)
-#undef Y;
+#undef Y
-Foo(X,Y);
+Foo(X,Y)
-Foo(X,);
+Foo(X,)
 </pre>
 <p class="Note"><strong>Note:</strong> The optional parameters mechanism can

@@ Line 20: / Line 20: @@
    [optional] GENERIC_IDENTIFIER
 </pre>
-<p>Where <em>IDENTIFIER</em> is the name of the macro and <em>PARAM_IDENT</em> is a list of zero or more formal parameter identifiers separated by commas and enclosed by parentheses. The parentheses are required even if no parameters are specified. {{New}} in version 3.7.1 see also: [[Reference:User Defined Macros#Optional Parameters|Optional Parameters]].</p>
+<p>Where <em>IDENTIFIER</em> is the name of the macro and <em>PARAM_IDENT</em> is a list of zero or more formal parameter identifiers separated by commas and enclosed by parentheses. The parentheses are required even if no parameters are specified. {{New}} in version 3.8 see also: [[Reference:User Defined Macros#Optional Parameters|Optional Parameters]].</p>
 <p>The <em>TOKENS</em> are any number of POV-Ray keyword, identifiers, or punctuation marks which are the <em> body</em> of the macro. The body of the macro may contain almost any POV-Ray syntax items you desire. It is terminated by the <code>#end</code> directive.</p>
 <p class="Note"><strong>Note:</strong> Any conditional directives such as <code>#if</code>...<code>#end</code>, <code>#while</code>...<code>#end</code>, etc. must be fully nested inside or outside the macro so that the corresponding <code>#end</code> directives pair-up properly.</p>

@@ Line 303: / Line 303: @@
 ==Macro Caching==
 {{#indexentry:caching, macro}}
-<p>Until now, each and every invocation of a macro from a file other than the one it was declared in, inevitably caused the latter file to be opened again for the macro code to be re-read. This process seriously impacts parser performance. To that end in version 3.7.1 a {{New}} cached macro mechanism has been implemented. It keeps a copy of each and every macro's code in memory (except for macros more than 65536 characters in size), greatly increasing the execution speed of macros in such scenarios.</p>
+<p>Until now, each and every invocation of a macro from a file other than the one it was declared in, inevitably caused the latter file to be opened again for the macro code to be re-read. This process seriously impacts parser performance. To that end in version 3.8 a {{New}} cached macro mechanism has been implemented. It keeps a copy of each and every macro's code in memory (except for macros more than 65536 characters in size), greatly increasing the execution speed of macros in such scenarios.</p>

@@ Line 261: / Line 261: @@
 {{#indexentry:optional, macro}}
 {{#indexentry:keyword, optional}}
-<p>{{New}} in version 3.7.1 macro parameters can be declared as optional by preceding the
+<p>{{New}} in version 3.8 macro parameters can be declared as optional by preceding the
 parameter identifier with the keyword <code>optional</code>; when calling
 a macro, you can pass undeclared identifiers to such optional parameters,

@@ Line 10: / Line 10: @@
 that previously required external utilities.</p>
 {{#indexentry:Directives, language, #macro}}
 {{#indexentry:Macros, declaring}}
 <p>The syntax for declaring a macro is:</p>
 <pre>
@@ Line 30: / Line 30: @@
 </ul>
 {{#indexentry:Macros, invoking}}
 <p>You invoke the macro by specifying the macro name followed by a list of zero or more actual parameters enclosed in parentheses and separated by commas. The number of actual parameters must match the number of formal parameters in the definition. The parentheses are required even if no parameters are specified. The syntax is:</p>
 <pre>
@@ Line 126: / Line 125: @@
 are somewhat macro-like but are mostly function-like.</p>
 {{#indexentry:Macros, returning values from}}
 <p>POV-Ray macros have a variety of uses. Like most macros, they provide a
 parameterized way to insert arbitrary code into a scene file. However most
@@ Line 207: / Line 206: @@
 <p>which is correct.</p>
 {{#indexentry:Macros, return values in parameters}}
 <p>Sometimes it is necessary to have a macro return more than one value or
 you may simply prefer to return a value via a parameter as is typical in
@@ Line 259: / Line 258: @@
 .0, only the first may modify the value of the identifier.</p>
 {{#indexentry:optional, macro}}
 {{#indexentry:keyword, optional}}
 <p>{{New}} in version 3.7.1 macro parameters can be declared as optional by preceding the
 parameter identifier with the keyword <code>optional</code>; when calling
@@ Line 301: / Line 300: @@
 <em>not</em> be used to return a value via a parameter to a previously
 undeclared identifier.</p>
 ==Macro Caching==
 <p>Until now, each and every invocation of a macro from a file other than the one it was declared in, inevitably caused the latter file to be opened again for the macro code to be re-read. This process seriously impacts parser performance. To that end in version 3.7.1 a {{New}} cached macro mechanism has been implemented. It keeps a copy of each and every macro's code in memory (except for macros more than 65536 characters in size), greatly increasing the execution speed of macros in such scenarios.</p>

@@ Line 283: / Line 283: @@
 macro will become visible instead. To reliably test whether an optional
 parameter has been supplied, you therefore need to make use of the
-<code>[[Reference:Declare and Local Directives#Identifier Name Collisions|local()]]</code>
+<code>local</code> <em>pseudo-dictionary</em>, as in the following example.</p>
-pseudo-function, as in the following example.</p>
+<p>See also the <code>[[Reference:Array|Array]]</code> section for more about <em>pseudo-dictionaries</em>.</p>
 <pre>
 #macro Foo(P1, optional P2)
-#ifndef(local(P2)) #local P2 = 0; #end // provide default for P2
+#ifndef(local.P2) #local P2 = 0; #end // provide default for P2
 ...
 #end
@@ Line 302: / Line 302: @@
 undeclared identifier.</p>
 {{#indexentry:caching, macro}}
 ==Macro Caching==
 <p>Until now, each and every invocation of a macro from a file other than the one it was declared in, inevitably caused the latter file to be opened again for the macro code to be re-read. This process seriously impacts parser performance. To that end in version 3.7.1 a {{New}} cached macro mechanism has been implemented. It keeps a copy of each and every macro's code in memory (except for macros more than 65536 characters in size), greatly increasing the execution speed of macros in such scenarios.</p>

@@ Line 26: / Line 26: @@
 <p>See also:</p>
 <ul>
-   <li>[[Reference:Conditional Directives#The ifdef and ifndef Directives|The <code>#ifdef</code> and <code>#ifndef</code> Directives]]</li>
+   <li>[[Reference:Conditional Directives#The ifdef and ifndef Directives|The ifdef and ifndef Directives]]</li>
-   <li>[[Reference:Declare and Local Directives#Destroying Identifiers with undef|Destroying Identifiers with <code>#undef</code>]]</li>
+   <li>[[Reference:Declare and Local Directives#Destroying Identifiers with undef|Destroying Identifiers with undef]]</li>
 </ul>

@@ Line 17: / Line 17: @@
 MACRO_DEFINITION:
    #macro IDENTIFIER ([PARAM_IDENT] [, PARAM_IDENT]... ) TOKENS... #end
 </pre>
-<p>Where <em>IDENTIFIER</em> is the name of the macro and <em>PARAM_IDENT</em> is a list of zero or more formal parameter identifiers separated by commas and enclosed by parentheses. The parentheses are required even if no parameters are specified.</p>
+<p>Where <em>IDENTIFIER</em> is the name of the macro and <em>PARAM_IDENT</em> is a list of zero or more formal parameter identifiers separated by commas and enclosed by parentheses. The parentheses are required even if no parameters are specified. See also: [[Reference:User Defined Macros#Optional Parameters|Optional Parameters]].</p>
 <p>The <em>TOKENS</em> are any number of POV-Ray keyword, identifiers, or punctuation marks which are the <em> body</em> of the macro. The body of the macro may contain almost any POV-Ray syntax items you desire. It is terminated by the <code>#end</code> directive.</p>
 <p class="Note"><strong>Note:</strong> Any conditional directives such as <code>#if</code>...<code>#end</code>, <code>#while</code>...<code>#end</code>, etc. must be fully nested inside or outside the macro so that the corresponding <code>#end</code> directives pair-up properly.</p>