doc/manual.tex

   1 \documentclass{article}
   2 \usepackage{fullpage}
   3
   4 \title{mlt manual}
   5 \author{Adam Chlipala}
   6
   7 \begin{document}
   8
   9 \maketitle
  10
  11 \section{Introduction}
  12
  13 This system is currently in need of a good name. I will use either ``mlt'' or generic terms to refer to it for now.
  14
  15 mlt is a system for the creation of dynamic web sites based around Standard ML. The meat of the system deals with compiling a template language. This language is purposely simplistic. It's not possible to create a non-terminating template without the complicity of SML code that it calls. Templates look like HTML source files with SML-like code inserted in strategic places. They are capable of full interaction with all types and values in any SML structures. The current implementation interfaces with web servers via the standard CGI protocol.
  16
  17 \section{Tool usage}
  18
  19 \begin{enumerate}
  20         \item Choose a directory to hold the sources for the dynamic web site project.
  21         \item Edit a {\tt mlt.conf} file in that directory to set project options, including which SML/NJ CM libraries to use, where to put some generated SML sources and binary files, and where to publish the actual CGI scripts.
  22         \item Create a set of Standard ML support files.
  23         \item Create a set of templates with {\tt .mlt} filename extensions. Each {\tt {\it page}.mlt} will become a CGI script named {\tt {\it page}}, and they may interact with libraries and project SML sources.
  24         \item Run the {\tt mlt} command-line program with no arguments.
  25         \item If it reports any errors, correct them and repeat the last step.
  26         \item Access your site from the base URL corresponding to the directory you chose for script output. (Probably a ``cgi-bin'' directory of some sort)
  27 \end{enumerate}
  28
  29 \section{{\tt mlt.conf} files}
  30
  31 Settings concerning compilation and publishing of projects are controlled by {\tt mlt.conf} files. There will generally be two files that influence a particular project: a system-wide file (probably in {\tt /etc/mlt.conf}) and the {\tt mlt.conf} file in the project directory. Single-value option settings from the project configuration override the system-wide configuration when there is a conflict.
  32
  33 Files consist of a sequence of the following kinds of lines in any order:
  34
  35 \begin{itemize}
  36         \item {\tt in {\it directory}}: Treat {\it directory} as the project directory. This defaults to the current working directory.
  37
  38         \item {\tt out {\it directory}}: Use {\it directory} as the working directory. Among other things, a {\tt heap.x86-linux} file will be placed here that must be readable by the web server that you intend to use. (If the server runs your CGI scripts as your user, like Apache does with suexec, then you probably don't need to worry about this.) This defaults to the current working directory.
  39
  40         \item {\tt pub {\it directory}}: Publish CGI scripts to {\it directory}. Each will be a {\tt sh} shell script that runs SML/NJ with the generated {\tt heap.x86-linux} and appropriate arguments. This defaults to the current working directory.
  41
  42         \item {\tt lib {\it file}}: {\it file} is the path to the {\tt .cm} file for the mlt template library. This is the library built from the {\tt src/lib/} tree. It defaults to {\tt /usr/local/share/mlt/src/lib/sources.cm}.
  43
  44         \item {\tt compiler {\it file}}: {\it file} is the path to the {\tt .cm} file for the mlt compiler library. This is the library built from the {\tt src/} tree. It defaults to {\tt /usr/local/share/mlt/src/sources.cm}.
  45
  46         \item {\tt sml {\it directory}}: {\it directory} is the path to the SML/NJ {\tt bin} directory. It defaults to {\tt /usr/local/sml/bin}.
  47
  48         \item {\tt cm {\it file}}: {\it file} is the path to a file that the SML/NJ Compilation Manager understands (i.e., {\tt .cm}, {\tt .sml}, {\tt .sig}, {\tt .grm}, {\tt .lex}). This file is to be made available to templates in the project.
  49
  50         \item {\tt print {\it type} = {\it code}}: This declares that the given {\it code} is an SML expression that evaluates to an appropriate function for printing values of the SML {\it type}. The {\it code} should usually be the name of a function defined in a library or project SML source file.
  51
  52         \item {\tt before {\it template}}: Run {\it template} before every normally-requested template, including its output at the beginning of the final output. This can be used to set up project-wide global state. Performing initialization inside project SML files will not generally be good enough. This is because all of the structure definitions these contain are evaluated at ``compile time,'' causing their code not found inside function definitions to be run only once.
  53
  54         \item {\tt after {\it template}}: Run {\it template} after every successfully executing template, including its output at the end.
  55
  56         \item {\tt exn {\it template}}: Run {\it template} when an exception goes uncaught during normal template execution. The function {\tt Web.getExn : unit -> exn} can be used to retrieve the causing exception from within {\it template}. The {\tt before} and {\tt after} templates are not run in the {\tt exn} template when it is executed because of an uncaught exception.
  57 \end{itemize}
  58
  59 \section{The template language}
  60
  61 The template language at the moment is a somewhat ad-hoc mixture of SML-style and Java-style syntax. The exact typing rules for the constructs described below should be clear to anyone with a good knowledge of SML.
  62
  63 \subsection{Grammar}
  64
  65 Template files (denoted by the filename extension {\tt .mlt}) are HTML source files with embedded declarations and statements in an SML-like language. Statements and declarations are separated by semicolons where necessary to disambiguate. The exact grammar can be found in ml-yacc form in {\tt src/mlt.grm}.
  66
  67 \subsection{Expressions}
  68
  69 \subsubsection{Constants}
  70
  71 Base type constants such as 1, $\sim 2$, and {\tt "some string"} are available, with identical types and meanings as in Standard ML. Character constants are denoted like 'x'.
  72
  73 \subsubsection{Variables}
  74
  75 User-defined variables are denoted the same way as in SML, except that the apostrophe character is disallowed in their identifiers.
  76
  77 \subsubsection{Paths}
  78
  79 While templates cannot define their own structures, they may access structures from imported libraries and project SML sources. The syntax for this is identical to the SML syntax, i.e., {\tt Posix.FileSys.opendir} or {\tt valOf}. The second example is treated as a path projecting the {\tt valOf} function from the top-level environment.
  80
  81 \subsubsection{Binary operators}
  82
  83 There is no mechanism for user definition of infix operators, but the following binary operators are supported: $+$, $-$, $*$, $/$, $\%$, $=$, $<>$, $<$, $<=$, $>$, $>=$, $::$, \^{}, {\tt and}, and {\tt or}. They are identical to SML operators, save that SML {\tt div} becomes $/$, {\tt mod} becomes $\%$, {\tt andalso} becomes {\tt and}, and {\tt orelse} becomes {\tt or}.
  84
  85 \subsubsection{Unary operators}
  86
  87 In addition to SML's $\sim$ prefix negation operator, there is a \$ operator for CGI parameter extraction. \$ has type {\tt string -> string}, so you can use it like {\tt \$"name"} to retrieve the value of the form field {\tt name}. \$ returns {\tt ""} for unset parameters.
  88
  89 \subsubsection{Applications}
  90
  91 Function application is like SML application.
  92
  93 \subsubsection{Tuples}
  94
  95 Tuple and {\tt ()} expressions are handled identically to how they are in SML.
  96
  97 \subsubsection{Records}
  98
  99 The syntax for creating records and extracting their fields is identical to SML's, with a few added conveniences. Record fields given in a record constructor without values are assigned the values of variables of the same names. For example, if there is a variable {\tt x} in scope, then the expressions {\tt \{x = x\}} and {\tt \{x\}} are equivalent. There are also O'Caml style functional record update expressions, such as {\tt \{myRecord with a = 1, b = 2\}} to construct a record identical to {\tt myRecord} except for the given field replacements.
 100
 101 \subsubsection{Template calls}
 102
 103 Where {\tt temp} is the name of a template in the current project, {\tt @temp} evaluates to a function {\tt (string * string) list -> unit} that takes in a list of name-value pairs for CGI parameters to modify and runs {\tt temp} with those changes. The Compilation Manager will prevent template calls from being used to implement any sort of recursion.
 104
 105 \subsubsection{Anonymous functions}
 106
 107 Anonymous {\tt fn} functions are available with the SML syntax.
 108
 109 \subsubsection{\tt case}
 110
 111 SML {\tt case} expressions are supported.
 112
 113 \subsubsection{\tt iff}
 114
 115 SML {\tt if} expressions are supported, except that the keyword that introduces them is {\tt iff}, to disambiguate from {\tt if} statements.
 116
 117 \subsubsection{\tt raise}
 118
 119 SML {\tt raise} expressions are supported.
 120
 121 \subsubsection{\tt let}
 122
 123 SML {\tt let} expressions are supported.
 124
 125 \subsection{Patterns}
 126
 127 Patterns are identical to SML patterns without support for user-defined infix constructors, though {\tt ::} is supported. Record patterns can include field names with no assigned patterns (the pattern for such a field is taken to be the field name) and "flex record" {\tt ...}'s to stand for unused fields.
 128
 129 \subsection{Statements and declarations}
 130
 131 \subsubsection{\tt Expressions}
 132
 133 An expression appearing in a statement position is evaluated and printed into the web page output. The function used to print it is found among the {\tt print} directives in {\tt mlt.conf} files.
 134
 135 \subsubsection{\tt open}
 136
 137 This construct is identical to SML's and is used as a convenience to import all bindings from a list of structures into the environment for the enclosing block.
 138
 139 \subsubsection{\tt val}
 140
 141 {\tt val} bindings are identical to those in SML.
 142
 143 \subsubsection{References}
 144
 145 Variables with reference type are introduced with {\tt ref} declarations, which give lists of identifiers and their initial values. An example is {\tt ref x = 1, y = 2}. Where such a definition is in scope, the defined reference variables are used like normal variables with no need to explicitly dereference them. The value of a reference variable is updated with the usual {\tt :=} operator, with the difference that such update assignments are separate kinds of statements, not expressions with {\tt unit} type.
 146
 147 \subsubsection{{\tt if}..{\tt then}..{\tt else}}
 148
 149 If statements are in the usual imperative style, meaning that else clauses are optional. They are of the form:
 150
 151 \begin{verbatim}
 152 if condition1 then
 153         block1
 154 else if condition 2 then
 155         block 2
 156 else
 157         block 3
 158 end
 159 \end{verbatim}
 160
 161 The {\tt block}s are sequences of statements and declarations. Every {\tt if} statement is followed by zero or more {\tt else if}'s and one or zero {\tt else}'s.
 162
 163 \subsubsection{\tt foreach}
 164
 165 All looping is done via {\tt foreach} statements, which have two forms. One is:
 166
 167 \begin{verbatim}
 168 foreach var in exp do
 169         block
 170 end
 171 \end{verbatim}
 172
 173 Where {\tt exp} has type {\tt t list}, {\tt block} is executed for each of {\tt exp}'s elements, binding {\tt var} to each of them in order from first to last.
 174
 175 There is also a shortcut integer iteration form:
 176
 177 \begin{verbatim}
 178 foreach var in fromExp .. toExp do
 179         block
 180 end
 181 \end{verbatim}
 182
 183 {\tt fromExp} and {\tt toExp} must have type {\tt int}. {\tt block} is evaluated with {\tt var} bound in sequence to each integer in the range defined by {\tt fromExp} and {\tt toExp}.
 184
 185 \subsubsection{\tt switch}
 186
 187 {\tt switch} statements are imperative equivalents of {\tt case} expressions, such as:
 188
 189 \begin{verbatim}
 190 switch exp of
 191   pat1 => block1
 192 | pat2 => block2
 193 end
 194 \end{verbatim}
 195
 196 \subsubsection{{\tt try}..{\tt with}}
 197
 198 This construction is to SML's {\tt handle} what {\tt switch} is to {\tt case}. For example:
 199
 200 \begin{verbatim}
 201 try
 202         block1
 203 with pat1 => block2
 204 | pat2 => block3
 205 end
 206 \end{verbatim}
 207
 208 \end{document}