From 6d66ba171ed03263a50a98f9822e31217a1fdced Mon Sep 17 00:00:00 2001 From: Brian Paul Date: Fri, 21 Nov 2003 16:50:03 +0000 Subject: reformat comments for 80-column viewing --- src/mesa/main/arbparse.c | 461 +++++++++++++++++++++++++---------------------- 1 file changed, 248 insertions(+), 213 deletions(-) (limited to 'src/mesa') diff --git a/src/mesa/main/arbparse.c b/src/mesa/main/arbparse.c index 2071835049e..e8a87aeba10 100644 --- a/src/mesa/main/arbparse.c +++ b/src/mesa/main/arbparse.c @@ -46,7 +46,8 @@ /* TODO: * Fragment Program Stuff: * ----------------------------------------------------- - * - How does negating on SWZ work?? If any of the components have a -, negate? + * - How does negating on SWZ work?? If any of the components have a -, + * negate? * - how does thing like 'foo[N]' work in src registers? * * - things from Michal's email @@ -56,7 +57,8 @@ * + fix multiple cases in switches, that might change * (these are things that are #defined to the same value, but occur * only on fp or vp's, which funkifies the switch statements) - * - STATE_TEX_* STATE_CLIP_PLANE, etc and PRECISION_HINT_FASTEST/PositionInvariant + * - STATE_TEX_* STATE_CLIP_PLANE, etc and PRECISION_HINT_FASTEST/ + * PositionInvariant * * - check all limits of number of various variables * + parameters @@ -93,8 +95,9 @@ * Outstanding Questions: * ----------------------------------------------------- * - palette matrix? do we support this extension? what is the extention? - * - When can we fetch env/local params from their own register files, and when - * to we have to fetch them into the main state register file? (think arrays) + * - When can we fetch env/local params from their own register files, and + * when to we have to fetch them into the main state register file? + * (think arrays) * * Grammar Changes: * ----------------------------------------------------- @@ -116,83 +119,104 @@ typedef byte *production; /* VERSION: 0.3 */ /* - INTRODUCTION - ------------ - - The task is to check the syntax of an input string. Input string is a stream of ASCII - characters terminated with null-character ('\0'). Checking it using C language is - difficult and hard to implement without bugs. It is hard to maintain and change prior - to further syntax changes. - - This is because of high redundancy of the C code. Large blocks of code are duplicated with - only small changes. Even using macros does not solve the problem, because macros cannot - erase the complexity of the code. - - The resolution is to create a new language that will be highly oriented to our task. Once - we describe particular syntax, we are done. We can then focus on the code that implements - the language. The size and complexity of it is relatively small than the code that directly - checks the syntax. - - First, we must implement our new language. Here, the language is implemented in C, but it - could also be implemented in any other language. The code is listed below. We must take - a good care that it is bug free. This is simple because the code is simple and clean. - - Next, we must describe the syntax of our new language in itself. Once created and checked - manually that it is correct, we can use it to check another scripts. - - Note that our new language loading code does not have to check the syntax. It is because we - assume that the script describing itself is correct, and other scripts can be syntactically - checked by the former script. The loading code must only do semantic checking which leads us to - simple resolving references. - - THE LANGUAGE - ------------ - - Here I will describe the syntax of the new language (further called "Synek"). It is mainly a - sequence of declarations terminated by a semicolon. The declaration consists of a symbol, - which is an identifier, and its definition. A definition is in turn a sequence of specifiers - connected with ".and" or ".or" operator. These operators cannot be mixed together in a one - definition. Specifier can be a symbol, string, character, character range or a special - keyword ".true" or ".false". - - On the very beginning of the script there is a declaration of a root symbol and is in the form: +INTRODUCTION +------------ + +The task is to check the syntax of an input string. Input string is a +stream of ASCII characters terminated with null-character +('\0'). Checking it using C language is difficult and hard to +implement without bugs. It is hard to maintain and change prior to +further syntax changes. + +This is because of high redundancy of the C code. Large blocks of code +are duplicated with only small changes. Even using macros does not +solve the problem, because macros cannot erase the complexity of the +code. + +The resolution is to create a new language that will be highly +oriented to our task. Once we describe particular syntax, we are +done. We can then focus on the code that implements the language. The +size and complexity of it is relatively small than the code that +directly checks the syntax. + +First, we must implement our new language. Here, the language is +implemented in C, but it could also be implemented in any other +language. The code is listed below. We must take a good care that it +is bug free. This is simple because the code is simple and clean. + +Next, we must describe the syntax of our new language in itself. Once +created and checked manually that it is correct, we can use it to +check another scripts. + +Note that our new language loading code does not have to check the +syntax. It is because we assume that the script describing itself is +correct, and other scripts can be syntactically checked by the former +script. The loading code must only do semantic checking which leads us +to simple resolving references. + +THE LANGUAGE +------------ + +Here I will describe the syntax of the new language (further called +"Synek"). It is mainly a sequence of declarations terminated by a +semicolon. The declaration consists of a symbol, which is an +identifier, and its definition. A definition is in turn a sequence of +specifiers connected with ".and" or ".or" operator. These operators +cannot be mixed together in a one definition. Specifier can be a +symbol, string, character, character range or a special keyword +".true" or ".false". + +On the very beginning of the script there is a declaration of a root +symbol and is in the form: .syntax ; - The must be on of the symbols in declaration sequence. The syntax is correct if - the root symbol evaluates to true. A symbol evaluates to true if the definition associated with - the symbol evaluates to true. Definition evaluation depends on the operator used to connect - specifiers in the definition. If ".and" operator is used, definition evaluates to true if and - only if all the specifiers evaluate to true. If ".or" operator is used, definition evalutes to - true if any of the specifiers evaluates to true. If definition contains only one specifier, - it is evaluated as if it was connected with ".true" keyword by ".and" operator. - - If specifier is a ".true" keyword, it always evaluates to true. - - If specifier is a ".false" keyword, it always evaluates to false. Specifier evaluates to false - when it does not evaluate to true. - - Character range specifier is in the form: - '' - '' - If specifier is a character range, it evaluates to true if character in the stream is greater - or equal to and less or equal to . In that situation - the stream pointer is advanced to point to next character in the stream. All C-style escape - sequences are supported although trigraph sequences are not. The comparisions are performed - on 8-bit unsigned integers. - - Character specifier is in the form: - '' - It evaluates to true if the following character range specifier evaluates to true: - '' - '' - - String specifier is in the form: + +The must be on of the symbols in declaration +sequence. The syntax is correct if the root symbol evaluates to +true. A symbol evaluates to true if the definition associated with the +symbol evaluates to true. Definition evaluation depends on the +operator used to connect specifiers in the definition. If ".and" +operator is used, definition evaluates to true if and only if all the +specifiers evaluate to true. If ".or" operator is used, definition +evalutes to true if any of the specifiers evaluates to true. If +definition contains only one specifier, it is evaluated as if it was +connected with ".true" keyword by ".and" operator. + +If specifier is a ".true" keyword, it always evaluates to true. + +If specifier is a ".false" keyword, it always evaluates to +false. Specifier evaluates to false when it does not evaluate to true. + +Character range specifier is in the form: + '' - '' + +If specifier is a character range, it evaluates to true if character +in the stream is greater or equal to and less or +equal to . In that situation the stream pointer is +advanced to point to next character in the stream. All C-style escape +sequences are supported although trigraph sequences are not. The +comparisions are performed on 8-bit unsigned integers. + +Character specifier is in the form: + '' + +It evaluates to true if the following character range specifier evaluates to +true: + '' - '' + +String specifier is in the form: "" - Let N be the number of characters in . Let [i] designate i-th character in - . Then the string specifier evaluates to true if and only if for i in the range [0, N) - the following character specifier evaluates to true: - '[i]' - If [i] is a quotation mark, '[i]' is replaced with '\[i]'. - - Symbol specifier can be optionally preceded by a ".loop" keyword in the form: - .loop (1) + +Let N be the number of characters in . Let [i] +designate i-th character in . Then the string specifier +evaluates to true if and only if for i in the range [0, N) the +following character specifier evaluates to true: + '[i]' + +If [i] is a quotation mark, '[i]' is replaced with +'\[i]'. + +Symbol specifier can be optionally preceded by a ".loop" keyword in the form: + .loop (1) where is defined as follows: ; (2) Construction (1) is replaced by the following code: @@ -202,134 +226,148 @@ typedef byte *production; .and ; ; - ESCAPE SEQUENCES - ---------------- - - Synek supports all escape sequences in character specifiers. The mapping table is listed below. - All occurences of the characters in the first column are replaced with the corresponding - character in the second column. - - Escape sequence Represents - ------------------------------------------------------------------------------------------------ - \a Bell (alert) - \b Backspace - \f Formfeed - \n New line - \r Carriage return - \t Horizontal tab - \v Vertical tab - \' Single quotation mark - \" Double quotation mark - \\ Backslash - \? Literal question mark - \ooo ASCII character in octal notation - \xhhh ASCII character in hexadecimal notation - ------------------------------------------------------------------------------------------------ - - RAISING ERRORS - -------------- - - Any specifier can be followed by a special construction that is executed when the specifier - evaluates to false. The construction is in the form: - .error - is an identifier declared earlier by error text declaration. The declaration is - in the form: - .errtext "" - When specifier evaluates to false and this construction is present, parsing is stopped - immediately and is returned as a result of parsing. The error position is also - returned and it is meant as an offset from the beggining of the stream to the character that - was valid so far. Example: - - (**** syntax script ****) - - .syntax program; - .errtext MISSING_SEMICOLON "missing ';'" - program declaration .and .loop space .and ';' .error MISSING_SEMICOLON .and - .loop space .and '\0'; - declaration "declare" .and .loop space .and identifier; - space ' '; +ESCAPE SEQUENCES +---------------- + +Synek supports all escape sequences in character specifiers. The +mapping table is listed below. All occurences of the characters in +the first column are replaced with the corresponding character in the +second column. + + Escape sequence Represents + ----------------------------------------------------------------------- + \a Bell (alert) + \b Backspace + \f Formfeed + \n New line + \r Carriage return + \t Horizontal tab + \v Vertical tab + \' Single quotation mark + \" Double quotation mark + \\ Backslash + \? Literal question mark + \ooo ASCII character in octal notation + \xhhh ASCII character in hexadecimal notation + ----------------------------------------------------------------------- + + +RAISING ERRORS +-------------- + +Any specifier can be followed by a special construction that is +executed when the specifier evaluates to false. The construction is in +the form: + .error + + is an identifier declared earlier by error text +declaration. The declaration is in the form: + + .errtext "" + +When specifier evaluates to false and this construction is present, +parsing is stopped immediately and is returned as a +result of parsing. The error position is also returned and it is meant +as an offset from the beggining of the stream to the character that +was valid so far. Example: + + (**** syntax script ****) + + .syntax program; + .errtext MISSING_SEMICOLON "missing ';'" + program declaration .and .loop space .and ';' + .error MISSING_SEMICOLON .and + .loop space .and '\0'; + declaration "declare" .and .loop space .and identifier; + space ' '; (**** sample code ****) - - declare foo , - - In the example above checking the sample code will result in error message "missing ';'" and - error position 12. The sample code is not correct. Note the presence of '\0' specifier to - assure that there is no code after semicolon - only spaces. - can optionally contain identifier surrounded by dollar signs $. In such a case, - the identifier and dollar signs are replaced by a string retrieved by invoking symbol with - the identifier name. The starting position is the error position. The lenght of the resulting - string is the position after invoking the symbol. - - PRODUCTION - ---------- - - Synek not only checks the syntax but it can also produce (emit) bytes associated with specifiers - that evaluate to true. That is, every specifier and optional error construction can be followed - by a number of emit constructions that are in the form: - .emit - can be a HEX number, identifier, a star * or a dollar $. HEX number is preceded by - 0x or 0X. If is an identifier, it must be earlier declared by emit code declaration - in the form: + declare foo , + +In the example above checking the sample code will result in error +message "missing ';'" and error position 12. The sample code is not +correct. Note the presence of '\0' specifier to assure that there is +no code after semicolon - only spaces. can optionally +contain identifier surrounded by dollar signs $. In such a case, the +identifier and dollar signs are replaced by a string retrieved by +invoking symbol with the identifier name. The starting position is the +error position. The lenght of the resulting string is the position +after invoking the symbol. + + +PRODUCTION +---------- + +Synek not only checks the syntax but it can also produce (emit) bytes +associated with specifiers that evaluate to true. That is, every +specifier and optional error construction can be followed by a number +of emit constructions that are in the form: + .emit + + can be a HEX number, identifier, a star * or a dollar +$. HEX number is preceded by 0x or 0X. If is an +identifier, it must be earlier declared by emit code declaration in +the form: .emtcode - When given specifier evaluates to true, all emits associated with the specifier are output - in order they were declared. A star means that last-read character should be output instead - of constant value. Example: - - (**** syntax script ****) +When given specifier evaluates to true, all emits associated with the +specifier are output in order they were declared. A star means that +last-read character should be output instead of constant +value. Example: - .syntax foobar; - .emtcode WORD_FOO 0x01 - .emtcode WORD_BAR 0x02 - foobar FOO .emit WORD_FOO .or BAR .emit WORD_BAR .or .true .emit 0x00; - FOO "foo" .and SPACE; - BAR "bar" .and SPACE; - SPACE ' ' .or '\0'; + (**** syntax script ****) - (**** sample text 1 ****) + .syntax foobar; + .emtcode WORD_FOO 0x01 + .emtcode WORD_BAR 0x02 + foobar FOO .emit WORD_FOO .or BAR .emit WORD_BAR .or .true .emit 0x00; + FOO "foo" .and SPACE; + BAR "bar" .and SPACE; + SPACE ' ' .or '\0'; - foo + (**** sample text 1 ****) - (**** sample text 2 ****) + foo - foobar + (**** sample text 2 ****) - For both samples the result will be one-element array. For first sample text it will be - value 1, for second - 0. Note that every text will be accepted because of presence of - .true as an alternative. + foobar - Another example: +For both samples the result will be one-element array. For first +sample text it will be value 1, for second - 0. Note that every text +will be accepted because of presence of .true as an alternative. - (**** syntax script ****) +Another example: - .syntax declaration; - .emtcode VARIABLE 0x01 - declaration "declare" .and .loop space .and - identifier .emit VARIABLE .and (1) - .true .emit 0x00 .and (2) - .loop space .and ';'; - space ' ' .or '\t'; - identifier .loop id_char .emit *; (3) - id_char 'a'-'z' .or 'A'-'Z' .or '_'; + (**** syntax script ****) + .syntax declaration; + .emtcode VARIABLE 0x01 + declaration "declare" .and .loop space .and + identifier .emit VARIABLE .and (1) + .true .emit 0x00 .and (2) + .loop space .and ';'; + space ' ' .or '\t'; + identifier .loop id_char .emit *; (3) + id_char 'a'-'z' .or 'A'-'Z' .or '_'; (**** sample code ****) - - declare fubar; - - In specifier (1) symbol is followed by .emit VARIABLE. If it evaluates to - true, VARIABLE constant and then production of the symbol is output. Specifier (2) is used - to terminate the string with null to signal when the string ends. Specifier (3) outputs - all characters that make declared identifier. The result of sample code will be the - following array: + declare fubar; + +In specifier (1) symbol is followed by .emit VARIABLE. If +it evaluates to true, VARIABLE constant and then production of the +symbol is output. Specifier (2) is used to terminate the string with +null to signal when the string ends. Specifier (3) outputs all +characters that make declared identifier. The result of sample code +will be the following array: { 1, 'f', 'u', 'b', 'a', 'r', 0 } - If .emit is followed by dollar $, it means that current position should be output. Current - position is a 32-bit unsigned integer distance from the very beginning of the parsed string to - first character consumed by the specifier associated with the .emit instruction. Current - position is stored in the output buffer in Little-Endian convention (the lowest byte comes - first). -*/ +If .emit is followed by dollar $, it means that current position +should be output. Current position is a 32-bit unsigned integer +distance from the very beginning of the parsed string to first +character consumed by the specifier associated with the .emit +instruction. Current position is stored in the output buffer in +Little-Endian convention (the lowest byte comes first). */ + /** * This is the text describing the rules to parse the grammar @@ -707,8 +745,8 @@ set_last_error (const byte * msg, byte * param, GLint pos) } /* - memory management routines -*/ + * memory management routines + */ static GLvoid * mem_alloc (GLsizei size) { @@ -741,8 +779,8 @@ str_duplicate (const byte * str) } /* - emit type typedef -*/ + * emit type typedef + */ typedef enum emit_type_ { et_byte, /* explicit number */ @@ -752,8 +790,8 @@ typedef enum emit_type_ emit_type; /* - emit typedef -*/ + * emit typedef + */ typedef struct emit_ { emit_type m_emit_type; @@ -1067,10 +1105,10 @@ barray_append (barray ** ba, barray ** nb) return 0; } -/* - * adds emit chain pointed by em to the end of array pointed by *ba, - * returns 0 on success, - * returns 1 otherwise + +/** + * Adds emit chain pointed by em to the end of array pointed by *ba. + * \return 0 on success, 1 otherwise. */ static GLint barray_push (barray ** ba, emit * em, byte c, GLuint pos) @@ -1117,7 +1155,7 @@ barray_push (barray ** ba, emit * em, byte c, GLuint pos) return 0; } -/* +/** * string to string map typedef */ typedef struct map_str_ @@ -1159,11 +1197,10 @@ map_str_append (map_str ** ma, map_str ** nm) *ma = *nm; } -/* +/** * searches the map for specified key, * if the key is matched, *data is filled with data associated with the key, - * returns 0 if the key is matched, - * returns 1 otherwise + * \return 0 if the key is matched, 1 otherwise */ static GLint map_str_find (map_str ** ma, const byte * key, byte ** data) @@ -1184,7 +1221,7 @@ map_str_find (map_str ** ma, const byte * key, byte ** data) return 1; } -/* +/** * string to byte map typedef */ typedef struct map_byte_ @@ -1224,11 +1261,10 @@ map_byte_append (map_byte ** ma, map_byte ** nm) *ma = *nm; } -/* - * searches the map for specified key, - * if the key is matched, *data is filled with data associated with the key, - * returns 0 if the is matched, - * returns 1 otherwise +/** + * Searches the map for specified key, + * If the key is matched, *data is filled with data associated with the key, + * \return 0 if the is matched, 1 otherwise */ static GLint map_byte_find (map_byte ** ma, const byte * key, byte * data) @@ -1286,11 +1322,10 @@ map_def_append (map_def ** ma, map_def ** nm) *ma = *nm; } -/* +/** * searches the map for specified key, * if the key is matched, *data is filled with data associated with the key, - * returns 0 if the is matched, - * returns 1 otherwise + * \return 0 if the is matched, 1 otherwise */ static GLint map_def_find (map_def ** ma, const byte * key, defntn ** data) -- cgit v1.2.3