te
Copyright (c) 2000, 2001, 2002, 2003, 2004 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.
Portions Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
ef_expand_file, del_ExpandFile, ef_last_error, ef_list_expansions, new_ExpandFile - expand filename and wildcard expressions

cc [ flag.\|.\|. ] file.\|.\|. -ltecla [ library.\|.\|. ]
#include <libtecla.h>

ExpandFile *ef_expand_file(void);

ExpandFile *del_ExpandFile(ExpandFile *ef);

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

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

const char *new_ExpandFile(ExpandFile *ef);

The ef_expand_file() function is part of the libtecla(3LIB) library. 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 backslashes that are themselves preceded by backslashes are preserved in the expanded filename.

In the presence of wildcards, the returned list of filenames includes only 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 tcsh shell.

The supported wildcards and their meanings are: *

? [chars] [^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(1) command.

The new_ExpandFile() function creates the resources used by the ef_expand_file() function. In particular, it maintains the memory that is used to record the array of matching file names that is returned by ef_expand_file(). This array is expanded as needed, so there is no builtin limit to the number of files that can be matched.

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

The ef_expand_file() function performs filename expansion. Its first argument is a resource object returned by new_ExpandFile(). A pointer to the start of the filename to be matched is passed by the path argument. This must be a normal null-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. 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;

The ef_expand_file() function returns a pointer to a container whose 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. If there were wild cards, then the contained files[] array will contain the names of the nfile existing files that matched the wild-carded filename, 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 with 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).

The ef_last_error() function returns the message which describes the error that occurred on the last call to ef_expand_file(), for the given (ExpandFile *ef) resource object.

The ef_list_expansions() function provides a convenient way to list the filename expansions returned by ef_expand_file(). Like the ls utility, 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 fp argument.

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.

Example 1 Use of file expansion function.

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).\en", arg,
 ef_last_error(ef));
 } else {
 printf("%s matches the following files:\en", arg);
 for(i=0; i<expn->nfile; i++)
 printf(" %s\en", expn->files[i]);
 }
 }

 ef = del_ExpandFile(ef);
 return 0;
}

See attributes(5) for descriptions of the following attributes:

ATTRIBUTE TYPE ATTRIBUTE VALUE

Interface Stability Evolving

MT-Level MT-Safe

cpl_complete_word(3TECLA), gl_get_line(3TECLA), libtecla(3LIB), pca_lookup_file(3TECLA), attributes(5)