[metalua.git] / src / lib / walk.mlua

--------------------------------------------------------------------------------\r
-- Code walkers\r
--      "Make everything as simple as possible, but not simpler".\r
--\r
-- This library offers a generic way to write AST transforming\r
-- functions. Macros can take bits of AST as parameters and generate a\r
-- more complex AST with them; but modifying an AST a posteriori is\r
-- much more difficult; typical tasks requiring code walking are\r
-- transformation such as lazy evaluation or Continuation Passing\r
-- Style, but more mundane operations are required in more macros than\r
-- one would thing, such as "transform all returns which aren't inside\r
-- a nested function into an error throwing".\r
--\r
-- AST walking is an intrinsically advanced operation, and the\r
-- interface of this library, although it tries to remain as simple as\r
-- possible, is not trivial. You'll probably need to write a couple of\r
-- walkers with it before feeling comfortable.\r
--\r
--\r
-- We deal here with 3 important kinds of AST: statements, expressions\r
-- and blocks. Code walkers for these three kinds for AST are called\r
-- [walk.stat (cfg, ast)], [walk.expr (cfg, ast)] and [walk.block\r
-- (cfg, ast)] respectively. the [cfg] parameter describes what shall\r
-- happen as the AST is traversed by the walker, and [ast] is the tree\r
-- itself. \r
--\r
-- An aparte to fellow functional programmers: although Lua has\r
-- got all the features that constitute a functional language, its\r
-- heart, and in particular it table data, is imperative. It's often\r
-- asking for trouble to work against the host language's nature, so\r
-- code walkers are imperative, cope with it. Or use table.deep_copy()\r
-- if you don't want issues with shared state.\r
--\r
-- Since walkers are imperative (i.e. they transform the tree in\r
-- place, rather than returning a fresh variant of it), you'll often\r
-- want to override a node, i.e. keep its "pointer identity", but\r
-- replace its content with a new one; this is done by\r
-- table.override(), and is conveniently abbreviated as\r
-- "target <- new_content".\r
--\r
-- So, [cfg] can contain a series of sub-tables fields 'expr', 'stat',\r
-- 'block'. each of them can contain a function up() and/or a function\r
-- down(). \r
--\r
-- * down() is called when the walker starts visiting a node of the\r
--   matching kind, i.e. before any of its sub-nodes have been\r
--   visited.  down() is allowed to return either the string "break",\r
--   which means "don't go further down this tree, don't try to walk\r
--   its children", or nil, i.e. "please process with the children\r
--   nodes". \r
--\r
--   There are two reasons why you might want down() to return\r
--   "break": either because you really weren't interested into the\r
--   children nodes,or because you wanted to walk through them in a\r
--   special way, and down() already performed this special walking.\r
--\r
-- * up() is called just before the node is left, i.e. after all of\r
--   its children nodes have been completely parsed, down and up. This\r
--   is a good place to put treatments which rely on sub-nodes being\r
--   already treated. Notice that if down() returned 'break', up() is\r
--   run immediately after.\r
--\r
-- In previous versions of this library, there were plenty of fancy\r
-- configurable ways to decide whether an up() or down() functions\r
-- would be triggered or not. Experience suggested that the best way\r
-- is to keep it simpler, as done by the current design: the functions\r
-- in sub-table expr are run on each expression node, and ditto for\r
-- stat and block; the user is expected to use the pattern matching\r
-- extension to decide whether to act or not on a given node.\r
--\r
-- Advanced features\r
-- =================\r
--\r
-- The version above is a strict subset of the truth: there are a\r
-- couple of other, more advanced features in the library.\r
--\r
-- Paths in visitor functions\r
-- --------------------------\r
-- First, up() and down() don't take only one node as a parameter, but\r
-- a series thereof: all the nested expr/stat/block nodes on the way\r
-- up to the ast's root. For instance, when a walker works on\r
-- +{ foo(bar*2+1) } an is on the node +{2}, up() and down() are called\r
-- with arguments (+{bar*2}, +{bar*2+1}, +{foo(bar*2+1)}).\r
--\r
-- `Call and `Invoke as statements\r
-- -------------------------------\r
-- `Call and `Invoke are normally expressions, but they can also\r
-- appear as statements. In this case, the cfg.expr.xxx() visitors\r
-- aren't called on them. Sometimes you want to consider tham as\r
-- expressions, sometimes not, and it's much easier to add a special\r
-- case in cfg.stat.xxx() visitors than to determine whether we're in\r
-- a statament's context in cfg.expr.xxx(),\r
--\r
-- Extra walkers\r
-- -------------\r
-- There are some second class walkers: walk.expr_list() and walk.guess(). \r
--\r
-- * The first one walks through a list of expressions. Although used\r
--   internally by the other walkers, it remains a second class\r
--   citizen: the list it works on won't appear in the path of nested\r
--   ASTs that's passed to up() and down(). This design choice has\r
--   been made because there's no clear definition of what is or isn't\r
--   an expr list in an AST, and anyway such lists are probably not\r
--   part of metacoders' mental image of an AST, so it's been thought\r
--   best to let people pretend they don't exist.\r
--\r
-- * walk.guess() tries to guess the type of the AST it receives,\r
--   according to its tag, and runs the appropriate walker. Node which\r
--   can be both stats and exprs (`Call and `Invoke) are considered as\r
--   expr.\r
--\r
-- These three walkers, although used internally by the other walkers,\r
-- remain second class citizens: the lists they work on won't appear\r
-- in the path of nested ASTs that's passed to up() and down().\r
--\r
-- Tag dictionaries\r
-- ----------------\r
-- There are two public dictionaries, walk.tags.stat and\r
-- walk.tags.expr, which keep the set of all tags that can start a\r
-- statement or an expression AST. They're used by walk.guess, and\r
-- users sometimes need them as well, so they've been kept available.\r
--\r
-- Binder visitor\r
-- --------------\r
-- Finally, there's one last field in [cfg]: binder(). This function\r
-- is called on identifiers in a binder position, i.e. `Id{ } nodes\r
-- which create a scoped local variable, in `Function, `Fornum, `Local\r
-- etc. The main use case for that function is to keep track of\r
-- variables, captures, etc. and perform alpha conversions. In many\r
-- cases that work is best done through the library 'walk.id', which\r
-- understands the notions of scope, free variable, bound variable\r
-- etc. \r
--\r
-- Binder visitors are called just before the variable's scope starts,\r
-- e.g. they're called after the right-hand-side has been visited in a\r
-- `Local node, but before in a `Localrec node.\r
--\r
--------------------------------------------------------------------------------\r
\r
-{ extension "match" }\r
\r
walk = { traverse = { }; tags = { }; debug = false }\r
\r
--------------------------------------------------------------------------------\r
-- Standard tags: can be used to guess the type of an AST, or to check\r
-- that the type of an AST is respected.\r
--------------------------------------------------------------------------------\r
walk.tags.stat = table.transpose{ \r
   'Do', 'Set', 'While', 'Repeat', 'Local', 'Localrec', 'Return',\r
   'Fornum', 'Forin', 'If', 'Break', 'Goto', 'Label',\r
   'Call', 'Invoke' }\r
walk.tags.expr = table.transpose{\r
   'Paren', 'Call', 'Invoke', 'Index', 'Op', 'Function', 'Stat',\r
   'Table', 'Nil', 'Dots', 'True', 'False', 'Number', 'String', 'Id' }\r
\r
--------------------------------------------------------------------------------\r
-- These [walk.traverse.xxx()] functions are in charge of actually going through\r
-- ASTs. At each node, they make sure to call the appropriate walker.\r
--------------------------------------------------------------------------------\r
function walk.traverse.stat (cfg, x, ...)\r
   if walk.debug then printf("traverse stat %s", table.tostring(x)) end\r
   local log = {...}\r
   local B  = |y| walk.block       (cfg, y, x, unpack(log))\r
   local S  = |y| walk.stat        (cfg, y, x, unpack(log))\r
   local E  = |y| walk.expr        (cfg, y, x, unpack(log))\r
   local EL = |y| walk.expr_list   (cfg, y, x, unpack(log))\r
   local I  = |y| walk.binder_list (cfg, y, x, unpack(log))\r
   match x with\r
   | {...} if x.tag == nil -> for y in ivalues(x) do walk.stat(cfg, y, ...) end\r
                              -- no tag --> node not inserted in the history log\r
   | `Do{...}                    -> B(x)\r
   | `Set{ lhs, rhs }            -> EL(lhs); EL(rhs)\r
   | `While{ cond, body }        -> E(cond); B(body)\r
   | `Repeat{ body, cond }       -> B(body); E(cond)\r
   | `Local{ lhs }               -> I(lhs)\r
   | `Local{ lhs, rhs }          -> EL(rhs); I(lhs)\r
   | `Localrec{ lhs, rhs }       -> I(lhs); EL(rhs)\r
   | `Fornum{ i, a, b, body }    -> E(a); E(b); I{i}; B(body)\r
   | `Fornum{ i, a, b, c, body } -> E(a); E(b); E(c); I{i}; B(body)\r
   | `Forin{ i, rhs, body }      -> EL(rhs); I(i); B(body)\r
   | `If{...}                    -> for i=1, #x-1, 2 do E(x[i]); B(x[i+1]) end\r
                                    if #x%2 == 1 then B(x[#x]) end\r
   | `Call{...}|`Invoke{...}|`Return{...} -> EL(x)\r
   | `Break | `Goto{ _ } | `Label{ _ }    -> -- nothing\r
   | {...} if walk.tags.stat[x.tag]-> \r
      printf("Warning: walk: malformed %s stat node: %s", x.tag, table.tostring(x,80))\r
   | {...} -> print("Warning: walk: unknown stat node: "..table.tostring(x,80))\r
   | _     -> print("Warning: walk: unexpected stat node of type "..type(x)\r
                    ..": "..table.tostring(x,80))\r
   end\r
end\r
\r
function walk.traverse.expr (cfg, x, ...)\r
   if walk.debug then printf("traverse expr %s", table.tostring(x)) end\r
   local log = {...}\r
   local B  = |y| walk.block       (cfg, y, x, unpack(log))\r
   local S  = |y| walk.stat        (cfg, y, x, unpack(log))\r
   local E  = |y| walk.expr        (cfg, y, x, unpack(log))\r
   local EL = |y| walk.expr_list   (cfg, y, x, unpack(log)) \r
   local I  = |y| walk.binder_list (cfg, y, x, unpack(log))\r
   match x with\r
   | `Paren{ e }               -> E(e)\r
   | `Call{...} | `Invoke{...} -> EL(x)\r
   | `Index{ a, b }            -> E(a); E(b)\r
   | `Op{ opid, ... }          -> E(x[2]); if #x==3 then E(x[3]) end\r
   | `Function{ params, body } -> I(params); B(body)\r
   | `Stat{ b, e }             -> B(b); E(e)\r
   | `Table{ ... }             ->\r
      for i = 1, #x do match x[i] with\r
         | `Pair{ k, v } -> E(k); E(v)\r
         | v            -> E(v)\r
      end end\r
   |`Nil|`Dots|`True|`False|`Number{_}|`String{_}|`Id{_} -> -- nothing \r
   | {...} if walk.tags.expr[x.tag]-> \r
      printf("Warning: walk: malformed %s expr node: %s", x.tag, table.tostring(x,80))\r
   | {...} -> print("Warning: walk: unknown expr node: "..table.tostring(x,80))\r
   | _     -> print("Warning: walk: unexpected expr node of type "..type(x)\r
                    ..": "..table.tostring(x,80))\r
   end\r
end\r
\r
function walk.traverse.block (cfg, x, ...)\r
   assert(type(x)=='table', "traverse.block() expects a table")\r
   for y in ivalues(x) do walk.stat(cfg, y, x, ...) end\r
end\r
\r
function walk.traverse.expr_list (cfg, x, ...)\r
   assert(type(x)=='table', "traverse.expr_list() expects a table")\r
   -- x doesn't appear in the log\r
   for y in ivalues(x) do walk.expr(cfg, y, ...) end\r
end\r
\r
----------------------------------------------------------------------\r
-- Generic walker generator.\r
----------------------------------------------------------------------\r
local walker_builder = |cfg_field, traverse| function (cfg, x, ...)\r
   local sub_cfg  = cfg[cfg_field] or { }\r
   local broken   = false\r
   if sub_cfg.down then\r
      if sub_cfg.down=='break' then broken='break'\r
      else broken = sub_cfg.down (x, ...) end\r
      assert(not broken or broken=='break', \r
             "Map functions must return 'break' or nil")\r
   end\r
   if not broken then traverse (cfg, x, ...) end\r
   if sub_cfg.up then sub_cfg.up (x, ...) end\r
end\r
\r
----------------------------------------------------------------------\r
-- Declare [walk.stat], [walk.expr], [walk.block] and [walk.expr_list]\r
----------------------------------------------------------------------\r
for w in values{ "stat", "expr", "block", "expr_list" } do\r
   walk[w] = walker_builder (w, walk.traverse[w])\r
end\r
\r
----------------------------------------------------------------------\r
-- Walk a list of `Id{...} (mainly a helper function actually).\r
----------------------------------------------------------------------\r
function walk.binder_list (cfg, x, ...)\r
   local f = cfg.binder \r
   if f then for v in ivalues(x) do f(v, ...) end end\r
end\r
\r
----------------------------------------------------------------------\r
-- Tries to guess the type of the AST then choose the right walkker.\r
----------------------------------------------------------------------\r
function walk.guess (cfg, x, ...)\r
   assert(type(x)=='table', "arg #2 in a walker must be an AST")\r
   if walk.tags.expr[x.tag] then return walk.expr(cfg, x, ...)  end\r
   if walk.tags.stat[x.tag] then return walk.stat(cfg, x, ...)  end\r
   if not x.tag             then return walk.block(cfg, x, ...) end\r
   error ("Can't guess the AST type from tag "..(x.tag or '<none>')) \r
end\r