New feature: messages with keyword arguments!
[sod] / src / sod-module.5
CommitLineData
9ed8eb2a
MW
1.\" -*-nroff-*-
2.\"
3.\" The Sod module syntax
4.\"
5.\" (c) 2015 Straylight/Edgeware
6.\"
7.
8.\"----- Licensing notice ---------------------------------------------------
9.\"
e0808c47 10.\" This file is part of the Sensible Object Design, an object system for C.
9ed8eb2a
MW
11.\"
12.\" SOD is free software; you can redistribute it and/or modify
13.\" it under the terms of the GNU General Public License as published by
14.\" the Free Software Foundation; either version 2 of the License, or
15.\" (at your option) any later version.
16.\"
17.\" SOD is distributed in the hope that it will be useful,
18.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
19.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
20.\" GNU General Public License for more details.
21.\"
22.\" You should have received a copy of the GNU General Public License
23.\" along with SOD; if not, write to the Free Software Foundation,
24.\" Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
25.
26.\" Highlight using terminal escapes, rather than overstriking.
27.\"\X'tty: sgr 1'
28.
29.\" String definitions and font selection.
30.ie t \{\
31. ds o \(bu
32. if \n(.g .fam P
33.\}
34.el \{\
35. ds o o
36.\}
37.
38.\" .hP TEXT -- start an indented paragraph with TEXT hanging off to the left
39.de hP
40.IP
41\h'-\w'\fB\\$1\ \fP'u'\fB\\$1\ \fP\c
42..
43.
44.\" An epsilon, or e.
45.ie t \{\
46. ds e \(*e
47. ds ^ \v'-.3m'\s'\\n(.s*7/10'
48. ds ^e \s0\v'.3m'
49. ds _ \v'.3m'\s'\\n(.s*7/10'
50. ds _e \s0\v'-.3m'
51.\}
52.el \{
53. ds e \fIe\fR
54. ds ^ ^
55. ds ^e
56. ds _ _
57. ds _e
58.\}
59.ds * \*^\(**\*(^e
60.ds + \*^+\*(^e
61.
62.de |
63.br
64\h'4n'|
65..
66.ie t \{\
67. de <
68..
69.\}
70.el
71. de <
72. br
73\h'4n'
74..
75.\}
76.
77.\"--------------------------------------------------------------------------
78.TH sod 5 "11 October 2015" "Straylight/Edgeware" "Sensible Object Design"
79.
80.SH NAME
81sod-module \- Sensible Object Design module syntax
82.
83.\"--------------------------------------------------------------------------
84.SH DESCRIPTION
85This manual page provides a highly compressed description of the
86Sod module syntax.
87For full details, consult the main manual.
88.PP
89.SS Notation
90Anywhere a simple nonterminal name
91.I x
92may appear in the grammar,
93an
94.I indexed
95nonterminal
96.IR x [ a \*_1\*(_e,
97\&...,
98.IR a \*_ n \*(_e]
99may also appear.
100On the left-hand side of a production rule,
101the indices
102.IR a \*_1\*(_e,
103\&...,
104.IR a \*_ n \*(_e
105are variables which vary over all nonterminal and terminal symbols,
106and the variables may also appear on the right-hand side
107in place of a nonterminal.
108Such a rule stands for a family of rules,
109in each variable is replaced by
110each possible simple nonterminal or terminal symbol.
111.PP
112The letter \*e denotes the empty nonterminal
113.IP
114.I \*e
115::=
116.PP
117The following indexed productions are used throughout the grammar, some often
118enough that they deserve special notation.
119.hP \*o
120.RI [ x ]
121abbreviates
122.IR optional [ x ],
123denoting an optional occurrence of
124.IR x :
125.RS
126.IP
127.RI [ x ]
128::=
129.IR optional [ x ]
130::=
131\*e
132|
133.I x
134.RE
135.hP \*o
136.IR x \**
137abbreviates
138.IR zero-or-more [ x ],
139denoting a sequence of zero or more occurrences of
140.IR x :
141.RS
142.IP
143.IR x \**
144::=
145.IR zero-or-more [ x ]
146::=
147\*e
148|
149.I x
150.IR x \**
151.RE
152.hP \*o
153.IR x \*+
154abbreviates
155.IR one-or-more [ x ]
156denoting a sequence of one or more occurrences of
157.IR x :
158.RS
159.IP
160.IR x \*+
161::=
162.IR one-or-more [ x ]
163::=
164.I x
165.IR x \**
166.RE
167.hP \*o
168.IR list [ x ]
169denotes a sequence of one or more occurrences of
170.I x
171separated by commas:
172.RS
173.IP
174.IR list [ x ]
175::=
176.I x
177|
178.IR list [ x ]
179.B ,
180.I x
181.RE
182.
183.SS Special nonterminals
184.I s-expression
185::=
186an S-expression, as parsed by the Lisp reader
187.br
188.I c-fragment
189::=
190a sequence of C tokens, with matching brackets
191.
192.\"--------------------------------------------------------------------------
193.SH LEXICAL SYNTAX
194.
195.SS Tokens
196.I token
197::=
198.I identifier
199.|
200.I string-literal
201.|
202.I char-literal
203.|
204.I integer-literal
205.|
206.I punctuation
207.
208.SS Identifiers
209.I identifier
210::=
211.I id-start-char
212.IR id-body-char \**
213.br
214.I id-start-char
215::=
216.I alpha-char
217|
218.B _
219.br
220.I id-body-char
221::=
222.I id-start-char
223|
224.I digit-char
225.br
226.I alpha-char
227::=
228.B A
229|
230.B B
231| ... |
232.B Z
233.|
234.B a
235|
236.B b
237| ... |
238.B z
239.|
240.I extended-alpha-char
241.br
242.I digit-char
243::=
244.B 0
245|
246.I nonzero-digit-char
247.br
248.I nonzero-digit-char
249::=
250.B 1
251|
252.B 2
253| ... |
254.B 9
255.PP
256The characters matched by
257.I extended-alpha-char
258depend on the locale and the host Lisp system.
259.
260.SS String and character literals
261.I string-literal
262::=
263.B """"
264.IR string-literal-char \**
265.B """"
266.br
267.I char-literal
268::=
269.B '
270.IR char-literal-char \**
271.B '
272.br
273.I string-literal-char
274::=
275any character other than
276.B \e
277or
278.B """"
279.|
280.B \e
281.I char
282.br
283.I char-literal-char
284::=
285any character other than
286.B \e
287or
288.B '
289.|
290.B \e
291.I char
292.
293.SS Integer literals
294.I integer-literal
295::=
296.I decimal-integer
297.|
298.I binary-integer
299.|
300.I octal-integer
301.|
302.I hex-integer
303.br
304.I decimal-integer
305::=
306.B 0
307|
308.I nonzero-digit-char
309.IR digit-char \**
310.br
311.I binary-integer
312::=
313.B 0
314.RB ( b | B )
315.IR binary-digit-char \*+
316.br
317.I binary-digit-char
318::=
319.B 0
320|
321.B 1
322.br
323.I octal-integer
324::=
325.B 0
326.RB [ o | O ]
327.IR octal-digit-char \*+
328.br
329.I octal-digit-char
330::=
331.B 0
332|
333.B 1
334| ... |
335.B 7
336.br
337.I hex-integer
338::=
339.B 0
340.RB ( x | X )
341.IR hex-digit-char \*+
342.br
343.I hex-digit-char
344::=
345.I digit-char
346.|
347.B A
348|
349.B B
350|
351.B C
352|
353.B D
354|
355.B E
356|
357.B F
358.|
359.B a
360|
361.B b
362|
363.B c
364|
365.B d
366|
367.B e
368|
369.B f
370.
371.SS Punctuation
372.I punctuation
373::=
374any non-alphanumeric character
375other than
376.BR _ ,
377.BR """" ,
378or
379.B '
380.
381.SS Comments
382.I comment
383::=
384.I block-comment
385.|
386.I line-comment
387.br
388.I block-comment
389::=
390.<
391.B /*
392.IR not-star \**
393.RI ( star \*+
394.I not-star-or-slash
395.IR not-star \**)\**
396.IR star \**
397.B */
398.br
399.I star
400::=
401.B *
402.br
403.I not-star
404::=
405any character other than
406.B *
407.br
408.I not-star-or-slash
409::=
410any character other than
411.B *
412or
413.B /
414.br
415.I line-comment
416::=
417.B //
418.IR not-newline \**
419.I newline
420.br
421.I newline
422::=
423a newline character
424.br
425.I not-newline
426::=
427any character other than newline
428.
429.\"--------------------------------------------------------------------------
430.SH MODULE SYNTAX
431.
432.I module
433::=
434.IR definition \**
435.br
436.I definition
437::=
438.I import-definition
439.|
440.I load-definition
441.|
442.I lisp-definition
443.|
444.I typename-definition
445.|
446.I code-definition
447.|
448.I class-definition
449.
450.SS Simple definitions
451.I import-definition
452::=
453.B import
454.I string-literal
455.B ;
456.br
457.I load-definition
458::=
459.B load
460.I string-literal
461.B ;
462.br
463.I lisp-definition
464::=
465.B lisp
466.I s-expression
467.B ;
468.br
469.I typename-definition
470::=
471.B typename
472.IR list [ identifier ]
473.B ;
474.
475.SS Literal code fragments
476.br
477.I code-definition
478::=
479.<
480.B code
481.I identifier
482.B
4fc52153 483.I item-name
9ed8eb2a
MW
484.RI [ constraints ]
485.B {
486.I c-fragment
487.B }
488.br
489.I constraints
490::=
491.B [
492.IR list [ constraint ]
493.B ]
494.br
495.I constraint
496::=
4fc52153
MW
497.IR item-name \*+
498.br
499.I item-name
500::=
501.I identifier
502|
503.B (
9ed8eb2a 504.IR identifier \*+
4fc52153 505.B )
9ed8eb2a
MW
506.
507.SS Class definitions
508.I
509class-definition
510::=
511.I class-forward-declaration
512.|
513.I full-class-definition
514.br
515.I class-forward-declaration
516::=
517.B class
518.I identifier
519.B ;
520.br
521.I full-class-definition
522::=
523.RI [ properties ]
524.<
525.B class
526.I identifier
527.B :
528.IR list [ identifier ]
529.<
530.B {
391c5a34 531.IR properties-class-item \**
9ed8eb2a
MW
532.B }
533.br
391c5a34
MW
534.I properties-class-item
535::=
536.RI [ properties ]
537.I class-item
538.br
9ed8eb2a
MW
539.I class-item
540::=
541.I slot-item
542.|
543.I initializer-item
544.|
545.I message-item
546.|
547.I method-item
548.br
549.I slot-item
550::=
551.<
9ed8eb2a
MW
552.IR declaration-specifier \*+
553.IR list [ init-declarator ]
554.B ;
555.br
556.I init-declarator
557::=
558.I simple-declarator
559.RB [ =
560.IR initializer ]
561.br
562.I initializer-item
563::=
9ed8eb2a
MW
564.RB [ class ]
565.IR list [ slot-initializer ]
566.B ;
567.br
568.I slot-initializer
569::=
570.I dotted-name
571.B =
572.I initializer
573.br
574.I initializer
575::=
576.B {
577.I c-fragment
578.B }
579|
580.I c-fragment
581.br
582.I message-item
583::=
9ed8eb2a
MW
584.<
585.IR declaration-specifier \*+
43073476
MW
586.IR keyword-declarator [ identifier ]
587.<
9ed8eb2a
MW
588.RI [ method-body ]
589.br
590.I method-item
391c5a34 591::=
9ed8eb2a
MW
592.<
593.IR declaration-specifier \*+
43073476
MW
594.IR keyword-declarator [ dotted-name ]
595.<
9ed8eb2a
MW
596.I method-body
597.br
598.I method-body
599::=
600.B {
601.I c-fragment
602.B }
603|
604.B extern
605.B ;
606.
607.SS Property sets
608.I properties
609::=
610.B [
611.IR list [ property ]
612.B ]
613.br
614.I property
615::=
616.I identifier
617.B =
618.I expression
619.br
620.I expression
621::=
622.I term
623|
624.I expression
625.B +
626.I term
627|
628.I expression
629.B \-
630.I term
631.br
632.I term
633::=
634.I factor
635|
636.I term
637.B *
638.I factor
639|
640.I term
641.B /
642.I factor
643.br
644.I factor
645::=
646.I primary
647|
648.B +
649.I factor
650|
651.B \-
652.B factor
653.br
654.I primary
655::=
656.I integer-literal
657|
658.I string-literal
659.ie t |
660.el .|
661.I char-literal
662|
663.I identifier
664.|
665.B ?
666.I s-expression
667.|
668.B (
669.I expression
670.B )
671.
672.SS C types
673.I declaration-specifier
674::=
675.I type-name
676.|
677.B struct
678.I identifier
679|
680.B union
681.I identifier
682|
683.B enum
684.I identifier
685.|
686.B void
687|
688.B char
689|
690.B int
691|
692.B float
693|
694.B double
695.|
696.B short
697|
698.B long
699.|
700.B signed
701|
702.B unsigned
703.|
2e01fd8b
MW
704.B bool
705|
706.B _Bool
707.|
708.B imaginary
709|
710.B _Imaginary
711|
712.B complex
713|
714.B _Complex
715.|
9ed8eb2a
MW
716.I qualifier
717.br
718.I qualifier
719::=
720.B const
721|
722.B volatile
723|
724.B restrict
725.br
726.I type-name
727::=
728.I identifier
729.PP
2e01fd8b
MW
730The following
731.IR type-name s
732are defined in the built-in module.
733.hP \*o
734.B va_list
735.hP \*o
736.B size_t
737.hP \*o
738.B ptrdiff_t
739.hP \*o
740.B wchar_t
741.PP
9ed8eb2a
MW
742Declaration specifiers may appear in any order.
743However, not all combinations are permitted.
744A declaration specifier must consist of
c32aa709
MW
745zero or more
746.IR qualifier s,
9ed8eb2a
MW
747and one of the following, up to reordering.
748.hP \*o
749.I type-name
750.hP \*o
751.B struct
752.IR identifier ,
753.B union
754.IR identifier ,
755.B enum
756.I identifier
757.hP \*o
758.B void
759.hP \*o
760.BR char ,
761.BR "unsigned char" ,
762.B "signed char"
763.hP \*o
764.BR short ,
765.BR "unsigned short" ,
766.B "signed short"
767.hP \*o
768.BR "short int" ,
769.BR "unsigned short int" ,
770.B "signed short int"
771.hP \*o
772.BR int ,
773.BR "unsigned int" ,
774.BR "signed int" ,
775.BR unsigned ,
776.B signed
777.hP \*o
778.BR long ,
779.BR "unsigned long" ,
780.B "signed long"
781.hP \*o
782.BR "long int" ,
783.BR "unsigned long int" ,
784.B "signed long int"
785.hP \*o
786.BR "long long" ,
787.BR "unsigned long long" ,
788.B "signed long long"
789.hP \*o
790.BR "long long int" ,
791.BR "unsigned long long int" ,
792.B "signed long long int"
793.hP \*o
794.BR float ,
795.BR double ,
796.B long double
2e01fd8b
MW
797.hP \*o
798.BR "float _Imaginary" ,
799.BR "double _Imaginary" ,
800.B "long double _Imaginary"
801.hP \*o
802.BR "float imaginary" ,
803.BR "double imaginary" ,
804.B "long double imaginary"
805.hP \*o
806.BR "float _Complex" ,
807.BR "double _Complex" ,
808.B "long double _Complex"
809.hP \*o
810.BR "float complex" ,
811.BR "double complex" ,
812.B "long double complex"
9ed8eb2a 813.PP
43073476 814.IR declarator [ k ", " a ]
9ed8eb2a
MW
815::=
816.IR pointer \**
43073476 817.IR primary-declarator [ k ", " a ]
9ed8eb2a 818.br
43073476 819.IR primary-declarator [ k ", " a ]
9ed8eb2a
MW
820::=
821.I k
822.|
823.B (
43073476 824.IR primary-declarator [ k ", " a ]
9ed8eb2a
MW
825.B )
826.|
43073476
MW
827.IR primary-declarator [ k ", " a ]
828.IR declarator-suffix [ a ]
9ed8eb2a
MW
829.br
830.I pointer
831::=
832.B *
833.IR qualifier \**
834.br
43073476 835.IR declarator-suffix [ a ]
9ed8eb2a
MW
836::=
837.B [
838.I c-fragment
839.B ]
840.|
841.B (
43073476 842.I a
9ed8eb2a
MW
843.B )
844.br
ea08dc56 845.I argument-list
9ed8eb2a
MW
846::=
847\*e |
848.B ...
849.|
850.IR list [ argument ]
851.RB [ ,
852.BR ... ]
853.br
854.I argument
855::=
856.IR declaration-specifier \*+
857.I argument-declarator
858.br
859.I argument-declarator
860::=
43073476 861.IR declarator [ identifier " | \*e, " argument-list ]
9ed8eb2a
MW
862.br
863.I simple-declarator
864::=
43073476
MW
865.IR declarator [ identifier ", " argument-list ]
866.br
867.I keyword-argument
868::=
869.I argument
870.RB [ =
871.IR c-fragment ]
872.br
873.I keyword-argument-list
874::=
875.I argument-list
876.B ?\&
877.I keyword-argument-list
878.br
879.I method-argument-list
880::=
881.I argument-list
882|
883.I keyword-argument-list
9ed8eb2a
MW
884.br
885.I dotted-name
886::=
887.I identifier
888.B .\&
889.I identifier
43073476
MW
890.br
891.IR keyword-declarator [ k ]
892::=
893.IR declarator [ k ", " method-argument-list ]
391c5a34 894.
9ed8eb2a
MW
895.\"--------------------------------------------------------------------------
896.SH SEE ALSO
897.BR sod (1),
898.BR sod (3),
899.BR sod-structs (3).
900.
901.\"--------------------------------------------------------------------------
902.SH AUTHOR
903Mark Wooding, <mdw@distorted.org.uk>
904.
905.\"----- That's all, folks --------------------------------------------------