BRU parsing routines

Command Parsing

KPARSE is a set of routines that make up a command-line driver for an interactive software package. It is stored in the BRU library, and has the following features:

automatic argument typing
list & parameter parsing
identification and evaluation of integer, hex, and floating point constants
argument & qualifier command syntax (arguments are delineated by spaces, qualifiers by "/"; eg. "command/option arg1 arg2")

Kparse breaks lines into words, which can be either arguments (necessary components of the command) or qualifiers (optional modifiers to the command). Each word is numbered sequentially, starting at 1. Arguments are numbered separately, starting at 0 (the zeroth argument is the command word itself). Qualifiers are also numbered separately, starting at 1.

Lexically, arguments are denoted by spaces, while qualifiers are denoted by the / character. Text enclosed in quotation marks is not parsed, and is taken to be all one word, regardless of the presence of spaces or other special characters.

CODE

All code exists in the BRU library. The following files are used:

	argtype.F		kparse.par
	datatype.F		kparse.cmn
	eval.F			kparse_table.cmn
	getword.F
	lens.F
	kparse.F
	kparse_word.F
	parse_data.F

LINE PARSING

All parsing tasks begin with the following call:

        CHARACTER*n TEXT
        INTEGER ISTAT, N_ARG, N_QUAL, KPARSE

	ISTAT = KPARSE( TEXT, N_ARG, N_QUAL )

TEXT is the character string to be parsed, while N_ARG and N_QUAL return the number of arguments and qualifiers found. ISTAT returns as 0 if parsing completes successfully, or the character position of the first lexical error, otherwise. Following this call, arguments and qualifiers can be retrieved with the calls (all functions are CHARACTER*(*)):

	ARG = ARGUMENT( N )
	QUAL = QUALIFIER( N )
	WORD = GETWORD( N )

where N is the sequential number of the argument, qualifier, or word desired (each is numbered separately).

Example:

	TEXT = 'delete/confirm *.txt;,*.for;*'
	ARGUMENT(0)  = WORD(1) = 'delete'
	QUALIFIER(1) = WORD(2) = 'confirm'
	ARGUMENT(1)  = WORD(3) = '*.txt;,*.for;*'

WORD PARSING

Command lines often include character representations of numeric or other data which must be extracted and converted to a format that the computer understands. Kparse has various routines that provide these services.

ARGUMENT TYPES

ARGTYPE analyzes a word, and decides what type of data it probably represents. It is called as follows:

	INTEGER ITYPE, ARGTYPE
	CHARACTER*n WORD

	ITYPE = ARGTYPE( WORD )

The following datatypes are recognized:

	mnemonic	data type	example
	---------------------------------------------
	ARG_TEXT	ASCII text	'test'
	ARG_INT		integer		'123'
	ARG_HEX		hexadecimal	'0xFFFF'
	ARG_FLOAT	floating point	'5.1E-3'

ARGTYPE will select whichever of these types best matches the input string. In addition, it may choose a format, which can be a combination of the following:

	mnemonic	format			example
	----------------------------------------------------
	ARG_LIST	list of values		'1,2,9'
	ARG_RANGE	range of values		'1:100'
	ARG_EQ		parameter setting	'X=1.5'

The returned ARGTYPE is the bitwise .OR. of all the mnemonics that apply to the input string. For example:

	input		argtype
	----------------------------------------------------------------
	'copy'		ARG_TEXT
	'-1.5:0.6'	ARG_FLOAT .OR. ARG_RANGE
	'BANK=TDDT'	ARG_TEXT .OR. ARG_EQ
	'RUNS=5,6:8'	ARG_INT .OR. ARG_EQ .OR. ARG_LIST .OR. ARG_RANGE

ARGTYPE is normally used by the application to perform sanity checking on the command line arguments.

IEVAL

IEVAL converts a string containing a representation of an integer or hexadecimal value into machine format. It is called as follows:

	IVAL = IEVAL( WORD )

The FEVAL entry point of IEVAL will also convert floating point values.

	VAL = FEVAL( WORD )

KPARSE_WORD

KPARSE_WORD evaluates complex words, evaluating all data values found within them. It can handle any argument of the form:

	[keyw=]data1[:data2][,data3[:data4][,data5[:data6] ...etc]]

It is called as follows:

	INTEGER ITYPE, NDATA, DATA1(n), DATA2(n)
	CHARACTER WORD*n, KEYW*n

	CALL KPARSE_WORD( WORD, KEYW, TYPE, NDATA, DATA1, DATA2 )

It returns the following information:

	KEYW = the keyword (or the word itself if no keyword present)
	TYPE = the ARGTYPE of the word
	NDATA = the number of comma-separated data fields in the word
	DATA1(i) = the value of the Ith data field, or
		   the value of the lower bound of the Ith data field, or
		   the starting character position of the Ith data field
	DATA2(i) = the value of the Ith data field, or
		   the value of the upper bound of the Ith data field, or
		   the ending character position of the Ith data field

Examples:

if WORD = 'range=-1.0:2.5', then

	KEYW = 'range'
	TYPE = ARG_FLOAT .OR. ARG_EQ .OR. ARG_RANGE
	NDATA = 1
	DATA1(1) = -1.0
	DATA2(1) =  2.5

if WORD = '1,2,3', then

	KEYW = '1,2,3'
	TYPE = ARG_INT .OR. ARG_LIST
	NDATA = 3
	DATA1(1) = 1
	DATA1(2) = 2
	DATA1(3) = 3

if WORD = 'BANKS=TDDT,TDPT', then

	KEYW = 'BANKS'
	TYPE = ARG_TEXT .OR. ARG_EQ .OR. ARG_LIST
	NDATA = 2
	DATA1(1) = 7
	DATA2(1) = 10
	DATA1(2) = 12   }  ie. the 2nd field is 
	DATA2(2) = 15   }  WORD(12:15) = 'TDPT'

morgan@sitka.triumf.ca, 95-Mar-06