Modules index

# CEI

This is the Compiler External Interface module which is the recommended way for the user to interact with the Converge compiler. This module necessarily contains a diverse range of functionality.

### Error reporting

`func error(msg, src_infos := null):` Reports the error in `msg` to the user, pinpointing it as occurring at `src_infos` positions if that is non-null. Once the error is reported, compilation stops, and an error code is returned.

`func warning(msg, src_infos := null):` Reports the warning in `msg` to the user, pinpointing it as occurring at `src_infos` positions if that is non-null. Once the error is reported, compilation continues as normal.

### Eval

`func eval(expr, vars := Dict{}, includes := []):` Dynamically evaluates the expression specified in the string `expr`, returning its result (which may be to fail). The expression is evaluated in the context of variables defined in the dictionary `vars`; the values in this dictionary are updated after `expr's` evaluation to reflect any assignments to them during evaluation. `includes` specifies a list of module objects to be made available as imports to `expr`.

For example the following call to `eval`:

    vars := Dict{"x" : 2}
    rtn := CEI::eval("y := (x += 1) + 4", vars)
    Sys::println(rtn, ": ", vars)

will result in the following output:

    7: Dict{"x" : 3, "y" : 7}

### Generic compile-time meta-programming functions

`func fresh_name(name := null):` Returns the name of a guaranteed fresh variable name (i.e. a variable name which won't clash with another variable name). If `name` is non-`null`, then it should be a string, the contents of which will form part of the fresh variable name.

`func lift(obj, src_infos := null):` Lifts an object into its ITree equivalent i.e. turns a string into an IString, an int into a IInt etc. Container types such as lists are recursively converted into their ITree equivalent.

### ITree functions

#### Hygiene

`func rename_itree(itree, vars := null):` Returns a version of `itree` where all externally visible free / bound variables which are mentioned in the keys of `vars` are renamed to the corresponding value. If `vars` is null, then all externally visible free / bound variables are renamed to fresh names.

`func embeddable_itree(itree, except_vars := Set{}):` This function is intended to be used on external ITrees which one wishes to embed in an AST being constructed. The external AST may have dynamically scoped references to variables which the AST it is embedded into should not interfere with. Thus this function renames all externally visible free / bound variables other than those in `except_vars` to fresh names. It then returns a list of IRename instances which can be easily inserted into a `rename` declaration.

#### Pretty printing

`func pp_itree(itree):` Returns a string representing the pretty-printed ITree `itree`.

`func elided_pp_itree(itree, self_mod_id := null):` Returns an elided string representing the pretty-printed ITree `itree`. This function will try to elide extraneous, cluttering, details from the pretty-printed ITree, but in so doing can return misleading and incorrect representations. Chiefly it tries to pretty print module lookups in a human readable fashion; if `self_mod_id` is non-`null` any module lookup within a module of that Id will be elided still further. Both these mechanisms can cause problems in certain situations. It is recommended that users always use `pp_itree` initially, falling back on this elided representation only when the output from the former is untelligible.

#### ITree definitions and expressions

`func imodule(module_name, defns, src_infos):`

`func iclass_def(class_name, supers, metaclass_, fields, src_infos):` Returns an IClass_Def whose: name is the string `class_name`; superclasses are defined by the list of IExpr's `supers`; metaclass is specified by the IExpr `metaclass_`, or `null` if there is no metaclass; fields are specified by the list of IAssignment's or IFunc_Def's `fields`.

`func ifunc_def(is_bound, func_name, params, var_arg, nonlocals, renames, body, src_infos):` Returns an IFunc_Def which is a bound function if `is_bound` is `1` and unbound if it is `0` (other values of `is_bound` lead to undefined behaviour). The resulting IFunc_Def has: name is the string `func_name` (which can be the empty string if the function is anonymous); parameters are defined by the list of IParam's `params`; var arg is defined by the IVar `var_arg`, or null if no var arg is specified; nonlocals are defined by the list of IVar's `nonlocals`; renames are defined by the list of `[<emph>from</emph>, <emph>to</emph>]` pairs in `renames`; body is defined by the IExpr_Seq `body`.

`func iif(clauses, else_body, src_infos):` Returns an IIf whose: main clauses are defined by the list of IClause's `clauses`; else branch is defined by the IExpr_Seq `else_body`, or null if there is no else branch.

`func indif(clauses, src_infos):` Returns an INDIf whose main clauses are defined by the list of IClause's `clauses`.

`func ivar(name, src_infos):` Returns an IVar whose name is defined by the string `name`.

`func iimport(mod_path, var_name, src_infos):` Returns an IImport which imports the module referenced by `mod_path` to the variable whose name is defined by the string `var_name`.

`func iwhile(condition, body, exhausted_body, broken_body, src_infos):` Returns an IWhile whose: condition is defined by the IExpr `condition`; main body is defined by the IExpr_Seq `body`; exhausted body is defined by the IExpr_Seq `exhausted_body`, or `null` if no exhausted body is specified; broken body is defined by the IExpr_Seq `broken_body`, or `null` if no broken body is specified.

`func ifor(condition, body, exhausted_body, broken_body, src_infos):` Returns an IFor whose: condition is defined by the IExpr `condition`; main body is defined by the IExpr_Seq `body`; exhausted body is defined by the IExpr_Seq `exhausted_body`, or `null` if no exhausted body is specified; broken body is defined by the IExpr_Seq `broken_body`, or `null` if no broken body is specified.

`func iint(val, src_infos):` Returns an IInt whose value is that of the integer `val`.

`func istring(val, src_infos):` Returns an IString whose value is that of the string `val`.

`func islot_lookup(target, slot_name, src_infos):` Returns an ISlot_Lookup which looks up the slot defined in the string `slot_name` in the IExpr defined in `target`.

`func imodule_lookup(target, def_name, src_infos):` Returns an IModule_Lookup which looks up the slot defined in the string `slot_name` in the IExpr defined in `target`.

`func ilist(elems, src_infos):` Returns an IList whose elements are the list of IExpr's in `elems`.

`func idict(elems, src_infos):` Returns an IDict whose elements are specified in the list of IDict_Elems `elems`.

`func iset(elems, src_infos):` Returns an ISet whose elements are the list of IExpr's in `elems`.

`func iapplication(target, args, src_infos):` Returns an IApplication of the list of IExpr `args` to the function specified in the IExpr `target`.

`func iget(target, index, src_infos):` Returns an IGet (i.e. `<emph>target</emph>[<emph>index</emph>]`) which looks up the index element specified by the IExpr `index` in the object specified by the IExpr `target`.

`func islice(target, lower_bound, upper_bound, src_infos):` Returns an ISlice (i.e. `<emph>target</emph>[<emph>index</emph>]`) which looks up the index element specified by the IExpr `index` in the object specified by the IExpr `target`.

`func iexbi(target, field_name, src_infos):` Returns an IEXBI which looks up the field specified by the string `field_name` in the IExpr `target`.

`func ireturn(expr, src_infos):` Returns an IReturn which returns the value of the IExpr `expr`, which may be `null` if the default return value is to be returned.

`func iyield(expr, src_infos):` Returns an IYield which returns the value of the IExpr `expr`.

`func ifail(src_infos):` Returns an IFail which both returns the current function and transmits failure to the functions caller.

`func iraise(expr, src_infos):` Returns an IRaise which raises the expression specified by the IExpr `expr`.

`func iassert(expr, src_infos):` Returns an IAssert which checks the assertion in the expression specified by the IExpr `expr`.

`func ibreak(src_infos):` Returns an IBreak.

`func icontinue(src_infos):` Returns an IContinue.

`func iconjunction(exprs, src_infos):` Returns an IConjunction of the list of IExpr's in `exprs`.

`func ialternation(exprs, src_infos):` Returns an IAlternation of the list of IExpr's in `exprs`.

`func iassignment(type, targets, expr, src_infos):` Returns an IAssignment whose: `type` must be one of `STD_ASSIGN`, `ADD_ASSIGN`, `SUB_ASSIGN`, `MUL_ASSIGN`, or `DIV_ASSIGN`; targets are defined by the non-empty list `targets` of IVar's, IGet's, or ISlot_Lookup's; expression is specified by the IExpr `expr`.

`func inot(expr, src_infos):` Returns an INot which checks the expression specified by the IExpr `expr`.

`func ibinary(type, lhs, rhs, src_infos):` Returns an IBinary whose: `type` must be one of `BINARY_ADD`, `BINARY_SUB`, `BINARY_MUL`, `BINARY_DIV`, or `BINARY_MOD`; left hand side expression is specified by the IExpr `lhs`; right hand side expression is specified by the IExpr `rhs`.

`func icomparison(type, lhs, rhs, src_infos):` Returns an IComparison whose: `type` must be one of `IS_COMPARISON`, `EQ_COMPARISON`, `NEQ_COMPARISON`, `LEQ_COMPARISON`, `GEQ_COMPARISON`, `LE_COMPARISON`, or `GE_COMPARISON`; left hand side expression is specified by the IExpr `lhs`; right hand side expression is specified by the IExpr `rhs`.

`func ipass(src_infos):` Returns an IPass.

`func iinsert(expr, src_infos):` Returns an INot which inserts the expression specified by the IExpr `expr` into a surrounding quasi-quoted expression.

`func iquasi_quotes(body, extra_src_infos, src_infos):` Returns an IQuasi_Quotes which quasi-quotes the IExpr_Seq `body`, adding extra src infos specified by `extra_src_infos` which may be `null` if no extra src infos are to be added to the resulting ITree.

`func imod_id_import(mod_id, src_infos):` Returns an `IMod_Id_Import` which imports and returns the module with ID `mod_id`.

#### ITree virtual elements

`func IExpr_Seq(exprs, src_infos):` Returns an IExpr_Seq of the non-empty list of IExpr's `exprs`.

`func iparam(var, default, src_infos):` Returns an IParam whose name is defined by the IVar `name`, and whose default value is specified by the IExpr `default` or `null` if there is no default value.

`func idict_elem(key, val, src_infos):` Returns an IDict_Elem whose key is `key`, and whose value is `val`.

`func irename(from, as_, src_infos):` Returns an IReturn from the IVar `from` to the IVar `as_`.

`func iclause(condition, body, src_infos):` Returns an IClause whose: condition is specified by the IExpr `condition`; body is specified by the IExpr_Seq `body`.

#### Assignment types

`STD_ASSIGN`: for the standard assignment operator `:=`.

`ADD_ASSIGN`: for the addition assignment operator `+=`.

`SUB_ASSIGN`: for the subtraction assignment operator `-=`.

`MUL_ASSIGN`: for the multiplication assignment operator `*=`.

`DIV_ASSIGN`: for the division assignment operator `/=`.

#### Binary operator types

`BINARY_ADD`: for the binary operator `+`.

`BINARY_SUB`: for the binary operator `-`.

`BINARY_MUL`: for the binary operator `*`.

`BINARY_DIV`: for the binary operator `/`.

`BINARY_MOD`: for the binary operator `%`.

#### Comparison operator types

`IS_COMPARISON`: for the comparison operator `is`.

`EQ_COMPARISON`: for the comparison operator `==`.

`NEQ_COMPARISON`: for the comparison operator `!=`.

`LEQ_COMPARISON`: for the comparison operator `<=`.

`GEQ_COMPARISON`: for the comparison operator `>=`.

`LE_COMPARISON`: for the comparison operator `<`.

`GE_COMPARISON`: for the comparison operator `>`.

cvd_to_html ©2006-2007 Laurence Tratt