A File-like domain mapping a URL domain onto a file-system hierarchy, providing templating and pre- and post- filtering of requests and responses (respectively)
[Nub domain /mason/ Mason root $docroot]
Where docroot is the path of your file directory. The directory can contain .tml files which will be [subst]ed under tcl, index files, .before and .after files.
Now any reference to /mason/path will return the content of the file at $docroot/path. You can restrict access to the file using the .before facility, transform the file contents using the .after facility, and guard against non-existent files using the .notfound facility.
The target URL is interpreted relative to the Mason object's root directory, and its value returned. A literal match is preferred, but if one can't be made, a templated file with the same file rootname will be evaluated and returned in its stead (allowing generated content to match a requested file-extension.)
Standard templates are run at strategic points in URL handling (pre- and post-processing) to allow Mason user-provided code to intervene in requests and transform responses. If a requested file can't be located, the per-directory notfound template is evaluated in its stead.
Any file ending with .tml file extension is considered to be a template file, and is passed to [subst] with the resultant value returned as content to the user. Unlike standard templates, *.tml templates are not expected to return complete response-dicts, but may return simple values. However, *.tml template scripts have access to a variable response which will form the response dict sent to the client (after .after processing) and may access and modify it. Any response fields may be modified, and will be combined with the value returned by the .tml script to form the client response. Any error in the .tml script evaluation will be immediately returned as a Server Error. If the .tml script sets the -content field of response, then that (and not the .tml script evaluation result) will be the response content. .tml may also set the response -code to an HTTP response code, and it will be definitive. A .tml may also use tcl's [return -code] to set the HTTP response code.
Content produced by .tml files is considered dynamic, it won't be cached by default. However, setting the -dynamic response field to 0 will override this behaviour, and the content will be considered cacheable. In this case, the file modification time of the .tml script itself will be considered to be the modification time of its result.
Content derived from the resolution of URLs to files are considered to be static, and will be cached. The modification time of these files will be considered in response to an HTTP if-modified-since request. This caching behaviour may be changed if the response -dynamic field is set to true.
Static content should probably specify an expires configuration value, which prevents caches from soliciting change information before the stated expiry time and which determines cache expiry. Proper selection of caching options is a subtle and complex area, well beyond this document's scope.
Standard templates are sought in ancestor directories of the url-addressed file, and are evaluated in a context in which the current response dict is available in $rsp or the current request dict is available in a variable as $req, respectively. The scripts may use or modify req or rsp, and are expected to return a new version. If they modify the dict (by adding, changing or removing request fields) those changes will be propagated through the system and be returned to the client. This gives Mason a great deal of power in interpreting client requests and transforming server responses.
Are not used to evaluate templates, but probably should be.
(generated by STX)