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)

Info:

  • Copyright: 2011
  • License: MIT/X11
  • Author: Steve Donovan

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) 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.
getter.matching (get, accept) get a list of consecutive matching tokens.
substitute_tostring (src, name) 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 () Make require use macro expansion.


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.

Returns:

  1. the copy
  2. the token that matched the predicate
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)
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

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
getter.matching (get, accept)
get a list of consecutive matching tokens.

Parameters:

  • get token fetching function
  • accept set of token types (default: {space=true,comment=true})
substitute_tostring (src, name)
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

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 ()
Make require use macro expansion. This is controlled by package.mpath, which is initially './?.m.lua'
generated by LDoc 1.4.6 Last updated 2021-09-21 16:31:36