script3.h

GNU ccScript is a C++ class framework for creating a virtual machine execution system for use with a

// Copyright (C) 1999-2005 Open Source Telecom Corporation.
//  
// This program is free software; you can redistribute it and/or modify
// it under the terms of the GNU General Public License as published by
// the Free Software Foundation; either version 2 of the License, or
// (at your option) any later version.
// 
// This program is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
// GNU General Public License for more details.
//
// You should have received a copy of the GNU General Public License
// along with this program; if not, write to the Free Software 
// Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
// 
// As a special exception, you may use this file as part of a free software
// library without restriction.  Specifically, if other files instantiate
// templates or use macros or inline functions from this file, or you compile
// this file and link it with other files to produce an executable, this
// file does not by itself cause the resulting executable to be covered by
// the GNU General Public License.  This exception does not however
// invalidate any other reasons why the executable file might be covered by
// the GNU General Public License.
//
// This exception applies only to the code released under the name GNU
// ccScript.  If you copy code from other releases into a copy of GNU
// ccScript, as the General Public License permits, the exception does
// not apply to the code that you add in this way.  To avoid misleading
// anyone as to the status of such modified files, you must delete
// this exception notice from them.
//
// If you write modifications of your own for GNU ccScript, it is your choice
// whether to permit this exception to apply to your modifications.
// If you do not wish that, delete this exception notice.
//

/**
 * @file script3.h
 * @short Threaded step execute scripting engine framework.
 **/


#ifndef	CCXX_SCRIPT3_H_
#define	CCXX_SCRIPT3_H_

#ifndef	CCXX_MISC_H_
#include <cc++/misc.h>
#endif

#ifndef	CXXX_FILE_H_
#include <cc++/file.h>
#endif

#ifndef	CCXX_BUFFER_H_
#include <cc++/buffer.h>
#endif

#define TRAP_BITS (sizeof(unsigned long) * 8)
#define	SCRIPT_INDEX_SIZE KEYDATA_INDEX_SIZE
#define	SCRIPT_MAX_ARGS	250
#define	SCRIPT_TEMP_SPACE 16
#define	SCRIPT_STACK_SIZE 32
#define	SCRIPT_ROUTE_SLOTS 16
#define	SCRIPT_EXEC_WRAPPER
#define	SCRIPT_APPS_WRAPPER
#define	SCRIPT_RIPPLE_LEVEL 2
#define	SCRIPT_BINDER_SELECT
#define	SCRIPT_SERVER_PREFIX
#define	SCRIPT_DEFINE_TOKENS

#ifndef CCXX_PACKING
#if defined(__GNUC__)
#define CCXX_PACKED
#elif !defined(__hpux) && !defined(_AIX)
#define CCXX_PACKED
#endif
#endif  

namespace ost {

class __EXPORT ScriptRegistry;
class __EXPORT ScriptCommand;
class __EXPORT ScriptImage;
class __EXPORT ScriptInterp;
class __EXPORT ScriptSymbols;
class __EXPORT ScriptProperty;
class __EXPORT ScriptThread;
class __EXPORT ScriptCompiler;

/**
 * Generic script class to hold master data types and various useful
 * class encpasulated friend functions.
 *
 * @author David Sugar <[e-mail]>
 * @short Master script class.
 */
class __EXPORT Script
{
public:
	class __EXPORT Line;
	class __EXPORT Name;

	typedef bool (ScriptInterp::*Method)(void);
	typedef const char *(ScriptCommand::*Check)(Line *line, ScriptImage *img);
	typedef bool (*Cond)(ScriptInterp *interp, const char *v);
	typedef long (*Function)(long *args, unsigned prec);
	typedef const char *(*Meta)(ScriptInterp *interp, const char *token);
	typedef const char *(*Parse)(ScriptCompiler *img, const char *token);
	typedef void (*Init)(void);

	enum scrAccess
	{
		scrPUBLIC,
		scrPROTECTED,
		scrPRIVATE,
		scrFUNCTION,
		scrLOCAL
	};

	typedef enum scrAccess scrAccess;
		
	enum symType
	{
		symNORMAL = 0,
		symCONST,
		symDYNAMIC,
		symFIFO,
		symSEQUENCE,
		symSTACK,
		symCOUNTER,
		symPOINTER,
		symREF,
		symARRAY,
		symASSOC,
		symINITIAL,
		symNUMBER,
		symLOCK,
		symPROPERTY,
		symORIGINAL,
		symMODIFIED,
		symTIMER
	};

	typedef enum symType symType;

	typedef struct _symbol
	{
		struct _symbol *next;
		const char *id;
		unsigned short size;
		symType type: 8;
		char data[1];
	}	Symbol;

#ifdef CCXX_PACKED
#pragma	pack(1)
#endif

	typedef struct _array
	{
		unsigned short head, tail, rec, count;
	}	Array;

#ifdef	CCXX_PACKED
#pragma pack()
#endif

public:
	class __EXPORT Line
	{
	public:
		Line *next;
		union
		{
			ScriptRegistry *registry;
			Method method;
			Name *name;
		}	scr;
		const char *cmd, **args;
		unsigned long cmask, mask;
		unsigned short loop, line, lnum;
		unsigned short argc;
	};

	class __EXPORT NamedEvent
	{
	public:
		NamedEvent *next;
		Line *line;
		char type;
		const char *name;
	};

	class __EXPORT Name
	{
	public:
		Name *next;
		NamedEvent *events;
		Line *first, *select;
		Line *trap[TRAP_BITS];
		unsigned long mask;
		const char *name, *filename;
		scrAccess access;
	};

        class __EXPORT Initial
        {
        public:
                const char *name;
                unsigned size;
                const char *value;
        };

        class __EXPORT Define
        {
        public:
                const char *keyword;
		bool init;
                Method method;   
                Check check; 
        };

        class __EXPORT Test
        {
        public:
                const char *id;
                Cond handler;
                Test *next;  
        };

	class __EXPORT Fun
	{
	public:
		const char *id;
		unsigned args;
		Function fn;
		Fun *next;
	};

	class __EXPORT InitScript
	{
	public:
		Init handler;
		InitScript *next;
	};	

	class __EXPORT Package : public DSO
	{
	public:
		static Package *first;
		Package *next;
		const char *filename;
	
		Package(const char *name);
	};

	static bool fastStart;
	static bool useBigmem;
	static unsigned fastStepping;
	static unsigned autoStepping;
	static size_t pagesize;
	static unsigned symsize;
	static unsigned symlimit;

	static bool isScript(Name *scr);
	static bool isSymbol(const char *id);
	static bool use(const char *name);
	static unsigned getIndex(const char *id);
	static Symbol *deref(Symbol *sym);
	static bool commit(Symbol *sym, const char *value);
	static bool append(Symbol *sym, const char *value);
	static bool symindex(Symbol *sym, short offset);
	static const char *extract(Symbol *sym);
	static unsigned count(Symbol *sym);
	static unsigned storage(Symbol *sym);
	static void clear(Symbol *sym);
	static char decimal;
	static bool use_definitions;
	static bool use_macros;
	static bool use_prefix;
	static bool use_merge;
	static bool use_funcs;
	static const char *plugins;
	static const char *altplugins;
	static const char *access_user;
	static const char *access_pass;
	static const char *access_host;
	static bool exec_funcs;
	static const char *exec_extensions;
	static const char *exec_token;
	static const char *exec_prefix;
	static const char *exit_token;
	static const char *apps_extensions;
	static const char *apps_prefix;

	static const char *etc_prefix;
	static const char *var_prefix;
	static const char *log_prefix;

        static void addFunction(const char *name, unsigned count, Function i);
        static void addConditional(const char *name, Cond test);

	static bool isPrivate(Name *scr);
	static bool isFunction(Name *scr);

protected:        
        static Test *test;
        static Fun *ifun;
        
};

class __EXPORT ScriptSymbols : public MemPager, public Script
{
protected:
	Symbol *index[SCRIPT_INDEX_SIZE + 1];

	void purge(void);

public:
	ScriptSymbols();
	~ScriptSymbols();

	inline const char *cstring(const char *str)
		{return MemPager::alloc(str);};

	unsigned gathertype(Symbol **idx, unsigned max, const char *prefix, symType group);
	unsigned gather(Symbol **idx, unsigned max, const char *prefix, const char *suffix);
	Symbol *find(const char *id, unsigned short size = 0);
	Symbol *make(const char *id, unsigned short size);

	Symbol *setReference(const char *id, Symbol *target);
};

/**
 * This class holds the bound keyword set for a given Bayonne style
 * script interpreter.  Application specific dialects are created
 * by deriving a application specific version of ScriptCommand which
 * then binds application specific keywords and associated methods
 * in an application derived ScriptInterp which are typecast to
 * (scriptmethod_t).
 *
 * @author David Sugar <[e-mail]>
 * @short Bayonne script keyword binding tables and compiler constants.
 */
class __EXPORT ScriptCommand : public Keydata, public Mutex, public Script
{
private:
	friend class __EXPORT ScriptImage;
	friend class __EXPORT ScriptInterp;
	friend class __EXPORT ScriptCompiler;
	friend class __EXPORT ScriptBinder;

#ifdef	CCXX_PACKED
#pragma pack(1)
#endif

	typedef struct _keyword
	{
		struct _keyword *next;
		Method method;
		Check check;
		bool init : 1;
		char keyword[1];
	}	Keyword;

#ifdef	CCXX_PACKED
#pragma pack()
#endif

	ThreadQueue *tq;
	Keyword *keywords[SCRIPT_INDEX_SIZE];
	char *traps[TRAP_BITS];
	ScriptImage *active;
	unsigned keyword_count;
	unsigned trap_count;
	unsigned long imask;
	unsigned dbcount;
	void *dbc;

protected:
	bool ripple;
	unsigned activity;	// activity counter
	static ScriptCommand *runtime;

	virtual const char *getExternal(const char *opt);

public:
	/**
	 * Checks if the line statement is an input statement.  Used in
	 * some servers...
	 *
	 * @return true if line is input.
	 * @param line to examine.
	 */
	virtual bool isInput(Line *line);

	/**
	 * Get the method handler associated with a given keyword.  This
	 * is used by ScriptImage when compiling.
	 *
	 * @param keyword to search for.
	 * @return method handler to execute for this keyword.
	 */
	Method getHandler(const char *keyword);

	/**
	 * Issue a control event against current image for attached
	 * modules until claimed.
	 *
	 * @param args list of control command and arguments.
	 * @return true if processed.
	 */
	bool control(char **args);

	/**
	 * Get the active script.
	 *
	 * @return pointer to active script image.
	 */
	inline ScriptImage *getActive(void)
		{return active;};

	/**
	 * Get the name of a trap from it's id.
	 *
	 * @param id of trap.
	 * @return name of trap.
	 */
	const char *getTrapName(unsigned id);

	/**
	 * Alias use modules...
	 *
	 * @param id to alias.
	 * @param id to use.
	 */
	void aliasModule(const char *id, const char *use);

protected:
	/**
	 * Fetch whether the given keyword is valid for constructor.
	 *
	 * @param keyword to search for.
	 * @return init flag.
	 */
	bool isInitial(const char *keyword);

	/**
	 * Check keyword syntax.
	 *
	 * @return syntax error string or NULL.
	 * @param command name of keyword to check.
	 * @param line pointer to line being compiled.
	 * @param img pointer to image being compiled.
	 */
	const char *check(char *command, Line *line, ScriptImage *img);

	/**
	 * Get the trap id number associated with a trap name.
	 *
	 * @return trap id number, 0 (exit) if invalid.
	 * @param name of trap identifier.
	 */
	virtual unsigned getTrapId(const char *name);

	/**
	 * Get the mask bits for the default script.
	 *
	 * @return trap mask to use.
	 */
	virtual unsigned long getTrapDefault(void);

	/**
	 * Get the mask bits for a trap "handler".
	 *
	 * @return script object of trap mask to use.
	 */
	virtual unsigned long getTrapHandler(Name *script);
  
	/**
	 * Get a trap mask for a given identifer.  This is a virtual
	 * since some derived handlers may manipulate mask bits.
	 *
	 * @return signal bit mask based on id number.
	 * @param id number of trap mask.
	 */
	virtual unsigned long getTrapMask(unsigned id);

	/**
	 * A helper method for the compiler.  Converts a named
	 * trap into it's bit shifted mask.  By making it a virtual,
	 * derived dialects can add "aliases" to default trap names.
	 *
	 * @param name of trap identifier.
	 * @return bit shifted mask or 0 if invalid.
	 */
	virtual unsigned long getTrapModifier(const char *name);

	/**
	 * A helper method for the compiler used specifically for
	 * "^" trap subsection requests.  These will occasionally
	 * carry different attribute settings.
	 *
	 * @param name of trap identifier.
	 * @return bit shifted mask or 0 if invalid.
	 */
	virtual unsigned long getTrapMask(const char *name);

	/**
	 * Test current command to see if it uses keyword syntax.
	 *
	 * @return true if keyword syntax used.
	 * @param line record to examine in check routine.
	 */
	static bool hasKeywords(Line *line);

public:
	/**
	 * Test for a specific keyword.
	 *
	 * @return content of keyword that is found.
	 * @param line pointer to record to examine in check routine.
	 * @param keyword to search for.
	 */
	static const char *findKeyword(Line *line, const char *keyword);

	/**
	 * Server level logging interface override.
	 *
	 * @param level of log message.
	 * @param text of message.
	 */
	virtual void errlog(const char *level, const char *text);

public:
	/**
	 * Test current command against a list of valid keywords.
	 *
	 * @return first keyword found not in list.
	 * @param line record to examine in check routine.
	 * @param list of =xxx keyword entries.
	 */
	static bool useKeywords(Line *line, const char *list);

	/**
	 * Count non-keyword arguments.
	 *
	 * @return number of non-keyword arguments.
	 * @param line record to examine.
	 */
	static unsigned getCount(Line *line);

	/**
	 * Get the member id code of a line.
	 *
	 * @return member id code.
	 * @param line record to examine in check routine.
	 */
	static const char *getMember(Line *line);


protected:
	/**
	 * Check the member list.
	 *
	 * @return true if member found or none.
	 * @param line record to examine in check routine.
	 * @param list of .members...
	 */
	static bool useMember(Line *line, const char *list);

	/**
	 * Get an option to examine in check routine.
	 *
	 * @return option or NULL if past end of line record.
	 * @param line record pointer to line to examine.
	 * @param index pointer to index value.  Start at 0.
	 */
	static const char *getOption(Line *line, unsigned *index);

	/**
	 * Load a set of keywords into the system keyword table.  This
	 * provides a convenient method of initializing and adding to
	 * the keyword indexes.
	 *
	 * @param keywords defined pair entries to load.
	 */
	void load(Script::Define *keywords);