Commit | Line | Data |
---|---|---|
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 | |
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 identifier | |
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 identifier \*+ | |
498 | . | |
499 | .SS Class definitions | |
500 | .I | |
501 | class-definition | |
502 | ::= | |
503 | .I class-forward-declaration | |
504 | .| | |
505 | .I full-class-definition | |
506 | .br | |
507 | .I class-forward-declaration | |
508 | ::= | |
509 | .B class | |
510 | .I identifier | |
511 | .B ; | |
512 | .br | |
513 | .I full-class-definition | |
514 | ::= | |
515 | .RI [ properties ] | |
516 | .< | |
517 | .B class | |
518 | .I identifier | |
519 | .B : | |
520 | .IR list [ identifier ] | |
521 | .< | |
522 | .B { | |
523 | .IR class-item \** | |
524 | .B } | |
525 | .br | |
526 | .I class-item | |
527 | ::= | |
528 | .I slot-item | |
529 | .| | |
530 | .I initializer-item | |
531 | .| | |
532 | .I message-item | |
533 | .| | |
534 | .I method-item | |
535 | .br | |
536 | .I slot-item | |
537 | ::= | |
538 | .< | |
539 | .RI [ properties ] | |
540 | .IR declaration-specifier \*+ | |
541 | .IR list [ init-declarator ] | |
542 | .B ; | |
543 | .br | |
544 | .I init-declarator | |
545 | ::= | |
546 | .I simple-declarator | |
547 | .RB [ = | |
548 | .IR initializer ] | |
549 | .br | |
550 | .I initializer-item | |
551 | ::= | |
552 | .RI [ properties ] | |
553 | .RB [ class ] | |
554 | .IR list [ slot-initializer ] | |
555 | .B ; | |
556 | .br | |
557 | .I slot-initializer | |
558 | ::= | |
559 | .I dotted-name | |
560 | .B = | |
561 | .I initializer | |
562 | .br | |
563 | .I initializer | |
564 | ::= | |
565 | .B { | |
566 | .I c-fragment | |
567 | .B } | |
568 | | | |
569 | .I c-fragment | |
570 | .br | |
571 | .I message-item | |
572 | ::= | |
573 | .RI [ properties ] | |
574 | .< | |
575 | .IR declaration-specifier \*+ | |
576 | .I simple-declarator | |
577 | .< | |
578 | .RI [ method-body ] | |
579 | .br | |
580 | .I method-item | |
581 | .RI [ properties ] | |
582 | .< | |
583 | .IR declaration-specifier \*+ | |
584 | .I dotted-declarator | |
585 | .< | |
586 | .I method-body | |
587 | .br | |
588 | .I method-body | |
589 | ::= | |
590 | .B { | |
591 | .I c-fragment | |
592 | .B } | |
593 | | | |
594 | .B extern | |
595 | .B ; | |
596 | . | |
597 | .SS Property sets | |
598 | .I properties | |
599 | ::= | |
600 | .B [ | |
601 | .IR list [ property ] | |
602 | .B ] | |
603 | .br | |
604 | .I property | |
605 | ::= | |
606 | .I identifier | |
607 | .B = | |
608 | .I expression | |
609 | .br | |
610 | .I expression | |
611 | ::= | |
612 | .I term | |
613 | | | |
614 | .I expression | |
615 | .B + | |
616 | .I term | |
617 | | | |
618 | .I expression | |
619 | .B \- | |
620 | .I term | |
621 | .br | |
622 | .I term | |
623 | ::= | |
624 | .I factor | |
625 | | | |
626 | .I term | |
627 | .B * | |
628 | .I factor | |
629 | | | |
630 | .I term | |
631 | .B / | |
632 | .I factor | |
633 | .br | |
634 | .I factor | |
635 | ::= | |
636 | .I primary | |
637 | | | |
638 | .B + | |
639 | .I factor | |
640 | | | |
641 | .B \- | |
642 | .B factor | |
643 | .br | |
644 | .I primary | |
645 | ::= | |
646 | .I integer-literal | |
647 | | | |
648 | .I string-literal | |
649 | .ie t | | |
650 | .el .| | |
651 | .I char-literal | |
652 | | | |
653 | .I identifier | |
654 | .| | |
655 | .B ? | |
656 | .I s-expression | |
657 | .| | |
658 | .B ( | |
659 | .I expression | |
660 | .B ) | |
661 | . | |
662 | .SS C types | |
663 | .I declaration-specifier | |
664 | ::= | |
665 | .I type-name | |
666 | .| | |
667 | .B struct | |
668 | .I identifier | |
669 | | | |
670 | .B union | |
671 | .I identifier | |
672 | | | |
673 | .B enum | |
674 | .I identifier | |
675 | .| | |
676 | .B void | |
677 | | | |
678 | .B char | |
679 | | | |
680 | .B int | |
681 | | | |
682 | .B float | |
683 | | | |
684 | .B double | |
685 | .| | |
686 | .B short | |
687 | | | |
688 | .B long | |
689 | .| | |
690 | .B signed | |
691 | | | |
692 | .B unsigned | |
693 | .| | |
694 | .I qualifier | |
695 | .br | |
696 | .I qualifier | |
697 | ::= | |
698 | .B const | |
699 | | | |
700 | .B volatile | |
701 | | | |
702 | .B restrict | |
703 | .br | |
704 | .I type-name | |
705 | ::= | |
706 | .I identifier | |
707 | .PP | |
708 | Declaration specifiers may appear in any order. | |
709 | However, not all combinations are permitted. | |
710 | A declaration specifier must consist of | |
711 | zero or more qualifiers, | |
712 | and one of the following, up to reordering. | |
713 | .hP \*o | |
714 | .I type-name | |
715 | .hP \*o | |
716 | .B struct | |
717 | .IR identifier , | |
718 | .B union | |
719 | .IR identifier , | |
720 | .B enum | |
721 | .I identifier | |
722 | .hP \*o | |
723 | .B void | |
724 | .hP \*o | |
725 | .BR char , | |
726 | .BR "unsigned char" , | |
727 | .B "signed char" | |
728 | .hP \*o | |
729 | .BR short , | |
730 | .BR "unsigned short" , | |
731 | .B "signed short" | |
732 | .hP \*o | |
733 | .BR "short int" , | |
734 | .BR "unsigned short int" , | |
735 | .B "signed short int" | |
736 | .hP \*o | |
737 | .BR int , | |
738 | .BR "unsigned int" , | |
739 | .BR "signed int" , | |
740 | .BR unsigned , | |
741 | .B signed | |
742 | .hP \*o | |
743 | .BR long , | |
744 | .BR "unsigned long" , | |
745 | .B "signed long" | |
746 | .hP \*o | |
747 | .BR "long int" , | |
748 | .BR "unsigned long int" , | |
749 | .B "signed long int" | |
750 | .hP \*o | |
751 | .BR "long long" , | |
752 | .BR "unsigned long long" , | |
753 | .B "signed long long" | |
754 | .hP \*o | |
755 | .BR "long long int" , | |
756 | .BR "unsigned long long int" , | |
757 | .B "signed long long int" | |
758 | .hP \*o | |
759 | .BR float , | |
760 | .BR double , | |
761 | .B long double | |
762 | .PP | |
763 | .IR declarator [ k ] | |
764 | ::= | |
765 | .IR pointer \** | |
766 | .IR primary-declarator [ k ] | |
767 | .br | |
768 | .IR primary-declarator [ k ] | |
769 | ::= | |
770 | .I k | |
771 | .| | |
772 | .B ( | |
773 | .IR primary-declarator [ k ] | |
774 | .B ) | |
775 | .| | |
776 | .IR primary-declarator [ k ] | |
777 | .IR declarator-suffix | |
778 | .br | |
779 | .I pointer | |
780 | ::= | |
781 | .B * | |
782 | .IR qualifier \** | |
783 | .br | |
784 | .I declarator-suffix | |
785 | ::= | |
786 | .B [ | |
787 | .I c-fragment | |
788 | .B ] | |
789 | .| | |
790 | .B ( | |
791 | .I arguments | |
792 | .B ) | |
793 | .br | |
794 | .I arguments | |
795 | ::= | |
796 | \*e | | |
797 | .B ... | |
798 | .| | |
799 | .IR list [ argument ] | |
800 | .RB [ , | |
801 | .BR ... ] | |
802 | .br | |
803 | .I argument | |
804 | ::= | |
805 | .IR declaration-specifier \*+ | |
806 | .I argument-declarator | |
807 | .br | |
808 | .I argument-declarator | |
809 | ::= | |
810 | .IR declarator [ identifier " | \*e]" | |
811 | .br | |
812 | .I simple-declarator | |
813 | ::= | |
814 | .IR declarator [ identifier ] | |
815 | .br | |
816 | .I dotted-name | |
817 | ::= | |
818 | .I identifier | |
819 | .B .\& | |
820 | .I identifier | |
821 | .br | |
822 | .I dotted-declarator | |
823 | ::= | |
824 | .IR declarator [ dotted-name ] | |
825 | ||
826 | .\"-------------------------------------------------------------------------- | |
827 | .SH SEE ALSO | |
828 | .BR sod (1), | |
829 | .BR sod (3), | |
830 | .BR sod-structs (3). | |
831 | . | |
832 | .\"-------------------------------------------------------------------------- | |
833 | .SH AUTHOR | |
834 | Mark Wooding, <mdw@distorted.org.uk> | |
835 | . | |
836 | .\"----- That's all, folks -------------------------------------------------- |