Macros are expanded at compile time, not at run time.

It's difficult to write a macro if you don't keep this in mind, so be sure to keep this in mind when writing a macro.

Here's a simple macro example:

// @lnsFront: ok
macro _Hello() {
   print( "hello world" );
}
_Hello(); // hello world

This is the macro _Hello that prints hello world.

Macro definitions use the macro keyword.

This example is a macro that is no different from using a function definition, so there is no point in defining it as a macro.

However, it is a good example to convey that "macros can be defined in the same way as function definitions".

In programming languages with macros, macro definitions often require special processing unlike general function definitions.

As a result, the hurdles of the mind rise, saying, "Macro seems to be something difficult."

However, in LuneScript, like the hello world sample above, you can define macros in the same way as defining functions in general.

However, you cannot define a meaningful macro by writing a macro like the example above.

Below we'll show you how to define meaningful macros.

Here's an example of a slightly more practical macro:

This macro has the following specifications:

• A macro _Test that defines a function that returns an int value
• The int value returned by the function is given as an argument to the macro
• The name of the defined function is determined by the value of int
• Specifically, the function name that returns 1 is func1

Here is the code for the specific macro:

// @lnsFront: ok
macro _Test( val:int ) {
   {
      let name = "func%d"(val);
   }
   fn ,,,name(): int {
      return ,,val;
   }
}

_Test( 1 );
_Test( 10 );

print( func1(), func10() ); // 1  10

When expanding a macro, it's pretty much the same as a function call.

In this case, _Test( 1 ), _Test( 10 ) are macro expansions. _Test( 1 ), _Test( 10 ) expands to

// @lnsFront: ok
// Test( 1 )
fn func1():int {
   return 1;
}
// Test( 10 )
fn func10():int {
   return 10;
}

This defines functions func1() and func10() , so print( func1(), func10() ) outputs 1 10 .

This macro is described below.

The macro definition syntax is:

// @lnsFront: skip
macro name( arg ) {
   {
      macro-statement
   }
   expand-statement
}

It starts with the keyword macro, followed by the macro name name and the arguments arg. Macro name name must start with _. Conversely, non-macro symbol names must not start with _.

Macro arguments support the following types:

• int
• real
• str
• bool
• stat
• List, Map, Set above
• sym
• __exp
• __block

sym, stat, __exp, and __block are described below.

Next comes the macro-statement block, followed by the expand-statement .

To understand how to define a macro, it is easier to understand expand-statement first, so expand-statement will be explained before explaining the macro-statement block.

// @lnsFront: skip
   fn ,,,name(): int {
      return ,,val;
   }

// @lnsFront: ok
fn func1():int {
   return 1;
}

// @lnsFront: skip
   {
      let name = "func%d"(val);
   }

// @lnsFront: ok
macro _Test( val:int ) {
   {
      fn funcname(): str {
         return "func%d"(val);
      }
      let name = funcname();
   }
   fn ,,,name(): int {
      return ,,val;
   }
}

// @lnsFront: ok
macro _Test( val:int ) {
   {
      let defstat = `{
         fn ,,,"func%d"(val)~~():int {
            return ,,val;
         }
      };
   }
   ,,defstat;
}

_Test( 1 );
_Test( 10 );

print( func1(), func10() ); // 1  10

// @lnsFront: skip
      let defstat = `{
         fn ,,,"func%d"(val)~~():int {
            return ,,val;
         }
      };

// @lnsFront: ok
macro _Test( val:int ) {
   {
      let mut statList:List<stat> = [];
      for count = 1, val {
         statList.insert(
            `{          
               fn ,,,"func%d"(count)~~():int {
                  return ,,count;
               }
            } );
      }
   }
   ,,statList;
}

_Test( 5 );

print( func1(), func2(), func3(), func4(), func5() ); // 1 2 3 4 5

// @lnsFront: skip
macro name( arg ) {
   expand-statement
}

Macros can be exposed to external modules.

By declaring pub as follows, the macro can be used at the import destination.

// @lnsFront: ok
pub macro _Hello() {
   print( "hello world" );
}

Here is an example of a slightly more practical macro.

In order to handle JSON used in parameters and responses of REST API provided by Google etc. with LuneScript, it is convenient to classify each JSON format of REST API. In such a case, manually defining a class that handles various types of JSON format data is inefficient and causes bugs.

So let's create a macro that loads the sample JSON format and defines a class that can store that JSON format.

For this example, load the following JSON file,

{
    "val1": "abc",
    "val2": 0
}

A macro that defines the following classes for handling the above JSON.

// @lnsFront: ok
class Hoge {
  pri let val1:str {pub};
  pri let val2:int {pub};
}

Here is a concrete example of a macro:

// @lnsFront: skip
macro _MkClass( name:str, path:str ) {
   {
      let mut memStatList:List<stat> = [];
      if! let mut fileObj = io.open( path ) {
         if! let txt = fileObj.read( "*a" ) {
            let defMap = "pub let val = %s;" (txt);
            let mod = _lnsLoad( "json", defMap );
            if! let jsonval = mod.val {
               fn getType( val:stem ): str {
                  switch type( val ) {
                     case "number" {
                        return "int";
                     }
                     case "string" {
                        return "str";
                     }
                  }
                  return "stem";
               }
               forsort val, key in jsonval@@Map<str,stem> {
                  memStatList.insert( `{
                     pri let ,,,key : ,,,getType( val )~~ {pub};
                  } );
               }
            }
         }
      }
   }
   class ,,,name {
      ,,memStatList;
   }
}
_MkClass( "Hoge", "hoge.js" );

let hoge = new Hoge( "ABC", 100 );
print( hoge.$val1, hoge.$val2 );

This macro loads JSON from a file and declares a class to store the JSON structure.

Specify the class name in the first argument of the macro.

This macro does the following:

• Open the specified file and read the JSON string defined in that file.
• Generate LuneScript code from JSON string txt with "pub let val = %s;" (txt);
• Use _lnsLoad() to load the generated LuneScript code
• Extract json val from loaded module and enumerate JSON elements with forsort
• Generate `{} declaring a member holding the enumerated elements and add it to memStatList
• Declare a class with name and memStatList.

In this example, the members are treated as int and str type data for simplicity. It does not support lists etc.

Macros are actions that are performed at compile time. Also, each macro execution is independent. When executing two macros A and B, it is not possible to change the control of macro B depending on the execution result of macro A.

However, this can be inconvenient. Therefore, common map between macros is used to share data within macros.

*This is an experimental feature.

From within the macro-statement of the macro, the special variable __var is available.

The special variable __var has the following restrictions:

• public macros cannot use __var
• Macros that access __var must be used from the same namespace that defines the macro.
• If __var is accessed from a different namespace, the contents of that __var are undefined.

The type of this variable is:

let mut __var:Map<str,stem>

This variable is created at the start of compilation for each module, and all macros access the same variable.

For example:

// @lnsFront: ok
   macro _test0( name:str, val:int ) {
      {
         __var[ name ] = val;
      }
   }
   macro _test1() {
      {
         let val;
         if! let work = __var[ "hoge" ] {
            val = work@@int;
         }
         else {
            val = 10;
         }
      }
      print( "%s" (,,val) );
   }
   _test0( "hogea", 1 );
   _test1(); // 10
   _test0( "hoge", 1 );
   _test1(); // 1

In this example, the _test0() macro holds the int data in __var[ "hoge" ] and the _test1() macro changes the processing depending on the stored value of __var[ "hoge" ].