rejeep/f.el — pull request #4 by lunaryorn (2013-08-10 18:21:27+00:00)
Title: Read/write files with proper coding conversion

This PR aims at clarifying (that is, fixing :) ) coding system conversion in `f-read` and `f-write`.

Currently these functions actually ignore coding system conversion. `f-write` just uses whatever Emacs just uses as default, and has no way of writing literal bytes. It will silently fail if the text to be written cannot be encoded in the current write coding system. `f-read` never decodes and has no way of decoding, but returns multibyte strings anyway. Hence, if the file contents encoded text, it'll silently great a wrong string, namely a multibyte string, but with separate character for each byte.

This PR introduces a `coding` argument to `f-read` and `f-write`.

Without this argument, `f-read` always returns an unencoded unibyte strings with the raw bytes of the file. If applied to `string-to-vector`, a vector with all integral byte values is the result. With `coding` argument, `f-read` decodes the content of the file in the given encoding.

`f-write` expects a unibyte string, and writes its raw bytes to the target file if not given an `coding`. With `coding`, it expects a multibyte string, and encodes this multibyte string with the given encoding before writing it to the file. Hence, the file will contain an encoded string. With `append`, the existing content of the file is *not* touched, i.e. it's not decoded, and the same bytes that were read are written back out. That means, if the file contains UTF-8 data, and is append with `coding` `iso-8859-1`, the old data is still UTF-8, only the new data is ISO-8859-1. I am not sure whether this semantics for `append` is any useful, but I can't think of a better one.

Note that this behavior is **backwards incompatible**, especially for `f-write`. Formerly, `f-write` would silently use the system encoding, now it will fail on multibyte strings without explicit `coding` argument. That will **break** existing applications, that just pass standard Emacs strings to `f-write`. Yet, I think this change must be done know, as long as there is still a change to get coding conversion right in these functions.