Imported from /srv/lorry/lorry-area/swig-tarball/swig-1.3.40.tar.gz.HEADswig-1.3.40master

1 files changed, 288 insertions, 0 deletions

diff --git a/Doc/Devel/scanner.html b/Doc/Devel/scanner.html
new file mode 100644
index 0000000..2722164
--- /dev/null
+++ b/Doc/Devel/scanner.html
@@ -0,0 +1,288 @@
+<html>
+<head>
+<title>SWIG C Scanner</title>
+</head>
+
+<body>
+<center>
+<h1>SWIG C/C++ Scanning</h1>
+
+<p>
+David M. Beazley <br>
+dave-swig@dabeaz.com<br>
+January 11, 2007<br>
+
+</b>
+</center>
+
+<h2>Introduction</h2>
+
+This document describes functions that can be used to tokenize C/C++
+input text.  These functions are relatively low-level and are meant to
+be used in the implementation of scanners that can be plugged into yacc or used for
+other purposes.  For instance, the preprocessor uses these functions to evaluate and test 
+constant expressions.  
+
+<p>
+All of these functions are declared in <tt>Source/Swig/swigscan.h</tt>.   This API is considered to be stable.
+
+<h2>Creation and Deletion of Scanners</h2>
+
+The following functions are used to create and destroy a scanner object.  More than one scanner object can be created and used
+as necessary.
+
+<p>
+<b><tt>Scanner *NewScanner()</tt></b>
+
+<blockquote>
+Creates a new scanner object.  The scanner contains initially contains no text.  To feed text to the scanner use <tt>Scanner_push()</tt>.
+</blockquote>
+
+<p>
+<b><tt>Scanner *DelScanner()</tt></b>
+
+<blockquote>
+Deletes a scanner object. 
+</blockquote>
+
+<h2>Scanner Functions</h2>
+
+<p>
+<b><tt>void Scanner_clear(Scanner *s)</tt></b>
+<blockquote>
+Clears all text from the scanner.  This can be used to reset a scanner to its initial state, ready to receive new input text.
+</blockquote>
+
+<p>
+<b><tt>void Scanner_push(Scanner *s, String *text)</tt></b>
+<blockquote>
+Pushes an input string into the scanner. Subsequent tokens will be
+returned from the new string.  If the scanner is already processing a
+string, the pushed string takes precedence--in effect, interrupting
+the scanning of the previous string.  This behavior is used to
+implement certain SWIG features such as the <tt>%inline</tt>
+directive. Once the pushed string has been completely scanned, the
+scanner will return to scanning the previous string (if any).  The
+scanning of text relies upon the DOH file interface to strings
+(<tt>Getc()</tt>, <tt>Ungetc()</tt>, etc.).  Prior to calling this
+function, the input string should be set so that its file pointer is
+in the location where you want scanning to begin. You may have to
+use <tt>Seek()</tt> to set the file pointer back to the beginning of a
+string prior to using this function.
+</blockquote>
+
+<p>
+<b><tt>void Scanner_pushtoken(Scanner *s, int tokvalue, String_or_char *val)</tt></b>
+<blockquote>
+Pushes a token into the scanner.  This exact token will be returned by the next call to <tt>Scanner_token()</tt>.  
+<tt>tokvalue</tt> is the integer token value to return and <tt>val</tt> is the token text to return.   This
+function is only used to handle very special parsing cases. For instance, if you need the scanner to
+return a ficticious token into order to enter a special parsing case.
+</blockquote>
+
+<p>
+<b><tt>int Scanner_token(Scanner *s)</tt></b>
+
+<blockquote>
+Returns the next token.  An integer token code is returned (see table below) on success.  If no more input text is
+available 0 is returned.  If a scanning error occurred, -1 is returned.  In this case, error information can be
+obtained using <tt>Scanner_errinfo()</tt>.
+</blockquote>
+
+<p>
+<b><tt>String *Scanner_text(Scanner *s)</tt></b>
+<blockquote>
+Returns the scanned text corresponding to the last token returned by <tt>Scanner_token()</tt>.   The returned string
+is only valid until the next call to <tt>Scanner_token()</tt>. If you need to save it, make a copy.
+</blockquote>
+
+<p>
+<b><tt>void Scanner_skip_line(Scanner *s)</tt></b>
+<blockquote>
+Skips to the end of the current line.   The text skipped can be obtained using <tt>Scanner_text()</tt> afterwards.
+</blockquote>
+
+<p>
+<b><tt>void Scanner_skip_balanced(Scanner *s, int startchar, int endchar)</tt></b>
+<blockquote>
+Skips to the end of a block of text denoted by starting and ending characters.  For example, <tt>{</tt> and <tt>}</tt>.  The
+function is smart about how it skips text.  String literals and comments are ignored.   The function also is aware of nesting.  The
+skipped text can be obtained using <tt>Scanner_text()</tt> afterwards. Returns 0 on success, -1 if no matching <tt>endchar</tt> could be found.
+</blockquote>
+
+
+<p>
+<b><tt>void Scanner_set_location(Scanner *s, int startchar, int endchar)</tt></b>
+<blockquote>
+Changes the current filename and line number of the scanner.
+</blockquote>
+
+<p>
+<b><tt>String *Scanner_file(Scanner *s)</tt></b>
+<blockquote>
+Gets the current filename associated with text in the scanner.
+</blockquote>
+
+<p>
+<b><tt>int Scanner_line(Scanner *s)</tt></b>
+<blockquote>
+Gets the current line number associated with text in the scanner.
+</blockquote>
+
+<p>
+<b><tt>int Scanner_start_line(Scanner *s)</tt></b>
+<blockquote>
+Gets the starting line number of the last token returned by the scanner.
+</blockquote>
+
+<p>
+<b><tt>void Scanner_idstart(Scanner *s, char *idchar)</tt></b>
+<blockquote>
+Sets additional characters (other than the C default) that may be used to start C identifiers.  <tt>idchar</tt> is a string
+containing the characters (e.g., "%@").  The purpose of this function is to up special keywords such as "%module" or "@directive" as
+simple identifiers.
+</blockquote>
+
+<p>
+<b><tt>String *Scanner_errmsg(Scanner *s)</tt></b>
+<blockquote>
+Returns the error message associated with the last scanner error (if any).   This will only return a meaningful result
+if <tt>Scanner_token()</tt> returned -1.
+</blockquote>
+
+<p>
+<b><tt>int Scanner_errline(Scanner *s)</tt></b>
+<blockquote>
+Returns the line number associated with the last scanner error (if any).   This will only return a meaningful result
+if <tt>Scanner_token()</tt> returned -1.  The line number usually corresponds to the starting line number of a particular
+token (e.g., for unterminated strings, comments, etc.).
+</blockquote>
+
+<p>
+<b><tt>int Scanner_isoperator(int tokval)</tt></b>
+<blockquote>
+A convenience function that returns 0 or 1 depending on whether <tt>tokval</tt> is a valid C/C++ operator (i.e., a candidate for
+operator overloading).  
+</blockquote>
+
+<p>
+<b><tt>void Scanner_freeze_line(int val)</tt></b>
+<blockquote>
+Freezes the current line number depending upon whether or not <tt>val</tt> is 1 or 0.  When the line number is frozen, newline characters will not result in 
+updates to the line number.  This is sometimes useful in tracking line numbers through complicated macro expansions.
+</blockquote>
+
+
+<h2>Token Codes</h2>
+
+The following table shows token codes returned by the scanner.  These are integer codes returned by
+the <tt>Scanner_token()</tt> function.
+
+<blockquote>
+<pre>
+Token code                   C Token
+-------------------------    -------------
+SWIG_TOKEN_LPAREN            (
+SWIG_TOKEN_RPAREN            )
+SWIG_TOKEN_SEMI              ; 
+SWIG_TOKEN_COMMA             , 
+SWIG_TOKEN_STAR              * 
+SWIG_TOKEN_TIMES             *
+SWIG_TOKEN_LBRACE            { 
+SWIG_TOKEN_RBRACE            } 
+SWIG_TOKEN_EQUAL             = 
+SWIG_TOKEN_EQUALTO           == 
+SWIG_TOKEN_NOTEQUAL          != 
+SWIG_TOKEN_PLUS              + 
+SWIG_TOKEN_MINUS             - 
+SWIG_TOKEN_AND               &amp; 
+SWIG_TOKEN_LAND              &amp;&amp; 
+SWIG_TOKEN_OR                | 
+SWIG_TOKEN_LOR               || 
+SWIG_TOKEN_XOR               ^ 
+SWIG_TOKEN_LESSTHAN          &lt; 
+SWIG_TOKEN_GREATERTHAN       &gt; 
+SWIG_TOKEN_LTEQUAL           &lt;= 
+SWIG_TOKEN_GTEQUAL           &gt;= 
+SWIG_TOKEN_NOT               ~ 
+SWIG_TOKEN_LNOT              ! 
+SWIG_TOKEN_LBRACKET          [ 
+SWIG_TOKEN_RBRACKET          ] 
+SWIG_TOKEN_SLASH             / 
+SWIG_TOKEN_DIVIDE            /
+SWIG_TOKEN_BACKSLASH         \ 
+SWIG_TOKEN_POUND             # 
+SWIG_TOKEN_PERCENT           % 
+SWIG_TOKEN_MODULO            %
+SWIG_TOKEN_COLON             : 
+SWIG_TOKEN_DCOLON            :: 
+SWIG_TOKEN_DCOLONSTAR        ::*
+SWIG_TOKEN_LSHIFT            &lt;&lt; 
+SWIG_TOKEN_RSHIFT            &gt;&gt; 
+SWIG_TOKEN_QUESTION          ? 
+SWIG_TOKEN_PLUSPLUS          ++ 
+SWIG_TOKEN_MINUSMINUS        -- 
+SWIG_TOKEN_PLUSEQUAL         += 
+SWIG_TOKEN_MINUSEQUAL        -= 
+SWIG_TOKEN_TIMESEQUAL        *= 
+SWIG_TOKEN_DIVEQUAL          /= 
+SWIG_TOKEN_ANDEQUAL          &amp;= 
+SWIG_TOKEN_OREQUAL           |= 
+SWIG_TOKEN_XOREQUAL          ^= 
+SWIG_TOKEN_LSEQUAL           &lt;&lt;= 
+SWIG_TOKEN_RSEQUAL           &gt;&gt;= 
+SWIG_TOKEN_MODEQUAL          %= 
+SWIG_TOKEN_ARROW             -&gt; 
+SWIG_TOKEN_ARROWSTAR         -&gt;* 
+SWIG_TOKEN_PERIOD            . 
+SWIG_TOKEN_AT                @ 
+SWIG_TOKEN_DOLLAR            $ 
+SWIG_TOKEN_ENDLINE           Literal newline
+SWIG_TOKEN_ID                identifer 
+SWIG_TOKEN_FLOAT             Floating point with F suffix (e.g., 3.1415F)
+SWIG_TOKEN_DOUBLE            Floating point (e.g., 3.1415 )
+SWIG_TOKEN_INT               Integer (e.g., 314)
+SWIG_TOKEN_UINT              Unsigned integer (e.g., 314U)
+SWIG_TOKEN_LONG              Long integer (e.g., 314L) 
+SWIG_TOKEN_ULONG             Unsigned long integer (e.g., 314UL)
+SWIG_TOKEN_LONGLONG          Long long integer (e.g., 314LL )
+SWIG_TOKEN_ULONGLONG         Unsigned long long integer (e.g., 314ULL) 
+SWIG_TOKEN_CHAR              Character literal in single quotes ('c')
+SWIG_TOKEN_STRING            String literal in double quotes ("str")
+SWIG_TOKEN_RSTRING           Reverse quote string (`str`)
+SWIG_TOKEN_CODEBLOCK         SWIG code literal block %{ ... %}
+SWIG_TOKEN_COMMENT           C or C++ comment  (// or /* ... */)
+SWIG_TOKEN_ILLEGAL           Illegal character
+</pre>
+</blockquote>
+
+<b>Notes</b>
+
+<ul>
+<li>When more than one token code exist for the same token text, those codes are identical (e.g., <tt>SWIG_TOKEN_STAR</tt> and <tt>SWIG_TOKEN_TIMES</tt>).
+
+<p>
+<li>
+String literals are returned in their exact representation in which escape codes (if any) have been interpreted.
+
+<p>
+<li>
+All C identifiers and keywords are simply returned as <tt>SWIG_TOKEN_ID</tt>.  To check for specific keywords, you will need to
+add extra checking on the returned text.
+
+<p>
+<li>C and C++ comments include the comment starting and ending text (e.g., "//", "/*").
+
+<p>
+<li>The maximum token integer value is found in the constant <tt>SWIG_MAXTOKENS</tt>.   This can be used if you wanted to create 
+an array or table for the purposes of remapping tokens to a different set of codes. For instance, if you are
+using these functions to write a yacc-compatible lexer.
+</ul>
+
+</body>
+</html>
+
+
+
+
+