A file browser's state. Embed this in your application state and transform it with handleFileBrowserEvent and the functions included in this module.

Information about a file entry in the browser.

File status information.

The type of file entries in the browser.

Make a new file browser state. The provided resource name will be used to render the List viewport of the browser.

By default, the browser will show all files and directories in its working directory. To change that behavior, see setFileBrowserEntryFilter.

A file entry selector that permits selection of all file entries except directories. Use this if you want users to be able to navigate directories in the browser. If you want users to be able to select only directories, use selectDirectories.

A file entry selector that permits selection of directories only. This prevents directory navigation and only supports directory selection.

Set the working directory of the file browser. This scans the new directory and repopulates the browser while maintaining any active search string and/or entry filtering.

If the directory scan raises an IOException, the exception is stored in the browser and is accessible with fileBrowserException. If no exception is raised, the exception field is cleared. Regardless of whether an exception is raised, .. is always presented as a valid option in the browser.

Get the working directory of the file browser.

Modify the file browser's active search string. This causes the browser's displayed entries to change to those in its current directory that match the search string, if any. If a search string is provided, it is matched case-insensitively anywhere in file or directory names.

Set the filtering function used to determine which entries in the browser's current directory appear in the browser. Nothing indicates no filtering, meaning all entries will be shown. Just indicates a function that should return True for entries that should be permitted to appear.

Handle a Vty input event. Note that event handling can cause a directory change so the caller should be aware that fileBrowserException may need to be checked after handling an event in case an exception was triggered while scanning the working directory.

Events handled regardless of mode:

• Enter, Space: set the file browser's selected entry (fileBrowserSelection) for use by the calling application, subject to fileBrowserSelectable.
• Ctrl-n: select the next entry
• Ctrl-p: select the previous entry
• List navigation keys

Events handled only in normal mode:

• /: enter search mode

Events handled only in search mode:

• Esc, Ctrl-C: cancel search mode
• Text input: update search string

If the browser's current entry is selectable according to fileBrowserSelectable, add it to the selection set and return. If not, and if the entry is a directory or a symlink targeting a directory, set the browser's current path to the selected directory.

Otherwise, return the browser state unchanged.

Render a file browser. This renders a list of entries in the working directory, a cursor to select from among the entries, a header displaying the working directory, and a footer displaying information about the selected entry.

Note that if the most recent file browser operation produced an exception in fileBrowserException, that exception is not rendered by this function. That exception needs to be rendered (if at all) by the calling application.

The file browser is greedy in both dimensions.

Get the file information for the file under the cursor, if any.

Returns whether the file browser is in search mode, i.e., the mode in which user input affects the browser's active search string and displayed entries. This is used to aid in event dispatching in the calling program.

Get the entries chosen by the user, if any. Entries are chosen by an Enter or Space keypress; if you want the entry under the cursor, use fileBrowserCursor.

The exception status of the latest directory change. If Nothing, the latest directory change was successful and all entries were read. Otherwise, this contains the exception raised by the latest directory change in case the calling application needs to inspect or present the error to the user.

The function that determines what kinds of entries are selectable with in the event handler. Note that if this returns True for an entry, an Enter or Space keypress selects that entry rather than doing anything else; directory changes can only occur if this returns False for directories.

Note that this is a record field so it can be used to change the selection function.

Get the file type for this file info entry. If the file type could not be obtained due to an IOException, return Nothing.

The base attribute for all file browser attributes.

The attribute used for the current directory displayed at the top of the browser.

The attribute used for the entry information displayed at the bottom of the browser.

The attribute used for selected entries in the file browser.

The attribute used to render directory entries.

The attribute used to render block device entries.

The attribute used to render regular file entries.

The attribute used to render character device entries.

The attribute used to render named pipe entries.

The attribute used to render symbolic link entries.

The attribute used to render Unix socket entries.

A file type filter for use with setFileBrowserEntryFilter. This filter permits entries whose file types are in the specified list.

A filter that matches any directory regardless of name, or any regular file with the specified extension. For example, an extension argument of "xml" would match regular files test.xml and TEST.XML and it will match directories regardless of name.

This matcher also matches symlinks if and only if their targets are directories. This is intended to make it possible to use this matcher to find files with certain extensions, but also support directory traversal via symlinks.

Generate a textual abbreviation of a file size, e.g. "10.2M" or "12 bytes".

Build a list of file info entries for the specified directory. This function does not catch any exceptions raised by calling makeAbsolute or listDirectory, but it does catch exceptions on a per-file basis. Any exceptions caught when inspecting individual files are stored in the fileInfoFileStatus field of each FileInfo.

The entries returned are all entries in the specified directory except for . and ... Directories are always given first. Entries are sorted in case-insensitive lexicographic order.

This function is exported for those who want to implement their own file browser using the types in this module.

Build a FileInfo for the specified file and path. If an IOException is raised while attempting to get the file information, the fileInfoFileStatus field is populated with the exception. Otherwise it is populated with the FileStatus for the file.