mdw@git.distorted.org.uk Git - sod/blob - src/sod-module.5.in

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