Module textadept.io
Provides file input/output routines for Textadept.
Overview
Textadept represents all characters and strings internally as UTF-8. You will
not notice any difference for working with files containing ASCII text since
UTF-8 is compatible with it. Problems may arise for files with more exotic
encodings that may not be detected properly, if at all. When opening a file,
the list of encodings tried before throwing a conversion failed
error is in
core/file_io.lua
's try_encodings
. Textadept respects the
detected encoding when saving the file.
New files are saved as UTF-8 by default.
Converting Filenames to and from UTF-8
If your filesystem does not use UTF-8 encoded filenames, conversions to and
from that encoding will be necessary. When opening and saving files through
dialogs, Textadept takes care of these conversions for you, but if you need
to do them manually, use textadept.iconv()
along with
_CHARSET
, your filesystem's detected encoding.
Example:
textadept.events.add_handler('file_opened',
function(utf8_filename)
local filename = textadept.iconv(utf8_filename, _CHARSET, 'UTF-8')
local f = io.open(filename, 'rb')
-- process file
f:close()
end)
Events
The following is a list of all File I/O events generated in
event_name(arguments)
format:
- file_opened (filename)
Called when a file has been opened in a new buffer.- filename: the filename encoded in UTF-8.
- file_before_save (filename)
Called right before a file is saved to disk.- filename: the filename encoded in UTF-8.
- file_saved_as (filename)
Called when a file is saved under another filename.- filename: the other filename encoded in UTF-8.
Overview
Textadept represents all characters and strings internally as UTF-8. You will
not notice any difference for working with files containing ASCII text since
UTF-8 is compatible with it. Problems may arise for files with more exotic
encodings that may not be detected properly, if at all. When opening a file,
the list of encodings tried before throwing a conversion failed
error is in
core/file_io.lua
's try_encodings
. Textadept respects the
detected encoding when saving the file.
New files are saved as UTF-8 by default.
Converting Filenames to and from UTF-8
If your filesystem does not use UTF-8 encoded filenames, conversions to and
from that encoding will be necessary. When opening and saving files through
dialogs, Textadept takes care of these conversions for you, but if you need
to do them manually, use textadept.iconv()
along with
_CHARSET
, your filesystem's detected encoding.
Example:
textadept.events.add_handler('file_opened',
function(utf8_filename)
local filename = textadept.iconv(utf8_filename, _CHARSET, 'UTF-8')
local f = io.open(filename, 'rb')
-- process file
f:close()
end)
Events
The following is a list of all File I/O events generated in
event_name(arguments)
format:
- file_opened (filename)
Called when a file has been opened in a new buffer.- filename: the filename encoded in UTF-8.
- file_before_save (filename)
Called right before a file is saved to disk.- filename: the filename encoded in UTF-8.
- file_saved_as (filename)
Called when a file is saved under another filename.- filename: the other filename encoded in UTF-8.
Overview
Textadept represents all characters and strings internally as UTF-8. You will
not notice any difference for working with files containing ASCII text since
UTF-8 is compatible with it. Problems may arise for files with more exotic
encodings that may not be detected properly, if at all. When opening a file,
the list of encodings tried before throwing a conversion failed
error is in
core/file_io.lua
's try_encodings
. Textadept respects the
detected encoding when saving the file.
New files are saved as UTF-8 by default.
Converting Filenames to and from UTF-8
If your filesystem does not use UTF-8 encoded filenames, conversions to and
from that encoding will be necessary. When opening and saving files through
dialogs, Textadept takes care of these conversions for you, but if you need
to do them manually, use textadept.iconv()
along with
_CHARSET
, your filesystem's detected encoding.
Example:
textadept.events.add_handler('file_opened',
function(utf8_filename)
local filename = textadept.iconv(utf8_filename, _CHARSET, 'UTF-8')
local f = io.open(filename, 'rb')
-- process file
f:close()
end)
Events
The following is a list of all File I/O events generated in
event_name(arguments)
format:
- file_opened (filename)
Called when a file has been opened in a new buffer.- filename: the filename encoded in UTF-8.
- file_before_save (filename)
Called right before a file is saved to disk.- filename: the filename encoded in UTF-8.
- file_saved_as (filename)
Called when a file is saved under another filename.- filename: the other filename encoded in UTF-8.
Functions
close (buffer) | Closes the current buffer. |
close_all () | Closes all open buffers. |
open (utf8_filenames) | Opens a list of files. |
read_api_file (filename, word_chars) | Reads an API file. |
reload (buffer) | Reloads the file in a given buffer. |
save (buffer) | Saves the current buffer to a file. |
save_all () | Saves all dirty buffers to their respective files. |
save_as (buffer, utf8_filename) | Saves the current buffer to a file different than its filename property. |
set_encoding (buffer, encoding) | Sets the encoding for the buffer, converting its contents in the process. |
Tables
boms | List of byte-order marks (BOMs). |
recent_files | List of recently opened files. |
try_encodings | List of encodings to try to decode files as after UTF-8. |
Functions
- close (buffer)
-
Closes the current buffer. If the buffer is dirty, the user is prompted to continue. The buffer is not saved automatically. It must be done manually.
Parameters
- buffer: The buffer to close. This must be the currently focused buffer.
Usage:
buffer:close() - close_all ()
-
Closes all open buffers. If any buffer is dirty, the user is prompted to continue. No buffers are saved automatically. They must be saved manually.
Usage:
textadept.io.close_all()Return value:
true if user did not cancel. - open (utf8_filenames)
-
Opens a list of files.
Parameters
- utf8_filenames: A '\n' separated list of filenames to open. If none specified, the user is prompted to open files from a dialog. These paths must be encoded in UTF-8.
Usage:
textadept.io.open(utf8_encoded_filename) - read_api_file (filename, word_chars)
-
Reads an API file. Each non-empty line in the API file is structured as follows: identifier (parameters) description Whitespace is optional, but can used for formatting. In description, '\\n' will be interpreted as a newline (\n) character. 'Overloaded' identifiers are handled appropriately.
Parameters
- filename: The absolute path to the API file to read.
- word_chars: Characters considered to be word characters for determining the identifier to lookup. Its contents should be in Lua pattern format suitable for the character class construct.
Usage:
textadept.io.read_api_file(filename, '%w_')Return value:
API table. - reload (buffer)
-
Reloads the file in a given buffer.
Parameters
- buffer: The buffer to reload. This must be the currently focused buffer.
Usage:
buffer:reload() - save (buffer)
-
Saves the current buffer to a file.
Parameters
- buffer: The buffer to save. Its 'filename' property is used as the path of the file to save to. This must be the currently focused buffer.
Usage:
buffer:save() - save_all ()
-
Saves all dirty buffers to their respective files.
Usage:
textadept.io.save_all() - save_as (buffer, utf8_filename)
-
Saves the current buffer to a file different than its filename property.
Parameters
- buffer: The buffer to save. This must be the currently focused buffer.
- utf8_filename: The new filepath to save the buffer to. Must be UTF-8 encoded.
Usage:
buffer:save_as(filename) - set_encoding (buffer, encoding)
-
Sets the encoding for the buffer, converting its contents in the process.
Parameters
- buffer: The buffer to set the encoding for. It must be the currently focused buffer.
- encoding: The encoding to set. Valid encodings are ones that GTK's g_convert() function accepts (typically GNU iconv's encodings).
Usage:
buffer:set_encoding('ASCII')