hs.httpserver.hsminweb.cgilua.lp.md

docs » hs.httpserver.hsminweb.cgilua.lp

---

Support functions for the CGILua compatibility module for including and translating Lua template pages into Lua code for execution within the Hammerspoon environment to provide dynamic content for http requests.

The most commonly used function is likely to be cgilua.lp.include, which allows including a template driven file during rendering so that common code can be reused more easily. While passing in your own environment table for upvalues is possible, this is not recommended for general use because the default environment passed to each included file ensures that all server variables and the CGILua compatibility functions are available with the same names, and any new non-local (i.e. "global") variable defined are shared with the calling environment and not shared with the Hammerspoon global environment.

If your template file requires the ability to create variables in the Hammerspoon global environment, access the global environment directly through _G.

Note that the above considerations only apply to creating new "global" variables. Any currently defined global variables (for example, the hs table where Hammerspoon module functions are stored) are available within the template file as long as no local or CGILua environment variable shares the same name (e.g. _G["hs"] and hs refer to the same table.

See the documentation for the cgilua.lp.include for more information.

API Overview

• Functions - API calls offered directly by the extension
• compile
• include
• translate

API Documentation

Functions

compile

Signature	hs.httpserver.hsminweb.cgilua.lp.compile(source, name, [env]) -> function
Type	Function
Description	Converts the specified Lua template source into a Lua function.
Parameters	source - a string containing the contents of a Lua/HTML template to be converted into a function name - a label used in an error message if execution of the returned function results in a run-time error env - an optional table specifying the environment to be used by the lua builtin function load when converting the source into a function. By default, the function will inherit its caller's environment.
Returns	A lua function which should take no arguments.
Notes	The source provided is first compared to a stored cache of previously translated templates and will re-use an existing translation if the template has been seen before. If the source is unique, cgilua.lp.translate is called on the template source. This function is used internally by cgilua.lp.include, and probably won't be useful unless you want to translate a dynamically generated template -- which has security implications, depending upon what inputs you use to generate this template, because the resulting Lua code will execute within your Hammerspoon environment. Be very careful about your inputs if you choose to ignore this warning.

include

Signature	hs.httpserver.hsminweb.cgilua.lp.include(file, [env]) -> none
Type	Function
Description	Includes the template specified by the file parameter.
Parameters	file - a string containing the file system path to the template to include. env - an optional table specifying the environment to be used by the included template. By default, the template will inherit its caller's environment.
Returns	None
Notes	This function is called by the web server to process the template specified by the requested URL. Subsequent invocations of this function can be used to include common or re-used code from other template files and will be included in-line where the cgilua.lp.include function is invoked in the originating template. During the processing of a web request, the local directory is temporarily changed to match the local directory of the path of the file being served, as determined by the URL of the request. This is usually different than the Hammerspoon default directory which corresponds to the directory which contains the init.lua file for Hammerspoon.

translate

Signature	hs.httpserver.hsminweb.cgilua.lp.translate(source) -> luaCode
Type	Function
Description	Converts the specified Lua template source into Lua code executable within the Hammerspoon environment.
Parameters	source - a string containing the contents of a Lua/HTML template to be converted into true Lua code
Returns	The lua code corresponding to the provided source which can be fed into the load lua builtin to generate a Lua function.
Notes	This function is used internally by cgilua.lp.include, and probably won't be useful unless you want to translate a dynamically generated template -- which has security implications, depending upon what inputs you use to generate this template, because the resulting Lua code will execute within your Hammerspoon environment. Be very careful about your inputs if you choose to ignore this warning. To ensure that the translated code has access to the cgilua support functions, pass _ENV as the environment argument to the load lua builtin; otherwise any output generated by the resulting function will be sent to the Hammerspoon console and not included in the HTTP response sent back to the client.