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 [from, to] 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. target[index]) 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. target[index]) 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