CmdLine - Command Line Parsing
	             ==============================
		       File: CmdLine - Update: 1.10
		 Author: J.G.Harston - Date: 27-Jul-2009


  CmdLine provides a simple interface to parse a program's command line. It
can also be used to parse command-line like strings. It would normally be
called with the command line returned by OS_GetEnv in the ProgEnv library.


Requirements and Dependancies
=============================
  CmdLine has no external dependancies other than the global variable A$
holding the string to parse. The library includes the function FNs() used to
strip leading and tailing spaces from a string.


Parse Command Line
==================
DEFFNcl(match$, number%)

  The function FNcl() scans the global variable A$ for the switch or option
in match$, modifying A$ for use in a following call to FNcl(). Switches and
options can be in any order, and interspersed with superfluous spaces.
Quoted parameters are recognised and are returned with quotes stripped.

* If number%=0 then FNcl() returns TRUE if the switch is present or FALSE
  if absent.

* If number%=1 then FNcl() returns a string parameter if the option is
  present, or a null string if it is absent.

* If match$ is "", then FNcl() returns the next parameter.

* FNcl() will match the first substring in A$ that matches all the
  characters in match$, so abbreviated strings can be used. To search for
  an exact match, match$ must end with a space.

* For example, FNcl("-d",1) will match -debug, -dir, -delete. FNcl("-d ",1)
  will only match -d.

* If match$ starts with a space, then the entirety of the command line
  after the option will be returned.


Examples
========
  With the following code:

  A$=FNOS_GetEnv
  quit$=FNcl(" -quit",0)
  IF FNcl("-?",0):PRINT "Syntax: zip -v -r -d dest -t date outfile indir"
  debug%=VALFNcl("-debug ",1)
  vb%=FNcl("-v",0)
  rc%=FNcl("-r",0)  
  dest$=FNcl("-d",1)
  date$=FNcl("-t",1)  
  out$=FNcl("",0)
  in$=FNcl("",0)

* quit$ will be set to everything after any -quit option, or to "".

* if the -? switch is present, the syntax string is displayed.

* vb% and rc% will be set to TRUE or FALSE according to the presence of
  switches starting with -v and -r.

* debug% will be set to 0 if no -debug option is present, or to the
  numeric parameter if it is present.

* dest$ and date$ will be set to any parameter following an option
  starting with -d or -t, or will be set to "" if not present.

* out$ will be set to the first remaining parameter after the switches and
  options are processed

* in$ will be sent to the next remaining parameter after the switches and
  options are processed.

Example 1
---------
    zip outfile indir

sets:
  quit$=""             debug%=0      vb% =FALSE      rc%=FALSE
  dest$=""             date$ =""     out$="outfile"  in$="indir"

Example 2
---------
    zip outfile   -r  -debug   2   -quit   *Dir $.Home

sets:
  quit$="*Dir $.Home"  debug%=2      vb% =FALSE      rc%=TRUE
  dest$=""             date$ =""     out$="outfile"  in$=""

Example 3
---------
    zip -verbose "Archive file" -dest "source dir" "outfile" "in dir"

sets:
  quit$=""             debug%=0      vb% =TRUE       rc%=FALSE
  dest$="source dir"   date$ =""     out$="outfile"  in$="in dir"

Example 4
---------
    A$="HELLO       FFFF1900 FFFF8023 17A"
    NAME$=FNcl("",0)
    LOAD$=FNcl("",0)
    EXEC$=FNcl("",0)
    LENG$=FNcl("",0)

sets:
  NAME$="HELLO"    LOAD$="FFFF1900"    EXEC$="FFFF8023"    LENG$="17A"


Programming Notes
=================
  If using abbreviated match strings, each abbreviated match string must be
sufficiently unambiguous to seperate them, and less ambiguous strings must
be searched for before more ambiguous strings. For example:

  dest$=FNcl("-de",1)
  dir$ =FNcl("-di",1)

or

  debug$=FNcl("-debug",1)
  dir$  =Fncl("-d",1)

Passing a value to number% other than 0 or 1 will give undefined and
unexpected results.


Bugs
====
If a switch or option is not followed by other parameters, FNcl() mangles
the stored command line. For example, with the command line:

  setup file1 -p

leaves A$ holding incorrect data. Calling with

  setup -p file1

works.

If the command line includes a null string, FNcl() does not return the
correct (null) string, but a string starting with a quote. Code along the
following lines works around this:

  file$=FNcl("",0):IFASCfile$=34:file$=""


Version history
===============
v0.10 01-Jul-1989: Only parses switches.
v0.20 12-Mar-1993: Both switches and options supported.
v1.00 09-Aug-1998: Ignores superflous spaces, " -opt" supported.
v1.10 27-Jul-2009: Parses quoted parameters, eg -in "My Files".