This shows you the differences between the selected revision and the current version of the page.
| ptpscript:commands:macro 2007/01/24 10:15 | ptpscript:commands:macro 2007/01/24 19:39 current | ||
|---|---|---|---|
| Line 1: | Line 1: | ||
| ======Macro Command====== | ======Macro Command====== | ||
| - | The ''Macro'' command allows a template section, containing data and/or PTPScript code, to be defined as a macro. In this context, a macro is essentially a sub-template, and behaves very much like a [[PTPScript:Functions|function]]. It has its own [[PTPScript:Variables|Variable]] "scope" - it cannot access Variables that are available in the main template. Any Variables that are created or modified within the macro will only affect the data inside that macro. | + | The ''Macro'' command allows a template section, containing data and/or PTPScript code, to be defined as a macro. In this context, a macro is essentially a sub-template, and behaves very much like a [[PTPScript:Functions|function]]. By default, it has its own [[PTPScript:Variables|Variable]] "[[PTPScript:Commands:Macro#Scope|scope]]" - it cannot access Variables that are available in the main template ([[PTPScript:Commands:Macro#Scope|PTPScript 4.1 added the ability to define macro scope]]). Any Variables that are created or modified within the macro will only affect the data inside that macro, unless the scope is changed. |
| When a ''Macro'' command is first encountered, the macro data is not displayed, but is instead stored for later use. Parameters can be defined, so that values can be passed to the macro. When required, the macro can be displayed by calling it in the same way as a function. This means that the output of a macro can be used in an expression in the same way as that of a function. | When a ''Macro'' command is first encountered, the macro data is not displayed, but is instead stored for later use. Parameters can be defined, so that values can be passed to the macro. When required, the macro can be displayed by calling it in the same way as a function. This means that the output of a macro can be used in an expression in the same way as that of a function. | ||
| Line 7: | Line 7: | ||
| There are two commands in the ''Macro'' family - ''Macro'' and ''EndMacro''. Each ''Macro'' command has to have a corresponding ''EndMacro'' command. | There are two commands in the ''Macro'' family - ''Macro'' and ''EndMacro''. Each ''Macro'' command has to have a corresponding ''EndMacro'' command. | ||
| - | The ''Macro'' command consists of the command, followed by the macro name, and then the names of any parameters, contained within parentheses and separated by commas. The ''EndMacro'' command does not use an expression, and so will ignore any expression given. | + | The ''Macro'' command consists of the command, followed by the macro name, and then the names of any parameters, contained within parentheses and separated by commas. The scope can also be changed. The ''EndMacro'' command does not use an expression, and so will ignore any expression given. |
| For example: | For example: | ||
| Line 26: | Line 26: | ||
| </note> | </note> | ||
| - | ''Macro'' definitions and calls can be nested indefinitely within other ''Macro'' definitions, and within other command structures, however each macro is fully enclosed and cannot detect or affect anything else. All ''Macro'' definitions are global in scope - that is, they can be called from anywhere, no matter where they were defined. However, if defined within a macro, the containing macro has to be called before the definition will be processed. | + | ''Macro'' definitions and calls can be nested indefinitely within other ''Macro'' definitions, and within other command structures, however each macro is fully enclosed and cannot detect or affect anything else unless its scope is altered. All ''Macro'' definitions are global in scope - that is, they can be called from anywhere, no matter where they were defined. However, if defined within a macro, the containing macro has to be called before the definition will be processed. |
| <note tip> | <note tip> | ||
| Line 48: | Line 48: | ||
| Because macros are called in the same way as functions, a macro could be declared with the same name as a function. In this case, the function will always be called, not the macro. | Because macros are called in the same way as functions, a macro could be declared with the same name as a function. In this case, the function will always be called, not the macro. | ||
| + | ====Scope==== | ||
| + | The scope of each macro can be set as desired, at declaration time. The "scope" is the behaviour of Variables present in the macro, relative to the environment outside the macro. There are three kinds of scope, with various keywords for each, to provide flexibility to cater for different tastes. | ||
| + | |||
| + | ^ Scope Type Keywords ^^^^ Description ^ | ||
| + | | ''shared'' | ''inherited'' | ''mutable'' | ''same'' | All Variables will be available to the macro, and changes will be reflected in the original environment | | ||
| + | | ''clean'' | ''fresh'' | ''separate'' | ''new'' | The macro will not inherit any Variables from the original environment, and vice versa (default) | | ||
| + | | ''clone'' | ''preserved'' | ''immutable'' | ''copy'' | The macro will inherit all Variables from the original environment, but changes will not affect the original environment | | ||
| + | |||
| + | The scope of each macro can be set by using the syntax ''macro (parameters...) as scope''. | ||
| + | |||
| + | For example: | ||
| + | |||
| + | <code ptpscript> | ||
| + | { Name = "Jim" } | ||
| + | { macro Greeting ( MealOfTheDay ) as shared }… | ||
| + | Hi there, {Name}! Would you like {MealOfTheDay}? | ||
| + | { endmacro }… | ||
| + | { Greeting ("fish and chips") } | ||
| + | </code> | ||
| + | |||
| + | <note tip> | ||
| + | Scope type keywords are case-insensitive. | ||
| + | </note> | ||
| + | |||
| + | <note important> | ||
| + | Macro scope can only be changed from PTPScript 4.1 onwards. PTPScript 4.0 anly allows macros to have ''clean'' scope - the default in PTPScript 4.1. | ||
| + | |||
| + | Note that templates compiled by PTPScript 4.0 are incompatible with PTPScript 4.1 if they contain macros, and vice-versa. This means that cached templates need to be cleared when moving between versions (this is advisable in any case). | ||
| + | </note> | ||
| + | |||
| + | <note info> | ||
| + | Note that when macro scope is set to ''shared'', the parameters passed to the macro will themselves become part of the global environment. This defeats the point of macros, in many ways, as one of the benefits of using macros is encapsulation. If shared variables are needed, using a [[PTPScript:Commands:Section|section]] may be more appropriate. | ||
| + | </note> | ||