The Recodec project is meant to disappear when it gets integrated into the Recode project. See its README file for more details.
Recodec is a clone of Recode meant for prototyping, experimenting, and preparing what Recode version 4.X will be. Recode has also been known under the names GNU Recode or Free Recode. All these programs or projects convert strings or files between various character sets and usages, transliterating between more than 240 different character sets. When exact transliteration are not possible, they get rid of offending characters or fall back on approximations.
Recodec and Recode have fairly compatible command calls. However, they use fairly different APIs internally, as Recodec extends the concept of Python codecs, and is designed to nicely mix with them.
Not everything is implemented (the @
signs in the output of recodec
--help
hints at what is currently missing from Recode). It may also
have some new features, compared to Recode. Be well aware that
Recodec is still alpha quality and should not be used without caution
in a production environment.
The Recodec program and library have been written by François Pinard, yet they reuse ideas from users, and other works in this area. This is an evolving package, specifications might change in future releases. Pretesters are welcome. Please gently report problems, suggestions or other comments to the author, either by email, or if you are comfortable with GitHub facilities, through GitHub Issues.
Install Recodec through either python setup.py install
or make install
at top-level of the unpacked distribution. To check the installation,
try recodec -lc
in a shell, this should list all usable charsets,
surfaces, and aliases. Also, make check
launches the validation
suite. The t_names
test is currently failing, and even verbosely:
this failure is innocuous and does not need to be reported.
Around permission problems, you may install in your own home directory
with python setup.py install --home=$HOME
. If you do, adjust some
environment variables before usage, with commands like these:
export PATH=$HOME/bin:$PATH
export PYTHONPATH=$HOME/lib/python:$PYTHONPATH
Maintenance of both Recode and Recodec, beyond mere installation and usage, already requires GNU Make, a C development environment, and Python. It is expected that later releases will also need Cython.
The Recode manual applies to Recodec as well, mutatis mutandis. File
NEWS
lists user visible changes, in a concise way. File ChangeLog
gives a more comprehensive description for all changes, yet this file
is not maintained anymore: Git history fills the role well enough now.
The C API, as documented in the Recode manual, is not available in Recodec. Until the Python API gets documented, the following example should help a bit. The shell command:
recodec qnx..latin-1 < INPUT > OUTPUT
could be rewritten into the following Python program:
import Recode
file('OUTPUT', 'w').write(
file('INPUT').read().encode('qnx..latin1', 'replace'))
or maybe a little more explicitly as:
from Recode import Recodec
input = file('INPUT')
output = file('OUTPUT', 'w')
codec = Recodec('qnx..latin-1')
buffer, length = codec.encode(input.read(), 'replace')
ouput.write(buffer)
The ‘replace’ argument may be omitted, this has the same effect as if the –strict (-s) option has been given on the recodec call.