Category : Pascal Source Code
Archive   : CLP30.ZIP
Filename : CLPARSER.DOC

 
Output of file : CLPARSER.DOC contained in archive : CLP30.ZIP

___________________________________________________________________________

CLPARSER.TPU (c)1989, 1990 Greg Truesdell
Version 3.0 a Turbo Pascal 5.5 Object Unit
___________________________________________________________________________


ABOUT THE AUTHOR___________________________________________________________

The author is an Information Technology Specialist at the Education
Development Centre in Burnaby, BC, Canada. The EDC is an industrial
training and development facility which provides state-of-the-art CBT and
instructor led courses to corporations and governments throught-out Canada,
The United States, Europe, Middle East and Far East. As a member of the
BC Tel Group of Companies, the EDC specializes in Telecommunications,
Mainframe Computer, Personal Computer, Management, Engineering and Sales
training as well as Educational Development Resources.

The author was trained as an Aviation Electronics Tech. in the US Navy and
joined the British Columbia Telephone Co. in 1974. He held positions in
Test Desk, Teletype/Data (computer maintenance) and Instructor of computer
technology courses.

The author is currently responsible for the design, implementation and
support of Database and Office Automation Systems and products used by the
EDC, and has co-produced their multi-user time tracking and shared project
reporting system, the automated billing system, the VAX PCSA-based Office
Automation multi-user menuing system, the information and report
distribution system and the student registration and confirmation system.

He is a member of a four person team responsible for all computer-based
information services required by more than 150 networked PC users as well
as over 100 mainframe SNA and direct access ports. Languages of choice
are Clipper, dBase, Vax C, Turbo C and MS C, Turbo C++, Turbo Pascal and
Assembler.

He lives with his wife of 18 years, Julia, and their two sons, Joe (16)
and Duncan (15). Many thanks to Julia for her MUCH patience!


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 CLPLIST. The following is the type definition for CLPLIST:

{ argument record }
itemRecord = record
item : ^String; { parsed item string }
itemlen : byte; { length + 2 of item string }
posn : Word; { position }
nextitem: Pointer; { pointer to the next node in list }
previtem: Pointer; { pointer to previous node in list }
end;

{ list is the data structure }
clpList = object
firstitem : Pointer; { pointer to first record in list }
currentitem : Pointer; { pointer to current record in list }
lastitem : Pointer; { pointer to last record in list}
items : Word; { number of items in the list }
index : Word; { current item number }

constructor Init;
destructor Erase;
function Add( add_item: string; locn: byte ): Boolean;
function Next: String;
function Prev: String;
function Count: Word;
function Position: Word;
procedure Reset;
end;

The CLPLIST 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.

Version 2.x was restricted to 1024 entries in any one of the objects. In
version 3.x, no such restriction applies. The only restriction is the
amount of available heap memory.

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
----------- --------------------------------------------------------
CLPLIST 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.
(clplist) 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 CLPLIST object is the primary object. The ARGUMENT object inherits all
of CLPLIST's methods except "Init", and adds two new methods; "Find" and
"Overflow". The remaining objects (WILD, ENVIRON and PFILE) all inherit
the methods from CLPLIST and ARGUMENT except "Init". Once you understand
how to use CLPLIST 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 only if 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=" 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('PARM.DAT',[';','*']);

The {} numbers represent the position numbers in the list
after execution. The list will contain only 6 items. All
other line 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 only to the amount of
heap memory available.


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;

___________________________________________________________________________



CHANGES IN VERSION 3.0_____________________________________________________

Version 3.0 represents a change in the data structure philosophy. When
CLPARSER was orginally designed, I used it as an included unit that was
compiled specifically for each project. The maximum number of command line
switches and arguments was known at compile time, so the unit would be
as small or large as required. No virtual methods were used, which allows
the smart linker to do it's thing, and the pointer arrays were only as
large as required.

The decision to release CLPARSER for others required some thinking. It is
my opinion now that the version released was in-ordinately wasteful of
memory resources. Each instantiation required another 1024 pointers and
1024 bytes, whether it used them or not. I knew that, for myself, this
would be un-acceptable.

So; in Version 3.0 NO memory (beyond the object itself) is used until an
item is added to the list. Also there are NO virtual methods. These were
removed to allow the smart linker to smart link and to provide EARLY
binding of objects. These are a little faster and definately safer to
use. The side effect is in inheritance. It is my opinion that CLPARSER
is not a particularly good choice as a general list object. I take my
hat off to Turbo Power's Object Professional as a source of good, general
purpose, objects. So, "no virtual methods" is prefered in this type of
object.

If you have purchased the SOURCE LICENSE, then you can virtualize until
you are blue in the face, if you wish.

Nothing else has been added. Only natures pure ingredients were used.



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 currently available for Turbo Pascal 5.5
only. A Turbo Pascal v6 and a Turbo C++ version are in the works.

Since the unit is in object format, you can make use of the primary objects
in your own programs. You are free 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.

o To sell programs with CLParser.TPU in them, you must register for
a license fee of $12.00 per copy of CLPARSER. No Royalties.

o To use CLParser.TPU in a Public Domain release you must register.
Registration is free, but handling is $5.00 if you want the
distribution disk.

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.

When registering, please remember to include your name, company name,
address, city, state/province and postal code. You must also provide
your signiture with a request for the source license.

If you are paying for registration, send MONEY ORDERS ONLY, please.


Greg L. Truesdell
1740 Lilac Drive
Surrey, BC CANADA V4A 5C9

Tel: (604) 536-5870
CompuServe: 75360,1303

___________________________________________________________________________



  3 Responses to “Category : Pascal Source Code
Archive   : CLP30.ZIP
Filename : CLPARSER.DOC

  1. Very nice! Thank you for this wonderful archive. I wonder why I found it only now. Long live the BBS file archives!

  2. This is so awesome! 😀 I’d be cool if you could download an entire archive of this at once, though.

  3. But one thing that puzzles me is the “mtswslnkmcjklsdlsbdmMICROSOFT” string. There is an article about it here. It is definitely worth a read: http://www.os2museum.com/wp/mtswslnk/