+.\" -*-nroff-*-
+.\"
+.\" The Sod module syntax
+.\"
+.\" (c) 2015 Straylight/Edgeware
+.\"
+.
+.\"----- Licensing notice ---------------------------------------------------
+.\"
+.\" This file is part of the Sensble Object Design, an object system for C.
+.\"
+.\" SOD is free software; you can redistribute it and/or modify
+.\" it under the terms of the GNU General Public License as published by
+.\" the Free Software Foundation; either version 2 of the License, or
+.\" (at your option) any later version.
+.\"
+.\" SOD is distributed in the hope that it will be useful,
+.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
+.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
+.\" GNU General Public License for more details.
+.\"
+.\" You should have received a copy of the GNU General Public License
+.\" along with SOD; if not, write to the Free Software Foundation,
+.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+.
+.\" Highlight using terminal escapes, rather than overstriking.
+.\"\X'tty: sgr 1'
+.
+.\" String definitions and font selection.
+.ie t \{\
+. ds o \(bu
+. if \n(.g .fam P
+.\}
+.el \{\
+. ds o o
+.\}
+.
+.\" .hP TEXT -- start an indented paragraph with TEXT hanging off to the left
+.de hP
+.IP
+\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
+..
+.
+.\" An epsilon, or e.
+.ie t \{\
+. ds e \(*e
+. ds ^ \v'-.3m'\s'\\n(.s*7/10'
+. ds ^e \s0\v'.3m'
+. ds _ \v'.3m'\s'\\n(.s*7/10'
+. ds _e \s0\v'-.3m'
+.\}
+.el \{
+. ds e \fIe\fR
+. ds ^ ^
+. ds ^e
+. ds _ _
+. ds _e
+.\}
+.ds * \*^\(**\*(^e
+.ds + \*^+\*(^e
+.
+.de |
+.br
+\h'4n'|
+..
+.ie t \{\
+. de <
+..
+.\}
+.el
+. de <
+. br
+\h'4n'
+..
+.\}
+.
+.\"--------------------------------------------------------------------------
+.TH sod 5 "11 October 2015" "Straylight/Edgeware" "Sensible Object Design"
+.
+.SH NAME
+sod-module \- Sensible Object Design module syntax
+.
+.\"--------------------------------------------------------------------------
+.SH DESCRIPTION
+This manual page provides a highly compressed description of the
+Sod module syntax.
+For full details, consult the main manual.
+.PP
+.SS Notation
+Anywhere a simple nonterminal name
+.I x
+may appear in the grammar,
+an
+.I indexed
+nonterminal
+.IR x [ a \*_1\*(_e,
+\&...,
+.IR a \*_ n \*(_e]
+may also appear.
+On the left-hand side of a production rule,
+the indices
+.IR a \*_1\*(_e,
+\&...,
+.IR a \*_ n \*(_e
+are variables which vary over all nonterminal and terminal symbols,
+and the variables may also appear on the right-hand side
+in place of a nonterminal.
+Such a rule stands for a family of rules,
+in each variable is replaced by
+each possible simple nonterminal or terminal symbol.
+.PP
+The letter \*e denotes the empty nonterminal
+.IP
+.I \*e
+::=
+.PP
+The following indexed productions are used throughout the grammar, some often
+enough that they deserve special notation.
+.hP \*o
+.RI [ x ]
+abbreviates
+.IR optional [ x ],
+denoting an optional occurrence of
+.IR x :
+.RS
+.IP
+.RI [ x ]
+::=
+.IR optional [ x ]
+::=
+\*e
+|
+.I x
+.RE
+.hP \*o
+.IR x \**
+abbreviates
+.IR zero-or-more [ x ],
+denoting a sequence of zero or more occurrences of
+.IR x :
+.RS
+.IP
+.IR x \**
+::=
+.IR zero-or-more [ x ]
+::=
+\*e
+|
+.I x
+.IR x \**
+.RE
+.hP \*o
+.IR x \*+
+abbreviates
+.IR one-or-more [ x ]
+denoting a sequence of one or more occurrences of
+.IR x :
+.RS
+.IP
+.IR x \*+
+::=
+.IR one-or-more [ x ]
+::=
+.I x
+.IR x \**
+.RE
+.hP \*o
+.IR list [ x ]
+denotes a sequence of one or more occurrences of
+.I x
+separated by commas:
+.RS
+.IP
+.IR list [ x ]
+::=
+.I x
+|
+.IR list [ x ]
+.B ,
+.I x
+.RE
+.
+.SS Special nonterminals
+.I s-expression
+::=
+an S-expression, as parsed by the Lisp reader
+.br
+.I c-fragment
+::=
+a sequence of C tokens, with matching brackets
+.
+.\"--------------------------------------------------------------------------
+.SH LEXICAL SYNTAX
+.
+.SS Tokens
+.I token
+::=
+.I identifier
+.|
+.I string-literal
+.|
+.I char-literal
+.|
+.I integer-literal
+.|
+.I punctuation
+.
+.SS Identifiers
+.I identifier
+::=
+.I id-start-char
+.IR id-body-char \**
+.br
+.I id-start-char
+::=
+.I alpha-char
+|
+.B _
+.br
+.I id-body-char
+::=
+.I id-start-char
+|
+.I digit-char
+.br
+.I alpha-char
+::=
+.B A
+|
+.B B
+| ... |
+.B Z
+.|
+.B a
+|
+.B b
+| ... |
+.B z
+.|
+.I extended-alpha-char
+.br
+.I digit-char
+::=
+.B 0
+|
+.I nonzero-digit-char
+.br
+.I nonzero-digit-char
+::=
+.B 1
+|
+.B 2
+| ... |
+.B 9
+.PP
+The characters matched by
+.I extended-alpha-char
+depend on the locale and the host Lisp system.
+.
+.SS String and character literals
+.I string-literal
+::=
+.B """"
+.IR string-literal-char \**
+.B """"
+.br
+.I char-literal
+::=
+.B '
+.IR char-literal-char \**
+.B '
+.br
+.I string-literal-char
+::=
+any character other than
+.B \e
+or
+.B """"
+.|
+.B \e
+.I char
+.br
+.I char-literal-char
+::=
+any character other than
+.B \e
+or
+.B '
+.|
+.B \e
+.I char
+.
+.SS Integer literals
+.I integer-literal
+::=
+.I decimal-integer
+.|
+.I binary-integer
+.|
+.I octal-integer
+.|
+.I hex-integer
+.br
+.I decimal-integer
+::=
+.B 0
+|
+.I nonzero-digit-char
+.IR digit-char \**
+.br
+.I binary-integer
+::=
+.B 0
+.RB ( b | B )
+.IR binary-digit-char \*+
+.br
+.I binary-digit-char
+::=
+.B 0
+|
+.B 1
+.br
+.I octal-integer
+::=
+.B 0
+.RB [ o | O ]
+.IR octal-digit-char \*+
+.br
+.I octal-digit-char
+::=
+.B 0
+|
+.B 1
+| ... |
+.B 7
+.br
+.I hex-integer
+::=
+.B 0
+.RB ( x | X )
+.IR hex-digit-char \*+
+.br
+.I hex-digit-char
+::=
+.I digit-char
+.|
+.B A
+|
+.B B
+|
+.B C
+|
+.B D
+|
+.B E
+|
+.B F
+.|
+.B a
+|
+.B b
+|
+.B c
+|
+.B d
+|
+.B e
+|
+.B f
+.
+.SS Punctuation
+.I punctuation
+::=
+any non-alphanumeric character
+other than
+.BR _ ,
+.BR """" ,
+or
+.B '
+.
+.SS Comments
+.I comment
+::=
+.I block-comment
+.|
+.I line-comment
+.br
+.I block-comment
+::=
+.<
+.B /*
+.IR not-star \**
+.RI ( star \*+
+.I not-star-or-slash
+.IR not-star \**)\**
+.IR star \**
+.B */
+.br
+.I star
+::=
+.B *
+.br
+.I not-star
+::=
+any character other than
+.B *
+.br
+.I not-star-or-slash
+::=
+any character other than
+.B *
+or
+.B /
+.br
+.I line-comment
+::=
+.B //
+.IR not-newline \**
+.I newline
+.br
+.I newline
+::=
+a newline character
+.br
+.I not-newline
+::=
+any character other than newline
+.
+.\"--------------------------------------------------------------------------
+.SH MODULE SYNTAX
+.
+.I module
+::=
+.IR definition \**
+.br
+.I definition
+::=
+.I import-definition
+.|
+.I load-definition
+.|
+.I lisp-definition
+.|
+.I typename-definition
+.|
+.I code-definition
+.|
+.I class-definition
+.
+.SS Simple definitions
+.I import-definition
+::=
+.B import
+.I string-literal
+.B ;
+.br
+.I load-definition
+::=
+.B load
+.I string-literal
+.B ;
+.br
+.I lisp-definition
+::=
+.B lisp
+.I s-expression
+.B ;
+.br
+.I typename-definition
+::=
+.B typename
+.IR list [ identifier ]
+.B ;
+.
+.SS Literal code fragments
+.br
+.I code-definition
+::=
+.<
+.B code
+.I identifier
+.B
+.I identifier
+.RI [ constraints ]
+.B {
+.I c-fragment
+.B }
+.br
+.I constraints
+::=
+.B [
+.IR list [ constraint ]
+.B ]
+.br
+.I constraint
+::=
+.IR identifier \*+
+.
+.SS Class definitions
+.I
+class-definition
+::=
+.I class-forward-declaration
+.|
+.I full-class-definition
+.br
+.I class-forward-declaration
+::=
+.B class
+.I identifier
+.B ;
+.br
+.I full-class-definition
+::=
+.RI [ properties ]
+.<
+.B class
+.I identifier
+.B :
+.IR list [ identifier ]
+.<
+.B {
+.IR class-item \**
+.B }
+.br
+.I class-item
+::=
+.I slot-item
+.|
+.I initializer-item
+.|
+.I message-item
+.|
+.I method-item
+.br
+.I slot-item
+::=
+.<
+.RI [ properties ]
+.IR declaration-specifier \*+
+.IR list [ init-declarator ]
+.B ;
+.br
+.I init-declarator
+::=
+.I simple-declarator
+.RB [ =
+.IR initializer ]
+.br
+.I initializer-item
+::=
+.RI [ properties ]
+.RB [ class ]
+.IR list [ slot-initializer ]
+.B ;
+.br
+.I slot-initializer
+::=
+.I dotted-name
+.B =
+.I initializer
+.br
+.I initializer
+::=
+.B {
+.I c-fragment
+.B }
+|
+.I c-fragment
+.br
+.I message-item
+::=
+.RI [ properties ]
+.<
+.IR declaration-specifier \*+
+.I simple-declarator
+.<
+.RI [ method-body ]
+.br
+.I method-item
+.RI [ properties ]
+.<
+.IR declaration-specifier \*+
+.I dotted-declarator
+.<
+.I method-body
+.br
+.I method-body
+::=
+.B {
+.I c-fragment
+.B }
+|
+.B extern
+.B ;
+.
+.SS Property sets
+.I properties
+::=
+.B [
+.IR list [ property ]
+.B ]
+.br
+.I property
+::=
+.I identifier
+.B =
+.I expression
+.br
+.I expression
+::=
+.I term
+|
+.I expression
+.B +
+.I term
+|
+.I expression
+.B \-
+.I term
+.br
+.I term
+::=
+.I factor
+|
+.I term
+.B *
+.I factor
+|
+.I term
+.B /
+.I factor
+.br
+.I factor
+::=
+.I primary
+|
+.B +
+.I factor
+|
+.B \-
+.B factor
+.br
+.I primary
+::=
+.I integer-literal
+|
+.I string-literal
+.ie t |
+.el .|
+.I char-literal
+|
+.I identifier
+.|
+.B ?
+.I s-expression
+.|
+.B (
+.I expression
+.B )
+.
+.SS C types
+.I declaration-specifier
+::=
+.I type-name
+.|
+.B struct
+.I identifier
+|
+.B union
+.I identifier
+|
+.B enum
+.I identifier
+.|
+.B void
+|
+.B char
+|
+.B int
+|
+.B float
+|
+.B double
+.|
+.B short
+|
+.B long
+.|
+.B signed
+|
+.B unsigned
+.|
+.I qualifier
+.br
+.I qualifier
+::=
+.B const
+|
+.B volatile
+|
+.B restrict
+.br
+.I type-name
+::=
+.I identifier
+.PP
+Declaration specifiers may appear in any order.
+However, not all combinations are permitted.
+A declaration specifier must consist of
+zero or more qualifiers,
+and one of the following, up to reordering.
+.hP \*o
+.I type-name
+.hP \*o
+.B struct
+.IR identifier ,
+.B union
+.IR identifier ,
+.B enum
+.I identifier
+.hP \*o
+.B void
+.hP \*o
+.BR char ,
+.BR "unsigned char" ,
+.B "signed char"
+.hP \*o
+.BR short ,
+.BR "unsigned short" ,
+.B "signed short"
+.hP \*o
+.BR "short int" ,
+.BR "unsigned short int" ,
+.B "signed short int"
+.hP \*o
+.BR int ,
+.BR "unsigned int" ,
+.BR "signed int" ,
+.BR unsigned ,
+.B signed
+.hP \*o
+.BR long ,
+.BR "unsigned long" ,
+.B "signed long"
+.hP \*o
+.BR "long int" ,
+.BR "unsigned long int" ,
+.B "signed long int"
+.hP \*o
+.BR "long long" ,
+.BR "unsigned long long" ,
+.B "signed long long"
+.hP \*o
+.BR "long long int" ,
+.BR "unsigned long long int" ,
+.B "signed long long int"
+.hP \*o
+.BR float ,
+.BR double ,
+.B long double
+.PP
+.IR declarator [ k ]
+::=
+.IR pointer \**
+.IR primary-declarator [ k ]
+.br
+.IR primary-declarator [ k ]
+::=
+.I k
+.|
+.B (
+.IR primary-declarator [ k ]
+.B )
+.|
+.IR primary-declarator [ k ]
+.IR declarator-suffix
+.br
+.I pointer
+::=
+.B *
+.IR qualifier \**
+.br
+.I declarator-suffix
+::=
+.B [
+.I c-fragment
+.B ]
+.|
+.B (
+.I arguments
+.B )
+.br
+.I arguments
+::=
+\*e |
+.B ...
+.|
+.IR list [ argument ]
+.RB [ ,
+.BR ... ]
+.br
+.I argument
+::=
+.IR declaration-specifier \*+
+.I argument-declarator
+.br
+.I argument-declarator
+::=
+.IR declarator [ identifier " | \*e]"
+.br
+.I simple-declarator
+::=
+.IR declarator [ identifier ]
+.br
+.I dotted-name
+::=
+.I identifier
+.B .\&
+.I identifier
+.br
+.I dotted-declarator
+::=
+.IR declarator [ dotted-name ]
+
+.\"--------------------------------------------------------------------------
+.SH SEE ALSO
+.BR sod (1),
+.BR sod (3),
+.BR sod-structs (3).
+.
+.\"--------------------------------------------------------------------------
+.SH AUTHOR
+Mark Wooding, <mdw@distorted.org.uk>
+.
+.\"----- That's all, folks --------------------------------------------------