Differences between version #14424 and #14425

1c1
< Some languages features such as C ''#define'' enable the user to define syntax shortcuts. They are useful to perform some pseudo-code-generation, but at the same time allow to modify the syntax of the language, making the code unreadable for other developers.
---
> Some languages features such as C ''#define'' enable the user to define syntax shortcuts. They are useful for performing some pseudo-code-generation, but at the same time they allow you to modify the syntax of the language, making the code unreadable for other developers.
20c20
< Each macro function must return an //expression// which correspond to the block of code that will replace the macro call. Please note that unlike //inline// functions you can do actual code generation inside the macro.
---
> Each macro function must return an //expression// which corresponds to the block of code that will replace the macro call. Please note that unlike //inline// functions you can do actual code generation inside the macro.
24c24
< The expression itself is an enum that is declared in the [[/api/haxe/macro/Expr|haxe.macro.Expr]] package
---
> The expression itself is an enum that is declared in the [[/api/haxe/macro/Expr|haxe.macro.Expr]] package.
28c28
< The ''haxe.macro.Context'' API can be used inside macros in order to query some contextual informations about the code at the place the macro is being called.
---
> The ''haxe.macro.Context'' API can be used inside macros in order to query some contextual information about the code at the place the macro is being called.
30c30
< Read [[/api/haxe/macro/Context]] API documentation for more detailed informations.
---
> Read [[/api/haxe/macro/Context]] API documentation for more detailed information.
34c34
< Macro can take one or several //expression// parameters, that can be manipulated in many different ways. Here's for example a macro that will repeat n times the same expression :
---
> Macro can take one or several //expression// parameters that can be manipulated in many different ways. For example, here's a macro that will repeat the same expression n times:
61c61
< And here's an example on how to use it :
---
> And here's an example of how to use it :
73c73
< If a macro has two ''Expr'' parameters, you will be able to call it with two and only two expressions. If you want your macro to take a **variable number of parameters**, you must accept a single ''Array<Expr>'' parameter :
---
> If a macro has two ''Expr'' parameters, you will be able to call it with two and only two expressions. If you want your macro to take a **variable number of parameters**, you must accept a single ''Array<Expr>'' parameter like so:
107c107
< In order to improve this, you can use ''ExprOf'' type that will specify which type to show when doing completion :
---
> In order to improve this, you can use the ''ExprOf'' type that will specify which type to show when doing completion :
115c115
< Please note that this only a tip : it will not enforce that the expression is of the given type.
---
> Please note that this only a tip : it will not enforce making the expression into the given type.
146c146
< It is possible to use [[/manual/using]] together with macros. However, if you want your macro to be only applicable to a given type, you need to use ''ExprRequire'' type to specify that you will only accept expressions of the given type :
---
> It is possible to use [[/manual/using]] together with macros. However, if you want your macro to be only applicable to a given type, you need to use the ''ExprRequire'' type to specify that you will only accept expressions of the given type :
160c160
< //New in 2.10//: Fields are evaluated and typed from left to right which **might cause some AST changes**. This means that "using" two macro calls subsequently, such as ''"foo".macro1().macro2()'', has a different meaning the standard ''macro2(macro1("foo"))'' variant. In the former case, the **result** of the call to ''macro1("foo")'' will be passed as argument to ''macro2'', while in the latter the **call** to ''macro1'' itself will be passed to ''macro2''.
---
> //New in 2.10//: Fields are evaluated and typed from left to right which **might cause some AST changes**. This means that "using" two macro calls subsequently, such as ''"foo".macro1().macro2()'', has a different meaning than the standard ''macro2(macro1("foo"))'' variant. In the former case, the **result** of the call to ''macro1("foo")'' will be passed as an argument to ''macro2'', while in the latter the **call** to ''macro1'' itself will be passed to ''macro2''.
172c172
< This will turn all static methods of this class into macro-functions. Please note that this prevent you from having helper static functions since they will be macros as well, and not normal functions.
---
> This will turn all static methods of this class into macro-functions. Please note that this prevents you from having helper static functions since they will be macros as well, and not normal functions.
176c176
< You can also include/exclude some code depending if you are running into the macro emulator, by using ''#if macro'' //conditional compilation//. For example :
---
> You can also include/exclude some code depending on if you are running in the macro emulator, by using ''#if macro'' //conditional compilation//. For example :
190c190
< Macros are executed directly into the Haxe compiler by using a ''neko'' platform emulator. Most of the [[/api/neko]] package API are supported inside macros and should behave the same as they do when running inside the NekoVM.
---
> Macros are executed directly into the Haxe compiler by using a ''neko'' platform emulator. Most of the [[/api/neko]] package API is supported inside macros and should behave the same as they do when running inside the NekoVM.
200c200
< In order to create per-class data that take into account the fields and/or inheritance, you can use ''haxe.macro.Context.onGenerate'' to register a callback that will run once your project is entirely compiled, prior to being generated for the target platform.
---
> In order to create per-class data that takes into account the fields and/or inheritance, you can use ''haxe.macro.Context.onGenerate'' to register a callback that will run once your project is entirely compiled, prior to being generated for the target platform.
213c213
< Since macro needs to run for every compilation, it is sometimes necessary to take performances into account. Here's a few tips for improving macro performances :
---
> Since macro needs to run for every compilation, it is sometimes necessary to take performance into account. Here's a few tips for improving macro performance :
216c216
< 	* disable processing in completion : since many IDE rely on the Haxe compiler for handling the autocompletion, sometimes macro execution will make autocompletion slower. You can disable some parts of the macro processing when running in completion mode, this can be checked with ''haxe.macro.Context.defined('display')''
---
> 	* disable processing in completion : since many IDEs rely on the Haxe compiler for handling the autocompletion, sometimes macro execution will make autocompletion slower. You can disable some parts of the macro processing when running in completion mode—this can be checked with ''haxe.macro.Context.defined('display')''
223c223
< This affects of course macros as well, here's a few tips on how to deal with it :
---
> This of course affects macros as well; here's a few tips on how to deal with it :
226c226
<   * if your macro produce code based on other files that are not part of the compilation process, you can use ''haxe.macro.Context.registerModuleDependency'' to inform the compiler that each that file is changed the corresponding module needs to be recompiled
---
>   * if your macro produces code based on other files that are not part of the compilation process, you can use ''haxe.macro.Context.registerModuleDependency'' to inform the compiler that if that file is changed the corresponding module needs to be recompiled