module Crystal::Macros

Overview

The Macros module is a fictitious module used to document macros
and macro methods.

You can invoke a fixed subset of methods on AST nodes at compile-time. These methods
are documented on the classes in this module. Additionally, methods of the
Macros module are top-level methods that you can invoke, like #puts and #run.

Compiles and execute a Crystal program and returns its output
as a MacroId.

The file denote by filename must be a valid Crystal program.
This macro invocation passes args to the program as regular
program arguments. The program must output a valid Crystal expression.
This output is the result of this macro invocation, as a MacroId.

The #run macro is useful when the subset of available macro methods
are not enough for your purposes and you need something more powerful.
With #run you can read files at compile time, connect to the internet
or to a database.

The above generates a program that will have the contents of some_file.txt.
The file, however, is read at compile time and will not be needed at runtime.

NOTE the compiler is allowed to cache the executable generated for
filename and only recompile it if any of the files it depends on changes
(their modified time). This is why it's strongly discouraged to use a program
for #run that changes in subsequent compilations (for example, if it executes
shell commands at compile time, or other macro run programs). It's also strongly
discouraged to have a macro run program take a lot of time, because this will
slow down compilation times. Reading files is OK, opening an HTTP connection
at compile-time will most likely result if very slow compilations.

Skips the rest of the file from which it is executed.
Typical usage is to skip files that have platform specific code,
without having to surround the most relevant code in {% if flag?(...) %} ... {% end %} macro blocks.