Power-Programmierung

home *** CD-ROM | disk | FTP | other *** search

/ Power-Programmierung / CD1.mdf / pascal / library / dos / comline / clparse / clparser.doc next >

Wrap

Text File | 1989-12-18 | 20.4 KB | 534 lines

___________________________________________________________________________ CLPARSER.TPU (c)1989 Greg Truesdell Version 2.1 (First Release) a Turbo Pascal 5.5 Object Unit ___________________________________________________________________________ INTRODUCTION_______________________________________________________________ CLParser.TPU is a Command Line Parser. It provides the programmer with several pre-defined objects for dealing with command line options and switches. The unit also provides parsing for wildcard filenames, all environment variables and simple text parameter files. The unit provides methods which manipulate lists of items. The primary object is LIST. The following is the type definition for LIST: const { maximum number of switches or arguments } CLPARSE_MAXITEMS = 1024; List = object { data structure } item : array [1..CLPARSE_MAXITEMS] of ^String; posn : array [1..CLPARSE_MAXITEMS] of word; items, index : word; { methods } constructor Init; destructor Erase; virtual; function Add( Add_Item:string; locn:word ): boolean; virtual; function Next: String; virtual; function Prev: String; virtual; function Count: word; virtual; function Position: word; virtual; procedure Reset; virtual; end; The LIST object can be used to maintain any kind of sequential list of strings. Each item in the list is a pointer to a variable length string and a location word. The location word was primarily provided to register where, on the command line, the item was found. It may also be used to mark entries in the list for other reasons. The minimum amount of memory used in the list is 1024 words + 1024 longs (address pointers) + 2 words; or 6148 bytes. The maximum number of item entries is 1024 or as many as free memory will allow. Each entry requires only as many bytes are required by the string, plus two or three, depend- ing on where the word boundries are. Since all other objects in this unit are based on this object, and because none of these objects add any data instances of their own, the above paragraph is true for them also. The following is a list of all objects defined in CLPARSER.TPU: name(type) unique methods ----------- -------------------------------------------------------- LIST Init : Clear list to initial values (nil). (object) Erase : Erase and reclaim memory used by the list. Add : Add an item onto the list. Next : Step forward and get next item. Prev : Step backward and get previous item. Count : Return the number of items in the list. Position : Return line position of this item. Reset : Reset the item pointer to the beginning. ----------- -------------------------------------------------------- ARGUMENT Init : Fill array with valid arguments. (list) Find : Locate a specific argument. Overflow : Returns TRUE if there were more arguments than could fit in memory. ----------- -------------------------------------------------------- WILD Init : Fill the array with filenames that match the (argument) filename mask. ----------- -------------------------------------------------------- ENVIRON Init : Fill the array with all environment (argument) variables. ----------- -------------------------------------------------------- PFILE Init : Fill the array with all parameters from a (argument) text parameter file. ----------- -------------------------------------------------------- The LIST object is the primary object. The ARGUMENT object inherits all of LIST's methods except "Init", and adds two new methods; "Find" and "Overflow". The remaining objects (WILD, ENVIRON and PFILE) all inherit the methods from LIST and ARGUMENT except "Init". Once you understand how to use LIST and ARGUMENT, then you need only examine the difference in the "Init" methods for the remaining objects. HOW TO USE CLPARSER.TPU____________________________________________________ To use CLPARSER, simply include the USES CLPARSER statement in your program header. You must also ensure that CLPARSER.TPU is placed in the directory where you keep your units; usually \TP\UNITS. CLPARSER will automatically parse the commandline for you when the program executes. The following is a list of pre-defined data structures in CLPARSER: Automatically initialized when program starts: Parse_Argument : List of arguments from commandline Parse_Switch : List of switches from commandline Available but must be initialized by the programmer: Parse_Wild : un-initialized list of filenames Parse_Environ : un-initialized list of environment variables Parse_File : un-initialized list of parameter file items Data Structure Access Methods In the introduction section you will find a list of objects and unique methods associated with them. From that list you can see the data struct- ure access methods available for the ARGUMENT and SWITCH objects. Let's first examine the automatically initialized data structures. Examine this program: program CLParser_Sample; uses CLParser; var I : Integer; begin if Parse_Argument.Count > 0 then begin Write('There are ',Parse_Argument.Count ); WriteLn(' arguments on the command line.'); for I := 1 to Parse_Argument.Count do WriteLn( Parse_Argument.Next ); WriteLn('End of Arguments'); end else WriteLn('There were NO arguments on the command line.'); WriteLn; if Parse_Switch.Count > 0 then begin Write('There are ',Parse_Switch.Count ); WriteLn(' arguments on the command line.'); for I := 1 to Parse_Switch.Count do WriteLn( Parse_Switch.Next ); WriteLn('End of Switches'); end else WriteLn('There were NO switches on the command line.'); end. When this program is compiled and executed, the two data structures are automatically filled with items. The unit determines which items on the command line are switches or arguments by checking the first character of the item. o Switches are items that begin with '/', '-' or '+'. o Arguments are items that begin with any normal character. Normal characters are [#32..#127]. The unit executes: Parse_Argument.Init( NormalChars-Switches ); and Parse_Switch.Init( Switches ); when the program starts. The initialization method is passed the set of valid first characters for each data structure. In the example program above, the arguments listed would be any that do not start with a switch character but DO start with a normal character. All other items on the commandline are IGNORED! Assume you have compiled the example program as SAMPLE.EXE and typed: SAMPLE ONE TWO /A THREE -B +C FOUR The program would display: There are 4 arguments on the command line. ONE TWO THREE FOUR There are 3 switches on the command line. /A -B +C The methods used in the example are COUNT and NEXT. COUNT returns the number of items in the list. Parse_Argument.COUNT returns the number of arguments parsed from the command line. NEXT returns the next item in the list; Parse_Argument.NEXT returns the next argument from the list. Here is a complete list of available COMMON methods: destructor ERASE function ADD( add_item:string; locn: byte ): BOOLEAN function NEXT: STRING function PREV: STRING function POSITION: BYTE function COUNT: BYTE procedure RESET function FIND( target: string ): STRING function OVERFLOW: BOOLEAN examples: Current_Position := Parse_Switch.Position; Next_Argument := Parse_Argument.Next; Parse_Switch.Reset; If Parse_Argument.Add('SETUP.DAT',0) then ..... Here is a list of available UNIQUE methods: Automatic: Parse_Argument.Init( LegalChars: CharSet ) Parse_Switch.Init( LegalChars: CharSet ) Programmer: Parse_Wild.Init( FileMask: string; Attributes: word ) Parse_Environ.Init Parse_File.Init( Filename: string; Comment: CharSet ) REFERENCE__________________________________________________________________ Method: ADD( add_item: string; locn: byte ): BOOLEAN Type: Function Definition: The ADD method is used to add an item to the end of the list. If the ADD is successful, the function returns TRUE. Failure to ADD occurs if the list is full (1024 items max) or there is not enough memory on the heap for a new item. The LOCN parameter is normally used with Parse_Argument and Parse_Switch to indicate where on the command line an item was found. It can be used by the programmer to supply a unique or special code to an item. Usage: If not Parse_Wild.ADD('C:\COMMAND.COM',0) Then WriteLn('Not enough room!'); ___________________________________________________________________________ Method: COUNT: WORD Type: Function Definition: The COUNT method returns the number of items in the list. If the list is empty then COUNT returns 0. Usage: If Parse_Switch.COUNT = 0 Then WriteLn('No Switches on the command line.'); ___________________________________________________________________________ Method: ERASE Type: Destructor Definition: ERASE will reclaim memory used by the list and reset all entries to nil. Usage: Parse_Environ.ERASE; ... or ... Dispose(Parse_Environ, ERASE); ___________________________________________________________________________ Method: FIND( target: string ): STRING Type: Function Definition: FIND is used to locate a given item in the list. If a match is found then FIND will return the matching item. If the target is shorter that the item compared, FIND will match partial string. ie. to find "/P=<filename>" use: Usage: Parameter_File := Parse_Switch.FIND('/P='); If length(Parameter_File) > 0 Then Filename := copy(Parameter_File,4,255) Else Filename := ''; ___________________________________________________________________________ Method: Parse_Argument.INIT( LegalChars: CharSet ) Type: Constructor Definition: This instance of INIT is used to fill the ARGUMENT list with items from the command line. LegalChars is a set of characters to be used as indicators of legal arguments. CLPARSER defaults to [#32..#127] - ['/','-','+']. WARNING! Do not use this command in your program until you have used Parse_Argument.ERASE first! Since this command is automatically executed when your program starts, allocated memory would become trapped and unusable! Usage: Parse_Argument.ERASE; { REMEMBER TO DO THIS! } Parse_Argument.INIT( ['0'..'9'] ); { scan for numbers only } ___________________________________________________________________________ Method: Parse_Environ.INIT Type: Constructor Definition: This instance of INIT fills the ENVIRON list with all environment variables that will fit. This is not an automatic-execution object. You MUST use this first before you can access the data structure. Usage: Parse_Environ.INIT ___________________________________________________________________________ Method: Parse_File.INIT( filename: string, Comment: CharSet ) Type: Constructor Definition: This is one of the more interesting objects in this unit. If the file specified by filename is found, then it is parsed for items to be added to the list. White space before and after the item is stipped. Blank lines and comment lines are skipped. Comment lines are defined by the set of characters specified by Comment. Any line whose first non-white space (tab or space) character is in the Comment set of characters is skipped. Usage: Example Parameter File: PARM.DAT ; Sample Parameter file ************* User Data ************* John Smith {1} Level=10 {2} Password=Not Now, Dear! {3} ************* System Data *********** Size=100 {4} Time=1:00 {5} Delay=1000 {6} ; end of parameter file Program example: Parse_File.Init('PARM.DAT',[';','*']); The {} numbers represent the position numbers in the list after execution. The list will contain only 6 items. All other lines have been skipped. ___________________________________________________________________________ Method: Parse_Switch.INIT( LegalChars: CharSet ) Type: Constructor Definition: This instance of INIT is used to fill the SWITCH list with items from the command line. LegalChars is a set of characters to be used as indicators of legal switches. CLPARSER defaults to ['/','-','+']. WARNING! Do not use this command in your program until you have used Parse_Switch.ERASE first! Since this command is automatically executed when your program starts, allocated memory would become trapped and unusable! Usage: Parse_Switch.ERASE; { REMEMBER TO DO THIS! } Parse_Switch.INIT( ['%','@','/','-','+'] ); ___________________________________________________________________________ Method: Parse_Wild.INIT( filemask:string; attributes:word ); Type: Constructor Definition: This method fills the WILD list with items (filenames) that that match the filename mask. This can build a potentially gigantic list. CLPARSER is limited to 1024 items up to the maximum memory can handle. The attributes parameter is identical to the attributes provided by Turbo's DOS unit. Usage: Parse_Wild.INIT('*.DOC',ANYFILE-HIDDEN-VOLUMEID); ___________________________________________________________________________ Method: NEXT: STRING Type: Function Definition: NEXT returns the next item in the list. If the last item has already been accessed, then NEXT returns an empty string. Use RESET to set the internal index back to the beginning of the list. Use PREV to return the previous item. Usage: Next_Item := Parse_Wild.NEXT; ___________________________________________________________________________ Method: OVERFLOW: BOOLEAN Type: Function Definition: Returns TRUE if INIT found more items than would fit in memory or in the list. Usage: If Parse_Wild.OVERFLOW Then WriteLn('Sorry, not enough space for all files!'); ___________________________________________________________________________ Method: POSITION: WORD Type: Function Definition: When used with Parse_Argument or Parse_Switch POSITION returns the position on the command line where the current item was found. Otherwise POSITION returns whatever value the programmer placed there with the ADD method. Usage: Current_Switch := Parse_Switch.NEXT; If Parse_Switch.POSITION < Parse_Argument.POSITION Then WriteLn('Ambiguous use of ',Current_Switch); ___________________________________________________________________________ Method: PREV: STRING Type: Function Definition: PREV backs up one entry and returns that item in the list. If already at the beginning, then PREV returns an empty string. Usage: Previous_Item := Parse_Environ.PREV; ___________________________________________________________________________ Method: RESET Type: Procedure Definition: RESET simply resets the data structure's current entry index pointer to the beginning of the list. Usage: If Parse_Argument.NEXT := '' then Parse_Argument.RESET; ___________________________________________________________________________ REGISTRATION_______________________________________________________________ There is no charge for using this unit unless you are profitting from it's use or you want the source code. Commercial users MUST register irregardless of whether you sell software or not. This version of CLPARSER.TPU is available only for Turbo Pascal 5.5. This is the only version, currently, that supports objects. Since the unit is in object format, you can make use of the primary objects in your own programs. You are free to use this unit as-is or as a basis for your own objects under the following restrictions: o Using CLParser.TPU for any commercial purpose, you must register for a single-site license fee of $12.00. No royalties are required beyond the site-license. o To use CLParser.TPU in a Public Domain release you must register. Registration is free, but, please mention that CLPARSER was used somewhere in your documentation. o To use CLParser.TPU with your own personal programs, no registrat- ion is required. To obtain the source code you must register for a source-code license of $20.00. This license covers all above mentioned licenses and source for the TP5.5 TPU version only. When registering, please remember to include your: Name Company name Address City, State/Province Postal Code. If you are paying for registration, send MONEY ORDERS ONLY, please. Also available are non-object versions of CLParser.TPU for TP4 and TP5. To recieve a disk with all versions, on disk manual and demo programs, send $6.00 to: Greg L. Truesdell 1740 Lilac Drive Surrey, BC CANADA V4A 5C9 CIS: 75360,1303