datatype compilerParameters

The compilerParameters datatype is used to construct a list of options for the PolyML.compiler function. These options control various aspects of the compilation. The options are arranged so that only those options that are actually required need to be included. If the option is not included in the list the compiler uses a default value. In each case the default value is listed.

CPOutStream of string->unit

Provide an output stream for output from the compiler. It is also used for printing the results unless CPPrintStream is provided. Default use TextIO.print to print to TextIO.stdOut.

CPNameSpace of PolyML.NameSpace.nameSpace

Name space to look up and enter results. Identifiers not defined locally within the code are looked up in this name space. When the compiled code is executed the results are added to this name space by calling the appropriate enter function. Default: PolyML.globalNameSpace

CPErrorMessageProc of
       { message: PolyML.pretty, hard: bool, location: PolyML.location, context: PolyML.pretty option } -> unit

Called by the compiler to generate error and warning messages. message is the message as a pretty-print data structure. isHard indicates whether this is a fatal error or a warning; it is true if this is an error, false if a warning. location is the file-name, line number and position. context is an optional extra piece of information showing the part of the parse tree where the error was detected if that is appropriate. Default: print a message to the stream provided by th CPOutStream option or TextIO.stdOut if that is not provided.

CPLineNo of unit -> int
  CPLineOffset of unit -> int
  CPFileName of string

CPLineNo, CPLineOffset and CPFileName can be used to provide information that go to form values of the location type. These values appear in many different situations when the compiler is reporting information; examples include error messages, the debugger and parse-trees. The compiler itself makes no interpretation of the values, simply recording the information and associating it with the start and end of lexical and parsed items. This allows user code that calls compiler to make its own interpretation. However, various ML functions, such as use and make and the interactive debugger, assume that CPFileName is the name of the source file and CPLineNo the number of the line. CPFileName is fixed for a particular call to compiler whereas the compiler calls CPLineNo and CPLineOffset for each lexical item. The default values are the empty string for CPFileName and functions that return zero for CPLineNo and CPLineOffset.

CPPrintInAlphabeticalOrder of bool

This controls whether the default result function should sort the results by alphabetical order before printing them. If an alternative result function has been set using CPResultFun or CPCompilerResultFun this option is ignored. Default: value of printInAlphabeticalOrder.

CPResultFun of {
            fixes: (string * fixityVal) list, values: (string * valueVal) list,
            structures: (string * structureVal) list, signatures: (string * signatureVal) list,
            functors: (string * functorVal) list, types: (string * typeVal) list} -> unit

Provides a function to be included in the resulting code of the compiler to apply to the results of bindings. It is only called when the top-level code has been executed and has not raised an exception. Default: print and enter the values into the name-space provided by CPNameSpace or PolyML.globalNameSpace.

CPCompilerResultFun of
            PolyML.parseTree option *
            ( unit -> {
                fixes: (string * fixityVal) list, values: (string * valueVal) list,
                structures: (string * structureVal) list, signatures: (string * signatureVal) list,
                functors: (string * functorVal) list, types: (string * typeVal) list}) option -> unit -> unit

Function to process the result of compilation. This can be used to capture the parse tree even if type-checking fails. Default: Execute the code and call the result function if the compilation succeeds. Raise an exception if the compilation failed.

CPProfiling of int

This is no longer used.

CPTiming of bool

This is no longer used.

CPDebug of bool

Control whether calls to the debugger should be inserted into the compiled code. This allows breakpoints to be set, values to be examined and printed
and functions to be traced at the cost of a significant run-time overhead. Default: value of debug.

CPPrintDepth of unit->int

This controls the depth of printing if the default CPResultFun is used. It is also bound into any use of PolyML.print in the compiled code and will
be called to get the print depth whenever that code is executed. Default: Get the current value of printDepth i.e. the value set by PolyML.print_depth.

CPPrintStream of string->unit

This is bound into any occurrence of PolyML.print and is used to produce the outut. Default: the value of CPOutStream or TextIO.print if it is not provided.

CPErrorDepth of int

Controls the depth of context to produce in error messages. Default : Get the current value of errorDepth i.e. the value set by PolyML.error_depth.

CPLineLength of int

Bound into any occurrences of PolyML.print. This is the length of a line used in the pretty printer. Default: Get the current value of lineLength i.e. the value set by PolyML.line_length.

CPRootTree of
        {
            parent: (unit -> PolyML.parseTree) option,
            next: (unit -> PolyML.parseTree) option,
            previous: (unit -> PolyML.parseTree) option
        }

This can be used to provide a parent for parse trees created by the compiler. This appears as a PTparent property in the tree. The default is NONE which does not to provide a parent.

CPAllocationProfiling of int

Controls whether to add profiling information to each allocation. Currently zero means no profiling and one means add the allocating function.

CPDebuggerFunction of int * valueVal * int * string * string * nameSpace -> unit

This is no longer used and is just left for backwards compatibility.

val printDepth : int ref

printDepth controls the depth of output to produce when printing output either in the result or in PolyML.print. Its value is also set by PolyML.print_depth.

val errorDepth : int ref

errorDepth controls the depth of output to produce when printing error messages. Its value is also set by PolyML.error_depth.

val lineLength : int ref

lineLength controls the length of a line when printing output either in the result or in PolyML.print. Its value is also set by PolyML.line_length.

val parsetree: bool ref
val codetree: bool ref
val codetreeAfterOpt: bool ref
val assemblyCode: bool ref
val pstackTrace: bool ref

These switches control whether the compiler should produce debugging output. The default is false for each. parsetree controls printing of the parsed ML source, codetree controls printing of the intermediate code, codetreeAfterOpt controls printing that code after the optimiser, assemblyCode controls printing the low-level machine code and pstackTrace the printing of the low-level pseudo-stack.

val compilerVersion: string
val compilerVersionNumber: int

compilerVersion and compilerVersionNumber contain information about the version of the compiler. For version 5.5.2 these contain "5.5.2 Release" and 552 respectively.

val prompt1: string ref
val prompt2: string ref

prompt1 and prompt2 contain the prompts for input used by the default Poly/ML top-level read-eval-print loop, PolyML.shell. prompt1 contains "> " and prompt2 contains "# " by default. They are included in the Compiler structure for historical reasons.

val reportExhaustiveHandlers: bool ref

The Poly/ML compiler produce a warning message if it is given a pattern match sequence which is not exhaustive, that is there are values that are not matched by any of the patterns. This warning message is not produced in the case of a handler where unhandled values are simply reraised.

There are circumstances where it is important that certain exceptions must not be caught, or if they are caught the handler must be reraise them in order to ensure that they return control to the outer level. This reference controls whether the compiler should produce a warning if an exception handler matches all exceptions rather than only specific exceptions. It may also be helpful to check for the situation where an exception handler is intended to match a single exception but because the exception identifier has been mistyped it is treated as a variable matching all exceptions. It defaults to false.

val reportUnreferencedIds: bool ref

This reference controls whether the compiler should produce a warning for identifiers that are declared but never used. Currently it is restricted to value bindings. It defaults to false.

val reportDiscardFunction: bool ref
val reportDiscardNonUnit: bool ref

These references control whether the compiler should produce a warning if a value is discarded. In an expression sequence or a let-binding only the value of the last expression is returned and the values of expressions followed by semicolons are discarded. Typically they are evaluated for their side-effects and return unit. reportDiscardFunction, default true, produces a warning message if the value being discarded has a function type but not otherwise. reportDiscardNonUnit, default false, produces a warning unless the discarded value has unit type.

val printInAlphabeticalOrder: bool ref

This reference controls whether the default result function for the compiler should sort the bindings being produced into alphabetical order. It provides the default value if the CPPrintInAlphabeticalOrder is not provided. It defaults to true.

val lowlevelOptimise: bool ref

This reference controls whether the compiler should perform low-level optimisations. This defaults to true and should not normally need to be changed.

val inlineFunctors: bool ref

This reference controls whether the compiler should treat ML functors as inline functions. All type checking is performed when the functor is declared but code-generation is deferred until the functor is applied to its argument structures. This defaults to true and should not normally need to be changed.

val createPrintFunctions: bool ref

This reference controls whether the compiler should generate default print functions for datatypes. This defaults to true.

val maxInlineSize: int ref

This reference controls how the compiler chooses to implement functions. If a function is small it is treated as an inline function and its code is expanded wherever it is used. If it is large it is compiled into a separate function and a call is made to it when it is used. Certain functions, such as recursive functions that are not tail-recursive or functions that are being passed as arguments or returned as results, cannot be treated as inline. The value represents the maximum size of a small function in some notional size units. It defaults to 80. Increasing the value will make the compiler treat more functions as inline.

val narrowOverloadFlexRecord: bool ref

This reference controls the way the Poly/ML compiler treats flexible records, i.e. record patterns containing "...", and overloading. The ML Definition says that these are resolved by the context but does not define exactly what that context should be, allowing different compilers to interpret this differently. With this reference set to false, the default, the Poly/ML compiler uses the whole of the topdec as the context to find a suitable fixed record type or to find the type of an overloaded function. When it is set to true the compiler uses the immediate val or fun binding as the context. The effect of this is that it may produce an error message unless appropriate type constraints have been included. However, that may ensure that the code is portable to compilers which take a more restrictive view than Poly/ML.

val traceCompiler: bool ref

This reference controls whether the compiler should produce an exception trace if an exception occurs within the compiler. This defaults to false.

val fixityNames : unit -> string list
val functorNames : unit -> string list
val signatureNames: unit -> string list
val structureNames: unit -> string list
val typeNames: unit -> string list
val valueNames: unit -> string list

These functions return the appropriate list from PolyML.globalNameSpace. They can all be written in terms of functions in the NameSpace structure and are included in the Compiler structure for backwards compatibility only.

val forgetFixity: string -> unit
val forgetFunctor: string -> unit
val forgetSignature: string -> unit
val forgetStructure: string -> unit
val forgetType: string -> unit
val forgetValue: string -> unit

These functions delete entries from PolyML.globalNameSpace. They are included in the Compiler structure for historical reasons.

val debug: bool ref

This reference controls whether debugging information is included in the compiled code. The value of this reference is used unless the CPDebug option is provided. Setting this to true increases the run-time by many factors.

val timing: bool ref

Setting this reference to true causes the compiler to include timing information in the output after each topdec. The timing information includes information about various passes of the compiler and also the execution time of the topdec. Its value is also set by the PolyML.timing function.