Tribblix: manual page: ef_expand

EF_EXPAND_FILE(3TECLA) Interactive Command-line Input Library Functions

NAME

ef_expand_file, del_ExpandFile, ef_last_error, ef_list_expansions,
new_ExpandFile - expand filename and wildcard expressions

SYNOPSIS

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);

DESCRIPTION

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:

*
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 loses 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 does not 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(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.

Thread Safety

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.

EXAMPLES

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).\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;
}

ATTRIBUTES