mirror of
https://github.com/lunarmodules/lua-iconv.git
synced 2025-06-22 20:24:36 +02:00
Update README
Put some small changes to style, typo fixes, and better organization.
This commit is contained in:
Alexandre Erwin Ittner
parent
f80402c452
commit
a9b6a899a4
164
README
164
README
@ -1,10 +1,9 @@
|
||||
|
||||
Lua-iconv: performs character set conversions in Lua
|
||||
(c) 2005-10 Alexandre Erwin Ittner <alexandre@ittner.com.br>
|
||||
Project page: http://lua-iconv.luaforge.net/
|
||||
Lua-iconv: performs character set conversions in Lua
|
||||
(c) 2005-10 Alexandre Erwin Ittner <alexandre@ittner.com.br>
|
||||
Project page: http://lua-iconv.luaforge.net/
|
||||
|
||||
|
||||
=== INTRODUCTION ===
|
||||
=== Introduction ===
|
||||
|
||||
Lua-iconv is POSIX 'iconv' binding for the Lua Programming Language. The
|
||||
iconv library converts a sequence of characters from one codeset into a
|
||||
@ -12,22 +11,91 @@ sequence of corresponding characters in another codeset. The codesets
|
||||
are those specified in the iconv.new() call that returned the conversion
|
||||
descriptor, cd.
|
||||
|
||||
Lua-iconv 6 *requires* Lua 5.1. If you are using Lua 5.0, please use the
|
||||
first release (lua-iconv-r1).
|
||||
Lua-iconv 6 and later *requires* Lua 5.1. If you are using Lua 5.0, please
|
||||
use the first release (lua-iconv-r1).
|
||||
|
||||
Details regarding iconv may be obtained from:
|
||||
http://www.opengroup.org/onlinepubs/007908799/xsh/iconv.h.html
|
||||
Details on iconv may be obtained in the Open Group's interface definition
|
||||
(http://www.opengroup.org/onlinepubs/007908799/xsh/iconv.h.html).
|
||||
|
||||
|
||||
|
||||
=== LICENSE ===
|
||||
=== Download and installation ===
|
||||
|
||||
Lua-iconv is (c) 2005-10 Alexandre Erwin Ittner <alexandre@ittner.com.br>
|
||||
Lua-iconv can be obtained from its LuaForge project page
|
||||
(http://luaforge.net/projects/lua-iconv/) or from some Linux distributions
|
||||
which already provide it (eg. Debian).
|
||||
|
||||
Unless you downloaded a compiled package, you must build the library for
|
||||
your system. If you are using a system with pkg-config (as many Linux
|
||||
distributions and Unix flavors) just fire up your favourite shell, untar
|
||||
the distribution package and type, as root, within the program directory:
|
||||
|
||||
make install
|
||||
|
||||
The library will be compiled and installed on the in the correct path (which
|
||||
is defined in lua5.1.pc).
|
||||
|
||||
Compiling on systems without pkg-config requires manual changes in the
|
||||
Makefile.
|
||||
|
||||
|
||||
|
||||
=== Loading and initialization ===
|
||||
|
||||
Lua-iconv is a shared library that must be loaded in the Lua interpreter
|
||||
before use. From Lua 5.1 and later, you can simply do a
|
||||
|
||||
require "iconv"
|
||||
|
||||
call to load up the library (that, of course, must be installed in a
|
||||
directory from package.cpath).
|
||||
|
||||
|
||||
|
||||
=== API documentation ===
|
||||
|
||||
cd = iconv.new(to, from)
|
||||
cd = iconv.open(to, from)
|
||||
|
||||
Opens a new conversion descriptor, from the 'from' charset to the
|
||||
'to' charset. Concatenating "//TRANSLIT" to the first argument will
|
||||
enable character transliteration and concatenating "//IGNORE" to
|
||||
the first argument will cause iconv to ignore any invalid characters
|
||||
found in the input string.
|
||||
|
||||
This function returns a new converter or nil on error.
|
||||
|
||||
|
||||
nstr, err = cd:iconv(str)
|
||||
|
||||
Converts the 'str' string to the desired charset. This method always
|
||||
returns two arguments: the converted string and an error code, which
|
||||
may have any of the following values:
|
||||
|
||||
nil
|
||||
No error. Conversion was successful.
|
||||
|
||||
iconv.ERROR_NO_MEMORY
|
||||
Failed to allocate enough memory in the conversion process.
|
||||
|
||||
iconv.ERROR_INVALID
|
||||
An invalid character was found in the input sequence.
|
||||
|
||||
iconv.ERROR_INCOMPLETE
|
||||
An incomplete character was found in the input sequence.
|
||||
|
||||
iconv.ERROR_UNKNOWN
|
||||
There was an unknown error.
|
||||
|
||||
|
||||
=== License ===
|
||||
|
||||
Lua-iconv is copyrighted free software: it can be used for both academic
|
||||
and commercial purposes at absolutely no cost. There are no royalties
|
||||
or GNU-like "copyleft" restrictions. The legal details are below:
|
||||
|
||||
Lua-iconv is (c) 2005-10 Alexandre Erwin Ittner
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining
|
||||
a copy of this software and associated documentation files (the
|
||||
"Software"), to deal in the Software without restriction, including
|
||||
@ -51,77 +119,3 @@ or GNU-like "copyleft" restrictions. The legal details are below:
|
||||
documentation would be greatly appreciated (but it is not required).
|
||||
|
||||
|
||||
|
||||
=== DOWNLOAD, COMPILATION AND INSTALLATION ===
|
||||
|
||||
Lua-iconv can be obtained from its LuaForge project page:
|
||||
http://lua-iconv.luaforge.net/
|
||||
|
||||
Lua-iconv must be compiled as a shared object and loaded by the Lua
|
||||
interpreter using the new module system in Lua 5.1.
|
||||
|
||||
If you are using a system with pkg-config (as many Linux distributions and
|
||||
Unix flavors) just fire up your favourite shell, untar the distribution
|
||||
package and type, as root, within the program directory:
|
||||
|
||||
make install
|
||||
|
||||
The library will be compiled and installed on the in the correct path (that
|
||||
is defined in lua5.1.pc.
|
||||
|
||||
Compiling on systems without pkg-config requires manual changes on the
|
||||
Makefile.
|
||||
|
||||
|
||||
|
||||
=== LOADING AND INITIALIZATION ===
|
||||
|
||||
Lua-iconv is a shared library that exports a single function called
|
||||
luaopen_iconv that must be called by the Lua interpreter. Lua 5.1
|
||||
uses the new package system, so you can simply do a
|
||||
|
||||
require "iconv"
|
||||
|
||||
call to load up the library (that, of course, must be installed in a
|
||||
directory from package.cpath).
|
||||
|
||||
|
||||
|
||||
=== USAGE ===
|
||||
|
||||
cd = iconv.new(to, from)
|
||||
cd = iconv.open(to, from)
|
||||
|
||||
Opens a new conversion descriptor, from the 'from' charset to the
|
||||
'to' charset. Concatenating "//TRANSLIT" to the first argument will
|
||||
enable character transliteration and concatenating "//IGNORE" to
|
||||
the first argument will cause iconv to ignore any invalid characters
|
||||
found in the input string.
|
||||
|
||||
This function returns a new converter or nil on error.
|
||||
|
||||
|
||||
nstr, err = cd:iconv(str)
|
||||
|
||||
Converts the 'str' string to the desired charset. This method always
|
||||
returns two arguments: the converted string and an error code, which
|
||||
may have any of the following values:
|
||||
|
||||
nil
|
||||
No error. Conversion was succeful.
|
||||
|
||||
iconv.ERROR_NO_MEMORY
|
||||
Failed to allocate enough memory in the conversion process.
|
||||
|
||||
iconv.ERROR_INVALID
|
||||
An invalid character was found in the input sequence.
|
||||
|
||||
iconv.ERROR_INCOMPLETE
|
||||
An incomplete character was found in the input sequence.
|
||||
|
||||
iconv.ERROR_UNKNOWN
|
||||
There was an unknown error.
|
||||
|
||||
|
||||
=== EOF ===
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user