chiark - git - mdw - sod/blob - 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 initarg-item
 546 .|
 547 .I fragment-item
 548 .|
 549 .I message-item
 550 .|
 551 .I method-item
 552 .br
 553 .I slot-item
 554 ::=
 555 .<
 556 .IR declaration-specifier \*+
 557 .IR list [ init-declarator ]
 558 .B ;
 559 .br
 560 .I init-declarator
 561 ::=
 562 .I simple-declarator
 563 .RB [ =
 564 .IR initializer ]
 565 .br
 566 .I initializer-item
 567 ::=
 568 .RB [ class ]
 569 .IR list [ slot-initializer ]
 570 .B ;
 571 .br
 572 .I slot-initializer
 573 ::=
 574 .I dotted-name
 575 .RB [ =
 576 .IR initializer ]
 577 .br
 578 .I initializer
 579 ::=
 580 .I c-fragment
 581 .br
 582 .I initarg-item
 583 ::=
 584 .<
 585 .B initarg
 586 .IR declaration-specifier \*+
 587 .IR list [ init-declarator ]
 588 .B ;
 589 .br
 590 .I fragment-item
 591 ::=
 592 .I fragment-kind
 593 .B {
 594 .I c-fragment
 595 .B }
 596 .br
 597 .I fragment-kind
 598 ::=
 599 .B init
 600 |
 601 .B teardown
 602 .br
 603 .I message-item
 604 ::=
 605 .<
 606 .IR declaration-specifier \*+
 607 .IR keyword-declarator [ identifier ]
 608 .<
 609 .RI [ method-body ]
 610 .br
 611 .I method-item
 612 ::=
 613 .<
 614 .IR declaration-specifier \*+
 615 .IR keyword-declarator [ dotted-name ]
 616 .<
 617 .I method-body
 618 .br
 619 .I method-body
 620 ::=
 621 .B {
 622 .I c-fragment
 623 .B }
 624 |
 625 .B extern
 626 .B ;
 627 .
 628 .SS Property sets
 629 .I properties
 630 ::=
 631 .B [
 632 .IR list [ property ]
 633 .B ]
 634 .br
 635 .I property
 636 ::=
 637 .I identifier
 638 .B =
 639 .I expression
 640 .br
 641 .I expression
 642 ::=
 643 .I term
 644 |
 645 .I expression
 646 .B +
 647 .I term
 648 |
 649 .I expression
 650 .B \-
 651 .I term
 652 .br
 653 .I term
 654 ::=
 655 .I factor
 656 |
 657 .I term
 658 .B *
 659 .I factor
 660 |
 661 .I term
 662 .B /
 663 .I factor
 664 .br
 665 .I factor
 666 ::=
 667 .I primary
 668 |
 669 .B +
 670 .I factor
 671 |
 672 .B \-
 673 .B factor
 674 .br
 675 .I primary
 676 ::=
 677 .I integer-literal
 678 |
 679 .I string-literal
 680 .ie t |
 681 .el .|
 682 .I char-literal
 683 |
 684 .I identifier
 685 .|
 686 .B <
 687 .I plain-type
 688 .B >
 689 .|
 690 .B ?
 691 .I s-expression
 692 .|
 693 .B (
 694 .I expression
 695 .B )
 696 .
 697 .SS C types
 698 .I declaration-specifier
 699 ::=
 700 .I type-name
 701 .|
 702 .B struct
 703 .I identifier
 704 |
 705 .B union
 706 .I identifier
 707 |
 708 .B enum
 709 .I identifier
 710 .|
 711 .B void
 712 |
 713 .B char
 714 |
 715 .B int
 716 |
 717 .B float
 718 |
 719 .B double
 720 .|
 721 .B short
 722 |
 723 .B long
 724 .|
 725 .B signed
 726 |
 727 .B unsigned
 728 .|
 729 .B bool
 730 |
 731 .B _Bool
 732 .|
 733 .B imaginary
 734 |
 735 .B _Imaginary
 736 |
 737 .B complex
 738 |
 739 .B _Complex
 740 .|
 741 .I qualifier
 742 .|
 743 .I storage-specifier
 744 .|
 745 .I atomic-type
 746 .br
 747 .I qualifier
 748 ::=
 749 .I atomic
 750 |
 751 .B const
 752 |
 753 .B volatile
 754 |
 755 .B restrict
 756 .br
 757 .I plain-type
 758 ::=
 759 .IR declaration-specifier \*+
 760 .I abstract-declarator
 761 .br
 762 .I atomic-type
 763 ::=
 764 .I
 765 atomic
 766 .B (
 767 .I plain-type
 768 .B )
 769 .br
 770 .I atomic
 771 ::=
 772 .B atomic
 773 |
 774 .B _Atomic
 775 .br
 776 .I storage-specifier
 777 ::=
 778 .I alignas
 779 .B (
 780 .I c-fragment
 781 .B )
 782 .br
 783 .I alignas
 784 ::=
 785 .B alignas
 786 |
 787 .B _Alignas
 788 .br
 789 .I type-name
 790 ::=
 791 .I identifier
 792 .PP
 793 The following
 794 .IR type-name s
 795 are defined in the built-in module.
 796 .hP \*o
 797 .B va_list
 798 .hP \*o
 799 .B size_t
 800 .hP \*o
 801 .B ptrdiff_t
 802 .hP \*o
 803 .B wchar_t
 804 .PP
 805 Declaration specifiers may appear in any order.
 806 However, not all combinations are permitted.
 807 A declaration specifier must consist of
 808 zero or more
 809 .IR qualifier s,
 810 zero or more
 811 .IR storage-specifier s,
 812 and one of the following, up to reordering.
 813 .hP \*o
 814 .I type-name
 815 .hP \*o
 816 .B struct
 817 .IR identifier ,
 818 .B union
 819 .IR identifier ,
 820 .B enum
 821 .I identifier
 822 .hP \*o
 823 .B void
 824 .hP \*o
 825 .BR char ,
 826 .BR "unsigned char" ,
 827 .B "signed char"
 828 .hP \*o
 829 .BR short ,
 830 .BR "unsigned short" ,
 831 .B "signed short"
 832 .hP \*o
 833 .BR "short int" ,
 834 .BR "unsigned short int" ,
 835 .B "signed short int"
 836 .hP \*o
 837 .BR int ,
 838 .BR "unsigned int" ,
 839 .BR "signed int" ,
 840 .BR unsigned ,
 841 .B signed
 842 .hP \*o
 843 .BR long ,
 844 .BR "unsigned long" ,
 845 .B "signed long"
 846 .hP \*o
 847 .BR "long int" ,
 848 .BR "unsigned long int" ,
 849 .B "signed long int"
 850 .hP \*o
 851 .BR "long long" ,
 852 .BR "unsigned long long" ,
 853 .B "signed long long"
 854 .hP \*o
 855 .BR "long long int" ,
 856 .BR "unsigned long long int" ,
 857 .B "signed long long int"
 858 .hP \*o
 859 .BR float ,
 860 .BR double ,
 861 .B long double
 862 .hP \*o
 863 .BR "float _Imaginary" ,
 864 .BR "double _Imaginary" ,
 865 .B "long double _Imaginary"
 866 .hP \*o
 867 .BR "float imaginary" ,
 868 .BR "double imaginary" ,
 869 .B "long double imaginary"
 870 .hP \*o
 871 .BR "float _Complex" ,
 872 .BR "double _Complex" ,
 873 .B "long double _Complex"
 874 .hP \*o
 875 .BR "float complex" ,
 876 .BR "double complex" ,
 877 .B "long double complex"
 878 .PP
 879 .IR declarator [ k ", " a ]
 880 ::=
 881 .IR pointer \**
 882 .IR primary-declarator [ k ", " a ]
 883 .br
 884 .IR primary-declarator [ k ", " a ]
 885 ::=
 886 .I k
 887 .|
 888 .B (
 889 .IR primary-declarator [ k ", " a ]
 890 .B )
 891 .|
 892 .IR primary-declarator [ k ", " a ]
 893 .IR declarator-suffix [ a ]
 894 .br
 895 .I pointer
 896 ::=
 897 .B *
 898 .IR qualifier \**
 899 .br
 900 .IR declarator-suffix [ a ]
 901 ::=
 902 .B [
 903 .I c-fragment
 904 .B ]
 905 .|
 906 .B (
 907 .I a
 908 .B )
 909 .br
 910 .I argument-list
 911 ::=
 912 \*e |
 913 .B ...
 914 .|
 915 .IR list [ argument ]
 916 .RB [ ,
 917 .BR ... ]
 918 .br
 919 .I argument
 920 ::=
 921 .IR declaration-specifier \*+
 922 .I argument-declarator
 923 .br
 924 .I abstract-declarator
 925 ::=
 926 .IR declarator "[\*e, " argument-list ]
 927 .br
 928 .I argument-declarator
 929 ::=
 930 .IR declarator [ identifier " | \*e, " argument-list ]
 931 .br
 932 .I simple-declarator
 933 ::=
 934 .IR declarator [ identifier ", " argument-list ]
 935 .br
 936 .I keyword-argument
 937 ::=
 938 .I argument
 939 .RB [ =
 940 .IR c-fragment ]
 941 .br
 942 .I keyword-argument-list
 943 ::=
 944 .I argument-list
 945 .B ?\&
 946 .I keyword-argument-list
 947 .br
 948 .I method-argument-list
 949 ::=
 950 .I argument-list
 951 |
 952 .I keyword-argument-list
 953 .br
 954 .I dotted-name
 955 ::=
 956 .I identifier
 957 .B .\&
 958 .I identifier
 959 .br
 960 .IR keyword-declarator [ k ]
 961 ::=
 962 .IR declarator [ k ", " method-argument-list ]
 963 .
 964 .\"--------------------------------------------------------------------------
 965 .SH SEE ALSO
 966 .BR sod (1),
 967 .BR sod (3),
 968 .BR sod-structs (3).
 969 .
 970 .\"--------------------------------------------------------------------------
 971 .SH AUTHOR
 972 Mark Wooding, <mdw@distorted.org.uk>
 973 .
 974 .\"----- That's all, folks --------------------------------------------------