Written June 2023
"Transclude" (aka "transcopy") is built on the same framework as MX_TRANSCOPY. It can be integrated into any of the existing ++include variants by adding one or two additional comma-delimited parameters:
++include includespec {,tcfspec {,section}}
If the tcfspec parameter is specified, it must identify a Transcopy Configuration File (TCF) that follows the rules described for MX_TRANSCOPY above.
If the section parameter is not included, then only the common section of the TCF (at the top, before any [section] headers) is processed. Otherwise, the common section plus the specified section is processed. Specifying a section that does not exist is considered an error, but a TCF file with no relevant search/replace patterns simply reverts back to an ordinary ++include operation.
The concept here is to allow the use of generalized (or quasi-template) include files that can be customized at compile time for different uses, rather than having to maintain multiple separate include file variations.
To debug the operation, you can either consult the LSX file, which will contain the result of each transclude operation, or use the MX_TRANSCOPY function.
Note that ++include'once takes into account the TCF and section, allowing the same original include file to be included multiple times, each with different TCF. But, if the include file contains a compiler directive to prevent multiple inclusions (e.g. ++IFNDEF, ++IFNLBL, etc.), then the parent program would need to take additional action to override it—for example, with an explicit ++UNDEF prior to the additional ++include directives.
Also note that in APN, using the Goto Definition function to locate the definition of a function or other symbol will take you to the original version of the include file. For example, if you have a function Fn'Foo() in an include file FOO.BSI, and you use the transclude feature to include a variation of the function called Fn'Foo2(), using the Goto Definition function on a reference to Fn'Foo2() will take you to the definition of Fn'Foo() in FOO.BSI. Fn'Foo2() only exists virtually so there is no practical way to jump to its source code.
History
2023 June, A-Shell 6.5.1732: Transclude function added.
