X-Git-Url: https://git.distorted.org.uk/~mdw/sod/blobdiff_plain/020b9e2b4364c61a668d47c4c5405295349817d8..f458e64e36509fa8c204f1dbcafff1d3dc059619:/doc/clang.tex diff --git a/doc/clang.tex b/doc/clang.tex index c4a6a53..b273a2c 100644 --- a/doc/clang.tex +++ b/doc/clang.tex @@ -169,12 +169,12 @@ type specifier. Type specifiers fit into two syntactic categories. \begin{describe}{gf}{expand-c-type-spec @ @> @
} Returns the Lisp form that @|(c-type @)| would expand into. - If @ is a list, then \descref{expand-c-type-form}{fun} is + If @ is a list, then \descref{expand-c-type-form}{gf} is invoked. \end{describe} \begin{describe}{gf}{expand-c-type-form @ @ @> @} - Returns the Lisp form that @|(c-type (@ . @)| would expand + Returns the Lisp form that @|(c-type (@ . @))| would expand into. \end{describe} @@ -565,23 +565,34 @@ In Sod, the leaf types are \begin{describe}{mac} {define-simple-c-type - \=@{ @ @! (@^+) @} @ \+\\ + \=@{ @ @! (@^+) @} + @{ @ @! (@^*) @} \+\\ @[[ @|:export| @ @]] \-\nlret @} Define type specifiers for a new simple C type. Each symbol @ is defined as a symbolic type specifier for the (unique interned) simple C - type whose name is the value of @. Further, each @ is - defined to be a type operator: the type specifier @|(@ + type whose name is the value of (the first) @. Further, each + @ is defined to be a type operator: the type specifier @|(@ @^*)| evaluates to the (unique interned) simple C type whose - name is @ and which has the @ (which are evaluated). + name is (the first) @ and which has the @ (which are + evaluated). - Furthermore, a variable @|c-type-@| is defined, for the first @ - only, and initialized with the newly constructed C type object. + Each of the @s is associated with the resulting type for retrieval + by \descref{find-simple-c-type}{fun}. Furthermore, a variable + @|c-type-@| is defined, for the first @ only, and initialized + with the newly constructed C type object. If @ is true, then the @|c-type-@| variable name, and all of the @s, are exported from the current package. \end{describe} +\begin{describe}{fun} + {find-simple-c-type @ @> @{ @ @! @|nil| @}} + If @ is the name of a simple C type, as established by the + \descref{define-simple-c-type}[macro]{mac}, then return the corresponding + @|simple-c-type| object; otherwise, return @|nil|. +\end{describe} + \begin{describe}{cls}{tagged-c-type (qualifiable-c-type) \&key :qualifiers :tag} Provides common behaviour for C tagged types. A @ is a string @@ -1006,23 +1017,45 @@ function type is the type of the function's return value. original list is not modified, but may share structure with the new list. \end{describe} -\begin{describe}{fun}{merge-keyword-lists @ @> @} +\begin{describe}{fun} + {merge-keyword-lists @ @ @> @} Merge a number of keyword-argument lists together and return the result. - The @ parameter is a list consisting of a number of @|(@ - . @)| pairs: in each pair, @ is a list of - \descref{argument}{cls} objects, and @ is either nil or an object - whose printed representation describes the origin of the corresponding - @ list, suitable for inclusion in an error message. + The @ is either nil or a function designator; see below. + + The @ parameter is a list consisting of a number of + @|(@ . @)| pairs: in each pair, @ + is either nil or a function designator, and @ is a list of + \descref{argument}{cls} objects. The resulting list contains exactly one argument for each distinct argument name appearing in the input @; this argument will contain the default value from the earliest occurrence in the input @ of an argument with that name. - If the same name appears multiple times with different types, an error is - signalled quoting the name, conflicting types, and (if non-nil) the origins - of the offending argument objects. + If the same name appears multiple times with different types, a continuable + error will be signalled, and one of the conflicting argument types will be + chosen arbitrarily. The @ will be called to establish + information which will be reported to the user. It will be called with no + arguments and is expected to return two values: + \begin{itemize} + \item a file location @ or other object acceptable to + \descref{file-location}{gf}, to be used as the location of the main + error; and + \item an object @, whose printed representation should be a noun + phrase describing the object for which the argument lists are being + combined. + \end{itemize} + The phrasing of the error message is `type mismatch in @'. Either, + or both, of @ and @ may be nil, though this is considered poor + practice; if @ is nil, this is equivalent to a function + which returns two nil values. Following the error, the @s + for the @ lists containing the conflicting argument objects are + called, in an arbitrary order, with a single argument which is the + offending @|argument| object; the function is expected to issue information + messages (see \descref{info}{fun}) to give more detail for diagnosing the + conflict. If a @ is nil, then nothing happens; this is + considered poor practice. \end{describe} \begin{describe}{fun}