muse.h File Reference

#include <stdio.h>
#include <wchar.h>
#include "muse_platform.h"

Include dependency graph for muse.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
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...
struct	muse_monad_view_t
	A monad view (id = 'mnad') provides higher order functional operations over collections. 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

Author:

Srikumar K. S. (mailto:kumar@muvee.com)

Copyright (c) 2006 Jointly owned by Srikumar K. S. and muvee Technologies Pte. Ltd.

All rights reserved. See LICENSE.txt distributed with this source code or http://muvee-symbolic-expressions.googlecode.com/svn/trunk/LICENSE.txt for terms and conditions under which this software is provided to you.

---