---
name: "Term::Clui::FileSelect"
section: "3pm"
platform: "linux"
package: "libterm-clui-perl"
version: "1.76-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Term::Clui::FileSelect"
---

# Term::Clui::FileSelect(3pm)

Perl module to ask the user to select a file.

## NAME

Term::Clui::FileSelect - Perl module to ask the user to select a file.

## SYNOPSIS

```
 use Term::Clui::FileSelect;
 $file = &select_file(-Readable=>1, -TopDir=>"/home", -FPat=>"*.html");
 @files = &select_file(-Chdir=>0, -Path=>$ENV{PWD}, -FPat=>"*.mp3");
 chdir &select_file(-Directory=>1, -Path=>$ENV{PWD});
```

## DESCRIPTION

This module asks the user to select a file from the filesystem. It uses the Command-line user-interface Term::Clui to dialogue with the user. It offers *Rescan* and *ShowAll* buttons. To ease the re-learning burden for the programmer, the options are modelled on those of Tk::FileDialog and of Tk::SimpleFileSelect, but various new options are introduced, namely *-TopDir*, *-TextFile*, *-Readable*, *-Writeable*, *-Executable*, *-Owned* and *-Directory*

Multiple choice is possible in a limited circumstance; when *file\_select* is invoked in a list context, with -Chdir=\>0 and without -Create.  It is currently not possible to select multiple files lying in different directories.

## SUBROUTINES

- *select\_file*( %options );

  ## OPTIONS

- *-Chdir*

  Enable the user to change directories. The default is 1. If it is set to 0, and *select\_file* is invoked in a list context, and *-Create* is not set, then the user can select multiple files.

- *-Create*

  Enable the user to specify a file that does not exist. The default is 0.

- *-ShowAll* or *-dotfiles*

  Determines whether hidden files (.\*) are displayed.  The default is 0.

- *-DisableShowAll*

  Disables the ability of the user to change the status of the ShowAll flag. The default is 0 (i.e. the user is by default allowed to change the status).

- *-SelDir*

  If True, enables selection of a directory rather than a file. The default is 0. To *enforce* selection of a directory, use the *-Directory* option.

- *-FPat* or *-filter*

  Sets the default file selection pattern, in glob format, e.g. *\*.html*. Only files matching this pattern will be displayed. If you want multiple patterns, you can use formats like *\*.\[ch\]* or *{\*.cgi,\*.pl}* - see *File::Glob* for more details. The default is "\*".

- *-File*

  The file selected, or the default file. The default default is whatever the user selected last time in this directory.

- *-Path* or *-initialdir*

  The path of the selected file, or the initial path. The default is `$ENV`{HOME}.

- *-Title*

  The Title of the dialog box. If *-Title* is specified, then Clui::FileSelect dynamically appends "in */where/ever*" to it. If *-Title* is not specified, Clui::FileSelect displays "in directory */where/ever*".

- *-TopDir*

  Restricts the user to remain within a directory or its subdirectories. The default is "/". This option, and the following, are not offered by Tk::FileDialog.

- *-TextFile*

  Only text files will be displayed. The default is 0.

- *-Readable*

  Only readable files will be displayed. The default is 0.

- *-Writeable*

  Only writeable files will be displayed. The default is 0.

- *-Executable*

  Only executable files will be displayed. The default is 0.

- *-Owned*

  Only files owned by the current user will be displayed. This is useful if the user is being asked to choose a file for a *chmod* or *chgrp* operation, for example. The default is 0.

- *-Directory*

  Only directories will be displayed. The default is 0.

## BUGS

Three problem filenames will, if present in your file-system, cause confusion. They are *Create New File*, *Show DotFiles* and *Hide DotFiles*

## AUTHOR

Original author:

Peter J Billam www.pjb.com.au/comp/contact.html

Current maintainer:

Graham Ollis

## CREDITS

Based on an old Perl4 library, *filemgr.pl*, with the options modelled after *Tk::FileDialog* and *Tk::SimpleFileSelect*.

## SEE ALSO

http://www.pjb.com.au/ , http://search.cpan.org/~pjb , File::Glob , Term::Clui , Tk::FileDialog , Tk::SimpleFileSelect , [**perl**(1)](/perl/1.md) .