86c29f8b13651780a9abb538d6f76f70f6870ac4
[sod] / src / sod-module.5
1 .\" -*-nroff-*-
2 .\"
3 .\" The Sod module syntax
4 .\"
5 .\" (c) 2015 Straylight/Edgeware
6 .\"
7 .
8 .\"----- Licensing notice ---------------------------------------------------
9 .\"
10 .\" This file is part of the Sensible Object Design, an object system for C.
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
81 sod-module \- Sensible Object Design module syntax
82 .
83 .\"--------------------------------------------------------------------------
84 .SH DESCRIPTION
85 This manual page provides a highly compressed description of the
86 Sod module syntax.
87 For full details, consult the main manual.
88 .PP
89 .SS Notation
90 Anywhere a simple nonterminal name
91 .I x
92 may appear in the grammar,
93 an
94 .I indexed
95 nonterminal
96 .IR x [ a \*_1\*(_e,
97 \&...,
98 .IR a \*_ n \*(_e]
99 may also appear.
100 On the left-hand side of a production rule,
101 the indices
102 .IR a \*_1\*(_e,
103 \&...,
104 .IR a \*_ n \*(_e
105 are variables which vary over all nonterminal and terminal symbols,
106 and the variables may also appear on the right-hand side
107 in place of a nonterminal.
108 Such a rule stands for a family of rules,
109 in each variable is replaced by
110 each possible simple nonterminal or terminal symbol.
111 .PP
112 The letter \*e denotes the empty nonterminal
113 .IP
114 .I \*e
115 ::=
116 .PP
117 The following indexed productions are used throughout the grammar, some often
118 enough that they deserve special notation.
119 .hP \*o
120 .RI [ x ]
121 abbreviates
122 .IR optional [ x ],
123 denoting 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 \**
137 abbreviates
138 .IR zero-or-more [ x ],
139 denoting 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 \*+
154 abbreviates
155 .IR one-or-more [ x ]
156 denoting 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 ]
169 denotes a sequence of one or more occurrences of
170 .I x
171 separated 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 ::=
186 an S-expression, as parsed by the Lisp reader
187 .br
188 .I c-fragment
189 ::=
190 a 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
256 The characters matched by
257 .I extended-alpha-char
258 depend 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 ::=
275 any character other than
276 .B \e
277 or
278 .B """"
279 .|
280 .B \e
281 .I char
282 .br
283 .I char-literal-char
284 ::=
285 any character other than
286 .B \e
287 or
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 ::=
374 any non-alphanumeric character
375 other than
376 .BR _ ,
377 .BR """" ,
378 or
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 ::=
405 any character other than
406 .B *
407 .br
408 .I not-star-or-slash
409 ::=
410 any character other than
411 .B *
412 or
413 .B /
414 .br
415 .I line-comment
416 ::=
417 .B //
418 .IR not-newline \**
419 .I newline
420 .br
421 .I newline
422 ::=
423 a newline character
424 .br
425 .I not-newline
426 ::=
427 any 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
483 .I item-name
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 ::=
497 .IR item-name \*+
498 .br
499 .I item-name
500 ::=
501 .I identifier
502 |
503 .B (
504 .IR identifier \*+
505 .B )
506 .
507 .SS Class definitions
508 .I
509 class-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 {
531 .IR properties-class-item \**
532 .B }
533 .br
534 .I properties-class-item
535 ::=
536 .RI [ properties ]
537 .I class-item
538 .br
539 .I class-item
540 ::=
541 .I slot-item
542 .|
543 .I initializer-item
544 .|
545 .I fragment-item
546 .|
547 .I message-item
548 .|
549 .I method-item
550 .br
551 .I slot-item
552 ::=
553 .<
554 .IR declaration-specifier \*+
555 .IR list [ init-declarator ]
556 .B ;
557 .br
558 .I init-declarator
559 ::=
560 .I simple-declarator
561 .RB [ =
562 .IR initializer ]
563 .br
564 .I initializer-item
565 ::=
566 .RB [ class ]
567 .IR list [ slot-initializer ]
568 .B ;
569 .br
570 .I slot-initializer
571 ::=
572 .I dotted-name
573 .B =
574 .I initializer
575 .br
576 .I initializer
577 ::=
578 .I c-fragment
579 .br
580 .I fragment-item
581 ::=
582 .I fragment-kind
583 .B {
584 .I c-fragment
585 .B }
586 .br
587 .I fragment-kind
588 ::=
589 .B init
590 |
591 .B teardown
592 .br
593 .I message-item
594 ::=
595 .<
596 .IR declaration-specifier \*+
597 .IR keyword-declarator [ identifier ]
598 .<
599 .RI [ method-body ]
600 .br
601 .I method-item
602 ::=
603 .<
604 .IR declaration-specifier \*+
605 .IR keyword-declarator [ dotted-name ]
606 .<
607 .I method-body
608 .br
609 .I method-body
610 ::=
611 .B {
612 .I c-fragment
613 .B }
614 |
615 .B extern
616 .B ;
617 .
618 .SS Property sets
619 .I properties
620 ::=
621 .B [
622 .IR list [ property ]
623 .B ]
624 .br
625 .I property
626 ::=
627 .I identifier
628 .B =
629 .I expression
630 .br
631 .I expression
632 ::=
633 .I term
634 |
635 .I expression
636 .B +
637 .I term
638 |
639 .I expression
640 .B \-
641 .I term
642 .br
643 .I term
644 ::=
645 .I factor
646 |
647 .I term
648 .B *
649 .I factor
650 |
651 .I term
652 .B /
653 .I factor
654 .br
655 .I factor
656 ::=
657 .I primary
658 |
659 .B +
660 .I factor
661 |
662 .B \-
663 .B factor
664 .br
665 .I primary
666 ::=
667 .I integer-literal
668 |
669 .I string-literal
670 .ie t |
671 .el .|
672 .I char-literal
673 |
674 .I identifier
675 .|
676 .B ?
677 .I s-expression
678 .|
679 .B (
680 .I expression
681 .B )
682 .
683 .SS C types
684 .I declaration-specifier
685 ::=
686 .I type-name
687 .|
688 .B struct
689 .I identifier
690 |
691 .B union
692 .I identifier
693 |
694 .B enum
695 .I identifier
696 .|
697 .B void
698 |
699 .B char
700 |
701 .B int
702 |
703 .B float
704 |
705 .B double
706 .|
707 .B short
708 |
709 .B long
710 .|
711 .B signed
712 |
713 .B unsigned
714 .|
715 .B bool
716 |
717 .B _Bool
718 .|
719 .B imaginary
720 |
721 .B _Imaginary
722 |
723 .B complex
724 |
725 .B _Complex
726 .|
727 .I qualifier
728 .br
729 .I qualifier
730 ::=
731 .B const
732 |
733 .B volatile
734 |
735 .B restrict
736 .br
737 .I type-name
738 ::=
739 .I identifier
740 .PP
741 The following
742 .IR type-name s
743 are defined in the built-in module.
744 .hP \*o
745 .B va_list
746 .hP \*o
747 .B size_t
748 .hP \*o
749 .B ptrdiff_t
750 .hP \*o
751 .B wchar_t
752 .PP
753 Declaration specifiers may appear in any order.
754 However, not all combinations are permitted.
755 A declaration specifier must consist of
756 zero or more
757 .IR qualifier s,
758 and one of the following, up to reordering.
759 .hP \*o
760 .I type-name
761 .hP \*o
762 .B struct
763 .IR identifier ,
764 .B union
765 .IR identifier ,
766 .B enum
767 .I identifier
768 .hP \*o
769 .B void
770 .hP \*o
771 .BR char ,
772 .BR "unsigned char" ,
773 .B "signed char"
774 .hP \*o
775 .BR short ,
776 .BR "unsigned short" ,
777 .B "signed short"
778 .hP \*o
779 .BR "short int" ,
780 .BR "unsigned short int" ,
781 .B "signed short int"
782 .hP \*o
783 .BR int ,
784 .BR "unsigned int" ,
785 .BR "signed int" ,
786 .BR unsigned ,
787 .B signed
788 .hP \*o
789 .BR long ,
790 .BR "unsigned long" ,
791 .B "signed long"
792 .hP \*o
793 .BR "long int" ,
794 .BR "unsigned long int" ,
795 .B "signed long int"
796 .hP \*o
797 .BR "long long" ,
798 .BR "unsigned long long" ,
799 .B "signed long long"
800 .hP \*o
801 .BR "long long int" ,
802 .BR "unsigned long long int" ,
803 .B "signed long long int"
804 .hP \*o
805 .BR float ,
806 .BR double ,
807 .B long double
808 .hP \*o
809 .BR "float _Imaginary" ,
810 .BR "double _Imaginary" ,
811 .B "long double _Imaginary"
812 .hP \*o
813 .BR "float imaginary" ,
814 .BR "double imaginary" ,
815 .B "long double imaginary"
816 .hP \*o
817 .BR "float _Complex" ,
818 .BR "double _Complex" ,
819 .B "long double _Complex"
820 .hP \*o
821 .BR "float complex" ,
822 .BR "double complex" ,
823 .B "long double complex"
824 .PP
825 .IR declarator [ k ", " a ]
826 ::=
827 .IR pointer \**
828 .IR primary-declarator [ k ", " a ]
829 .br
830 .IR primary-declarator [ k ", " a ]
831 ::=
832 .I k
833 .|
834 .B (
835 .IR primary-declarator [ k ", " a ]
836 .B )
837 .|
838 .IR primary-declarator [ k ", " a ]
839 .IR declarator-suffix [ a ]
840 .br
841 .I pointer
842 ::=
843 .B *
844 .IR qualifier \**
845 .br
846 .IR declarator-suffix [ a ]
847 ::=
848 .B [
849 .I c-fragment
850 .B ]
851 .|
852 .B (
853 .I a
854 .B )
855 .br
856 .I argument-list
857 ::=
858 \*e |
859 .B ...
860 .|
861 .IR list [ argument ]
862 .RB [ ,
863 .BR ... ]
864 .br
865 .I argument
866 ::=
867 .IR declaration-specifier \*+
868 .I argument-declarator
869 .br
870 .I argument-declarator
871 ::=
872 .IR declarator [ identifier " | \*e, " argument-list ]
873 .br
874 .I simple-declarator
875 ::=
876 .IR declarator [ identifier ", " argument-list ]
877 .br
878 .I keyword-argument
879 ::=
880 .I argument
881 .RB [ =
882 .IR c-fragment ]
883 .br
884 .I keyword-argument-list
885 ::=
886 .I argument-list
887 .B ?\&
888 .I keyword-argument-list
889 .br
890 .I method-argument-list
891 ::=
892 .I argument-list
893 |
894 .I keyword-argument-list
895 .br
896 .I dotted-name
897 ::=
898 .I identifier
899 .B .\&
900 .I identifier
901 .br
902 .IR keyword-declarator [ k ]
903 ::=
904 .IR declarator [ k ", " method-argument-list ]
905 .
906 .\"--------------------------------------------------------------------------
907 .SH SEE ALSO
908 .BR sod (1),
909 .BR sod (3),
910 .BR sod-structs (3).
911 .
912 .\"--------------------------------------------------------------------------
913 .SH AUTHOR
914 Mark Wooding, <mdw@distorted.org.uk>
915 .
916 .\"----- That's all, folks --------------------------------------------------