X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/b0d55f11362b9e2d2d2b9e24bdfb5a12429b1e70..eaa0e159e693ee8ac660a15cea6450402f120d5a:/doc/syntax.tex diff --git a/doc/syntax.tex b/doc/syntax.tex index 666fe84..07b7ce7 100644 --- a/doc/syntax.tex +++ b/doc/syntax.tex @@ -63,8 +63,8 @@ could be a token. \end{grammar} The precise definition of @ is left to the function -\textsf{alpha-char-p} in the hosting Lisp system. For portability, -programmers are encouraged to limit themselves to the standard ASCII letters. +@|alpha-char-p| in the hosting Lisp system. For portability, programmers are +encouraged to limit themselves to the standard ASCII letters. There are no reserved words at the lexical level, but the higher-level syntax recognizes certain identifiers as \emph{keywords} in some contexts. There is @@ -190,9 +190,9 @@ during translation. They are read using a simple scanner which nonetheless understands C comments and string and character literals. A C fragment is terminated by one of a small number of delimiter characters -determined by the immediately surrounding context -- usually a closing brace -or bracket. The first such delimiter character which is not enclosed in -brackets, braces or parenthesis ends the fragment. +determined by the immediately surrounding context -- usually some kind of +bracket. The first such delimiter character which is not enclosed in +brackets, braces or parentheses ends the fragment. %%%-------------------------------------------------------------------------- \section{C types} \label{sec:syntax.type} @@ -431,8 +431,8 @@ operators. Finally, an S-expression preceded by @|?| causes the expression to be read in the current package (which is always @|sod-user| at the start of a module) and immediately evaluated (using @|eval|); the resulting value is converted -into a property value using the \descref{decode-property}[generic -function]{gf}. +into a property value using the \descref{gf}{decode-property}[generic +function]. \subsection{Property output types and coercions} @@ -440,8 +440,8 @@ function]{gf}. When a property value is inspected by the Sod translator, or an extension, it is \emph{coerced} so as to conform to a requested output type. This coercion -process is performed by the \descref{coerce-property-value}[generic -function]{gf}, and additional output types and coercions can be defined by +process is performed by the \descref{gf}{coerce-property-value}[generic +function], and additional output types and coercions can be defined by extensions. The built-in output types coercions, from the value types listed above, are as follows. @@ -462,10 +462,10 @@ above, are as follows. \item The @|boolean| output type denotes a boolean value, which may be either true or false. A value of type @|id| is considered true if it is @|true|, - @|t|, @|yes|, @|on|, or @|verily|; or false if it is @|false|, @|nil|, - @|no|, @|off|, or @|nowise|; it is erroneous to provide any other - identifier where a boolean value is wanted. A value of type @|int| is - considered true if it is nonzero, or false if it is zero. + @|t|, @|yes|, @|on|, @|yup|, or @|verily|; or false if it is @|false|, + @|nil|, @|no|, @|off|, @|nope|, or @|nowise|; it is erroneous to provide + any other identifier where a boolean value is wanted. A value of type + @|int| is considered true if it is nonzero, or false if it is zero. \item The @|symbol| output type denotes a Lisp symbol. @@ -476,7 +476,7 @@ above, are as follows. upper; if the name contains letters of both cases, then it is not changed. For example, @|foo45| becomes @|FOO45|, or \emph{vice-versa}; but @|Splat| remains as it is. Second, the name is subjected to \emph{separator - switching}: all underscores in the name are replaced with hyphens (and + switching}: all underscores in the name are replaced with hyphens (and \emph{vice-versa}, though hyphens aren't permitted in identifiers in the first place). Finally, the resulting name is interned in the current package, which will usually be @|sod-user| unless changed explicitly by the @@ -512,16 +512,20 @@ above, are as follows. \begin{grammar} ::= @^* - ::= + ::= \fixme{undefined} +\alt \alt \alt \alt \alt \alt +\alt \fixme{undefined} \end{grammar} -A @ is the top-level syntactic item. A module consists of a sequence -of definitions. +A @ is the top-level syntactic item: a source file presented to Sod +is expected to conform with the @ syntax. + +A module consists of a sequence of definitions. \fixme{describe syntax; expand} Properties: @@ -546,9 +550,9 @@ A search is made for a module source file as follows. \begin{itemize} \item The module name @ is converted into a filename by appending @`.sod', if it has no extension already.\footnote{% - Technically, what happens is \textsf{(merge-pathnames name (make-pathname - :type "SOD" :case :common))}, so exactly what this means varies - according to the host system.} % + Technically, what happens is @|(merge-pathnames name (make-pathname :type + "SOD" :case :common))|, so exactly what this means varies according to + the host system.} % \item The file is looked for relative to the directory containing the importing module. \item If that fails, then the file is looked for in each directory on the @@ -558,7 +562,7 @@ A search is made for a module source file as follows. \end{itemize} At this point, if the file has previously been imported, nothing further happens.\footnote{% - This check is done using \textsf{truename}, so it should see through simple + This check is done using @|truename|, so it should see through simple tricks like symbolic links. However, it may be confused by fancy things like bind mounts and so on.} % @@ -575,23 +579,22 @@ A search is made for a Lisp source file as follows. \begin{itemize} \item The name @ is converted into a filename by appending @`.lisp', if it has no extension already.\footnote{% - Technically, what happens is \textsf{(merge-pathnames name (make-pathname - :type "LISP" :case :common))}, so exactly what this means varies - according to the host system.} % + Technically, what happens is @|(merge-pathnames name (make-pathname :type + "LISP" :case :common))|, so exactly what this means varies according to + the host system.} % \item A search is then made in the same manner as for module imports (\xref{sec:syntax-module}). \end{itemize} -If the file is found, it is loaded using the host Lisp's \textsf{load} -function. +If the file is found, it is loaded using the host Lisp's @|load| function. Note that Sod doesn't attempt to compile Lisp files, or even to look for existing compiled files. The right way to package a substantial extension to the Sod translator is to provide the extension as a standard ASDF system (or similar) and leave a dropping @|foo-extension.lisp| in the module path saying something like -\begin{quote} - \textsf{(asdf:load-system :foo-extension)} -\end{quote} +\begin{prog} + (asdf:load-system :foo-extension) +\end{prog} which will arrange for the extension to be compiled if necessary. (This approach means that the language doesn't need to depend on any @@ -709,6 +712,7 @@ class Sub: Super \{ \\ \ind \alt \alt \alt +\alt \fixme{undefined} \end{grammar} A full class definition provides a complete description of a class. @@ -722,8 +726,9 @@ The @$[\mbox{@}]$ names the direct superclasses for the new class. It is an error if any of these @s does not name a defined class. The superclass list is required, and must not be empty; listing @|SodObject| as your class's superclass is a good choice if nothing else -seems suitable. It's not possible to define a \emph{root class} in the Sod -language: you must use Lisp to do this, and it's quite involved. +seems suitable. A class with no direct superclasses is called a \emph{root +class}. It is not possible to define a root class in the Sod language: you +must use Lisp to do this, and it's quite involved. The @ provide additional information. The standard class properties are as follows.