diff --git a/doc/assembler.txt b/doc/assembler.txt new file mode 100644 index 0000000..e69de29 diff --git a/doc/assemblers.ods b/doc/assemblers.ods new file mode 100644 index 0000000..0d6635c Binary files /dev/null and b/doc/assemblers.ods differ diff --git a/doc/block.txt b/doc/block.txt new file mode 100644 index 0000000..b742706 --- /dev/null +++ b/doc/block.txt @@ -0,0 +1,170 @@ +Block Memory Functions + +This library contains functions for accessing data in blocks of memory. +A block consists of up to 65,535 contiguous bytes. This allows for the +storage, retrieval, and manipulation of data exceeding the maximum +array length of 255. + +These functions assume that a block is divided into equally sized segments +of up to 255 bytes in length. Data in the block is accessed by copying +data into and out of arrays with the same length as the segment size. + +A segment consists of a string field, which is used as a key, followed +by a number of individual bytes. For example, the segments in a variable +table might be 9 bytes long, consisting of a 7 byte variable name string +(6 characters plus a terminator), the variable type (at index 7) and +the variable length (at index 8). + +Usage: at the beginning of the program use the directives + + #include + #include + #include + +The following application functions are defined: + + blkbgn(&b); Block Begin: Set beginning of block to address b. + + The beginning of a block is the first byte of memory + in the block. + + Although a block usually begins on a 256 byte + boundary, this is not required. + + Note: Sets variables blkslo and blkshi. + + blkend(&e); Block End: Set end of block to address b. The end of + a block is the byte after the last byte of memory in + the block. + + Although a block usually begins on a 256 byte + boundary, this is not required. + + Note: Sets variables blkslo and blkshi. + + blkseg(n); Block Segment: Set block segment size to n. + + Required before calls any calls that manipulate + block segments. + + Note: Sets blklen to n. + + blkset(c); Block Set: Fill entire block with character c, + leaving block pointer at end of block. + + Used to initialize a block before use. + + blkrst(); Block Reset: Set block segment pointer to block + begin address. + + This routine is called before populating a block with + calls to the blkapd function. + + blknxt(); Block Next: Move block pointer forward by the segment + length set by a prior blkseg call. + + If the block pointer is moved past the end of the + block, a value of 0 (false) is returned. Otherwise, + a value of 255 (true) is returned. + + blkput(n ,&m); Block Append: Copy n bytes of array m to block + at current pointer location, and moves block pointer + forward by the segment length set by a prior blkseg + call. + + If the appended bytes would overflow the end of the + block, no bytes are copied and a value of 0 (false) + is returned. Otherwise, the bytes are copied and + a value of 255 (true) is returned. + + Note: Sets dstlo and dsthi to the block pointer prior + to the copy, updates blkslo and blkshi, then calls + the memcpy function. + + blkget(n ,&m); Block Get: Copy n bytes from block at current + pointer location to array m, and moves block pointer + forward by the segment length set by a prior blkseg + call. + + If the copied bytes would overflow the end of the + block, no bytes are copied and a value of 0 (false) + is returned. Otherwise, the bytes are copied and + a value of 255 (true) is returned. + + Note: Sets dstlo and dsthi to the address of m, + srclo and srchi to the block pointer prior to the + copy, updates blkslo and blkshi, then calls the + memcpy function. + + blkmem(n ,&m); Block Memory search: Search block for n byte long + segment matching array m. + + If a matching segment is found, the value 255 (true) + is returned and the destination pointer is set to the + address of the matching segment, allowing it to be + overwritten with a subsequent memcpy call. Otherwise, + the value 0 (false) is returned. + + Note: Sets srclo and srchi to the address of m, + dstlo and dsthi to the address of the matching segment, + and temp0 to n. Does not change the block pointer. + + blkstr(n ,&s); Block String Search: Search block for n byte long + segments beginning with string s. + + If a matching segment is found, the value 255 (true) + is returned and the segment is copied to the array set + by a prior memdst call. Otherwise, the value 0 (false) + is returned. + + Note: Sets srclo and srchi to the address of the + segment, temp0 to n, and copies dstlo and dsthi to + temp1 and temp2. Does not change the block pointer. + + blkswp(n); Block Swap: Swaps n bytes of array m with the current + block segment (pointed to by the block pointer. The + block pointer is not changed. + + Requires a prior call to the memdst function specifying + an array at least n bytes long, which is used for + temporary storage. + + Note: Sets temp0 to n, copies blklo and blkhi to dstlo, + and dsthi, and calls memswp. + + blksrt(&m); Block Sort: Sort segments in block by initial string, + using array m as temporary storage. + + Segments are sorted in alphabetical order, with segment + length set by a prior blkseg call, and sorting stops at + the first segment that begins with an empty string (the + first byte is 0), leaving the block pointer at that + segment. + + Note: Uses the selection sort algorithm. Sets temp1 + and temp2 to the address of array m. + +Note: This library expects the following functions to be defined + + setdst(&s); Set destination string pointer + setsrc(&s); Set source string pointer and initialize index + memcmp Compare memory + memcpy Copy memory + memsrc Set memory source and count + strcml Compare string (alternate entry point) + +along with the zero page variable pairs + + srclo, srchi Source String Pointer + dstlo, dsthi Destination String Pointer + blklo, blkhi Block Pointer + +the static variable + + blkslo, blkshi Block Start Address + blkelo, blkehi Block End Address + blklen Block Segment Length + +as well as the transient variables + + temp0, temp1, temp2 Temporary storage diff --git a/doc/c02.txt b/doc/c02.txt new file mode 100644 index 0000000..f678518 --- /dev/null +++ b/doc/c02.txt @@ -0,0 +1,628 @@ +INTRODUCTION + +C02 is a simple C-syntax language designed to generate highly optimized +code for the 6502 microprocessor. The C02 specification is a highly +specific subset of the C standard with some modifications and extensions + +PURPOSE + +Why create a whole new language, particularly one with severe restrictions, +when there are already full-featured C compilers available? It can be +argued that standard C is a poor fit for processors like the 6502. The C +was language designed to translate directly to machine language instructions +whenever possible. This works well on 32-bit processors, but requires either +a byte-code interpreter or the generation of complex code on a typical +8-bit processor. C02, on the other hand, has been designed to translate +directly to 6502 machine language instructions. + +The C02 language and compiler were designed with two goals in mind. + +The first goal is the ability to target machines with low memory: a few +kilobytes of RAM (assuming the generated object code is to be loaded into +and ran from RAM), or as little as 128 bytes of RAM and 2 kilobytes of ROM +(assuming the object code is to be run from a ROM or PROM). + +The compiler is agnostic with regard to system calls and library functions. +Calculations and comparisons are done with 8 bit precision. Intermediate +results, array indexing, and function calls use the 6502 internal registers. +While this results in compiled code with virtually no overhead, it severely +restricts the syntax of the language. + +The second goal is to port the compiler to C02 code so that it may be +compiled by itself and run on any 6502 based machine with sufficient memory +and appropriate peripherals. This slightly restricts the implementation of +code structures. + +SOURCE AND OUTPUT FILES + +C02 source code files are denoted with the .c02 extension. The compiler +reads the source code file, processes it, and generates an assembly +language file with the same name as the source code file, but with +the .asm extension instead of the .c02 extension. This assembly language +file is then assembled to create the final object code file. + +Note: The default implementation of the compiler creates assembly +language code formatted for the DASM assembler. The generation of the +assembly language is parameterized, so it may be easily changed to +work with other assemblers. + +COMMENTS + +The parser recognizes both C style and C++ style comments. + +C style comments begin with /* and end at next */. Nested C style comments +are not supported. + +C++ style comments begin with // and end at the next newline. C++ style +comments my be nested inside C style comments. + +DIRECTIVES + +Directives are special instructions to the compiler. They do not directy +generate compiled code. A directive is denoted by a leading # character. +C02 currently supports only one directive. + +The #include directive causes the compiler to read and process and external +file. In most cases, #include directives will be used with libraries of +function calls, but they can also be used to modularize the code that makes +up a program. + +An #include directive is followed by the file name to be included. This +file name may be surrounded with either a < and > character, or by two " +characters. In the former case, the compiler looks for the file in an +implementation specific library directory (the default being ./include), +while in the latter case, the compiler looks for the file in the current +working directory. Two file types are currently supported. + +Header files are denoted by the .h02 extension. A header file is used to +provide the compiler with the information necessary to use machine +language system and/or library routines written in assembly language, +and consists of comments and declarations. The declarations in a header +file added to the symbol table, but do not directly generate code. After +a header file has been processed, the compiler reads and process a +assembly language file with the same name as the header file, but with +the .a02 extension instead of the .h02 extension. + +The compiler does not currently generate any assembler required +pseudo-operators, such as the specification of the target processor, +or the starting address of the assembled object code. Therefore, at least +one header file, with an accompanying assembly language file is needed +in order to successfully assemble the compiler generated code. Details +on the structure and implementation of a typical header file can be +found in the file header.txt. + +Assembly language files are denoted by the .asm extension. When the +compiler processes an assembly language file, it simply inserts the contents +of the file into the generated code. + +Note: Unlike standard C and C++, which use a preprocessor to process +directives, the C02 compiler processes directives directly. + +CONSTANTS + +A constant represents a value between 0 and 255. Values may be written as +a number (binary, decimal, osir hexadecimal) or a character literal. + +A binary number consists of a % followed by eight binary digits (0 or 1). + +A decimal number consists of one to three decimal digits (0 through 9). + +A hexadecimal number consists of a $ followed by two hexadecimal digits +(0 throuth 9 or A through F). + +A character literals consists of a single character surrounded by ' symbols. +A ' character may be specified by escaping it with a \. + +Examples: + &0101010 Binary Number + 123 Decimal Number + $FF Hexadecimal Number + 'A' Character Literal + '\'' Escaped Character Literal + +STRINGS + +A string is a consecutive series of characters terminated by an ASCII null +character (a byte with the value 0). + +A string literal is written as up to 255 printable characters. prefixed and +suffixed with " characters. + +SYMBOLS + +A symbol consists of an alphabetic character followed by zero to five +alphanumeric characters. Four types of symbols are supported: labels, +simple variables, variable arrays, and functions. + +A label specifies a target point for a goto statement. A label is written +as a symbol suffixed by a : character. + +A simple variable represents a single byte of memory. A variable is written +as a symbol without a suffix. + +A variable array represents a block of up to 256 continuous bytes in +memory. An Array reference are written as a symbol suffixed a [ character, + +index, and ] character. The lowest index of an array is 0, and the highest +index is one less than the number of bytes in the array. There is no bounds +checking on arrays: referencing an element beyond the end of the array will +access indeterminate memory locations. + +A function is a subroutine that receives multiple values as arguments and +optionally returns a value. A function is written as a symbol suffixed with +a ( character, up to three arguments separated by commas, and a ) character, + +The special symbols A, X, and Y represent the 6502 registers with the same +names. Registers may only be used in specific circumstances (which are +detailed in the following text). Various C02 statements modify registers +as they are processed, care should be taken when using them. However, when +used properly, register references can increase the efficiency of compiled +code. + +STATEMENTS + +Statements include declarations, assignments, stand-alone function calls, +and control structures. Most statements are suffixed with ; characters, +but some may be followed with program blocks. + +BLOCKS + +A program block is a series of statements surrounded by the { and } +characters. They may only be used with function definitions and control +structures. + +DECLARATIONS + +A declaration statement consists of type keyword (char or void) followed +by one or more variable names and optional definitions, or a single +function name and optional function block. + +Variables may only be of type char and all variable declaration statements +are suffixed with a ; character. + +A simple variable declaration may include an initial value definition in +the form of an = character and constant after the variable name. + +A variable array may be declares in one of two ways: the variable name +suffixed with a [ character, a constant specifying the upper bound of +the array, and a ] character; or a variable name followed by an = character +and string literal or series of constants separated by , characters and +surrounded by { or } characters. + +Variables are initialized at compile time. If a variable is changed during +execution, it will not be reinitialized unless the compiled program is +reloaded into memory. + +Examples: + char c; //Defines variable c + char i, j; //Defines variables i and j + char r[7]; //Defines 8 byte array r + char s = "string"; //Defines 7 byte array s initialized to "string" + char m = {1,2,3}; //Defines 3 byte array m initialized to 1, 2, and 3 + +A function declaration consists of the function name suffixed with a ( +character, followed zero to three comma separated simple variables and +a ) character. A function declaration terminated with a ; character is +called a forward declaration and does not generate any code, while one +followed by a program block creates the specified function. Functions of +type char explicitly return a value (using a return statement), while +functions of type void do not. + +Examples: + void myfunc(); //Forward declaration of function myfunc + char min(tmp1, tmp2) {if (tmp1 < tmp2) return tmp1; else return tmp2;} + +Note: Like all variables, function parameters are global. They must be +declared prior to the function decaration, and retain there values after +the function call. Although functions may be called recursively, they are +not re-entrant. Allocation of variables and functions is implementation +dependent, they could be placed in any part of memory and in any order. +The default behavior is to place variables directly after the program code, +including them as part of the generated object file. + +The return value of a function is passed through the A register. A return +statement with an explicit expression will simply process that expression +(which leaves the result in the A register) before returning. A return +statement without an expression (including an implicit return) will, by +default, return the value of the last processed expression. + +EXPRESSIONS + +An expression is a sseries of one or more terms separated by operators. + +The first term in an expression may be a function call, subscripted array +element, simple variable, constant, or register (A, X, or Y). An expression +may be preceded with a - character, in which case the first term is assumed +to be the constant 0. + +Additional terms are limited to subscripted array elements, simple variables +and constants. + +Operators: + + — Add the following value. + - — Subtract the following value. + & — Bitwise AND with the following value. + | — Bitwise OR with the following value. + ^ — Bitwise Exclusive OR with the following value. + +Arithmetic operators have no precedence. All operations are performed in +left to right order. Expressions may not contain parenthesis. + +Note: the character ! may be substituted for | on systems that do not +support the latter character. No escaping is necessary because a ! may +not appear anywere a | would. + +After an expression has been evaluated, the A register will contain the +result. + +EVALUATIONS + +An evaluation is a construct which generates either TRUE or FALSE condition. +It may be an expression, a comparison, or a test. + +A stand-alone expression evaluates to TRUE if the result is non-zero, or +FALSE if the result is zero. + +A comparison consists of an expression, a comparator, and a term (subscripted +array element, simple variable, or constant). + +Comparators: + = — Evaluates to TRUE if expression is equal to term + < — Evaluates to TRUE if expression is less than term + <= — Evaluates to TRUE if expression is less than or equal to term + > — Evaluates to TRUE if expression is greater than term + >= — Evaluates to TRUE if expression is greater than or equal to term + <> — Evaluates to TRUE if expression is not equal to term + +The parser considers == equivalent to a single =. The operator <> +was chosen instead of the usual != because it simplified the parser design. + +A test consists of an expression followed by a test-op. + +Test-Ops: + :+ — Evaluates to TRUE if the result of the expression is positive + :- — Evaluates to TRUE if the result of the expression is negative + +A negative value is one in which the high bit is a 1 (128 — 255), while a +positive value is one in which the high bit is a 0 (0 — 127). The primary +purpose of test operators is to check the results of functions that return +a positive value upon succesful completion and a negative value if an error +was encounters. They compile into smaller code than would be generated +using the equivalent comparison operators. + +A comparison may be preceded by negation operator (a ! character), which +reverses the meaning of the entire comparison. For example, + ! expr +evaluates to TRUE if expr is zero, or FALSE if it is non-zero; while + ! expr = term +evaluates to TRUE if expr and term are not equal, or FALSE if they are; and + ! expr :+ +evaluates to TRUE if expr is negative, or FALSE if it is positive + +Note: Evaluations are compiled directly into 6502 conditional branch +instructions, which precludes their use inside expressions. Standalone +expressions and test-ops generate a single branch instruction, and +therefore result in the most efficient code. Comparisons generate a +compare instruction and one or two branch instructions (=. <. >=, and <> +generate one, while <= and > generate two). A preceding negation operator +will switch the number of branch instructions used in a comparison, but +otherwise does not change the size of the generated code. + +ARRAY SUBSCRIPTS + +Individual elements of an array are accessed using subscript notation. +Subscripted array elements may be used as a terms in an expression, as well +as the target variable in an assignments. They are written as the variable +name suffixed with a [ character, followed by an index, and the ] character. +The index may be a constant, a simple variable, or a register (A, X or Y). + +Examples: + z = r[i]; //Store the value from element i of array r into variable z + r[0] = z; //Store the value of variable z into the first element of r + +Note: After a subscripted array reference, the 6502 X register will contain +the value of the index (unless the register Y was used as the index, in +which X register is not changed). + +FUNCTION CALLS + +A function call may be used as a stand-alone statement, or as the first +term in an expression. A function call consists of the function name +appended with a ( character, followed by zero to three arguments separated +with commas, and a closing ) character. + +The first argument of a function call may be an expression, address, or +string (see below). + +The second argument may be a term (subscripted array element, simple +variable, or constant), address, or string, + +The third argument may only be a simple variable or constant. + +If the first or second argument is an address or string, then no more +arguments may be passed. + +To pass the address of a variable or array into a function, precede the +variable name with the address-of operator &. To pass a string, simply +specify the string as the argument. + +Examples: + c = getchr(); //Get character from keyboard + n = abs(b+c-d); //Return the absolute value of result of expression + m = min(r[i], r[j]); //Return lesser of to array elements + l = strlen(&s); //Return the length of string s + p = strchr(c, &s); //Return position of character c in string s + putstr("Hello World"); //Write "Hello World" to screen + +Note: This particular argument passing convention has been chosen because +of the 6502's limited number of registers and stack processing instructions. +When an address is passed, the high byte is stored in the Y register and +the low byte in the X register. If a string is passed, it is turned into +anonymous array, and it's address is passed in the Y and X registers. +Otherwise, the first argument is passed in the A register, the second in +the Y register, and the third in the X register. + +EXTENDED PARAMETER PASSING + +To enable direct calling of machine language routines that that do not match +the built-in parameter passing convention, C02 supports the non-standard +statements push, pop, and inline. + +The push statement is used to push arguments onto the machine stack prior +to a function call. When using a push statement, it is followed by one or +more arguments, separated by commas, and terminated with a semi-colon. An +argument may be an expression, in which case the single byte result is +pushed onto the stack, or it may be an address or string, in which case the +address is pushed onto the string, high byte first and low byte second. + +The pop statement is likewise used to pop arguments off of the machine +stack after a function call. When using a pop statement, it is followed +with one or more simple variables, separated by commas, and terminated +with a semicolon. If any of the arguments are to be discarded, an asterisk +can be specified instead of a variable name. + +The number of arguments pushed and popped may or may not be the same, +depending on how the machine language routine manipulates the stack pointer. + +Examples: + push d,r; mult(); pop p; + push x1,y1,x2,y2; rect(); pop *,*,*,*; + push &s, "tail"; strcat(); + +Note: The push and pop statements could also be used to manipulate the +stack inside or separate from a function, but this should be done with +care. + +The inline statement is used when calling machine language routines that +expect constant byte or word values immediately following the 6502 JSR +instruction. A routine of this type will adjust the return address to the +point directly after the last instruction. When using the inline statement, +it is followed by one or more arguments, separated by commas, and +terminated with a semicolon. The arguments may be constants, addresses, +or strings. + +Examples; + iprint(); inline "Hello World"; //Print "Hello World" + irect(); inline 10,10,100,100; //Draw rectangle from (10,10) to (100,100) + +Note: If a string is specified in an inline statement, rather than creating +an anonymous string and compiling the address inline, the entire string will +be compiled directly inline. + +ASSIGNMENTS + +An assignment is a statement in which the result of an expression is stored +in a variable. An assignment usually consists of a simple variable or +subscripted array element, an = character, and an expression, terminated +with a ; character. + +Examples: + i = i + 1; //Add 1 to contents variable i + c = getchr(); //Call function and store result in variable c + s[i] = 0; //Terminate string at position i + +SHORTCUT-IFS + +A shortcut-if is a special form of assignment consisting of an evaluation +and two expressions, of which one will be assigned based on the result +of the evaluation. A shortcut-if is written as a condition surrounded +by ( and ) characters, followed by a ? character, the expression to be +evaluated if the condition was true, a : character, and the expression to +be evaluated if the condition was false. + +Example: + result = (value1 < value) ? value1 : value2; + +Note: Shortcut-ifs may only be used with assignments. This may change in +the future. + +POST-OPERATORS + +A post-operator is a special form of assignment which modifies the value +of a variable. The post-operator is suffixed to the variable it modifies. + +Post-Operators: + ++ Increment variable (increase it's value by 1) + -- Decrement variable (decrease it's value by 1) + << Left shift variable + >> Right shift variable + +Post-operators may be used with either simple variables or subscripted +array elements. + +Examples: + i++; //Increment the contents variable i + b[i]<<; //Left shift the contenta of element i of array b + +Note: Post-operators may only be used in stand-alone statements, although +this may change in the future. + +ASSIGNMENTS TO REGISTERS + +Registers A, X, and Y may assigned to using the = character. Register A +(but not X or Y) may be used with the << and >> post-operators, while +registers X and Y (but not A) may be used with the ++ and -- post-operators. + +IMPLICIT ASSIGNMENTS + +A statement consisting of only a simple variable is treated as an +implicit assignment of the A register to the variable in question. + +This is useful on systems that use memory locations as strobe registers. + +Examples: + HMOVE; //Move Objects (Atari VCS) + S80VID; //Enable 80-Column Video (Apple II) + +Note: An implicit assignment generates an STA opcode with the variable +as the operand. + +GOTO STATEMENT + +A goto statement unconditionally transfers program execution to the +specified label. When using a goto statement, it is followed by the +label name and a terminating semicolon. + +Example: + goto end; + +Note: A goto statement may be executed from within a loop structure +(although a break or continue statement is preferred), but should not +normally be used to jump from inside a function to outside of it, as +this would leave the return address on the machine stack. + +IF AND ELSE STATEMENTS + +The if then and else statements are used to conditionally execute blocks +of code. + +When using the if keyword, it is followed by an evaluation (surrounded by +parenthesis) and the block of code to be executed if the evaluation was true. + +An else statement may directly follow an if statement (with no other +executable code intervening). The else keyword is followed by the block +of code to be executed if the evaluation was false. + +Examples: + if (c = 27) goto end; + if (n) q = (n/d) else putstr("Division by 0!"); + if (r[j]13) //Echo line to screen + +Note: Unlike the other loop structures do/while statements do not use +6502 JMP instructions. This optimizes the compiled code, but limits +the amount of code inside the loop. + +FOR LOOPS + +The for statement allows the initialization, evaluation, and modification +of a loop condition in one place. For statements are usually used to +execute a piece of code a specific number of times, or to iterate through +a set of values. + +When using the if keyword, it is followed by a pair of parenthesis +containing an initialization assignment statement (which is executed once), +a semicolon separator, an evaluation (which determines if the code block +is exectued), another semicolon separator, and an increment assignment +(which is executed after each iteration of the code block). This is then +followed by the block of code to be conditionally executed. + +The assignments and conditional of a for loop must be populated. If an +infinite loop is desired, use a while () statement. + +Examples: + for (c='A'; c<='Z'; c++) putchr(c); //Print letters A-Z + for (i=strlen(s)-1;i:+;i--) putchr(s[i]); //Print string s backwards + for (i=0;c>0;i++) {c=getchr();s[i]=c} //Read characters into string s + +Note: For loops are compiled using the 6502 JMP statements, so the code +blocks may be abritrarily large. A for loop generates less efficient code +more than a simple while loop, but will always execute the increment +assignment on a continue. + +BREAK AND CONTINUE + +The break and continue statements are used to jump to the beginning or +end of a do, for, or while loop. Neither may be used outside of a loop. + +When a break statement is encountered, program execution is transferred +to the statement immediately following the end of the block associated +with the innermost for or while loop. When using the break keyword, it is +followed with a trailing semicolon. + +When a continue statement is encountered, program execution is transferred +to the beginning of the block associated with the innermost for or while +loop. In the case of a for statement, the increment assignment is executed, +followed by the evaluation, and in the case of a while statement, the +evaluation is executed. When using the break keyword, it is followed with +a trailing semicolon. + +Examples: + do {c=rdkey(); if (c=0) continue; if (c=27) break;} while (c<>13);` + for (i=0;i + +The following functions are defined: + + b = isalnm(c); Returns TRUE if c is alphanumeric, otherwise FALSE. + + An alphanumeric character is a letter (A-Z or a-z), + or a digit (0-9). + + Note: Calls internal routine isaln, which in turn + calls internal routines isdgt and isalp. + + b = isalph(c); Returns TRUE if c is alphabetic, otherwise FALSE. + + An alphabetic character is a letter (A-Z or a-z). + + Note: Call internal routine isalp, which in turn + calls internal routines isupr and islwr. + + b = isbdgt(c); Returns TRUE if c is a binary digit, otherwise FALSE. + + A binary digit is a character in the range 0 through 1. + + Note: Calls internal routine isbin, which shares code + with the internal routine isdgt. + + b = isctrl(c); Returns TRUE if c is a control characte, otherwise FALSE. + + A control character is a character with ASCII code + 0 through 31 or 127. + + Note: Calls internal routine isctl. + + b = isdigt(c); Returns TRUE if c is a digit, otherwise FALSE. + + A digit is a character in the range 0 through 9. + + Note: Calls internal routine isdgt. + + b = isgrph(c); Returns TRUE if c is graphical, otherwise FALSE. + + A graphical character is any character in the + range ! through |. + + Note: Calls internal routine isgrp, which in turn + calls internal routine isprt. + + b = ishdgt(c); Returns TRUE if c is a hex digit, otherwise FALSE. + + A hex digit is a character in the range 0 through 9. + A through F, or a through f. + + Note: Calls internal routine ishex, which in turn + calls internal routine isdgt. + + b = islowr(c); Returns TRUE if c is lowercase, otherwise FALSE. + + An alphabetic character is a letter in the range + a through z. + + Note: Call internal routine islwr. + + b = ispnct(c); Returns TRUE if c is punctuation, otherwise FALSE. + + A punctuation character is any graphical character + that is not aplhapnumeric. + + Note: Calls internal routine ispnc, which in turn + calls internal routines isalp and isgrp. + + b = isprnt(c); Returns TRUE if c is printable, otherwise FALSE. + + A printable character is any character in the + range Space through |. + + Note: Calls internal routine isprt. + + b = isspce(c); Returns TRUE if c is white space, otherwise FALSE. + + The white space characters are Tab (9), Line Feed (10), + Vertical Tab (11), Form Feed (12), Carriage Return (13), + and Space (32). + + Note: Calls internal routine isspc. + + b = isuppr(c); Returns TRUE if c is upper case, otherwise FALSE. + + An uppercase character is a letter in the range + A through Z. + + Note: Call internal routine isupr. + + t = tolowr(c); Returns lower case version of c if it is an upper case + character, otherwise c. + + Note: Calls internal routine isupr. + + t = touppr(c); Returns upper case version of c if it is a lower case + character, otherwise c. + + Note: Calls internal routine islwr. + +Note: This library has no external dependencies. + +Implementation: The standard method of implementing the ctype library is to +use a bit mask table of 128 bytes (one for each standard ASCII character). + +This library instead uses a series of comparisons in the internal routines, +which leave the accumulator unmodified, and occupies approximately 128 bytes +of memory. + diff --git a/doc/file.txt b/doc/file.txt new file mode 100644 index 0000000..f014178 --- /dev/null +++ b/doc/file.txt @@ -0,0 +1,139 @@ +File System Input/Output Functions for C02 Programs + +This library contains functions for file handling. These functions +are included here instead of in stdio.h because not all 6502 systems +support file based input/output. Functions that are not part of the +standard C libraries begin with the letters "fs". + +At the beginning of the program use the directives + + #include + #include + +The following functions are defined: + + fsinit(); Initialize file system. + + This function should be called before calling + before any other file functions. + + Note: Closes any open files and initializes + the library's internal file table. + + f = fsptr(); Find an available file pointer. + + Returns 0 if no more file pointers are available. + + Note: This is called by the fopen() function, which + does the actual file allocation and is of limited + use in application programming. + + r = fschk(f); Check to see if f is a valid file pointer. + + Returns 0 if valid, otherwise 255. + + Note: Called by the fclose(), feof(), fgetc(), + fgets(), fputc(), fputs(), fread(), and fwrite() + functions. + + r = fstat(f); Get status of file table entry or last file error. + + If f is 0, returns a system dependent value + corresponding to the last filesystem I/O error. + + If f is a potentially valid file pointer. returns a + value representing the state of the corresponding + entry in the file table. If the file table entry is + unused, then a 0 is returned. Otherwise, a system + dependent system dependent value is returned. + + If f does not point to a valid file table entry, + then 255 is returned. + + Note: On CBM machines, fstat(0) returns the result + of READST directly after the last error. Valid file + pointer values are between 1 and FOMAX, inclusive + and return a value with bits 0 through 3 containing + the Kernal device number, and bit 7 set if an End of + File or other error was encountered. + + f = fopen(d, &n); Open file specified from null-terminated string n + on device d, returning a pointer to the file. + + Return 0 if the file could not be opened. + + Note: On CBM machines, d is the device number and + f is a logical file nunber as used in a Basic Open + statement. Up to 7 files may be opened at a time. + + r = fclose(f); Close file pointed to by f, returning 0 if + successful or 255 if there was an error. + + Note: Returns 255 if f is not a valid file pointer. + + c = fgetc(f); Read character from file opened to by filepointer f. + + Returns character read from file. + + Note: Returns 255 if f is not a valid file pointer. + + Returns a system dependent garbage character if end + of file has been reached or any other I/O error. Use + feof(f) and fstat(0) to check for these conditions. + + fputc(f, c); Write character c to file opened to filepointer f. + + Use feof(f) and fstat(0) to check for errors after + write. + +----------------------------------------------------------------- + + + r = getstr(&s); Reads a maximum of 128 characters from keyboard + until the Return/Enter key is pressed, storing the + entered characters as null-terminated string s. + + Allows corrections using Backspace/Delete. + + Pressing the Escape/Abort key terminates entry, + leaving the string in an undefined state. + + Returns number of characters entered, or 255 + if entry was aborted. + + Note: Calls getchr() in a loop and uses constants + DELKEY, RTNKEY, and ESCKEY from the system library. + + + r = putstr(&s): Writes up to 128 characters of null-terminated + string s to the screen and advances the cursor to + the beginning of the next line. + + Returns number of characters printed. + + Note: Calls outstr(&s) followed by newlin(). + +Note: This library expects the following functions to be defined: + + setdst(&s); Set destination string pointer + setsrc(&s); Set source string pointer and initialize index + +along with the zero page variable pairs + + dstlo,dsthi: Destination string pointer + srclo,srchi: Source string pointer + +the static array + + ftbl[FOMAX] + +and the assembler constant + + FOMAX The maximum number of files that can be opened + at one time. + +as well as the data structure + + FTBL A system dependent table of bytes containing data + related to files opened by the fopen() function. + See function fstat() for more information. diff --git a/doc/func-idx.txt b/doc/func-idx.txt new file mode 100644 index 0000000..f0a380c --- /dev/null +++ b/doc/func-idx.txt @@ -0,0 +1,90 @@ +Function Library Name Description +abs stdlib Absolute Value Return absolute value of byte. +atoc stdlib ASCII to Character Convert numeric string to byte. +blkbgn block Block Begin Set beginning of block address. +blkend block Block End Set end of block address. +blkseg block Block Segment Set block segment size. +blkset block Block Set Fill entire block with character. +blkrst block Block Reset Set block pointer to beginning of block. +blknxt block Block Next Move block pointer forward one segment. +blkput block Block Append Copy bytes from array to current segment. +blkget block Block Get Copy bytes from current segment to array. +blkmem block Block Memory Search block for segment matching array. +blkstr block Block String Search block for segment beginning with string. +blkswp block Block Swap Swap bytes of array with the current segment. +blksrt block Block Sort Sort segments in block by initial string. +ctoa stdlib Character to ASCII Convert byte to numeric string. +div stdlib Divide Divide two bytes. +fclall file File Close All Close all files. +fclose file File Close Close file. +feof file File End of File Check for end of file condition. +ferror file File Error Get file error information. +fgetc file File Get Character Read character from file. +fgets file File Get String Read string from file. +fopen file File Open Open file. +fputc file File Put Character Write character to file. +fputs file File Put String Write string to file. +fread file File Read Read bytes from file. +fschk file File System Check Check for valid file pointer +fsdst file File Set Destination Set destination array for fread. +fsinit file File System Init Initialize file system. +fsptr file File System Pointer Get unused file pointer. +fssrc file File Set Source Set source array for fwrite. +fstat file File System Status Get file pointer status. +fwrite file File Write Write bytes to file. +getchr stdio Get Character Read character from keyboard. +isalnm ctype Is Alphanumeric Return TRUE if character is A-Z, a-z, or 0-9. +isalph ctype Is Alphabetic Return TRUE if character is A-Z or a-z. +isbdgt ctype Is Binary Digit Return TRUE if character is 0 or 1. +isctrl ctype is Control Return TRUE if ASCII code is 0-31 or 127. +isdigt ctype Is Digit Return TRUE if character is 0-9. +isgrph ctype Is Graphical Return TRUE if ASCII code is 33-126. +ishdgt ctype Is Hex Digit Return TRUE if character is 0-9, A-F, or a-f. +islowr ctype Is Lowercase Return TRUE if character is a-z. +ispnct ctype Is Punctuation Return TRUE if Graphical and not Alphanumeric. +isprnt ctype Is Printable Return TRUE if ASCII code is 32-126. +isspce ctype Is white Space Return TRUE if ASCII code is 9-13 or 32. +isuppr ctype Is Uppercase Return TRUE if character is A-Z. +max stdlib Maximum Return greater of two byte. +memdst memory Memory Destination Set destination array for subsequent functions. +memset memory Memory Set File bytes in array with character. +memchr memory Memory Character Search for byte in array. +memcmp memory Memory Compare Compare bytes in array against destination array. +memcpy memory Memory Copy Copy bytes from array to destination array. +memswp memory Memory Swap Swap bytes in array with destination array. +min stdlib Minimum Return lesser of two byte. +mult stdlib Multiply Multiply two bytes. +ptrset pointer Pointer Set Set pointer to address. +ptrput pointer Pointer Put Write byte and increment pointer. +ptrget pointer Pointer Get Read byte and increment pointer. +ptrinc pointer Pointer Increment Increment pointer. +ptrdec pointer Pointer Decrement Decrement pointer. +ptradd pointer Pointer Add Add value to pointer. +ptrsub pointer Pointer Subtract Subtract value from pointer. +ptrcmp pointer Pointer Compare Compare pointer against address. +ptrsav pointer Pointer Save Save pointer into two-byte array. +ptrrst pointer Pointer Restore Restore pointer from two-byte array. +putchr stdio Put Character Write character to screen. +getstr stdio Get String Read string from keyboard. +outstr stdio Output String Write string to screen. +outsub stdio Output Substring Write substring to screen. +putstr stdio Put String Write string plus newline to screen. +rand stdlib Random Generate pseudorandom number. +rands stdlib Random Seed Seed random number generator. +shiftl stdlib Shift Left Shift byte left specified number of bits. +shiftr stdlib Shift Right Shift byte right specified number of bits. +strapd string String Append Append character to string. +strcat string String Concatenate Concatenate string to destination string. +strchr string String Character Search for character in string. +strcmp string String Compare Compare string contents against destination string. +strcpy string String Copy Copy string contents to destination string. +strcsp stringx String Char Span Return length of span in destination not in string. +strcut string String Cut Copy substring to destination string. +strdst string String Destination Set destination string for subsequent functions. +strlen string String Length Calculate length of string. +strpbk stringx String Pointer Break Find first character in destination found in string. +strrch string String Reverse Char Search for character from end of string. +strspn stringx String Span Return length of span in destination found in string. +strstr string String String Search for string in destination string. +tolowr ctype To Lowercase Convert character to lowercase. +touppr ctype To Uppercase Convert character to uppercase. diff --git a/doc/header.txt b/doc/header.txt new file mode 100644 index 0000000..51e5b05 --- /dev/null +++ b/doc/header.txt @@ -0,0 +1,83 @@ +System Specific Header File Specification + +The very first directive of the program must be + + #include + +where header.h02 is the system specific header file, (e.g. apple1.h02, +vic20.h02, etc.). + +Note: This will probably be replaced with a command line parameter +(e.g. '-s apple1', '-s vic20', etc...) to allow program portability. + +If compatibility with the C02 Standard Libraries is needed, the following +functions must be defined: + + c = plkey(); Polls keyboard and returns raw ASCII character + corresponding to last/current pressed key. + + Returns constant NULKEY (usually 0) if no key was + pressed. + + c = rdkey(); Waits for a keypress and returns the raw ASCII + character corresponding to the pressed key. + + Note: Usually a loop that calls plkey(), but may + also directly call a system subroutine. + + c = getkey(); Waits for a keypress and returns the cleaned + ASCII value corresponding to the pressed key. + + Note: Calls rdkey() followed by any necessary + character code conversions. This can be due to + high-bit being set by keyboard decoder, + non-standard key mappings, keys that generate + escape sequences, etc... + + newlin(); Advances the cursor to the beginning of then + next line. + + Note: Depending on the system, this will usually + output a Carriage Return, Line Feed, both. + + prchr(c); Writes character c to the screen. + + Note: May directly access memory-mapped I/O + or may call a system subroutine. + + setdst(&s): Stores pointer to &s in dstlo and dsthi. + + setsrc(&s): Stores pointer to &s in srclo and srchi and + initializes Y register to 0. + +along with the Zero Page locations (each pair of which must be sequential) + + srclo, srchi Spurce String Pointer + dstlo, dsthi Destination String Pointer + +the following locations that may be Zero Page, but don't have to before + + temp0 Temporary variables used by stdlib.asm + temp1 + temp2 + +and the following locations that must be preserved between function calls + + random Storage for the Random Number Generator + + Contains the last number generated and is used to + generate the next number in the sequence + + rdseed Seed for Pseudo-Random Number Generator + + Usually a counter or timer. If one is not provided + by the system, should be generated by incrementing + in the plkey(), rdkey() functions. + +and the constants + + DELKEY ASCII code for Delete/Backspace key (usually DEL or BS) + ESCKEY ASCII code for Escape/Abort key (usually ESC) + NULKEY Returned if no Key was Pressed + RTNKEY ASCII code for Return/Enter key (usually CR) + diff --git a/doc/keywords.txt b/doc/keywords.txt new file mode 100644 index 0000000..bf0b196 --- /dev/null +++ b/doc/keywords.txt @@ -0,0 +1,50 @@ +Standard C Keywords +break +case +char +const +continue +default +do +else +for +goto +if +return +switch +void +while + +C Preprocessor directives +#define +#error +#include +#pragma + +Questionable C Keywords +enum +extern +register +signed +sizeof +struct +typedef +union +unsigned +volatile + +Unused Standard C Keywords +auto n/a +double n/a +float n/a +int n/a +long n/a +short n/a +static n/a + +Unused Preprocessor Directives +#if +#ifdef +#ifndef +#undef +# line diff --git a/doc/memory.txt b/doc/memory.txt new file mode 100644 index 0000000..f073345 --- /dev/null +++ b/doc/memory.txt @@ -0,0 +1,82 @@ +Array Manipulation Functions for C02 + +This library contains functions for handling non-string arrays. It is +maintained separately from string.h so that it can be included only +when needed, in order to reduce program size. + +Arrays may be declared with up to 256 elements, but only lengths of up +to 255 characters may be passed to the array handling functions. + +Usage: at the beginning of the program use the directives + + #include + +The following functions are defined: + + memdst(&d); Sets array d as the destination array for subsequent + memchr(). memcmp(), strcpy(), and memset() calls. + + This function is not part of the standard C and + C++ string libraries. It is needed because of the + parameter passing limitations of C02. + + Note: Aliased to the setdst() routine which sets + variables dstlo and dsthi as a pointer to the array. + + memset(c, n); Fills first n bytes of the destination array set + by a a prior memdst() call with character c. + + Note: dstlo and dsthi are left pointing to the + destination array. + + p = memchr(c, n); Searches for character c in the first n bytes of the + destination array set by a a prior memdst() call. + + Returns position of first occurance of character + in array, or 255 if character was not found or a + length of 0 was specified. + + Note: dstlo and dsthi are left pointing to the + destination array. + + c = memcmp(n, &s); Compares up to n bytes of source array s against the + destination array set by a prior memdst() call. + + Returns 255 if destination < source, 0 if + destination = source, and 1 if destination > source. + + These results can be evaluated using the C02 + unary comparator ! or the test-operators :+ or :-. + + Note: dstlo and dsthi are left pointing to the + destination array. + + memcpy(n, &s); Copies n bytes of source array s into destination + array set by prior memdst() call. Data in the + destination array starting at position n is left + undisturbed. + + Note: dstlo and dsthi are left pointing to the + destination array. + + memswp(n, &s); Swaps n bytes of source array s with destination + array set by prior memdst() call. Data in both + arrays starting at position n is left undisturbed. + + Note: dstlo and dsthi are left pointing to the + destination array. + +Note: This library expects the following functions to be defined + + setdst(&s); Set destination string pointer + setsrc(&s); Set source string pointer and initialize index + +along with the zero page pairs + + strlo, strhi Source String Pointer + dstlo, dsthi Destination String Pointer + +and the memory locations + + temp0, temp1 Temporary storage + diff --git a/doc/notes.txt b/doc/notes.txt new file mode 100644 index 0000000..1348f78 --- /dev/null +++ b/doc/notes.txt @@ -0,0 +1,54 @@ +Keywords: + break complete + case unimplemented + char incomplete + const unimplemented + continue complete + default unimplemented + do incomplete - break/continue don't work + else complete + for complete + goto complete + if complete + return untested + switch unimplemented + void incomplete + while complete + +Features: + comparisons variable type checking not implemented + functions definition incomplete + + +Conditional Operator Bit-Mask + +Character + = 1 + < 2 + > 4 + +Comparator Complement + == 1 6 <> + < 2 5 >= + <= 3 4 > + > 4 3 <= + >= 5 2 < + <> 6 1 == + +XOR 7 Reverses Operator!!! + +Block Sort Algorithm +;blkptr = blkbgn +;while blkptr < blkend +; dst = blkptr +; src = blkptr +; while dst += seglen < blkend +; if *dst < *src +; src = dst +; if src <> blkptr +; *m = *src +; *src = *blkptr +; *blkptr = *m +; blkptr += seglen + + diff --git a/doc/pointer.txt b/doc/pointer.txt new file mode 100644 index 0000000..a2abcd6 --- /dev/null +++ b/doc/pointer.txt @@ -0,0 +1,139 @@ +Pointer Functions + +This library contains functions for basic pointer access and manipulation. + +These functions are intended to allow sequential reading and writing of +individual bytes to arbitrary locations in memory. + +Only one pointer may be active at a time, but it's contents may be saved +and restored. + +Note: There is no concept of a null pointer in C02. A pointer containing +the value 0 simply points to the first byte of memory. + +In the equivalent C code examples below, the system pointer is represented +as the variable p. In all cases, assume the following declaration : + + int *p; + +Usage: at the beginning of the program use the directives + + #include + +The following application functions are defined: + + ptrset(&v); Pointer Set: Set pointer contents to the address of + variable v. + + This is equivalent to the C code + + p = &v; + + Note: Sets variables ptrlo and ptrhi. + + ptrput(b); Pointer Put: Stores value of b in the byte currently + pointed to and increments the pointer. + + This is equivalent to the C code + + *p = b; p++; + + Note: Updates variables ptrlo and ptrhi. + + b = ptrget(); Pointer Get: Retrieves the contents of the byte + currently pointed to and increments the pointer. + + This is equivalent to the C code + + b = *p; p++; + + Note: Updates variables ptrlo and ptrhi. + + ptrinc(); Pointer Increment: Increases the pointer value by 1, + causing it to point to the next byte in memory. + + This is equivalent to the C code + + p++; + + Note: Updates variables ptrlo and ptrhi. + + ptrdec(); Pointer Decrement: Decreases the pointer value by 1, + causing it to point to the previous byte in memory. + + This is equivalent to the C code + + p++; + + Note: Updates variables ptrlo and ptrhi. + + ptradd(n); Pointer Add: Adds the value n to the address contained + in the pointer, moving it that many bytes forward in + memory. + + This is equivalent to the C code + + p += n; + + Note: Updates variables ptrlo and ptrhi. + + ptrsub(n); Pointer Subtract: Adds the value n to the address + contained in the pointer, moving it that many bytes + backward in memory. + + This is equivalent to the C code + + p -= n; + + Note: Updates variables ptrlo and ptrhi. + + ptrcmp(&v); Pointer Compare: Compares pointer contents against + the address of variable v. + + Returns 255 if the pointer is less than the address + (pointing to a byte lower in memory), 0 if the pointer + is equal to the address (pointing to the same byte), + and 1 if greater than tge address (pointing to a + byte higher in memory). + These results can be evaluated using the C02 + unary comparator ! or the test-operators :+ or :-. + + This is equivalent to the C code + + if (p < &v) return 255; + else if (p > &v) return 1; + else return 0; + + Note: Sets variables srclo and srchi. + + ptrsav(&r); Pointer Save: Copies the pointer contents into the + first to bytes of array r. + + This is roughly equivalent to the C code + + r = (int) p; + + + Note: Sets variables srclo, srchi, and temp0. + + ptrrst(&r); Pointer Restore: Copies the first to bytes of array r + into the pointer contents. + + This is roughly equivalent to the C code + + p = (void*) r; + + Note: Sets variables srclo, srchi, ptrlo, and ptrhi. + +Note: This library expects the following functions to be defined + + setsrc(&s); Set source string pointer and initialize index + +along with the zero page variable pairs + + strlo, strhi Source String Pointer + +as well as the transient variable + + temp0 Temporary storage + diff --git a/doc/quickref.odt b/doc/quickref.odt new file mode 100644 index 0000000..9a57ed8 Binary files /dev/null and b/doc/quickref.odt differ diff --git a/doc/screen.txt b/doc/screen.txt new file mode 100644 index 0000000..28c3abe --- /dev/null +++ b/doc/screen.txt @@ -0,0 +1,113 @@ +Screen Control Functions for C02 + +This is a prototype definition for a library providing functions +to manipulate the screen and move the cursor. Since this code is +highly system dependent, a separate library will need to be +created for each system type. + +The following functions should be defined: + + clrscn(); Clears the screen and returns the cursor to the + home position. + + Note: May call a system routine, or may print + "clear screen" character sequence. + + crsrhm(); Moves cursor to home position (upper left corner + of the screen). + + Note: May call mvcrsr(0,0); or may print "cursor + home" character sequence. + + crsrlf(); Moves cursor one column to the left. May or may not + screen wrap, depending on system. + + Note: May call mvcrsr; or may print "cursor left" + character sequence. + + crsrrt(); Moves cursor one column to the right. May or may not + screen wrap, depending on system. + + Note: May call mvcrsr; or may print "cursor right" + character sequence. + + crsrup(); Moves cursor one row up. + + Note: May call mvcrsr; or may print "cursor up" + character sequence. + + crsrdn(); Moves cursor one row down. + + Note: May call mvcrsr; or may print "cursor down" + character sequence. + + mvcrsr(r, c); Moves cursor to row r, column c. + + Note: May call system routine, or set system variables. + + h = scnhgt(); Returns screen height in rows. + + Note: May call system routine, or read system variable. + + w = scnwid(); Returns screen width in columns. + + Note: May call system routine, or read system variable. + + c = scncol(); Returns current screen column. + + Note: May call system routine, or read system variable. + + r = scnrow(); Returns current screen row. + + Note: May call system routine, or read system variable. + + txtclr(c); Sets text color to system color c. + + Note: May call system routine or may print color change + sequence. + + bkgclr(c); Sets background color to system color c. + + Note: May call system routine or may print color change + sequence. + + +Assembly Constants (Defined in System Header file) + + BLACK Code for color Black + BLUE Code for color Blue + GREEN Code for color Green + CYAN Code for color Cyan + RED Code for color Red + MAGNTA Code for color Magenta + YELLOW Code for color Yellow + WHITE Code for color White + + BREAK ASCII code for Break/Stop Key + BCKSPC ASCII code for Backspace key + CLEAR ASCII code for Clear Key + DELETE ASCII code for Delete key + DOWN ASCII code for Cursor Down Key + ENTER ASCII code for Return/Enter key (usually CR) + ESCAPE ASCII code for Escape/Abort key (usually ESC) + FNx ASCII code for Function Key x + HOME ASCII code for Home Key + INSERT ASCII code for Insert Key + LEFT ASCII code for Cursor Left Key + RIGHT ASCII code for Cursor Left Key + TAB ASCII code for Tab Key + UP ASCII code for Cursor Up Key + + BTMLFT ASCII code for Box Drawing Bottom Left Corner + BTMRGT ASCII code for Box Drawing Bottom Right Corner + BTMTEE ASCII code for Box Drawing Bottom to Cetter Tee + CTRCRS ASCII code for Box Drawing Center Cross + HRZLIN ASCII code for Box Drawing Horizontal Line + LFTTEE ASCII code for Box Drawing Left To Center T + RGHTEE ASCII code for Box Drawing Right To Center T + TOPLFT ASCII code for Box Drawing Top Left Corner + TOPRGT ASCII code for Box Drawing Top Right Corner + TOPTEE ASCII code for Box Drawing Top to Center T + VRTLIN ASCII code for Box Drawing Verical Line + + diff --git a/doc/small-c.txt b/doc/small-c.txt new file mode 100644 index 0000000..a2dc7ec --- /dev/null +++ b/doc/small-c.txt @@ -0,0 +1,155 @@ +Types + char — 8 bit data element + int — 16 bit data element + +Declarations + type name — declares name to be element + type *name — declares name to be pointer to element of specified type + type name[] — syntactically identical to above pointer declaration + type name[constant] — declares an array of "constant” size where + each array element is of specified type + +Constants + Decimal number. + Single or pair of ASCII characters enclosed in single quotes, + such as ‘a’ or ‘T X ’. + String enclosed in double quotes, such as “this is a string”. + The value such a constant yields is a pointer to the first character + of the string which the compiler stores in memory. + +Function Calls + Defined as any expression followed by an open paren. Thus, a function + can be to a named routine, such as “print()” , or to the results of some + expression, such as “1000()” (which calls location 1000 decimal), or + “array[i]()” which calls the location whose value is found in array[i] . + +Subscripted elements. + Either an array name or a pointer may be subscripted to refer to the + appropriate element. Subscripts are assumed to start from zero. Therefore, + legal expressions are: + array [0] - the first element in array, + array [x+31] — the element at the address given by adding x to 31 + and then to array, + pointer [i] — the elemen t at the address given by adding i to the + contents of pointer. + Only single dimensions are allowed. Subscripting either an integer array + or a pointer to an integer will cause the subscript expression to be + doubled. Therefore, if you declare “int *ptr”, the expression “ptr[3]” + refers to the element at ptr+6. + +Unary Expression Operators + "-" — forms the two’s complement of the expression (minus). + “*” — refers to the element pointed to by the expression + (providing the expression is a pointer). + “&” — evaluates the address of the given expression, providing + it hasone. Hence, &count yields the address of the element + “count”. &1000 is an error. + “&” — increments the expression by one. If this appears before the + expression, it increments before using it. If it appears after + it, it will increment it after. Only values (expressions which + can appear on the left-hand side of an equal sign) are allowed. + Hence, assuming “count” contains a 5, ++count would evaluate to + a 6, and “count” would contain a 6. Likewise, count++ would + evaluate to a 5, and count would contain a 6. 1000++ is illegal. + If this operator is applied to an integer pointer, it will + increment by 2. + "--" — decrements the expression by one. This works just like ++ but + subtracts one rather than adding. + +Binary Operators + “+” — adds the two expressions (i.e. count + total) + "-" — subtracts the two expressions. + “*” — multiplies the two expressions. + “/” — divides the first expression by the second. + "%" — yields the remainder after dividing the first expression + by the second (modulo). + “|” — yields the logical inclusive “or” of the two expressions. + "^" — yields the logical exclusive “or” of the two expressions. + "&" — yields the logical “and” of the two expressions. + “=” — assigns the value of the expression on the right to the one + on the left. Since evaluation is done right to left in this + case, syntaxes like "x = y = z" are legal. + +Comparison Operators + “==” — tests for equality. + “==” — tests for inequality. + “<” — tests for less than. + “>” — tests for greater than. + “<=” — tests for less than or equal to + “>=” — tests for greater than or equal to + Comparisons involving a pointer (which is an address) are done + as unsigned compares. All other compares are signed. + +Statements + expression; An expression, no matter how complex, is considered + a simple statement. + if (expression); If the expression is non-zero, the statement + is executed , otherwise it isn’t. + if (expression) statement; else statement; This form of the “if” + statement allows the “else” clause. As is the case with most + “dangling else” ambiguities, all “else" statements pair with + the nearest unmatched “if". + while (expression) statement; The statement is performed until + the expression becomes zero. Since the test is made before the + statement is executed the first time, it need not be executed + at all. + break; This statement will cause control to be transferred out + of the inner-most “while” loop. + continue; This statement, used within a “while” loop, will transfer + control back to the top of the loop. + return; This statement does an immediate return from the current + function . If a function does not end with this statement, one + is performed regardless. + return expression; This statement allows a function to return a + value explicitly. + ; A semicolon by itself is considered a null statement which does + nothing but take the place of a statement. You see this in forms + such as: “while (*iptr++ = *jptr++);” where the test itself + contains all the necessary parts of the statement. + {statement; statement;. . . ; statement;} The use of curly brackets + (“{ }”) around any group of simple statements is considered a + compound statement. A compound statement can be used anywhere a + simple statement can. For example: + while (1) {x = 3; y = 10; funct(33);} + or + if (x< y) + { print(x); + total (x); + --x; + } + else + { type(“all done”); + x = y; + } + +Pseudo-ops + #include filename — Anywhere this statement appears in the program, + the indicated filename will be opened and inserted. The “included” + file may not contain an “#include” statement. + #define name string — This statement will cause the given name to + be replaced by the string throughout the entire program . Normally, + it is used to define constants, such as: + #define tablesize 1000 + #define maxlength 8 + But it can also be used for any sort of text: + #define jprint 3crs print(12); print(12); print(l2); + The replacem ent is purely on a text level, and error checking will + be performed only after the replacement. + #asm . . . #endasm — This structure is not supported by standard C, + but it was a feature I felt I needed. It may appear anywhere a statement + would, but it passes everything between the word “#asm” and the word + “#endasm” right through the parser without intervention. It is intended + to be used to pass assembly language code through the parsing mechanism. + Since it counts as a single statement, allowable (and expected) forms are: + if (x < y) + #asm + LHLD TOTAL + CALL ADD + CNC ERROR + #end asm + else return; + This pseudo-op conceivably allows an entire assembly language program to + be passed through the compiler. Its intent is to allow machine dependent + features (like the 8080’s “IN” and “OUT” instructions to be used without + writing separate programs). + diff --git a/doc/stdio.txt b/doc/stdio.txt new file mode 100644 index 0000000..002ed01 --- /dev/null +++ b/doc/stdio.txt @@ -0,0 +1,72 @@ +Standard Input/Output Functions for C02 Programs + +At the beginning of the program use the directives + + #include + +The following functions are defined: + + c = getchr(); Waits for a keypress and returns the cleaned + ASCII value corresponding to the pressed key. + + Note: Aliased to getkey() from system library. + + putchr(c); Writes character c to the screen. + + Note: Aliased to prchr() from system library. + + r = getstr(&s); Reads a maximum of 128 characters from keyboard + until the Return/Enter key is pressed, storing the + entered characters as null-terminated string s. + + Allows corrections using Backspace/Delete. + + Pressing the Escape/Abort key terminates entry, + leaving the string in an undefined state. + + Returns number of characters entered, or 255 + if entry was aborted. + + Note: Calls getchr() in a loop and uses constants + DELKEY, RTNKEY, and ESCKEY from the system library. + + r = outstr(&s): Writes up to 128 characters of null-terminated + string s to the screen. + + Returns position of null terminator in string. + + Note: Calls outsub(0, &s). + + r = outsub(n, &s): Writes up to 128 characters of null-terminated + string s to the screen, starting at position n. + + Returns position of null terminator in string. + + Note: Calls putchr() in a loop. + + r = putstr(&s): Writes up to 128 characters of null-terminated + string s to the screen and advances the cursor to + the beginning of the next line. + + Returns number of characters printed. + + Note: Calls outstr(&s) followed by newlin(). + +Note: This library expects the following functions to be defined: + + getkey(); Wait for and read ASCII character from keyboard + prchr(c); Print ASCII character to screen + delchr(); Backspace and delete previous character on screen + newlin(); Advance cursor to beginning of next line + setsrc(&s); Set source string pointer and initialize index + +along with the zero page variable pairs + + srclo,srchi: Source string pointer + +and the assembler constants + + DELKEY Delete/Backspace key ASCII code (usually DEL or BS) + ESCKEY Escape/Abort key ASCII code (usually ESC) + RTNKEY Return/Enter key ASCII code (usually CR) + diff --git a/doc/stdlib.txt b/doc/stdlib.txt new file mode 100644 index 0000000..9a51a2c --- /dev/null +++ b/doc/stdlib.txt @@ -0,0 +1,100 @@ +Standard Library Functions for C02 Programs + +At the beginning of the program use the directives + + #include + +The following functions are defined: + + c = abs(b); Returns the absolute value of the two's-complement + byte b. + + In two's-complement arithmetic, the unsigned values + 0 - 127 are considered positive, while the unsigned + values 128 - 255 are considered negative. + + c = atoc(&s); Returns the numeric value of the string in array s. + + Does not skip leading white-space characters and + stops when first non-digit character is encountered. + + Overflows are ignored, so numbers greater than 255 + will be returned modulo 256. + + ctoa(c, &s); Stores the ASCII representation of usigned byte c + as a null-terminated string in array s. + + The array must be dimensioned to at least 4 bytes. + + c = max(b, d); Returns the greater of the two unsigned bytes b and d. + + c = min(b, d); Returns the lesser of the two unsigned bytes b and d. + + c = mult(d, r); Returns the product of byte d times byte r. + + Overflows are ignored, so results greater than 255 + will be returned modulo 256. + + c = div(n, d); Returns the quotient of byte n divided by byte d. + + Remainders are discarded and division by 0 returns ??. + + c = rand(); Returns pseudo-random number. Sequence repeats + after 255 repeated calls. The generator must be + seeded using the rands() function before the first + call to rand(). + + rands(n); Seeds the pseudo-random number generator. + + If n is 0, the generator is seeded with a system + seed value. This should be used for normal operation. + + If n is not 0. then it is used as the seed. This can + be used for program testing or when a predictable + pattern is needed. + + Note: The system seed is generated by a counter or + timer. On systems that don't use a timer, the counter + is cycled by the keyboard routines, so the getkey() + or getchr() function must called at least once before + a rands(0) call. + + c = shiftl(b, n); Returns byte b shifted n bits to the left, filling + with 0's from the right. + + If n is greater than 8, all bits will be shifted out, + and a value of 0 is treated as 256. + + c = shiftr(b, n); Returns byte b shifted n bits to the right, filling + with 0's from the left. + + If n is greater than 8, all bits will be shifted out, + and a value of 0 is treated as 256. + + Note: Using the shiftl() or shiftr() functions with + an asignment generates 9 to 12 bytes of code, whereas + the << and >> post-operators generate either 2 or 3 + bytes each. So for a constant number of shifts, the + post-operators will generate smaller code for less + than 5 shifts and will always be faster. + + +Note: This library expects the following function to be defined + + setsrc(&s); Set source string pointer and initialize index + +along with the zero page variables + + srclo,srchi: Source string pointer + +as well as the transient variables + + temp0 Temporary storage + temp1 + temp2 + +and the static variables + + random Psuedo-random number generator seed Value + rdseed System generated initial seed (counter or timer) + diff --git a/doc/string.txt b/doc/string.txt new file mode 100644 index 0000000..088fbfd --- /dev/null +++ b/doc/string.txt @@ -0,0 +1,138 @@ +Common String Manipulation Functions for C02 + +Strings are zero-terminated arrays of type char with a maximum length +of 128 characters. + +The first character in a string is at position 0, and the last character +is at position length minus 1. + +Since all of the routines stop processing at the 128th character, a 128 +character string does not require a zero terminator. + +Due to the limitations of parameter passing in C02, the argument lists of +most of these functions do not match those in standard C and C++. + +Usage: at the beginning of the program use the directives + + #include + +The following functions are defined: + + p = strapd(c, &s); Append character c to string s. + + Returns length of new string. + + If the string length exceeds 127 prior to the + append, no action is taken and the existing + length is returned. + + This function is not part of the standard C and + C++ string libraries. It is included because it + is more efficient than the equivalent C02 code. + + p = strchr(c, &s); Searches string s for character c. + + Returns position of first occurance of character + in string, or 255 if character was not found. + + n = strlen(&s); Determines length of string s. + + Returns length of string. + + p = strrch(c, &s); Searches end of string s for character c. + + Returns position of last occurance of character + in string, or 255 if character was not found. + + strdst(&d); Sets string d as the destination string for subsequent + strcat(). strcmp(), strcpy(), and strstr() calls. + + This function is not part of the standard C and + C++ string libraries. It is needed because of the + parameter passing limitations of C02. + + Note: Aliased to the setdst() routine which sets + variables dstlo and dsthi as a pointer to the string. + + n = strcat(&s); Concatenates source string s onto the end of + destination string set by prior strdst() call. + + Returns total length of concatenated string. + + Note: dstlo and dsthi are left pointing to the + destination string. + + c = strcmp(&s); Compares source string s against destination + string set by prior strdst() call. + + Returns 255 if destination < source, 0 if + destination = source, and 1 if destination > source. + + These results can be evaluated using the C02 + unary comparator ! or the test-operators :+ or :-. + + Note: dstlo and dsthi are left pointing to the + destination string. + + n = strcpy(&s); Copies wource string s into destination string set + by prior strdst() call, replacing previous contents. + + Returns number of characters copied. + + Note: dstlo and dsthi are left pointing to the + destination string. + + To copy the first n characters from string s to + string d, the following code can be used: + + strdst(&d); strcpy(&s); s[n]=0; + + n = strcut(n, &s); Copies from source string s, starting at position n, + into destination string set by prior strdst() call, + replacing previous contents. + + Returns number of characters copied. + + This function is not part of the standard C and + C++ string libraries. It is included because + it is faster and more compact tham the equivalent + C02 code. + + To copy a substring starting at position n with + length l from string s to string d, the following + code can be used: + + strdst(&d); strcut(&s, n); s[l]=0; + + Note: calls routine strcat(). leaving dstlo and + dsthi pointing to the destination string, along + with strlo and strhi pointing to the address of + position n in the source string. + + p = strstr(&s); Searches for destination string s in source string + set by prior strdst() call. + + Returns position of source string in destination + string, or 255 if character was not found. + + Note: calls routine strcmp(), leaving dstlo and + dsthi pointing to the address of the position of + the source string in the destination string (or + the end of the destination string if the source + string was not found). + +Note: This library expects the following functions to be defined + + setdst(&s); Set destination string pointer + setsrc(&s); Set source string pointer and initialize index + +along with the zero page variable pairs + + strlo, strhi Source String Pointer + dstlo, dsthi Destination String Pointer + +as well as the transient variables + + temp0 Temporary storage + temp1 + diff --git a/doc/stringx.txt b/doc/stringx.txt new file mode 100644 index 0000000..8b04ef8 --- /dev/null +++ b/doc/stringx.txt @@ -0,0 +1,67 @@ +Extended String Manipulation Functions for C02 + +This library contains less commonly used string functions. It is maintained +as a separate set of files so that it can be included only when needed, in +order to reduce program size. + +Strings follow all the same rules as specified in the string.h02 library. + +Usage: at the beginning of the program use the directives + + #include + #include + +The following functions are defined: + + + + n = strspn(&s); Returns the length of the span of characters at + the beginning of destination string set by prior + strdst() call that are present in source string s. + + This mimics the functionality of the standard C + and C++ strspn() function. + + Note: calls routine strchr(), leaving dstlo and + dsthi pointing to the destination string. + + n = strcsp(&s); Returns the length of the span of characters at + the beginning of destination string set by prior + strdst() call that are not present in source + string s. + + This mimics the functionality of the standard C + and C++ strcspn() function. + + Note: aliased to the strbrk() function, which calls + strchr(), leaving dstlo and dsthi pointing to the + destination string. + + n = strpbk(&s); Returns the poisition of the first character in + the destination string set by prior strdst() call + that is present in source string s. + + If no characters in the source string are present + in the destination string, returns 255. + + This mimics the functionality of the standard C + and C++ strpbrk() function. + + Note: calls routine strchr(), leaving dstlo and + dsthi pointing to the destination string. + +Note: This library expects the following functions to be defined + + setdst(&s); Set destination string pointer + setsrc(&s); Set source string pointer and initialize index + strchr(c, &s); Return position of character in string + +along with the zero page pairs + + strlo, strhi Source String Pointer + dstlo, dsthi Destination String Pointer + +and the memory locations + + temp0, temp1 Temporary storage + diff --git a/doc/syntax.bnf b/doc/syntax.bnf new file mode 100644 index 0000000..b849b9d --- /dev/null +++ b/doc/syntax.bnf @@ -0,0 +1,17 @@ +conditional := expression | expression comparator term +comparator := comparacter | comparacter comparacter +comparactor := '=' | '<' | '>' +operator := '+' | '-' | '&' | '|' | '^' +term := element | value +element := variable '[' value ']' + +number := binary | decimal | hexadecimal +hexadecimal := '$' hexdigit hexdigit +decimal := digit | decimal digit +binary := '%' bit bit bit bit bit bit bit bit +letter := 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | + 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | + 'W' | 'X' | 'Y' | 'Z' +hexdigit := digit | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' +digit := bit | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' +bit := '0' | '1'