Embedding API for the Muse language.

The muSE embedding API is a C wrapper around the core muSE runtime with additional support functions. More...


Data Structures
struct	muse_functional_object_type_t
	Type information for a functional object. More...
struct	muse_functional_object_type_t
	Type information for a functional object. More...
struct	muse_functional_object_t
	Any muSE functional object must always begin with this structure. More...
Cell access
typedef muse_cell(*)	muse_list_generator_t (void context, int i, muse_boolean eol)
	A function that is called to generate elements which are collected into a list by `muse_generate_list()`.
muse_cell_t	muse_cell_type (muse_cell cell)
	Returns the type of the cell data referenced by the given cell reference.
muse_boolean	muse_isfn (muse_cell cell)
	Returns MUSE_TRUE if the given cell is a function either native or lambda.
muse_cell	muse_head (muse_cell cell)
	Returns the head of the cons cell referred to by the given cell reference.
muse_cell	muse_tail (muse_cell cell)
	Returns the tail of the cons cell referred to by the given cell reference.
muse_cell	muse_tail_n (muse_cell cell, int n)
	Returns the n-th tail of the given list.
muse_cell	muse_next (muse_cell cell)
	(next list) = For traversing lazy lists.
muse_int	muse_int_value (muse_cell cell)
	Given an integer or float cell, it returns the value cast to a 64-bit integer.
muse_float	muse_float_value (muse_cell cell)
	Given an integer or float cell, it returns the value cast to a 64-bit float.
const muse_char *	muse_text_contents (muse_cell cell, int *length)
	Returns a pointer to the characters of the string referenced by the given cell.
const muse_char *	muse_symbol_name (muse_cell sym)
	Returns the string name of the given symbol.
muse_cell	muse_symbol_value (muse_cell sym)
	Returns the top-most value of the symbol that's on the symbol's value stack.
int	muse_list_length (muse_cell list)
	Returns the number of elements in the list.
muse_cell	muse_list_last (muse_cell list)
	Returns the last cell of a list or () if the list is itself ().
muse_cell	muse_list_append (muse_cell head, muse_cell tail)
	Appends the tail list to the end of the head list and returns the head list.
muse_cell	muse_array_to_list (int count, const muse_cell *array, int astep)
	Constructs a new list whose contents are that of the given array in the given order.
muse_cell *	muse_list_to_array (muse_cell list, int *lengthptr)
	Constructs a new array with the contents of the list in the given order.
void	muse_list_extract (int count, muse_cell list, int lstep, muse_cell *array, int astep)
	Extracts `count` elements from the list starting with the first element, into the given array.
muse_cell	muse_generate_list (muse_list_generator_t generator, void *context)
	Creates a list whose contents are generated by the given generator function.
Dynamically loading plugins
typedef muse_cell(*)	muse_plugin_entry_t (void module, muse_env env, muse_cell arglist)
	A muSE plugin is expected to export only one function - the entry point - of this type.
muse_cell	muse_link_plugin (const muse_char *path, muse_cell arglist)
	Loads a muse plugin DLL and calls its entry point function which is to have the name "muse_plugin_entry" and be of the type muse_plugin_entry_t.
Ports API
A port is an I/O abstraction that you can use to work with objects like files and network connections. Anything that satisfies a simple protocol can be used as a port. All standard muSE functions such as muse_pwrite and muse_pread will work with any port that satisfies such the protocol. See also: Ports
typedef _muse_port_base_t *	muse_port_t
enum	muse_stdport_t { MUSE_STDIN_PORT, MUSE_STDOUT_PORT, MUSE_STDERR_PORT }
enum	muse_port_mode_bits_t { MUSE_PORT_READ = 1, MUSE_PORT_WRITE = 2, MUSE_PORT_READ_WRITE = MUSE_PORT_READ \| MUSE_PORT_WRITE, MUSE_PORT_EZSCHEME = 4, MUSE_PORT_READ_EXPAND_BRACES = 0x10, MUSE_PORT_READ_DETECT_MACROS = 0x20, MUSE_PORT_TRUSTED_INPUT = MUSE_PORT_READ \| MUSE_PORT_READ_EXPAND_BRACES \| MUSE_PORT_READ_DETECT_MACROS }
	These bits are used to identify various port features, whether it is for reading, writing, etc. More...
muse_port_t	muse_port (muse_cell p)
	Takes a muSE port represented as a cell and returns the internal port object that it uses.
muse_port_t	muse_stdport (muse_stdport_t descriptor)
muse_port_t	muse_assign_port (FILE *f, int mode)
	Creates a port definition that you can use to read/write stuff from a given file pointer.
void	muse_unassign_port (muse_port_t p)
	Unassigns a file port which was earlier assigned using `muse_assign_port`.
muse_cell	muse_pread (muse_port_t port)
	Reads the next symbolic expression at the current stream position, ignoring white space and comment lines.
void	muse_pwrite (muse_port_t port, muse_cell sexpr)
	Writes the given s-expression to the given stream.
void	muse_pprint (muse_port_t port, muse_cell sexpr)
Managing the muse environment.
enum	muse_env_parameter_name_t { MUSE_END_OF_LIST, MUSE_HEAP_SIZE, MUSE_GROW_HEAP_THRESHOLD, MUSE_STACK_SIZE, MUSE_MAX_SYMBOLS, MUSE_DISCARD_DOC, MUSE_PRETTY_PRINT, MUSE_TAB_SIZE, MUSE_NUM_PARAMETER_NAMES }
	When creating a new muse environment, you can configure it using a set of parameters. More...
muse_env *	muse_init_env (const int *parameters)
	Creates a new muse environment.
void	muse_destroy_env (muse_env *env)
	Destroys the given environment.
muse_env *	muse_get_current_env ()
	Returns the current muse environment or NULL if none is set.
muse_env *	muse_set_current_env (muse_env *env)
	Changes the current muse environment to the given one.
Basic memory management
muse_cell	muse_cons (muse_cell head, muse_cell tail)
	Allocates a new cons cell with the given head and tail cells.
muse_cell	muse_mk_int (muse_int i)
	Allocates a new integer cell to hold the given integer.
muse_cell	muse_mk_float (muse_float f)
	Allocates a new float cell to hold the given integer.
muse_cell	muse_mk_text (const muse_char start, const muse_char end)
	Copies the given text and creates a new text cell to store it.
muse_cell	muse_mk_text_utf8 (const char start, const char end)
	Same as `muse_mk_text()` except that it takes a UTF8 string and converts it into a unicode string and stores it.
muse_cell	muse_mk_ctext (const muse_char *start)
	Same as `muse_mk_text()` except that it assumes a null terminated string.
muse_cell	muse_mk_ctext_utf8 (const char *start)
	Same as `muse_mk_text_utf8()` except that it assumes a null terminated string as input.
muse_cell	muse_mk_nativefn (muse_nativefn_t fn, void *context)
	Creates a new cell that stores a C function.
muse_cell	muse_mk_destructor (muse_nativefn_t fn, void *context)
	A destructor is a native function that also gets called with no arguments when the function is garbage collected.
muse_cell	muse_mk_anon_symbol ()
	An anonymous symbol is similar to a named symbol, except that it is not stored permanently on the symbol stack.
muse_cell	muse_list (const char *format,...)
	Returns a list of the given items.
muse_cell	muse_symbol (const muse_char start, const muse_char end)
	Returns a reference to a named symbol with the given name.
muse_cell	muse_csymbol (const muse_char *sym)
	Same as `muse_symbol()`, but takes a c-style null terminated unicode character string.
muse_cell	muse_symbol_utf8 (const char start, const char end)
	Same as `muse_symbol()` except that it takes a UTF8 string.
muse_cell	muse_csymbol_utf8 (const char *sym)
	Same as `muse_symbol_utf8()` except that it takes a c-style null terminated utf8 string.
muse_cell	muse_builtin_symbol (muse_builtin_symbol_t s)
	Returns a symbol reference corresponding to the given symbol index.
int	muse_stack_pos ()
	Returns the current stack position.
void	muse_stack_unwind (int stack_pos)
	Unwinds the stack to the given position.
muse_cell	muse_stack_push (muse_cell obj)
	Saves the given object on the stack so that it will not be garbage collected when gc is next invoked.
void	muse_gc (int free_cells_needed)
	Collects all the garbage cells - i.e.
void	muse_mark (muse_cell cell)
	Prior to garbage collection, muse_mark is called on all cells which are referenced somewhere and should not be garbage collected.
Cell editing
muse_cell	muse_set_cell (muse_cell cell, muse_cell head, muse_cell tail)
	Sets the given cell's head and tail to the given cell references.
muse_cell	muse_set_head (muse_cell cell, muse_cell head)
	Sets the head of the given cell.
muse_cell	muse_set_tail (muse_cell cell, muse_cell tail)
	Sets the tail of the given cell.
muse_cell	muse_set_int (muse_cell int_cell, muse_int value)
	Sets the integer value of an int cell.
muse_cell	muse_set_float (muse_cell float_cell, muse_float value)
	Sets the float value of a float cell.
muse_cell	muse_set_text (muse_cell text, const muse_char start, const muse_char end)
	Copies the given string to the given text cell, modifying the cell's contents.
muse_cell	muse_set_ctext (muse_cell text, const muse_char *start)
	Same as `muse_set_text`, except that it takes a null terminated c-style string instead.
muse_cell	muse_define (muse_cell symbol, muse_cell value)
	Sets the value of the symbol.
muse_cell	muse_pushdef (muse_cell symbol, muse_cell value)
	Makes the given value the current value of the symbol, without losing the previously assigned set of values.
muse_cell	muse_popdef (muse_cell symbol)
	Removes the current value on the symbol's value stack and returns it.
muse_cell	muse_dup (muse_cell obj)
	Deep copies the given object.
muse_cell *	muse_find_list_element (muse_cell *listptr, muse_cell element)
	Searches for the given `element` in the given `list` and returns a reference to it.
Property lists
int	muse_eq (muse_cell a, muse_cell b)
	Shallow compares two cells.
int	muse_equal (muse_cell a, muse_cell b)
	Deep compares two cells.
int	muse_compare (muse_cell a, muse_cell b)
	Deep compares two cells for ordering.
muse_cell	muse_symbol_plist (muse_cell sym)
	Returns the property list of the given symbol.
muse_cell	muse_assoc (muse_cell alist, muse_cell prop)
	Looks up a particular association by key in an association list.
muse_cell *	muse_assoc_iter (muse_cell *alist, muse_cell prop)
	Similar to muse_assoc, except that the return value is not the kvpair, but the list position of the kvpair.
muse_cell	muse_get_prop (muse_cell sym, muse_cell prop)
	Looks up the given property in the given symbol's property list.
muse_cell	muse_put_prop (muse_cell sym, muse_cell prop, muse_cell value)
	Sets or adds the given property-value association to the symbol's property list.
I/O
muse_cell	muse_load (FILE *f)
	Reads all symbolic expressions in the stream and evaluates them one by one, until end of stream.
Evaluation
muse_cell	muse_eval (muse_cell sexpr)
	Evaluates the given symbolic expression.
muse_cell	muse_evalnext (muse_cell *sexpr)
	Evaluates the head of the list referred to by the given sexpr pointer and steps the pointer to the tail of the list, getting ready for the next call.
muse_cell	muse_eval_list (muse_cell list)
	Evaluates each element of the given list, builds a new list out of the results of the evaluations and returns the list.
muse_cell	muse_apply (muse_cell fn, muse_cell args, muse_boolean args_already_evaluated)
	Applies the given native function or lambda to the given list of arguments and returns the result.
muse_cell	muse_do (muse_cell block)
	A block of code is a list of expressions to evaluate in sequence.
muse_cell	muse_quote (muse_cell args)
	Returns the given arguments quoted.
muse_boolean	muse_bind_formals (muse_cell formals, muse_cell values)
	Binds the symbols in the given formals list to the corresponding values in the args list.
muse_cell	muse_callcc (muse_cell proc)
Misc
muse_int	muse_hash (muse_cell obj)
	Hashes a given cell reference.
muse_int	muse_hash_text (const muse_char start, const muse_char end, muse_int initial)
	A hash similar to muse_hash_data, but tailored for text.
muse_int	muse_hash_data (const unsigned char start, const unsigned char end, muse_int initial)
	Creates a simple hash of the given data.
void *	muse_tick ()
	Used for performance timing.
muse_int	muse_tock (void *)
	When passed the timing handle returned by `muse_tick()`, it returns the time elapsed between the `muse_tick()` call and this `muse_tock()` call in microseconds.
void	muse_sleep (muse_int time_us)
	Sleeps the muse process for the given time in microseconds.
FILE *	muse_fopen (const muse_char filename, const muse_char options)
	A wrapper to the common fopen function so that we can call _wfopen if available, or the narrow version if the wide version isn't available.
Diagnostics
const muse_char *	muse_typename (muse_cell thing)
	Returns a non-mutable string describing the type of the `thing` passed as the parameter.
int	muse_sprintf (muse_char buffer, int maxlen, const muse_char format,...)
	Formats a string consisting of the given format string with the other argument objects inserted at specified positions.
void	muse_message (const muse_char context, const muse_char format,...)
	Displays a message string formatted according to the given message string with format codes.
muse_boolean	muse_expect (const muse_char context, const muse_char spec,...)
	Checks whether a set of expectations are satisfied by some values.
muse_cell	muse_similar_symbol (muse_cell symbol, int *distance)
	Sometimes, it is useful to know whether another symbol that's very similar in textual representation from a known symbol.
muse_cell	muse_symbol_with_value (muse_cell value)
	Searches the symbol table to find a symbol whose current value is the given cell.
Multilingual stuff
int	muse_unicode_to_utf8 (char out, int out_maxlen, const muse_char win, int win_len)
	Converts the given double-byte unicode string to multibyte UTF8 string.
int	muse_utf8_to_unicode (muse_char wout, int wout_maxlen, const char in, int in_len)
	Converts the given UTF8 string to double-byte unicode string.
int	muse_utf8_size (const muse_char *wstr, int length)
	Returns an estimate of the number of bytes (conservative upper bound) that might be needed to represent the given number of unicode characters using UTF8 encoding.
int	muse_unicode_size (const char *utf8, int nbytes)
	Returns an estimate (conservative upper bound) of the number of bytes that will be required to store the converted unicode version of the given utf8 string.
REPL - Read Eval Print Loop
void	muse_repl ()
	The muSE REPL - Read-Eval-Print-Loop.
Extending muSE with functional objects
muse_cell	muse_mk_functional_object (muse_functional_object_type_t *type_info, muse_cell init_args)
	Creates a new functional object instance based on the given type information.
muse_functional_object_t *	muse_functional_object_data (muse_cell fobj, int type_word)
	Returns the data pointer of the functional object, or NULL if the object is not a functional object.
Vectors
muse_cell	muse_mk_vector (int length)
	Creates a new vector object that has enough slots allocated to hold the given number of objects.
int	muse_vector_length (muse_cell vec)
	Returns the number of slots the vector has.
muse_cell	muse_vector_get (muse_cell vec, int index)
	Returns the value occupying the slot at the given 0-based index.
muse_cell	muse_vector_put (muse_cell vec, int index, muse_cell value)
	Replaces the value in the slot at the given index with the new value.
Hashtables
muse_cell	muse_mk_hashtable (int length)
	Creates a hashtable with a bucket count setup according to the given desired length.
int	muse_hashtable_length (muse_cell ht)
	Returns the number of key-value pairs put into the hash table.
muse_cell	muse_hashtable_get (muse_cell ht, muse_cell key)
	Returns the key-value pair with the given key as the head if the key is present in the hash table, otherwise it returns MUSE_NIL.
muse_cell	muse_hashtable_put (muse_cell ht, muse_cell key, muse_cell value)
	Associates the given value with the given key in the hash table.
Typedefs
typedef _muse_env	muse_env
	Identifies a particular muse instance.
typedef wchar_t	muse_char
	Unicode character type used throughout muse.
typedef longlong_t	muse_int
	64-bit signed integer type.
typedef double	muse_float
	64-bit double precision floating point type.
typedef int	muse_cell
	A cell is referred using a single 32-bit signed integer.
typedef muse_cell(*)	muse_nativefn_t (muse_env env, void context, muse_cell args)
	You can include native C-function calls within Muse procedure execution.
Enumerations
enum	muse_cell_t { MUSE_CONS_CELL, MUSE_LAMBDA_CELL, MUSE_SYMBOL_CELL, MUSE_NATIVEFN_CELL, MUSE_INT_CELL, MUSE_FLOAT_CELL, MUSE_TEXT_CELL }
	Type codes for the various cell types. More...
enum	muse_boolean { MUSE_FALSE, MUSE_TRUE }
enum	muse_builtin_symbol_t { MUSE_NIL, MUSE_T, MUSE_QUOTE, MUSE_RETURN, MUSE_BREAK, MUSE_CLASS, MUSE_SUPER, MUSE_DOC, MUSE_CODE, MUSE_SIGNATURE, MUSE_USAGE, MUSE_BRIEF, MUSE_DESCR, MUSE_TIMEOUT, MUSE_DEFINE, MUSE_NUM_BUILTIN_SYMBOLS }
	Some builtin-symbols are provided for general use. More...

Detailed Description

The muSE embedding API is a C wrapper around the core muSE runtime with additional support functions.

muSE - which stands for "muvee Symbolic Expressions" - is an environment for manipulating list-based data structures. It consists of functions to create and parse such data structures as well as functions to read and write them from/to files.

The muSE environment

The muSE environment holds all the data constructed using the muSE API calls and keeps track of object references. There is a single global muse environment muse_env* active at any given time. One creates this global muse environment using muse_init_env and destroys it using muse_destroy_env.

The basic data types in muSE

64-bit integers - see MUSE_INT_CELL, muse_mk_int
64-bit floats - see MUSE_FLOAT_CELL, muse_mk_float
and unicode strings - see MUSE_TEXT_CELL, muse_mk_text and family
symbols - see MUSE_SYMBOL_CELL, muse_symbol and family

The cons cell

The object that glues the above fundamental types into complex structures is the "cons cell", aka a "pair" (MUSE_CONS_CELL, muse_cons). A cons (short for "constructor") cell is a pair of cells which are referred to as the head and tail of the cons cell. A cons cell may have another cons cell as its head or tail.

If one uses the notation

 (cons h t)

to denote a cons cell whose head is h and tail is t, then we can encode a list of items

 (h1 h2 h3 ... hN)

using cons cells like this -

 (cons h1 (cons h2 (cons h3 ... (cons hN ()) ... )))

where () is another name for the empty list and is used to mark the end of a list.

Symbols

Symbols are objects that are uniquely identified by giving their names (see muse_symbol, muse_csymbol, and family). A symbol may have a value (see muse_symbol_value and muse_define) and a list of properties (see muse_symbol_plist, muse_get_prop and muse_put_prop).

The property list of a symbol is in the form of what's called an "association list" - a list of property-value pairs. Each property-value pair is stored in a cons cell with the property in the head and the value in the tail. (see muse_assoc)

It is also possible to have anonymous symbols which differ from named symbols in only one aspect - they have no name and are not preserved eternally. Anonymous symbols form the foundation of muSE's simple, yet powerful object system.

S-Expressions

Compound structures built out of cons cells, and values such as ints, floats, symbols, strings, are called s-expressions - short for "symbolic expressions". This term includes functions as well.

Reading and writing s-expressions

The functions muse_pread and muse_pwrite read and write complete s-expressions from a given IO stream. You can use this feature to load and save data to files, or to build a simple interpreter using a read-eval-print-loop (REPL for short). For a brief description of the syntax of the data structure representation, see mainpage.

Typedef Documentation

typedef struct _muse_env muse_env

Identifies a particular muse instance.

typedef wchar_t muse_char

Unicode character type used throughout muse.

typedef longlong_t muse_int

64-bit signed integer type.

typedef double muse_float

64-bit double precision floating point type.

typedef int muse_cell

A cell is referred using a single 32-bit signed integer.

typedef muse_cell(*) muse_nativefn_t(muse_env *env, void *context, muse_cell args)

You can include native C-function calls within Muse procedure execution.

This is how built-in functionality is provided. A Muse nativefn can be passed a single pointer to arbitrary data that is not managed by the muse environment. This is called its "context" and serves to supply any data and state the function may need to maintain. For example, context can be the pointer to a C++ object instance and the nativefn can in turn call some specific method of that object.

Parameters:

	env	The muse environment that's calling the native function.
	context	The function's closure argument.
	args	A list of arguments that was passed to the function when it was called within the muse environment.

typedef muse_cell(*) muse_list_generator_t(void *context, int i, muse_boolean *eol)

A function that is called to generate elements which are collected into a list by muse_generate_list().

Parameters:

	context	Arbitrary data that is passed by `muse_generate_list` to the generator function, without being touched.
	i	An integer indicating the zero-based index of the list element that the generator function is being asked to generate.
	eol	If the generator function wants to end the list at the given index `i`, then it can simply set (eol) to `MUSE_TRUE` and return. If (eol) is found to be `MUSE_FALSE`, then the element returned by the generator function is appended to the list.

typedef muse_cell(*) muse_plugin_entry_t(void *module, muse_env *env, muse_cell arglist)

A muSE plugin is expected to export only one function - the entry point - of this type.

When linking the plugin using muse_link_plugin, this entry point function is invoked and the result returned by this function is returned by muse_link_plugin.

Parameters:

	module	The system specific handle of the loaded dynamically linked module. In Windows, this is the HMODULE returned by the `LoadLibrary` call. In Unix, its the handle returned by `dlopen`.
	env	The muse environment which is linking the plugin. The plugin entry function is expected to set its current environment to this environment pointer before calling any muSE API functions.
	arglist	An arbitrary list of arguments for use by the plugin entry point function.

Returns:: Any s-expression. This return value will be returned by muse_link_plugin.

typedef struct _muse_port_base_t* muse_port_t

Enumeration Type Documentation

enum muse_cell_t

Type codes for the various cell types.

Enumerator:

MUSE_CONS_CELL	A CONS cell contains a pair of cells - the "head" and "tail".
MUSE_LAMBDA_CELL	A LAMBDA cell contains a definition of a function.
MUSE_SYMBOL_CELL	Holds a SYMBOL that may have been given a value or have properties.
MUSE_NATIVEFN_CELL	A NATIVEFN holds the address of C-function to execute with an arbitrary argument.
MUSE_INT_CELL	Holds a single 64-bit signed integer.
MUSE_FLOAT_CELL	Holds a single 64-bit floating point number - i.e. a "double".
MUSE_TEXT_CELL	Holds an immutable copy of a wide character string - as ptrs to beginning and end.

enum muse_boolean

Enumerator:

MUSE_FALSE
MUSE_TRUE

enum muse_builtin_symbol_t

Some builtin-symbols are provided for general use.

See also:: muse_builtin_symbol()

Enumerator:

MUSE_NIL
MUSE_T
MUSE_QUOTE
MUSE_RETURN
MUSE_BREAK
MUSE_CLASS
MUSE_SUPER
MUSE_DOC
MUSE_CODE
MUSE_SIGNATURE
MUSE_USAGE
MUSE_BRIEF
MUSE_DESCR
MUSE_TIMEOUT
MUSE_DEFINE
MUSE_NUM_BUILTIN_SYMBOLS	Not a symbol.

enum muse_env_parameter_name_t

When creating a new muse environment, you can configure it using a set of parameters.

Parameters are passed as an array of 32-bit integers where indices 0, 2, 4, etc. hold parameter names and indices 1, 3, 5, etc. hold parameter values. This enumeration defines the set of configurable parameters.

Enumerator:

MUSE_END_OF_LIST	Used to signal the end of the parameter list. No value needed.
MUSE_HEAP_SIZE	Integer parameter giving required heap size.
MUSE_GROW_HEAP_THRESHOLD	Percentage of heap size usage above which to grow the heap. Default = 80.
MUSE_STACK_SIZE	Integer parameter giving required stack size.
MUSE_MAX_SYMBOLS	Integer parameter giving max symbols used.
MUSE_DISCARD_DOC	Boolean parameter indicating that documentation should not be kept. Default = MUSE_FALSE.
MUSE_PRETTY_PRINT	Boolean parameter indicating whether write and print should indent their output. Default = MUSE_TRUE
MUSE_TAB_SIZE	Defaults to 4. Controls pretty printed output.
MUSE_NUM_PARAMETER_NAMES	Not a parameter.

enum muse_stdport_t

Enumerator:

MUSE_STDIN_PORT
MUSE_STDOUT_PORT
MUSE_STDERR_PORT

enum muse_port_mode_bits_t

These bits are used to identify various port features, whether it is for reading, writing, etc.

Enumerator:

MUSE_PORT_READ	Indicates that the port is to be used for input.
MUSE_PORT_WRITE	Indicates that the port is to be used for output.
MUSE_PORT_READ_WRITE	Convenient definition for bi-directional ports.
MUSE_PORT_EZSCHEME	Says that the input from the given port is uses the EZSCHEME syntax.
MUSE_PORT_READ_EXPAND_BRACES	Allows muse_pread() function to expand s-expressions that use braces instead of parentheses. This is enabled by default for standard input and for files from which code is loaded using muse_load().
MUSE_PORT_READ_DETECT_MACROS	Allows muse_pread() function to detect and expand macro expressions. Macro expressions are those parentheses delimited list expressions with a macro symbol as the first list element. A macro symbol is a symbol that is defined to a macro function at the point at which the macro expression is encountered. Macro expression detection is always disabled when reading quoted expressions, though brace expansion may be active.
MUSE_PORT_TRUSTED_INPUT	Convenience definition indicating that input from the given port can be trusted, therefore enabling macro expansion. Standard input and file ports using by muse_load() are considered to be trusted input sources.

Function Documentation

muse_env* muse_init_env ( const int * parameters )

Creates a new muse environment.

The new environment is made current.

Parameters:

parameters

is an int array of param-value pairs. The last entry should be MUSE_END_OF_LIST which need not be given a value.

See also:: muse_env_parameter_name_t

< We need a x2 in the size for the bindings stack above because the bindings stack is an array of symbol-value pairs.

void muse_destroy_env ( muse_env * env )

Destroys the given environment.

If the given environment is the current environment, then the current environment is set to NULL and no muse calls can subsequently be made.

muse_env* muse_get_current_env ( )

Returns the current muse environment or NULL if none is set.

muse_env* muse_set_current_env ( muse_env * env )

Changes the current muse environment to the given one.

muse_cell muse_cons	(	muse_cell	head,
		muse_cell	tail
	)

Allocates a new cons cell with the given head and tail cells.

This is the primary constructor in the whole of muse out of which all muse objects are built. A new cell for the cons operation is taken from the heap's free list. If no cell is available the garbage collector is invoked to collect the unreferenced cells into the free list. If absolutely no cells are available, then the heap is grown in order to get a free cell to allocate to the cons. The newly allocated cell is placed on the stack so that it won't be inadvertently garbage collected. This way, you can safely write expressions of the form

 muse_cons( muse_cons(a,b), muse_cons(c,d) )

The cons operation does not fail unless there is absolutely no system memory available for the new cell.

muse_cell muse_mk_int ( muse_int i )

Allocates a new integer cell to hold the given integer.

The newly allocated cell is placed on the stack.

muse_cell muse_mk_float ( muse_float f )

Allocates a new float cell to hold the given integer.

The newly allocated cell is placed on the stack.

muse_cell muse_mk_text	(	const muse_char *	start,
		const muse_char *	end
	)

Copies the given text and creates a new text cell to store it.

The newly allocated cell is placed on the stack. If you pass NULL for start, then this creates a new text cell of the needed length (= end-start), but stores null characters in it. You can subsequently change the contents of the text cell.

For internal use only.

The cell is also placed on the specials list so that the memory required to hold the cell can be destroyed when the text cell is no longer needed and is garbage collected.

muse_cell muse_mk_text_utf8	(	const char *	start,
		const char *	end
	)

Same as muse_mk_text() except that it takes a UTF8 string and converts it into a unicode string and stores it.

muse_cell muse_mk_ctext ( const muse_char * start )

Same as muse_mk_text() except that it assumes a null terminated string.

muse_cell muse_mk_ctext_utf8 ( const char * start )

Same as muse_mk_text_utf8() except that it assumes a null terminated string as input.

muse_cell muse_mk_nativefn	(	muse_nativefn_t	fn,
		void *	context
	)

Creates a new cell that stores a C function.

The C function can be passed its own context data that is not managed by muSE. The function pointer is given in fn and the context data is given in context. Using the context pointer, it is possible to encode a call to a C++ member function, by writing a static wrapper function.

muse_cell muse_mk_destructor	(	muse_nativefn_t	fn,
		void *	context
	)

A destructor is a native function that also gets called with no arguments when the function is garbage collected.

muse_cell muse_mk_anon_symbol ( )

An anonymous symbol is similar to a named symbol, except that it is not stored permanently on the symbol stack.

It has a property list as well and a value stack, but the symbol name cell is nil. The hash code of an anonymous symbol is the integer value of cell reference itself, so comparing using the hash is the same as comparing the cell reference itself.

Anonymous symbols are used to represent objects in muSE's object system. An object's properties are stored in the plist of an anonymous symbol.

muse_cell muse_list	(	const char *	format,
			...
	)

Returns a list of the given items.

The format string is a string of single character codes indicating the type of argument to convert to a muse object.

c -> cell
i -> 32-bit integer
I -> 64-bit integer
f -> 64-bit float
T -> unicode text string
t -> utf8 text string
S -> unicode symbol string
s -> utf8 symbol string

muse_cell muse_symbol	(	const muse_char *	start,
		const muse_char *	end
	)

Returns a reference to a named symbol with the given name.

All symbols with the same name have identical symbol references. Therefore you can compare whether two symbols are the same by comparing their cell references.

For internal use only.

A symbol is a compound constructed out of cons cells.

symbol = (value . ((hash . name) . plist))
values = (symbol . () )
plist = () or (( key . value ) . plist)

values is a stack of symbol value definitions that you can push and pop using muse_pushdef() and muse_popdef().

muse_cell muse_csymbol ( const muse_char * sym )

Same as muse_symbol(), but takes a c-style null terminated unicode character string.

muse_cell muse_symbol_utf8	(	const char *	start,
		const char *	end
	)

Same as muse_symbol() except that it takes a UTF8 string.

muse_cell muse_csymbol_utf8 ( const char * sym )

Same as muse_symbol_utf8() except that it takes a c-style null terminated utf8 string.

muse_cell muse_builtin_symbol ( muse_builtin_symbol_t s )

Returns a symbol reference corresponding to the given symbol index.

This a convenience function.

See also:: muse_builtin_symbol_t

int muse_stack_pos ( )

Returns the current stack position.

You can subsequently unwind to the position by calling muse_stack_unwind(), passing the position as its argument.

A muse enviroment maintains a stack of cell references which will not be garbage collected the next time the gc is invoked. Every API function that uses muse_cons takes at least one new cell from the free list and places it on the stack. Such functions include muse_mk_int, muse_mk_float and family, the muse_list and related functions and so on - anything that will need to allocate a new cell.

Once a reference to a cell is placed into another cell, either by using muse_define on a named symbol, or by placing it in the property list of a named symbol or by adding it to a list that is itself protected by being on the stack, the stack space occupied by the cell can be released. This is done using muse_stack_unwind.

If a function does not allocate an unreferenced cell, but creates temporary cells, it should reset the stack position before it returns. This is typically done as follows -

 void my_func()
 {
     int sp = muse_stack_pos();
     / * ... code that allocates new cells ... * /
     muse_stack_unwind(sp);
 }

If a function returns as its result a newly constructed compound data structure referenced by a single muse_cell reference, it is advisable for it to place it on the stack, but release all other stack references to the constituent elements. For example -

 muse_cell my_make_blooper( int arg )
 {
     int sp = muse_stack_pos();
     muse_cell result = MUSE_NIL;
     / * .. compute the data structure and store the reference in "result". * /
       muse_unwind_stack(sp);
     muse_stack_push(result);
     return result;
 }

See also:: muse_stack_unwind, muse_stack_push

void muse_stack_unwind ( int stack_pos )

Unwinds the stack to the given position.

This discards all references to cells that have been kept on the stack. Temporary objects which were placed on the stack that aren't referred to elsewhere will be available for garbage collection.

See also:: muse_stack_pos

muse_cell muse_stack_push ( muse_cell obj )

Saves the given object on the stack so that it will not be garbage collected when gc is next invoked.

See also:: muse_stack_pos

void muse_gc ( int free_cells_needed )

Collects all the garbage cells - i.e.

unreferenced cells. Cells referenced on the various stacks including the symbol stack are not collected. muse_cons() automaticallly invokes this function when it cannot take a cell from the free list.

Parameters:

free_cells_needed

Tells the garbage collector to ensure that these many free cells are available after collection. If simply collecting unreferenced cells is insufficient, the collector will grow the heap by a sufficient amount. If this parameter is <= 0, it means muse environment is being destroyed and the gc call simply destroys all the specials.

void muse_mark ( muse_cell c )

Prior to garbage collection, muse_mark is called on all cells which are referenced somewhere and should not be garbage collected.

The unmarked cells are then swept into the free list.

muse_cell_t muse_cell_type ( muse_cell cell )

Returns the type of the cell data referenced by the given cell reference.

muse_boolean muse_isfn ( muse_cell cell )

Returns MUSE_TRUE if the given cell is a function

either native or lambda.

muse_cell muse_head ( muse_cell cell )

Returns the head of the cons cell referred to by the given cell reference.

Symbols, lambdas are also defined using cons cells, so this applies to those kinds of cells as well.

Applicable to cons cells, symbols, lambdas.

See also:: muse_tail

muse_cell muse_tail ( muse_cell cell )

Returns the tail of the cons cell referred to by the given cell reference.

Applies to symbols and lambdas in addition to cons cells because they are defined in terms of cons cells.

See also:: muse_head

muse_cell muse_tail_n	(	muse_cell	cell,
		int	n
	)

Returns the n-th tail of the given list.

 muse_tail_n( list, 0 )

is equivalent to

 list

The n-th element of an N-element list (n = 1, 2, 3, ..., N) can be obtained using

 muse_head( muse_tail_n( list, n-1 ) )

muse_cell muse_next ( muse_cell arg )

(next list) = For traversing lazy lists.

When given a lazy list producer function, it evaluates it and returns the head of the result.

When given a lazy list, it acts like cdr if the next item is a cons cell.

When given a lazy list where the cdr is a lazy list producer function, it evaluates the producer function and returns the result.

Note:: Subject to change!

muse_int muse_int_value ( muse_cell cell )

Given an integer or float cell, it returns the value cast to a 64-bit integer.

muse_float muse_float_value ( muse_cell cell )

Given an integer or float cell, it returns the value cast to a 64-bit float.

const muse_char* muse_text_contents	(	muse_cell	cell,
		int *	length
	)

Returns a pointer to the characters of the string referenced by the given cell.

If the length parameter is non-NULL, the length of the string is stored in that location.

const muse_char* muse_symbol_name ( muse_cell sym )

Returns the string name of the given symbol.

Can be used only with a named symbol. Invalid with an anonymous symbolm you'll get NULL.

muse_cell muse_symbol_value ( muse_cell sym )

Returns the top-most value of the symbol that's on the symbol's value stack.

int muse_list_length ( muse_cell list )

Returns the number of elements in the list.

The list must be a proper list - i.e. all tails must be cons cells and the tail of the last cell in the list must be MUSE_NIL.

muse_cell muse_list_last ( muse_cell list )

Returns the last cell of a list or () if the list is itself ().

For example if you have the list '(1 2 3 4), it'll return the cell which will print as (4).

muse_cell muse_list_append	(	muse_cell	head,
		muse_cell	tail
	)

Appends the tail list to the end of the head list and returns the head list.

The head list is thus destructively modified. If the head list is (), then the head list cannot be modified, so the tail list is returned as is.

muse_cell muse_array_to_list	(	int	count,
		const muse_cell *	array,
		int	astep
	)

Constructs a new list whose contents are that of the given array in the given order.

Parameters:

	count	The number of elements to extract from the array.
	astep	The step interval to reach the elements to extract. Typically, `astep` is 1.

muse_cell* muse_list_to_array	(	muse_cell	list,
		int *	lengthptr
	)

Constructs a new array with the contents of the list in the given order.

If you give a non-NULL lengthptr, the length of the array will be stored in it. You should free() the result array when you're done with it.

void muse_list_extract	(	int	count,
		muse_cell	list,
		int	lstep,
		muse_cell *	array,
		int	astep
	)

Extracts count elements from the list starting with the first element, into the given array.

List elements are extracted by stepping by lstep each time and array locations into which the extracted elements will be placed are obtained by stepping the array pointer by astep items for each element.

muse_cell muse_generate_list	(	muse_list_generator_t	generator,
		void *	context
	)

Creates a list whose contents are generated by the given generator function.

The generator function is called until it return "eol" or end-of-list. context is an arbitrary data pointer that's passed to the generator.

muse_cell muse_set_cell	(	muse_cell	cell,
		muse_cell	head,
		muse_cell	tail
	)

Sets the given cell's head and tail to the given cell references.

Works with symbols, lambdas, cons cells.

See also:: muse_set_head
muse_set_tail

muse_cell muse_set_head	(	muse_cell	cell,
		muse_cell	head
	)

Sets the head of the given cell.

See also:: muse_set_cell
muse_set_tail

muse_cell muse_set_tail	(	muse_cell	cell,
		muse_cell	tail
	)

Sets the tail of the given cell.

See also:: muse_set_cell
muse_set_tail

muse_cell muse_set_int	(	muse_cell	int_cell,
		muse_int	value
	)

Sets the integer value of an int cell.

muse_cell muse_set_float	(	muse_cell	float_cell,
		muse_float	value
	)

Sets the float value of a float cell.

muse_cell muse_set_text	(	muse_cell	text,
		const muse_char *	start,
		const muse_char *	end
	)

Copies the given string to the given text cell, modifying the cell's contents.

The previous contents of the cell are freed.

muse_cell muse_set_ctext	(	muse_cell	text,
		const muse_char *	start
	)

Same as muse_set_text, except that it takes a null terminated c-style string instead.

muse_cell muse_define	(	muse_cell	symbol,
		muse_cell	value
	)

Sets the value of the symbol.

The current top-most value of the symbol on the symbol's value stack is replaced.

See also:: muse_pushdef
muse_popdef

muse_cell muse_pushdef	(	muse_cell	symbol,
		muse_cell	value
	)

Makes the given value the current value of the symbol, without losing the previously assigned set of values.

i.e. It pushes the value on the symbol's value stack.

muse_cell muse_popdef ( muse_cell symbol )

Removes the current value on the symbol's value stack and returns it.

The cell used to hold a reference to the value is released immediately to the free list because it is not available to the language environment in normal circumstances, unless the program delves into the internal representation of symbols.

muse_cell muse_dup ( muse_cell obj )

Deep copies the given object.

muse_cell* muse_find_list_element	(	muse_cell *	list,
		muse_cell	element
	)

Searches for the given element in the given list and returns a reference to it.

Parameters:

	list	The list in which to search for the element. The first cell of the list is `*list`.
	element	The element to remove. The list item removed is one that satisfies muse_equal().

Returns:

If the element was found at the head of the list, it will return the value of list. If it was found elsewhere, then it will return a ptr such that muse_head(*ptr) is the element you searched for and you can remove the element with code like the following -

 muse_cell list, element;
 muse_cell *ptr = muse_find_list_element( &list, element );
 if ( ptr )
    *ptr = muse_tail(*ptr);

If the element could not be found, the return value is NULL.

int muse_eq	(	muse_cell	a,
		muse_cell	b
	)

Shallow compares two cells.

Two cells are "eq" if either they refer to the same cell, or they are equal intgers.

int muse_equal	(	muse_cell	a,
		muse_cell	b
	)

Deep compares two cells.

Returns:: 1 if the two cells are equal, 0 otherwise.

int muse_compare	(	muse_cell	a,
		muse_cell	b
	)

Deep compares two cells for ordering.

Returns:: 0 if the cells are eq, 1 if b < a and -1 if a < b.

muse_cell muse_symbol_plist ( muse_cell sym )

Returns the property list of the given symbol.

The symbol can be either a named symbol such as that created by the muse_symbol() class of functions, or an anonymous symbol created by muse_mk_anon_symbol().

muse_cell muse_assoc	(	muse_cell	alist,
		muse_cell	prop
	)

Looks up a particular association by key in an association list.

An association list has the form

 ((key1 . value1) (key2 . value2) ... (keyN . valueN))

When given a key keyK, it returns the pair

 (keyK . valueLK)

if the key can be found in the association list, or () if it doesn't exist in the list.

Note:: I'm considering changing this function to return the list whose head is the found key-value pair instead. This will let us search through an assoc list for all instances of a given key.

muse_cell* muse_assoc_iter	(	muse_cell *	alist,
		muse_cell	prop
	)

Similar to muse_assoc, except that the return value is not the kvpair, but the list position of the kvpair.

Since the return value is also an assoc list, you can iterate through the list using this function.

The reason the return value is given as a muse_cell* instead of simply a muse_cell is so that you can remove the found cell using a simple pointer setting operation, from the assoc list.

 muse_cell alist, prop;
 muse_cell *pos = muse_assoc_iter( &alist, prop );
 if ( pos )
 {
     (*pos) = muse_tail(*pos);
 }

muse_cell muse_get_prop	(	muse_cell	sym,
		muse_cell	prop
	)

Looks up the given property in the given symbol's property list.

The return value is the pair whose head is the property key and the tail is the property value.

muse_cell muse_put_prop	(	muse_cell	sym,
		muse_cell	prop,
		muse_cell	value
	)

Sets or adds the given property-value association to the symbol's property list.

If the property already exists in the symbol's plist, the value of the property is changed to the new one. If it doesn't exist, a new cell with the new association is created and added to the symbol's property list.

Returns:: The cell in the symbol's plist that contains the association.

muse_cell muse_load ( FILE * f )

Reads all symbolic expressions in the stream and evaluates them one by one, until end of stream.

Returns the result of evaluating the last s-expression in the stream.

Use this to load definitions from files.

muse_cell muse_eval ( muse_cell sexpr )

Evaluates the given symbolic expression.

Numbers, strings, native functions and lambda functions evaluate to themselves.
Quoted expressions evaluate to their unquoted forms.
A list is evaluated by evaluating the first element, interpreting it as a function to be supplied the rest of the list as arguments. If the first element is not a function, then the list evaluates to itself.

The result of the evaluation is usually protected by the stack if it is a newly allocated cell.

muse_cell muse_evalnext ( muse_cell * sexpr )

Evaluates the head of the list referred to by the given sexpr pointer and steps the pointer to the tail of the list, getting ready for the next call.

This is useful to evaluate arguments inside native functions.

muse_cell muse_eval_list ( muse_cell list )

Evaluates each element of the given list, builds a new list out of the results of the evaluations and returns the list.

muse_cell muse_apply	(	muse_cell	fn,
		muse_cell	args,
		muse_boolean	args_already_evaluated
	)

Applies the given native function or lambda to the given list of arguments and returns the result.

The arguments are not evaluated when passing them to a native function but are evaluated when passing to a lambda. Not evaluating the arguments for a native function lets us define syntaxes in native code. If you're passing already evaluated arguments in the args list, set the args_already_evaluated parameter to MUSE_TRUE.

See also:: muse_apply_lambda

muse_cell muse_do ( muse_cell block )

A block of code is a list of expressions to evaluate in sequence.

The result of evaluating a block is the result of evaluating the last expression in the block.

muse_cell muse_quote ( muse_cell args )

Returns the given arguments quoted.

The behaviour of quote is that

 s = muse_eval( muse_quote(s) )

muse_boolean muse_bind_formals	(	muse_cell	formals,
		muse_cell	args
	)

Binds the symbols in the given formals list to the corresponding values in the args list.

This recursive definition of muse_(un)bind_formals can perform arbitrary structure pattern matching between the formals specification and the given arguments.

For ex: A formals specification of

 ( (a b) (c . d) )

and an argument list with the structure

 ( (1 2) (3 4 5 6) )

will cause the bindings -

a = 1
b = 2
c = 3
d = (4 5 6)

Returns:: MUSE_TRUE if the match succeeded and MUSE_FALSE if some element failed. In case of failure, no variables are bound.

See also:

syntax_lambda

syntax_case

syntax_let

muse_cell muse_callcc ( muse_cell proc )

muse_int muse_hash ( muse_cell obj )

Hashes a given cell reference.

The hash has the property that if two cells have different hashes, they are not eq.

muse_int muse_hash_text	(	const muse_char *	start,
		const muse_char *	end,
		muse_int	initial
	)

A hash similar to muse_hash_data, but tailored for text.

muse_int muse_hash_data	(	const unsigned char *	start,
		const unsigned char *	end,
		muse_int	initial
	)

Creates a simple hash of the given data.

This hash is sufficient for strings, but not robust enough for arbitrary data. Use some other hash scheme if you want greater strength.

void* muse_tick ( )

Used for performance timing.

muse_tick() captures the current time and returns a handle containing the time information. Use it with muse_tock() to get the time elapsed between the two calls in microseconds.

muse_int muse_tock ( void * arg )

When passed the timing handle returned by muse_tick(), it returns the time elapsed between the muse_tick() call and this muse_tock() call in microseconds.

The handle becomes unusable after it is passed to muse_tock().

void muse_sleep ( muse_int time_us )

Sleeps the muse process for the given time in microseconds.

FILE* muse_fopen	(	const muse_char *	filename,
		const muse_char *	options
	)

A wrapper to the common fopen function so that we can call _wfopen if available, or the narrow version if the wide version isn't available.

const muse_char* muse_typename ( muse_cell thing )

Returns a non-mutable string describing the type of the thing passed as the parameter.

int muse_sprintf	(	muse_char *	buffer,
		int	maxlen,
		const muse_char *	format,
			...
	)

Formats a string consisting of the given format string with the other argument objects inserted at specified positions.

%m prints the next argument given as a muse_cell.
%t prints the type of the argument given as a muse_cell.
%i prints the cell index of the argument. This is like a pointer to the cell.
%s means the next argument is a unicode string and has to be included literally in the message.
%f means the next argument is a muse_float.
%d means the next argument is a muse_int.
%% prints the % character itself.

Returns:: The number of characters used in the buffer.

Todo:: The maxlen is not strictly adhered to and its good to give an extra 20 characters more than what you actually need. Needs to be fixed to be strict.

See also:: muse_vsprintf

void muse_message	(	const muse_char *	context,
		const muse_char *	message,
			...
	)

Displays a message string formatted according to the given message string with format codes.

The format codes are the same as for muse_sprintf().

Parameters:

message

A format string possibly containing codes indicating where and how to insert a string representation of further arguments.

See also:: muse_sprintf
muse_vsprintf

muse_boolean muse_expect	(	const muse_char *	context,
		const muse_char *	spec,
			...
	)

Checks whether a set of expectations are satisfied by some values.

The spec parameter is a string of condition characters that consume arguments and perform the appropriate tests. This function, which is itself a sort of mini language, is motivated by the fact that I've often coded ASSERT statements encoding multiple conditions that must be jointly satisfied in some way, having the assert fail, and not immediately knowing which of those conditions was responsible for the failure and the vales involved. If the entire set of expectations fails in some way, the generated error report (message box or stderr print out) is rather informative about which exact expectation was violated.

's' -> The next argument is a symbol (given as muse_cell) which will be used as the subject of subsequent tests. Its value will be used in any tests that may require it.

'v' -> The next argument is a value (given as a muse_cell) which will be used as the subject of subsequent tests. You can use this if you want to check some properties of a value which is not the value of any symbol you know. If you know the symbol, then use 's' in order to get better diagnostic messages.

':' -> The symbol must be defined to some value. The argument is expected to be a unicode string that describes what the symbol must be defined as. Ex: "a function", "a number", etc. This label is used in the message text.

'?' -> Next argument is int and the value of the symbol must be of that type - given by enum muse_cell_t.

'=' -> The symbol's value must be "eq" to the next argument, which is given as muse_cell.

'[' -> The next argument must be a muse_float and the symbol's value will be checked for >= the given limit.

']' -> The next argument must be a muse_float and the symbol's value will be checked for <= the given limit.

'(' -> The next argument must be a muse_float and the symbol's value will be checked for > the given limit.

')' -> The next argument must be a muse_float and the symbol's value will be checked for < the given limit.

"|blah|" -> The symbol must satisfy at least one of the conditions within the || pair. i.e. the conditions are "or"ed.

'!' -> Placing this character causes the result of the following test to be inverted. For example, a "not-defined" check can be encoded as "!:". The following test can be an or-block too.

muse_cell muse_similar_symbol	(	muse_cell	symbol,
		int *	outDistance
	)

Sometimes, it is useful to know whether another symbol that's very similar in textual representation from a known symbol.

For example, the user may make a spelling mistake in keying in a symbol and it'll be useful to know the alternative. You can use this function in such circumstances to determine the symbol that is very similar to the known symbol, yet different, so that you can warn the user about the closeness.

You can obtain the levenshtein distance measure between the two symbols if you supply an int pointer in outDistance. You can then use the distance measure to decide whether the similar symbol is worth bothering about.

muse_cell muse_symbol_with_value ( muse_cell value )

Searches the symbol table to find a symbol whose current value is the given cell.

The value's contents are not used in the comparison, but the symbol must actually contain this particular cell as its value. This function is useful to lookup a function name given a native function object. If a symbol exists with the given value, it is returned. Otherwise it returns MUSE_NIL.

Beware that the complexity of this operation is linear w.r.t. the number of symbols in the environment - defined or undefined.

int muse_unicode_to_utf8	(	char *	out,
		int	out_maxlen,
		const muse_char *	win,
		int	win_len
	)

Converts the given double-byte unicode string to multibyte UTF8 string.

Note that it'll place the terminating null character only if the output buffer can hold it as well.

Parameters:

	out	The output buffer to store the UTF8 string.
	out_maxlen	The maximum number of characters (bytes) that the output buffer can hold.
	win	The input wide character string.
	win_len	The number of input wide characters to convert.

Returns:: The number of bytes written to the output UTF8 buffer, excluding any terminating null character that we written.

int muse_utf8_to_unicode	(	muse_char *	wout,
		int	wout_maxlen,
		const char *	in,
		int	in_len
	)

Converts the given UTF8 string to double-byte unicode string.

Note that it'll place the terminating null character only if the output buffer can hold it as well.

Parameters:

	in	The input UTF8 encoded string.
	in_len	The number of bytes in the UTF8 string.
	wout	The output buffer to store the double byte unicode string.
	wout_maxlen	The maximum number of double-byte characters that can be written to the output buffer.

Returns:: The number of output *characters* written the buffer, excluding any terminating null character that might have been written.

int muse_utf8_size	(	const muse_char *	wstr,
		int	length
	)

Returns an estimate of the number of bytes (conservative upper bound) that might be needed to represent the given number of unicode characters using UTF8 encoding.

int muse_unicode_size	(	const char *	utf8,
		int	nbytes
	)

Returns an estimate (conservative upper bound) of the number of bytes that will be required to store the converted unicode version of the given utf8 string.

muse_cell muse_link_plugin	(	const muse_char *	path,
		muse_cell	arglist
	)

Loads a muse plugin DLL and calls its entry point function which is to have the name "muse_plugin_entry" and be of the type muse_plugin_entry_t.

The function must be declared extern "C" if defined in a CPP file and must be exported from the DLL.

The entry point function receives 3 arguments -

The first argument is the HMODULE of the loaded library.
The second argument is the muse environment pointer.
The third argument is an arbitrary argument list that can used for whatever purpose the plugin sees fit. The entry point function must call muse_set_current_env() with the given env pointer before calling any other muse functions.

Parameters:

	path	Path to the DLL file.
	arglist	Arg list passed to the entry point function.

See also:: muse_plugin_entry_t

void muse_repl ( )

The muSE REPL - Read-Eval-Print-Loop.

It reads symbolic expressions from standard input, evaluates them and writes the result of the evaluation to the standard output.

The only way to return from the function is to exit the program by typing

 (exit)

into the command line.

muse_cell muse_mk_functional_object	(	muse_functional_object_type_t *	type_info,
		muse_cell	init_args
	)

Creates a new functional object instance based on the given type information.

The type of the returned cell is a native function, so that the object can be used in the function position.

muse_functional_object_t* muse_functional_object_data	(	muse_cell	fobj,
		int	type_word
	)

Returns the data pointer of the functional object, or NULL if the object is not a functional object.

muse_port_t muse_port ( muse_cell p )

Takes a muSE port represented as a cell and returns the internal port object that it uses.

If the given thing is not a port, then it returns NULL.

muse_port_t muse_stdport ( muse_stdport_t descriptor )

muse_port_t muse_assign_port	(	FILE *	f,
		int	mode
	)

Creates a port definition that you can use to read/write stuff from a given file pointer.

The returned port is only for use by the API when it has a file pointer and must use the port calls such as muse_pread() several times on the same port.

Ports assigned using muse_assign_port must be released using muse_unassign_port.

Parameters:

	f	The file that the new port should read from.
	mode	A combination of `muse_port_mode_bits_t` indicating properties of the file port.

void muse_unassign_port ( muse_port_t p )

Unassigns a file port which was earlier assigned using muse_assign_port.

Should not be used with other ports.

muse_cell muse_pread ( muse_port_t f )

Reads the next symbolic expression at the current stream position, ignoring white space and comment lines.

Parameters:

The port from which the expression is to be read.

< Some error happened.

void muse_pwrite	(	muse_port_t	f,
		muse_cell	sexpr
	)

Writes the given s-expression to the given stream.

If the expression contains only basic objects such as numbers, lists and symbols, then output of write is suitable to read back by muse_pread(). Otherwise, the only difference between write and print is that write encloses strings in quotes and print doesn't.

void muse_pprint	(	muse_port_t	port,
		muse_cell	sexpr
	)

muse_cell muse_mk_vector ( int length )

Creates a new vector object that has enough slots allocated to hold the given number of objects.

All slots are initialized to MUSE_NIL.

int muse_vector_length ( muse_cell vec )

Returns the number of slots the vector has.

muse_cell muse_vector_get	(	muse_cell	vec,
		int	index
	)

Returns the value occupying the slot at the given 0-based index.

muse_cell muse_vector_put	(	muse_cell	vec,
		int	index,
		muse_cell	value
	)

Replaces the value in the slot at the given index with the new value.

muse_cell muse_mk_hashtable ( int length )

Creates a hashtable with a bucket count setup according to the given desired length.

Note that calling muse_hashtable_length() without first putting anything into the hashtable will always get you 0. The "length" of the hashtable is the number of key-value pairs put into it.

int muse_hashtable_length ( muse_cell ht )

Returns the number of key-value pairs put into the hash table.

muse_cell muse_hashtable_get	(	muse_cell	ht,
		muse_cell	key
	)

Returns the key-value pair with the given key as the head if the key is present in the hash table, otherwise it returns MUSE_NIL.

The value associated with the key will be in the tail of the returned pair.

muse_cell muse_hashtable_put	(	muse_cell	ht,
		muse_cell	key,
		muse_cell	value
	)

Associates the given value with the given key in the hash table.

The given value replaces any previous value that might have been associated with the key.

Generated on Mon Sep 25 23:12:48 2006 for muSE by

1.4.7

Embedding API for the Muse language.

Data Structures

Cell access

Dynamically loading plugins

Ports API

Managing the muse environment.

Basic memory management

Cell editing

Property lists

I/O

Evaluation

Misc

Diagnostics

Multilingual stuff

REPL - Read Eval Print Loop

Extending muSE with functional objects

Vectors

Hashtables

Typedefs

Enumerations

Detailed Description

The muSE environment

The basic data types in muSE

The cons cell

Symbols

S-Expressions

Reading and writing s-expressions

Typedef Documentation

Enumeration Type Documentation

Function Documentation