Expand macro functionality

[kenkellner]

This PR expands macro functionality in nimble:

1. Macros can modify and add constants and add inits
2. Macros automatically determine which new parameters they created and store this info
3. "Comments" now allowed in model code (lines containing only a character string)
4. Macros can auto-generate and add comments to the model code
5. Extra curly brackets in macro output are cleaned up automatically

Detailed changes

1. Key macro functionality

• Expands the section in the setupModel method of modelDefClass which is activated only when enableModelMacros option is TRUE. This is where all the macro processing happens, primarily via the codeProcessModelMacros function. codeProcessModelMacros and supporting functions (the vast majority of code in this PR) are now found in the `BUGS_macros.R' file.

• A new section in the nimbleModel function which is activated only when enableModelMacros is TRUE. This section is required to make sure that any modifications to the constants and inits by macros are actually used by nimble.

2. Exported functions

• One new exported function: getMacroParameters (see below), marked as EXPERIMENTAL in the title. Has docs via Roxygen.
• Technically, model_macro_builder (which is already in nimble before this PR) could live in the nimbleMacros package instead, I'm not sure we ever decided on that.

3. Changes to reference classes

• Two new fields in RC modelDefClass: macroParameters (a list of parameters created by macros) and macroInits (inits created by macros). These are set to NULL if macros are not enabled.
• Two new methods in RC modelDefClass: assignMacroInits and assignMacroParameters for setting the above.
• Three new methods in RC modelBaseClass: getMacroParameters, getMacroInits for users to easily access info in the new fields above, and getConstants which is just a shortcut to return the constants.

4. New nimbleOptions

• Two new nimbleOptions: enableMacroComments which toggles auto-generation of comments indicating which macro new code came from, and
• codeInMacroComments, which instead of just indicating the macro name in the comments, shows the entire source line of code.

5. Other stuff:

• When enableModelMacros is TRUE, nimble will now convert factors (or character vectors/arrays) found in the constants into equivalent numeric form, allowing use of factors in macros like the linear predictor macro I demonstrated. This happens in the codeProcessModelMacros function. When enableModelMacros is FALSE, factors should continue to behave as previously.
• At the end of the processBUGSCode method for modelDefClass, I made a small change so that nimble ignores (passes through) lines of code which are just a single character string, which I now use as "comments". At the moment this occurs regardless of whether macros are enabled, but doesn't seem to have any side effects.

Tests

I've added a bunch of tests for the above in the test-macros.R file. They all run cleanly for me. I've struggled to get the full test suite to run locally but ran a few seemingly relevant single test files and all seemed well. Hopefully I haven't overlooked anything.

Examples

See the help file for model_macro_builder and getMacroParameters, and test-macros.R for example code.

Manual

Nothing yet, not sure if it's the right time to add things to the manual.

[kenkellner]

@perrydv @paciorek I've made nearly all the suggested changes. Just a couple of notes.

• I didn't change the internals of getMacroParameters - if it becomes as bottleneck for some reason I will revisit this.
• Regarding the stop_after_processing_the_model_code option, you may want to take a closer look at 943a26dac. The problem was that the option wasn't checked until after processBUGScode was executed (the source of the repeated-index error) and thus had no effect. The comments imply the check should actually happen just after if/else and macro processing, so I moved it up to before processBUGScode. It makes the option name slightly more confusing, though.

[perrydv]

Thanks @kenkellner . This looks great and thanks for attending to the points we emailed about. I think the only remaining test failure will be fixed by the --preclean PR and is not due to this PR. It looks like the "stop_after_processing_model_code" option is only used in one place (and did not get much use, I think), so I am fine with slightly repurposing it by the move up a few lines of code that you figured out. That seemed like the only slightly tricky issue and is a simple fix.

My only extremely minor last tweak would be to replace if(nimbleOptions("stop_after_processing_model_code")) with if(isTRUE(getNimbleOption("stop_after_processing_model_code"))) where the isTRUE protects against an error if the option is somehow removed from the list or set to some non-logical value and the getNimbleOption should access a single option more directly.