\section{Lua Expressions and the Sandbox}
\label{sec:lua-expressions}

Most package keys do not take plain numbers. They take Lua source code that is
evaluated when the command runs. The source is evaluated in a read-only sandbox
that exposes the mathematical objects needed for scene construction while blocking
the usual dynamic-loading interfaces.

\subsection{Names available in the sandbox}

The following names are the ones most authors will use directly:

\begin{itemize}[leftmargin=2em]
\item \verb|Vector| and \verb|Matrix| for geometric construction;
\item \verb|math|, \verb|string|, \verb|table|, and related standard tables;
\item \verb|tau| as shorthand for $2\pi$;
\item any object previously defined with \verb|\setobject|.
\end{itemize}

The sandbox is read-only. User snippets cannot rebind globals and cannot load new
modules through \verb|require|, \verb|load|, \verb|loadfile|, \verb|dofile|,
\verb|package|, or \verb|debug|. Those names are blocked explicitly.

In practice it is best to brace any nontrivial key value, especially if the Lua
code spans multiple lines or contains commas that are not already protected by a
nested table literal. The examples below follow that convention.

\subsection{Expression keys versus block keys}

The package uses three related conventions.

\paragraph{Single-expression keys.}
Some keys behave like expressions and may omit \verb|return|. A transformation key
such as
\verb|transformation = Matrix.identity()|
is accepted because the package wraps the string in an implicit \verb|return|.

\paragraph{Block keys.}
Some keys are evaluated as full Lua chunks. Those keys should usually begin with
\verb|return| when the intent is to produce a value. The \verb|curve| key on
\verb|\appendsurface| is an example: it expects a chunk that returns a Lua table
describing parameter-space segments.

\paragraph{Function-body keys.}
The key \verb|v| on \verb|\appendcurve|, \verb|\appendsurface|, and
\verb|\appendsolid| is interpreted as the body of a Lua function in one, two, or
three parameters, respectively. In other words, the package builds
\verb|function(u) ... end|, \verb|function(u,v) ... end|, or
\verb|function(u,v,w) ... end| for you.

\subsection{Typical return types}

The most common return types are:

\begin{itemize}[leftmargin=2em]
\item a \verb|Vector:new{...}| for a point, direction, light, or parameter triple;
\item a \verb|Matrix:new{...}| for a triangle or transformation matrix;
\item a Boolean expression in a \verb|filter| body;
\item a Lua table returned by \verb|curve| on a surface.
\end{itemize}

The package rejects invalid or non-finite values. If a projection produces a
NaN, an infinity, or a degenerate simplex, the corresponding piece is not added
to the scene.

\subsection{Examples of each style}

\begin{Verbatim}
% Single-expression style.
transformation = {Matrix.identity()}

% Explicit block style.
object = {
  return Matrix.translate(Vector:new{0, 0, 2, 1})
    :multiply(Matrix.axis_angle(Vector:new{0, 1, 0, 1}, 0.5))
}

% Function-body style for a curve.
v = {return Vector:new{math.cos(u), math.sin(u), 0.3*u, 1}}

% Filter body style.
filter = {
  if A[3] < 0 then
    return false
  end
  return true
}
\end{Verbatim}

\subsection{Reusable objects}

The command \verb|\setobject| evaluates one Lua chunk and stores the result under
a chosen name. Every later snippet may refer to that name directly. This is the
most convenient way to share a transformation matrix, a point, a scalar, or even
a custom Lua function between multiple append commands.

\begin{Verbatim}
\setobject[
  name = frame,
  object = {
    return Matrix.axis_angle(Vector:new{1, 0, 0, 1}, 0.8)
      :multiply(Matrix.axis_angle(Vector:new{0, 0, 1, 1}, 0.4))
  }
]

\appendtriangle[
  m = {
        return Matrix:new{
          {-1, -1, 0, 1},
          { 1, -1, 0, 1},
          { 0,  1, 0, 1}
        }
      },
  transformation = {return frame},
  fill options = {fill=ltdtbrightness, draw=black}
]
\end{Verbatim}

Reserved base-environment names cannot be rebound through \verb|\setobject|.
In practice that means you should choose descriptive application names and avoid
trying to redefine \verb|Vector|, \verb|Matrix|, \verb|math|, and similar globals.

\input{figures/04-sandbox-diagram.tex}