Otherware

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

/ Otherware / Otherware_1_SB_Development.iso / amiga / programm / misc / rexxtra1.lzh / RexxExtra.doc next >

Wrap

Text File | 1990-04-29 | 15.8 KB | 480 lines

RexxExtra --------- Documentation on the rexxextra.library (Version 1.2) Date: March 18, 1990 Introduction ------------ rexxextra.library is an ARexx external function library. It's purpose is to extend the string manipulation and mathematical capabilities of ARexx by defining new functions. This library is intended for users of ARexx, the Amiga implementation of the high level language by William S. Hawes, who wish to expand the set of functions available, just as the libraries supplied with ARexx (rexxsupport, rexxarplib, and rexxmathlib.library) add new functions. Archive Contents ---------------- The following files should be contained in this archive file. File Size Description ----------------- ----- ----------- rexxextra.library 7060 The ARexx library. Copy to libs: RexxExtra.doc 16226 This file. This size may vary some. Test.rexx 3946 Exercises and verifies the library functions rexx/ directory 37960 Example programs (approx.) Please distribute the library archive only in it's original form, without changes or additions. If possible, when uploading to a BBS, name the archive RXXTRA12.LZH so we may all know which version it is. Although WShell (also by Mr. Hawes), an Amiga command shell, is not needed to use RexxExtra, all example programs have only been run under WShell, so these may have to be modified to run under your own shell. Probably by adding "address command" in front of any CLI callable command strings. Installation ------------ First, copy the included rexxextra.library file to your libs: directory. The size is only about 7K. copy rexxextra.library libs: Adding the library to ARexx --------------------------- The functions are available to any ARexx program once the command: call addlib 'rexxextra.library',-20,-30,0 has been issued in any Arexx program. This only need be done once per session (I do all mine at bootup, then I don't have to worry about it). The included ARexx programs contains this step. Description of library functions -------------------------------- Basically, you've now got some new functions available you can call from any ARexx program. More are being added, so this list will grow in the future. o Replace() - replace one string with another throughout a third. o Sortwords() - sorts string of words into alphabetical order. o Cparse() - "parse" a command line. o Fparse() - "parse" a file name. You also have some example ARexx programs using and testing these functions. Following is a detailed description of each of the functions. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- Replace - replace one string with another in a string ------- Syntax ====== string4 = Replace(string1,string2,string3,['Case']) string1 is the string to replace with. string2 is the string to look for. string3 is string to perform replacment on. 'Case' is an optional argument and, if supplied, case will be ignored when searching for string2 in string3. string4 is returned value when all string2's have been replaced by string1's in string3. Description =========== This function was the first one I tried the library out with, and its such a simple and useful function, I decided to leave it in. Restrictions ============ The result string cannot be longer than 10 times string3. If anybody knows of a good way to compute the length needed for the result string before doing the replace, let me know. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- Sortwords - sort a string of words --------- Syntax ====== string2 = SortWords(string1) string1 is list of words to sort string2 is sorted string1 Description =========== This function will returns its argument, which is a string of words, into ascending alphabetical order. Currently, the space is the only delimiter for words. As with ARexx itself, string1 and the returned string are limited to about 65,500 characters. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- Cparse - parse a command line ------ Syntax ====== string = Cparse(commandline,template,stem) commandline is as recieved from the user, ie, "parse arg commandline". template is standard AmigaDOS/ARP command template (with extensions), ie, "Q=QUICK/S,BUF=BUFFER/K,FROM,TO/A". Note: Any single keyword should not be more than 30 characters. stem is the name of the stem variable to use for the compound variables to create. You might want to keep this relatively short, especially if you're getting many arguments from the command line. You do not need to include the ending period. Description =========== This function allows you to quickly and easily determine the input to your ARexx program, and "parse" the command line into a whole set of user-defined variables. This gives your ARexx programs the power of AmigaDOS/ARP command parsing with one function call. You supply to the function in a standard AmigaDOS/ARP template format (with certain extensions) what to expect on the command line. The function scans the command line, determining what flags, arguments, qualifiers and such are present, and returns a "program string" (a string suitable for INTERPRETing) containing the commands neccessary to assign values from the command line to variables in the program. Got that? Well, fortunately using Cparse is simpler than explaining it. For instance, we want to write an ARexx program that accepts the same arguments as the LIST command. Let's call it TREE. The TREE command has a template of: DIR,P=PAT/K,KEYS/S,DIRS/S,FILES/S,SORT/S,SINCE/K,UPTO/K, DATES/S,NODATES/S,SUB/K,BLOCK=BLOCKS/S,NOHEAD/S,LFORMAT/K This function will fill in args.DIR, args.P, args.KEYS, args.DIRS, etc. from the supplied command line. Arguments, qualifiers, and flags may appear on the command line in any order, just as with AmigaDOS/ARP. Command lines are verified for missing arguments, and a variable is assigned a severity level (0...2) so you can determine the the error, if any. You must format the template in this order: flags (/S), qualifiers (/K), arguments (/A & /R) and optional arguments (in the order to expect them from the user), then lists (/... & /L). For example, the TREE command would pass a template of: KEYS/S,DIRS/S,FILES/S,SORT/S,DATES/S,NODATES/S,BLOCK=BLOCKS/S, NOHEAD/S,SINCE/K,UPTO/K,P=PAT/K,SUB/K,LFORMAT/K,DIR You must also decide on a stem variable name before calling this routine. You may assign values to the compound variables for default responses (except switches); these will not be changed if that option is missing from the command line. Switches will always be in the returned string, and will always be a boolean value. Synonyms for keywords (those following an "=" in the template) are supported, but the assigned variable will always be the keyword on the LEFT of the equals sign. If, after resolving all template tokens, there is still some commandline left, a variable "stem.REMAIN" is added equaling what's left. Consequently, you may find it difficult to use "REMAIN" as a keyword in your template. A variable, "stem.ERRCODE" is added indicating if any errors were encountered while parsing the commandline. If errors are encountered, another variable "stem.ERRTEXT" is also added to explain the error. Consequently, you may find it difficult to use "ERRCODE" and "ERRTEXT" as keywords in your template. Either single or double quotes are recognized for delimiting an argument containing spaces. However, the "double quoting" convention (two quotes in a row to denote one in the string) is not accepted. In summary, token variable description ----- -------- ----------- FLAG/S stem.FLAG 1 if present, 0 if not. QUALIFIER/K stem.QUALIFIER value of following string or not changed if not present. ARGUMENT/A stem.ARGUMENT value of following string if keyword present, first string found after removing flags and qualifiers if not. ARGUMENT/R same as /A but keyword is required ARGUMENT stem.ARGUMENT value of first string found after removing flags and qualifiers LIST/... stem.LIST.0 count of items in list. 0 if none. stem.LIST.1 list items thru stem.LIST.n LIST/L same as /... but list is required. stem.REMAIN remainder of command line after all tokens have been parsed out stem.ERRCODE 0 if no errors parsing commandline 1 if remainder but no other problems 2 if required argument missing or qualifier keyword specified w/o value stem.ERRTEXT explanation of error (currently if > 1) Note: The AmigaDOS tempate structure of multiple commas (",,,,,,,") is not supported. Using Cparse ============ There are probably many ways Cparse could be used, but here's what I do. This adds complete interactive command line parsing to any ARexx program. In each ARexx program I want to add command parsing capabilities to, I start with or add this "template" and modify to suit. This template contains statements to do the preliminary work for Cparse, such as handling "?" on the command line, presenting a template to the user, showing additional help upon entry of a second "?", calling the Cparse function, and exiting if an invalid command line is found. The user may request additional help by entering a second "?" at the display of the template. The program will display help information contained in the source code of the program. Place this "self-documenting" help using a comment in the ARexx program. The beginning of the comment must be the third source line, and continues until a close comment is found. --------------------------------------------------------------- /* typical.rexx */ /* Typical ARexx program using Command Line Parsing and help system USAGE: TYPICAL [FROM] <file> [TO <dir>] [QUIET] */ dtemplate = 'FROM/A,TO/K,QUIET/S' /* template displayed to the user */ template = 'QUIET/S,FROM/A,TO/K' /* template supplied to Cparse */ args.='' /* stem variable to use */ parse arg g_c do while g_c='?' options prompt dtemplate parse pull g_c if g_c='?' then do g_s=sourceline(3) if pos('/*',g_s)=0 then break; if pos('*/',g_s)>0 then break say g_s=sourceline(4) do i=5 while pos('*/',g_s)=0; say g_s; g_s=sourceline(i); end say end end interpret Cparse(g_c,template,'args') if args.ERRCODE > 1 then do; say args.ERRTEXT; exit 5; end /* This is the body of the program, that would actually do something. From here on in the program, ARGS.FROM, ARGS.TO, and ARGS.QUIET will contain the values from the command line. */ exit 0 --------------------------------------------------------------- Or, of course, you can figure out your own way to use it. Example programs ================ I've included many example programs illustrating the above in this release. The programs are also useful in their own right. Limits ====== Variable names (keywords in the template) are limited to 30 characters. Stem variable names should be reasonably short, perhaps less than 8 characters. The returned string is limited to 1023 characters. If this isn't long enough, I can change it. =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- Fparse - parse a file name ------ Syntax ====== string = Fparse(start_dir,filespec,[defaultspec], [relatedspec],[item]) start_dir is beginning directory. If I knew more about all this stuff, this argument wouldn't be needed. We could find out the current directory and use that. I accually tried that first but it didn't seem to work (crashed). For now, just put "pragma('D')" here when calling this routine. filespec is the name of the file you want. It can include a volume name and/or directories, including leading /'s to move up from the start_dir. defaultspec and relatedspec are optional parameters containing all or parts of a filespec, and is supplied in the same form as filespec. Any parts of the file name missing from filespec will be supplied from defaultspec, then relatedspec. item is one of: 'Volume' Volume: 'Directory' dir/ 'Name' filename 'Type' .type 'File' filename.type 'c' (any character) Volume:<c>dir/<c>filename<c>.type (null or missing Volume:[dir/]filename[.type] Description =========== Given a partial filename (ie, "file.type" or "/over1/file"), this function will return a string containing the complete filename, or any or all parts of the filename. Defaults may be supplied (for any of the categories volume, directory, name, or type) in two optional arguments. Wildcard characters are left as found. No check is made for the existence of any device or directory. If you want a spec ending in a directory, be sure and include a trailing '/'. The start_dir parameter does not need one, as it is assumed to be a directory, and the others aren't. Examples ======== say fparse(pragma('D'),'name','.type') ==> Work:files/name.type say fparse(pragma('D'),'/name','.type') ==> Work:name.type =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=- Conditions for use and distribution ----------------------------------- RexxExtra is Copyright (c) 1990 by Dale W. Thompson RexxExtra is a copyrighted program that is provided "as is". There is no warranty, either expressed or implied, as to the quality or usefullness of the program. The user of the program accepts all risks associated with it's use. RexxExtra is freely distributable provided: 1. The files are included in their original form without additions, deletions, or modifications of any kind. 2. No charge is made for RexxExtra (other than a reasonable copy charge of $6.00 or less). 3. RexxExtra is not packaged as a part of a commercial product. 4. RexxExtra may not be uploaded to any electronic service that claims a copyright to it's files and programs. Requests for additional functions --------------------------------- The author is always looking for candidate functions to add to the library. If you have an idea for a function or, better yet, if you have C source code for a function you would like to see available from ARexx, send it to me and I'll try to include it in the next release. Author ------ This software was developed by Dale W. Thompson from an example library supplied on the ARexx disk (version 1.10), by William S. Hawes. All changes and additions by me. This library was compiled with A68K, a public domain assembler, and Lattice C V4.0. Any comments, questions, suggestions, flames, improvements, bug reports (what bug? that's a feature.), etc., can be directed to the following address: Dale W. Thompson 542 N. 95th Circle Mesa, AZ 85207 or you can leave me a message on one of the following boards: AmAzing Connection - Phoenix, AZ - (602) 843-6574 Database 2000 - Phoenix, AZ - (602) 242-6734