New feature: proper object lifecycle protocol; init and teardown fragments.

[sod] / src / sod-module.5

.\" -*-nroff-*-
.\"
.\" The Sod module syntax
.\"
.\" (c) 2015 Straylight/Edgeware
.\"
.
.\"----- Licensing notice ---------------------------------------------------
.\"
.\" This file is part of the Sensible 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 item-name
.RI [ constraints ]
.B {
.I c-fragment
.B }
.br
.I constraints
::=
.B [
.IR list [ constraint ]
.B ]
.br
.I constraint
::=
.IR item-name \*+
.br
.I item-name
::=
.I identifier
|
.B (
.IR identifier \*+
.B )
.
.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 properties-class-item \**
.B }
.br
.I properties-class-item
::=
.RI [ properties ]
.I class-item
.br
.I class-item
::=
.I slot-item
.|
.I initializer-item
.|
.I fragment-item
.|
.I message-item
.|
.I method-item
.br
.I slot-item
::=
.<
.IR declaration-specifier \*+
.IR list [ init-declarator ]
.B ;
.br
.I init-declarator
::=
.I simple-declarator
.RB [ =
.IR initializer ]
.br
.I initializer-item
::=
.RB [ class ]
.IR list [ slot-initializer ]
.B ;
.br
.I slot-initializer
::=
.I dotted-name
.B =
.I initializer
.br
.I initializer
::=
.I c-fragment
.br
.I fragment-item
::=
.I fragment-kind
.B {
.I c-fragment
.B }
.br
.I fragment-kind
::=
.B init
|
.B teardown
.br
.I message-item
::=
.<
.IR declaration-specifier \*+
.IR keyword-declarator [ identifier ]
.<
.RI [ method-body ]
.br
.I method-item
::=
.<
.IR declaration-specifier \*+
.IR keyword-declarator [ dotted-name ]
.<
.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
.|
.B bool
|
.B _Bool
.|
.B imaginary
|
.B _Imaginary
|
.B complex
|
.B _Complex
.|
.I qualifier
.br
.I qualifier
::=
.B const
|
.B volatile
|
.B restrict
.br
.I type-name
::=
.I identifier
.PP
The following
.IR type-name s
are defined in the built-in module.
.hP \*o
.B va_list
.hP \*o
.B size_t
.hP \*o
.B ptrdiff_t
.hP \*o
.B wchar_t
.PP
Declaration specifiers may appear in any order.
However, not all combinations are permitted.
A declaration specifier must consist of 
zero or more
.IR qualifier s,
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
.hP \*o
.BR "float _Imaginary" ,
.BR "double _Imaginary" ,
.B "long double _Imaginary"
.hP \*o
.BR "float imaginary" ,
.BR "double imaginary" ,
.B "long double imaginary"
.hP \*o
.BR "float _Complex" ,
.BR "double _Complex" ,
.B "long double _Complex"
.hP \*o
.BR "float complex" ,
.BR "double complex" ,
.B "long double complex"
.PP
.IR declarator [ k ", " a ]
::=
.IR pointer \**
.IR primary-declarator [ k ", " a ]
.br
.IR primary-declarator [ k ", " a ]
::=
.I k
.|
.B (
.IR primary-declarator [ k ", " a ]
.B )
.|
.IR primary-declarator [ k ", " a ]
.IR declarator-suffix [ a ]
.br
.I pointer
::=
.B *
.IR qualifier \**
.br
.IR declarator-suffix [ a ]
::=
.B [
.I c-fragment
.B ]
.|
.B (
.I a
.B )
.br
.I argument-list
::=
\*e |
.B ...
.|
.IR list [ argument ]
.RB [ ,
.BR ... ]
.br
.I argument
::=
.IR declaration-specifier \*+
.I argument-declarator
.br
.I argument-declarator
::=
.IR declarator [ identifier " | \*e, " argument-list ]
.br
.I simple-declarator
::=
.IR declarator [ identifier ", " argument-list ]
.br
.I keyword-argument
::=
.I argument
.RB [ =
.IR c-fragment ]
.br
.I keyword-argument-list
::=
.I argument-list
.B ?\&
.I keyword-argument-list
.br
.I method-argument-list
::=
.I argument-list
|
.I keyword-argument-list
.br
.I dotted-name
::=
.I identifier
.B .\&
.I identifier
.br
.IR keyword-declarator [ k ]
::=
.IR declarator [ k ", " method-argument-list ]
.
.\"--------------------------------------------------------------------------
.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 --------------------------------------------------