oracular (3) Term::Clui::FileSelect.3pm.gz

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