bluehelp.xml

charp compiler

            <para>Blue is an entirely managed C# implementation written 
            in C# using the .NET runtime and Frameworks.</para>
            <para>Contact [e-mail] for issues.</para>
            <para>See help on <see cref="T:Blue.Driver"/> for more details on the implementation</para>
            </remarks>
        </member>
        <member name="T:Blue.Driver">
            <summary>
            The <c>Driver</c> class houses the Main() function and 
            controls all other components.
            </summary>
            <remarks>
            The Driver class is the primary client for the interfaces in <see cref="N:Blue.Public"/>.
            It creates the components in the compilation pipeline.
            <list type="bullet">
            <item><see cref="T:Blue.Public.ILexer"/> - convert source to a token stream </item>
            <item><see cref="T:Blue.Public.IParser"/> - convert token stream into AST </item>
            <item><see cref="T:Blue.Public.ISemanticChecker"/> - do symbol resolution on the AST </item>
            <item><see cref="T:Blue.Public.ICodeGenDriver"/> - emit IL for a resolved-AST </item>    
            </list>
            It also creates the utility components:
            <list type="bullet">
            <item><see cref="T:Blue.Public.IOptions"/> - register delegates to handle command line options</item>
            <item><see cref="T:Blue.Public.IError"/> - unified error-reporting system for user-errors</item>
            <item><see cref="T:Blue.Log"/> - logging facility, mostly for debugging </item>
            </list>
            </remarks>
        </member>
        <member name="T:Blue.Log">
            <summary>
            The <c>Log</c> class allows all other subsystems to emit log messages.
            This is mostly a debugging feature.
            </summary>
            <remarks>
            Activated by command line arguments (independent of the IOption system).
            See <see cref="M:Blue.Log.InitLogging(System.String[])"/> for details.
            </remarks>
        </member>
        <member name="M:Blue.Log.InitLogging(System.String[])">
            <summary> Initialize the logging system. </summary>
            <param name="stArgs">The command line arguments.</param>
            <remarks>
            Do a prelim sweep of command line args to set streams.
            We can't use the ErrorHandling subsystem or the Options Subsystem because
            logging is a more fundamental subsystem that the others depend on.
            <para>Activate via:
            '-l:XXXXX' where XXXXX is {Codegen, Verbose, Parser, Resolve }
            Can specify multiple switches</para>
            </remarks>
        </member>
        <member name="T:Blue.Log.LF">
            <summary> Control what gets logged. </summary>
            <remarks>
            Each member get log to is own <see cref="T:System.IO.TextWriter"/>.
            The buffer may go to the console, a file, or nothing.
            </remarks>
        </member>
        <member name="F:Blue.Log.LF.Verbose">
            <summary>Verbose information of use to an end-user.</summary>
        </member>
        <member name="F:Blue.Log.LF.Parser">
            <summary> Information from the parser </summary>
        </member>
        <member name="F:Blue.Log.LF.Resolve">
            <summary> Information during resolution </summary>
        </member>
        <member name="F:Blue.Log.LF.CodeGen">
            <summary> Information during codegen </summary>
        </member>
        <member name="F:Blue.Log.LF.All">
            <summary> All information </summary>
        </member>
        <member name="T:Blue.Public.ILexer">
            <summary>
            Interface provided by a lexer. This interface provides 1 token 
            of lookahead (via peek).
            </summary>
            <remarks>
            Used by an <see cref="T:Blue.Public.IParser"/> to convert the entire  
            text-based input into a token stream. 
            <para> The lexer handles EOF by returning the EOF token.
            The lexer handles normal errors by returning the Error token, and
            all subsequent calls will return EOF. </para>
            <para> All preprocessor directives are handled behind the ILexer interface.</para>
            <para> The primary implementation is <see cref="T:ManualParser.Lexer"/></para>
            </remarks>
        </member>
        <member name="M:Blue.Public.ILexer.GetNextToken">
            <summary>
            Consume the next token in the stream and return it
            </summary>        
        </member>
        <member name="M:Blue.Public.ILexer.PeekNextToken">
            <summary>
            Peek at the next token in the stream, but don't consume it (non-invasive)    
            </summary>                
        </member>
        <member name="T:Blue.Public.IParser">
            <summary>
            The parser is responsible for providing the compiler with an AST to compile.    
            </summary>
            <remarks>
            The parser has no specific knowledge of the filesystem or locating source files.
            The primary implemenation of the IParser interface is <see cref="T:ManualParser.Parser"/>
            which uses an <see cref="T:Blue.Public.ILexer"/> to parse a token stream into an AST. 
            However, not all parser implementations would require a lexer. For example,
            a parser could be implemented to read in from XML.
            </remarks>
        </member>
        <member name="M:Blue.Public.IParser.ParseSourceFile">
            <summary>
            Parse a single source file and return a namespace.
            </summary>
            <remarks>
            The driver must package all NamespaceDecl nodes into a single <see cref="T:AST.ProgramDecl"/>
            which can then be resolved (using <see cref="T:Blue.Public.ISemanticChecker"/>) and
            codegened (using <see cref="T:Blue.Public.ICodeGenDriver"/>)
            </remarks>
        </member>
        <member name="T:Blue.Public.ISemanticChecker">
            <summary>
            This is the interface the Driver uses to kick off semantic checks.
            </summary>
        </member>
        <member name="T:Blue.Public.OptionHandler">
            <summary>
            An OptionHandler delegate gets invoked by the option subsystem when it
            parses the command line parameters.
            </summary>
            <remarks>
            Handlers are registered by calling <see cref="M:Blue.Public.IOptions.AddHandler(System.String,System.String,Blue.Public.OptionHandler,System.String,System.String)"/>.
            The <paramref name="stOptionParams"/> is the parameter from the command line.
            </remarks>
        </member>
        <member name="T:Blue.Public.IOptions">
            <summary>
            Subsystems use the IOption interface to add delegates to handle the 
            different command line switches.
            </summary>
        </member>
        <member name="M:Blue.Public.IOptions.AddHandler(System.String,System.String,Blue.Public.OptionHandler,System.String,System.String)">
            <summary>
            Add a handler for a command line option.
            </summary>
            <param name="stOption">The long name of the option.</param>
            <param name="stShortcut">A shortcut name for the option.</param>
            <param name="ha">A <see cref="T:Blue.Public.OptionHandler"/> delegate to be invoked to handle this option</param>
            <param name="stDescription">A short 1-line, description of this option.</param>
            <param name="stFullHelp">A full description of the option including examples and details.</param>
        </member>
        <member name="T:Blue.Public.IError">
            <summary>
            The IError interface provides all subsytems with a unified ability to
            report errors resulting from bad user-input (not internal compiler bugs).
            </summary>
            <remarks>
            The IError interface is exposed to all components because anyone can
            produce an error. 
            <para> IError is built around the <see cref="T:ErrorException"/>
            The rationale is that it is an implementation detail whether an error should
            be thrown or just printed. By making everything an exception, clients of IError
            can easily switch between Print and Throw as their implementaiton changes. </para>
            </remarks>
        </member>
        <member name="M:Blue.Public.IError.PrintError(ErrorException)">
            <summary>
            Print an error.
            </summary>
            <remarks>
            *Every* single user-error comes through here.
            This does not include internal errors and exceptions (such as File-not-found).
            However, if those exceptions impact the user, then they are converted to a
            ErrorException and then they come through here.
            </remarks>
            <param name="e">The error.</param>
        </member>
        <member name="M:Blue.Public.IError.PrintWarning(ErrorException)">
            <summary> 
            Print a warning.   
            </summary>
            <remarks>
            The cousin to PrintError.
            *Every* single user-warning comes through here.        
            Note that there is no ThrowWarning because a warning, by nature,
            should only be informative and not require a change in flow-control.
            </remarks>
            <param name="e">The error.</param>
        </member>
        <member name="M:Blue.Public.IError.ThrowError(ErrorException)">
            <summary>
            call <see cref="M:Blue.Public.IError.PrintError(ErrorException)"/> and then throw the exception.
            </summary>
            <remarks>
            ThrowError is a convenience function. Many times a user error is an 
            exceptional case that requires major control flow. We use exception
            handling for that. This lets us avoid having to check for error cases 
            all over the place.    
            </remarks>    
            <param name="e">The error.</param>
        </member>
        <member name="M:Blue.Public.IError.HasErrors">
            <summary>
            This can be used by the Driver to change control flow in response to errors.
            </summary>
            <remarks>
            Note that this is a check of errors since startup, not errors since last called.