    ef_expand_file                    ef_expand_file

## NAME

           ef_expand_file,   del_ExpandFile,   ef_last_error,  ef_list_expansions,
           new_ExpandFile - expand filenames containing ~user/$envvar and wildcard
           expressions

## SYNOPSIS

           #include <libtecla.h>

           ExpandFile *new_ExpandFile(void);

           ExpandFile *del_ExpandFile(ExpandFile *ef);

           FileExpansion *ef_expand_file(ExpandFile *ef,
                                         const char *path,
                                         int pathlen);

           int ef_list_expansions(FileExpansion *result, FILE *fp,
                                  int term_width);

           const char *ef_last_error(ExpandFile *ef);

## DESCRIPTION

           The  ef_expand_file()  function  is  part of the tecla library (see the
           libtecla man page). It  expands  a  specified  filename,
           converting  ~user/  and  ~/ expressions at the start of the filename to
           the corresponding home directories, replacing $envvar with the value of
           the  corresponding  environment  variable,  and  then, if there are any
           wildcards, matching these against existing  filenames.  Backslashes  in
           the  input filename are interpreted as escaping any special meanings of
           the characters that follow them.  Only backslahes that  are  themselves
           preceded by backslashes are preserved in the expanded filename.

           In  the  presence  of  wildcards,  the  returned list of filenames only
           includes the names of existing files which match the wildcards.  Other-
           wise,  the  original  filename is returned after expansion of tilde and
           dollar expressions, and the result  is  not  checked  against  existing
           files. This mimics the file-globbing behavior of the unix tcsh shell.

           The supported wildcards and their meanings are:
             *        -  Match any sequence of zero or more characters.
             ?        -  Match any single character.
             [chars]  -  Match any single character that appears in
                         'chars'.  If 'chars' contains an expression of
                         the form a-b, then any character between a and
                         b, including a and b, matches. The '-'
                         character looses its special meaning as a
                         range specifier when it appears at the start
                         of the sequence of characters. The ']'
                         character also looses its significance as the
                         terminator of the range expression if it
                         appears immediately after the opening '[', at
                         which point it is treated one of the
                         characters of the range. If you want both '-'
                         and ']' to be part of the range, the '-'
                         should come first and the ']' second.

             [^chars] -  The same as [chars] except that it matches any
                         single character that doesn't appear in
                         'chars'.

           Note that wildcards never match the initial dot in filenames that start
           with '.'. The initial '.' must be explicitly specified in the filename.
           This  again  mimics  the globbing behavior of most unix shells, and its
           rational is based in the fact that in unix, files with names that start
           with  '.'  are usually hidden configuration files, which are not listed
           by default by the ls command.

           The following is a complete example of how to use  the  file  expansion
           function.

             #include <stdio.h>
             #include <libtecla.h>

             int main(int argc, char *argv[])
             {
               ExpandFile *ef;      /* The expansion resource object */
               char *filename;      /* The filename being expanded */
               FileExpansion *expn; /* The results of the expansion */
               int i;

               ef = new_ExpandFile();
               if(!ef)
                 return 1;

               for(arg = *(argv++); arg; arg = *(argv++)) {
                 if((expn = ef_expand_file(ef, arg, -1)) == NULL) {
                   fprintf(stderr, "Error expanding %s (%s).\n", arg,
                                    ef_last_error(ef));
                 } else {
                   printf("%s matches the following files:\n", arg);
                   for(i=0; i<expn->nfile; i++)
                     printf(" %s\n", expn->files[i]);
                 }
               }

               ef = del_ExpandFile(ef);
               return 0;
             }

           Descriptions of the functions used above are as follows:

             ExpandFile *new_ExpandFile(void)

           This  function creates the resources used by the ef_expand_file() func-
           tion. In particular, it maintains the memory that is used to record the
           array  of matching filenames that is returned by ef_expand_file(). This
           array is expanded as needed, so there is no built in limit to the  num-
           ber of files that can be matched.

             ExpandFile *del_ExpandFile(ExpandFile *ef)

           This  function  deletes  the resources that were returned by a previous
           call to new_ExpandFile(). It always returns NULL (ie a deleted object).
           It does nothing if the ef argument is NULL.

           A container of the following type is returned by ef_expand_file().

             typedef struct {
               int exists;   /* True if the files in files[] exist */
               int nfile;    /* The number of files in files[] */
               char **files; /* An array of 'nfile' filenames. */
             } FileExpansion;

             FileExpansion *ef_expand_file(ExpandFile *ef,
                                           const char *path,
                                           int pathlen)

           The  ef_expand_file()  function  performs  filename expansion, as docu-
           mented at the start of this section. Its first argument is  a  resource
           object  returned  by  new_ExpandFile().  A  pointer to the start of the
           filename to be matched is passed via the path argument. This must be  a
           normal  NUL  terminated  string, but unless a length of -1 is passed in
           pathlen, only the first pathlen characters will be used in the filename
           expansion.   If  the length is specified as -1, the whole of the string
           will be expanded.

           The function returns a pointer to a container who's  contents  are  the
           results  of  the expansion. If there were no wildcards in the filename,
           the nfile member will be 1, and the exists member should be queried  if
           it  is  important to know if the expanded file currently exists or not.
           If there were wildcards, then the contained files[] array will  contain
           the names of the nfile existing files that matched the wildcarded file-
           name, and the exists member will  have  the  value  1.  Note  that  the
           returned container belongs to the specified ef object, and its contents
           will change on each call, so if you need to retain the results of  more
           than  one  call  to  ef_expand_file(), you should either make a private
           copy  of  the  returned  results,  or  create  multiple  file-expansion
           resource objects via multiple calls to new_ExpandFile().

           On  error,  NULL  is  returned,  and an explanation of the error can be
           determined by calling ef_last_error(ef).

             const char *ef_last_error(ExpandFile *ef)

           This function returns  the  message  which  describes  the  error  that
           occurred  on  the last call to ef_expand_file(), for the given (Expand-
           File *ef) resource object.

             int ef_list_expansions(FileExpansion *result, FILE *fp,
                                    int terminal_width);

           The ef_list_expansions() function provides a convenient way to list the
           filename expansions returned by ef_expand_file(). Like the unix ls com-
           mand, it arranges the filenames into equal width columns,  each  column
           having  the  width  of  the largest file. The number of columns used is
           thus determined by the length of the longest filename, and  the  speci-
           fied  terminal  width.  Beware  that filenames that are longer than the
           specified terminal width are printed without being truncated, so output
           longer than the specified terminal width can occur. The list is written
           to the stdio stream specified by the fp argument.

## THREAD SAFETY

           In multi-threaded programs, you should use the libtecla_r.a version  of
           the library. This uses POSIX reentrant functions where available (hence
           the _r suffix), and disables features that rely on non-reentrant system
           functions. Currently there are no features disabled in this module.

           Using  the  libtecla_r.a  version of the library, it is safe to use the
           facilities of this module  in  multiple  threads,  provided  that  each
           thread  uses  a separately allocated ExpandFile object. In other words,
           if two threads want  to  do  file  expansion,  they  should  each  call
           new_ExpandFile() to allocate their own file-expansion objects.

## FILES

           libtecla.a    -    The tecla library
           libtecla.h    -    The tecla header file.

## SEE ALSO

           libtecla, gl_get_line, cpl_complete_word,
           pca_lookup_file

## AUTHOR

           Martin Shepherd  (mcs@astro.caltech.edu)

                                                     ef_expand_file