io - Textadept API

# Textadept

- Home |
- Download |
- Lua API |
- Source |
- Language Modules |
- Stats |
- Wiki |
- Mailing List

# io

Extends Lua’s `io` library with Textadept functions for working with files.

## Working with UTF-8

If your filesystem does not use UTF-8-encoded filenames (e.g. Windows), conversions to and from that encoding are necessary since all of Textadept’s internal strings are UTF-8-encoded. When opening and saving files through dialogs, these conversions are performed automatically, but if you need to do them manually, use `string.iconv()` along with `_CHARSET`, your filesystem’s detected encoding. An example is

    events.connect(events.FILE_OPENED, function(utf8_filename)
      local filename = utf8_filename:iconv(_CHARSET, 'UTF-8')
      local f = io.open(filename, 'rb')
      -- process file
      f:close()
    end)

## Fields

### `SNAPOPEN_MAX` (number)

The maximum number of files to list in the snapopen dialog. The default value is `1000`.

### `_G.events.FILE_AFTER_SAVE` (string)

Emitted right after saving a file to disk. Emitted by `buffer:save()`. Arguments:

- `filename`: The UTF-8-encoded filename.

### `_G.events.FILE_BEFORE_SAVE` (string)

Emitted right before saving a file to disk. Emitted by `buffer:save()`. Arguments:

- `filename`: The UTF-8-encoded filename.

### `_G.events.FILE_OPENED` (string)

Emitted when opening a file in a new buffer. Emitted by `open_file()`. Arguments:

- `filename`: The UTF-8-encoded filename.

### `_G.events.FILE_SAVED_AS` (string)

Emitted after saving a file under a different filename. Emitted by `buffer:save_as()`. Arguments:

- `filename`: The UTF-8-encoded filename.

## Functions

### `close_all`()

Closes all open buffers, prompting the user to continue with unsaved buffers, and returning `true` if the user did not cancel. No buffers are saved automatically. They must be saved manually.

Return:

- `true` if user did not cancel.

See also:

- `buffer.close`

### `open_file`(utf8_filenames)

Opens utf8_filenames, a “\n” delimited string of UTF-8-encoded filenames, or user-selected files. Emits a `FILE_OPENED` event.

Parameters:

- `utf8_filenames`: Optional string list of UTF-8-encoded filenames to open. If `nil`, the user is prompted with a fileselect dialog.

See also:

- `events`

### `open_recent_file`()

Prompts the user to open a recently opened file.

See also:

- `recent_files`

### `save_all`()

Saves all unsaved buffers to their respective files.

See also:

- `buffer.save`

### `snapopen`(utf8_paths, filter, exclude_FILTER, …)

Quickly open files from utf8_paths, a “\n” delimited string of UTF-8-encoded directory paths, using a filtered list dialog. Files shown in the dialog do not match any pattern in string or table filter, and, unless exclude_FILTER is `true`, `lfs.FILTER` as well. A filter table contains Lua patterns that match filenames to exclude, with patterns matching folders to exclude listed in a `folders` sub-table. Patterns starting with ‘!’ exclude files and folders that do not match the pattern that follows. Use a table of raw file extensions assigned to an `extensions` key for fast filtering by extension. All strings must be encoded in `_G._CHARSET`, not UTF-8. The number of files in the list is capped at `SNAPOPEN_MAX`.

Parameters:

- `utf8_paths`: String list of UTF-8-encoded directory paths to search.
- `filter`: Optional filter for files and folders to exclude.
- `exclude_FILTER`: Optional flag indicating whether or not to exclude the default filter `lfs.FILTER` in the search. If `false`, adds `lfs.FILTER` to filter. The default value is `false` to include the default filter.
- `...`: Optional additional parameters to pass to `gui.dialog()`.

Usage:

- `io.snapopen(buffer.filename:match('^.+/')) -- list all files in the current file's directory, subject to the default filter`
- `io.snapopen('/project', '!%.lua$') -- list all Lua files in a project directory`
- `io.snapopen('/project', {folders = {'build'}}) -- list all source files in a project directory`

See also:

- `lfs.FILTER`
- `SNAPOPEN_MAX`

## Tables

### `boms`

List of byte-order marks (BOMs) for identifying unicode file types.

### `encodings`

List of encodings to try to decode files as. You should add to this list if you get a “Conversion failed” error when trying to open a file whose encoding is not recognized. Valid encodings are GNU iconv’s encodings and include:

- European: ASCII, ISO-8859-{1,2,3,4,5,7,9,10,13,14,15,16}, KOI8-R, KOI8-U, KOI8-RU, CP{1250,1251,1252,1253,1254,1257}, CP{850,866,1131}, Mac{Roman,CentralEurope,Iceland,Croatian,Romania}, Mac{Cyrillic,Ukraine,Greek,Turkish}, Macintosh.
- Semitic: ISO-8859-{6,8}, CP{1255,1256}, CP862, Mac{Hebrew,Arabic}.
- Japanese: EUC-JP, SHIFT_JIS, CP932, ISO-2022-JP, ISO-2022-JP-2, ISO-2022-JP-1.
- Chinese: EUC-CN, HZ, GBK, CP936, GB18030, EUC-TW, BIG5, CP950, BIG5-HKSCS, BIG5-HKSCS:2004, BIG5-HKSCS:2001, BIG5-HKSCS:1999, ISO-2022-CN, ISO-2022-CN-EXT.
- Korean: EUC-KR, CP949, ISO-2022-KR, JOHAB.
- Armenian: ARMSCII-8.
- Georgian: Georgian-Academy, Georgian-PS.
- Tajik: KOI8-T.
- Kazakh: PT154, RK1048.
- Thai: ISO-8859-11, TIS-620, CP874, MacThai.
- Laotian: MuleLao-1, CP1133.
- Vietnamese: VISCII, TCVN, CP1258.
- Unicode: UTF-8, UCS-2, UCS-2BE, UCS-2LE, UCS-4, UCS-4BE, UCS-4LE, UTF-16, UTF-16BE, UTF-16LE, UTF-32, UTF-32BE, UTF-32LE, UTF-7, C99, JAVA.

Usage:

- `io.encodings[#io.encodings + 1] = 'UTF-16'`

### `recent_files`

List of recently opened files, the most recent being towards the top.