## GtkSourceView to Tepl file loading and saving porting guide

## Introduction

The file loading and saving feature of GtkSourceView has been forked in Tepl in order to improve the implementation and to develop higher-level APIs, without being constrained by API backward-compatibility requirements.

The file loading and saving in GtkSourceView contains only the backend part, it doesn't deal with the GUI/frontend; as such the API is still a little low-level. With the Tepl framework, it is possible to implement higher-level APIs.

Another thing that we wanted to improve was the file loader, to use uchardet, to have better encoding auto-detection, but the file loader implementation in GtkSourceView was not appropriate at all to use uchardet, so a new implementation needed to be written from scratch. Developing this new implementation in GtkSourceView itself would have been more difficult, since in GtkSourceView it's better to keep the API backward-compatible, and it can take a long time before the new implementation supports all features that the old implementation supported (so to not introduce regressions in applications, the new implementation can be merged into GtkSourceView only when all previous features are implemented).

## GtkSourceFileSaver to TeplFileSaver

TeplFileSaver has almost the same API as GtkSourceFileSaver. One difference is that tepl_file_saver_new_with_target() adds the `TEPL_FILE_SAVER_FLAGS_IGNORE_MODIFICATION_TIME` flag. Without that flag, a “save as” operation (i.e. saving to a different location) is not guaranteed to work with TeplFileSaver.

## GtkSourceFileLoader to TeplFileLoader

TeplFileLoader has an API similar to GtkSourceFileLoader, but TeplFileLoader doesn't support yet all features of GtkSourceFileLoader.

## GtkSourceEncoding to TeplEncoding

TeplEncoding is quite different compared to GtkSourceEncoding. The API has been modified to accomodate the needs of the new file loader.

Differences between GtkSourceEncoding and TeplEncoding:

- The TeplEncoding “objects” returned by the `tepl_encoding_new*()` functions need to be freed, while the GtkSourceEncoding “objects” are owned by the GtkSourceView library.

- Likewise, the tepl_encoding_get_all() function has the (transfer full) annotation for the return value.

- tepl_encoding_new() copies the charset string as-is without modifying it, while gtk_source_encoding_get_from_charset() returns NULL if GtkSourceEncoding doesn't know the charset. This permits to not loose any information from what uchardet returns (uchardet might return a charset unknown by TeplEncoding).