README
1Lua-iconv: performs character set conversions in Lua
2(c) 2005-11 Alexandre Erwin Ittner <alexandre@ittner.com.br>
3Project page: http://ittner.github.com/lua-iconv/
4
5
6=== Introduction ===
7
8Lua-iconv is POSIX 'iconv' binding for the Lua Programming Language. The
9iconv library converts a sequence of characters from one codeset into a
10sequence of corresponding characters in another codeset. The codesets
11are those specified in the iconv.new() call that returned the conversion
12descriptor, cd.
13
14Lua-iconv 7 *requires* Lua 5.1 or Lua 5.2. For Lua 5.0, use the first
15release (lua-iconv-r1).
16
17Details on iconv may be obtained in the Open Group's interface definition
18(http://www.opengroup.org/onlinepubs/007908799/xsh/iconv.h.html).
19
20
21
22=== Download and installation ===
23
24Lua-iconv can be obtained from its GitHub project page
25(https://github.com/ittner/lua-iconv/downloads), from a LuaRocks server or
26from some Linux distributions which already provide it (eg. Debian).
27
28Unless you downloaded a compiled package, you must build the library for
29your system. If you have LuaRocks installed, all the process is automatic;
30just fire up your favourite shell and type, as root:
31
32 luarocks install lua-iconv
33
34and the package will be downloaded from a rock server, installed and
35configured. Otherwise, you must compile and install the package. In a system
36with pkg-config (as many Linux distributions and Unix flavors) open a shell,
37untar the distribution package and, within the program directory, type:
38
39 make install
40
41as root. The library will be compiled and installed on the in the correct
42path (which is defined in lua5.x.pc). Compiling on systems without pkg-config
43requires manual changes in the Makefile (this includes Windows).
44
45
46
47=== Loading and initialization ===
48
49Lua-iconv is a shared library that must be loaded in the Lua interpreter
50before use. You can simply do a
51
52 local iconv = require("iconv")
53
54call to load up the library (that, of course, must be installed in a
55directory from package.cpath).
56
57
58
59=== API documentation ===
60
61 cd = iconv.new(to, from)
62 cd = iconv.open(to, from)
63
64 Opens a new conversion descriptor, from the 'from' charset to the
65 'to' charset. Concatenating "//TRANSLIT" to the first argument will
66 enable character transliteration and concatenating "//IGNORE" to
67 the first argument will cause iconv to ignore any invalid characters
68 found in the input string.
69
70 This function returns a new converter or nil on error.
71
72
73 nstr, err = cd:iconv(str)
74
75 Converts the 'str' string to the desired charset. This method always
76 returns two arguments: the converted string and an error code, which
77 may have any of the following values:
78
79 nil
80 No error. Conversion was successful.
81
82 iconv.ERROR_NO_MEMORY
83 Failed to allocate enough memory in the conversion process.
84
85 iconv.ERROR_INVALID
86 An invalid character was found in the input sequence.
87
88 iconv.ERROR_INCOMPLETE
89 An incomplete character was found in the input sequence.
90
91 iconv.ERROR_FINALIZED
92 Trying to use an already-finalized converter. This usually means
93 that the user was tweaking the garbage collector private methods.
94
95 iconv.ERROR_UNKNOWN
96 There was an unknown error.
97
98
99=== License ===
100
101Lua-iconv is copyrighted free software: it can be used for both academic
102and commercial purposes at absolutely no cost. There are no royalties
103or GNU-like "copyleft" restrictions. The legal details are below:
104
105 Lua-iconv is (c) 2005-11 Alexandre Erwin Ittner
106
107 Permission is hereby granted, free of charge, to any person obtaining
108 a copy of this software and associated documentation files (the
109 "Software"), to deal in the Software without restriction, including
110 without limitation the rights to use, copy, modify, merge, publish,
111 distribute, sublicense, and/or sell copies of the Software, and to
112 permit persons to whom the Software is furnished to do so, subject
113 to the following conditions:
114
115 The above copyright notice and this permission notice shall be
116 included in all copies or substantial portions of the Software.
117
118 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
119 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
120 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
121 IN NO EVENT SHALL THE AUTHOR OR COPYRIGHT HOLDER BE LIABLE FOR ANY
122 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
123 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
124 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
125
126 If you use this package in a product, an acknowledgment in the product
127 documentation would be greatly appreciated (but it is not required).
128
129
130