fpl.doc

类PASCAL语言的编译器,LINUX环境的,我没试过是否正确.

TABLE OF CONTENTS

fpl.library/fplAddFunction
fpl.library/fplAddVariable
fpl.library/fplAlloc
fpl.library/fplAllocString
fpl.library/fplAlloca
fpl.library/fplCloseLib
fpl.library/fplConvertString
fpl.library/fplDealloc
fpl.library/fplDealloca
fpl.library/fplDelFunction
fpl.library/fplExecuteFile
fpl.library/fplExecuteScript
fpl.library/fplFree
fpl.library/fplFreeString
fpl.library/fplGetErrorMsg
fpl.library/fplInit
fpl.library/fplLtostr
fpl.library/fplOpenLib
fpl.library/fplReference
fpl.library/fplReset
fpl.library/fplSend
fpl.library/fplStrtol
fpl.library/fplStrtol                                 fpl.library/fplStrtol

   NAME
	fplStrtol -- convert a string holding a number to a long integer.

   SYNOPSIS
	long fplStrtol( string, base, end);			(V8)
	D0		A0      D0    D1

   FUNCTION
	Converts a string representation of a number to a long integer.
	The convertion will use the supplied base or if zero (0) is specified,
	it will scan the string and figure out the base itself. The recognized
	prefixes are the FPL standard; '0' for octal numbers, '0x' for
	hexadecimal and '0b' for binary.
	The 'end' parameter is a supplied pointer to a char pointer in which
	the position of the final parse position will be stored.

   RESULT
	The long integer the string was converted to!

   INPUTS
	char *string	- Pointer to the string to convert!
	long base	- Base to use when the convertion is performed
	char **end	- Pointer to a char pointer in where to store the
			  position of the end of the convertion.

   SEE ALSO
	fplLtostr and the strtol() function in FPLuser.guide

fpl.library/fplLtostr                               fpl.library/fplLtostr

   NAME
	fplLtostr -- convert a long integer to a string.

   SYNOPSIS
	char *fplLtostr( key, base, number);			(V8)
	D0               A0   D0    D1

   FUNCTION
	Converts the inpute 'number' using the 'base' parameter. The result
	will be returned as a pointer to a stringm or NULL is something
	failed. Each call to this function must have a matching call to the
	fplFreeString() function.

   RESULT
	A pointer to a zero terminated string or NULL if the function failed.
	The returned string must be freed with a call to fplFreeString().

   INPUTS
	void *key	- Return value from fplInit().
	long base	- Base to use when converting.
	long number	- Number to create a string from.

   SEE ALSO
	fplStrtol and the ltostr() function in FPLuser.guide

fpl.library/fplConvertString                     fpl.library/fplConvertString

   NAME
	fplConvertString -- convert FPL string to binary.

   SYNOPSIS
	long fplConvertString( key, convert, buffer );		(V4)
	D0		       A0   A1       A2

   FUNCTION
	Convert a FPL syntax string to a binary string. *ALL* in FPL allowed
	backslash sequences are supported. The string to convert should be a
	zero terminated string.

	The output will be stored in the buffer given as input. FPL also adds
	a terminating zero to the output string.

   RESULT
	The number of characters in the output string. The terminating zero
	excluded.

   INPUTS
	void *key	- Return value from fplInit().
	vhar *convert	- String to convert to binaries.
	char *buffer	- Pointer to buffer large enough to hold the resulting
			  string plus an additional zero terminate byte.

fpl.library/fplExecuteScript                     fpl.library/fplExecuteScript

   NAME
	fplExecuteScript -- execute an FPL program.
	fplExecuteScriptTags -- execute an FPL program.

   SYNOPSIS
	long fplExecuteScript( key, program, lines, tags );
	D0       	       A0   A1	     D0     A2

	For SAS/C users:
	long fplExecuteScriptTags( key, program, lines, ... );

   FUNCTION
	This function executes the program (array of char pointers) pointed
	to by the program parameter according to the rules set by the
	call to fplInit(). Each line must end with a zero (0) byte.
	If any error occurs, the function returns proper error code (see
	FPL.h).

	If the program is started and is expected only to run once and then to
	be removed from memory, use the FPLTAG_STOREGLOBALS tag to disable any
	global symbol storage.

	The tag list pointer is new for V3.

   TAGS
	FPLTAG_INTERPRET
	  This data is interpreted after all declaring and prototyping has been
	  done in the FPL program. NULL will disable. Mainly implemented to
	  enable single function invokes within a larger program. The data of
	  this tag is to be looked upon as a string argument to an interpret()
	  function call. After this interpret() call, the FPL program will
	  exit.
		This example calls only the function named foobar (with 2 and 3
		as parameters) within the much larger program:

		unsigned long tags={
		  FPLTAG_INTERPRET, "foobar(2, 3);", FPLTAG_DONE
		};
		fplExecuteScript(anchor, programarray, 200, tags);

	  NOTE: This intepreted statement will act *EXACTLY* as if it is
	  interpreted by the program right before the actual start of the main
	  program. If you call any inside function, it *must* be prototyped
	  properly first or else this will fail!

	  HINT: This enables a beautilful way for us to send arguments to the
	  FPL functions. By making the main function including prototyping just
	  as any other function. Invoke the following example with the tag
	  {FPLTAG_INTERPRET, "main(22, \"Daniel\");"} and you see my point!
		Example:

		int main(int, string);
		exit(-1);	/* just to prevent normal starts */
		int main(int age, string name)
		{
		   output(name " is " age " years old!\n");
		}


	FPLTAG_STARTPOINT.
	  By setting this pointer you can force FPL to start interpreting at
	  another position than from the start of the program. If this start
	  position is on any other line than the first, FPLTAG_STARTLINE must
	  be set too.

	FPLTAG_STARTLINE
	  Set this only if you set the FPLTAG_STARTPOINT tag. By only setting
	  this tag, you achieve nothing but confusing the interpreter.

	  NOTE regarding these upper two tags: when changing the interpreting
	  start position you must think of that the variable declarations
	  and/or function prototyping that may be written in the original
	  start of program might get passed.

	FPLTAG_USERDATA
	  Does the same as when used in fplInit() or fplReset().

	FPLTAG_CACHEFILE
	  Turn on or off FPL caching of this file. Default is set with the
	  'FPLTAG_CACHEALLFILES' in a fplInit() or a previous fplReset()
	  call. Its default is FPLCACHE_NONE.

	  Cashing can be done in three ways:
	  FPLCACHE_NONE    - Will never ever cache a file
	  FPLCACHE_ALWAYS  - Will cache files that have one or more global
			     symbols
	  FPLCACHE_EXPORTS - Will only cache files that have exported symbols.

	  NOTE: Files that do not declare any global symbols will not be
	  cached, no matter what this tag says!

	FPLTAG_FILEGLOBALS/FPLTAG_ISCACHED
	  Supply this tag a pointer to a `long'. This variable will tell if the
	  progam declared any global symbols, which is the same as if it is to
	  be cached. The long will contain zero if no global symbols were
	  declared or non-zero if a not known number of variables were
	  declared.

	FPLTAG_PROGNAME
	  Name of the FPL program. When using multiple FPL source files it is
	  almost required to use this tag. If any error occurs when running
	  FPL, the FPLSEND_GETPROGNAME will receive a pointer to the program
	  name (or "<unknown program>" if it is never set). fplExecuteFile()
	  sets the program name by default to the file name. Programs without
	  names can never be cached!

	FPLTAG_FILENAMEGET
	  Tells FPL that when this file has been flushed, the program can be
	  found by using the program name as file name to read from. Set as
	  default be fplExecuteFile().

	FPLTAG_STRING_RETURN					(V6)
	  Supply a pointer to a char pointer. This enables the started FPL
	  programs to return a string to you. The string can be returned from
	  the main (highest) level of the FPL program with "return" or from
	  any level with "exit". The string will be readable just like any
	  regular string from FPL. The FPL_STRLEN macro will give to the
	  length of the returned string.

	  Programs that are executed with this tag set will not be able to
	  return any other data than a string! Using the FPLSEND_GETRETURNCODE
	  tag in a fplSend() call will not return a valid number!

	  The string is to be treated exactly as fplAllocString() strings:
	  you must fplFreeString() it when you have finished using it. The
	  string can even be used with the FPLSEND_DONTCOPY_STRING tag to
	  the fplSend() call!

	FPLTAG_REREAD_CHANGES					(V8)
	  Suppy a boolean to switch this on/off for this script/file. When
	  enabled this file is attempted to be ran and the actual file has
	  been changed on disk, all symbols declared in the file will be
	  removed and the new version will be loaded and run instead.

	  * Default for this state is set with the same tag to fplInit().
	  * This can be forced on/off with the pragmas 'reread' and 'noreread'
	    inside the FPL program.
	  * This tag will only be of use for calls to fplExecuteFile().

	FPLTAG_FLUSH_NOT_IN_USE					(V8)
	  Suppy a boolean to switch this on/off for this script/file. When
	  enabled, and this file isn't in use, the program will be flushed
	  from memory and read into memory again when accessed.

	  * Default for this state is set with the same tag to fplInit().
	  * This can be forced with the pragmas 'cache' and 'nocache'
	    inside the FPL program. They force the file to remain in memory
	    or not.

	FPLTAG_KIDNAP_CACHED					(V9)
	  (This is only usful in calls to fplExecuteScript().)
	  Suppy a boolean to switch this on/off for this script/file. When
	  enabled, FPL will duplicate all programs that should be cashed.
	  By default, FPL will simply use the supplied program pointer,
	  whether the program is cached or not. By using this tag, the host
	  program can do whatever it wants with the memory after an execution,
	  if if the program was cached.

	  * Default for this state is set with the same tag to fplInit().

	FPLTAG_DEBUG						(V9)
	  Suppy a boolean to switch this on/off for this script/file. When
	  enabled, FPL runs the program/script in 'debug mode'. Debug mode
	  enables certain hooks and control stuff that wouldn't be done
	  otherwise, and also always an external debugger to supervise the
	  execution. "FPLdb" will be available in the future to provide a
	  debugger for FPL usage on Amiga. The local status for debug mode
	  can be altered and set with the debug() internal FPL function.

	  * Default for this state is set with the same tag to fplInit().

	FPLTAG_ISOLATE						(V13.7)
	  Suppy a boolean to switch this on/off for this script/file. When
	  enabled, FPL runs the program/script in 'protected mode', isolated
	  from other previously run FPL programs. Isolated programs cannot
	  access nor declare exported symbols. Symbols declared as 'export'
	  when 'isolate' is active, will be made like ordinary globals.

   RESULT
	The error number, or zero (0) if everything was ok.

   INPUTS
	void *key		- Return value from fplInit().
	char **program		- The FPL program to execute.
	long lines		- Number of lines in the program.
	unsigned long *tags 	- Pointer to a tag list.

   SEE ALSO
	fplExecuteFile

fpl.library/fplExecuteFile                       fpl.library/fplExecuteFile

   NAME
	fplExecuteFile -- execute a file as an FPL program.
	fplExecuteFileTags -- execute a file as an FPL program.

   SYNOPSIS
	long fplExecuteFile( key, filename, tags );
	D0  		     A0	  A1        A2

	For SAS/C users:
	long fplExecuteFileTags( key, filename, ... );

   FUNCTION
	This function executes the file with the name pointed to by the
	filename parameter according to the rules set by the fplInit()
	function call. If any error occurs, the subroutine returns.
	The program is loaded into memory before execution. If the program
	didn't export any functions or if it shouldn't be cached, it will be
	unloaded when the program exits.

	fplExecuteFile() will internally read the given file and then call
        fplExecuteScript().

   TAGS
	The tags are the same as for fplExecuteScript().

   RESULT
	The error number, or zero (0) if everything was ok.

   INPUTS
	void *key		- Return code from fplInit().
	char *filename		- Pointer to the filename.
	unsigned long *tags 	- Pointer to a tag list.

   SEE ALSO
	fplExecuteScript()

fpl.library/fplGetErrorMsg                        fpl.library/fplGetErrorMsg

   NAME
	fplGetErrorMsg -- get error message from error number.

   SYNOPSIS
	char *fplGetErrorMsg( key, errnum, buffer );
	D0      	      A0   D0      A1

   FUNCTION
	To get a verbose error message from the error number returned by
	fplExecuteScript() or fplExecuteFile().
	Giving this function a error number out of range, will cause the
	library to return "Unknown" error. The buffer given to hold the error
	message must be at least FPL_ERRORMSG_LENGTH bytes long.

   NOTE
	This should since V9 be replaced with the FPLTAG_ERROR_BUFFER tag to
	fplInit()!

   RESULT
	A pointer to a zero terminated string.

   INPUTS
	void *key	- The return code of the initial fplinit() call.
	long errnum	- Error number to get error message for.
	char *buffer	- Buffer to store message in.

   SEE ALSO
	fplExecuteScript(), fplExecuteFile()

fpl.library/fplAddFunction                   fpl.library/fplAddFunction

   NAME
	fplAddFunction -- add function to be recognized by FPL.
	fplAddFunctionTags -- add function to be recognized by FPL.

   SYNOPSIS
	long fplAddFunction( key, name, ID, ret, format, tags );
	D0                   A0   A1    D0  D1   A2      A3