TODO

Things that need attention, categorized by estimated complexity.
That might not match reality, though:

Relatively Easy:
- More documentation!
- More tests! (and better tests)
- Improved build system.
  => luajit, lua, which? Which one by default? See TODO in Makefile.PL, too.
- Other Lua/Perl individual type conversions
- Expose Perl functions to Lua
  => In both cases, what's the syntax to mark a function as exported? Or
      should they all have transparent access to everything? That's overdoing
      it, isn't it?
- Add checks/exceptions to make sure that table objects passed back into
  a lua_State are referring to the same Lua state!
- Filehandles (see Inline::Lua)
  => Implemented Perl => Lua and ENTIRELY untested.
  => TODO: Implement Lua => Perl
- Figure out what Lua's ... should do on the Perl side and whether/how it's
  portable between 5.1/5.2/future.

Medium:
- Type conversion between Perl and Lua - Tables are hashes AND arrays. The fun!
  => Basic type conversion is mostly done: Design principle is that
     the receiving language will specify the conversion/marshalling behaviour
     to avoid confusion. Too much automation / cleverness here is likely to
     be counterproductive as Perl SVs are intrinsically ambiguous and Lua tables
     are Perl arrays + Perl hashes + then some.
- lua_State Perl abstraction (wrapper written in XS) with some of the
  main bits of interface wrapped for Perl.
  => Harder bit is figuring out how this ties in with function and table
     object ownership and lua_State object lifetime. Ugh refcounting?

Harder:
- Move much or all of global state to per-Perl-interpreter storage.
  => Without performance regression! (this makes it harder)
  => partial ithread-safety? The lexical access by offset is totally not thread safe.
- Concurrent Lua execution with multiple Lua interpreters?
  => Depends on having a lua_State abstraction exposed to Perl
  => Depends on having lua_State global state moved to per-interpreter logic
  => Likely quite hard to do sanely for the "PLua::Table" Lua table wrapper which is
     tied to a lua_State.
- Access to Perl globals where there's no lexicals (and adherence to use strict?)
- Design: Straight Perl array/hash accesses from Lua?
- Improved scanning/lexing for finding the end of the Lua blocks.
  => Requires a proper Lua parser. At least there's a BNF grammar for it!
- Is there a faster way of executing Lua snippets than using Lua refs to store the
  compiled Lua functions? I doubt it. But if so, please share!
- There needs to be a better way of implementing the syntax extensions to Lua
  that implement the Perl-specific bits (right now: Perl lexical access) than
  regexes. Maybe an extended Lua parser that does transformations and then
  faithfully regenerates Lua code with the same line numbers?
- Lua line numbers need to be file-level for better debuggability!

HARD:
- Make lexical Perl variable access thread-safe.
  => Right now, the lexical offsets here are going to refer to the thread that compiled
     the code, I believe, but they'll be shared by virtue of the OP tree being shared?
  => Requires learning a lot about the PADLIST/ithread connection (for Steffen)
- Make Lua functions be Perl-level closures for Perl lexicals.
  => A way to efficiently stash the PAD offsets
  => This seems fine now for getting perl lexicals:
     $foo.int, $foo.num, $foo.str all get compiled to a Lua C
     function call that uses the PAD offset (determined at compile
     time) to fetch the Perl lexical value.
  => Setting Perl lexicals: Currently grabs expression to end of line. Good enough?
  => pad_findlex (not API) is part of the answer if there is any. To wit, it contains:
        /* out_capture non-null means caller wants us to capture lex; in
         * addition we capture ourselves unless it's an ANON/format */
        new_capturep = out_capture ? out_capture :
                       CvLATE(cv) ? NULL : &new_capture;
  => Look for /* found in an outer CV. Add appropriate fake entry to this pad */ in pad.c
     => Need to emulate much of the code following that.
  => After learning from the master, I'm close to concluding that this won't work.