wildargs
                                 --------
           Documentation for version 1.0, on December 31th, 1991

                              by Bruno Costa



WARNING

  Although  this  program  is public domain (see DISCLAIMER below), I would
appreciate  if  you take the time to write me a line or two (E-Mail please)
if  you  are  using  any of my programs or if you have any kind of ideas or
suggestions  (This  is  not  too  much  to  ask,  is  it?).   If  you  feel
particularly  generous,  I  would  like  to  receive a disk with any useful
programs you have written, preferrably with source.  Thanks!


DESCRIPTION

  wildargs  is  a  small set of routines to easily expand wildcards for any
program  under  Kickstart  2.0.  The main routine (wildargs()) works on the
argc  and  argv  variables  received  by your program, changing them if any
wildcards  are  expanded.   There  is  an  additional  routine  that can be
optionally  called  before  wildargs()  to  set wildcard expanding options,
wildoptions().


OPTIONS

  usage:  int wildargs (int *argcptr, char ***argvptr)

  This  routine  changes  argc  and  argv  to  reflect the expansion of any
wildcards  that  may  be present.  It works like most Unix shells, i.e., it
expands  ANY  wildcards  present  in  the  line,  substituting the original
wildcard  by  the  set of filenames that match it, separated by blanks.  If
there is no match, the wildcard will be substituted by nothing.

  usage:  void wildoptions (int options)

  There are three options that can be controlled by this routine:

  WILD_FILES:     if set, names of files will be considered in the wildcard
                  expansion.
  WILD_DIRS:      if set,  names  of  directories will be considered in the
                  wildcard expansion.
  WILD_KEEPSTAR:  if set, a lonely '*' will not be changed to '#?' (so that
                  the meaning of the * as the current window is kept).

  These  options  are flags that can be OR'ed together, and they default to
WILD_FILES | WILD_DIRS.   You  must  select  at  least one of WILD_FILES or
WILD_DIRS.


EXAMPLES

  Consider the following program (test.c) in the next examples:

  /* test.c - tests wildcard expansion */

  #include <stdio.h>
  #include "wildargs.h"

  void main (int argc, char *argv[])
  {
   int i;

   wildoptions (WILDOPTIONS);

   if (!wildargs (&argc, &argv))
     printf ("error expanding args!\n");

   for (i = 0; i < argc; i++)
     printf ("%d\t%s\n", i, argv[i]);
  }

  Consider also that the current directory contains two files, "fileA" and
"fileB", and two directories, "dirA" and "dirB".

  if WILDOPTIONS is WILD_FILES:
  > test *
  0	test
  1	fileA
  2	fileB

  > test *a
  0	test
  1	fileA

  if WILDOPTIONS is WILD_DIRS:
  > test *
  0	test
  1	dirA
  2	dirB

  > test *a
  0	test
  1	dirA

  if WILDOPTIONS is WILD_DIRS | WILD_KEEPSTAR:
  > test *
  0	test

  > test *a
  0	test
  1	dirA


BUGS

  If  there  is  no  match  for a particular wildcard, it is substituted by
nothing.   Although  this is different from the behavior of Unix shells, it
just seemed the natural thing to do.

  There is a limitation of at most 256 arguments after expansion, and each
filename can be at most 100 characters in lenght, but this can be easily
changed in the source code.


AUTHOR

  The  accompanying  program  and  this documentation were written by Bruno
Costa.  He can be reached in the following ways:

  E-Mail: bruno@brlncc.bitnet (InterNet)
          bruno@BRLNCC        (BitNet)

  Mail:   Bruno Costa
          Rua Almirante Guilhem 454/102 bloco 1
          Leblon - Rio de Janeiro
          RJ 22440
          BRAZIL


DISCLAIMER

  This  software  and documentation are released into the public domain for
personal,  non-commercial  use  only.   Limited  rights to use, modify, and
redistribute  are hereby granted for non-commercial purposes, provided that
all copyright notices remain intact and all changes are clearly documented.
The  author  makes no warranty of any kind with respect to this product and
explicitly  disclaims  any implied warranties of merchantability or fitness
for any particular purpose.  (Thanks Fred! :-)