This is the help/information file detailing the creation of expansion libraries for the Emu language (for use via the UseModule function).

This requires a copy of Emu, version 1.0 or higher. Installation instructions are available at the Emu homepage.

You are writing a shared object (.so) file. Thus, when compiling with gcc, always use the -shared flag. Also, your library must link against libemusdk.so (the last parameter to gcc should be -lemusdk.

Your library will contain all of the functions you wish to make available to the user, any support functions, and also a function named RegisterLibrary(). This function must be of the form: int RegisterLibrary(LPLIBRARYHANDLES hnds). RegisterLibrary() is used as a sort of "main()" for the library; it is called immediately upon loading. The function should do two things:

1. It should pass hnds to the InitLibrary() function in the SDK library. This function will set up the pointers required to call back to the emu executable. Thus, this call should be the first one in RegisterLibrary(). InitLibrary() is prototyped as: int InitLibrary(LPLIBRARYHANDLES hnds). It returns 0 on success and 1 on failure. The pointer to the LIBRARYHANDLES structure that was passed to RegisterLibrary should be passed on without modification to InitLibrary. Should this function return 1, RegisterLibrary() should return 1 immediately as well.
2. RegisterLibrary() must also register all user-accessable functions with Emu via the create_intrinsic_function() function. This is prototyped as: int create_intrinsic_function(char *user_name,int (*C_function_name)(char *, FILE *, FILE *, LPSAFELISTITEM, long *). (Thus, you pass it the name you want the script to access it as, in quotes, followed by the name of the handling C function.)

Language function definitions can be abbreviated using the LangFunc() macro. Simply define all your language functions as LangFunc(funcname). The parameters passed to the function are:

• char *str - a string containing all the unevaluated parameters passed to your function in the script. (Note: tailing carriage returns, semicolons, as well as the function's name are all removed from this line, in advance.)
• FILE *fpin - A FILE * indicating the script file input. (not stdin!)
• FILE *fpout - A FILE * indicating stdout.
• LPSAFELISTITEM pThisLine - A pointer to the SAFELISTITEM describing the line of code.
• unsigned long *force_jump - A pointer to a variable which can be changed to indicate the next line of code that should be executed. Leaving force_jump as -1 will cause the next line in the script to execute.

Other Emu functions available for use:

• int addrawstr(LPSAFESTRING str,char *new) - Adds a null-terminated string to the end of the string contained within the SAFESTRING element.
• int addrawstrn(LPSAFESTRING str,char *new,int n) - Adds n characters of the null-terminated string new to the SAFESTRING str.
• int addsafestr(LPSAFESTRING dest, LPSAFESTRING source) - Adds the string in source to the end of the string in dest.
• int addsafestrn(LPSAFESTRING dest, LPSAFESTRING source, int n) - Adds n characters of source to the end of the string in dest.
• int addsafestrno(LPSAFESTRING dest, LPSAFESTRING source, int n, int offset) - Adds n characters of source, beginning offset characters into the string, to the end of the string in dest.
• int addsafestro(LPSAFESTRING dest, LPSAFESTRING source, int offset) - Adds the string starting offset characters into source to the end of the string represented by dest.
• create_user_variables(char *str, LPSAFELISTITEM pThisLine, int var_type, int domain) - Creates variables based on the current line of input. str and pThisLine should be passed as they were passed to the calling function. var_type describes the type of variable to create. (Same types as for GetUserIdentifier().) domain indicates if the variables are only available locally (pass the value in int *CallDepth for this), or globally (pass 0).
• int eval_expression(char *str, unsigned long *u_result, long *i_result, double *f_result, int type, int has_op) - evaluates an algebraic, logical, bitwise, or comparative expression taken from str. The result is stored in one of the three result parameters, depending upon the type of the variable to receive the value of this expression (as declared by the type parameter). The has_op parameter is set to 1 if the expression contains a self-inclusive operator, such as =+, =-, etc.
• int GetLibVersion() - Returns an integer specifying the library version of libemusdk.so.
• LPFUNCTIONDEF GetUserIdentifier(char *name) - Returns a pointer to a structure containing the identifier in name. (Returns 0 on failure.) If the identifier is a variable, its value is in one of the members of the val union in the struct, based on the type of the variable (as indicated by the type member. The types are:
  • 0 is intrinsic (C-based) function
  • 1 is a function in the script
  • 2 is float
  • 3 is int
  • 4 is unsigned int
  • 5 is a string
  • 6 is internal int (reserved type)
  • 7 is internal float (reserved type)
  • 8 is float array
  • 9 is int array
  • 10 is unsigned int array
  • 11 is string array
  • 12 is internal non-comparative float (reserved type)
  • 13 is intrinsic (C-based) keyword; can not be used as a function (e.g., x = break; is illegal.)
  • 14-64 are reserved for internal use.
• int killstring(LPSAFESTRING str) - Destroys the SAFESTRING in str. Must be called when the use of the SAFESTRING is done.
• char *ltoa(long n) - Returns a null-terminated string representing the value stored in n.
• char *ltrim(char *str) - Returns the string str with any leading whitespace removed.
• long pop(STACK *s) - returns the top value popped off the stack, s. The global stack is located in STACK *calls.
• print_eval_error(int err) - Prints an error message based on the return value of eval_expression().
• int push(STACK *s,long x) - pushes the value x onto the stack, s. The global stack is located in STACK *calls.
• int replacestr(LPSAFESTRING str, int offset, int length, char *new) - Removes the section of a SAFESTRING (stroffset characters from the start of the string, and lasting for length characters, and replacing it with the null-terminated string in new. new need not be the same length as the section being replaced.
• int SetLongRet(long) - Sets the global return value 'ret' to the given value.
• int SetStrRet(char *) - Sets the global return value 'ret' to the given string.
• int SetRealRet(float) - Sets the global return value 'ret' to the given value.
• unsigned long strhash(char *) - creates a 32-bit hash based on the string given.
• char *strip_whitespace(char *) - strips any carriage-returns (\n)'s from the string.
• void SysErr(char *errmsg) - Prints a message (automatically adding a carriage-return) and flags it as an error.
• void SysWarn(char *errmsg) - Prints a message (automatically adding a carriage-return) and flags it as a warning.
• int zerostring(LPSAFESTRING str) - Clears a SAFESTRING item and readies it for use. (Must be called before any other action is taken on the SAFESTRING).

Emu is packaged with an example module. The modtest module (in the libemumodtest/ directory off of the source tree) demonstrates the proper way to build a module. The use of the module in an Emu script is demonstrated in test #17 (17.emu) in the bin/tests/ directory.

This document was written by Aaron Kimball (kimballa@concentric.net).
© Copyright 2001 Aaron Kimball.
Part of the Emu Language - http://emulang.sourceforge.net/.