Module macro

LuaMacro 2, a macro-preprocessor for Lua.

Unlike LuaMacro 1.x, it does not depend on the token-filter patch and generates Lua code which can be printed out or compiled directly. C-style macros are easy, but LM2 allows for macros that can read their own input and generate output using Lua code. New in this release are lexically-scoped macros. The Lua Lpeg Lexer is by Peter Odding.

Examples:

 macro.define 'sqr(x) ((x)*(x))'
 macro.define 'assert_(expr) assert(expr,_STR_(expr))'
 macro.define('R(n)',function(n)
   n = n:get_number()
   return ('-'):rep(n)
 end
 macro.define('lazy',function(get)
    get() -- skip space
    local expr,endt = get:upto(function(t,v)
        return t == ',' or t == ')' or t == ';'
          or (t=='space' and v:match '\n')
    end)
    return 'function(_) return '..tostring(expr)..' end'..tostring(endt)
 end)

Defining and Working with Macros

copy_tokens (tok, pred) make a copy of a list of tokens.
define_tokens (extra) define new lexical tokens.
define (macstr, subst_fn) define a macro using a specification string and optional function.
set_macro (name, subst, parms) define a macro using a function and a parameter list.
define_scoped (name, subst, parms) defined a scoped macro.
get_macro_value (name) get the value of a macro.
push_macro_stack (name, value) push a value on the stack associated with a macro.
pop_macro_stack (name) pop a value from a macro stack.
value_of_macro_stack (name) value of top of macro stack.
block_handler (lev, action) specify a block handler at a given level.
keyword_handler (word, action) set a keyword handler.
scoped_keyword_handler (word, action, keyword) set a scoped keyword handler.
error (msg) macro error messages.
assert (expr, msg) macro error assert.
substitute (src, out, name, use_c) do a macro substitution on Lua source.
substitute_tostring (src, name, use_c, throw) take some Lua source and return the result of the substitution.
load (src, name, env) load Lua code in a given envrionment after passing through the macro preprocessor.
eval (src, env) evaluate Lua macro code in a given environment.
set_package_loader (ext) Make require use macro expansion for a given extension.


Defining and Working with Macros

copy_tokens (tok, pred)
make a copy of a list of tokens.

Parameters:

  • tok: the list
  • pred: copy up to this condition; if defined, must be a function of two arguments, the token type and the token value.
define_tokens (extra)
define new lexical tokens.

Parameters:

  • extra: a list of strings defining the new tokens

Usage:

    macro.define_tokens{'{|'}
define (macstr, subst_fn)
define a macro using a specification string and optional function. The specification looks very much like a C preprocessor macro: the name, followed by an optional formal argument list (no space after name!) and the substitution. e.g answer 42 or sqr(x) ((x)*(x))

If there is no substitution, then the second argument must be a function which will be evaluated for the actual substitution. If there are explicit parameters, then they will be passed as token lists. Otherwise, the function is passed a get and a put argument, which are Getter and TokenList objects.

The substitution function may return a TokenList object, or a string.

Parameters:

  • macstr:
  • subst_fn: the optional substitution function

see also:

set_macro (name, subst, parms)
define a macro using a function and a parameter list.

Parameters:

  • name: either an identifier or an operator.
  • subst: a function
  • parms: a list of parameter names

Returns:

    the existing value of this macro, if any
define_scoped (name, subst, parms)
defined a scoped macro. Like define except this macro will not be visible outside the current scope.

Parameters:

  • name: either an identifier or an operator.
  • subst: a function
  • parms: a list of parameter names

see also:

get_macro_value (name)
get the value of a macro. The macro substitution must either be a a string or a single token.

Parameters:

  • name: existing macro name

Returns:

    a string value, or nil if the macro does not exist.
push_macro_stack (name, value)
push a value on the stack associated with a macro.

Parameters:

  • name: macro name
  • value: any value
pop_macro_stack (name)
pop a value from a macro stack.

Parameters:

  • name: macro name

Returns:

    any value, if defined
value_of_macro_stack (name)
value of top of macro stack.

Parameters:

  • name: macro name

Returns:

    any value, if defined
block_handler (lev, action)
specify a block handler at a given level. a block handler may indicate with an extra true return that it wants to persist; it is passed the getter and the keyword so we can get more specific end-of-block handlers.

Parameters:

  • lev: relative block level
  • action: will be called when the block reaches the level
keyword_handler (word, action)
set a keyword handler. Unlike macros, the keyword itself is always passed through, but the handler may add some output afterwards. If the action is nil, then the handler for that keyword is removed.

Parameters:

  • word: keyword
  • action: function to be called when keyword is encountered

Returns:

    previous handler associated with this keyword
scoped_keyword_handler (word, action, keyword)
set a scoped keyword handler. Like keyword_handler, except it restores the original keyword handler (if any) at the end of the current block.

Parameters:

  • word: keyword
  • action: to be called when keyword is encountered
  • keyword:

see also:

error (msg)
macro error messages.

Parameters:

  • msg: the message: will also have file:line.
assert (expr, msg)
macro error assert.

Parameters:

  • expr: an expression.
  • msg: a message
substitute (src, out, name, use_c)
do a macro substitution on Lua source.

Parameters:

  • src: Lua source (either string or file-like reader)
  • out: output (a file-like writer)
  • name: input file name
  • use_c: nil for Lua; if 'line', then output #line directives; if true, then don't

Returns:

  1. the result as table of strings
  2. line number information
substitute_tostring (src, name, use_c, throw)
take some Lua source and return the result of the substitution. Does not raise any errors.

Parameters:

  • src: either a string or a readable file object
  • name: optional name for the chunk
  • use_c:
  • throw:

Returns:

  1. the result or nil
  2. the error, if error
load (src, name, env)
load Lua code in a given envrionment after passing through the macro preprocessor.

Parameters:

  • src: either a string or a readable file object
  • name: optional name for the chunk
  • env: the environment (may be nil)

Returns:

  1. the cnunk, or nil
  2. the error, if no chunk
eval (src, env)
evaluate Lua macro code in a given environment.

Parameters:

  • src: either a string or a readable file object
  • env: the environment (can be nil)

Returns:

  1. true if succeeded
  2. result(s)
set_package_loader (ext)
Make require use macro expansion for a given extension.

Parameters:

  • ext: the extension - default is 'm.lua'