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