FilterLib
Library for FILTERSEL filter programs
Written by Darren Salt
Version 1.00, 9 Sep 1995


All internal variables begin with ` unless LOCAL


PROCfilter_initialise(delete_flag%,filter_name$)
	This must be called before using any other FilterLib routine.
	It sets up:
		the file handles, in% and out%
		the file names, in$ and out$
		the argument string, arg$ (less redirection operators)
		a buffer for the argument list (filled in by PROCgetargs)
		some machine code routines
		an error handler
		the filter name, filter_name$
		delete flag, used on error
			if TRUE, then output file is deleted on error


PROCfilter_error
	Standard error handler
	Closes standard input & output files if open
	Deletes output file if present AND del% is TRUE

PROCreport(error_msg$)
PROCreportb(error_block%)
	Standard error report routines


FNaddswitch(switch_name$)
	Adds a switch to the list of allowed arguments, eg. -dummy
	Returns a number which can be passed to FNswitch

FNaddval(switch_name$,key%)
	Adds a switch to the list of allowed arguments, eg. -dummy 123
	key% is TRUE if the switch is not to be auto-assigned a value
	Returns a number which can be passed to FNswitch

FNaddstring(switch_name$)
	Adds a switch to the list of allowed args, eg. -dummy "Hello world"
	key% as above
	Returns a number which can be passed to FNswitch


PROCgetargs
	Scan supplied arguments using syntax string built with FNaddswitch,
	FNaddval and FNaddstring


FNswitch(argument_number%)
	Used for switches without parameters
	Returns TRUE/FALSE
	argument_number% is a number returned by FNaddswitch()

FNval(argument_number%)
	Used for switches with numeric (evaluated) parameters
	Returns parameter value
	argument_number% is a number returned by FNaddval()

FNstring(argument_number%)
	Used for switches with string parameters
	Returns string
	argument_number% is a number returned by FNaddstring()


FNstring0(address%)
	Returns the null-terminated string at address

FNstringLF(address%)
	Returns the LF-terminated string at address

FNstringc(address%)
	Returns the ctrl-code-terminated string at address

FNstringx(address%, terminating_code%)
	Returns the string at address - you specify the terminator
	These functions will only return up to 255 characters


FNlen0(address%)
	Length of the null-terminated string at address

FNlenLF(address%)
	Length of the LF-terminated string at address

FNlenc(address%)
	Length of the ctrl-code-terminated string at address

FNlenx(address%, terminating_code%)
	Length of the string at address - you specify the terminator


These functions will only return up to 255 characters:
PROCopenin	Opens the input file (sets in% to the file handle)
PROCopenout	Opens the output file (sets out% to the file handle)
PROCclosein	Closes the input file
PROCcloseout	Closes the output file


PROCloadin(RETURN address%, RETURN length%)
	Claim memory for, and load input file
	Ensures that buffer is followed by a line feed and a null

PROCsaveout(address%, length%)
	Save output file (will fail if the file is open)
	File type is 'text'


FNgetblock(address%, length%)
	Read length% bytes from input file (must be opened using PROCopenin)
	Returns 0 if successful, else number of bytes not read

FNputblock(address%, length%)
	Read length% bytes from input file (must be opened using PROCopenin)
	Returns 0 if successful, else number of bytes not read
	(More likely 0 or error report)


FNclaim(size%)
	Claim size% bytes from free memory
	Note this is NOT a heap (yet), so memory claims are fixed
	All claims are word-aligned
	NOTE: Negative claims are allowed...

PROCflush
	Release all workspace (except that required by BASIC)


FNlosearg(argument_string$)
	Returns argument string without first argument

FNstripspaces(string$)
	Removes excess spaces at start and end of string
