ReadArgs

ReadArgs ( Source | Full Release )

ReadArgs 1.10 (C) Jon Ripley 2006,2007

Installation
============

To install the ReadArgs library copy the files ReadArgs.bbc and ReadArgs.txt 
into the BBC BASIC for Windows LIB directory, this should be "C:\Program 
Files\BBC BASIC for Windows\LIB" if you have installed BBC BASIC for Windows 
in the default installation directory.  If you wish to remove this library 
you should delete these two files.

Usage
=====

To make use of this library in your own programs you should add the following
lines to the initialisation routine:

      INSTALL @lib$+"ReadArgs.bbc"
      PROC_ReadArgs(argc,argv$())

PROC_ReadArgs returns the parameters from the command line used to start your
program.  The number of parameters is returned in argc and the parameters
themselves are returned in argv$().  There is no need to DIMension argv$()
before calling PROC_ReadArgs.

Parameter values are stored in the range argv$(1) to argv$(argc), argv$(0)
contains the command used to run the program.

Interface
=========

DEF PROC_ReadArgs(RETURN argc, RETURN argv$())
----------------------------------------------
PROC_ReadArgs returns the parameters from the command line used to start your
program.  The number of parameters is returned in argc and the parameters
themselves are returned in argv$().  There is no need to DIMension argv$()
before calling PROC_ReadArgs.

Parameter values are stored in the range argv$(1) to argv$(argc), argv$(0)
contains the command used to run the program.

DEF PROC_ReadArgsLex(RETURN ptr%, RETURN token$, RETURN ttype%)
---------------------------------------------------------------
This routine, used internally by PROC_ReadArgs, is documented here as it may
be useful to advanced programmers.  There is no need to call this routine
unless you specifically want to make use of its features.

PROC_ReadArgsLex is a simple lexical analyzer, or lexer for short, used by
PROC_ReadArgs to parse the command line parameters passed to the calling
program.

To start the lexer you should call PROC_ReadArgsLex with ptr% pointing to a
NUL terminated string stored in memory.  Each time the lexer is called the
value of ptr% is updated, this value must be passed to the lexer on the next
call.

Return values:

    ptr%   - pointer to pass PROC_ReadArgsLex on next call.
    token$ - The token read.
    ttype% - Token type.
        0 - An error occurred.
        1 - token$ contains a symbol.
        2 - token$ contains an switch.
        3 - token$ contains a string literal.
        4 - End of input.
 
An switch is defined as any symbol which begins with a dash character.

Example usage:

      DIM block% 65536
      REPEAT
        INPUT LINE "Enter text:" $$block%
        ptr% = block%
        PROC_ReadArgsLex(ptr%, token$, ttype%)
        WHILE ttype%<>4 AND ttype%<>0
          CASE ttype% OF
            WHEN 1: PRINT "SYMBOL:";token$
            WHEN 2: PRINT "OPTION:";token$
            WHEN 3: PRINT "STRLIT:";token$
          ENDCASE
          PROC_ReadArgsLex(ptr%, token$, ttype%)
        ENDWHILE
        IF ttype% = 0 THEN PRINT "ERROR:";token$
        IF ttype% = 4 THEN PRINT "END"
        PRINT
      UNTIL FALSE
       
Look-ahead, or peeking at the next token in the data, is possible using the
following code:

      tmp% = ptr%
      PROC_ReadArgsLex(tmp%, next_token$, next_ttype%)

The following routine can be added to your code if you require a dedicated
look-ahead routine.  The parameters as the same as for PROC_ReadArgsLex with
the exception that the value of ptr% will not be updated:

      DEF PROC_ReadArgsLookAhead(ptr%, RETUTN token$, RETURN ttype%)
      PROC_ReadArgsLex(ptr%, token$, ttype%)
      ENDPROC

Change Log
==========

1.00 29apr2006 Initial release
1.10 20jan2007 Improved lexer