X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/eb41dc760ead320d9c7089839913ae9758e333ba..40f2456eca4c0386a1fd473cfdf61253d13f0048:/doc/syntax.tex diff --git a/doc/syntax.tex b/doc/syntax.tex index ccb7087..0b415d2 100644 --- a/doc/syntax.tex +++ b/doc/syntax.tex @@ -53,18 +53,18 @@ could be a token. ::= @! - ::= "A" | "B" | \dots\ | "Z" -\alt "a" | "b" | \dots\ | "z" -\alt + ::= "A" | "B" $| \cdots |$ "Z" + | "a" | "b" $| \cdots |$ "z" + | ::= "0" | - ::= "1" | "2" $| \ldots |$ "9" + ::= "1" | "2" $| \cdots |$ "9" \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 @@ -80,11 +80,11 @@ level. ::= "'" "'" - ::= any character other than "\\" or "\"" -\alt "\\" + :: "\\" + | any character other than "\\" or "\"" - ::= any character other than "\\" or "'" -\alt "\\" + :: "\\" + | any character other than "\\" or "'" ::= any single character \end{grammar} @@ -101,25 +101,25 @@ discouraged. \begin{grammar} ::= -\alt -\alt -\alt + | + | + | ::= "0" | @^* - ::= "0" @("b"|"B"@) @^+ + ::= "0" @("b" @! "B"@) @^+ ::= "0" | "1" - ::= "0" @["o"|"O"@] @^+ + ::= "0" @["o" @! "O"@] @^+ - ::= "0" | "1" $| \ldots |$ "7" + ::= "0" | "1" $| \cdots |$ "7" - ::= "0" @("x"|"X"@) @^+ + ::= "0" @("x" @! "X"@) @^+ ::= -\alt "A" | "B" | "C" | "D" | "E" | "F" -\alt "a" | "b" | "c" | "d" | "e" | "f" + | "A" | "B" | "C" | "D" | "E" | "F" + | "a" | "b" | "c" | "d" | "e" | "f" \end{grammar} Sod understands only integers, not floating-point numbers; its integer syntax @@ -130,15 +130,16 @@ binary. However, length and signedness indicators are not permitted. \subsection{Punctuation} \label{sec:syntax.lex.punct} \begin{grammar} - ::= any nonalphanumeric character other than "_", "\"" or "'" + ::= "<<" | ">>" | "||" | "&&" + | "<=" | ">=" | "==" | "!=" | "\dots" +\alt any nonalphanumeric character other than "_", "\"", or "'" \end{grammar} \subsection{Comments} \label{sec:syntax.lex.comment} \begin{grammar} - ::= -\alt + ::= | ::= "/*" @@ -190,9 +191,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} @@ -367,18 +368,53 @@ keyword arguments. ::= "=" - ::= | "+" | "--" + ::= - ::= | "*" | "/" + ::= + | "||" - ::= | "+" | "--" + ::= + | "&&" + + ::= + | "|" + + ::= + | "^" + + ::= + | "&" + + ::= + | "==" + | "!=" + + ::= + | "<" + | "<=" + | ">=" + | ">" + + ::= + | "<<" + | ">>" + + ::= + | "+" + | "--" + + ::= + | "*" + | "/" + + ::= + | "!" | "~" factor + | "+" | "--" ::= | | | -\alt "<" ">" -\alt "{" "}" -\alt "?" -\alt "(" ")" +\alt "<" ">" | "{" "}" | "?" + | "(" ")" \end{grammar} \emph{Property sets} are a means for associating miscellaneous information @@ -431,8 +467,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 +476,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 +498,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 +512,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,12 +548,14 @@ 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 source file presented to Sod @@ -548,9 +586,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 @@ -560,7 +598,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.} % @@ -577,23 +615,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 @@ -633,9 +670,11 @@ declarations instead. \begin{grammar} ::= - "code" ":" @[@] + "code" ":" @[@] "{" "}" + ::= + ::= "[" $[\mbox{@}]$ "]" ::= @^+ @@ -711,6 +750,7 @@ class Sub: Super \{ \\ \ind \alt \alt \alt +\alt \fixme{undefined} \end{grammar} A full class definition provides a complete description of a class. @@ -724,8 +764,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.