# 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

<div style="clear: right;"><!-- Clear Table of Contents --></div>

    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)

[`string.iconv()`]: string.html#iconv
[`_CHARSET`]: _G.html#_CHARSET

- - -

## Fields

- - -

<a id="SNAPOPEN_MAX"></a>
### `SNAPOPEN_MAX` (number)

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

- - -

<a id="_G.events.FILE_AFTER_SAVE"></a>
### `_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.

[`buffer:save()`]: buffer.html#save

- - -

<a id="_G.events.FILE_BEFORE_SAVE"></a>
### `_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.

[`buffer:save()`]: buffer.html#save

- - -

<a id="_G.events.FILE_OPENED"></a>
### `_G.events.FILE_OPENED` (string)

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

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

- - -

<a id="_G.events.FILE_SAVED_AS"></a>
### `_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.

[`buffer:save_as()`]: buffer.html#save_as

- - -


## Functions

- - -

<a id="close_all"></a>
### `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`](buffer.html#close)

- - -

<a id="open_file"></a>
### `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`](events.html)

- - -

<a id="open_recent_file"></a>
### `open_recent_file`()

Prompts the user to open a recently opened file.

See also:

* [`recent_files`](#recent_files)

- - -

<a id="save_all"></a>
### `save_all`()

Saves all unsaved buffers to their respective files.

See also:

* [`buffer.save`](buffer.html#save)

- - -

<a id="snapopen"></a>
### `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`](lfs.html#FILTER)
* [`SNAPOPEN_MAX`](#SNAPOPEN_MAX)

- - -


## Tables

- - -

<a id="boms"></a>
### `boms`

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

- - -

<a id="encodings"></a>
### `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.

[GNU iconv's encodings]: http://www.gnu.org/software/libiconv/

Usage:

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

- - -

<a id="recent_files"></a>
### `recent_files`

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

- - -

