The msource() Function
In the macro package, pre-processing of the macro
code is accomplished by a special function: msource(). The
msource() function is similar to the source()
function in R. The msource() function will execute your
code, just like the source() function. First, however, it
will execute the macro pre-processor.
The steps can be summarized as follows:
Step 1: Pre-process the code and resolve all macro language
syntax.
Step 2: Generate a new code file with the resolved code.
Step 3: Execute the resolved code with the source()
function.
Notice that the above steps map directly to the way the SAS macro processor works.
In addition, the R macro language is a text-replacement language, just like SAS. Macro variables are swapped out with real values as text replacements. Macro conditions are evaluated, and only the code in the TRUE macro conditions is executed.
All of the above is handled by the msource() function.
msource() is the core function in the
macro package.
Parameters
The msource() function has several parameters. Here is a
short summary:
- pth: The path to the macro program.
- file_out: An optional path to store the generated code.
- envir: An optional environment to use for program execution.
- exec: A TRUE or FALSE value indicating whether to execute the generated code.
- debug: If TRUE, the function will generate additional debug information. By default, this information is sent to the console.
- debug_out: An optional file path to send the debug information.
- symbolgen: If TRUE, macro variable values are added to the debug information.
- echo: Echos the generated code to the console. TRUE by default.
- clear: Clears the macro symbol table and macro
function list at the beginning of every call to
msource(). TRUE by default.
Additional information about the msource() parameters is
available in the function reference.
How to Use
To use the macro package, you will first write your macro-enabled R code in a regular “.R” code file. You can use RStudio® or another code editor. The macro statements are written as special comments, as described above. You can execute a macro-enabled program in three different ways:
- From the console
- From a script
- From a keyboard shortcut
The below sections will elaborate on these different approaches.
Execute From the Console
To execute a macro-enabled program, simply call the
msource() function in the console and pass the program
path. If you want to save the generated code, or run in debug mode, pass
the appropriate parameters to msource().
The msource() function provides some convenience for
those people working in RStudio. If you are working in RStudio, the
function will use the path of the currently active program by default.
In that case, you don’t even need to pass the program path. Just call
msource() in the console with no parameters.
A simple example of executing a macro program from the console is provided below. For a more extensive example, please see Example 1.
Execute From a Script
The msource() function can also be sourced from a
regular R program. You can create a driver script to set up some macro
parameters, and then call the msource() function from the
driver.
For an example of a driver script, see Example 2 or Example 3.
Execute From a Keyboard Shortcut
The core features of the macro package are also available via the RStudio Addin menu and keyboard shortcuts. These features allow you to use the macro package interactively in RStudio. They make writing and debugging macro-enabled programs much easier.
See the Installation and Setup vignette for instructions on how to enable and use the macro keyboard shortcuts.
Example Macro Program
Here is what a simple macro-enabled program looks like:
Console Output
If you execute the msource() function in the console,
the above program will run and display the following:
> msource()
---------
library(procs)
library(macro)
# Analysis of 'mpg'
anl_mpg <- proc_means(mtcars, mpg, class = cyl,
output = report)
# Analysis of 'disp'
anl_disp <- proc_means(mtcars, disp, class = cyl,
output = report)
# Analysis of 'drat'
anl_drat <- proc_means(mtcars, drat, class = cyl,
output = report)
# Combine analysis
final <- list(anl_mpg, anl_disp, anl_drat)
# Print to console
print(final)
# Print to viewer
proc_print(final,
titles = c("Analysis of Selected MTCARS Variables",
"by cylinders"))
---------
[[1]]
CLASS VAR N MEAN STD MIN MAX
1 4 mpg 11 26.66364 4.509828 21.4 33.9
2 6 mpg 7 19.74286 1.453567 17.8 21.4
3 8 mpg 14 15.10000 2.560048 10.4 19.2
[[2]]
CLASS VAR N MEAN STD MIN MAX
1 4 disp 11 105.1364 26.87159 71.1 146.7
2 6 disp 7 183.3143 41.56246 145.0 258.0
3 8 disp 14 353.1000 67.77132 275.8 472.0
[[3]]
CLASS VAR N MEAN STD MIN MAX
1 4 drat 11 4.070909 0.3654711 3.69 4.93
2 6 drat 7 3.585714 0.4760552 2.76 3.92
3 8 drat 14 3.229286 0.3723618 2.76 4.22
The msource() console output contains two sections. The
first section is the generated code. The second section is any printed
output from the generated code. In this way, you can see what code was
actually sourced, and the output of that code.
If you do not wish to see the generated code, set the “echo”
parameter on msource() to FALSE.
Viewer Output
The above macro program also displayed the analysis in the RStudio viewer. It looks like this:
See the procs package
documentation for more information about the proc_means()
and proc_print() functions. Both the macro
package and the procs package are part of the sassy system of packages.