home *** CD-ROM | disk | FTP | other *** search
/ CP/M / CPM_CDROM.iso / cpm / draco / draco-1.ark / DRACO.REF < prev    next >
Text File  |  1986-11-12  |  66KB  |  1,287 lines
  1.             Draco Quick Reference Guide
  2.  
  3.                Copyright 1983 by Chris Gray
  4.  
  5.  
  6. I. Using the compiler under CP/M
  7.     (CP/M is a trademark of Digital Research Incorporated)
  8.  
  9.     draco f1[.drc] f2[.drc] ... fn[.drc]
  10.  
  11.     Each file is a separate compilation; they need not be related. If no
  12.     extension is given, then .DRC is assumed. For each file, if the
  13.     compilation is successful, a corresponding .REL file is produced.
  14.     Standard CP/M ambiguous file specifications are accepted - all matching
  15.     files will be compiled.
  16.  
  17. II. Using the assembler under CP/M
  18.  
  19.     das f1[.das] f2[.das] ... fn[.das]
  20.  
  21.     Each file is a separate assembly. If no extension is given, then .DAS
  22.     is assumed. For each file, if the assembly is successful, a corresponding
  23.     .REL file is produced.
  24.  
  25. III. Using the link editor under CP/M
  26.  
  27.     link f1[.rel] f2[.rel] ... fn[.rel] fa.lib fb.lib ... fz.lib
  28.  
  29.     Each file is a .REL file produced by DAS or DRACO, a .LIB file produced 
  30.     by DLIB, or a .PLD file produced by LINK. If no extension is given on a 
  31.     file name, then .REL is assumed; thus libraries must have the .LIB given 
  32.     explicitly. Flags can be interspersed with the file names. Each flag 
  33.     starts with a minus sign (UNIX convention) and consists of several flag 
  34.     letters, and perhaps one flag value. The recognized flags and their 
  35.     meanings are: 
  36.  
  37.     m - produce a map of the load address of the various procedures and
  38.         the addresses of all local and global variable groups. This map
  39.         is sent to a file whose base name is the same as that of the
  40.         resulting .COM file (see later) and whose extension is ".MAP".
  41.         The symbols will be sorted alphabetically.
  42.     a - produce a map file as above, but sort the symbols by their load
  43.         addresses. This is useful when debugging.
  44.     i - suppress the normal Draco initialization code. This option should
  45.         only be used by assembler programmers. Note: LINK allocates
  46.         data areas before code areas if -d is not specified. Thus, if
  47.         neither -s nor -d are specified, the first .REL file must not
  48.         have any file variables, and the first procedure in it must not
  49.         have any local variables. If either set of variables exist,
  50.         they will be first in the .COM file, and will be at the entry
  51.         point to the program. This option also prevents the standard
  52.         libraries TRRUN.LIB and TRCPM.LIB from being automatically 
  53.         searched. (The 'TR' is from a previous name of the language.)
  54.     q - produce a program which will return to CP/M quickly. This is done
  55.         by using an alternate initialization section which leaves CP/M's
  56.         CCP untouched in memory, and which will simply return to CP/M
  57.         without doing a warm start. This flag should not be given when
  58.         linking programs which use CP/M's location 6 (pointer to warm
  59.         boot routine) to determine the top of available memory. The
  60.         pointer so returned does not take the CCP into account, and so
  61.         the resulting program will probably not run. A very smart program
  62.         could determine if it had been compiled with '-q' and subtract
  63.         the size of the CCP from the top-of-memory pointer. The standard
  64.         storage allocator does this by referencing the special symbols
  65.         '_DataEnd' and '_CodeEnd' which point to the ends of the data and
  66.         code portions of the final object file.
  67.     o - specifies the name for the resulting .COM file. The name must
  68.         immediately follow the 'o', with no intervening spaces or other
  69.         flags. If no explicit name is given, then the name is derived
  70.         from the name of the first .REL file in the parameter list.
  71.     c - specifies the first address to be used for program (code). The
  72.         value must follow immediately and is in hexadecimal. This option
  73.         is normally only useful for people who wish to produce .COM files
  74.         suitable for PROM burning. The default program start address is
  75.         0x100, which is the standard CP/M entry point.
  76.     d - specifies the first address to be used for data (variables). The
  77.         value must follow immediately and is in hexadecimal. This option
  78.         should be used for programs which have large data areas, or for
  79.         programs which are to be burned into PROMS. If no value is given,
  80.         then data areas are intermixed with code areas.
  81.     s - the linker is forced to take two passes for it's operation. The
  82.         first pass determines the total code size of the resulting
  83.         program, and the second pass does the actual linking, using a
  84.         data start address (as with the '-d' flag) just past the address
  85.         of the last byte of code. The 's' stands for small - the
  86.         resulting .COM file will be as small as possible (it will contain
  87.         only the code of the program) and the total space occupied will
  88.         be a minimum, since no gaps will exist. In linking with no flags
  89.         given, code and data will be intermixed, thus the data space will
  90.         occupy disk space in the .COM file
  91.     v - verbose. The linker prints out the names of the .REL and .LIB
  92.         files it is processing. This gives you something to watch when
  93.         linking a large program on slow disks.
  94.     p - requests that a .PLD file be produced representing the entire
  95.         program. This file is a machine readable map, in address order,
  96.         of all symbols loaded. The format is a 4 character hexadecimal
  97.         address, a space, the symbol name, and CR/LF for each symbol, and
  98.         an extra CR/LF at the end of the file. When such a PLD file is
  99.         given to LINK as input, the named symbols are assumed to pre-
  100.         exist at the given addresses. This could be because they are in
  101.         ROM or because they are in a program which has dynamically loaded
  102.         the program that is referencing them.
  103.  
  104.     The Draco linker provides partial support for a type of module, i.e. for
  105.     a fully independent package of routines with its own local variables,
  106.     it's own initialization and termination code, and a set of procedures
  107.     which are exported to its 'clients' or users. Most of this is provided
  108.     by the normal features of the Draco language. A module is written as a
  109.     single Draco source file, with its own local variables. Clients import
  110.     procedures from it in the normal way, using 'extern' declarations.
  111.  
  112.     The additional support provided by the linker works as follows. If a
  113.     procedure in a library is called, and the file which that procedure came
  114.     from contains another procedure called "_initialize", then the linker
  115.     will load "_initialize" and will generate code at the beginning of the
  116.     program to call it. Similarly, a routine called "_terminate" will be
  117.     automatically loaded and called at the end of the program (directly
  118.     returning to the system via "exit" or "SystemReset" will bypass the
  119.     termination call). There can be multiple occurrences of these special
  120.     symbols, so long as there is only one per source file.
  121.  
  122.     In the interests of portability, all versions of Draco will have
  123.     available a routine called "exit", which has a single integer parameter.
  124.     This routine will return directly to the host operating system. The
  125.     parameter passed is an error indicator, and should be 0 to indicate
  126.     successful execution. CP/M cannot make use of this returned error code,
  127.     but other systems can, so this facility is provided to simplify the
  128.     transportation of Draco programs among different systems.
  129.  
  130.     LINK's operation can involve one or two passes, each pass consisting of 
  131.     a read of the .REL files and one or more reads of the .LIB files. The
  132.     second pass is necessary only if the '-s' flag is given or if the program
  133.     is too large to fit into the available memory. When operating in two-pass
  134.     mode, LINK can produce a final .COM file larger than the amount of memory
  135.     on the machine on which LINK is running. LINK will automatically switch
  136.     to two-pass mode whenever the available memory runs out.
  137.  
  138.     Libraries produced by DLIB have a directory at the front which indicates
  139.     where in the library all of the individual procedures can be found. LINK
  140.     loads only those procedures which have been referenced, and it will scan
  141.     the libraries several times if needed to resolve all references. If a
  142.     procedure is loaded which references file-level global variables, then
  143.     space for those variables is allocated, and all procedures from that
  144.     original source file will reference them. When running under CP/M 1.0,
  145.     random access is not supported, so the entire library is actually read
  146.     in, but under later versions of CP/M, random access is used to reduce the
  147.     amount of actual disk I/O done.
  148.  
  149.     If a given symbol is present in more than one of the libraries being
  150.     scanned, then it is loaded from the first library encountered after the
  151.     first reference to the symbol. All .REL files are scanned first, in the
  152.     order they appear on the LINK command, then all .LIB files are scanned,
  153.     in the order they appear on the LINK command. The entire set of .LIB
  154.     files is rescanned if further unresolved references occur. If the first
  155.     reference to a symbol comes from a library member, then the search for
  156.     that symbol starts with the remainder of that library and continues on
  157.     with later ones.
  158.  
  159.     Because of this strictly forward searching, the order of placement of
  160.     symbols in libraries can be important. If a procedure in a given source
  161.     file which is to be part of a library references another procedure in
  162.     that source file, then the referenced procedure should be forward
  163.     declared and appear LATER in the source file than its referencer. This
  164.     approach minimizes the number of library scans needed to resolve all
  165.     references. All of the standard libraries are set up this way.
  166.  
  167.     Unless the '-i' flag is given, LINK will automatically add the libraries
  168.     'TRRUN.LIB' and 'TRCPM.LIB' to the end of the set of libraries searched.
  169.     TRRUN.LIB contains the run-time system, including support needed by the
  170.     compiler, the I/O library and the utility library described later.
  171.     TRCPM.LIB is an interface library which provides interface routines to
  172.     all of the CP/M entry points. Entry point names are exactly as given in
  173.     the CP/M manuals - e.g. SetDMAAddress, ReadSequential, etc. Most simple
  174.     programs will not need any other libraries, and thus can be linked by
  175.     simply giving all of the .REL files. A program with only one source file
  176.     xxx.drc can thus be compiled and linked by:
  177.  
  178.     draco xxx
  179.     link xxx
  180.  
  181.     A program with source files p1.drc, p2.drc and p3.drc, which references
  182.     the CRT library can be fully compiled and linked by:
  183.  
  184.     draco p?
  185.     link p1 p2 p3 crt.lib
  186.  
  187.     For a final version, the '-s' flag should probably be given.
  188.  
  189. IV. Using the disassembler under CP/M
  190.  
  191.     ddis [-r] f1[.rel] f2[.rel] ... fn[.rel]
  192.  
  193.     Each disassembly is separate. The files being disassembled can be
  194.     produced by either the compiler or the assembler. The disassembler knows
  195.     about all of the conventions and special code sequences produced by the
  196.     compiler. If no extension is given on a file name, then .REL is used.
  197.     Each disassembly produces a .DIS file corresponding to the .REL file.
  198.     The contents of the .DIS file is assembler source, suitable for
  199.     assembling with DAS. The disassembler does not generate correct
  200.     declarations for file variables (it uses only the information passed in
  201.     the relocation information, which may not completely identify them
  202.     without processing the entire program). Also, since the assembler does
  203.     not handle global variables, no declarations for them are produced.
  204.     The '-r' flag requests that code labels not appear and branches use a
  205.     position-relative form (*-n or *+n). This is useful when working with
  206.     a printed, out-of-date disassembly listing, since most of the branches
  207.     will still be correct.
  208.  
  209. V. Using the librarian under CP/M
  210.  
  211.     dlib f[.lib]
  212.     dlib f[.lib] f1[.rel] f2[.rel] ... fn[.rel]
  213.  
  214.     In the first form, the already existing library file is read in, and a
  215.     listing of it's contents is produced on the console. In the second form,
  216.     the (1 or more) .REL files are read, and a .LIB library is constructed
  217.     from them. This is a two pass operation, and the name of the .REL file
  218.     currently being read is printed on each pass.
  219.  
  220. VI. Using the cross-referencer under CP/M
  221.  
  222.     xref [-supo<file>] x1[.rel] ... xn[.rel]
  223.  
  224.     A cross reference listing of the procedures in the given .REL files
  225.     is produced. If no flags are given, the listing is produced on the
  226.     console. If '-p' is given, the listing is sent to the printer. If '-o'
  227.     followed by a filename is given, the listing is sent to that file. Flag
  228.     '-s' tells the cross-referencer to include procedures whose names start
  229.     with an underscore ('-') - the default is to omit such procedures, since
  230.     they are usually part of the run-time system or private to a library.
  231.     Flag '-u' tells the cross-referencer to include procedures whose names
  232.     start with an upper-case letter - the default is to omit such procedures,
  233.     since they are usually library routines, not part of the current program.
  234.     Note that the cross referencer works on the .REL files, NOT the .DRC
  235.     source files, thus it cross references only procedure calls, and only
  236.     those that are not conditionally compiled out.
  237.  
  238. VII. Draco source files
  239.  
  240.     Source files for the Draco compiler are either normal source files,
  241.     usually with an extension of .DRC, or are declaration include files,
  242.     usually with an extension of .G. Declaration include files can contain
  243.     only declarations (constant, type, external, variable), and the symbols
  244.     declared in them are called 'global', and are available to all procedures
  245.     in all source files which include that particular include file.
  246.  
  247.     Normal source files contain, in the order given:
  248.  
  249.     - 0 or more include file references. These must start in the first
  250.         column of the first line, and consist of a backslash (\) or
  251.         number sign (#) followed by the name of the include file being
  252.         referenced. Several such references may occur, one per line,
  253.         with no intervening spaces or comments. When a program consists
  254.         of more than one source file, each of the source files will
  255.         usually have the same set of include file references. The link
  256.         editor requires that the 'global' variables be consistent among
  257.         all .REL files being linked. .REL files being put into libraries
  258.         may not have any 'global' variables.
  259.  
  260.     - declarations. These declarations are called 'file' declarations,
  261.         and are available to all procedures in that particular source
  262.         file. Short Draco programs, consisting of only one source file,
  263.         will not have any 'global' declarations - the 'file' declarations
  264.         will play that role. In larger programs, 'file' declarations are
  265.         still useful, in that procedures associated with a given portion
  266.         of a program can be assembled in one file, and any declarations
  267.         private to those procedures can be 'file' declarations in that
  268.         file, and thus will not be accessible to any other procedures.
  269.         Also, 'file' declarations are common in files which are to be
  270.         used as part of a library, since any 'file' variables will be
  271.         allocated (assigned real memory addresses) by the link-editor
  272.         whenever a routine from that file is referenced.
  273.     
  274.     - procedures. Each procedure can have it's own set of local
  275.         declarations (it's parameters are assumed to be part of that
  276.         set). These declarations are accessible only within that
  277.         procedure, and the values of any variables are not preserved
  278.         between activations of the procedure. Procedures defined in a
  279.         source file are considered to be declared for the remainder of
  280.         that source file. If circular referencing of procedures is
  281.         required, then a 'file' level extern declaration of the procedure
  282.         can be given before the procedure is used, and, so long as that
  283.         declaration is consistent with the final definition, the compiler
  284.         will not complain. Because of the compiler's requirement that
  285.         all symbols be declared before they are used, the simplest
  286.         arrangement of source files is that which puts the lowest-level
  287.         routines first, and the highest-level routines (those which call
  288.         the lower-level ones) last. Thus, short programs consisting of
  289.         only one source file will normally put procedure 'main' last.
  290.         (All Draco programs must have a procedure 'main', since the
  291.         initialization code starts program execution by calling 'main'.)
  292.  
  293.         In keeping with a highly readable convention used by some UNIX 
  294.         programmers, it is suggested that all 'global' and 'file' 
  295.         symbols begin with a capital letter, and all local symbols 
  296.         begin with a small letter (other than constants). In keeping 
  297.         with this convention the names of all routines in all libraries 
  298.         supplied with Draco begin with a capital letter. Even though 
  299.         procedure definitions are technically 'file' declarations, such 
  300.         procedures, unless they are to be part of an externally 
  301.         available library, should have names beginning with small
  302.         letters.
  303.  
  304.         Draco takes a different approach to scope than many standard
  305.         algorithmic languages. Languages such as Pascal, Algol68, etc.
  306.         allow the declaration of an identifier, at an inner scope level,
  307.         which is already declared at an outer scope level. For the
  308.         duration of that scope, the new, inner, declaration masks the
  309.         outer declaration so that the outer meaning of the identifier
  310.         is not available. In Draco, it is illegal to attempt to declare
  311.         an identifier which already exists, regardless of the scope
  312.         levels of the declarations (Draco only has 3 levels anyway -
  313.         global, file and local). Several procedures can declare the same
  314.         identifier locally (names such as 'i', 'p', 'n', etc. are quite
  315.         common), but they cannot declare a name which exists at either
  316.         the global or file level. Similarly, at the file level, a name
  317.         cannot be used which is already in use at the global level. This
  318.         approach is used so as to eliminate the problems arising from
  319.         accidentally masking an outer meaning in a situation which uses
  320.         that outer meaning, but also declares a similar, inner meaning.
  321.         This situation can result in bugs which are very difficult to
  322.         detect. If the naming convention suggested above is used, little
  323.         inconvenience will occur. Also, since Draco imposes no limit on
  324.         the length of identifiers, there should be no problem in choosing
  325.         meaningful ones.
  326.  
  327. VIII. Declarations
  328.  
  329.     Declarations in Draco can be of constants, types, variables or external 
  330.     procedures. 
  331.  
  332.     Constant declarations consist of the type, followed by the identifiers, 
  333.     along with an '=' and their value. Constants can be numeric (signed or 
  334.     unsigned), single character, or 'chars' values. In keeping with a highly 
  335.     readable convention used on UNIX systems, it is suggested that the names 
  336.     of constants be fully capitalized. Example constant declarations:
  337.     
  338.     word MAX_LENGTH = 1000,
  339.          ENTRY_COUNT = 10;
  340.     char BEL = '\(7)', BS = '\b', LETTER_F = 'f';
  341.     *char AUTHOR = "Sam Spade";
  342.     unsigned 255 LIMIT = 255 - 1;
  343.     
  344.     The values used for constants can be any expression whose value can be
  345.     determined at compile time by the compiler. This can include conditional
  346.     expressions, so long as the conditions are known at compile time.
  347.  
  348.     Type declarations consist of the word 'type', followed by the names of
  349.     the new types, each followed by '=' and the type's definition. The
  350.     various kinds of types in Draco are as follows:
  351.     
  352.     - signed numeric types. These are specified by the word 'signed',
  353.         followed by a constant expression giving the upper bound on the
  354.         positive values allowed. The negative values have a similar
  355.         limit (one less for 2's complement machines). The maximum value
  356.         of the limit will vary from machine to machine and possibly from
  357.         version to version of the compiler. All versions will allow at
  358.         least 'signed 32767'. In programs where execution time must be
  359.         minimized, the programmer should use numeric types with the
  360.         smallest possible range. This allows the compiler to generate
  361.         more efficient code for CPU's which do some types of arithmetic
  362.         better than others.
  363.     
  364.     - unsigned numeric types. These are specified by the word 'unsigned',
  365.         followed by a constant expression giving the upper bound on the
  366.         values allowed (the lower bound is 0). Signed and unsigned values
  367.         can be mixed in arithmetic operations. The two kinds of values
  368.         can be compared for equality, but not for magnitude (they use the
  369.         same bit pattern for different values).
  370.     
  371.     - enumerated types. These are specified by the word 'enum', followed
  372.         by an open brace ({), followed by a list of the named values of
  373.         this type, followed by a close brace (}). The values named in the
  374.         list are the only allowed values of this type. They can be
  375.         compared (all comparisons are meaningful), subtracted (the result
  376.         is an unsigned numeric), and can have a numeric added to or
  377.         subtracted from them (the result is another value of the same
  378.         enumerated type). This kind of type is usually used for flag
  379.         values, where the flag can take on a limited set of values. A
  380.         sample enumerated type:
  381.         
  382.         enum {c_red, c_yellow, c_blue, c_black, c_white}
  383.  
  384.     - pointer types. These are specified by an '*' preceding the type 
  385.         which is to be pointed to. Thus, '*int' is a type specification 
  386.         meaning 'pointer to integer'. In the language's single exception 
  387.         to the requirement that all identifiers be declared before they 
  388.         can be used, the pointed to type can be an undeclared symbol, 
  389.         which is assumed to be an as-yet undeclared type, which must be 
  390.         declared before the end of the current set of declarations. This 
  391.         rule relaxation is used to allow the construction of circularly 
  392.         referencing structures. Pointer values can be compared, 
  393.         subtracted (as long as the values are of the same pointer type), 
  394.         and can have a numeric value added to or subtracted from them. 
  395.         Unlike similar operations in the 'C' language, the value being 
  396.         added or subtracted is not multiplied by the size of the 
  397.         pointed-to type. Pointer values are usually generated via the '&'
  398.         address-of operator, or by using a 'chars' constant, which is of 
  399.         type *char. The predefined value 'nil' is compatible with all 
  400.         pointer types. 
  401.  
  402.     - array types. These are specified by a left square bracket ([),
  403.         followed by a list of constant expressions giving the size of the
  404.         array in that dimension, followed by a right square bracket (]),
  405.         followed by the type of the array elements. There is no limit on
  406.         the number of dimensions of an array, but the user must keep in
  407.         mind the amount of memory occupied by the array as compared to
  408.         the amount of memory available on the computer system. Arrays
  409.         are stored in row-major order, i.e. when scanning along an array
  410.         in memory, the last index varies most frequently. Array values
  411.         can be assigned. Sample array types:
  412.         
  413.         [MAX_NAME_LENGTH + 1] char
  414.         [M, N, P] int
  415.         [BLOCK_COUNT] [BLOCK_LEN] unsigned 32
  416.  
  417.     - structure types. These are specified by the word 'struct', followed
  418.         by a left brace bracket ({), followed by the types and names of
  419.         the fields of the structure, followed by a right brace bracket
  420.         (}). Unlike some other languages, Draco does not allow field
  421.         names to be re-used; all must be unique. The easiest way to do
  422.         this is to follow yet another highly readable UNIX convention
  423.         which names all fields of a structure as a short abbreviation of
  424.         the structure name (1 - 3 letters), followed by an underscore (_)
  425.         and the mnemonic name of the field. Like array types, structure
  426.         types can be assigned. Some structure declarations:
  427.  
  428.         type
  429.             ProcessState_t = struct {
  430.             word st_programCounter, st_stackPointer;
  431.             [8] word st_registers;
  432.             byte st_statusRegister;
  433.             },
  434.  
  435.             Process_t = struct {
  436.             int pr_priority;
  437.             *Process_t pr_parent, pr_children, pr_nextSibling;
  438.             ProcessState_t pr_state;
  439.             *ProcessQueue_t pr_waitQueue;
  440.             },
  441.  
  442.             ProcessQueue_t = struct {
  443.             *ProcessQueue_t pq_next;
  444.             *Process_t pq_this;
  445.             };
  446.  
  447.     - union types. Union types are declared exactly like structure types
  448.         except that the word 'union' replaces the word 'struct'. Union
  449.         types are similar to unions in 'C', in that they specify a type
  450.         which is a set of types. The space allocated for a value of a
  451.         union type is the maximum of the spaces needed for the various
  452.         member types in the union. The programmer informs the compiler
  453.         which of the member types is currently active by selecting the
  454.         member type, exactly as a field of a structure is selected, when
  455.         the union value is referenced or assigned to as other than the
  456.         union type. Union types are useful when constructing networks of
  457.         nodes, and the nodes are of differing natures, but all are
  458.         pointed to by other nodes. The alternative of having separate
  459.         pointers for each possible node type is very wasteful of memory.
  460.         Sample union type: (this one from a railroad simulation)
  461.  
  462.         type
  463.             Track_t = union {
  464.             int tr_straight;    /* straight track option */
  465.             struct {        /* turnout option */
  466.                 int trn_length;
  467.                 bool trn_open;
  468.                 bool trn_isRight;
  469.             } tr_turnout;
  470.             };
  471.  
  472.     - procedure types. These types are declared similarly to actual
  473.         procedure headers, except that no procedure name occurs, no
  474.         machine specific options (e.g. 'nonrec') can occur, and the names
  475.         of the parameters are required, but are irrelevant. Procedure
  476.         values can be compared for equality, assigned, and called. Sample
  477.         procedure types:
  478.         
  479.         proc (int a, b)int
  480.         proc (proc (char c)void putChar; *char charsPtr)void
  481.         proc ([12]**int x, y)[12]**int
  482.  
  483.     - operator types. This kind of type is Draco's (somewhat limited) way
  484.         of being an extensible language. Syntactically an operator type
  485.         consists of an open parenthesis, a string constant, a comma, a
  486.         base type, a comma, a numeric constant and a close parenthesis.
  487.         The string constant is a prefix which is used to build the names
  488.         of the procedures that the compiler will generate calls to in
  489.         order to do operations on values of this new type. The base type
  490.         is the type that is the underlying representation of this new
  491.         type, and the numeric constant is a set of 16 bits, indicating
  492.         which operations are enabled for this type. Operator types will
  493.         be explained in a later section.
  494.  
  495.     Types in Draco can be combined in arbitrary ways. The only 
  496.     limitations imposed by the compiler are those inherent in the sizes 
  497.     of the type table and the type information table. The question of 
  498.     type equivalence is answered in Draco in the following way: two 
  499.     types are equivalent if they are equivalently constructed from
  500.     equivalent component types. The determination of type equivalence is
  501.     done while the compiler is parsing the type specification. Thus, in
  502.     the following:
  503.     
  504.         [12] int a;
  505.         [10 + 4 / 2] int b;
  506.  
  507.     'a' and 'b' will have the same type. The type of 'b' is equivalent 
  508.     to the type of 'a', and so will BE the type of 'a'. If a type is
  509.     given a name via a type declaration, however, then that type is 
  510.     unique and is not equivalent to any other named type. Thus, if we
  511.     declare: 
  512.  
  513.         type T1 = [10] int,
  514.          T2 = [10] int;
  515.         T1 a;
  516.         T2 b;
  517.         [10] int c;
  518.  
  519.     Types T1 and T2 are not equivalent, and 'a' and 'b' cannot be 
  520.     assigned to one-another. Both can be assigned to or from 'c', 
  521.     however, else there would be no way to generate values of named 
  522.     types. This scheme is an attempted compromise between the need for 
  523.     usability of named types, and the desire to have the compiler 
  524.     protect us from mistakes when two named types just happen to have 
  525.     equivalent definitions. Signed or unsigned numeric types which are 
  526.     named are always compatible with other named or unnamed numeric
  527.     types, whether equivalent or not.
  528.  
  529.     The following types are supplied predefined:
  530.  
  531.         int - signed numeric using the standard fully supported word
  532.         size on the host processor 
  533.         short - smaller sized signed value (often 8 bit)
  534.         word - unsigned numeric, same size as int
  535.         ushort - unsigned numeric, same size as short
  536.         byte - unsigned numeric, one byte long (8 bits)
  537.         char - enumeration type of all 256 character values
  538.         bool - enumeration type consisting of 'false' and 'true'
  539.  
  540.     Most programs can safely use types 'int' and 'word', since they will 
  541.     always be at least 16 bits long. The careful programmer will usually 
  542.     use his/her own signed and unsigned types, however, so that the 
  543.     reader is always aware of the range of possible values, and so that 
  544.     compilers can optimally decide the implemented size of variables
  545.     (which may vary from processor to processor). 
  546.  
  547.     Variable declarations consist of the type (either named or explicit) 
  548.     followed by a comma separated list of identifiers. This format is 
  549.     similar to that used for constants, but combining the two is not 
  550.     advised, since doing so can be confusing. 
  551.  
  552.     External procedure declarations consist of the word 'extern' followed
  553.     by a list of procedure headers, complete with procedure name, parameter
  554.     types and names, and result type.
  555.  
  556. IX. Procedures
  557.  
  558.     Each Draco procedure definition begins with the word 'proc', followed
  559.     by any special machine dependent modifiers, followed by the name of the
  560.     procedure, followed by a procedure header, followed by a colon, followed
  561.     by the body of the procedure and a final terminating word, 'corp'. A
  562.     procedure header consists of '(', optional parameter declarations, ')',
  563.     and the result type (or 'void' for procedures which don't return a
  564.     result). Note that the parentheses are required, even if no parameters
  565.     are declared. Parameter declarations are just like variable declarations.
  566.  
  567.     Unlike Pascal and C, Draco provides a way for arrays of differing sizes
  568.     to be passed to a common procedure. An array parameter can use an
  569.     asterisk (*) for the size of one or more of its dimensions, instead of
  570.     the normal constant expression. When such a procedure is called, the
  571.     compiler will automatically pass the true size of the dimensions of the
  572.     passed array along with the array. These true sizes can be determined
  573.     inside the procedure via the 'dim' construct. Note that this method can
  574.     only be used for parameter arrays, and can only be used for top level
  575.     arrays (e.g. if the parameter is an array of arrays, then only the top-
  576.     level array can have '*' sizes).
  577.  
  578.     If the procedure is to return a result, the type placed between the
  579.     closing ')' of it's header and the following ':' is the type expected
  580.     by the compiler. Conversions among various numeric types are allowed
  581.     here as elsewhere. The result is returned by placing it at the end of
  582.     the procedure's body, just before the closing 'corp'. There must not be
  583.     a semicolon after the result, since the compiler uses the semicolon as
  584.     a signal that the previous unit should have been a statement. As a sample
  585.     procedure, here is the old standard, "Towers of Hanoi":
  586.  
  587.     proc hanoi(int n; *char from, to, using)void:
  588.  
  589.         if n > 0 then
  590.         hanoi(n - 1, from, using, to);
  591.         writeln("Move disk ", n, " from peg ", from, " to peg ", to);
  592.         hanoi(n - 1, using, to, from);
  593.         fi;
  594.     corp;
  595.     
  596.     A standard procedure with a result:
  597.     
  598.     proc minimum([*] int a)int:
  599.         int i, min;
  600.  
  601.         min := a[0];
  602.         for i from 1 upto dim(a, 1) - 1 do
  603.         if a[i] < min then
  604.             min := a[i];
  605.         fi;
  606.         od;
  607.         min
  608.     corp;
  609.  
  610. X. Statements in Draco
  611.  
  612.     Draco is a fairly standard programming language, along the lines of
  613.     Pascal, C, and Algol. Where several statements are allowed, they are
  614.     separated by semicolons (the semicolon is a separator, not a terminator).
  615.     The standard statement forms in Draco are:
  616.     
  617.     - assignment statement. This is the usual, consisting of the destination,
  618.     a ':=', and the source expression.
  619.     
  620.     - procedure call statement. This consists of the procedure's name (or an
  621.     expression yielding a procedure), followed by the procedure's
  622.     parameters, enclosed in parentheses. The parentheses must be present,
  623.     even if the procedure has no parameters (this makes it very clear
  624.     when something is being called - useful for procedures such as random
  625.     number generators which have no parameters but return a result).
  626.     The parameters passed must be compatible with those specified in
  627.     the defining procedure header, in terms of both type and number.
  628.     
  629.     - if statements. If statements in Draco are syntactically identical to
  630.     if statements in Algol68. The simplest form consists of the word
  631.     'if', followed by an expression of type 'bool', followed by the word
  632.     'then', followed by a sequence of statements to be executed when the
  633.     bool yields 'true', followed by the word 'fi'. An 'else' clause,
  634.     which is executed when the bool yields 'false', can be placed between
  635.     the 'true' statements and the 'fi'. An 'else' clause consists of the
  636.     word 'else' and a sequence of statements. As in Algol68, alternate
  637.     conditions, consisting of the word 'elif', a bool expression, the
  638.     word 'then', and a statement sequence, can be placed between the
  639.     first statement sequence and the 'else' (or 'fi' if there is no
  640.     'else'). In that case, the conditions are evaluated one at a time,
  641.     until one is found that yields 'true'. The corresponding statement
  642.     sequence is then executed. Only if no condition yields 'true' will
  643.     the 'else' statements be executed. When a condition has yielded
  644.     'true', no more conditions will be evaluated. As an example,
  645.     
  646.         if a then
  647.         b
  648.         elif c then
  649.         d
  650.         elif e then
  651.         f
  652.         else
  653.         g
  654.         fi
  655.     
  656.     is equivalent to
  657.     
  658.         if a then
  659.         b
  660.         else
  661.         if c then
  662.             d
  663.         else
  664.             if e then
  665.             f
  666.             else
  667.             g
  668.             fi
  669.         fi
  670.         fi
  671.     
  672.     The advantage of the 'elif' form is fairly obvious - it has far less
  673.     indentation for the same logic.
  674.     
  675.     The standard if statement is the basis for the conditional
  676.     compilation feature of the Draco compiler. If the condition for an
  677.     if statement can be evaluated at compile time, then no code is
  678.     generated for the if statement, and code for only one of the branches
  679.     is generated. This feature is not as flexible as that provided by
  680.     full macro preprocessors, but it has the advantage that the compiler
  681.     always checks all branches for correct syntax and semantics, thus the
  682.     programmer can be sure that changing the flag value controlling the
  683.     conditional compilation will not cause the program to stop compiling.
  684.     (With macro pre-processors, and conditional inclusion, as supported
  685.     by most C compilers, the compiler does not even see the code which
  686.     has been conditioned out.) By including conditional compilation
  687.     in the compiler, rather than requiring a separate pre-processor,
  688.     compilation times for Draco programs can be significantly less.
  689.     One common use for conditional compilation is that of including
  690.     debugging statements, dependent on a global debugging flag. E.g.
  691.     
  692.         bool DEBUG = false;
  693.         ...
  694.         if DEBUG then
  695.         writeln(DebugOut; "We got to this point, key values are:");
  696.         ...
  697.         fi;
  698.         
  699.     In situations like this, the Draco compiler will generate no code at
  700.     all for the entire if statement. If the DEBUG flag is set to 'true'
  701.     instead, then the debugging code will appear, but there will still be
  702.     no code to actually test DEBUG (DEBUG doesn't even exist). For more
  703.     complex debugging, the DEBUG flag can be a number, specifying the
  704.     level of debugging required. Another common use of conditional
  705.     compilation is to have one source file which can produce two or more
  706.     different versions of a program, depending on one or more flags.
  707.     
  708.     - while statements. The standard while statement consists of the word
  709.     'while', followed by a bool expression, followed by the word 'do',
  710.     followed by a sequence of statements (the loop body), followed by
  711.     the word 'od'. Draco allows an extension of this form, in which a
  712.     sequence of statements can be placed between the 'while' and the
  713.     bool expression. This extension allows the same 'while' construct to
  714.     serve as beginning, middle and end exit loops. E.g.
  715.     
  716.         while
  717.         write("Enter command: ");
  718.         command := getCommand();
  719.         command ~= HALT
  720.         do
  721.         processCommand(command);
  722.         od;
  723.  
  724.     - for statements. The for statement is the standard way in Draco of
  725.     iterating over a fixed sequence of values. It is similar to the
  726.     for statements in most programming languages. It consists of the
  727.     word 'for', followed by the name of the variable to use as an index
  728.     variable, followed by the word 'from' and an expression giving the
  729.     start of the range, optionally followed by the word 'by' and an
  730.     expression giving the step amount, followed by either the word
  731.     'upto' or the word 'downto' and an expression giving the end of the
  732.     range, followed by the word 'do', followed by a statement sequence,
  733.     and finally, the word 'od'.
  734.     
  735.     In Draco, the direction of the loop (increasing or decreasing) is
  736.     set at compile time, by the selection of 'upto' or 'downto'. If the
  737.     'by' part is omitted, then either +1 or -1, whichever is appropriate,
  738.     is used. The for loop terminates when the index variable attains the
  739.     last possible value between the two limits (inclusive). Thus we have
  740.     the loop
  741.     
  742.         for i from 1 by 5 upto 13 do
  743.         ...
  744.         od;
  745.         
  746.     stepping 'i' through the values 1, 6, and 11. The index variable can
  747.     be numeric (signed or unsigned), an enumeration value, or a pointer
  748.     value. The limits must be compatible with the index variable, and
  749.     the 'by' value, if present, must be numeric. Thus we can have a loop
  750.     which steps through every second letter of the alphabet:
  751.     
  752.         for ch from 'a' by 2 upto 'z' do
  753.         ...
  754.         od;
  755.     
  756.     Most programs which do a lot of computation have a lot of for loops
  757.     in them (fancy compilers are an exception). Thus, it is beneficial
  758.     if the compiler can generate fairly fast code for for loops. The
  759.     Draco compiler does a number of fancy tricks with for loops. Because
  760.     of this, it is important that none of the assumptions made by the
  761.     compiler are broken. Thus, the program should never attempt to assign
  762.     a value to the for index variable within the for loop. (A later
  763.     version of the compiler may be able to flag such usages as errors.)
  764.  
  765.     - case statements. Case statements in Draco are similar to those in 
  766.     many languages; they are of the variety where the individual 
  767.     alternatives being selected among are an explicit part of the case 
  768.     statement. A default alternative is also available. The syntax is as 
  769.     follows: the word 'case'; followed by the expression being used as a 
  770.     selector; followed by several alternatives, each consisting of 1 or 
  771.     more alternative index values given as the word 'incase', a constant 
  772.     expression, and a colon. Each alternative then has a body, which is 
  773.     a sequence of statements to be executed when that alternative is 
  774.     selected. The entire case statement is terminated by the word 'esac'.
  775.     The default case, if present, can occur anywhere among the
  776.     alternatives, and consists of the word 'default' and a colon, 
  777.     followed by the statements of the default case. The alternative index
  778.     values can be a pair of values separated by '..', in which case all
  779.     values between the two (inclusive) are used. The index expression
  780.     can be of any numeric or enumerated type. The alternative index
  781.     values must be compatible with the index expression. A sample case
  782.     statement:
  783.     
  784.         case ch
  785.         incase 'a':
  786.         incase 'A':
  787.         writeln("It was an A.");
  788.         incase 'b' .. 'd':
  789.         incase 'B' .. 'D':
  790.         x := y;
  791.         y := z;
  792.         default:
  793.         flag := true;
  794.         esac;
  795.     
  796.     The various Draco compilers will use different code sequences to
  797.     handle case statements. At least two forms will probably be
  798.     supported - one form which uses the index expression as a direct
  799.     index in a (perhaps sparse) table of code addresses, and one form
  800.     which uses a binary search through a sorted table of the alternative
  801.     index values. The appropriate form will be selected by the compiler,
  802.     based on the range and number of alternative index values.
  803.  
  804.     - I/O statements are discussed in a separate section later.
  805.  
  806.     - the 'free' construct, which can be applied to any value of a pointer
  807.     type, returns the storage pointed to to the storage allocator. That
  808.     storage must have been previously allocated by using 'new'. 'free' is
  809.     a statement since it returns no result.
  810.  
  811.     - the 'pretend' type-cheating construct can be used as a statement 
  812.     if the type being forced is 'void'. This form is used to throw
  813.     away a value, usually from a procedure, which is not needed. 
  814.  
  815.     - the 'error' construct, which accepts a parenthesized string constant
  816.     as its argument, simply uses that string as the text of an error
  817.     message to print AT COMPILE TIME. This construct is useful for 
  818.     putting consistency checks into code. For example, if a program has 
  819.     been written with the assumption that "IDENTIFIER"s fit in one byte,
  820.     then the following check, done somewhere in the program, would be
  821.     appropriate:
  822.  
  823.         if range(IDENTIFIER) > 255 then
  824.         error("IDENTIFIER range must be <= 255");
  825.         fi;
  826.  
  827.     Then, when someone comes along later and changes the definition of
  828.     the IDENTIFIER numeric type, if the type is made bigger than
  829.     'unsigned 255', a compile time error message will be produced when
  830.     compiling the file containing the above check. Near the check would
  831.     be a good place to put comments saying why the limitation exists.
  832.  
  833.     - some machine dependent constructs are formulated as statements. 
  834.  
  835. XI. Expressions in Draco
  836.  
  837.     Most small processors are more efficient at doing 8 bit operations then
  838.     they are at doing 16 or 32 bit operations. Because of this, the Draco
  839.     compiler will normally attempt to use the smallest possible size for
  840.     a given numeric type. One result of this is that the operands to an
  841.     operator may not be of the same size. In such cases, the compiler will
  842.     expand the smaller value (doing sign-extension on signed values) and do
  843.     the operation in the larger size. The one exception to this rule involves
  844.     the shift operators - the operation is always done in the size of the
  845.     value being shifted (the left operand). Also, the type of numeric
  846.     constants will be overridden by any non-constant operand, so long as
  847.     their value will fit in that size. If both operands are constants, the
  848.     larger type will be used as the result type.
  849.     
  850.     Similarly, the result of an operation can depend on whether that
  851.     operation is done using signed or unsigned arithmetic. In cases where
  852.     one operand to an arithmetic operator is signed and the other is
  853.     unsigned, the operation is done as a signed operation, and the result
  854.     is considered to be signed. This only affects the result for the
  855.     division and remainder operations. Note that this rule is opposite to
  856.     that of C, which would yield an unsigned result. This can be though of
  857.     as follows: in C, the normal numeric type is signed, while in Draco, the
  858.     normal numeric type is unsigned. In either language, any ocurrence of
  859.     a non-normal value forces non-normal operation and result. This choice
  860.     in Draco is likely to be contentious - the reasoning is that most numbers
  861.     used in most programs are unsigned. I personally find C's habit of
  862.     reserving '-1' as an error flag to be quite disgusting. As with size, the
  863.     signedness of a constant is ignored unless both operands are constants.
  864.  
  865.     Draco has a fairly large set of operators. These include the familiar
  866.     arithmetic operators of addition, subtraction, etc., along with a full
  867.     set of bit operators (and, xor, etc.), and a few special operators. The
  868.     operators are at various levels of priority, meaning that a higher
  869.     priority operator will be evaluated before a lower priority one, unless
  870.     there are parentheses explicitly governing the order of evaluation. This
  871.     reflects the usual view that multiplication comes before addition, etc.
  872.     Draco also has the usual constructs for calling functions, indexing
  873.     arrays, selecting fields of structures, etc. These are included in the
  874.     following table, to indicate their position in the precedence scheme.
  875.     The operators and constructs, in order of decreasing precedence are:
  876.     
  877.     ----------
  878.     
  879.     * - postfix dereferencing operator. This operator is postfix in
  880.         Draco, rather than prefix as in C, so that there is never any
  881.         ambiguity about the order in which the various constructs are to
  882.         be applied (consider *a[i] in C, which is either a[i]* or a*[i]
  883.         in Draco (I can never remember how C evaluates these)).
  884.     
  885.     [] - postfix array indexing. Array indexing is 0-origin in Draco,
  886.         i.e. the first element of an array has index 0. The compiler will
  887.         attempt to be efficient with indexing, but most microprocessors
  888.         have little direct support for array indexing, so if the
  889.         application is critical in terms of CPU time or program size, it
  890.         may be necessary to use pointer arithmetic instead of array
  891.         indexing. Values used for indexing can be of any numeric or
  892.         enumeration type.
  893.     
  894.     . - field selection. Field selection in Draco is fairly efficient,
  895.         usually requiring little, if any, extra machine code. The same
  896.         notation (structure '.' field-name) is used to select the current
  897.         form from a union type value.
  898.     
  899.     () - function calling. Function calls are identical to procedure
  900.         calls, except that they return a value. The function to be called
  901.         can be the result of an expression. (E.g. many versions of UNIX
  902.         contain an array of structures of procedures, which is used to
  903.         direct I/O calls based on the device being accessed (the array
  904.         index), and the particular function requested.)
  905.     
  906.     ----------
  907.     
  908.     & - prefix address-of operator. This operator takes the address of
  909.         it's operand. The type of the value generated is 'pointer-to-X',
  910.         where 'X' is the type of the operand. This operator cannot be
  911.         applied to expressions which do not have an inherent address,
  912.         e.g. '&(a + 1)' will not work, but '&a[i].name[j]' will. In
  913.         general, these constructs are arranged in Draco in such a way
  914.         that if you need brackets to express it, it's probably illegal.
  915.     
  916.     ----------
  917.     
  918.     ~ - prefix bitwise complement operator. This and the other bit
  919.         operators can only be applied to numeric values.
  920.     
  921.     ----------
  922.     
  923.     & - bitwise and operator.
  924.     
  925.     >< - bitwise exclusive-or operator.
  926.     
  927.     << - logical left shift operator. In both shift operators, the left
  928.         operand must be an unsigned numeric, while the right operand can
  929.         be any numeric. The operation and result are done using the size
  930.         of the left operand.
  931.     
  932.     >> - logical right shift operator.
  933.     
  934.     ----------
  935.     
  936.     | - bitwise inclusive-or operator.
  937.     
  938.     ----------
  939.     
  940.     | - prefix numeric absolute value operator. This, and other
  941.         arithmetic operators, can only be applied to numeric values.
  942.         (Exceptions for binary + and - are listed there.) Both the
  943.         absolute value and negation unary operators always yield a
  944.         signed type, regardless of the signedness of their operand.
  945.     
  946.     - - prefix numeric negation operator.
  947.     
  948.     + - prefix numeric do-nothing operator. This operator is included so
  949.         that forms like '+0' can be allowed.
  950.     
  951.     ----------
  952.     
  953.     * - multiplication operator.
  954.     
  955.     / - division operator.
  956.     
  957.     % - remainder operator.
  958.     
  959.     ----------
  960.     
  961.     + - addition operator. In addition to numeric operands, one
  962.         operand can be of an enumeration or pointer type. The resulting
  963.         value will be of the same type, incremented by the other,
  964.         numeric, operand. Unlike C, which pre-multiplies the numeric
  965.         value by the size of the pointed-to type, Draco doesn't modify
  966.         the numeric value at all.
  967.     
  968.     - - subtraction operator. Similar to incrementing a pointer or
  969.         enumeration value, these values can be decremented by using them
  970.         as the left-hand operand in subtraction. Two enumeration or
  971.         pointer values of the same type can also be subtracted, yielding
  972.         an unsigned numeric value.
  973.  
  974.     ----------
  975.     
  976.     >, <, >=, <=, =, ~= - comparison operators. Most values in Draco can
  977.         be compared. For some comparisons, only the equality comparisons
  978.         (= and ~=) are meaningful. For example, comparing a signed
  979.         numeric with an unsigned numeric can yield two different results,
  980.         depending on whether a signed or unsigned comparison is used.
  981.         Because of this, the compiler will not allow a signed value to be
  982.         compared with an unsigned value with other than = or ~=. The
  983.         values being compared must be of compatible types. Structure and
  984.         array types cannot be compared, since these types might contain
  985.         internal gaps due to alignment requirements, and the contents of
  986.         these gaps is undefined.
  987.  
  988.     ----------
  989.  
  990.     Along with the capability of conditional compilation provided by the
  991.     if statement, the Draco compiler attempts to evaluate expressions at
  992.     compile-time, so that they need not be evaluated at run-time. If both
  993.     operands to an operator can be evaluated at compile time, then the
  994.     operation is done at compile time, producing a constant. The evaluation
  995.     is done using the highest precision supported by the compiler. The
  996.     nature of the evaluation will be the same as if it was done at run-time,
  997.     i.e. mixing signed and unsigned values will yield a signed result, etc.
  998.     This facility is used in all places where constants appear, e.g. in
  999.     array declarations, signed/unsigned declarations, case statement
  1000.     alternative index values, etc.
  1001.  
  1002.     There are several forms of expressions in Draco which do not involve
  1003.     actual operators. These include the boolean 'and', 'or' and 'not'
  1004.     operations. These are not classed with the normal operators, since they
  1005.     are actually language constructs instead. Both 'and' and 'or' will not
  1006.     evaluate their right-hand operand if the value of the left-hand operand
  1007.     is sufficient to determine the result. This is known as 'short-circuit-
  1008.     evaluation', or the McCarthy form of the 'and' and 'or' operators. There
  1009.     is no exclusive-or operation for bools, but the same result can be
  1010.     achieved using the ~= operator, which can be applied to bool values.
  1011.     
  1012.     Draco also allows conditional expressions - the if expression and the
  1013.     case expression. These forms are identical to their statement forms,
  1014.     except that the various statement sequences used as their alternatives
  1015.     must end with an expression, which is the result for that alternative.
  1016.     Also, if expressions must have an else part, since they must yield a
  1017.     result in all cases. The same feature which allows if statements to be
  1018.     used for conditional compilation allows the use of if expressions in
  1019.     constant expressions, so long as the conditions and all alternative
  1020.     values are themselves constant expressions.
  1021.  
  1022.     The unwise programmer can 'type cheat' (convince the compiler to allow 
  1023.     him to do things which he would not normally be allowed to do) by 
  1024.     misusing union types. In the hope of preventing this, Draco has an 
  1025.     explicit construct for type cheating. It uses the word 'pretend'. The 
  1026.     form 'pretend(expr, type)' instructs the compiler to consider 'expr' to 
  1027.     be of type 'type', regardless of what it thinks the type must be. As a 
  1028.     special case, 'type' can be 'void', in which case the value of 'expr' is 
  1029.     simply discarded (this action, called voiding, is done automatically by 
  1030.     most C compilers, often resulting in programming errors, since it is 
  1031.     easy to do it unintentionally). The pretend construct should be used
  1032.     with great care, since some values cannot possibly be of some types. For 
  1033.     example, what is supposed to happen in something like 'pretend(x + y, 
  1034.     [10] int)'? A more innocuous form of the pretend construct uses the word 
  1035.     'make' instead of the word 'pretend'. This form requests that the 
  1036.     compiler convert the given expression to the given type. This form will 
  1037.     only allow those conversions which make sense. 'make' is normally used 
  1038.     to expand a short value to a longer form, to force an operation to be 
  1039.     in a longer form (e.g. to force 16 bit arithmetic on 8 bit values).
  1040.  
  1041.     The form 'dim(arrayname, number)' will be replaced by the size of the
  1042.     named array in the given dimension (the first dimension is dimension
  1043.     number 1). If the array is a parameter array and the selected dimension
  1044.     was declared as '*', then the value will be obtained at run-time from
  1045.     a hidden parameter passed along with the normal parameters, otherwise,
  1046.     the value is a compile-time constant and can be used in constant
  1047.     expressions. Note that the value is the size of the array in that
  1048.     dimension, which is one greater than the maximum legal index in that
  1049.     dimension.
  1050.     
  1051.     The form 'sizeof(type)' yields a numeric constant which is the number of
  1052.     bytes needed to store an object of the given type. The type can be the
  1053.     name of a declared type, or can be a more complex type description.
  1054.     Proper use of this construct is needed to allow some programs to be
  1055.     portable among machines which have, say, different sized integers. Most
  1056.     programmers will not have to use it, however.
  1057.  
  1058.     The construct 'new(type)' creates a call to the standard storage
  1059.     allocator to allocate a new object of type 'type'. It can be thought of
  1060.     as equivalent to 'pretend(malloc(sizeof(type)), *type). Note that the
  1061.     value returned is a pointer to the newly allocated storage, and thus its
  1062.     type is *type.
  1063.  
  1064.     The form 'range(type)' can be applied to signed or unsigned numeric types
  1065.     to return the upper limit of that type (the value given when type was
  1066.     declared); or to an enumeration type to return the number of values in
  1067.     that type. Thus 'range(bool)' is equivalent to '2', and 'range(int)'
  1068.     returns the maximum signed numeric value allowed with the normal integer
  1069.     values supported by that version of the compiler. Note that 'range(byte)'
  1070.     is not legal since 'byte' is not considered to be a normal numeric type,
  1071.     since it is forced to be exactly 1 byte long, regardless of whether that
  1072.     is efficient for the target machine.
  1073.  
  1074. XII. Basic components of Draco programs
  1075.  
  1076.     Identifiers in Draco can be any length. This applies to variables, 
  1077.     constants, types and procedure names. The link editor maintains the lack 
  1078.     of a limit - the full name of an external procedure is used when 
  1079.     searching for it in other files and libraries. Draco treats upper and 
  1080.     lower case letters as distinct, thus the identifiers 'A' and 'a' are not 
  1081.     the same. The programmer can use any convention he wishes with regard to 
  1082.     capitalization, but the conventions mentioned previously are highly 
  1083.     recommended. Note also that keywords in Draco are recognized only in the
  1084.     exact case in which they are specified. Identifiers in Draco must start
  1085.     with a letter or an underscore (_), and must consist of letters, digits
  1086.     and underscores.
  1087.  
  1088.     Comments in Draco consist of the delimiters '/*' and '*/' around the 
  1089.     portion of the source to be commented out. Comments can span several 
  1090.     input lines. Comments can be nested, i.e. a comment entirely within an 
  1091.     outer comment is recognized and handled properly by the compiler. Thus, a
  1092.     section of code can be commented out by enclosing it in /* and */, 
  1093.     regardless of whether it has any comments in it or not. Comments, along 
  1094.     with 'whitespace' (blanks, tabs, carriage-returns and linefeeds) can 
  1095.     occur between any two tokens, as well as in string breaks (see below). 
  1096.  
  1097.     Numeric constants in Draco can be in decimal, octal, hexadecimal or 
  1098.     binary. Simple numbers like '10' and '6348' are treated as decimal. Other
  1099.     bases are selected by preceeding the number by a prefix consisting of a 
  1100.     '0' and a base indicator. The base indicators, which can be in upper or 
  1101.     lower case, are 'x' for hexadecimal, 'o' for octal, and 'b' for binary. 
  1102.     Hexadecimal digits 'a' - 'f' can be in upper or lower case. The compiler 
  1103.     checks for proper digits for a given base and for numeric overflow in 
  1104.     constants. 
  1105.  
  1106.     Character constants in Draco come in two forms. The apostrophe (') is 
  1107.     used to delimit single character constants, as in 'a', '.', etc. Quotes
  1108.     (") are used to delimit C - style strings, consisting of a sequence of 
  1109.     characters terminated by a 0 character. In both forms, an escape 
  1110.     convention is available. The escapes consist of a backslash followed 
  1111.     either by a single character, or by a numeric expression enclosed in 
  1112.     parentheses. The single character forms are: 
  1113.  
  1114.     \b - the ASCII backspace character
  1115.     \t - the ASCII tab character
  1116.     \r - the ASCII carriage return character
  1117.     \n - the ASCII linefeed (newline) character
  1118.     \e - the C - style string termination character (0)
  1119.  
  1120.     Any other character used this way will be passed through unchanged. This 
  1121.     can be used to put backslashes and quotation marks of the same type as 
  1122.     the delimiter into the string. The convention of doubling a quote mark to
  1123.     produce a single one is also supported. The escape form consisting of a 
  1124.     numeric value in parentheses must yield a constant between 0 and 255. 
  1125.     This form can be used for special named characters, as in: 
  1126.  
  1127.     write('\(BEEP)');        /* ring terminal's bell */
  1128.  
  1129.     The multi-character form of character constants ('chars' values using ") 
  1130.     supports the 'string break'. This is a convention which allows a long 
  1131.     string to be split up over several input lines, and to be indented 
  1132.     nicely. If the last thing (other than spaces, comments, etc.) on an input
  1133.     line is a portion of a chars constant, and the first thing (other than 
  1134.     spaces, comments, etc.) on the next input line is a similar constant, 
  1135.     then the two are concatenated at compile time to yield a single, longer 
  1136.     constant. This can be carried on for as many input lines as are needed to
  1137.     nicely format the constant. 
  1138.  
  1139.     Many CP/M systems in use today do not have full ASCII keyboards (e.g.
  1140.     CP/M on the Apple-II or Apple-II+). In such systems, it could be
  1141.     difficult to use Draco, since the language uses characters not found on
  1142.     the keyboards. To help alleviate this problem, the compiler recognizes
  1143.     the following alternate forms for some operators and characters:
  1144.  
  1145.      standard     alternate
  1146.  
  1147.         \            #
  1148.         [            (:
  1149.         ]            :)
  1150.         {            ($
  1151.         }            $)
  1152.         ~=            /=
  1153.         ~            $-
  1154.         |            $/
  1155.         _            ^
  1156.  
  1157.     Draco allows the construction of array and structure constants for 
  1158.     named array and structure types. The form is that of a parenthesized
  1159.     list of values. Such constants can be arbitrarily complex. If one is
  1160.     used in a constant declaration, it simply appears after the '='. If one
  1161.     is desired inside executable code, it must be preceeded by the name of
  1162.     the type in question, so that the compiler has some clue as to what is
  1163.     going on. For example:
  1164.  
  1165.     type type1 = struct {int field1, field2; char field3};
  1166.     type type2 = [2] type1;
  1167.     type2 CONST = ((1, 2, 'a'), (3, 4, 'a' - FRED / 2));
  1168.     type2 var;
  1169.     ...
  1170.     var := type2((-26, 13 + 2 / 7, 'a' + 2), (+1, -1, '\e'));
  1171.  
  1172. XIII. Machine specific constructs
  1173.  
  1174.     The 8080 (CP/M) version of the compiler has several additional features,
  1175.     which can make certain types of programming easier.
  1176.     
  1177.     When a variable (global, file or local) is declared, it can be followed
  1178.     by an '@' and a numeric constant. This informs the compiler that that
  1179.     variable is to be located at that address. This is useful for things
  1180.     like memory-mapped displays and memory-mapped I/O. This same modifier
  1181.     can be appended to 'extern' procedures, enabling Draco programs to call
  1182.     routines at absolute addresses in ROMS.
  1183.  
  1184.     When declaring variables, the value given after the '@' can also be the
  1185.     name of some other variable. In this case, the second named variable must
  1186.     occupy at least as many bytes of storage as the first, and the two will
  1187.     then occupy the same storage. This technique can be used to "type-cheat",
  1188.     but the programmer is strongly advised to use 'pretend' instead, unless
  1189.     unreadable code is desired. This feature of the compiler is intended to
  1190.     be used to conserve storage space as used for variables.
  1191.     
  1192.     The 8080 processor has no really efficient way to access variables
  1193.     stored on the stack. This tends to make recursive programs quite
  1194.     inefficient. Draco sidesteps the problem by not storing any variables on
  1195.     the stack - all can be directly addressed at a fixed location. Recursion
  1196.     is allowed by using special code at the beginning and end of procedures,
  1197.     which saves and restores that procedure's local variables on the stack.
  1198.     This can be slightly time-consuming if the procedure is called often.
  1199.     If the word 'nonrec' is placed between the word 'proc' and the name of
  1200.     the procedure, then this special code is ommitted. Such a procedure must
  1201.     not be used recursively. The scheme used has one slight flaw - taking the
  1202.     address of a local variable of a routine used recursively may not work
  1203.     as expected, since the value originally pointed to will be moved onto the
  1204.     stack when the procedure is called recursively, and the pointer will be
  1205.     left pointing to the new version of the variable. This flaw will not
  1206.     affect many programs (it did affect the compiler, however).
  1207.  
  1208.     Several provisions were added to the CP/M compiler to allow nearly all 
  1209.     types of programming to be done directly in Draco, rather than having to 
  1210.     write assembler language subroutines. The form 'input(port)' will return 
  1211.     a 'byte' value obtained from input port 'port' ('port' must be a compile 
  1212.     time expression whose value is between 0 and 255). Similarly, the form 
  1213.     'output(port, value)' will output an 8 bit value 'value' to the specified
  1214.     output port. If the 'value' expression is ommitted, then a indeterminate 
  1215.     value is output. (This is useful with hardware configurations in which 
  1216.     the output instruction itself causes the desired external action.) The 
  1217.     statement form 'halt' will generate a HLT instruction. The statement form
  1218.     'ion' will generate an EI instruction. The statement form 'ioff' will 
  1219.     generate a DI instruction. If the word 'vector' is used instead of 
  1220.     'nonrec' when defining a procedure, ('vector' also implies 'nonrec') then
  1221.     that procedure is assumed to be an interrupt handler, and will start with
  1222.     code to stack all of the processor's registers, and will end with code to
  1223.     unstack the registers, enable the interrupts, and return. Remember that 
  1224.     the 8080's EI instruction will not enable interrupts until after the NEXT
  1225.     instruction. 'vector' procedures must not have any parameters (who would 
  1226.     supply them?), and cannot yield any result (where would it go?). The 
  1227.     cleanest way to set up interrupt vectors would be something like: 
  1228.  
  1229.     type
  1230.         VECTOR = struct {
  1231.         byte v_jmp;
  1232.         proc()void v_handler;
  1233.         [5] byte v_padding;    /* pad to 8 bytes each */
  1234.         };
  1235.     
  1236.     byte JMP = 0xc3;        /* 8080 JUMP instruction */
  1237.     
  1238.     [8] VECTOR Vector @ 0x0000;    /* array of vectors at absolute */
  1239.                     /* address 0x0000 */
  1240.     proc vector handle0()void:
  1241.         ...
  1242.     corp;
  1243.     
  1244.     ...
  1245.     
  1246.     Vector[0].v_jmp := JMP;        /* set up the machine's vectors */
  1247.     Vector[0].v_handler := handle0;
  1248.     Vector[1].v_jmp := JMP;
  1249.     Vector[1].v_handler := handle1;
  1250.     ...
  1251.  
  1252.     ion;                /* enable interrupts */
  1253.  
  1254.     Since the Draco compiler directly emits object code, rather than
  1255.     assembler source code, it is not possible to allow in-line assembler
  1256.     language statments. Instead, Draco has the 'code' construct, which
  1257.     consists of the keyword 'code' followed by a parenthesized list of
  1258.     constant expressions and symbol references. The values of constant
  1259.     expressions are emitted directly into the code stream. The type of the
  1260.     constants controls its size as emitted. Variable and procedure references
  1261.     yield 16 bit words which will be relocated at link time to contain the
  1262.     required address. For example (an 8080 example):
  1263.  
  1264.     byte
  1265.         OP_CALL = 0o315,
  1266.         OP_MOV = 0o100,
  1267.         OP_ADD = 0o200,
  1268.         OP_SUB = 0o220,
  1269.         OP_DAA = 0o047,
  1270.         OP_LXI = 0o001,
  1271.  
  1272.         R_A = 0o7,
  1273.         R_B = 0o0,
  1274.         R_C = 0o1;
  1275.     int x;
  1276.  
  1277.     word CALL_ADDRESS = 0x1234;
  1278.  
  1279.     ...
  1280.     code (
  1281.         OP_MOV | R_A << 3 | R_B,
  1282.         OP_ADD | R_C,
  1283.         OP_DAA,
  1284.         OP_CALL, CALL_ADDRESS,
  1285.         OP_LXI | R_H << 3, x    /* load address of x into HL */
  1286.     );
  1287.