runlua: Portable Lua Invocation for POSIX

[William Ahern <william@...>]

Initial release of runlua.

PROJECT PAGE
============
http://www.25thandclement.com/~william/projects/runlua.html

DOWNLOAD
========
http://www.25thandclement.com/~william/projects/releases/runlua-20150122

DESCRIPTION
===========
runlua is a POSIX shell script for locating and invoking specific Lua
interpreter versions. For example, the environment's Lua 5.1 interpreter
might be named lua, lua5.1, lua51, luajit, luajit2.0.2, etc. runlua
automates this difficult task in a safe, portable manner. runlua is
regularly tested on Linux, OS X, Solaris, AIX, FreeBSD, NetBSD, and OpenBSD.
And runlua safely handles all special characters encountered in option
arguments, directory and command paths, and shell variables.

To execute a simple statement in either a Lua 5.2 or 5.3 interpreter:

   runlua -r5.2-5.3 -e "print(_VERSION)"

The command-line options to runlua are a superset of the standard Lua
interpreter. Run `runlua -h` for a description of each option.

Shebang (#!) Execution
----------------------
In addition to explicit invocation, runlua supports two modes of shebang
execution:

  #!/path/to/runlua -r5.2
  print"running Lua code!"

and

  #!/bin/sh
  echo "running shell code!"
  exec runlua -r5.2 -s"^exec" "$0" "$@"
  print "running Lua code!"

Only Linux and OS X support the first mode. The second is portable in
practice--although POSIX does not require sh to be located at
/bin/sh, it nonetheless can be invoked from that location on all the
environments I've tested.

Also, the first mode requires a fully qualified path name, whereas with the
second mode the shell code in the header can locate runlua dynamically. For
example, a regression or example script in a project repository might have a
header like

  #!/bin/sh
  PATH="${PATH}:$(dirname "$0")/../bin"
  exec "$(dirname "$0")/../contrib/runlua" -s"^exec" "$0" "$@"
  local mymodule = require"mymodule"
  -- ...

which will work regardless of the current working directory when invoking
the script.

USAGE
=====
Usage: runlua [-e:il:vEr:j:Js:tdpVh] [PATH [...]]
  -e STRING  execute statement
  -i         enter interactive mode after executing PATH
  -l STRING  require package
  -v         print interpreter version information
  -E         ignore environment variables
  -r RANGE   run specific Lua version
  -j RANGE   run specific LuaJIT version
  -J         exclude LuaJIT from candidate interpreters
  -s SKIP    line(s) to skip when loading script
  -t         preload POSIX threading library
  -d         enable debug logging
  -p         print path of Lua interpreter
  -V         print runlua version information
  -h         print this usage message

BNF:
  <PATH>    ::= <STRING>
  <RANGE>   ::= <VERSION> | [VERSION] "-" [VERSION]
  <VERSION> ::= <NUMBER> ["." <NUMBER> ["." <NUMBER>]]
  <SKIP>    ::= <NUMBER> | <PATTERN>
  <PATTERN> ::= <STRING>

Examples:
  -r5.2.1    only run PUC Lua 5.2.1 interpreter
  -r5.1      run any Lua 5.1 interpreter, including LuaJIT
  -r5.2-5.3  run any Lua 5.2 or 5.3 interpreter
  -r5.2-     run any Lua 5.2 or later interpreter
  -j2.1      only run LuaJIT 2.1 interpreter
  -s4        skip first 4 lines of script
  -s"^exec"  skip lines up to and including line matching ^exec

Report bugs to <william@25thandClement.com>