The nity-gritty (develop…)

This manual is a pre-release preview. Please follow Moonstalk on Twitter or Facebook to be notified of a public release.

Tables

These data-structures provide access to the Moonstalk environment, the request, and the response. You may check and change the values in these tables to determine how to handle a request—and to generate a page for response.

All tables exist in either a global or ephemeral (per-request) scope. The latter are discarded after each request is completed and may be modified freely, whilst the prior exist across all requests and should not be modified. Additional reference (pointer) tables are provided in the ephemeral scope for convenient access to some global tables.

Global tables should not be changed during a request, and are intended to only be modified by application load-time functions. Failure to adhere to this will result in random results when using more than a single backend instance. Whilst reference tables change with each request, they are dynamic pointers, or aliases, to the contents of global tables and therefore should also not be changed. No tables are persisted (use a database such as the Teller).

request.

This predominantly contains details of the HTTP headers, with parsing into a more Lua-friendly format where appropriate. Use of this table is discouraged as its format and structure is dependant upon the web server API. See form and page instead.

Ephemeral table

form.

Contains merged values from both request.get and request.post (latter has precedence), but is always present regardless of method.

Ephemeral table

site.

Reference table

page.

Defines the page to be rendered as a response.

Ephemeral table

temp.

Ephemeral table

Always declare variables as local or use the temp table.

moonstalk.

Global table

node.

The global Moonstalk environment for each server (node). Settings are configured in the data/configuration/Node.lua, and may also be changed at launch time by the .Runner

Settings

Table (global)

scribe. (global)

Functions

For application-specific functions see the applications page.

Content

write

Appends the passed value to the current output section. Values may only be strings, numbers or nil (which is ignored).

A table or function value will invoke an error as they cannot be respresented as text in a response, for debugging you may however output them with tostring().

In views, do not call write from a ?() expression tag, instead call it from a <? ?> processing tag.

l.

Returns the given language key's value from a translated vocabulary, in its original case. Use L.key for an initial capital.

This is a proxy table—a function with table.key syntax. (Achieved using a metatable __call overload.)

macro

Replace defined ?(key) macros in the specified text, with their correspondingly specified values.

Whilst macros in views (expression tags) accept expressions (thus, function calls) for replacement, text macros do not, and where no corresponding key is specified a macro is not replaced.

Text macros are typically used for customising strings, such as translated language keys from vocabularies, where pre-defined grammar is customised using embedded variables.

Page

scribe.Section

Changes the current output to a new container, as named. (The default page response output is named content.) See also Cut.

scribe.Mark

Marks the current position in a view to later Insert a section or other value.

scribe.Insert

Inserts a previously defined section into the current view/section. Takes an optional mark_name parameter to insert at the specified Mark instead of the current location. See also Paste.

scribe.Page

Run a specified controller and/or associated view and append it's output to the current page.

scribe.View

Run a specified view only and append it's output to the page. If the view provides versions for different cultures a matching translation/localisation will be served.

scribe.Controller

Run a specified controller only.

scribe.Cookie

Sets a cookie in the user's browser.

Abandonment

The following functions abandon page processing in some way, to display an alternate view or response.

The current function from which these functions are called, and any chaining from it, will continue to run but their output will be surpressed. No further functions will run except for the default template (if any). To prevent the current function from continuing, follow the function call with a return termination.

scribe.Redirect

Abandons the page processing to instead returns a 302 redirect response to the user's browser. The address may be a path or URL.

scribe.Authorised

Checks that the current user has one of the specified keys, otherwise abandons the page processing. If not signed-in the generic/signin view is displayed, or if signed-in but without a specified key, the generic/unauthorised view is displayed.

For a conditional termination use if not scribe.Authorised{"name"} then return end. For conditional content check user.keychain directly.

scribe.Error

Abandons the page processing with the generic/error view using the specified details.

scribe.NotFound

Abandons the page processing with the generic/not-found view. Accepts an optional user-friendly name to be displayed instead of the page.address.

Utility

The following functions abandon page processing in some way, to display an alternate view or response.

Lua Modules

All standard Lua libraries are available, with the following, and some other less commonly used libraries that are documented on the credits page.

You may use load other libraries (.lua or .so) saved in the same folder as a view or controller, or within an application folder by using the full path.

Moonstalk uses its own package.path and cpath, therefore if you wish to use other libraries elsewhere on your system (such as from LuaRocks), you must append those paths to Moonstalk's values. Applications may do this in the settings or functions files.

Components

Web server

Moonstalk uses the data/configuration/lighttpd.conf as its base configuration, with which its own configuration is combined at launch-time, and then saved to the temporary/lighttpd.conf file to launch Lighttpd.

Behaviours

Bundles

Behaviours

Views

Other files

Table

Applications

A bundle whose table exists in the global environment, and having handlers that run at launch-time.

Functions

Initialisation

Requests

Behaviours

Table

Performance

Enabling applications has no per-request performance overhead except where the following are defined by the application, where the overhead will be specific to the functionality provided. Memory overhead for applications with multiple sites is minimal (sites are populated only with references to the application).

Sites

Sites are defined by the sites() function of applications. See the Sites Folder or Tenants applications, or any other application with a sites function, for details on how sites may be defined and configured outside the Scribe environment.

Within the Scribe environment, sites are stored in the node.sites table, with references from the global domains table (used to lookup a site for each request) and ephemeral (per-request) site table.

Behaviours

Table

Views

Features

Behaviours

Functions

Table

Controllers

Behaviours

Features

Addresses

Features

Behaviours

Table

Selectors

Defines how to match a request. Only one may be used.

Handlers

Defines what to do with the request. One or more may be specified per address. You need only specify both controller and view if they are different.

Attributes

Addresses may specify any of the attributes of a page, such as template or title.

User

Represents the anonymous visitor that made the request, a profiled visitor (cookie-tracked but anonymous), or a registered user. Managed by the built-in authentication mechanism but may be extended by applications.

Features

Behaviours

Extend…

To learn how you can extend moonstalk, and make use of pre-packaged functionality, read the applications page, or to understand the Moonstalk's design jump to the architecture page.