.\" Copyright (c) 2000, 2001, 2002, 2003, 2004, 2012 by Martin C. Shepherd
.\" 
.\" All rights reserved.
.\" 
.\" Permission is hereby granted, free of charge, to any person obtaining a
.\" copy of this software and associated documentation files (the
.\" "Software"), to deal in the Software without restriction, including
.\" without limitation the rights to use, copy, modify, merge, publish,
.\" distribute, and/or sell copies of the Software, and to permit persons
.\" to whom the Software is furnished to do so, provided that the above
.\" copyright notice(s) and this permission notice appear in all copies of
.\" the Software and that both the above copyright notice(s) and this
.\" permission notice appear in supporting documentation.
.\" 
.\" THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
.\" OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
.\" MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
.\" OF THIRD PARTY RIGHTS. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
.\" HOLDERS INCLUDED IN THIS NOTICE BE LIABLE FOR ANY CLAIM, OR ANY SPECIAL
.\" INDIRECT OR CONSEQUENTIAL DAMAGES, OR ANY DAMAGES WHATSOEVER RESULTING
.\" FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT,
.\" NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
.\" WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\" 
.\" Except as contained in this notice, the name of a copyright holder
.\" shall not be used in advertising or otherwise to promote the sale, use
.\" or other dealings in this Software without prior written authorization
.\" of the copyright holder.
.TH ef_expand_file @FUNC_MANEXT@
.SH NAME
ef_expand_file, del_ExpandFile, ef_last_error, ef_list_expansions, new_ExpandFile \- expand filenames containing ~user/$envvar and wildcard expressions
.SH SYNOPSIS
.nf
#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);
.fi

.SH DESCRIPTION

The \f3ef_expand_file()\f1 function is part of the tecla library
(see the libtecla(@LIBR_MANEXT@) man page). It expands a specified filename,
converting \f3~user/\f1 and \f3~/\f1 expressions at the start of the
filename to the corresponding home directories, replacing
\f3$envvar\f1 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.
.sp
In the presence of wildcards, the returned list of filenames only
includes the names of existing files which match the
wildcards. Otherwise, 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 \f3tcsh\f1 shell.
.sp
The supported wildcards and their meanings are:
.nf
  *        -  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'.
.fi

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.
.sp
The following is a complete example of how to use the file expansion
function.

.nf
  #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;
  }
.fi
.sp
Descriptions of the functions used above are as follows:
.sp
.nf
  ExpandFile *new_ExpandFile(void)
.fi
.sp
This function creates the resources used by the \f3ef_expand_file()\f1
function. In particular, it maintains the memory that is used to record the
array of matching filenames that is returned by \f3ef_expand_file()\f1. This
array is expanded as needed, so there is no built in limit to the number of
files that can be matched.
.sp
.nf
  ExpandFile *del_ExpandFile(ExpandFile *ef)
.fi
.sp
This function deletes the resources that were returned by a previous call to
\f3new_ExpandFile()\f1. It always returns \f3NULL\f1 (ie a deleted object). It
does nothing if the \f3ef\f1 argument is \f3NULL\f1.
.sp
A container of the following type is returned by \f3ef_expand_file()\f1.
.sp
.nf
  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;
.fi
.sp
.nf
  FileExpansion *ef_expand_file(ExpandFile *ef,
                                const char *path,
                                int pathlen)
.fi
.sp
The \f3ef_expand_file()\f1 function performs filename expansion, as documented
at the start of this section. Its first argument is a resource object returned
by \f3new_ExpandFile()\f1. A pointer to the start of the filename to be matched
is passed via the \f3path\f1 argument. This must be a normal \f3NUL\f1
terminated string, but unless a length of -1 is passed in \f3pathlen\f1, only
the first \f3pathlen\f1 characters will be used in the filename expansion.  If
the length is specified as -1, the whole of the string will be
expanded.
.sp
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 \f3nfile\f1 member will be 1, and the \f3exists\f1 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
\f3files[]\f1 array will contain the names of the \f3nfile\f1 existing
files that matched the wildcarded filename, and the \f3exists\f1
member will have the value 1. Note that the returned container belongs
to the specified \f3ef\f1 object, and its contents will change on each
call, so if you need to retain the results of more than one call to
\f3ef_expand_file()\f1, you should either make a private copy of the
returned results, or create multiple file-expansion resource objects
via multiple calls to \f3new_ExpandFile()\f1.
.sp
On error, \f3NULL\f1 is returned, and an explanation of the error can
be determined by calling \f3ef_last_error(ef)\f1.
.sp
.nf
  const char *ef_last_error(ExpandFile *ef)
.fi
.sp
This function returns the message which describes the error that
occurred on the last call to \f3ef_expand_file()\f1, for the given
\f3(ExpandFile *ef)\f1 resource object.
.sp
.nf
  int ef_list_expansions(FileExpansion *result, FILE *fp,
                         int terminal_width);
.fi
.sp
The \f3ef_list_expansions()\f1 function provides a convenient way to
list the filename expansions returned by \f3ef_expand_file()\f1. Like
the unix \f3ls\f1 command, 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 specified 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
\f3fp\f1 argument.

.SH THREAD SAFETY

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

Using the \f3libtecla_r.a\f1 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 \f3ExpandFile\f1 object. In other
words, if two threads want to do file expansion, they should each call
\f3new_ExpandFile()\f1 to allocate their own file-expansion objects.

.SH FILES
.nf
libtecla.a    -    The tecla library
libtecla.h    -    The tecla header file.
.fi

.SH SEE ALSO
.nf
libtecla(@LIBR_MANEXT@), gl_get_line(@FUNC_MANEXT@), cpl_complete_word(@FUNC_MANEXT@),
pca_lookup_file(@FUNC_MANEXT@)
.fi

.SH AUTHOR
Martin Shepherd  (mcs@astro.caltech.edu)
