fpl.doc

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

	For SAS/C users:
	long fplAddFunctionTags( key, name, ID, ret, format, ... );

   FUNCTION
	This function adds a function to the FPL internal list of functions
	to accept. All data pointed to by the different pointers here, must
	remain unmodified (or at least existent, they may be changed any time
	but the proper syntax must be respected) while FPL runs.

	DO NOT add function identifiers with names longer than 64 characters.
	Such function won't be recognized in an FPL program.

	This function will be remembered as a function by FPL until fplFree()
	(or fplDelFunction() naming this function) is invoked.

	To achieve dynamic function names which might change during the
	execution or from one execution time to the next, you can call this
	function whenever you please and the function will be accepted when FPL
	gets control again. To remove a function, use fplDelFunction(). You
	can do this at _any_ time, even in the middle of an execution!)

	If you want to add a function with the same name as an internal
	function, or simply replace it, just fplDelFunction() the internal
	function and then add your own using that name!

   TAGS
	* FPLTAG_FUNCDATA. This data is readable in the ->funcdata member of
	  the fplArgument structure whenever this function is invoked. This
	  gives you a great chance to pass local data between here and your
	  interface function.

	* FPLTAG_FUNCTION. This is a function specific function pointer to be
	  called when this function is found in the FPL program. This enables
	  unique function calls for each function you add to FPL. The function
	  specified is called with the same argument and permissions as the
	  `global' interface function.

   RESULT
	Zero if success, error code if failure.

   INPUTS
	void *key	- This is the data received from the initial
			  fplInit() function call.

	char *name	- Pointer to a zero terminated string holding the
			  name of the function to add.

	long ID		- Function ID. May be set to whatever you please to
			  speed up function checks in the interface function.
			  All subzero values are reserved for FPL use and
			  calls.

	char ret	- FPL_STRARG or FPL_INTARG depending on if this
			  function is to return a string or an int to the
			  caller. FPL_OPTARG means that the function can
			  return either a string or an int. The return type
			  is determined by FPL at run time, and you help a
			  lot by *always* returing values from such functions
			  since each fplSend() will tell FPL the kind of the
			  return value.

	char *format	- This is a pointer to a zero terminated array holding
			  the argument specifiers for this function. You can
			  make your function receive for types of arguments:
			  strings, integers, string variables or integer
			  variables. You can also specify optional parameters
			  and/or parameter list. Available argument types are
			  - 'S' (required 'string')
			  - 's' (optional 'string')
			  - 'I' (required 'int')
			  - 'i' (optional 'int')
			  - 'O' (required 'S' or 'I')
			  - 'o' (optional 's' or 'i')
			  - '>' (optional number of the previous type
			        can be specified)

			  From version 9, these are also available:
			  - 'N' (required 'int' reference)
			  - 'n' (optional 'int' reference)
			  - 'C' (required 'string' reference)
			  - 'c' (optional 'string' reference)
			  - 'R' (required 'N' or 'C')
			  - 'r' (optional 'n' or 'c')
			  - 'A' (required 'S', 'I', 'N' or 'C')
			  - 'a' (optional 's', 'i', 'n' or 'c')

			  From version 10, these are also available:
			  - 'B' (required 'string array reference')
			  - 'b' (optional 'string array reference')
			  - 'D' (required 'int array reference')
			  - 'd' (optional 'int array reference')

			  NOTE: the optional kinds *must* be specified to the
			  right of the required ones!

			  Examples:

			  "ISi"
			  means one required int, one required string
			  and one optional int.

			  "Si>"
			  means one required string and any number of
			  optional ints.

	unsigned long *tags - Pointer to a tag list. See TAGS

   SEE ALSO
	fplDelFunction()

fpl.library/fplAddVariable                      fpl.library/fplAddVariable

   NAME
	fplAddVariable -- add variable to be recognized by FPL.
	fplAddVariableTags -- add variable to be recognized by FPL.

   SYNOPSIS
	long fplAddVariable( key, name, ID, type, default, tags );
	D0                   A0   A1    D0  D1   A2       A3

	For SAS/C users:
	long fplAddVariableTags( key, name, ID, type, default, ... );

   FUNCTION
	This function adds a variable to the FPL internal list of variables
	to accept. The name pointed to by the 'name' pointer here, must
	remain unmodified while FPL runs.

	DO NOT add variables with names longer than 64 characters.
	Such a variable won't be recognized in an FPL program.

	The variable will appear as any regular 'const' variable to the FPL
	programmer. That is, it is read-only and any assign of such a
	variable results in an error.

	This variable will be remembered as a function by FPL until fplFree()
	(or fplDelFunction() naming this variable) is invoked.

   TAGS
	No tags are currently (V10) supported!

   RESULT
	Zero if success, error code if failure.

   INPUTS
	void *key	- This is the data received from the initial
			  fplInit() function call.

	char *name	- Pointer to a zero terminated string holding the
			  name of the function to add.

	long ID		- Variable ID. May be set to whatever you please to
			  speed up variable checks in the interface function.
			  All subzero values are reserved for FPL use and
			  calls. NOTE that variables and functions ought to
			  get different IDs to prevent mixups!!

	char type	- FPL_STRARG or FPL_INTARG depending on the intended
			  type of this variable. No other type is valid!

	void *default	- Default value of the variable. If this is a string
			  that's added, this should point to a zero terminated
			  string that's copied into the new variable, and if
			  this is an integer variable, it should be an
			  integer!

	unsigned long *tags - Pointer to a tag list. See TAGS

   SEE ALSO
	fplAddFunction(), fplDelFunction()

fpl.library/fplDelFunction                       fpl.library/fplDelFunction

   NAME
	fplDelFunction -- remove function definition.

   SYNOPSIS
	long fplDelFunction( key, name );
	D0                   A0   A1

   FUNCTION
	As the name hints you about, this function removes a named
	function from the FPL internal identifier cach. After this
	call the named function will no longer be recognized.

	You can do this with any of the internal FPL functions too,
	which has to be done if you want to add your own function
	using the same name as a FPL internal function (or replacing
	it with one which you think work better).

	NOTE: You don't have to fplDelFunction() every function you
	have fplAddFunction()'ed. fplFree() will take care of that
	for you.

   RESULT
	Zero if everything was ok, otherwise an error code.

   INPUTS
	void *key	- The return code of the initial fplInit().
	char *name	- Pointer to the function name (zero terminated).

   SEE ALSO
	fplAddFunction(), fplAddVariable()

fpl.library/fplFree                                     fpl.library/fplFree

   NAME
	fplFree -- clean up all resources used by FPL.

   SYNOPSIS
	void fplFree( key );
		      A0

   FUNCTION
	When you have used FPL for the last time in your program, use
	this function to make FPL free it's internal buffers and resources.
	This call will make the data received from the initial fplInit()
	useless.

	NOTE: You do not have to make a fplDelFunction() for every
	function you've added. It's enough with a call to fplFree().

	NOTE2: If you intend to use FPL again in the same session, avoid
	the overhead of doing fplFree() after every invoke of an FPL program.
	My suggestion is, in all normal cases, an fplInit() call when starting
	your program and an fplFree() call just before you exit it.

   INPUTS
	void *key	- The return code of the initial fplInit().

   SEE ALSO
	fplInit()

fpl.library/fplInit                                    fpl.library/fplInit

   NAME
	fplInit -- intializes an FPL usage session.

   SYNOPSIS
	void *fplInit( function, tags );

	void *fplInitTags( function, ... );

   FUNCTION
	This function initializes the FPL internal buffers and caches and
	allocates the new stack to use when the library is invoked.
	This function *MUST* be called the first thing you do when you want
	to use any functions in FPL. The return code of this function is
	used as parameters in several of the other FPL functions. Can be called
	several times using the same library base if wanted.

	Each call to fplInit() should have a corresponding call to fplFree().

   TAGS
	FPLTAG_ALLFUNCTIONS					(V5.3)
	  This tag enables/disables the FPL_UNKNOWN_FUNCTION ID. If that ID is
	  sent to the interface function, it means that the function just
	  interpreted was not found in the FPL internal lists. When this tag
	  is enabled, all function names will always be interpreted as best as
	  it can be done, no functions will be reported as "identified
	  unknown". Default is disabled.

	FPLTAG_HASH_TABLE_SIZE					(V5)
	  Specified the size of the hash table to use. Default is 67, and any
	  size below 10 is ignored. Set this *ONLY* at the fplInit() call!!!
	  Highest performance will be achieved if this is a prime number.

	FPLTAG_INTERVAL
	  Specifies the interval function which is called every now and then
	  to enable external processes to stop the FPL program. Returning
	  non-zero stops the program with a FPL_PROGRAM_STOPPED error code.

	FPLTAG_NEWLINE_HOOK
	  Obsolete from version 9!

	FPLTAG_USERDATA
	  Data to send to the interval function. Readable with the
	  FPLSEND_USERDATA tag to the fplSend() function.

	FPLTAG_INTERNAL_ALLOC					(V3)
	  With this tag you specify a function pointer that will be called
	  instead of the internal AllocMem()/malloc() function. This has to be
	  a "void *(*function)(long size, void *userdata)" function. Amiga
	  programmers will find the size argument in register D0 and the
	  userdata in A0.

	  When using this, all FPL allocations will be made using this
	  function, although FPL has it's own memory caching/recycling system.

	FPLTAG_INTERNAL_DEALLOC					(V3)
	  Specifies a function pointer to be called instead of the internal
	  FreeMem()/free() function. The function must be a
	  "void (*function)(void *pointer, long size, void *userdata)"
	  function. Amiga programs will receive the arguments in A1 and D0
	  (just as FreeMem() wants them...) and userdata in A0.

	FPLTAG_CACHEALLFILES					(V3)
	  Turn on or off default FPL caching. 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.

	  (The execute tag 'FPLTAG_CACHEFILE' can change this on a single
	  program basis. FPLTAG_CACHEALLFILES sets the default cache switch.)

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

	FPLTAG_REREAD_CHANGES					(V8)
	  Suppy a boolean to switch this default to on/off. When enabled all
	  files that are attempted to be ran with the actual file modified on
	  disk, will get all symbols declared in the file removed and the new
	  version loaded and run instead.

	  * Individual files can be altered with the same tag to
	    fplExecuteScript() and fplExcuteFile().
	  * 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 default to on/off. When enabled, all
	  files that aren't in use will be flushed from memory and read into
	  memory again when accessed.

	  * Individual files can be altered with the same tag to
	    fplExecuteScript() and fplExcuteFile().
	  * 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_IDENTITY						(V9)
	  During debug mode, a possible external debugger should get a real
	  name of each FPL using process that keeps them apart. All users
	  of FPL should make the supplied pointer to this tag point to a
	  unique string as an ID of this process.
	  FPL will *not* copy any data from the pointer, but simply read from
	  it from time to time. NULL is the same as not specifying anything.

	FPLTAG_DEBUG						(V9)
	  See the tag with the name name under the fplExecuteScript()
	  description!

	FPLTAG_KIDNAP_CACHED					(V9)
	  See the tag with the name name under the fplExecuteScript()
	  description!

	FPLTAG_ERROR_BUFFER					(V9)
	  The supplied char pointer should point to at least
	  FPL_ERRORMSG_LENGTH free bytes. If FPL encounters an error, this
	  buffer will be filled with a zero terminated error message string
	  just before the FPL_GENERAL_ERROR message is sent to the interface
	  function!
	  This tag should be used *prior* to the fplGetErrorMsg() function
	  which from now on is declared not-to-be-used.

	FPLTAG_PREVENT_RUNNING_SAME				(V10)
	  If this tag is set to TRUE, no programs are allowed to get executed
	  a second time (that is, if the program is already cashed).
	  The FPLTAG_REREAD_CHANGES tag still works fine with this though.


	  Amiga-only tags:

	FPLTAG_STACK
	  Startup stack size. Any size below 8000 bytes is ignored!

	FPLTAG_MAXSTACK.
	  After one execution with possible stack expandings, this specified
	  size is the maximum memory area that still will be allocated by FPL
	  to use in the next execution as stack. (This is done like this to
	  prevent FPL to have to enlarge the stack on every execution if
	  memory is available!) Default is 20000 bytes.